第8章 实战项目代码仓库健康度分析Agent本章你将学到综合运用第二部全部所学从零搭建一个完整的工具增强型Agent系统在实际项目中设计评测规范、构建测试集、开发Agent、运行评测、迭代优化让Agent在项目中识别能力缺口并自建工具将完整项目包装为可写入简历的作品本章你将产出一个能自动扫描Python项目、分析代码质量、生成诊断报告的Agent系统以及一套完整的工程资产规范、测试集、评测报告、迭代记录全部章节收录在专栏《AI应用工程化实战教程》之【智能体工具使用实战】8.1 项目背景与需求定义8.1.1 场景设定学期末你的室友正在赶软件工程课设。他的项目是一个Python Web应用包含十几个.py文件。截止日期前三天他想做一次代码质量检查——有没有明显的逻辑错误哪些函数写得太长有没有写了但从未被调用的函数手动检查十几个文件、几千行代码光是读完就要半天。他来找你帮忙。你说“我正好有一个能自动分析代码仓库的Agent。”这就是本章的实战项目代码仓库健康度分析Agent。8.1.2 系统功能描述Agent接收一个项目文件夹路径自动完成以下分析分析维度具体内容需要的工具代码规模统计文件数量、总行数、有效代码行数去除空行和注释read_fileexecute_python函数复杂度每个函数的行数、嵌套深度、参数数量read_fileexecute_python代码风格检查是否有过长函数超过50行、是否有过多嵌套超过4层execute_python调用pylint或自定义检查逻辑重复代码检测是否存在相似度高的代码片段execute_python可能需要自建工具依赖分析哪些模块被导入哪些常用但没有被使用execute_python生成诊断报告Markdown格式的健康度报告包含问题清单和改进建议write_file最终输出一份project_health_report.md包含总体评分、各维度得分、问题清单、改进建议。8.2 系统架构设计8.2.1 工具集规划基于功能需求Agent需要以下工具预置工具继承前七章read_file(path)读取单个文件内容execute_python(code, timeout)在沙盒中执行Python代码write_file(path, content)写入文件可能需要自建的工具Agent在任务中发现缺口后创建scan_directory(path)扫描目录返回所有Python文件列表analyze_function_complexity(file_path)分析单个文件的函数复杂度check_code_style(file_path)对单个文件进行代码风格检查注意scan_directory是Agent可能首先需要的——它需要知道项目里有哪些Python文件。但我们的预置工具中没有这个功能。这就是一个天然的“能力缺口”为Agent自建工具创造了场景。8.2.2 工作流程设计用户分析 /path/to/project │ ▼ Agent 发现我需要知道这个目录下有哪些Python文件但我没有 scan_directory 工具 │ ▼ Agent 自建工具scan_directory通过 execute_python 扫描目录write_file 保存代码register_tool 注册 │ ▼ Agent 调用 scan_directory → 拿到文件列表 │ ▼ Agent 逐个调用 read_file → 拿到所有文件内容 │ ▼ Agent 调用 execute_python批量分析所有文件的规模、复杂度、风格 │ ▼ Agent 调用 write_file → 生成 project_health_report.md8.3 Step1规范定义在动手开发之前先定义评测规范。这是Harness五步法的第一步也是确保系统质量的基础。8.3.1 设计评测规范创建specs/code_health_spec.md。在Trae对话面板中输入在项目>8.4 Step2数据构建8.4.1 准备测试用的示例项目我们需要2-3个不同质量的Python项目作为测试数据。每个项目模拟真实的学生课设代码——有些写得好有些有问题。在Trae对话面板中输入在项目>8.4.2 构建黄金标准测试集在Trae对话面板中输入请读取 test_projects/ 下的三个项目为每个项目构建黄金标准评测数据保存为 data/code_health_test_cases.json。 ## 每个测试用例包含 - test_idCH001, CH002, CH003 - project_path项目路径 - project_description项目描述 - expected_tool_calls预期工具调用序列至少应包含扫描目录/获取文件列表、读取文件、执行代码分析、写入报告 - expected_issues预期应被识别的问题列表至少列出已知问题 - expected_report_constraints - should_contain报告必须包含的内容如总体评分、问题清单 - should_not_contain报告不应包含的内容如对不存在的问题的误报 - score_range预期总体评分的合理范围如 problematic_project 应在60-75分 ## 特别注意 - problematic_project 的预期问题列表中应包含 1. parse_data 函数过长超过80行 2. parse_data 嵌套深度过大5层 3. deprecated_helper 函数未被调用 4. handlers.py 与 utils.py 存在重复代码生成后人工审查data/code_health_test_cases.json确认预期问题列表准确无误。8.5 Step3Agent开发8.5.1 修改系统提示词本章的Agent基于前七章构建的agent.py但需要针对代码分析任务调整系统提示词。在Trae对话面板中输入请修改 agent.py 的系统提示词在原有数据分析助手的基础上增加代码仓库分析能力。 ## 新增角色能力 你同时是一个代码质量分析专家。当用户让你分析一个代码项目时你应该 1. 先确认项目的Python文件列表。如果现有工具无法直接扫描目录使用 execute_python 写一段 os.listdir 或 pathlib.Path.glob 来获取文件列表。如果发现这个功能会被反复使用考虑创建 scan_directory 工具。 2. 逐个读取每个.py文件的内容。 3. 在 execute_python 中执行代码分析检查 - 每个函数的行数超过50行标记为过长函数 - 嵌套深度超过4层标记为嵌套过深 - 参数数量超过5个标记为参数过多 - import 语句中哪些模块导入但未使用 4. 生成健康度报告时使用以下评分标准 - 总体评分0-100基于问题数量和严重程度 - 代码规模分合理行数范围 - 函数质量分过长函数占比 - 代码风格分嵌套深度、命名规范 - 可维护性分重复代码、未使用代码 5. 报告以Markdown格式保存。结构 - # 项目健康度报告 - ## 总体评分 - ## 各维度得分 - ## 问题清单按严重程度排序 - ## 改进建议8.5.2 确认基础工具集当前agent.py的工具集应该包含read_file预置execute_python预置沙盒保护write_file预置register_tool预置元工具确认ToolManager中这些工具都已注册。8.5.3 更新沙盒白名单代码分析需要一些额外的Python标准库。在Trae对话面板中输入请修改 sandbox.py 的模块白名单在原有基础上增加以下模块 - ast抽象语法树用于代码分析 - pathlib路径操作 - collections.Counter统计用 更新后白名单完整列表为pandas, numpy, math, statistics, json, csv, collections, itertools, datetime, re, string, decimal, fractions, ast, pathlib8.6 Step4自动化评测8.6.1 生成评测脚本本章的评测脚本可以复用第6章的evaluator.py和run_evaluation.py框架但需要针对代码分析任务调整评测Agent的Prompt。在Trae对话面板中输入请修改 evaluator.py 中的评测Agent系统提示词使其适用于代码仓库健康度分析场景。 ## 评测维度调整 ### 维度1报告质量40% - 报告结构是否完整标题、总分、分维度分、问题清单、改进建议 - 评分是否在合理范围内与GT的 score_range 对比 ### 维度2问题识别质量40% - 召回率GT中 expected_issues 列出的问题报告中识别出了多少 - 精确率报告中列出的问题有多少是真实存在的GT确认的 - 不允许将不存在的文件、不存在的函数列为问题 ### 维度3工具使用审计20% - 是否扫描了所有.py文件 - 是否对每个文件进行了分析 - 工具调用顺序是否合理 错误类型代码沿用 TW, PA, EX, TC新增 IFIssue False——误报问题IMIssue Missing——遗漏问题8.6.2 修改 run_evaluation.py在Trae对话面板中输入请修改 run_evaluation.py使其适配代码健康度分析场景。 ## 修改要点 1. 读取 data/code_health_test_cases.json 2. 对每个测试用例 a. 确认 test_projects/ 下的项目代码存在 b. 向Agent发送请求请分析 {project_path}生成健康度报告保存为 {project_path}/health_report.md c. 等待Agent完成包括可能的自建工具步骤 d. 读取Agent生成的报告文件 e. 调用评测Agent进行评估 3. 汇总指标 4. 保存 evaluation_report.json8.7 Step5运行评测与迭代优化8.7.1 首次运行评测在Trae终端中python run_evaluation.py观察每个测试用例的执行过程。特别关注Agent是否在第一个用例中自建了工具比如scan_directory自建工具后后续用例是否复用了该工具Agent是否准确识别了problematic_project中的已知问题报告格式是否符合预期8.7.2 分析评测报告打开evaluation_report.json。首次评测的分数可能不会太高——特别是问题识别部分。常见问题包括遗漏问题IMAgent没有检测到deprecated_helper未被调用误报问题IFAgent将正常长度的函数标记为“过长”评分偏差Agent给出的总体评分与GT预期范围不一致找到得分最低的维度针对性修改系统提示词。8.7.3 第一次迭代假设评测报告显示Agent在problematic_project中遗漏了“重复代码”问题handlers.py与utils.py存在相似片段。修改方向在系统提示词中增加对重复代码检测的强调。在Trae对话面板中输入请修改 agent.py 的系统提示词在代码分析步骤中增加 4. 重复代码检测比较不同文件中的函数体如果两个函数的代码相似度超过60%通过逐行比较或使用SequenceMatcher在报告中列为重复代码问题。修改后重新运行评测python run_evaluation.py对比两次evaluation_report.json中问题识别相关指标的变化。8.7.4 用Git记录迭代gitadd-Agitcommit-mv1.1: 增加重复代码检测提示问题召回率从XX%提升至XX%8.8 项目交付与验证评测通过后你的代码仓库健康度分析Agent就可以真正使用了。找一份真实的Python项目——你室友的课设、你自己之前写的代码、或者GitHub上随便找的一个小项目——让Agent分析它。在agent.py的测试入口中if__name____main__:request请分析 /path/to/real/project生成健康度报告保存为 health_report.mdoutput,logrun_agent(request)print(output)打开生成的health_report.md。这是一份由你的Agent自动生成的专业代码质量报告——它是你第二部全部学习成果的集中体现。8.9 作品集包装指南这个项目是你课程设计的成果完善后也可以作为求职或竞赛作品集的核心资产。以下是包装建议。8.9.1 项目命名“代码仓库健康度分析Agent——具备自建工具能力的AI驱动代码质量审计系统”8.9.2 一句话介绍开发了一个能自动扫描Python项目、分析代码质量并生成诊断报告的AI Agent。Agent具备工具自建能力——当发现缺少目录扫描功能时自动生成并注册了scan_directory工具。完整实现了Harness五步工程化闭环。8.9.3 项目亮点设计并实现了3个预置工具文件读取、沙盒代码执行、报告写入 动态工具注册机制Agent可在运行时自动扩展工具箱构建了执行沙盒5层安全机制临时文件隔离、超时终止、模块白名单、输出限制、危险关键字扫描确保AI生成代码的安全执行在代码分析任务中Agent成功自建了scan_directory工具并在后续任务中复用展示了AI自我扩展能力设计了含工具调用审计的评测体系新增TW/PA/EX/TC/IF/IM六种错误类型构建了3个示例项目的黄金标准测试集完整走通“规范定义→数据构建→Agent开发→自动化评测→迭代优化”的工程闭环8.9.4 可用于软件工程/人工智能课程设计互联网/挑战杯/大创等科创竞赛校招AI应用岗/后端开发岗求职作品集个人技术博客文章8.10 本章小结本章综合运用了第二部教程的全部所学工具定义与实现、Function Calling循环、沙盒安全、ToolManager、工具调用审计、Agent自建工具。三个预置工具 N个自建工具构成了Agent的完整工具箱。scan_directory是Agent在本章任务中最可能自建的工具——它让Agent从“需要你告诉它有哪些文件”变成“自己搞清楚项目结构”。Harness五步法再次验证即使在更复杂的代码分析场景中规范定义→数据构建→Agent开发→自动化评测→迭代优化依然是最可靠的工程路线。这是一个能体现在简历上的项目它不仅展示了AI工具使用能力更展示了工程化思维、安全意识、系统设计能力——这些恰好是企业面试官最想看到而普通应届生最缺乏的。课后练习运行代码仓库健康度分析Agent让它分析test_projects/problematic_project。检查生成的报告是否识别了全部四个已知问题。如果有遗漏分析原因并修改系统提示词。让Agent分析你自己之前写过的一个Python项目。它发现了哪些你之前没意识到的问题报告的评分你觉得合理吗进阶扩展Agent的功能增加“代码注释覆盖率”检查——统计每个文件的注释行数占总行数的比例。如果Agent发现这个功能需要创建新工具观察它是否能成功自建。进阶让Agent在分析完成后不仅生成Markdown报告还生成一个JSON格式的机器可读报告方便接入CI/CD流程。这可能需要Agent修改write_file的调用方式或自建一个export_json_report工具。第二部【智能体工具使用实战】全书完