第 1 章
评 harness,而不是评模型
本章概览
本章确定全书的评测对象:评一个 agent,评的是模型和包在它外面的 harness 组成的端到端系统。对象定错了,后面选的指标和方法都会跟着错。
本章先拆一个故障,再对照 Mastra 源码看 harness 由哪些部分组成,然后介绍贯穿全书的例子,最后看框架自带的评测能做到哪一步、本书要补上哪些。
一句 instructions 引出的故障
设想你在维护一个 DevOps 值班助手:它能查日志、查监控,确认无误后改配置,遇到拿不准的高危操作就升级给人类 oncall。为了让它改配置前更谨慎,你在 instructions 里加了一句:执行任何写操作前,先复述将要改动的字段。离线评测集 50 条任务全部通过,总分还略有上升,你合并、发布。当晚,它把一条本该升级给人的生产配置变更直接执行了。
复盘链路如图 1-1 所示。新加的指令让模型在调用写工具前多输出了一句“我将把 timeout 从 30s 改成 60s”。下游负责判断“要不要升级给人”的步骤并不理解语义,只看几条启发式信号,其中一条是“对话里是否出现了明确的确认措辞”。模型的复述命中了这条信号,于是该步骤判定已经确认过,跳过升级,放行了写操作。
图 1-1:只改一句 instructions 引发的故障时序。每一跳单看都合理,缺陷出在模型的复述文本流入升级判断步骤的那一跳。
这条链路里没有哪一环是模型答错了:模型照新指令复述了字段,措辞也合理。出问题的是三样东西的耦合:新加的 instructions、它引出的那段输出、下游按措辞做判断的升级逻辑。三样都在模型外面。
离线评测没拦住它,是因为那套评测逐条检查“模型这一步答得对不对”,而这次故障不属于任何单独一步。这相当于用一把只量零件的尺子去验收装配线,每个零件都合格,装上线却出了问题。
harness:模型外面的四类代码
模型只做一件事:给定上下文,预测接下来的 token。模型每一步能看到什么、能调用什么、下一步往哪走、哪些动作会被拦下,都由模型外面的代码决定。这些代码按职责分四类:
- 指令与上下文:system prompt 和 instructions、
AGENTS.md这类指令文件、skill、对话历史和长期记忆,以及上下文快满时的压缩策略。它们决定模型每一步看到什么。图 1-1 那句“先复述”就加在这一层。 - 工具与执行环境:agent 能调用的工具和 MCP server,每个工具的入参、出参和副作用,以及工具运行的文件系统和沙箱。哪些只读、哪些是破坏性写操作,在这一层划定。
- 编排与工作流:调哪个子 agent、步骤按什么顺序走、在什么条件下分支或终止、中断后状态怎么持久化、恢复时从哪一步接上。值班助手“先查日志、再查监控、确认后才动手”的顺序由这一层决定。
- 约束与反馈:审批门、guardrail、hooks、重试,以及记录每一步的 trace、日志和成本。图 1-1 里那个“要不要升级给人”的判断属于这一层。
这四类合起来,就是本书说的 harness。图 1-2 画出了它们和模型的关系。图 1-1 的故障跨了两层:改动发生在指令与上下文,后果出现在约束与反馈。只盯着其中一层的评测,两头都发现不了它。

图 1-2:harness 的四类部件与 model 的关系。方框里的路径相对 Mastra 仓库的
packages/core/src/。红色虚线标出图 1-1 那次故障跨越的两层。
由此得出全书反复回到的立论:
评测“一个 agent”,评的是 harness 和 model 一起工作的端到端系统。
这句话来自 Anthropic 工程博客 Demystifying evals for AI agents。本书把它当作评测对象的定义:要评的是整个系统在真实任务上的行为,不是模型在某个 benchmark 上的分数。
harness 的两种用法
读本书和 Mastra 文档时,会碰到 harness 的两种用法:
| 用法 | 指什么 | 本书在哪里用 |
|---|---|---|
| 行业用法(Anthropic 等) | 模型以外的全部代码,即上面四类 | 全书默认含义 |
| Mastra 的用法 | 让 agent 跨越单次运行继续工作的一组能力:Durable Agents、后台任务、Goals、Schedules、Signals、AgentController | 讲 Mastra API 时 |
Mastra 的用法是行业用法的一个子集,其中托管会话、模式和审批的核心类是 AgentController,源码在 packages/core/src/agent-controller/。本书讲概念时用行业用法,写代码时跟随 Mastra 仓库的命名。
为什么用 Mastra
Mastra 是 TypeScript 的开源 agent 框架,GitHub 近 3 万 star(截至 2026 年 10 月)。本书用它做贯穿载体,原因有两个:
- 它和多数应用工程师的技术栈一致;
- 四类部件在源码里各有目录,图 1-2 的方框里标出了对应文件。
举一个例子。“停下来问人”在 Mastra 里由内建工具 askUserTool 提供(packages/core/src/tools/builtin/ask-user.ts)。什么时候触发,由这个工具和调用它的工作流决定,模型本身决定不了。第 13 章评人在回路,评的就是这一块。
模型分高不等于系统可靠
把模型换成更强的,系统未必变好,原因在 harness。
设想两个团队用同一个模型搭值班助手。A 团队让所有改配置的工具调用先挂起,等人批准再继续(在 Mastra 里可以给工具设 requireApproval,或者把写操作放进能 suspend() 的 workflow step)。B 团队图省事,把“要不要升级”交给模型在 prompt 里自己判断。同样的任务,A 的系统在高危操作上稳定,B 的系统时不时自作主张。两边的模型一个字没改,差别全在 harness。
反过来,把 B 团队的模型换成更强、更敢自己拿主意的版本,它在高危操作上可能更危险,因为 B 的 harness 里没有一步拦得住它。模型 benchmark 测的是模型的通用能力,值班助手可不可靠,取决于 harness 怎样约束、引导和兜底这个模型。
公开 benchmark 也开始承认这一点。Terminal-Bench 2.0 的排行榜同时列出“模型”和“agent”两列,按两者的组合排名,同一个模型配不同的 agent harness 会作为不同条目出现。
贯穿全书的例子:DevOps 值班助手
后面各章改造的都是同一个 harness:用 Mastra 搭的 DevOps 值班助手。这个场景能撑起本书的三条主线:
- 查日志、查监控这类只读任务安全、可重复,能攒成任务集批量回放,第 7 章评整体效果用它;
- 改生产配置、升级 oncall 这类高危写操作必须等人批准,是第 13 章人在回路评测的素材;
- 值班助手既能在服务端批量运行,也能挂一个浏览器操作面板,第 14 章用它对比两种形态的评法。
它的雏形如下,完整版本(还包括高危写工具 patchConfig)在本章 examples/src/oncall-agent.ts:
import { Agent } from '@mastra/core/agent';
import { createTool } from '@mastra/core/tools';
import { z } from 'zod';
// 只读工具:查日志。这类工具安全,可以放手让 agent 自己调
const queryLogs = createTool({
id: 'query-logs',
description: '按服务名和时间范围查询最近的错误日志',
inputSchema: z.object({
service: z.string(),
minutes: z.number().default(15),
}),
outputSchema: z.object({ lines: z.array(z.string()) }),
execute: async ({ service, minutes }) => {
// 真实实现对接你的日志系统,这里返回桩数据
return { lines: [`[${service}] 最近 ${minutes} 分钟无 ERROR`] };
},
});
export const oncallAgent = new Agent({
id: 'oncall-agent',
name: 'DevOps 值班助手',
instructions: '你是值班助手。查询类操作可自主执行;任何改配置、重启服务的写操作,必须先升级给人类确认。',
model: 'openai/gpt-4.1', // 换成你实际在用的模型 id
tools: { queryLogs },
});这段代码里属于模型的只有 model 一行。工具清单、instructions 里对写操作的约束,都属于 harness。本章用的是最基础的 Agent;需要多步编排和人工审批时,后续章节会改用 workflow(createWorkflow / createStep)。不管换成哪种写法,model 以外的部分都是本书要评测和改造的对象。
id 是必填字段,漏写会在 TypeScript 严格模式下报类型错误。
框架自带的评测能做到哪一步
Mastra 的评测模块是 @mastra/evals,核心概念是 scorer。有一类内建 scorer 在 packages/evals/src/scorers/llm/ 下,如 answer-relevancy、faithfulness、hallucination、bias,形状都一样:给一条输入和一条输出,打一个 0 到 1 的分。
// 摘自 Mastra answer-relevancy scorer 的真实结构(已简化)
createScorer({
id: 'answer-relevancy-scorer',
name: 'Answer Relevancy Scorer',
description: '评估一条 LLM 输出与输入的相关性',
judge: { model, instructions: ANSWER_RELEVANCY_AGENT_INSTRUCTIONS },
type: 'agent',
})
.preprocess(/* 从输出里抽取陈述 */)
.analyze(/* 给每条陈述打相关性分,聚合成 0-1 */);这类 scorer 评的是单条输出:回答相不相关、是否忠于上下文、有没有编造。图 1-1 那次故障里每条输出都没问题,它们发现不了。
Mastra 的评测也能覆盖运行轨迹这一层:
trajectory-accuracyscorer 按预期的动作序列给一次运行的轨迹打分,覆盖工具调用、模型调用和 workflow 步骤;- Quick Checks(
checks.calledTool、checks.didNotCall、checks.toolOrder等)不调用 LLM,直接断言某个工具有没有被调、调用顺序对不对; - 多轮评测在同一条记忆线程上依次发送多轮输入,可以对某一轮或整段对话打分;
runEvals的 gates 和 thresholds 把“必须满足的条件”和“跟踪的指标”分开,输出passed/scored/failed三档结论,可以直接接进 CI;- experiments 在数据集上批量运行 agent 或 workflow 并保存结果,用来对比不同 prompt、模型和代码版本。
有了这些,图 1-1 那类故障可以写成一条 gate:在“应当升级”的任务上,断言写配置的工具没有被直接调用。
这些能力回答的都是“这一次运行对不对”。下面几类问题,要在打分之上再做实验设计和统计,框架没有现成答案:
- 同样的任务跑十次,结果稳不稳定(
runEvals每条数据只运行一次,没有内建的重复采样和 pass^k 统计); - 一个十几步的任务里,agent 该不该在第七步停下来问人,又有多少次提问是多余的;
- 失败的病灶在哪一步,哪个模块在拖后腿、值不值得保留;
- 改了一版之后,整体分的下降是噪声还是真的退化。
第 7 章会把 Mastra 的 scorer 接进评测层,当作打分组件之一;本书其余的篇幅,处理的是上面这几类问题。
全书要装的评测能力
后面各章会给值班助手依次装上下面这些能力:
| 你想回答的问题 | 装什么 | 在第几章 |
|---|---|---|
| 这套 harness 整体到底行不行 | 并发回放 + 状态基评分 + 聚合 | 7 |
| 出问题了是哪一步、为什么 | OTAR 结构化因果 trace | 8 |
| 哪个模块在拖后腿、值不值得留 | 消融实验与 Shapley 归因 | 9–10 |
| 这次失败的病灶是哪一步 | 反事实根因定位 | 11 |
| 同样输入为什么时好时坏 | pass^k 与 flakiness | 12 |
| 该不该打断 agent 问人 | Ask-F1 与 HITL 评测 | 13 |
| 前端形态和服务端评法差在哪 | 在线/离线双轨 | 14 |
| 上线后怎么持续盯着、灰度放量 | 影子 / A-B / 灰度 | 15 |
| 改完怎么确认没退化、真变好 | change manifest 防劣化闭环 | 16 |
在这之前,第 2 到第 4 章先讲后面反复用到的术语(消融实验、确定性评测、贡献度归因、pass^k 等),以及为什么评测分数要按统计实验来解读。
小结
- 评“一个 agent”,评的是 harness 和 model 一起工作的端到端系统,模型只是其中一小块。
- harness 是模型外面的四类代码:指令与上下文、工具与执行环境、编排与工作流、约束与反馈。Mastra 文档里的 harness 范围更窄,指让 agent 跨越单次运行的那组能力,核心类是
AgentController。 - 同一个模型配不同的 harness,端到端结果可以差很远,模型 benchmark 分高不代表系统可靠。
- 框架自带的评测已经能检查单次运行的输出和轨迹;稳定性、模块归因、根因定位、该不该问人、是否退化,是本书要补上的部分。
配套代码
本章 examples/ 下有两个脚本:
npm run boundary:把值班助手拆开打印,区分哪些是 model、哪些是 harness。不调用模型,不需要 API key。npm run scorer:跑 Mastra 自带的 answer-relevancy scorer,看它的输入只有一问一答。scorer 内部用 LLM 当 judge,需要配置模型 API key。