《Agent Runtime 工程化》第十章 Eval Harness 与 CI 回归

Golden task 是一组有代表性的任务。对 coding agent 来说，至少要覆盖：

• 文件阅读任务；
• 代码搜索任务；
• 单文件编辑任务；
• 多文件编辑任务；
• 测试修复任务；
• 权限拒绝任务；
• 工具失败恢复任务；
• 上下文压缩任务；
• checkpoint/resume 任务；
• MCP 工具不可用任务。

每个 task 至少包含：

{
  "id": "edit-bigint-001",
  "title": "add 支持 BigInt",
  "prompt": "把 src/math.ts 的 add 改成支持 BigInt，并补测试。",
  "workspaceFixture": "fixtures/math-lib",
  "policy": "interactive_mock",
  "model": "scripted",
  "expected": {
    "filesChanged": ["src/math.ts", "test/math.test.ts"],
    "commandsPass": ["npm test"],
    "mustNotCall": ["run_command:rm", "run_command:curl"],
    "maxSteps": 12,
    "maxEstimatedUsd": 0.2
  }
}

不要只测最终文本答案。Agent Runtime 的关键行为是路径、工具、权限、文件变更和恢复。一个 Agent 可以写出看似漂亮的总结，但从未运行测试；也可以完成测试，却用了危险命令。Eval 要把这些都看见。

10.3 Fixture 要可复原

Eval 的第一原则是可重复。每个任务都应在干净 workspace fixture 中运行。

建议目录：

evals/
  tasks/
    edit-bigint-001.json
  fixtures/
    math-lib/
      package.json
      src/math.ts
      test/math.test.ts
  expected/
    edit-bigint-001.snapshot.json
  reports/
    2026-08-14-smoke.html

运行前复制 fixture 到临时目录，运行后收集 diff、命令结果、trace 和成本报告。不要直接在 fixture 原地执行，否则一次失败 eval 会污染下一次结果。

工作区复原可以用三种方式：

初学阶段用目录复制即可。产品化后，再把依赖缓存、git worktree 和容器隔离纳入执行器。

10.4 Deterministic mock model

真实模型有随机性、网络波动和供应商变化。Eval 必须分两层。

第一层用 deterministic mock model 测 runtime 逻辑。它按照脚本返回固定 tool calls，用来验证 schema 校验、权限、checkpoint、trace、停止条件。

第二层用真实模型测端到端能力。它更接近用户体验，但结果会有波动，需要统计和人工抽查。

mock model 示例：

type ScriptedModelStep =
  | { type: "message"; content: string }
  | { type: "tool_call"; name: string; args: unknown; id: string };

class ScriptedModel implements ModelProvider {
  constructor(private steps: ScriptedModelStep[][]) {}

  async *generate(): AsyncGenerator<ModelEvent> {
    const next = this.steps.shift();
    if (!next) throw new Error("No scripted response");

    for (const item of next) {
      if (item.type === "message") {
        yield { type: "text_delta", text: item.content };
      } else {
        yield {
          type: "tool_call",
          toolCallId: item.id,
          name: item.name,
          args: item.args,
        };
      }
    }
  }
}

如果没有 mock model，你很难判断一次 eval 失败是模型变了，还是 runtime 改坏了。Runtime 的核心不应被真实模型随机性绑架。

10.5 行为断言优先于字面匹配

Agent 输出有自然语言，字面匹配很脆。更好的断言是行为断言。

示例：

type EvalAssertion =
  | { kind: "file_changed"; path: string }
  | { kind: "file_unchanged"; path: string }
  | { kind: "command_passed"; command: string }
  | { kind: "must_not_call"; tool: string; pattern?: string }
  | { kind: "trace_has_span"; name: string }
  | { kind: "cost_under"; estimatedUsd: number }
  | { kind: "max_steps"; count: number };

对代码编辑任务，最终标准仍应落到测试、静态检查或 snapshot 上。自然语言 judge 可以辅助评价解释质量，但不要让它成为唯一门禁。

10.6 从 trace 生成 replay

一次线上失败，如果不能转化为 eval，它就会再次发生。建议流程：

1. 从 trace 中提取用户目标、关键上下文、工具调用和失败结果；
2. 去除 secret、用户隐私和客户专有内容；
3. 固化 workspace fixture；
4. 写 expected behavior；
5. 加入 CI；
6. 修复 runtime；
7. 证明 eval 通过。

Trace 到 eval 的转换不必一开始全自动。半自动工具已经很有价值：生成 eval 草稿，让工程师审阅。

Replay 也分两类。

如果失败来自上下文构建，优先 replay context.build。如果失败来自权限绕过，优先 replay permission span。不要把所有问题都压到端到端大模型评测上，那样又慢又难定位。

10.7 指标：不要只看成功率

成功率重要，但不够。还要看：

• 平均 step 数；
• 平均 tool call 数；
• 平均 token；
• 平均耗时；
• 权限请求次数；
• 用户拒绝后是否停止；
• 相同错误重复次数；
• 输出是否引用证据；
• 文件 diff 是否最小；
• 回滚是否成功；
• 估算成本；
• 输出截断次数。

一个 runtime 策略可能成功率略高，但成本翻倍、工具调用翻倍、危险审批增加。这不一定是好策略。

报告里建议用三组指标：

真正的产品决策通常发生在这三组指标之间。比如'通过率提升 2%，成本增加 80%，危险工具审批增加 4 倍'，这不是一个可以轻易发布的改动。

10.8 Flaky eval 的处理

Agent eval 天生有波动。处理 flaky 的方法：

• runtime 单元测试使用 mock model；
• 真实模型 eval 多跑几次取统计；
• 用行为断言代替字面匹配；
• 把'必须不发生'的危险行为单独作为硬门禁；
• 把人工 judge 与程序化断言分开；
• 对不稳定 case 标记 quarantine，但不能永久忽略；
• 报告中保留每次 run 的 traceId，方便回看。

Quarantine 不是垃圾桶。每个 quarantine case 都要有 owner、原因和复查日期。否则 eval 套件会慢慢变成'失败但大家假装没看见'的仓库。

10.9 CI 分层

CI 里建议分层：

一个实用命令可以长这样：

agent-eval run \
  --suite replay \
  --model scripted \
  --report build/evals/replay.html \
  --fail-on safety,regression

CI 输出不应只有'失败'。至少要列出失败 task、第一条错误 span、失败归因、相关 diff、artifact 链接和重跑命令。

10.10 Prompt A/B 与 runtime 策略对比

Eval 不只是测模型，也测 runtime 策略。例如：

• maxSteps=10 vs maxSteps=20；
• 工具描述短版 vs 长版；
• 旧历史保留 4 轮 vs 8 轮；
• 搜索结果返回 20 条 vs 50 条；
• 写入前是否强制计划；
• 工具失败后是否允许自动重试；
• context compression 阈值 70% vs 85%；
• MCP 工具按全量暴露 vs 按任务筛选。

每次对比只改一个关键变量。否则你不知道提升来自哪里。

A/B 报告建议包含：

{
  "experiment": "context-tail-4-vs-8",
  "baseline": "tail4",
  "candidate": "tail8",
  "tasks": 60,
  "baselinePassRate": 0.78,
  "candidatePassRate": 0.82,
  "costDeltaPct": 21.4,
  "latencyDeltaPct": 18.9,
  "safetyRegressions": 0,
  "decision": "manual_review"
}

不要让'更聪明'这种词进入发布结论。发布结论要写数据：通过率、成本、延迟、安全回归、失败样本。

10.11 Judge 的使用边界

LLM-as-judge 可以用，但要小心。它适合评价解释是否清楚、摘要是否覆盖证据、最终回答是否引用了相关文件；不适合替代测试命令、权限策略和 secret 扫描。

建议把 judge 输出作为软指标：

Judge 也要有版本。prompt、模型、温度、评分 rubric 改了，历史分数就不能直接比较。

10.12 成本治理进入 eval

Agent Runtime 的成本不是只有模型 token。还包括：

• 模型输入输出 token；
• 工具调用时间；
• 外部 API 费用；
• 浏览器或容器资源；
• 重试成本；
• 长上下文导致的延迟；
• 人工审批等待成本。

Eval 报告中至少记录估算模型成本、总耗时、平均 step 和 p95 latency。成本门禁可以先从简单阈值开始：

{
  "costPolicy": {
    "maxEstimatedUsdPerTask": 0.25,
    "maxStepsPerTask": 20,
    "maxToolCallsPerTask": 40,
    "maxP95LatencyMs": 120000
  }
}

成本门禁不是为了让 Agent 变得吝啬，而是为了防止 runtime 策略无意中把一次简单任务拖成昂贵长跑。

10.13 动手任务

建立 evals/ 目录：

• 10 个文件编辑任务；
• 10 个工具调用任务；
• 10 个失败恢复任务；
• 每个任务有 fixture、prompt、expected、policy；
• CI 中运行 mock replay；
• safety suite 每次提交必跑；
• 成功率低于阈值则失败；
• 输出报告包含成功率、平均 step、平均 token、估算成本、失败类型；
• 从第九章的一条失败 trace 生成 replay case。

建议先实现三个命令：

agent-eval init
agent-eval run --suite replay
agent-eval report --input .agent/eval-runs/latest.json

10.14 验收标准

完成本章后，你应该能做到：

• 不再靠感觉判断 Agent 是否变好；
• 能比较两个 prompt 或两个 runtime 策略；
• 一次线上失败能进入回归集；
• 危险行为有硬门禁；
• 失败报告能定位到 trace span；
• 成本、延迟和安全边界能进入发布判断。

到这里，Agent Runtime 才有了团队协作所需的反馈机制：改动可以被验证，失败可以被复现，质量可以被持续维护。

系列文章目录

• 《Agent Runtime 工程化》完整目录
• 《Agent Runtime 工程化》第一章 Agent Runtime 全景
• 《Agent Runtime 工程化》第二章 TypeScript / Node Runtime 基础
• 《Agent Runtime 工程化》第三章 最小 Agent Loop
• 《Agent Runtime 工程化》第四章 工具系统设计
• 《Agent Runtime 工程化》第五章 上下文工程
• 《Agent Runtime 工程化》第六章 MCP 与 Provider 抽象
• 《Agent Runtime 工程化》第七章 权限与安全边界
• 《Agent Runtime 工程化》第八章 Checkpoint、Resume、Rollback
• 《Agent Runtime 工程化》第九章 可观测与 Trace
• 《Agent Runtime 工程化》第十章 Eval Harness 与 CI 回归
• 《Agent Runtime 工程化》第十一章 Agent Runtime 进阶学习路线
• 《Agent Runtime 工程化》第十二章 hermes-agent 产品级实战
• 《Agent Runtime 工程化》附录