AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

顶点课 27：带 Fixture Tasks 的 Eval Harness ​

coding agent 的上限，取决于你拿什么任务集去量它。这节课会做一套 evaluation harness：吃进一目录 fixture task，把每个 task 喂给候选 agent，用确定性 verifier 评分，再聚合成 pass@1、pass@k、平均延迟和平均成本。harness 就是那份能分清“回归”与“重构”的真值源。

类型： Build 语言： Python（stdlib） 前置要求： 第 19 阶段 · 25（verification gates），第 19 阶段 · 26（sandbox runner），第 14 阶段 · 30（eval-driven agent development），第 14 阶段 · 19（SWE-bench 与 GAIA benchmarks） 预计时间： ~90 分钟

学习目标 ​

  • 把 fixture task 定义成目标、setup、verifier 组成的三元组。
  • 对每个 task 跑多次 sample，并计算 pass@1 与 pass@k。
  • 聚合 latency 和 cost，给出均值与 95 分位。
  • 把确定性 verifier（文件 diff、exit code、regex match）做成可复用函数。
  • 产出结构化 JSON 报告，供回归跟踪脚本直接吞。

问题背景 ​

没有 eval harness 的 agent benchmark，通常会死在三种故障里。

第一种是假通过。agent 说自己修好了，人工扫一眼 diff，套件就被标绿。三周后同一个 bug 又从回归测试里冒出来，因为 agent 当时只是推理得很像样，并没有真的修对。

第二种是静默回归。prompt template 改了一版，某个响亮任务提升 4%，某个不显眼任务却掉了 14%。没有 goldset 和逐 task 分数，回归就一路溜进 main，直到客户来报错。

第三种是任务集漂移。周一 eval 跑了 100 个任务，周五只跑了 95 个，因为有人把 5 个 fixture 改名了。pass rate 看起来像涨了 5%，其实纯属统计幻觉。

harness 的意义就是把这些幻觉打回事实：每次都按可复现顺序跑完全部 fixture，再用确定性 verifier 返回 true/false。

核心概念 ​

mermaid
flowchart LR
  F1[fixtures/task_001/<br/>task.json + expected/] --> Harness
  F2[fixtures/task_002/<br/>...] --> Harness
  Harness[Harness<br/>对每个任务：<br/>准备 / 跑 agent k 次采样 /<br/>验证每次采样 /<br/>记录延迟和成本]
  Harness --> Report[EvalReport<br/>pass@1 / pass@k<br/>平均 ms / 平均成本]

一个 FixtureTask 是一个小 JSON，再加一个可选的 expected/ 目录。JSON 至少声明：

  • id
  • goal：喂给 agent 的 prompt
  • setup：要放进 scratch dir 的文件
  • verifier：调用哪一个 verifier，以及参数

3 种 verifier 形状已经能覆盖绝大多数有用任务：

  • file_equals：agent 跑完后，把某个文件与 expected 内容做精确比对。适合“必须按这个方式修”的任务。
  • regex_match：对指定文件内容跑正则。适合“函数必须存在并返回 X”这种存在多种等价写法的任务。
  • shell_exit_zero：通过第 26 课的 sandbox 执行一条 shell 命令，只有 exit code 为 0 才算通过。适合“测试必须全过”。

harness 对每个 task 跑 k 次。pass@k 可以表示成 1 - (1 - p)^k，其中 p 是经验通过率；同时 harness 也会把原始通过次数一起报出来，让你看到方差。latency 按 sample 的 wall-clock 统计。cost 则吃 agent 自报的 token、USD 或二者之一，然后给出逐 task 与总量聚合。

figure
pass-at-k

架构 ​

mermaid
flowchart TD
  Harness[EvalHarness] -->|加载| Task[FixtureTask<br/>goal / setup / verifier]
  Harness --> Loop[对每个任务：<br/>从 setup 准备 scratch 目录<br/>对 k 次采样：<br/>跑 candidate task, scratch_dir -> SampleResult<br/>验证采样, task -> bool<br/>记录逐任务聚合]
  Loop --> TaskReport[TaskReport<br/>task_id / k / passes / pass_rate<br/>mean_latency / mean_cost]
  TaskReport -->|聚合| EvalReport[EvalReport<br/>总任务数 / pass@1 / pass@k / p95 延迟]

candidate 是一个 callable：Callable[[FixtureTask, str], SampleResult]。harness 自己用 tempfile.mkdtemp() 准备 scratch dir，并把路径当普通字符串传进去。harness 不关心 candidate 是怎么工作的。它可以是一个确定性 patch applier，也可以是真实 LLM agent，甚至是 fuzzer。harness 只认 SampleResult 这个契约。

你要构建什么 ​

main.py 里会交付：

  1. FixtureTask dataclass
  2. SampleResult dataclass：success_self_reported、latency_ms、cost_units、edits
  3. TaskReport、EvalReport dataclass，并带 to_dict()
  4. VerifierRegistry，把 verifier name 映射到函数。内置 verifier 有 file_equals、regex_match、shell_exit_zero
  5. EvalHarness 类：对一整个任务目录跑 candidate，返回 EvalReport
  6. tasks/ 里自带 5 个 fixture：
    • fizzbuzz 里的 off-by-one
    • factorial 缺 return
    • error message 拼写错误
    • 空函数体
    • linked-list traversal 的 off-by-one
  7. 一个确定性的参考 candidate：apply_known_fixes，用于演示 pass@1 = 1.0
  8. demo：打印 EvalReport JSON，并以 0 退出

fixture task 由 tasks/ 下的 JSON 和配套 buggy/、expected/ 目录组成。harness 先把 buggy 拷进 scratch dir，再交给 candidate，最后按 expected 做验证。

为什么要看 pass@k，不只是 pass@1 ​

真实 LLM agent 天生随机。pass@1 = 0.6 看起来像半残，但 pass@5 = 0.95 往往说明模型大多数时候知道正确答案，只是在早期 sample 里选错了。那该修的可能是 sampling 与 ranking，而不一定是模型本身。

但 pass@k 不能单独看，因为它很容易把真实失败洗白。一个模型 20 次里只蒙对 1 次，你并没有一个可用 agent。所以 harness 会同时报 pass@1 和 pass@k。

它如何接进 Track A ​

第 25 课给了 gate chain，第 26 课给了 sandbox。shell_exit_zero verifier 会直接走 sandbox。第 28 课把每次 harness run 包进 OTel trace。第 29 课则拿 bunded fixture 之一跑完整端到端 demo，并断言参考 candidate 的 pass@1 = 1.0。

运行方式 ​

bash
cd phases/19-capstone-projects/27-eval-harness-fixture-tasks
python3 code/main.py
python3 -m pytest code/tests/ -v

demo 会打印 EvalReport JSON，包含 pass@1、pass@5、平均延迟，以及逐 task 细分。退出码为 0。测试覆盖 verifier 函数、pass@k 计算、fixture 加载，以及 harness 对 bundled 参考 candidate 的端到端流程。