【智能体工具使用实战08】实战项目：代码仓库健康度分析Agent

第8章实战项目：代码仓库健康度分析Agent

本章你将学到：

综合运用第二部全部所学，从零搭建一个完整的工具增强型Agent系统

在实际项目中设计评测规范、构建测试集、开发Agent、运行评测、迭代优化

让Agent在项目中识别能力缺口并自建工具

将完整项目包装为可写入简历的作品

本章你将产出 ：一个能自动扫描Python项目、分析代码质量、生成诊断报告的Agent系统，以及一套完整的工程资产（规范、测试集、评测报告、迭代记录）

全部章节 ：收录在专栏《AI应用工程化实战教程》之【智能体工具使用实战】

8.1 项目背景与需求定义

8.1.1 场景设定

学期末，你的室友正在赶软件工程课设。他的项目是一个Python Web应用，包含十几个 .py 文件。截止日期前三天，他想做一次代码质量检查------有没有明显的逻辑错误？哪些函数写得太长？有没有写了但从未被调用的函数？

手动检查十几个文件、几千行代码，光是读完就要半天。他来找你帮忙。你说："我正好有一个能自动分析代码仓库的Agent。"

这就是本章的实战项目：代码仓库健康度分析Agent。

8.1.2 系统功能描述

Agent接收一个项目文件夹路径，自动完成以下分析：

分析维度	具体内容	需要的工具
代码规模统计	文件数量、总行数、有效代码行数（去除空行和注释）	`read_file` + `execute_python`
函数复杂度	每个函数的行数、嵌套深度、参数数量	`read_file` + `execute_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.md

8.3 Step1：规范定义

在动手开发之前，先定义评测规范。这是Harness五步法的第一步，也是确保系统质量的基础。

8.3.1 设计评测规范

创建 specs/code_health_spec.md。在Trae对话面板中输入：

复制代码

在项目 data-analyst-agent 中创建 specs/ 目录，然后生成一份评测规范文档 specs/code_health_spec.md。

## 系统功能
代码仓库健康度分析Agent。输入一个Python项目路径，输出一份健康度分析报告。

## 评测维度

### L1 工程指标
- 报告格式合规率：报告是否包含标题、总体评分、分维度评分、问题清单、改进建议
- 文件覆盖率：是否分析了项目中所有.py文件（不可遗漏）
- 可解析性：报告是否结构清晰，可被程序或人工快速定位问题

### L2 业务指标
- 问题识别准确率：报告中指出的问题是否确实存在（不误报）
- 问题召回率：项目中实际存在的问题，报告是否指出了（不漏报）
- 评分合理性：总体评分和各维度评分是否与实际问题严重程度一致

### L3 场景指标
- 过长函数检测准确率：对超过50行的函数的检测是否正确
- 依赖分析完整性：是否识别了所有导入但未使用的模块

## 黄金标准构建原则
- 准备2-3个不同规模和质量的示例Python项目作为测试集
- 每个项目由人工标注已知问题清单（ground truth issues）
- 黄金评审报告包含：预期识别的问题列表、预期评分范围、预期报告结构

## 边界规则
- 空项目（没有.py文件）：报告应说明"未找到Python文件"
- 单个文件项目：应正常分析
- 包含非UTF-8编码文件：应跳过或标注
- 项目路径不存在：应返回清晰错误信息

8.4 Step2：数据构建

8.4.1 准备测试用的示例项目

我们需要2-3个不同质量的Python项目作为测试数据。每个项目模拟真实的学生课设代码------有些写得好，有些有问题。

在Trae对话面板中输入：

复制代码

在项目 data-analyst-agent 中创建 test_projects/ 目录，包含三个示例项目：

## 项目A：良好项目（good_project）
路径：test_projects/good_project/
包含3个.py文件，代码质量较好：
- main.py：入口文件，代码简洁，调用其他模块
- utils.py：工具函数，每个函数不超过30行
- models.py：数据模型定义，结构清晰
所有函数不超过50行，嵌套不超过3层，无重复代码

## 项目B：有问题项目（problematic_project）
路径：test_projects/problematic_project/
包含4个.py文件，存在已知问题：
- main.py：包含一个超过80行的函数（parse_data），嵌套深度达到5层
- utils.py：有一个从未被调用的函数（deprecated_helper）
- models.py：正常
- handlers.py：与 utils.py 中有超过60%相似度的重复代码片段

## 项目C：极简项目（minimal_project）
路径：test_projects/minimal_project/
包含1个.py文件：hello.py，只有10行，功能简单

请生成这些项目的完整代码。

8.4.2 构建黄金标准测试集

在Trae对话面板中输入：

复制代码

请读取 test_projects/ 下的三个项目，为每个项目构建黄金标准评测数据，保存为 data/code_health_test_cases.json。

## 每个测试用例包含
- test_id：CH001, 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 Step3：Agent开发

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, pathlib

8.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，新增 IF（Issue False------误报问题），IM（Issue 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.json

8.7 Step5：运行评测与迭代优化

8.7.1 首次运行评测

在Trae终端中：

bash 复制代码

python run_evaluation.py

观察每个测试用例的执行过程。特别关注：

Agent是否在第一个用例中自建了工具？（比如 scan_directory）
自建工具后，后续用例是否复用了该工具？
Agent是否准确识别了 problematic_project 中的已知问题？
报告格式是否符合预期？

8.7.2 分析评测报告

打开 evaluation_report.json。首次评测的分数可能不会太高------特别是问题识别部分。常见问题包括：

遗漏问题（IM） ：Agent没有检测到 deprecated_helper 未被调用
误报问题（IF）：Agent将正常长度的函数标记为"过长"
评分偏差：Agent给出的总体评分与GT预期范围不一致

找到得分最低的维度，针对性修改系统提示词。

8.7.3 第一次迭代

假设评测报告显示：Agent在 problematic_project 中遗漏了"重复代码"问题（handlers.py 与 utils.py 存在相似片段）。

修改方向：在系统提示词中增加对重复代码检测的强调。

在Trae对话面板中输入：

复制代码

请修改 agent.py 的系统提示词，在代码分析步骤中增加：
"4. 重复代码检测：比较不同文件中的函数体，如果两个函数的代码相似度超过60%（通过逐行比较或使用SequenceMatcher），在报告中列为'重复代码'问题。"

修改后重新运行评测：

bash 复制代码

python run_evaluation.py

对比两次 evaluation_report.json 中问题识别相关指标的变化。

8.7.4 用Git记录迭代

bash 复制代码

git add -A
git commit -m "v1.1: 增加重复代码检测提示，问题召回率从XX%提升至XX%"

8.8 项目交付与验证

评测通过后，你的代码仓库健康度分析Agent就可以真正使用了。

找一份真实的Python项目------你室友的课设、你自己之前写的代码、或者GitHub上随便找的一个小项目------让Agent分析它。

在 agent.py 的测试入口中：

python 复制代码

if __name__ == "__main__":
    request = "请分析 /path/to/real/project，生成健康度报告，保存为 health_report.md"
    output, log = run_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 工具。

第二部【智能体工具使用实战】全书完

【智能体工具使用实战08】实战项目：代码仓库健康度分析Agent

第8章 实战项目：代码仓库健康度分析Agent

8.1 项目背景与需求定义

8.1.1 场景设定

8.1.2 系统功能描述

8.2 系统架构设计

8.2.1 工具集规划

8.2.2 工作流程设计

8.3 Step1：规范定义

8.3.1 设计评测规范

8.4 Step2：数据构建

8.4.1 准备测试用的示例项目

8.4.2 构建黄金标准测试集

8.5 Step3：Agent开发

8.5.1 修改系统提示词

8.5.2 确认基础工具集

8.5.3 更新沙盒白名单

8.6 Step4：自动化评测

8.6.1 生成评测脚本

8.6.2 修改 run_evaluation.py

8.7 Step5：运行评测与迭代优化

8.7.1 首次运行评测

8.7.2 分析评测报告

8.7.3 第一次迭代

8.7.4 用Git记录迭代

8.8 项目交付与验证

8.9 作品集包装指南

8.9.1 项目命名

8.9.2 一句话介绍

8.9.3 项目亮点

8.9.4 可用于

8.10 本章小结

课后练习

第8章实战项目：代码仓库健康度分析Agent