CodeReviewAgent 智能代码审查报告全解析从 AST 静态分析到 LLM 优化建议的完整落地【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents本文以 CodeReviewAgent 实际产出的代码审查报告outputs/review_report.md为骨架逐节还原一份高质量审查报告的结构与内容并结合项目源码main.ipynb剖析 AST 静态分析、PEP 8 风格检查与 LLM 深度建议三者如何协作。读完本文你将掌握 CodeReviewAgent 的完整工作链路理解审查报告每一小节背后的实现原理并能够复现一次从提交代码到生成报告的智能审查流程。一、报告从何而来审查对象与生成链路这份审查报告的审查对象是项目内置的示例代码 data/sample_code.py——一个演示用的简单用户管理系统包含一个UserManager类、两个辅助函数全部代码仅 44 行class UserManager: 用户管理类 def __init__(self): self.users [] def add_user(self, name, age, email): 添加用户 user {name: name, age: age, email: email} self.users.append(user) return True def get_user(self, name): 获取用户信息 for user in self.users: if user[name] name: return user return None def delete_user(self, name): 删除用户 for i, user in enumerate(self.users): if user[name] name: del self.users[i] return True return False def calculate_average_age(users): 计算平均年龄 total 0 for user in users: total user[age] return total / len(users) def send_email(email, message): 发送邮件模拟 print(f发送邮件到 {email}: {message}) return True报告并非人工撰写而是由 main.ipynb 中定义的SimpleAgent名为代码审查助手自动生成。其完整生成链路如下第 1 部分 环境配置导入hello_agents框架的SimpleAgent、HelloAgentsLLM、Tool、ToolParameter、ToolRegistry并设置 LLM 环境变量第 2 部分 定义工具实现CodeAnalysisToolAST 结构分析与StyleCheckToolPEP 8 风格检查两个工具类第 3 部分 创建智能体将两个工具注册进ToolRegistry以代码审查专家系统提示词初始化SimpleAgent第 4 部分 读取代码从data/sample_code.py读取待审查源码第 5 部分 执行审查调用agent.run(...)让 LLM 结合工具返回的静态分析结果组织审查报告第 6 部分 保存报告将 LLM 输出的 Markdown 文本写入 outputs/review_report.md。也就是说这份报告是工具先做静态事实核查、LLM 再做语义化解读与建议的产物。下面逐节解析报告正文。二、代码结构分析AST 解析如何还原代码骨架报告的第一部分代码结构分析对应 review_report.md给出了审查对象的静态结构清单类定义UserManager类负责用户管理包含三个方法add_user、get_user和delete_user初始化方法__init__创建了一个空的用户列表self.users。方法分析add_user(name, age, email)将用户信息添加到用户列表中返回True表示操作成功get_user(name)根据用户名查找并返回用户信息找不到时返回Nonedelete_user(name)根据用户名从用户列表中删除用户删除成功返回True否则返回False。辅助函数calculate_average_age(users)计算给定用户列表的平均年龄send_email(email, message)模拟发送邮件实际只是打印一条消息。这些信息并非 LLM凭空读出的而是由 main.ipynb 第 2 部分定义的CodeAnalysisTool提供的。该工具基于 Python 标准库ast模块实现先用ast.parse(code)将源码解析为抽象语法树再通过ast.walk(tree)遍历整棵树筛出ast.FunctionDef函数定义与ast.ClassDef类定义节点统计函数数量、类数量、代码行数并输出函数列表与类列表tree ast.parse(code) # 统计信息 functions [node for node in ast.walk(tree) if isinstance(node, ast.FunctionDef)] classes [node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)] result { 函数数量: len(functions), 类数量: len(classes), 代码行数: len(code.split(\n)), 函数列表: [f.name for f in functions], 类列表: [c.name for c in classes] } return str(result)正因为有 AST 这一事实层兜底LLM 报告中的结构描述才能做到与真实代码一一对应而不是靠模型记忆猜测。这也体现了 Agent 工具设计的核心思路把可确定性计算的静态分析交给代码把语义理解和建议生成交给 LLM。三、风格问题检查PEP 8 规则的自动化落地报告的第二部分风格问题review_report.md指出行长度第 1 行超过 79 个字符建议将长行拆分成多行或减少注释的长度。这条结论来自StyleCheckTool的检查结果。该工具逐行扫描代码实现了两条最常用的 PEP 8 规则行宽不超过 79 字符if len(line) 79时记录第 N 行超过79个字符缩进规范化检查行首空格数若不在[0, 4, 8, 12]这一组合法缩进档位中则记录第 N 行缩进不规范。当全部行都通过检查时工具返回代码风格良好符合PEP 8规范否则拼接所有违规项返回。与CodeAnalysisTool一样该工具通过ToolParameter声明了唯一的入参codestring 类型、必填供 LLM 在推理时按工具规范调用def get_parameters(self) - List[ToolParameter]: return [ ToolParameter( namecode, typestring, description要检查的Python代码, requiredTrue ) ]从源码结构看PEP 8 检查目前只实现了行宽与缩进两条核心规则属于够用但可扩展的最小实现——新增规则只需在run方法中追加判断分支即可这也是 README 中可扩展易于添加新的检查规则和工具一说的由来。四、潜在 Bug 识别与性能优化建议潜在 Bug删除用户时的索引问题报告第三部分潜在Bugreview_report.md指出了delete_user方法中的隐患在delete_user方法中删除用户后列表的索引会发生变化。虽然当前实现可以正常工作但为了避免潜在的索引问题建议使用列表推导或其他更安全的方法来删除元素。回顾 sample_code.py 的实现它在for i, user in enumerate(self.users)循环中直接执行del self.users[i]。由于delete_user在命中目标后立即return True当前逻辑不会触发边遍历边删除导致的跳项但这依赖只删一个且立即返回的巧合。一旦后续演进为删除所有匹配项或删除后继续遍历del引发的索引漂移就会造成元素被跳过甚至越界。该结论属于典型的 LLM 语义审查——静态工具统计不出这类逻辑隐患需要模型理解控制流后才能给出。性能优化建议一用字典替换列表存储报告指出get_user方法在最坏情况下需要遍历整个用户列表若用户数量较多建议改用字典存储用户信息以将查找从 O(n) 降为 O(1)def __init__(self): self.users {} # 以 name 为键的字典 def get_user(self, name): return self.users.get(name) # 哈希查找性能优化建议二平均年龄的重复计算calculate_average_age每次调用都要遍历整个用户列表报告建议在列表非常大时缓存计算结果或改用更合适的数据结构。这实际上呼应了读多写少场景下以空间换时间的经典权衡。五、最佳实践建议与改进后代码报告第五部分最佳实践建议review_report.md从工程化角度给出了四条建议异常处理在add_user和delete_user方法中增加异常处理机制以应对可能的输入错误或意外情况日志记录用logging库替代print函数便于统一管理和调试单元测试为每个方法编写单元测试确保代码的稳定性与可靠性文档字符串已有 docstring 但可进一步细化特别是复杂逻辑与边界情况。随后报告给出了完整的改进版代码review_report.md将上述所有建议一次性落地——这也是整份报告最具实操价值的部分完整继承如下 示例代码一个简单的用户管理系统 用于演示代码审查功能 import logging # 配置日志记录 logging.basicConfig(levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s) class UserManager: 用户管理类 def __init__(self): self.users {} def add_user(self, name, age, email): 添加用户 if name in self.users: logging.warning(f用户 {name} 已经存在) return False self.users[name] {name: name, age: age, email: email} return True def get_user(self, name): 获取用户信息 return self.users.get(name) def delete_user(self, name): 删除用户 if name in self.users: del self.users[name] return True return False def calculate_average_age(users): 计算平均年龄 if not users: return 0 total sum(user[age] for user in users.values()) return total / len(users) def send_email(email, message): 发送邮件模拟 logging.info(f发送邮件到 {email}: {message}) return True # 示例用法 if __name__ __main__: user_manager UserManager() user_manager.add_user(Alice, 30, aliceexample.com) user_manager.add_user(Bob, 25, bobexample.com) print(user_manager.get_user(Alice)) user_manager.delete_user(Alice) print(user_manager.get_user(Alice)) average_age calculate_average_age(user_manager.users) print(f平均年龄: {average_age}) send_email(adminexample.com, 用户管理系统的平均年龄已更新)对照原代码可以清晰看到改进点存储结构从列表升级为以name为键的字典消除get_user的线性扫描、规避delete_user的索引漂移add_user增加重复用户检测并返回Falsecalculate_average_age增加空列表保护返回 0所有print替换为logging补充__main__演示入口。这份改进代码本身即可作为审查输出直接可落地的证据——LLM 不只是指出问题还交付了可运行的新版本。六、Agent 是如何会审查的SimpleAgent 与系统提示词设计要让 LLM 输出像上面这样结构稳定的报告关键在 main.ipynb 第 3 部分的系统提示词设计。项目为代码审查助手定义了如下system_promptsystem_prompt 你是一位经验丰富的代码审查专家。你的任务是 1. 使用code_analysis工具分析代码结构 2. 使用style_check工具检查代码风格 3. 基于分析结果提供详细的审查报告 审查报告应包括 - 代码结构分析 - 风格问题 - 潜在bug - 性能优化建议 - 最佳实践建议 请以Markdown格式输出报告。这段提示词完成三件事角色设定经验丰富的代码审查专家、工作流约束先调工具再写报告、输出格式约束固定五节结构 Markdown。这正是最终报告各章节标题与提示词一一对应的原因。智能体组装则体现了 HelloAgents 框架SimpleAgent的最小用法先创建两个工具实例并注册进ToolRegistry再以HelloAgentsLLM()为推理后端、以系统提示词和工具注册表构建SimpleAgenttool_registry ToolRegistry() tool_registry.register_tool(CodeAnalysisTool()) tool_registry.register_tool(StyleCheckTool()) llm HelloAgentsLLM() agent SimpleAgent( name代码审查助手, llmllm, system_promptsystem_prompt, tool_registrytool_registry )审查执行时只需把源码作为用户消息交给智能体review_result agent.run(f请审查以下Python代码\n\npython\n{sample_code}\n)SimpleAgent在运行中负责LLM 决策 → 调用工具 → 结果回填 → 继续生成的循环工具输出结构统计、风格违规列表作为上下文喂回模型最终生成完整报告并保存到 outputs/review_report.md。七、如何复现一次智能代码审查1. 安装依赖项目依赖见 requirements.txt核心包括 HelloAgents 框架hello-agents[all]0.1.0、Jupyter 环境jupyter1.0.0、notebook7.0.0、环境变量管理python-dotenv1.0.0与代码注释解析工具ast-comments1.0.0pip install -r requirements.txt2. 配置 LLM 参数项目使用 OpenAI 兼容接口调用大模型通过四个环境变量控制环境变量作用项目默认值示例LLM_MODEL_ID指定模型Qwen/Qwen2.5-72B-InstructLLM_API_KEYAPI 密钥需自行填写LLM_BASE_URLAPI 服务地址https://api-inference.modelscope.cn/v1/LLM_TIMEOUT请求超时秒60既可在 Notebook 第 1 部分的配置单元格中直接设置也可在外部通过.env文件注入README 提供了cp .env.example .env的说明具体以你克隆到的仓库实际文件为准。3. 运行审查流程jupyter lab # 打开 main.ipynb依次运行第 0~6 部分第 0 部分快速演示用精简版QuickAnalysisTool跑一遍分析→建议流程用于快速了解项目能力第 1~6 部分完整版流程最终在outputs/review_report.md生成审查报告若要审查自己的代码将待审查源码放入data/sample_code.py后重新运行即可。八、报告的价值边界与扩展方向这份报告说明了什么一份高质量审查报告的价值在于事实 判断双层结构code_analysis与style_check提供可验证的静态事实LLM 基于事实完成语义层的问题定位如delete_user的索引隐患、性能权衡分析列表 vs 字典与工程化建议日志、测试、docstring并直接交付改进后的可运行代码。这种确定性工具 生成式模型的分工正是 Agent 应用于代码审查这类任务的范式。需要说明的局限StyleCheckTool目前仅实现行宽与缩进两条规则CodeAnalysisTool只统计结构与行数无法覆盖复杂重构检测、跨文件依赖分析等高级场景报告中的语义结论Bug、性能建议由 LLM 推断生成其准确性依赖模型能力与提示词设计对于关键生产代码建议人工复核后再采纳。从源码可见的扩展方向项目 README 与 Notebook 第 7 部分总结与展望明确了后续路线支持更多编程语言、添加安全漏洞检测、集成更多静态分析工具、支持批量文件审查、生成 HTML 格式报告。从实现角度看这些方向都只需新增Tool子类并注册进ToolRegistry或在系统提示词中补充输出要求——整体架构具备清晰的扩展位。综上outputs/review_report.md 不仅是一份结果文档更完整地示范了静态分析工具 LLM 语义审查 结构化报告输出的 Agent 落地模式可直接作为自行搭建代码审查智能体的参考蓝本。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考