给完整的 Pi 建一套独立评测

#write-answer 从任务对象走到通过报告

第 13 章的 Runtime 已经拥有 Agent、session、context 和生命周期。最后一章把它当作 被评对象，不再修改产品核心。下面这一个 EvalCase 会贯穿全章：

EvalCase write-answer
  id      = "write-answer"
  prompt  = "write ok to answer.txt"
  files   = ["answer.txt"]
  prepare = 每次创建新的临时目录、Runtime 和 session
  judge   = 检查文件正文和最终 assistant

第一次调用 prepare() 得到 PreparedEval #1。它包含一个新的 Runtime、只读文件函数 和 cleanup；第二次运行同一个 case 时，prepare() 返回另一个 PreparedEval #2。 两次运行不共享目录、session 或 Runtime。

PreparedEval #1 的 Runtime 执行 prompt 后返回：

AgentRunResult
  reason   = stop
  steps    = 2
  messages = [
    user("write ok to answer.txt"),
    assistant(toolCall id="call-write", name="write_file"),
    toolResult(id="call-write", name="write_file", isError=false),
    assistant("done"),
  ]

同一轮的 session 还含一个 metadata root 和一条未选中的 sibling。活动 leaf 指向最终 assistant，因此 pathTo() 只返回下面这条祖先链：

meta → u1 → a-call → r-write → a-done
          └─ sibling                         不在 active path

runner 只读取 case 声明的 answer.txt，得到字符串 "ok"。随后交给 judge 的 EvalObservation 是：

observation.result   = 上面的 AgentRunResult
observation.entries  = [meta, u1, a-call, r-write, a-done]
observation.files    = { "answer.txt": "ok" }

这三个值已深复制并递归冻结。Judge 可以读取，不能改写 Runtime 返回值、session entry 或文件映射。write-answer 的 judge 返回：

{
  passed: true,
  checks: [
    observation.files["answer.txt"] === "ok",
    textOf(observation.result.messages.at(-1)!) === "done",
  ],
}

两个检查都为 true，runner 最后交出一份不含原始正文的报告：

{
  id: "write-answer",
  status: "passed",
  evidence: {
    messages: { user: 1, assistant: 2, toolResult: 1 },
    tools: { calls: 1, results: 1, errors: 0 },
    files: { requested: 1, read: 1 },
    checks: { passed: 2, failed: 0 },
  },
  secondaryFailures: [],
}

这条正向链包含本章所有对象：case 负责 setup，Runtime 完成任务，runner 收集可信事实， judge 判断任务条件，report 只留下可公开的分类和计数。

#Runner 每次重新调用 prepare()

EvalCase 只描述任务和判定入口：

interface EvalCase {
  id: string;
  prompt: string;
  files: readonly string[];
  prepare(): Awaitable<PreparedEval>;
  judge(observation: EvalObservation): Awaitable<TaskVerdict>;
}

interface PreparedEval {
  runtime: Runtime;
  readFile(file: string): Awaitable<string>;
  cleanup?(): Awaitable<void>;
}

setup 工作发生在 prepare() 内。write-answer 的实现约定第一次调用创建目录 1 和 Runtime 1，第二次调用创建目录 2 和 Runtime 2。runner 不缓存 PreparedEval；suite 即使 收到两次同一个 case 对象，也会再次调用 prepare()。

Runner 只能保证“重新调用”，无法判断返回的目录、session 和 Runtime 是否真是新的。 fresh environment 是 case 作者要履行的契约。示例 fixture 用不同 generation 证明 write-answer 履行了它：如果第二次仍返回第一次的目录，旧 answer.txt 会混入这次 判定，报告便不再只描述当前运行。

EvalCase.files 也是 setup 契约的一部分。Runner 不遍历目录，只调用：

for (const file of evalCase.files) {
  files[file] = await prepared.readFile(file);
}

因此 write-answer 的 judge 只能看到 answer.txt。临时目录中的日志、缓存和未声明文件 不进入 observation。

#Runtime 完成后，runner 只取活动路径

一次正常执行按固定顺序前进：

prepare
  → runtime.prompt(prompt)
  → runtime.flush()
  → runtime.session.entries()
  → runtime.getActiveLeafId()
  → pathTo(allEntries, leafId)
  → 工具协议与 result/session 深比较
  → 读取声明文件
  → judge
  → runtime.dispose()
  → prepared.cleanup()

flush() 明确等待 Runtime 已接受的工作。随后 runner 读取完整 session，但不会把整个树 交给 judge。它用第 10 章的 pathTo() 从活动 leaf 回到 root，未选 sibling 自然消失。 Runner 不复制一套 parent traversal，也不把物理最后一行当作活动 leaf。

Runtime 的返回 messages 与 session active path 是两条独立来源。runner 从活动路径中 取出 message entries，并与 result.messages 做深比较：

Runtime.prompt() result.messages
                  ╲
                   深相等
                  ╱
active path 中的 message entries

两边一致以后，文件和 task verdict 才有可信的运行背景。write-answer 的 metadata root 可以留在 observation.entries 中，但不参与 messages 比较。

#Observation 先复制，再递归冻结

EvalObservation 只有三个出口：

interface EvalObservation {
  readonly result: AgentRunResult;
  readonly entries: readonly SessionEntry[];
  readonly files: Readonly<Record<string, string>>;
}

TypeScript 的 readonly 不限制运行时对象。Object.freeze(observation) 也只冻结最外层。 目标实现先用 structuredClone() 切断与 Runtime、session 和 fixture 的引用，再递归访问 嵌套值并冻结。Judge 因此不能 push entry、改 tool arguments 或替换文件内容。

冻结发生在文件收集之后。任何文件读取返回非字符串，或 observation 无法结构化复制， runner 都不会调用 judge。正常 case 得到的 observation 则可以稳定重复判定。

#Judge 先得到可信轨迹，再判断任务条件

在 write-answer 中，runner 在调用 judge 前核对四类协议事实：

• active path 至少包含一条 user interaction；
• call-write 在 assistant 中只声明一次；
• toolResult 的 toolCallId 和 toolName 都与 call 相同，并且只出现一次；
• result messages 与持久化路径中的 messages 深相等。

Judge 不负责这些检查。它只判断 answer.txt 和最终 assistant 是否满足任务。返回值中的 passed 必须等于 checks.every(Boolean)。正常 verdict { passed: true, checks: [true, true] } 因而有效。

运行成功以后，finally 仍会先 runtime.dispose()，再调用可选的 prepared.cleanup()。Dispose 让 Runtime 完成关闭；cleanup 再删除 case 创建的临时 资源。若 prepare() 在交出 PreparedEval 前失败，runner 没有 cleanup 句柄，prepare 自身负责回滚已经创建到一半的资源。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 14.1" \
  packages/pi-course/dist/test/14-*.test.js

#Runner 捕获偏差时记录所在阶段

通过 case 已经说明 runner 正常时怎样工作。现在才需要给偏差命名。

表中的分类来自显式 catch 分支，不从 Error.message 猜测。进入这些分支后，报告只保存 固定 phase 和 code；异常正文、cause 与 stack 留在评测边界内。

当前 target 把 getActiveLeafId() 放在 collect catch 之前，作为 collect 阶段的前置读取。 它返回 null 时会生成 protocol/missing_active_leaf；它自己若抛异常，finally 仍会执行， 但 runEvalCase() 会把原异常 reject 给调用者。由代码位置可知，“固定 failure 不泄露正文” 这条契约从 collect catch 开始，不包含这个前置读取。

#合法拒绝和坏 judge 是两种结果

下面的 verdict 合法：

{ passed: false, checks: [true, false] }

它表示任务两项条件只通过一项，所以报告是 task_failed。下面的值则自相矛盾：

{ passed: true, checks: [true, false] }

checks 的合取为 false，passed 却为 true。Runner 把它归到 judge/invalid_verdict，不能让 Agent 承担判定器自己的错误。Judge 直接抛异常时，对应 judge/judge_failed。

#工具协议按活动路径顺序扫描

Runner 逐条读取 active path 中的 message entries。遇到 assistant tool call 时，它记录 call id、name 和是否已配对；遇到 result 时，它核对 id、name 与 matched 状态。

单纯比较 call/result 总数不够。下面四条消息最终各有一个 call 和 result，但仍不合法：

user
assistant(toolCall call-write)
assistant("continued before result")
toolResult(call-write)

第二条 assistant 到达时，前一条 call 还没有 result。Runner 当场返回 protocol/unpaired_tool_call，不允许跨 assistant 补交。重复 call、孤立 result、重复 result、toolName 错配和结尾未配对都有各自固定 code。

扫描结束后，runner 再比较 active messages 与 Runtime result。工具协议完整但两份 transcript 不同，会得到 protocol/result_session_mismatch。Judge 不会看到这组互相冲突 的事实。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 14.2" \
  packages/pi-course/dist/test/14-*.test.js

#SafeEvidence 从事实中计数，不转述事实

write-answer 的通过报告已经展示了 SafeEvidence。计数来源如下：

报告不包含 transcript、prompt、文件名、文件正文、临时路径、callId、tool arguments 或异常 文字。Runner 不会把 observation 放进报告，但 judge 已经拿到完整内容，也可以把它保存到 闭包、日志或外部系统。因此 judge 属于受信任的评测代码；递归 freeze 只阻止它改写本次 事实，并不提供数据隔离。调试正文留在受控本地环境，公共 EvalReport 仍维持这组固定 字段。

EvalReport.id 会公开，因此 case 作者也应把它当作普通标签，不能把 secret 或绝对路径 编码进 id。

#清理故障追加在最早结果之后

假设 write-answer 的 judge 合法拒绝任务，随后 dispose 和 cleanup 都抛错。报告保留最 早得到的 task 事实：

{
  status: "task_failed",
  primaryFailure: { phase: "task", code: "task_rejected" },
  secondaryFailures: [
    { phase: "dispose", code: "dispose_failed" },
    { phase: "cleanup", code: "cleanup_failed" },
  ],
}

生命周期故障不能覆盖已有 primary。若主流程原本通过，dispose_failed 才成为 primary， 后到的 cleanup_failed 成为 secondary，status 改为 infra_failed。数组顺序就是实际 发生顺序。

这个规则依赖 report 在 try/finally 之间保持同一对象引用。主流程即使提前 return， finally 仍能追加 dispose 和 cleanup 结果，然后 Promise 才把最终 report 交给调用者。

#Suite 等一个 case 完整收口再开始下一个

runEvalSuite() 使用普通 for...of：

const reports: EvalReport[] = [];
for (const evalCase of cases) {
  reports.push(await runEvalCase(evalCase));
}
return reports;

输入 [alpha, beta, alpha] 产生同顺序的三份报告。第一个 alpha 完成 cleanup 后，beta 才 prepare；最后一个 alpha 再次调用 prepare，示例 case 随之创建新环境。这里观察的是执行 顺序与 case 的隔离契约，并不测量并发吞吐。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 14.3" \
  packages/pi-course/dist/test/14-*.test.js
node --test packages/pi-course/dist/test/14-*.test.js

#移除 transcript 交叉验证会制造假通过

正常链和三段实现已经完成，可以做一次定向故障注入。临时跳过：

if (!isDeepStrictEqual(activeMessages, result.messages)) {
  // protocol/result_session_mismatch
}

然后只运行：

node --test \
  --test-name-pattern="active path 拒绝不一致 transcript" \
  packages/pi-course/dist/test/14-*.test.js

测试中的 session 路径满足工具协议，Runtime 返回值却替换了最终 assistant。少了深比较， runner 会继续读文件并调用 judge，测试因此变红。

#公开测试与真正的 held-out 检查

practice 目录只注入 14-eval-capstone.test.ts 的 9 项公开测试。官方 target 还保存 3 项 capstone-held-out.test.ts 回归，用新的实例检查同一套公开协议。它们在 reference target 上通过，证明 target 的实现满足这些回归；运行 reference target 不能证明你在 practice 目录写出的实现也通过。

针对学习者实现的 held-out 检查需要保持两个条件：测试实例在实现冻结后才产生，且测试 运行的正是那份冻结实现。只记录 eval.ts 的 hash 还不够，因为实际执行的是编译后的 JavaScript，tsconfig、导入的 src/**、依赖锁和旧 dist 都会改变结果。可以把下面的 迁移交给另一名 reviewer 或 Agent。

#9 项公开测试固定到哪里

公开测试固定了：每次重新 prepare；prompt、flush、dispose、cleanup 的顺序；active path 和声明文件的观察范围；深复制与冻结；execute/collect 分层；verdict 校验；工具协议； result/session 一致性；固定 failure；SafeEvidence；primary/secondary；串行 suite。

这九项证据也给 runner 划出三个范围：

• 它是进程内、受信任的评测 harness。Freeze 防止 judge 改写 observation，report 过滤原始 内容；两者都不隔离 judge 的读取与外传，也不把任意远程 benchmark 变成安全输入。
• Runner 重新调用 prepare，并检查公开测试里的协议组合。真正的新目录、session 与 Runtime 由 case 提供；getActiveLeafId() 抛错目前还会越过固定 failure 报告。
• 串行 suite 和 SafeEvidence 服务于可重复的正确性判断，不是性能基准或完整根因日志。 Reference target 的 held-out 结果也只描述 target，学习者实现要走前面的冻结快照流程。

target 的 3 项 held-out 加上公开测试得到 Chapter 14 12/12，目标提交的课程全量是 120/120。这些数字是固定 reference snapshot 的回归证据。

#本章验收

npm run build -w @pi/course
node --test packages/pi-course/dist/test/14-*.test.js

#小结

write-answer 每次从新的 PreparedEval 开始。Runner 调用 Runtime，读取活动路径和 声明文件，把深复制且冻结的 observation 交给 judge；合法 passing verdict 最后变成只含 固定计数的报告。

协议错误、任务拒绝和评测设施故障拥有不同 status。最早失败保持 primary，dispose 与 cleanup 只按发生顺序追加。runEvalSuite() 等一个 case 完整收口后再开始下一个。

这套 runner 没有进入产品核心。它站在第 13 章 Runtime 外面，用另一套代码检查运行结果 是否可信，也让整本教材最终拥有可重复的整机证据。