Skip to Content

第 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 的关系

图 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-accuracy scorer 按预期的动作序列给一次运行的轨迹打分,覆盖工具调用、模型调用和 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 结构化因果 trace8
哪个模块在拖后腿、值不值得留消融实验与 Shapley 归因9–10
这次失败的病灶是哪一步反事实根因定位11
同样输入为什么时好时坏pass^k 与 flakiness12
该不该打断 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。