第6章 智能体开发Step4 & 5：让“裁判”上场，实现自动化评测与迭代

本章你将学到：

• 严格区分业务智能体和评测智能体，理解各自职责
• 用Claude Code生成评测智能体的Prompt和运行脚本
• 让AI帮你编写批量评测脚本，一键生成完整评测报告
• 使用常见错误归因手册快速定位问题根源
• 基于评测数据完成第一次真正的迭代优化
• 用Git管理Prompt和代码的版本，建立可追溯的迭代历史
• 将智能体导出为独立脚本，理解“开发工具≠运行环境”

本章你将产出：一个评测智能体、一个批量评测脚本、一份完整的评测报告、一个迭代优化后的业务智能体V1.1、以及一份清晰的Git版本历史
全部章节：收录在专栏《AI应用工程化实战教程》

---

第5章我们用Claude Code生成了评论甄别智能体。它跑起来了，在几条测试上表现看起来还不错。但“看起来不错”离“真的不错”之间，差着一整套自动化评测体系。

本章我们要做的是：再让Claude Code帮我们造一个“裁判”——评测智能体，并让它批量审阅业务智能体的每一次判断，最后自动生成一份告诉你“哪里做错了、为什么错、怎么改”的评测报告。

整章的工作，依然遵循本书的核心原则：你不会写的代码，让AI帮你写；但你必须知道要让它写什么，写完之后能判断它对不对。

本章以Claude Code作为开发环境，但同样的方法也适用于其它AI辅助编程工具，比如Trae也可以，还免费，详见第3章。

---

6.1 关键区分：业务智能体 VS 评测智能体

在动手让AI干活之前，先理清一对容易混淆的概念。

业务智能体：直接面向用户需求，执行具体业务任务的AI。在我们的项目里，就是第5章生成的 comment_agent.py 背后那个判断评论有效性的AI。你可以把它想象成正在参加考试的考生——它的任务就是答题。

评测智能体：不面向用户，而是面向开发者。它的任务是对业务智能体的输出进行质量评估。它手握着我们第4章人工标注的黄金标准（GT），就像批改试卷的老师——它有标准答案，它的职责是判断考生的答案对不对。

两者必须严格分离。如果让同一个Prompt既做判断又做评测，你根本不知道它评测的标准是不是已经悄悄“放水”了。分离之后，评测智能体本身也可以被独立迭代——如果“老师”改卷标准有问题，你可以单独修正它，而不会影响“考生”。

---

6.2 用Claude Code生成评测智能体

评测智能体的核心任务可以用一句话描述：给定一条评论、业务智能体的判定结果、黄金标准，判断业务智能体是否正确，并给出错误类型和分析。

现在，我们把这句话变成一条给Claude Code的指令，让它帮我们生成两个文件：评测Prompt模板和评测脚本。

6.2.1 设计给Claude Code的指令

在终端中（确保你在项目目录下，且已启动Claude Code），输入以下指令：

你是AI工程化开发专家。我正在开发“评论有效性甄别智能体”，目前已经有了：
- comment_agent.py：业务智能体脚本，核心函数 analyze_comment(comment_text) 返回 {"valid": bool, "reason": str, "details": {...}}
- test_data.csv：测试数据集，包含 comment_id、comment_text、gt_label（"有效"或"无效"）三列
- spec_review_validity.md：评测规范文档

现在我需要你帮我生成一套评测系统，包含两个文件。

### 文件1：eval_prompt.txt
这是评测智能体的系统提示词。要求：
- 角色：你是一个专业的AI评测审计员。你的任务是比对“业务智能体的判定结果”与“黄金标准”，判断业务智能体是否正确。
- 输入：你会收到三条信息——用户评论原文、业务智能体输出（JSON格式，含 valid 和 reason）、黄金标准标签（"有效"或"无效"）。
- 任务：
  1. 对比 valid 值与黄金标准是否一致。
  2. 分析判定理由是否合理（即使结果正确，理由明显荒谬也应标注为错误）。
  3. 输出严格JSON，不包含任何其他文字。
- 输出格式：
  {
    "match": true/false,
    "ground_truth": "有效"或"无效",
    "agent_judgment": true/false,
    "error_type": "无"或错误代码,
    "analysis": "简要分析，不超过100字"
  }
- 错误类型代码（必须严格使用以下代码）：
  - FP：将无效评论误判为有效
  - FN：将有效评论误判为无效
  - RE：判定结果正确但理由明显错误或不合理
  - OK：完全正确
- 语言为中文。

### 文件2：evaluator.py
这是封装评测智能体调用逻辑的Python脚本。要求：
- 使用 anthropic 库调用Claude API，使用 python-dotenv 从 .env 文件读取密钥。
- 包含完整的类型注解和中文docstring。
- 核心函数签名为 evaluate(comment_text: str, agent_result: dict, ground_truth: str) -> dict。
- 函数内部：
  a. 根据 agent_result 中的 valid 和 reason 构建给评测智能体的用户消息。
  b. 调用Claude API，发送系统提示词（从 eval_prompt.txt 读取）和用户消息。
  c. 解析返回的JSON，返回字典。
  d. 如果API调用或JSON解析失败，返回一个结构一致的错误字典，match 为 false，error_type 为 "EVAL_FAILED"，analysis 中包含异常信息。
- 在脚本底部包含 if __name__ == "__main__": 测试入口，用一条评论、一个模拟的 agent_result 和一个 ground_truth 进行单次评测测试。

请先读取项目中的相关文件，理解数据格式和业务智能体的输出结构，然后生成上述两个文件。

Claude Code会依次读取规范文档、测试数据和业务智能体脚本，然后生成 eval_prompt.txt 和 evaluator.py。

6.2.2 审查生成的评测系统

生成完毕后，你需要做审查。

检查 eval_prompt.txt：

• 角色定义清晰？
• 错误类型代码是否完整（FP、FN、RE、OK）？
• 输出格式是否严格JSON，没有多余引导语？
• 有没有包含“要求业务智能体输出格式”之类的无关内容？（应该没有，评测智能体只关心比对）

检查 evaluator.py：

• 是否正确导入了 anthropic 和 dotenv？
• evaluate 函数的三个参数类型注解正确？
• 是否读取了 eval_prompt.txt 作为系统提示词？
• 用户消息中是否包含了评论、agent结果和黄金标准？
• 异常处理是否返回了统一结构的错误字典，而不是 None 或抛出异常？
• 测试入口是否写了模拟调用？

如果有任何问题，直接在Claude Code中要求修正。例如：

evaluator.py 中异常处理返回的字典里没有 ground_truth 字段，请补上，并确保结构与其他情况一致。

---

6.3 用Claude Code生成批量评测脚本

评测智能体就绪后，我们需要一个“跑批脚本”——它遍历 test_data.csv 中的每一条数据，依次调用业务智能体和评测智能体，统计所有指标，最后生成评测报告。

同样，我们让Claude Code来写这个脚本。

6.3.1 给Claude Code的指令

在Claude Code中继续输入：

现在评测智能体已经就绪（eval_prompt.txt 和 evaluator.py）。请帮我生成一个批量评测脚本 run_evaluation.py。

要求：
- 读取 test_data.csv，遍历其中的每一条数据。
- 对每条数据：
  a. 调用 comment_agent.py 中的 analyze_comment 函数，传入评论文本，获得业务智能体结果。
  b. 调用 evaluator.py 中的 evaluate 函数，传入评论文本、业务智能体结果、gt_label，获得评测结果。
  c. 在终端显示进度：[comment_id] GT=有效/无效 | Agent=有效/无效 | ✅/❌
  d. 为避免API速率限制，每次调用后休眠0.5秒。
- 统计以下指标：
  - 总测试数
  - 判定正确数
  - 准确率（百分比，保留一位小数）
  - FP（误判为有效）数量
  - FN（误判为无效）数量
  - RE（理由错误）数量
  - 评测失败数量（如果 error_type 为 EVAL_FAILED）
- 将每条详细结果（comment_id, comment_text前50字, agent_valid, agent_reason, gt_label, eval_match, error_type, analysis）存入列表。
- 最后，将汇总指标和详细结果保存为 evaluation_report.json（格式：{"summary": {...}, "details": [...]}）。
- 代码要有清晰的注释，包含类型注解，并在脚本开头用docstring说明用途。
- 所有导入的模块应该都是标准库或已安装的（csv, json, time, 以及我们项目中的 comment_agent 和 evaluator）。

Claude Code会生成 run_evaluation.py。生成后，检查以下几点：

• 是否正确从 comment_agent 和 evaluator 导入了函数？
• 是否遍历了所有测试数据？
• 统计指标的计算逻辑是否正确？
• 休眠是否在循环内部？
• JSON报告的结构是否符合要求？

如果发现某个地方不对（比如它没有统计RE数量），直接告诉Claude Code修正。

---

6.4 首次运行评测，获得第一份报告

所有脚本就绪。在终端中执行：

python run_evaluation.py

你会看到终端里逐条刷过 ✅ 和 ❌。运行完毕后，一份 evaluation_report.json 就生成了。

打开它，重点关注 summary 部分的几个数字：

• 准确率低于80%？ 没关系，初版智能体通常就是这样，这恰恰说明了评测的价值。
• FP特别多？ 你的智能体太“宽容”了，放进了很多无效评论。
• FN特别多？ 你的智能体太“严格”了，误杀了很多真实有用的评论。
• RE（理由错误）有出现？ 就算结果蒙对了，理解也可能是错的，这是隐患。

---

6.5 使用常见错误归因手册精准定位问题

有了评测报告，接下来要回答的问题是：为什么会犯这些错？该从哪里改起？

这里有一份常见错误归因手册，对照你的 evaluation_report.json 中 error_type 和 analysis 字段，找到你的智能体最常犯的错误类型。

错误现象	典型特征	常见原因	解决方向
FP：笼统好评误判为有效	“味道好极了”“真心不错”被判有效	具体性维度定义不够严格，只看到“正面情绪”没检查具体细节	在Prompt中强化“具体性”的判断标准，要求必须出现具体名词或可验证描述
FP：情绪发泄被判有效	大段愤怒文字被判有效，只因篇幅长	信息密度维度失效，误把“情绪字数”当“有效信息”	在信息密度维度中明确区分“情绪表达”和“事实信息”
FN：简短但有用的评论被误判	“分量足，比图片多”被判无效	过度惩罚短评论，认为短=无信息	调整信息密度维度：短评论如果有具体细节，仍应判有效
FN：混合型评论被整体否定	前半段抱怨配送，后半段说菜品好，整体被判无效	相关性维度权重过高，没有区分“部分无关”与“主体无关”	在相关性规则中明确：只要商品相关内容超过50%，仍可判有效
RE：结果正确但理由荒谬	判对了，但理由是“评论语气好”	Prompt中对输出理由没有约束，AI自由发挥	在Prompt中要求理由必须引用具体维度判断，不能出现主观感受描述
边界案例：空/纯表情处理不一致	空评论有时判有效有时判无效	没有在代码层做硬校验，依赖模型判断	在代码中硬性拦截空输入，不交给AI判断（我们已在第5章做了）

现在，从你的评测报告中找出占比最大的错误类型，然后从表中找到对应的解决方向。带着明确的目标去修改，而不是“感觉哪里不对就改哪里”。

---

6.6 完成第一次迭代优化

6.6.1 基于数据修改Prompt

假设你的评测报告显示：FP错误最多，主要是“笼统好评被判为有效”。那么你需要修改 prompt_template.txt，强化具体性的判断标准。

在Claude Code中输入：

请修改 prompt_template.txt，在“具体性”维度的判断标准中增加一条严格要求：
仅出现“好吃”“不错”“推荐”等笼统形容词，而未提及任何具体菜品名、口味细节、价格、分量等可验证信息的，一律判定为不通过。正面情绪不等于具体信息。

修改完成后，不要手动测试几条就认为修好了。正确的做法是：再次运行完整的评测脚本。

python run_evaluation.py

对比两次 evaluation_report.json：FP数量下降了吗？FN有没有因此上升？如果FN也上升了，说明修改可能矫枉过正——你需要继续微调。

6.6.2 用Git管理迭代历史

在修改Prompt之前，先提交当前版本：

git add prompt_template.txt comment_agent.py evaluator.py eval_prompt.txt run_evaluation.py evaluation_report.json
git commit -m "v1.0: 初版智能体及评测系统，首次评测准确率XX%"

修改Prompt后，再次评测，确认指标有提升，然后提交新版本：

git add prompt_template.txt evaluation_report.json
git commit -m "v1.1: 强化具体性维度，FP减少X个，准确率提升至XX%"

现在，用 git log 查看提交历史。你会看到一条清晰的演进轨迹：v1.0 → v1.1。如果v1.1反而变差了，你可以用 git diff HEAD~1 prompt_template.txt 看到Prompt到底改了什么，然后用 git revert 回退。

这就是工程化迭代：每一步都有记录，每一次修改都有数据支撑，每一个版本都可以回退。

---

6.7 工程资产归档与工具解耦

至此，你的项目目录应该包含以下文件：

comment-analyzer/
├── .env                       # API密钥（不提交）
├── .gitignore
├── spec_review_validity.md    # 评测规范文档（第4章）
├── test_data.csv              # 黄金标准测试集（第4章）
├── prompt_template.txt        # 业务智能体Prompt（第5章）
├── comment_agent.py           # 业务智能体脚本（第5章）
├── eval_prompt.txt            # 评测智能体Prompt（本章）
├── evaluator.py               # 评测智能体脚本（本章）
├── run_evaluation.py          # 批量评测脚本（本章）
└── evaluation_report.json     # 最新评测报告（本章）

所有这些文件，除了 .env，都是你的工程资产。下次你做一个新的智能体，完全可以复用这套目录结构和脚本框架——只需要替换规范和Prompt。

现在验证一下“工具解耦”。你是在Claude Code的辅助下完成了这些开发，但你的智能体现在完全不依赖Claude Code。打开一个全新的终端窗口（不要进入Claude Code），直接运行：

cd comment-analyzer
python run_evaluation.py

它应该正常工作。所有逻辑都在Python脚本里，所有配置都在txt和.env里。你甚至可以把整个文件夹打包发给朋友，他只需要有自己的API密钥就能运行。

开发工具是“脚手架”，产出的智能体是“建筑”。房子盖好了，脚手架可以拆走。

---

6.8 本章小结

• 业务智能体与评测智能体必须分离——考生和老师不能是同一个人。
• 我们再一次让AI写了代码。评测智能体的Prompt、评测脚本、批量跑批脚本，都是给Claude Code下指令生成的。你做的事是：提需求、审产出、做决策。
• 自动化评测让我们告别“肉眼一条条看”。一键运行，所有指标和错误分布清清楚楚。
• 常见错误归因手册帮助精准定位问题，而不是凭感觉猜。
• 迭代优化必须有数据支撑：改前跑一次评测，改后再跑一次，对比指标变化。用Git记录每一次迭代。
• 开发工具≠运行环境：所有产出的脚本都是独立可运行的，不绑定Claude Code。

从第4章到本章，我们完整走完了Harness五步法的全部流程：

• Step1：规范定义 → spec_review_validity.md
• Step2：数据构建 → test_data.csv（含GT）
• Step3：智能体开发 → comment_agent.py + prompt_template.txt
• Step4：自动化评测 → evaluator.py + run_evaluation.py + evaluation_report.json
• Step5：迭代优化 → v1.0 → v1.1 的演进记录

你已经第一次完成了可评测、可迭代、标准化的智能体全流程开发。换一个工具——比如Trae IDE，你可以把同一个项目完整复刻一遍。这将证明：范式是永恒的，工具只是载体。

---

课后练习

1. 运行 run_evaluation.py，得到你的初版评测报告。统计FP、FN、RE各有多少，找出占比最大的错误类型。
2. 根据常见错误归因手册，针对你发现的最主要错误类型，用Claude Code修改 prompt_template.txt。修改后重新运行评测，准确率有提升吗？有没有引入新的错误？
3. 用 git log 查看你的版本历史。用 git diff 对比两次Prompt的变化，写一段简短的迭代日志，说明你改了什么、为什么改、效果如何。
4. 尝试让Claude Code修改 eval_prompt.txt，使它对“理由错误（RE）”的判定更严格（例如：理由中出现了“感觉”“似乎”等主观词汇就标记为RE）。重新跑一次评测，观察RE数量的变化。
5. （进阶）告诉Claude Code：“请在 run_evaluation.py 中增加对四个维度的独立统计——解析 agent_result 中的 details 字段，计算业务智能体在各个维度上的通过率，并写入评测报告。” 观察AI如何实现这个功能。

---