
前言
为什么写这本书
[需作者补充:一次你亲历的“离线评测通过、上线后 agent 行为出问题”的经历。系统、时间、后果写具体,放在本节第一段。]
第 1 章开头用了一个构造的故障:给 DevOps 值班 agent 的 instructions 加一句“写操作前先复述要改的字段”,50 条离线任务全部通过,发布当晚 agent 却没有等人审批,直接改了一条生产配置。原因是下游的升级判断步骤把模型那句笃定的复述当成了“已有人确认”。模型没换,每一步的输出单看都没错,问题出在 instructions、模型输出和升级判断三者的衔接上。
逐条检查“模型这一步答得对不对”的评测,发现不了这类问题。包在模型外面的指令与上下文、工具与执行环境、编排与工作流、约束与反馈统称 harness,agent 的实际行为越来越多由这一层决定。现在主流 agent 框架都自带打分器,能判断一次运行的输出和轨迹对不对,但下面这些问题仍然要自己搭:同一批任务跑多次结果稳不稳定,哪个模块在拖后腿,失败的病灶在哪一步,该停下来问人的时候 agent 有没有停,改一版之后整体分的下降是噪声还是退化。这本书讲的就是怎么把这些评测装到一个真实的 harness 上,并让它们在每次改动时自动运行。
这本书写给谁
适合:
- 已经在搭 agent、harness、skill 或知识库,但说不清它好在哪、差在哪的工程师;
- 改完提示词、加完工具,发布前没有把握的人;
- 负责一套线上 agent 系统,需要量化各模块贡献、防止整体劣化的人。
不适合:
- 只关心预训练、RLHF 等模型内部机制,不做应用层系统的人;
- 想找开箱即用的 SaaS 评测平台、不打算改自己 harness 的人。
没跑过评测也可以读。LLM judge、评测数据集、回归门禁这些基础概念,书里在用到的地方都会讲。读过姊妹篇《AI Agent 评测工程实战》的话,第 2 章的部分术语可以略读。
覆盖范围
覆盖:
- 评测方法论的地基:消融实验、确定性评测、贡献度归因、pass^k 等后面反复用到的术语,以及为什么评测分数要按统计实验来解读(第 1–4 章);
- 给 harness 接上评测层,构建任务集,量出带误差棒的整体分,记录可追因的 trace(第 5–8 章);
- 模块贡献度归因和失败根因定位(第 9–11 章);
- 稳定性、人在回路、前端与服务端形态的评测差异(第 12–14 章);
- 线上影子评估与灰度、防劣化闭环,以及评测平台和业务定制各自该管什么(第 15–17 章)。
不覆盖:
- 模型训练与对齐;
- 某个评测平台的界面操作。平台功能变化快,书里只在第 17 章讨论平台和自建的分工。
全书贯穿一个例子:用 TypeScript 框架 Mastra 搭的 DevOps 值班助手,会查日志、查监控、改配置,遇到高危操作升级给人类 oncall。一个场景覆盖了三类情况:能批量回放的只读任务(第 7 章),必须等人审批的高危写操作(第 13 章),服务端和浏览器面板两种形态(第 14 章)。各章依次给它加上评测能力。评测层 harness-lab 通过适配器和 Mastra 解耦,换成别的框架怎么改见附录 A。
怎么读
- 先出结果:读完第 1、2 章,跳到第 5、7 章,把评测层接上、跑出第一个整体分。第 3、4 章的维度划分和统计方法,等看到置信区间、样本量这些概念时再回去补。
- 系统学习:从第 1 章顺读,跟着每章
examples/敲代码。后面的章节复用前面的适配器和任务集,顺读不用来回翻。 - 按问题查:手上有具体问题就直接翻对应章,第 1 章末尾有一张“问题—章节”对照表。章内引用前文的地方都标了章号。
配套代码与来源
每章的 examples/ 是可以独立运行的 TypeScript 工程,正文的关键代码都能在里面找到完整版本。引用 Mastra、Inspect AI、τ-bench 等开源项目时,正文标了源码文件路径。Mastra 迭代很快,遇到 API 对不上时以官方文档为准。
第 9–16 章有一部分方法(用 Shapley 值给模块分账、用 change manifest 驱动防劣化等)来自 2026 年的单篇 arXiv 预印本,多数结果是论文作者自报,还没有独立复现。正文里这类内容都标了出处和“前沿探索”,并尽量用最小代码验证过。来源和可信度汇总在附录 B。
勘误和建议可以在 GitHub 仓库 diguike/book-harness-evals 提 issue。
目录
- 01评 harness,而不是评模型8 分钟
- 02评测方法论术语地图11 分钟
- 03一个 harness 该评哪些维度11 分钟
- 04把评测当成统计实验10 分钟
- 05外挂评测层:harness-lab 与适配器10 分钟
- 06评测任务集的构建与防污染12 分钟
- 07harness 整体效果评测13 分钟
- 08OTAR 结构化因果 trace11 分钟
- 09消融实验与贡献不可加12 分钟
- 10Shapley 模块贡献分账12 分钟
- 11反事实根因定位12 分钟
- 12pass^k 与 flakiness 检测11 分钟
- 13人在回路评测与 Ask-F113 分钟
- 14前端与服务端的评测分野13 分钟
- 15线上持续评估:影子、A/B 与灰度12 分钟
- 16change manifest 与防劣化闭环13 分钟
- 17评测平台化与业务特化的边界15 分钟
- A更换 harness 载体10 分钟
- B前沿来源与诚实边界12 分钟