Eval Harness 源码内核：完整目录

第一次读这套教材，建议你从学习入口 开始，先跟着运费案例跑完整条证据链，再决定后面要往哪里深挖。目录依次安排了「共同语言 → 最小实现 → 上游源码 → 工程专题 → 横向比较 → 案例与实验」，按这个顺序读，你就不会一开始便钻进各种工具名称，更不会把某个项目自己的叫法当成通用语义。

入口

• 开始学习：贯穿案例、阅读约定和第一次运行；
• 学习路线：新人、源码阅读、Agent 评测和 Eval-to-RL 路径；
• 仓库首页：项目定位、内容地图和快速命令；
• 完整中文 PDF：可离线阅读的整书版本；
• 第三方来源：锁定提交、许可证与引用边界。

第一部分：基础篇

1. Agent Harness 与 Eval Harness
2. Task、Dataset、Target 与 Environment
3. Sample、Trial 与 Attempt
4. Trace、Artifact 与 Observation
5. Scorer、Judge、Score 与 Metric
6. 不确定性、比较与 Gate
7. Eval-to-RL 与独立发布评测

第二部分：可运行参考

• 运费边界案例
• eval-harness-ref 命令入口
• Reference Harness 自动化测试

Reference Harness 用一份最小合同把 Trial/Attempt、Trace、按内容寻址的 Artifact、Observation、Score、Metric、Comparison、Gate 和离线报告串了起来。你可以拿它检验教材里讲的机制，但不能因此宣称它复刻了某套上游工具。这条边界不能越过。

第三部分：上游源码课程

1. lm-evaluation-harness：Task 怎样变成批量模型请求
2. Inspect AI：Solver、Sandbox、Scorer 与 EvalLog
3. OpenAI Evals：Registry、CompletionFn 与 Recorder
4. Promptfoo：配置矩阵、Provider、Assertion 与 CI
5. DeepEval：Golden、TestCase、Metric 与执行策略
6. Harbor 与 Terminal-Bench 1：环境、Agent、Verifier 与 Trial

每条源码课程都先用导读带你进门，再分三篇往深处讲。正文会对着锁定的提交，依次找到源码从哪里进入、调用怎样往下走、哪些数据结构最关键，以及失败如何一层层传出来，然后再让你用实验、预期输出和参考答案检验自己是否真的看懂了这些设计取舍。别只记名词。

第四部分：工程篇

1. 最小 Eval Loop
2. Run Identity 与可复现性
3. Retry 与 Recovery
4. LLM-as-a-Judge
5. 统计比较
6. Agent Environment
7. Quality Gate
8. Eval-to-RL

第五部分：横向比较

1. Task、Dataset 与 Target
2. Runner、并发、缓存与 Retry
3. Trace、Artifact 与血缘
4. Scorer、Judge 与 Outcome
5. Metric、统计单位与不确定性
6. Agent Environment 与 Final State
7. Report、CI 与 Release Gate
8. 平台适配器边界

第六部分：案例

• 运费边界
• 退款 Agent
• 企业知识助手
• 合同审查 Agent
• SWE-bench 补丁评测机制

前四个案例都准备了结果确定的 buggy/fixed Target，你也可以直接把门禁跑起来。SWE-bench 则把重心放在环境怎样影响机制，你会看到补丁、隔离环境、测试证据和实例级判定如何互相约束。

第七部分：实验

1. 运行一份确定性 Eval
2. 新增 Target Adapter
3. 编写 Scorer
4. 重复运行并比较
5. 导入 Agent Trace
6. 构建 Release Gate

附录

• 术语表
• 验证与证据边界
• 来源与许可证

怎样读一篇源码课

读源码课时，先查清课程锁定了哪个版本，并找到入口，然后顺着调用链逐站追问：谁发起调用，传进来什么，状态在哪里变了，结果怎样返回，失败又怎样传出去，以及哪组测试锁住了这些行为。读完再跑一遍本仓库的确定性实验，拿实际输出检验自己是否看懂了机制，别只记住 API。