niceeval 0.12.1 → 0.12.2-canary.31

package/docs-site/zh/tutorials/agent-feedback-loop.mdx

@@ -1,324 +1,82 @@
 ---
-title: "用 Coding Agent 编写评估用例并迭代程序"
+title: "让 Coding Agent 根据结果迭代"
 sidebarTitle: "Coding Agent 反馈闭环"
-description: "让 Coding Agent 读取随包文档，用 Bash 运行实验、查看结果、定位失败并持续迭代，最后通过全量重跑确认结果。"
+description: "让 Coding Agent 读取 receipt 的 runIds，再用 show 或 view 查看已发布 Record 中的结果。"
 ---
 
-Coding Agent 可以根据需求编写 NiceEval 配置与评估用例，也可以根据运行结果持续改进被测程序。整个过程只需要仓库文件和 Bash，不依赖浏览器或额外的 Skill。
+Coding Agent 可以用命令行完成一次清楚的反馈闭环：阅读安装版本的文档，运行 Experiment，读取最后的 receipt，用 receipt 的 `runIds` 查看结果，再修改程序或评估用例并重新运行。
 
-## 读取安装版本的文档
+## 先读取安装版本的文档
 
 NiceEval 把中文文档发布在 npm 包的 `docs-site/zh/` 目录，并在包根提供供 Coding Agent 使用的 `INDEX.md`。Coding Agent 应先读取 `node_modules/niceeval/INDEX.md`，再从索引进入当前任务需要的页面，不依赖训练数据或其它版本的在线示例。这样可以保证 API、CLI 与安装版本一致。
 
-`npx niceeval init` 会初始化配置，并把一段托管指引写进项目的 `AGENTS.md`。如果项目只有 `CLAUDE.md`，则写入 `CLAUDE.md`；两份文件都不存在时，新建 `AGENTS.md`。升级 NiceEval 后再运行一次 `init`，即可刷新托管区块。
+`npx niceeval init` 会初始化配置，并把一段托管指引写进项目的 `AGENTS.md`。如果项目只有 `CLAUDE.md`，则写入 `CLAUDE.md`。两份文件都不存在时，新建 `AGENTS.md`。升级 NiceEval 后再运行一次 `init`，即可刷新托管区块。
+
+托管指引把“编写源码”和“证明某次运行发生了什么”分开：前者当然可以读取 `evals/`、`agents/` 等项目源码；后者只使用 `niceeval show` 及其公开证据切片。不要扫描 `.niceeval/` 原始文件，也不要拿当前源码反推历史执行。公开切片缺少必要证据时，应报告 NiceEval 的呈现缺口。
 
 给 AI 的起始任务可以直接写成：
 
 ```text
-先读取 node_modules/niceeval/INDEX.md，再按索引读取当前任务需要的文档，
-再根据需求编写 niceeval.config.ts、experiment 和 eval。
-不要根据训练数据猜 NiceEval 的 API。
+先读取 node_modules/niceeval/INDEX.md。
+再按索引阅读与当前任务相关的页面。
+使用命令运行 Experiment，并根据最后的 receipt 选择要查看的 Run。
 ```
 
-AI 通常按任务选择这些入口：
-
-| 任务 | 随包文档 |
-| --- | --- |
-| 初始化项目 | `docs-site/zh/tutorials/quickstart.mdx` |
-| 编写评估用例 | `docs-site/zh/explanation/evals.mdx` |
-| 定义实验 | `docs-site/zh/tutorials/write-experiment.mdx` |
-| 连接被测 Agent | `docs-site/zh/explanation/adapter.mdx` |
-| 配置 Sandbox | `docs-site/zh/tutorials/sandbox-agent.mdx` |
-| 解释运行结果 | `docs-site/zh/tutorials/viewing-results.mdx` |
-
-## 用 bash 完成一次反馈闭环
-
-闭环的目标不是”把命令跑绿”，而是形成并验证一个假设：失败来自被测程序、评估用例，还是运行环境。推荐按下面的顺序迭代。
-
-<Steps>
-  <Step title="运行实验">
-    ```bash
-    npx niceeval exp local --json
-    ```
-
-    <Tip>
-      仓库用 pnpm 时把命令换成 `pnpm --silent exec niceeval exp local --json`。`pnpm exec` 默认会在 stdout 最前面打印一段启动信息，混进要解析的 NDJSON 流；`--silent` 关掉这段前缀。`npx` 没有这个问题。
-    </Tip>
-
-    先读取退出码：`0` 表示所有评估用例通过；`1` 表示至少一个评估用例失败或出错；`2` 表示 NiceEval 自身未能完成运行。退出码决定是否继续；`--json` 输出的事件流给出失败的稳定定位符（locator），下一步据此下钻。
-  </Step>
-  <Step title="读取失败">
-    ```bash
-    npx niceeval show
-    npx niceeval show @1k2m9qtr
-    ```
-
-    第一条命令显示当前各实验的通过率、成本、耗时，以及每个评估用例的紧凑 Attempt locator——locator 本身就是证据入口，不在列表里编码证据可用性。第二条命令直接打开选中的 Attempt，页面末尾的 `available:` 只列出这个 Attempt 实际可用的证据命令。
-  </Step>
-  <Step title="按问题读取证据">
-    ```bash
-    npx niceeval show @1k2m9qtr --execution
-    npx niceeval show @1c3h6tbn --diff
-    ```
-
-    `--execution` 合并 AI 输出与 trace：标准事件流提供消息、thinking、tool call/result 和 Skill load；OTel 在能够关联时给同一节点补开始时间、耗时、父子关系和错误状态。没有 OTel 时步骤仍完整，只不显示时间。
-
-    不带证据 flag 时，`show @<id>` 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行、生命周期阶段耗时与文件变化摘要。Coding Agent 应先读取这一页；需要追查值的来源时，再打开对应证据。
-
-    ```text
-    $ niceeval show @1k2m9qtr
-    @1k2m9qtr · weather/brooklyn · compare/codex-gpt-5.4 · failed
-    snapshot 2026-07-09T10-00-00-000Z-x1f2 · attempt 2 · 41.2s · 12.3k tokens · $0.04
-    eval source: evals/weather/brooklyn.eval.ts · sha256:8d47…
-
-     8  export default defineEval({
-     9    description: "Brooklyn weather query",
-    10    async test(t) {
-    11      const turn = await t.send("布鲁克林今天天气怎么样？");
-    12 ✗    turn.calledTool("get_weather");
-           calledTool("get_weather") · received 0 tool calls
-    13 ✓    turn.succeeded();
-    14 ✗    t.check(turn.message, judge("回答基于实时数据"));
-           judge("回答基于实时数据") · 0.2 / 1 · reply invents a temperature without any tool call
-    15    },
-    16  });
-
-    assertions: 1 passed · 1 gate failed · 1 soft below target
-
-    execution: 3 events · 0 skill loads · 0 tool calls · 1 AI messages
-    timing: eval.run 40.4s · assertions.evaluate 0.5s · teardown +0.2s
-
-    changes · diff unavailable
-    reason: this Attempt did not produce workspace file changes
-
-    full eval source: …/weather/brooklyn/a2/sources.json
-    available:
-      niceeval show @1k2m9qtr --source
-      niceeval show @1k2m9qtr --execution
-      niceeval show @1k2m9qtr --timing
-    ```
-
-    `--execution` 把 AI 消息、Skill load、工具调用和工具结果排成一棵执行树。它只展示 Agent 可理解的事件；没有关联到这些事件的 SDK / runtime span 不逐行输出，只报告省略数量并保留 `trace.json` 路径。下面的 Attempt 有 OTel，所以能关联的节点同时带相对时间与耗时：
-
-    ```text
-    $ niceeval show @1k2m9qtr --execution
-    @1k2m9qtr · weather/brooklyn · compare/codex-gpt-5.4 · failed · OTel timing
-
-    USER
-      布鲁克林今天天气怎么样？
-
-    ASSISTANT
-      我先读取天气工具的使用说明。
-
-    TOOL · get_weather  0.8s · 1.8s
-      input
-        {"location":"Brooklyn"}
-      result · completed
-        {"temperatureC":18,"condition":"rain"}
-
-    ASSISTANT  2.8s · 1.2s
-      布鲁克林当前约 18°C，有雨。
-
-    total 4.0s · 1 skill load · 1 tool call · 2 AI messages
-    full events: …/weather/brooklyn/a2/events.json
-    69 unlinked telemetry spans omitted; inspect the OTel trace for framework timing.
-    full OTel trace: …/weather/brooklyn/a2/trace.json
-    ```
-
-    没有 OTel 时仍用标准事件流展示相同的步骤，只去掉时间列和瀑布关系，不把“缺时间”误写成“没有执行”：
-
-    ```text
-    $ niceeval show @1nx4dpwq --execution
-    @1nx4dpwq · weather/brooklyn · compare/bub-gpt-5.4 · failed
-
-    USER
-      布鲁克林今天天气怎么样？
+这样 Agent 使用的文档与项目安装的版本一致。
 
-    ASSISTANT
-      我先读取天气工具的使用说明。
+## 运行并保留 receipt
 
-    TOOL · get_weather
-      input
-        {"location":"Brooklyn"}
-      result · completed
-        {"temperatureC":18,"condition":"rain"}
-
-    ASSISTANT
-      布鲁克林当前约 18°C，有雨。
-
-    timing unavailable · OTel trace was not collected
-    full events: …/weather/brooklyn/a2/events.json
-    ```
-
-    diff 是被测 Agent 在 Sandbox 工作区造成的文件变化，不是评估用例源码的新旧差异。只有 Sandbox 评估用例才会收集到 diff——非 Sandbox 评估用例或 agent 确实没碰任何文件时，attempt 页的 `available:` 列表会省略 `--diff`。默认先给文件级摘要，避免把大段补丁塞进 Agent 上下文；`--diff=<文件>` 再展开单个文件，原始 artifact 路径始终保留：
-
-    ```text
-    $ niceeval show @1c3h6tbn --diff
-    @1c3h6tbn · fixtures/button · compare/bub-gpt-5.4 · errored
-
-    M src/components/Button.tsx   +42 −3
-    A src/components/Button.css   +18
-
-    2 files changed · +60 −3
-    full diff: …/fixtures/button/a1/diff.json
-    next: niceeval show @1c3h6tbn --diff=src/components/Button.tsx
-    ```
-
-    用这组输出检查信息是否足够：
-
-    | 诊断目标 | 入口 | 输出必须包含 |
-    | --- | --- | --- |
-    | 查看一次 Attempt 摘要 | `niceeval show @<id>` | 评估用例断言、执行步骤、生命周期阶段耗时摘要、diff 摘要及各块可用性 |
-    | 检查评估用例断言及其通过或失败原因 | `niceeval show @<id> --source` | 运行时评估用例源码、源码哈希、断言所在行、严重度、分数与原因 |
-    | 检查 Coding Agent 的消息与调用 | `niceeval show @<id> --execution` | 消息、thinking、Skill load、工具调用与结果；有 OTel 时在同一节点附时间、父子关系和错误状态 |
-    | 检查 Attempt 各阶段耗时 | `niceeval show @<id> --timing` | lifecycle → hook/turn → shell → OTel 的统一时间树；出错的 Attempt 标出已知的最深失败节点 |
-    | 检查 Sandbox 工作区改动 | `niceeval show @<id> --diff` | 文件摘要、增删行数、具体补丁和原始 diff 路径；无文件工作区时明确 unavailable |
-  </Step>
-  <Step title="需要时把证据交给脚本或下一个 agent">
-    以上任何一条 `show` 命令加 `--json`，都会把同一范围、同一切片选出的同一批实体输出成一份结构化 JSON 文档到 stdout，而不是排好版的文本。字段名与落盘类型保持一致，Coding Agent 不用再解析人读格式：
-
-    ```bash
-    npx niceeval show @1puv8ydu --json
-    ```
-
-    ```json
-    {
-      "format": "niceeval.show",
-      "schemaVersion": 1,
-      "view": "attempt",
-      "sample": { "resultsRoot": "…", "experiments": ["compare/claude-mempal"], "fresh": false },
-      "data": {
-        "summary": {
-          "locator": "@1puv8ydu",
-          "identity": { "experimentId": "compare/claude-mempal", "evalId": "react-datepicker/pr-6058", "attempt": 0 },
-          "verdict": "failed",
-          "durationMs": 29800,
-          "costUSD": 0.07,
-          "capabilities": { "source": false, "execution": true, "timing": false, "diff": false }
-        },
-        "assertions": {
-          "attention": [
-            {
-              "name": "fixes month navigation year sync",
-              "detail": "judge(\"月份切换后年份同步\")",
-              "severity": "gate",
-              "outcome": "failed",
-              "score": 0,
-              "expected": ">= 0.7",
-              "received": "0.4 / 1 · fix still off by one month at year boundary"
-            }
-          ],
-          "passedGroups": []
-        },
-        "fixPrompt": { "prompt": "Fix the failing eval from this niceeval run.\n\n## Failure\n…" }
-      }
-    }
-    ```
-
-    `--json` 是数据超集：text 面为注意力预算省略或截断的字段（完整字符串、完整树）在这里保留完整。`--source`、`--execution`、`--timing`、`--diff`、`--usage`、`--stats` 与对照矩阵同样接受 `--json`，是同一条规则，不是 attempt 视图的特例。需要把某次失败的结构化事实转交给另一个 agent、拼进自己的分析脚本，或喂进 CI 判定时，读这里，不要重新扫 `.niceeval/` 原始文件——那样会复刻出第二套不一致的选择和去重口径。
-  </Step>
-  <Step title="提出假设并修改">
-    根据证据只修改最可能出错的一侧：
-
-    | 看到的现象 | 优先检查 |
-    | --- | --- |
-    | 回复或工具调用不符合需求 | 被测程序、Prompt、工具定义 |
-    | `diff` 与任务要求不符 | 被测 Agent 的实现策略或运行环境 |
-    | 正确行为被 gate 拒绝 | 评估用例断言、fixture、setup |
-    | timeout、鉴权或 Sandbox 错误 | 实验配置、Adapter、Sandbox |
-    | 同一评估用例时好时坏 | `--history`、`attempts` 和稳定性问题 |
-
-    不要为了变绿而放宽一个本来正确的断言。先写清楚“哪条证据支持什么判断”，再修改代码。
-  </Step>
-  <Step title="局部重跑并验证假设">
-    ```bash
-    npx niceeval exp local weather/brooklyn --json --rerun all
-    npx niceeval show weather/brooklyn
-    ```
-
-    位置参数按评估用例 ID 前缀缩小实验范围。调试同一个失败时加 `--rerun all`，确保刚才的修改真的触发一次新运行。然后用 `show` 验证判定、断言和证据是否按预期变化。
-  </Step>
-  <Step title="全量确认没有回归">
-    ```bash
-    npx niceeval exp local --json --rerun all
-    npx niceeval show
-    ```
-
-    局部结果变绿只证明当前假设成立。收工前必须强制全量重跑；只有命令退出码为 `0`，且 `show` 没有新的失败或错误，才算完成。
-  </Step>
-</Steps>
-
-## 从输出读取诊断信号
-
-`--json` 在 stdout 上输出一行一个 JSON 对象的 NDJSON 流——这才是 Coding Agent 应该解析的部分。首行是携带流身份的 `start` 事件；之后只有失败、错误或去重后的 warning 立即追加一行，长时间没有这些事件才补一条 `progress` 心跳（存活信号，不是结果数据源）；最后一个事件永远是给出结论、计数和快照路径的 `result`：
-
-```text
-{"format":"niceeval.exp","schemaVersion":1,"event":"start","total":15,"configs":1,"concurrency":8,"reused":0}
-{"event":"failure","locator":"@1k2m9qtr","evalId":"weather/brooklyn","experimentId":"local","severity":"gate","assertion":"calledTool(\"get_weather\")","received":"0 tool calls"}
-{"event":"result","status":"failed","passed":14,"failed":1,"errored":0,"reused":0,"completion":"complete","snapshots":[".niceeval/local/2026-07-09T10-00-00-000Z-x1f2/"]}
+```sh
+npx niceeval exp checkout --json | tee .niceeval-invocation.ndjson
 ```
 
-Coding Agent 应从 `failure` / `error` 事件里取出 `locator`，再逐个运行 `niceeval show @<id>` 或按需加证据 flag；事件按发生顺序追加，不用等到 `result` 才开始处理已经拿到的 locator。不要用 `progress` 心跳判断结果，它只说明进程还活着。`--json` 不做数量截断——每条失败都是独立事件，量大时用 `niceeval view` 或结果快照做批量分析。机器读取以结果快照为事实来源：
+`--json` 的每一行都是当前进程反馈。progress 与 diagnostic 只说明这次运行正在发生什么。最后恰好一条 receipt 包含：
 
-```text
-.niceeval/<experiment>/<快照>/
-├── snapshot.json
-└── <eval-id>/a<attempt>/
-    ├── result.json
-    ├── events.json
-    ├── trace.json
-    └── diff.json
+```json
+{
+  "invocationId": "01J8ZK3M6P4T7V9X2C5N8QW0RY",
+  "runIds": ["01J9ZK3M6P4T7V9X2C5N8QW0RY"],
+  "startedAt": "2026-08-09T10:00:00.000Z",
+  "completedAt": "2026-08-09T10:01:00.000Z",
+  "completion": "completed"
+}
 ```
 
-- `snapshot.json` 记录实验身份、运行配置、格式版本和时间。
-- `result.json` 记录该 Attempt 的判定、断言、结构化错误、diagnostics 和用量；瞬时 progress 不落盘。
-- `events.json` 是对话与工具调用事件，`trace.json` 是调用链，`diff.json` 是 Sandbox 文件变化。
-- 某类证据不存在时，对应文件不会生成。先以 `show` 的提示为准，不要假设每个目录都有全部文件。
+Agent 应把最后一条 receipt 当作本次调用的交接信息。它不是持久化的结果协议；业务事实仍要通过 `runIds` 从已发布的 Record 读取。
 
-`show` 的默认结果可能合成自多次运行：每个 Experiment × 评估用例选择最新判定，因此局部重跑后仍能看到其它评估用例的旧结果。该视图用于查看每条评估用例的最新已知判定；同一版代码的整体结果必须通过一次 `--rerun all` 全量运行确认。
+## 用 Run ID 查看结果
 
-## 结果复用条件
+运行结束后，先读取 Run 的 Report：
 
-不传 `--rerun all` 时，NiceEval 会比较当前指纹与最近结果。指纹由两部分组成：
-
-- **评估用例的源码**：`.eval.ts` 文件本身，加上它 import 的项目内模块，以及用 `loadYaml` / `loadJson` / `loadText` 读进来的数据文件。
-- **运行配置**：实验 ID、Agent、model、flags、Sandbox、`Judge` 的模型与端点，以及 `--strict`。
+```sh
+npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
+npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
+```
 
-超时上限不在指纹里：它决定等不等得到，不决定跑出来的结果是什么。改大改小都不会作废已完成的结果。
+`show` 与 `view` 选择 Sample，投影需要的 `RecordAttachment`，并形成固定的 `ReportExecution`。Agent 应区分以下状态：
 
-| 最近结果与当前输入 | 本次行为 |
+| 看到的状态 | 下一步 |
 | --- | --- |
-| 指纹相同，判定为 `passed` 或 `failed` | 携入旧结果，不重新执行 |
-| 指纹不同 | 重新执行 |
-| 最近结果为 `errored` 或 `skipped` | 重新执行 |
-| 使用 `--rerun` | 只有 `passed` 携入，失败项重新执行 |
-| 使用 `--rerun all` | 忽略旧结果，全部重新执行 |
-
-被测程序的源码不在指纹里。修改实现后，即使行为已经变化，旧的 `passed` 或 `failed` 仍可能被复用。因此可以这样选择：
+| `failed` | 检查任务结果与断言，修正被测程序或评估逻辑。 |
+| `errored` | 检查诊断、Adapter、Sandbox 或凭据。 |
+| `not-recorded` | 检查该 expected slot 为什么没有 Member。 |
+| `core-invalid` | 阅读具名 Core issue，不要把它当成未采集。 |
+| `unavailable` | 确认 owner 是否应当有这个 Attachment。 |
+| `migration-required` | 运行 `niceeval migrate`。 |
+| `unsupported` 或 `invalid` | 只处理依赖该 Attachment 的查看内容，并阅读具名 issue。 |
 
-- 只想重看已有结果：运行 `niceeval show`，不产生新费用。
-- 修改了评估用例或实验配置：直接重跑；指纹变化会触发对应任务。改公共 helper、改数据文件、换 `Judge` 模型都算在内。
-- 修改了被测程序，要复验失败项：加 `--rerun`。已通过的照常携入，不必先去找失败的评估用例 ID——失败面板的 `Retry:` 行给的就是这条命令。
-- 准备结束本轮工作：对整个实验使用 `--rerun all`，排除其它评估用例的回归。
+## 修改后再次运行
 
-哪一处改动作废哪些结果，逐场景的对照见[重跑与沿用](/zh/tutorials/rerun-and-cache)。
+让 Agent 每次只处理一个可验证假设：修改程序或评估用例，运行相同范围，再读取新的 receipt 和 Run。需要确认所有 slot 真实执行时使用：
 
-## 设置自主迭代协议
+```sh
+npx niceeval exp checkout --rerun all --json
+```
 
-可以把下面的协议放进任务描述。它既适合优化被测实现，也适合调试评估用例：
+自动采用已有 Attempt 时，`--dry` 会说明原因。carry 与 accept 的理由位于目标 Run 的 `niceeval.membership-provenance/v1` RecordAttachment；详情见[重跑与沿用](/zh/tutorials/rerun-and-cache)。
 
-```text
-读取 node_modules/niceeval/INDEX.md，再按索引读取与任务有关的文档。
-运行 npx niceeval exp local --json，并根据退出码和 failure/error 事件里的 locator 决定下一步。
-对每个失败的 Eval，从事件里取一个 Attempt locator；再运行 niceeval show @<id>
-并按问题选择 --source、--execution、--timing 或 --diff；--timing 从 lifecycle 展开 setup/teardown
-hook、shell 命令、每轮 send 与可关联的 OTel model/tool，回答整个 Attempt 的时间花在哪里。
-写出失败原因的假设，并判断应该修改被测程序、
-Eval，还是实验环境。修改后用 --rerun 重跑失败项，比较新的判定和证据。
-同一问题连续三轮没有新证据或改善时停止并汇报，不要为得到通过结果而放宽正确的断言。
-全部局部失败清零后，用 npx niceeval exp local --json --rerun all 全量验证；退出码 0 才完成。
-```
+## Record 的边界
 
-真实 Agent 的运行可能产生费用。实验阶段可以加 `--budget <美元>` 限制本轮累计成本；预算只能限制单次命令，不能替代上面的停止条件。
+Record 只保存已发布的事实，发布后不可修改。Agent 需要不同结果时修改程序或评估用例，运行新的 Invocation，再用新 receipt 的 `runIds` 查看。
 
-人与 AI 随时可以接手同一轮工作。AI 用 `niceeval show` 读取的结果，也能由人运行 `npx niceeval view` 在网页中查看。两者读取同一批 artifact；完整的输出格式、历史选择和网页操作见[查看结果](/zh/tutorials/viewing-results)。
+需要把某次结果交给他人时，使用[发布静态报告](/zh/tutorials/publish-report)，而不是把当前进程反馈当作分享格式。

package/docs-site/zh/tutorials/agent-onboarding.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "Coding Agent 从零接入"
 description: "给 Coding Agent 的完整接入流程：探索项目、与用户确认路径、配置 Judge、写出 Adapter / Experiment / 评估用例并跑通第一个实验。"
 ---
 
-这一页是 Coding Agent 把 NiceEval 接入一个项目的执行步骤。前提：`niceeval` 依赖已经装进项目、`niceeval init` 已经运行，你是从随包 `INDEX.md` 进入本页的。用用户的语言与用户交流；所有 API、字段和 CLI 行为以随包文档为准，不要凭训练记忆现编。
+这一页是 Coding Agent 把 NiceEval 接入一个项目的执行步骤。前提：`niceeval` 依赖已经装进项目、`niceeval init` 已经运行，你是从随包 `INDEX.md` 进入本页的。用用户的语言与用户交流。所有 API、字段和 CLI 行为以随包文档为准，不要凭训练记忆现编。
 
 ## 第 1 步：探索项目，再和用户确认
 
@@ -14,14 +14,16 @@ description: "给 Coding Agent 的完整接入流程：探索项目、与用户
 2. **前端和 Agent 怎么通信**：HTTP 还是 gRPC / WebSocket？协议是标准的还是自己实现的——AI SDK UI Message Stream、OpenAI Responses / Chat Completions 这类标准协议，还是 SDK 原生事件流透传，还是用户自定义的 JSON/SSE 帧？这直接决定 Adapter 是用内置的（零映射）还是手写 `send`（要自己写事件映射）。
 3. **后端有没有接 OTel**：搜有没有 OTel SDK 初始化、AI SDK telemetry、LangSmith / OpenLLMetry / OpenInference 这类埋点。已经有的话 Tier 2 几乎零成本。
 4. **用户自己有没有做 A/B Test / feature flag**：应用里已有变体开关的话，Experiment 的 `flags` 可以直接透传给它（Tier 3 的现成入口）。
-5. **Judge 用什么**：语义评分（`t.judge.autoevals.*`）要一个**与被测 Agent 分离的 Judge 模型**，走 OpenAI 兼容的 `/chat/completions` 协议——OpenAI 官方、DeepSeek、任何兼容该协议的网关都行。问用户手上有哪个服务的 key、想用什么 Judge 模型（没有内置默认模型，必须显式指定）。缺 key 不会静默通过：Judge 断言会记为 `unavailable`，非 optional 断言会让 Attempt `errored`。只有明确不写 Judge，或显式链 `.optional()` 允许该断言缺席时，才先用精确断言跑通。
-6. **是不是 Agent 本体要进 Sandbox**：被测对象是 coding agent CLI、或给 coding agent 写的 Skill/Plugin/Hook/MCP server（要在隔离 workspace 里改文件/跑命令）的话，必须走 Sandbox，不能像 HTTP 服务那样直接 `send`。默认建议 `dockerImageSandbox({ image: "node:24-slim" })`，但**要先跟用户确认**——本机/CI 有没有 Docker、要不要 Vercel Sandbox 或其它远程 Provider；用户没有异议就默认走 Docker。Provider 声明在 Eval 或 Experiment 上，没有 CLI flag、项目级兜底或自动探测——见[选择 Sandbox Provider](/zh/tutorials/sandbox-providers)。
+5. **Judge 用什么**：语义评估（`t.judge.autoevals.*`）要一个**与被测 Agent 分离的 Judge 模型**，走 OpenAI 兼容的 `/chat/completions` 协议。问用户手上有哪个服务的 key、想用什么 Judge 模型。缺 key 不会静默通过：Judge Assertion 会记为 `unavailable`；它参与 Pass grading，或在 Score Eval 中配置了 `.score()` / `.orStop()` 时，Attempt 的 grading 不可用。没有 Judge 配置时，先只写精确 Match。
+6. **是不是 Agent 本体要进 Sandbox**：被测对象是 coding agent CLI、或给 coding agent 写的 Skill/Plugin/Hook/MCP server（要在隔离 workspace 里改文件/跑命令）的话，必须走 Sandbox，不能像 HTTP 服务那样直接 `send`。
+
+   默认建议 `dockerSandbox({ source: { type: "image", image: "node:24-slim" } })`，但**要先跟用户确认**——本机/CI 有没有 Docker、要不要 Vercel Sandbox 或其它远程 Provider。用户没有异议就默认走 Docker。Provider 声明在 Eval 或 Experiment 上，没有 CLI flag、项目级默认值或自动探测——见[选择 Sandbox Provider](/zh/tutorials/sandbox-providers)。
 
 探完之后，向用户**介绍接入等级**并给出推荐（详见[接入等级](/zh/explanation/tier)）：
 
 - **Tier 1（只接 send）**：应用一行不改，全套断言（文本、Judge、多轮、工具、HITL）都在这一档。
-- **Tier 2（send + OTel）**：应用把 OTel span 也发 NiceEval 一份，换 `niceeval view` 的调用瀑布图；已有埋点（第 3 点探到的）就零改动。
-- **Tier 3（侵入改造 + flags）**：把应用内部变体暴露成 `flags` 做 feature A/B；已有 A/B 开关（第 4 点探到的）就是现成入口。
+- **Tier 2（send + OTel）**：应用把 OTel span 也发 NiceEval 一份，换 `niceeval view` 的调用瀑布图。已有埋点（第 3 点探到的）就零改动。
+- **Tier 3（侵入改造 + flags）**：把应用内部变体暴露成 `flags` 做 feature A/B。已有 A/B 开关（第 4 点探到的）就是现成入口。
 
 **默认推荐先 Tier 1 跑通，再升 Tier 2**——尤其当第 3 点探到应用已有 OTel 时，明确告诉用户「升 Tier 2 只是把 span 多发一份，成本接近零」。Tier 3 只在用户明确要做变体对比时提。
 
@@ -30,7 +32,7 @@ description: "给 Coding Agent 的完整接入流程：探索项目、与用户
 | 被测对象 | 去读 |
 |---|---|
 | 用 Vercel AI SDK（`useChat` 后端）写的应用 | [内置 Agent 参考](/zh/reference/builtin-agents)：内置 `uiMessageStreamAgent` 无侵入接入，不用手写事件映射 |
-| coding agent CLI（claude-code / codex / bub 等改文件的任务） | [在 Sandbox 中评测 Agent](/zh/tutorials/sandbox-agent)：要配 `sandbox`，默认 `dockerImageSandbox({ image: "node:24-slim" })`，先跟用户确认 Provider |
+| coding agent CLI（claude-code / codex / bub 等改文件的任务） | [在 Sandbox 中评测 Agent](/zh/tutorials/sandbox-agent)：要配 `sandbox`，默认 `dockerSandbox({ source: { type: "image", image: "node:24-slim" } })`，先跟用户确认 Provider |
 | 给 Claude Code / Codex 写的 Skill、Plugin、Hook 或 MCP server | [评测 Coding Agent 扩展](/zh/examples/coding-agent-extensions)：同样跑在 Sandbox 里，Provider 确认方式同上 |
 | 其它自研 agent loop、LangGraph、OpenAI Agents SDK、已部署 Agent | [接入自己的 Agent](/zh/tutorials/connect-your-agent) 起步，手写 `send` 的完整教程在[编写 send](/zh/tutorials/write-send) |
 | 纯函数、没有独立服务的场景 | 先读[接入自己的 Agent](/zh/tutorials/connect-your-agent) 里「为什么不直调」那段，跟用户确认这确实是他们要的边缘用法，再继续 |
@@ -47,7 +49,7 @@ export default defineConfig({
     model: "gpt-5.4-mini",                // 必填：没有内置默认模型
     // 用非 OpenAI 官方的兼容服务（DeepSeek、网关等）时再加这两项：
     // baseUrl: "https://api.deepseek.com/v1",
-    // apiKeyEnv: "DEEPSEEK_API_KEY",     // key 从这个环境变量读；不配就读 NICEEVAL_JUDGE_KEY
+    // apiKeyEnv: "DEEPSEEK_API_KEY",     // key 从这个环境变量读。不配就读 OPENAI_API_KEY
   },
 });
 ```
@@ -56,19 +58,19 @@ export default defineConfig({
 
 三个要提醒用户的点：
 
-- **配错不会假装通过。** 模型或 key 解析不到、网关拒了鉴权、判分请求超时，这条 Judge 断言记成 `unavailable` 并带上原因，这次 Attempt 判 `errored`——评不出来的结论既不算通过，也不算 agent 答错。所以「全绿」就是真的评过了。确实允许某条缺席（实验性的、开发机上没 key）时，在那一条上显式写 `.optional()`。
-- **配完先验一次。** 写一条只评固定文本的轻量评估用例跑一遍，不需要先调被测 agent：`t.judge.autoevals.closedQA("这段文本是否表达成功?", { on: "operation completed successfully" }).gate(0.8)`。跑完 `niceeval show <评估用例 id>` 确认每条后面真的跟着分数。
-- **没有用户在场（自治接入）时不要直接跳过 Judge**：先看环境里有没有可用的 key（`NICEEVAL_JUDGE_KEY`、`DEEPSEEK_API_KEY` 等），有就用 `apiKeyEnv` 指过去并按上一条验证；确实没有才降级到精确断言 + 形状断言（`includesUrl()` / `hasSections()` 这类，见[题型与断言](/zh/tutorials/evaluation-kinds)），并在收尾总结里明确说明 Judge 未配置及原因。
-- Judge 模型要**与被测 Agent 分离**，避免同一个模型给自己打分。模型解析优先级（单次调用 → 评估用例级 → 全局配置）和三种评分形状见 [Judge](/zh/explanation/judge)，`judge` 字段全集见 [defineConfig 参考](/zh/reference/define-config)。
+- **配错不会假装通过。** 模型或 key 解析不到、网关拒绝鉴权、评估请求超时时，Judge Assertion 记为 `unavailable` 并带上原因；读取面不会把缺失 measurement 伪装成 mismatch 或零分。
+- **配完先验一次。** 写一条带 `judge: true` 的轻量 Pass Eval，调用 `turn.judge.autoevals.closedQA(...).atLeast(0.8)`。跑完 `niceeval show <评估用例 id>`，确认能看到 measurement、threshold、condition 与 Assertion 证据。
+- **没有用户在场（自治接入）时不要直接跳过 Judge**：先看环境里是否已有可用 key，例如 `OPENAI_API_KEY` 或 `DEEPSEEK_API_KEY`。有就用 `apiKeyEnv` 指向它并验证；没有时先写精确 Match，并在收尾说明 Judge 没有配置。
+- Judge 模型要**与被测 Agent 分离**，避免同一个模型给自己的输出打分。配置按 Eval、Experiment、项目配置逐字段解析；三种 recipe 见 [Judge](/zh/explanation/judge)。
 
 ## 第 3 步：写三件套
 
 按第 1 步选中的方向读完对应文档后，依次写：
 
-1. **Adapter**（`agents/*.ts` 或用户项目里约定的目录）——用 `defineDirectAgent` 实现 `send`，配置走工厂参数，不写死、不读 `process.env`。契约见 [Adapter](/zh/explanation/adapter)，API 签名见 [Adapter 参考](/zh/reference/define-agent)，事件映射见[事件参考](/zh/reference/events)。两个容易踩的点：**端点/模式要选被测系统核心能力的入口，不是最容易跑通的入口**——比如被测平台既有「纯 LLM 聊天」又有「连库执行」两种模式，接前者等于评了个底层模型代理，没评到产品本身；**`evidenceCoverage` 必须按实际映射如实声明**——只把最终文本映射出来就不要用 `completeEvidenceCoverage`，声明会影响断言完整性，虚报比保守更糟。
-2. **Experiment**（`experiments/*.ts`）——引用上面的 Adapter，声明 `model`、`flags`、`attempts` 等。模型对比写两个实验文件，各自钉一个 `model`；`evals: (eval) => boolean` 决定各自运行哪些评估用例。路径只负责 id 和批量运行，报告读取每份快照的 `selectedEvalIds`。
-3. **评估用例**（`evals/*.eval.ts`）——**先探明这个应用是干嘛的，再写一条贴着它真实功能的评估用例**：读它的 README、路由、工具定义或系统提示，找出它的核心用例（客服机器人就问一条真实的客服问题、SQL agent 就给一个真实的查询任务），拿这个用例做第一条评估用例的输入和断言。两类输入都不合格：「你好」这种和应用无关的占位输入，以及「你是什么/你能做什么」这种**问被测系统它自己的元问题**——那不是用户拿它干活的用例。形式上仍从最小写起：一句输入，`t.succeeded()` + 一个针对预期回答的内容断言——但最小形式只是调通的脚手架，不是交付标准，收尾前还要满足两条：
-   - **断言在被测系统胡编时要会变红**。不要断言输入里本来就有的词（问「X 是什么」再断言回答含「X」，被测方复读题目就能通过）；断言预期回答独有的实质内容——具体事实、结构（`hasSections()`）、真实链接（`includesUrl()`），或用 `t.judge` 做语义判定。
+1. **Adapter**（`agents/*.ts` 或用户项目里约定的目录）——用 `defineAgent` 实现 `send`，配置走工厂参数，不写死、不读 `process.env`。契约见 [Adapter](/zh/explanation/adapter)，API 签名见 [Adapter 参考](/zh/reference/define-agent)，事件映射见[事件参考](/zh/reference/events)。两个容易踩的点：**端点/模式要选被测系统核心能力的入口，不是最容易跑通的入口**——比如被测平台既有「纯 LLM 聊天」又有「连库执行」两种模式，接前者等于评了个底层模型代理，没评到产品本身。**`evidenceCoverage` 必须按实际映射如实声明**——只把最终文本映射出来就不要用 `completeEvidenceCoverage`，声明会影响断言完整性，虚报比保守更糟。
+2. **Experiment**（`experiments/*.ts`）——引用上面的 Adapter，声明 `model`、`flags`、`attempts` 等。模型对比写两个实验文件，各自钉一个 `model`。`evals: (eval) => boolean` 决定各自本次运行哪些评估用例。路径只负责 id 和批量运行，报告消费当前 Sample 的物理结果与覆盖事实。
+3. **评估用例**（`evals/*.eval.ts`）——**先探明这个应用是干嘛的，再写一条贴着它真实功能的评估用例**。读它的 README、路由、工具定义或系统提示，找出它的核心用例（客服机器人就问一条真实的客服问题、SQL agent 就给一个真实的查询任务），拿这个用例做第一条评估用例的输入和断言。两类输入都不合格：「你好」这种和应用无关的占位输入，以及「你是什么/你能做什么」这种**问被测系统它自己的元问题**——那不是用户拿它干活的用例。形式上仍从最小写起：一句输入，`t.succeeded()` + 一个针对预期回答的内容断言——但最小形式只是调通的脚手架，不是交付标准，收尾前还要满足两条：
+   - **断言在被测系统胡编时要会变红**。不要断言输入里本来就有的词（问「X 是什么」再断言回答含「X」，被测方复读题目就能通过）。断言预期回答独有的实质内容——具体事实、结构（`hasSections()`）、真实链接（`includesUrl()`），或用 `t.judge` 做语义判定。
    - **至少一条负例**。喂一个被测系统应该答不了的输入（不存在的表、检索不到的主题），断言它明确说查不到/做不到，而不是编造一个看似合理的结果——对连着真实数据/检索源的 agent，这是最值得先测的失败形态。
    写法见[编写评估用例](/zh/tutorials/authoring)，断言与题型见[题型与断言](/zh/tutorials/evaluation-kinds)，签名见 [defineEval 参考](/zh/reference/define-eval)。
 
@@ -77,7 +79,7 @@ export default defineConfig({
 架构上有两条硬规则，写 Adapter 时不要违反：
 
 - **不做进程内直调**。就算 agent runtime 和评估用例在同一个代码库里，Adapter 也要走 HTTP（或对应传输层），不要把 `fetch` 换成直接 `import` 被测函数——原因见[接入自己的 Agent](/zh/tutorials/connect-your-agent) 里「为什么不直调」。
-- **评估用例侧不代管被测进程**。不 spawn 应用、不另开端口；应用由用户自己按平时的方式启动（`pnpm dev` 之类），Adapter 连不上时报「先起应用」这类明确的错误，不要自己起服务。
+- **评估用例侧不代管被测进程**。不 spawn 应用、不另开端口。应用由用户自己按平时的方式启动（`pnpm dev` 之类），Adapter 连不上时报「先起应用」这类明确的错误，不要自己起服务。
 
 ## 第 4 步：跑通并验证
 
@@ -86,7 +88,7 @@ export default defineConfig({
 <包管理器> exec niceeval view                 # 查看器里看对比结果
 ```
 
-按 [Coding Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)用 `niceeval show` 加 `--source`、`--execution`、`--timing`、`--diff` 完成运行、观察、修改和重跑；查看器用法见[查看结果](/zh/tutorials/viewing-results)。没跑通分三类定位：`fetch` 直接抛错 → 应用没起来或 URL 不对；`t.succeeded()` 不过 → 应用回了非成功状态；只有内容断言不过 → 接入已经通了，调断言或调应用。
+按 [Coding Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)用 `niceeval show` 加 `--source`、`--execution`、`--timing`、`--diff` 完成运行、观察、修改和重跑。查看器用法见[查看结果](/zh/tutorials/viewing-results)。没跑通分三类定位：`fetch` 直接抛错 → 应用没起来或 URL 不对。`t.succeeded()` 不过 → 应用回了非成功状态。只有内容断言不过 → 接入已经通了，调断言或调应用。
 
 ## 第 5 步：收尾，告诉用户做了什么
 
@@ -95,7 +97,7 @@ export default defineConfig({
 - [ ] 评估用例的输入是被测系统的核心用例，不是问它自己的元问题或占位寒暄
 - [ ] 每条内容断言在被测系统复读题目/胡编时会变红（断言的词不是输入里本来就有的）
 - [ ] 至少有一条负例（应该答不了的输入，断言它明确说做不到）
-- [ ] 有 key 时 Judge 已配置，且在 `niceeval view` 里看到过 Judge 分数；没 key 时总结里说明了
+- [ ] 有 key 时 Judge 已配置，且在 `niceeval view` 里看到过 Judge 分数。没 key 时总结里说明了
 - [ ] Experiment 里声明的 `model` / `flags` 确实被 Adapter 消费（没有写了没人读的死配置，也没有编造被测系统不存在的 model 值）
 
 跑通之后先总结，再谈下一步。总结要说清：接了什么被测对象、生成了哪几个文件（Adapter / Experiment / 评估用例各在哪）、`niceeval exp <实验路径>` 和 `niceeval view` 怎么跑、第一次运行的结果是什么样。不要在没被要求的情况下顺手重构用户已有代码，也不要在这几个文件之外新增抽象。
@@ -109,7 +111,7 @@ export default defineConfig({
 | 工具调用断言（`t.calledTool()` 等） | 只改 Adapter：把应用响应映射成标准事件流，约 10–30 行映射代码 | 评估用例能断言「Agent 有没有调对工具、参数对不对」，不再只看最终回复 | [编写 send](/zh/tutorials/write-send)、[事件参考](/zh/reference/events) |
 | 多轮对话、会话隔离 | 只改 Adapter：接上 `ctx.session`（typed slot 或 `id` + `capture()`），几行到十几行 | 评估用例能写多轮场景、`t.newSession()` 验证会话间不串味 | [驱动多轮交互](/zh/explanation/drive)、[编写 send](/zh/tutorials/write-send) |
 | 人工审批流（HITL） | 只改 Adapter：停轮返回 `waiting` + `input.requested`，回答轮续跑，约 10–20 行 | 评估用例能覆盖「批准/拒绝之后 Agent 行为对不对」这类审批场景 | [HITL](/zh/explanation/hitl) |
-| 调用瀑布图（升 Tier 2） | 应用已有 OTel 埋点（第 1 步探过）：只是把 span 多发一份给 NiceEval，几行配置；没埋点：补一段通用 OTel 初始化 | `niceeval view` 里看到应用内部每次模型调用、工具执行的耗时和 token 时间线；不影响任何断言 | [配置 OTel](/zh/tutorials/connect-otel) |
-| feature A/B 对比（升 Tier 3） | 改应用：把变体暴露成 `flags` 可切换的配置，改动量取决于应用；已有 A/B 开关（第 1 步探过）就是现成入口 | Experiment 层面直接对比「改 prompt / 换工具集 / 开关 feature 谁更好」 | [组织 Experiment](/zh/tutorials/experiments)、[接入等级](/zh/explanation/tier) |
+| 调用瀑布图（升 Tier 2） | 应用已有 OTel 埋点（第 1 步探过）：只是把 span 多发一份给 NiceEval，几行配置。没埋点：补一段通用 OTel 初始化 | `niceeval view` 里看到应用内部每次模型调用、工具执行的耗时和 token 时间线。不影响任何断言 | [配置 OTel](/zh/tutorials/connect-otel) |
+| feature A/B 对比（升 Tier 3） | 改应用：把变体暴露成 `flags` 可切换的配置，改动量取决于应用。已有 A/B 开关（第 1 步探过）就是现成入口 | Experiment 层面直接对比「改 prompt / 换工具集 / 开关 feature 谁更好」 | [组织 Experiment](/zh/tutorials/experiments)、[接入等级](/zh/explanation/tier) |
 
 共同点也要讲给用户：这些全是给 Adapter 或应用加增量，**已写的评估用例一行不用改**。三档投入分别买到什么、什么时候值得升级，见[接入等级](/zh/explanation/tier)。第 1 步探到应用已有 OTel 埋点的话，瀑布图那条要主动推荐——成本接近零。

package/docs-site/zh/tutorials/authoring.mdx

@@ -44,7 +44,7 @@ export default defineEval({
 });
 ```
 
-`tags` 可供 `--tag` 和 experiment 的 `evals` 谓词读取。`environment` 只声明环境 profile；具体 image / template 由 experiment 使用的 Sandbox 配置映射。
+`tags` 可供 `--tag` 和 experiment 的 `evals` 谓词读取。`environment` 只声明环境 profile。具体 image / template 由 experiment 使用的 Sandbox 配置映射。
 
 ## 单轮评估
 
@@ -133,7 +133,7 @@ export default defineEval({
 
 ## 输出信息
 
-`setup` 用于这条评估用例的 Fixture。第二个参数绑定到评估用例 setup 阶段；`test(t)` 里的反馈绑定到评估用例 run 阶段：
+`setup` 用于这条评估用例的 Fixture。第二个参数绑定到评估用例 setup 阶段。`test(t)` 里的反馈绑定到评估用例 run 阶段：
 
 ```ts
 export default defineEval({
@@ -161,11 +161,11 @@ export default defineEval({
 });
 ```
 
-`progress` 只更新运行中的短期状态，不进入结果。`diagnostic` 会写进当前 Attempt 的 `result.json`，但不会代替断言或自动改变判定：业务结论仍用 `t.check` / `t.require` / gate；基础设施无法继续时抛出异常。
+`progress` 只更新运行中的短期状态，不进入结果。`diagnostic` 会写进当前 Attempt 的 `result.json`，但不会代替断言或自动改变判定：业务结论仍写 `t.check(value, match)`、作用域 Assertion 或 Judge measurement。基础设施无法继续时抛出异常。
 
 ## 评估的生命周期
 
-`setup(sandbox, ctx)` 准备 Fixture；配一个 `teardown(sandbox, ctx)` 收尾，两者合起来是这条评估用例的 Fixture，每个 Attempt 各执行一次。它在整条 Attempt 里的位置是固定的：
+`setup(sandbox, ctx)` 准备 Fixture。配一个 `teardown(sandbox, ctx)` 收尾，两者合起来是这条评估用例的 Fixture，每个 Attempt 各执行一次。它在整条 Attempt 里的位置是固定的：
 
 <Lifecycle
   title="一条 Attempt 从排队到收尾"
@@ -187,14 +187,14 @@ export default defineEval({
   ]}
 />
 
-右列是「谁的一次」：四层 Hook 共用同一副成对形态，但触发频次不同。不声明 `sandboxReuse` 时每条 Attempt 独占一个 Sandbox，所以「每个 Sandbox 一次」和「每 Attempt」重合；声明复用之后两者分开，见[复用 Sandbox](/zh/tutorials/sandbox-reuse)。
+右列是「谁的一次」：四层 Hook 共用同一副成对形态，但触发频次不同。不声明 `sandboxReuse` 时每条 Attempt 独占一个 Sandbox，所以「每个 Sandbox 一次」和「每 Attempt」重合。声明复用之后两者分开，见[复用 Sandbox](/zh/tutorials/sandbox-reuse)。
 
 大多数 Fixture 不需要 `teardown`——写进 Sandbox 的起始文件、装的依赖随 Sandbox 销毁自动没了。需要 `teardown` 的是**Sandbox 外**的 Fixture：在共享外部服务里为这个 Attempt 建的临时资源（临时 repo、bucket、队列 topic），不收就泄漏。
 
 同一条评估用例的多个 Attempt（`attempts` 大于 1、或同批多个实验跑同一条评估用例）并发执行且共享同一个模块，`setup` 的句柄不能放进普通模块变量——会被后一个并发 Attempt 覆写。以 `sandbox` 实例作键存取（`WeakMap`）：sandbox 与 Attempt 一一对应，天然是 per-attempt 键：
 
 ```ts
-// evals/pr-review/close-stale.eval.ts
+// evals/pr-review/close-outdated.eval.ts
 import { defineEval } from "niceeval";
 import type { Sandbox } from "niceeval/sandbox";
 
@@ -204,18 +204,18 @@ const fixtures = new WeakMap<Sandbox, { repoUrl: string; destroy(): Promise<void
 export default defineEval({
   async setup(sandbox, ctx) {
     ctx.progress({ message: "seeding fixture repo" });
-    const fixture = await createFixtureRepo("pr-review/close-stale"); // 沙箱外的临时资源
+    const fixture = await createFixtureRepo("pr-review/close-outdated"); // Sandbox 外的临时资源
     fixtures.set(sandbox, fixture);
     await sandbox.runCommand("git", ["clone", fixture.repoUrl, "workspace"]);
   },
   async teardown(sandbox) {
     await fixtures.get(sandbox)?.destroy(); // setup 抛错也会进来：没建成就跳过
   },
-  async test(t) { /* 驱动 agent 清理 stale PR，断言 */ },
+  async test(t) { /* 驱动 agent 清理过期 PR，断言 */ },
 });
 ```
 
-`teardown` 当且仅当这条 Attempt 走到过 `setup` 的时点才执行——`setup` 抛错不豁免，收尾代码要对可能没建成的资源做防御。`teardown` 抛错或超过 30 秒清理上限只记 `teardown-failed` 诊断，不改变这个 Attempt 已经产出的判定；要让某个收尾动作影响结论，在 `setup` / `test` 里抛错，不要指望 `teardown` 能改判。
+`teardown` 当且仅当这条 Attempt 走到过 `setup` 的时点才执行——`setup` 抛错不豁免，收尾代码要对可能没建成的资源做防御。`teardown` 抛错或超过 30 秒清理上限只记 `teardown-failed` 诊断，不改变这个 Attempt 已经产出的判定。要让某个收尾动作影响结论，在 `setup` / `test` 里抛错，不要指望 `teardown` 能改判。
 
 ## 命名约定