Lesson 09 — Eval Harness：让每个机制的收益有数字

本课目标：建立回归式评估基线——机制开关矩阵（全关/全开/单开）× 任务变体集 × 轨迹评估 = 机制收益表。把"加了记忆更好"从感觉变成表格里的数字。

学完你能回答：「你怎么知道你加的那些机制（记忆/反思/代码）真的有用？」——有回归评估，机制开关矩阵，收益全部量化。

0. 起点：L08 评估体系，但没有自动化

L08 建了 TrajectoryEvaluator（评一条轨迹）。但手动评估一条一条太慢——要对比"开记忆 vs 关记忆"得跑两组、评估两组、手动算差值。

本课建 harness：自动化这个对比。给它一组任务 + 一组开关配置，它自动跑所有组合、评估、产出收益表。

1. Agent 评估的特殊坑

坑1：非确定性

同一个 prompt，Agent 两次跑可能走不同路径（LLM 温度 > 0、搜索结果变化）。

应对：重复跑取分布，不看单次。本课简化为单次 + 标注（mock 模式下）。生产应跑 N 次取均值±标准差。

坑2：评估集设计

不是随便几个任务就行——任务要能区分"有机制 vs 无机制"。

能区分的任务（好）：
  "MCP 各年份工具数量对比" → 开了 code 才能算，关了只能口算 → 区分度高

不能区分的任务（差）：
  "MCP 是什么" → 有没有记忆都能答 → 区分度低

task_set.json 设计原则：每个任务标注 tests_mechanism，确保覆盖各机制的可区分场景。

坑3：成本控制

评估也烧 token（每个任务跑一次 = 几次 LLM 调用 × N 个任务 × M 个配置）。

应对： - 无 API 时用 mock 路径出流程演示（不烧钱，但数字不真实） - 真实评估用 fast 模型 judge（便宜）、抽样（不全跑） - 本课的 mock 模式零成本验证流程，--real 模式才烧钱

2. 开关矩阵

┌─────────────── 开关矩阵 ───────────────┐
│                                        │
│   配置          memory  skills  code   │
│   ────────────  ──────  ──────  ─────  │
│   全关（基线）    ❌      ❌      ❌    │
│   全开（v2）      ✅      ✅      ✅    │
│   仅记忆          ✅      ❌      ❌    │
│   仅代码          ❌      ❌      ✅    │
│                                        │
└────────────────────────────────────────┘
         × 8 个任务变体
         = 32 次运行
         → TrajectoryEvaluator 评估
         → 机制收益表

单机制开关的价值

不只是"全关 vs 全开"——单开某个机制能看这个机制单独的边际收益： - 全关 → 仅记忆：记忆的边际收益 - 仅记忆 → 全开：加上 skills+code 的边际收益 - 全关 → 仅代码：代码的边际收益

3. 任务变体集

task_set.json（8 个任务），每个标注： - tests_mechanism：测什么机制 - requires_memory/code/conflict：需要哪些机制才能做好

ID	主题	测的机制
T01	MCP 协议核心设计	memory（第2次记得）
T02	各年份工具数量对比	code（走代码计算）
T03	MCP vs function calling	skills（对比表）
T04	SDK 支持的语言	memory（第2次记得）
T05	是否基于 gRPC	conflict（冲突修正）
T06	场景统计	code（分类统计）
T07	演进路线图	memory+reflection（增量追踪）
T08	增长率趋势	code+memory（综合）

4. 流派对比

问题：怎么自动化评估 Agent 机制收益？

流派	做法	取舍
① 手动跑手动评	跑一次看一次	✅ 灵活；🚫 不可重复、主观
② 端到端集成测试	CI 里跑完整流程	✅ 自动；🚫 只知道通过/失败，不知道指标差异
③ 开关矩阵 harness（本课选它）	配置矩阵 × 任务集 × 评估器	✅ 可量化、可重复、隔离单机制；🚫 搭建成本

选 ③ 的理由：这正是"回归测试"在 Agent 领域的对应——传统软件回归测试是"改了代码别弄坏功能"，Agent 回归评估是"加了机制别弄坏质量+能看到收益"。开关矩阵让每个机制的边际收益隔离可见。

5. 落地清单

改了哪些文件

文件	改动	说明
`eval_agent/task_set.json`	新增	8 个任务变体（覆盖各机制可区分场景）
`eval_agent/run_harness.py`	新增	开关矩阵 × 任务集 × TrajectoryEvaluator → REPORT.md
`eval_agent/REPORT.md`	生成	机制收益表（mock 演示数字，诚实标注）

如何验证

cd portfolio-projects/research-assistant

# 1. mock 模式跑 harness（零成本，演示流程）
python eval_agent/run_harness.py
# 预期：生成 REPORT.md，含全关/全开/单机制对比表

# 2. 看报告
cat eval_agent/REPORT.md
# 预期：机制收益表 + 关键发现 + 数字来源标注

# 3. 真实模式（需 API key，烧 token）
python eval_agent/run_harness.py --real
# 预期：真实数字替代 mock 演示数字

演示

cd frontier-lessons/09_eval_harness
PYTHONIOENCODING=utf-8 ../../.venv/Scripts/python.exe code.py

6. 本课在两条主线上的位置

评估主线：本课是评估主线的收官——L08 建评估器，L09 建自动化 harness。至此，"加了机制有没有用"从 L00 的"感觉"变成了 L09 的"表格里的数字"。这是整个评估主线的闭环。
上下文工程主线：评估结果反过来指导上下文工程改进——如果 harness 显示"记忆召回率低"，说明 recall 的匹配策略要优化；如果"代码执行率低"，说明路由判断要调。评估是上下文工程的反馈环。

🎯 面试话术

「我给智能体建了回归评估：8 个任务变体、机制开关矩阵（全关/全开/单开）、用 L08 的 TrajectoryEvaluator 评轨迹指标。跑出来一张机制收益表——记忆召回从 0% 到 100%、代码执行从无到有。"加了记忆更好"在我这不是感觉，是表格里的数字。而且我诚实标注了 mock 演示和实测的区别——没跑过的不编数字。」