基于 Microsoft Agent Framework 的智能代码注释工具：让 AI 为你的代码"说话"

项目地址：code_comment_agent
技术栈：Python + Microsoft Agent Framework RC6 + Azure OpenAI
适用场景：代码文档补全、 legacy 代码维护、团队代码规范统一

一、背景与痛点

作为开发者，我们经常遇到这样的困境：

  • Legacy 代码"裸奔"：接手老项目时，发现关键函数没有任何注释，理解业务逻辑像"破译密码"
  • 注释质量参差：团队成员注释风格不一，有的过于简略，有的冗长无效
  • 时间成本高：手动为每个函数添加规范注释，耗时且易遗漏

有没有一种方式，能让 AI 自动理解代码意图，并生成专业、规范的注释？

答案是：Code Comment Agent —— 一个基于 Microsoft Agent Framework RC6 构建的智能代码注释工具。

二、核心功能一览

功能 说明
📝 自动添加注释 为缺少注释的代码自动生成清晰的说明
🔍 结构分析 智能识别函数、类、模块等代码结构
🌐 多语言支持 Python、JS/TS、Java、Go、Rust、C/C++ 等 15+ 语言
📊 注释统计 分析代码注释比例，量化可读性状况
💾 批量处理 支持目录级批量处理，一键搞定整个项目
🔧 灵活配置 支持 OpenAI API 和本地模型（Ollama/vLLM）

三、技术架构解析

3.1 Agent Framework 核心概念

Microsoft Agent Framework RC6 提供了一套简洁的 Agent 构建范式：

Agent = Instructions + Tools + Client
  • Instructions：定义 Agent 的角色和行为准则
  • Tools：赋予 Agent 调用外部工具的能力
  • Client：连接 LLM（OpenAI/Azure/本地模型）

本项目正是基于这一架构，构建了一个"代码注释专家" Agent。

3.2 工作流程

输入代码文件路径

调用 read_code_file 工具

调用 analyze_code_structure 工具

Agent 分析代码结构

生成专业注释

输出带注释代码

工作步骤详解：

  1. 文件读取：读取代码内容，统计行数、注释比例等基础信息
  2. 结构分析：识别函数、类、接口等代码元素及其位置
  3. 注释生成：LLM 根据代码语义生成符合语言规范的注释
  4. 输出保存：带注释的代码保存到 commented_code/ 目录

四、代码实现详解

4.1 工具函数设计

Agent 需要两个核心工具来完成任务：

(1) 代码文件读取工具
def read_code_file(
    file_path: Annotated[str, Field(description="代码文件的完整路径")],
) -> str:
    """读取指定路径的代码文件内容。

    Args:
        file_path: 代码文件路径

    Returns:
        文件内容字符串，包含基本信息统计
    """
    # 文件存在性检查
    if not os.path.exists(file_path):
        return f"文件不存在: {file_path}"

    # 支持的文件类型验证
    supported_exts = [
        ".py", ".js", ".ts", ".tsx", ".jsx",
        ".java", ".kt", ".go", ".rs", ".cpp", ".c", ".h",
        ".cs", ".swift", ".php", ".rb", ".sh", ".sql",
    ]

    # 读取内容并统计
    with open(file_path, "r", encoding="utf-8") as f:
        content = f.read()

    # 计算注释比例
    lines = content.split("\n")
    comment_lines = sum(1 for line in lines 
                       if any(line.strip().startswith(m) 
                              for m in ["#", "//", "/*", "///"]))
    
    return f"注释比例: {comment_lines / len(lines) * 100:.1f}%\n" + content

设计要点：

  • 使用 Annotated + Field 提供参数描述，让 LLM 正确调用
  • 返回内容包含统计信息，帮助 Agent 理解代码现状
  • 支持 15+ 种编程语言
(2) 代码结构分析工具
def analyze_code_structure(
    code_content: Annotated[str, Field(description="代码内容字符串")],
    language: Annotated[str, Field(description="编程语言类型")] = "python",
) -> str:
    """分析代码结构，识别函数、类、模块等。"""
    
    # 不同语言的识别模式
    patterns = {
        "python": {
            "function": r"^\s*def\s+(\w+)\s*\(",
            "class": r"^\s*class\s+(\w+)",
            "import": r"^\s*(import|from)\s+",
        },
        "javascript": {
            "function": r"^\s*(function\s+\w+|const\s+\w+\s*=)",
            "class": r"^\s*class\s+(\w+)",
        },
        "go": {
            "function": r"^\s*func\s+(\w+)",
            "struct": r"^\s*type\s+(\w+)\s+struct",
        },
    }

    # 遍历代码行，匹配结构模式
    for line in code_content.split("\n"):
        for category, pattern in patterns[language].items():
            if re.search(pattern, line):
                # 记录发现的代码结构
                ...

设计要点：

  • 为不同语言定义专属的正则模式
  • 返回结构化报告，包含行号便于精确定位

4.2 Agent 构建核心

class CodeCommentAgentSystem:
    def __init__(self):
        self._setup_chat_client()

    def _setup_chat_client(self):
        """配置 OpenAI 兼容的 Chat Client"""
        from agent_framework.openai import OpenAIChatCompletionClient

        # 支持官方 API 和本地模型
        if os.getenv("OPENAI_BASE_URL"):
            # 本地模型 / Azure / 兼容端点
            self.chat_client = OpenAIChatCompletionClient(
                model=os.getenv("OPENAI_CHAT_MODEL"),
                base_url=os.getenv("OPENAI_BASE_URL"),
                api_key=os.getenv("OPENAI_API_KEY"),
            )
        else:
            # OpenAI 官方
            self.chat_client = OpenAIChatCompletionClient(
                model="gpt-4o-mini",
                api_key=os.getenv("OPENAI_API_KEY"),
            )

    async def add_comments(self, file_path: str) -> str:
        """为代码添加注释"""
        from agent_framework import Agent

        # 创建代码注释专家 Agent
        comment_agent = Agent(
            name="Comment_Specialist",
            client=self.chat_client,
            instructions="""你是一个专业的代码注释专家。

注释原则：
1. 文件级注释：描述模块用途、主要功能和依赖
2. 函数注释：说明用途、参数、返回值、异常
3. 类注释：说明类的用途、属性和关键方法
4. 复杂逻辑注释：解释算法和业务逻辑意图
5. 避免过度注释：简单代码保持自解释

注释风格：
- Python: Docstring (""" """)
- JavaScript: JSDoc (/** */)
- Go: godoc (//)
- C/C++: Doxygen
""",
            tools=[read_code_file, analyze_code_structure],
        )

        # 构建任务并执行
        task_prompt = f"""请为 {file_path} 添加专业注释。
步骤：
1. 调用 read_code_file 读取文件
2. 调用 analyze_code_structure 分析结构
3. 输出带注释的完整代码"""

        result = await self._run_agent(comment_agent, task_prompt)
        return result

架构亮点：

  1. Instructions 设计：明确定义注释原则和风格，确保输出质量
  2. Tools 注册：Agent 可自主决定何时调用工具
  3. 流式输出：实时显示生成过程，提升用户体验

4.3 交互式运行模式

async def interactive_mode(self):
    """交互式 CLI 模式"""
    while True:
        print("\n请选择操作：")
        print("  1. 为单个文件添加注释")
        print("  2. 批量处理目录")
        print("  3. 查看注释统计")
        print("  4. 退出")

        choice = input("请输入选项: ").strip()

        if choice == "1":
            file_path = input("文件路径: ")
            result = await self.add_comments(file_path)
            self._save_commented_code(result, file_path)

        elif choice == "2":
            # 批量处理目录下所有代码文件
            await self._batch_process(input("目录路径: "))

五、使用指南

5.1 安装与配置

# 克隆项目
git clone https://github.com/loveStudyWjj/code_comment_agent.git
cd code_comment_agent

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

依赖列表（requirements.txt）：

agent-framework>=0.0.6
python-dotenv
pydantic
openai

5.2 环境配置

复制 .env.example 为 .env：

cp .env.example .env

配置选项：

# 方式一：OpenAI 官方 API
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_CHAT_MODEL=gpt-4o-mini

# 方式二：本地模型（Ollama/vLLM）
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_CHAT_MODEL=llama3

# 方式三：Azure OpenAI
OPENAI_BASE_URL=https://your-resource.openai.azure.com
OPENAI_API_KEY=your-azure-key
OPENAI_CHAT_MODEL=gpt-4

5.3 运行示例

python code_comment_agent.py

交互示例：

============================================================
代码注释补全系统 (Microsoft Agent Framework RC6)
============================================================

请选择操作：
  1. 为单个文件添加注释
  2. 批量处理目录下的代码文件
  3. 查看文件注释比例统计
  4. 退出

请输入选项 (1/2/3/4): 1
请输入代码文件路径: ./src/utils.py

正在分析代码并添加注释...
============================================================
[Agent 输出带注释的代码]
============================================================

带注释的代码已保存至: commented_code/utils_commented_20260403_120000.py

六、注释输出示例

原始代码（无注释）：

def calculate_discount(price, customer_type, years):
    if customer_type == "vip":
        base_discount = 0.2
    else:
        base_discount = 0.1
    
    loyalty_bonus = min(years * 0.01, 0.15)
    final_price = price * (1 - base_discount - loyalty_bonus)
    return final_price

Agent 生成的带注释代码：

"""
价格折扣计算模块

提供基于客户类型和忠诚度的智能折扣计算功能。
"""

def calculate_discount(
    price: float,
    customer_type: str,
    years: int
) -> float:
    """计算客户的最终折扣价格。

    根据客户类型和购买年限，综合计算折扣比例。

    Args:
        price: 商品原始价格
        customer_type: 客户类型（"vip" 或普通客户）
        years: 客户购买年限，用于计算忠诚度奖励

    Returns:
        应用折扣后的最终价格

    Example:
        >>> calculate_discount(1000, "vip", 5)
        650.0  # VIP 20% + 5年忠诚度 5% = 25% 折扣
    """
    # VIP 客户享受更高基础折扣
    if customer_type == "vip":
        base_discount = 0.2
    else:
        base_discount = 0.1
    
    # 忠诚度奖励：每年增加 1%，上限 15%
    loyalty_bonus = min(years * 0.01, 0.15)
    
    # 计算最终价格
    final_price = price * (1 - base_discount - loyalty_bonus)
    return final_price

七、技术亮点总结

特性 实现方式
Agent 自主决策 LLM 自动决定何时调用工具，无需硬编码流程
多语言适配 正则模式库 + 语言映射表
注释风格规范 Instructions 中定义各语言的注释惯例
流式输出 async for update in agent.run(stream=True)
本地模型支持 OpenAI 兼容接口，可接入 Ollama/vLLM
批量处理 目录遍历 + 智能跳过 node_modules 等目录

八、扩展方向

  1. 注释质量评分：添加注释质量评估功能，量化改进效果
  2. Git Hook 集成：pre-commit 时自动检查注释覆盖率
  3. IDE 插件：VS Code/JetBrains 插件，实时注释建议
  4. 团队模板：支持自定义注释模板，统一团队风格
  5. 增量处理：只处理新增/修改的函数，节省 API 成本

九、结语

Code Comment Agent 展示了 Agent Framework 在代码辅助领域的应用潜力：

  • 工具调用让 Agent 具备了"读代码"的能力
  • 精心设计的 Instructions 确保注释质量和风格统一
  • 流式交互提供了直观的用户体验

这不仅是一个工具，更是 AI 辅助编程的一次实践探索。期待 Agent Framework 在更多场景中释放价值！

参考资料：

# microsoft # 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

我们不画饼：一份写给开源共建者的真实承诺（QiLink v2.0 公告全文）

avatar AtomGit开源社区
cover

应用数学论文降AI工具免费推荐：2026年应用数学毕业论文降AI4.8元亲测99.26%知网达标完整指南

avatar AtomGit开源社区
cover

学校AIGC检测标准差异解读：不同高校AI率标准对比2026年如何针对性免费处理完整指南

avatar AtomGit开源社区