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

基于 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 ClientInstructions定义 Agent 的角色和行为准则Tools赋予 Agent 调用外部工具的能力Client连接 LLMOpenAI/Azure/本地模型本项目正是基于这一架构构建了一个代码注释专家 Agent。3.2 工作流程输入代码文件路径调用 read_code_file 工具调用 analyze_code_structure 工具Agent 分析代码结构生成专业注释输出带注释代码工作步骤详解文件读取读取代码内容统计行数、注释比例等基础信息结构分析识别函数、类、接口等代码元素及其位置注释生成LLM 根据代码语义生成符合语言规范的注释输出保存带注释的代码保存到commented_code/目录四、代码实现详解4.1 工具函数设计Agent 需要两个核心工具来完成任务(1) 代码文件读取工具defread_code_file(file_path:Annotated[str,Field(description代码文件的完整路径)],)-str:读取指定路径的代码文件内容。 Args: file_path: 代码文件路径 Returns: 文件内容字符串包含基本信息统计 # 文件存在性检查ifnotos.path.exists(file_path):returnf文件不存在:{file_path}# 支持的文件类型验证supported_exts[.py,.js,.ts,.tsx,.jsx,.java,.kt,.go,.rs,.cpp,.c,.h,.cs,.swift,.php,.rb,.sh,.sql,]# 读取内容并统计withopen(file_path,r,encodingutf-8)asf:contentf.read()# 计算注释比例linescontent.split(\n)comment_linessum(1forlineinlinesifany(line.strip().startswith(m)formin[#,//,/*,///]))returnf注释比例:{comment_lines/len(lines)*100:.1f}%\ncontent设计要点使用AnnotatedField提供参数描述让 LLM 正确调用返回内容包含统计信息帮助 Agent 理解代码现状支持 15 种编程语言(2) 代码结构分析工具defanalyze_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)\sstruct,},}# 遍历代码行匹配结构模式forlineincode_content.split(\n):forcategory,patterninpatterns[language].items():ifre.search(pattern,line):# 记录发现的代码结构...设计要点为不同语言定义专属的正则模式返回结构化报告包含行号便于精确定位4.2 Agent 构建核心classCodeCommentAgentSystem:def__init__(self):self._setup_chat_client()def_setup_chat_client(self):配置 OpenAI 兼容的 Chat Clientfromagent_framework.openaiimportOpenAIChatCompletionClient# 支持官方 API 和本地模型ifos.getenv(OPENAI_BASE_URL):# 本地模型 / Azure / 兼容端点self.chat_clientOpenAIChatCompletionClient(modelos.getenv(OPENAI_CHAT_MODEL),base_urlos.getenv(OPENAI_BASE_URL),api_keyos.getenv(OPENAI_API_KEY),)else:# OpenAI 官方self.chat_clientOpenAIChatCompletionClient(modelgpt-4o-mini,api_keyos.getenv(OPENAI_API_KEY),)asyncdefadd_comments(self,file_path:str)-str:为代码添加注释fromagent_frameworkimportAgent# 创建代码注释专家 Agentcomment_agentAgent(nameComment_Specialist,clientself.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_promptf请为{file_path}添加专业注释。 步骤 1. 调用 read_code_file 读取文件 2. 调用 analyze_code_structure 分析结构 3. 输出带注释的完整代码resultawaitself._run_agent(comment_agent,task_prompt)returnresult架构亮点Instructions 设计明确定义注释原则和风格确保输出质量Tools 注册Agent 可自主决定何时调用工具流式输出实时显示生成过程提升用户体验4.3 交互式运行模式asyncdefinteractive_mode(self):交互式 CLI 模式whileTrue:print(\n请选择操作)print( 1. 为单个文件添加注释)print( 2. 批量处理目录)print( 3. 查看注释统计)print( 4. 退出)choiceinput(请输入选项: ).strip()ifchoice1:file_pathinput(文件路径: )resultawaitself.add_comments(file_path)self._save_commented_code(result,file_path)elifchoice2:# 批量处理目录下所有代码文件awaitself._batch_process(input(目录路径: ))五、使用指南5.1 安装与配置# 克隆项目gitclone https://github.com/loveStudyWjj/code_comment_agent.gitcdcode_comment_agent# 创建虚拟环境python-mvenv venvsourcevenv/bin/activate# Linux/Mac# 或 venv\Scripts\activate # Windows# 安装依赖pipinstall-rrequirements.txt依赖列表requirements.txtagent-framework0.0.6 python-dotenv pydantic openai5.2 环境配置复制.env.example为.envcp.env.example .env配置选项# 方式一OpenAI 官方 API OPENAI_API_KEYsk-your-api-key-here OPENAI_CHAT_MODELgpt-4o-mini # 方式二本地模型Ollama/vLLM OPENAI_BASE_URLhttp://localhost:11434/v1 OPENAI_CHAT_MODELllama3 # 方式三Azure OpenAI OPENAI_BASE_URLhttps://your-resource.openai.azure.com OPENAI_API_KEYyour-azure-key OPENAI_CHAT_MODELgpt-45.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六、注释输出示例原始代码无注释defcalculate_discount(price,customer_type,years):ifcustomer_typevip:base_discount0.2else:base_discount0.1loyalty_bonusmin(years*0.01,0.15)final_priceprice*(1-base_discount-loyalty_bonus)returnfinal_priceAgent 生成的带注释代码 价格折扣计算模块 提供基于客户类型和忠诚度的智能折扣计算功能。 defcalculate_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 客户享受更高基础折扣ifcustomer_typevip:base_discount0.2else:base_discount0.1# 忠诚度奖励每年增加 1%上限 15%loyalty_bonusmin(years*0.01,0.15)# 计算最终价格final_priceprice*(1-base_discount-loyalty_bonus)returnfinal_price七、技术亮点总结特性实现方式Agent 自主决策LLM 自动决定何时调用工具无需硬编码流程多语言适配正则模式库 语言映射表注释风格规范Instructions 中定义各语言的注释惯例流式输出async for update in agent.run(streamTrue)本地模型支持OpenAI 兼容接口可接入 Ollama/vLLM批量处理目录遍历 智能跳过 node_modules 等目录八、扩展方向注释质量评分添加注释质量评估功能量化改进效果Git Hook 集成pre-commit 时自动检查注释覆盖率IDE 插件VS Code/JetBrains 插件实时注释建议团队模板支持自定义注释模板统一团队风格增量处理只处理新增/修改的函数节省 API 成本九、结语Code Comment Agent 展示了 Agent Framework 在代码辅助领域的应用潜力工具调用让 Agent 具备了读代码的能力精心设计的 Instructions确保注释质量和风格统一流式交互提供了直观的用户体验这不仅是一个工具更是 AI 辅助编程的一次实践探索。期待 Agent Framework 在更多场景中释放价值参考资料Microsoft Agent Framework 文档OpenAI API 文档Ollama 本地模型