niceeval 0.13.2-canary.35 → 0.13.2

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

@@ -1,7 +1,7 @@
 ---
 title: "Coding Agent 从零接入项目"
 sidebarTitle: "Coding Agent 从零接入"
-description: "给 Coding Agent 的完整接入流程：探索项目、与用户确认路径、配置 Judge、写出 Adapter / Experiment / 评估用例并跑通第一个实验。"
+description: "给 Coding Agent 的完整接入流程：探索项目、与用户确认路径、配置 Judge、写出 Adapter、Experiment 与评估用例，并跑通第一个实验。"
 ---
 
 这一页是 Coding Agent 把 NiceEval 接入一个项目的执行步骤。前提：`niceeval` 依赖已经装进项目、`niceeval init` 已经运行，你是从随包 `INDEX.md` 进入本页的。用用户的语言与用户交流。所有 API、字段和 CLI 行为以随包文档为准，不要凭训练记忆现编。
@@ -14,10 +14,10 @@ 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` 协议。问用户手上有哪个服务的 key、想用什么 Judge 模型。缺 key 不会静默通过：Judge Assertion 会记为 `unavailable`；它参与 Pass grading，或在 Score Eval 中配置了 `.score()` / `.orStop()` 时，Attempt 的 grading 不可用。没有 Judge 配置时，先只写精确 Match。
+5. **Judge 用什么**：语义评估（`t.judge.autoevals.*`）要一个**与被测 Agent 分离的 Judge 模型**，走 OpenAI 兼容的 `/chat/completions` 协议。问用户手上有哪个服务的 key、想用什么 Judge 模型。缺 key 不会静默通过：Judge Assertion 会记为 `unavailable`；它参与 Pass grading，或在计分制评估中配置了 `.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)。
+   默认建议 `dockerSandbox({ source: { type: "image", image: "node:24-slim" } })`，但**要先跟用户确认**——本机/CI 有没有 Docker、要不要 Vercel Sandbox 或其它远程 Provider。用户没有异议就默认走 Docker。Provider 声明在评估用例或 Experiment 上，没有 CLI flag、项目级默认值或自动探测——见[选择 Sandbox Provider](/zh/tutorials/sandbox-providers)。
 
 探完之后，向用户**介绍接入等级**并给出推荐（详见[接入等级](/zh/explanation/tier)）：
 
@@ -59,9 +59,9 @@ export default defineConfig({
 三个要提醒用户的点：
 
 - **配错不会假装通过。** 模型或 key 解析不到、网关拒绝鉴权、评估请求超时时，Judge Assertion 记为 `unavailable` 并带上原因；读取面不会把缺失 measurement 伪装成 mismatch 或零分。
-- **配完先验一次。** 写一条带 `judge: true` 的轻量 Pass Eval，调用 `turn.judge.autoevals.closedQA(...).gate(0.8)`。跑完 `niceeval show <评估用例 id>`，确认能看到 measurement、threshold、condition 与 Assertion 证据。
+- **配完先验一次。** 写一条带 `judge: true` 的轻量通过制评估，调用 `turn.judge.autoevals.closedQA(...).gate(0.8)`。跑完后用 `niceeval show --run <run-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)。
+- Judge 模型要**与被测 Agent 分离**，避免同一个模型给自己的输出打分。配置按评估用例、Experiment、项目配置逐字段解析；三种 recipe 见 [Judge](/zh/explanation/judge)。
 
 ## 第 3 步：写三件套
 
@@ -100,7 +100,7 @@ export default defineConfig({
 - [ ] 有 key 时 Judge 已配置，且在 `niceeval view` 里看到过 Judge 分数。没 key 时总结里说明了
 - [ ] Experiment 里声明的 `model` / `flags` 确实被 Adapter 消费（没有写了没人读的死配置，也没有编造被测系统不存在的 model 值）
 
-跑通之后先总结，再谈下一步。总结要说清：接了什么被测对象、生成了哪几个文件（Adapter / Experiment / 评估用例各在哪）、`niceeval exp <实验路径>` 和 `niceeval view` 怎么跑、第一次运行的结果是什么样。不要在没被要求的情况下顺手重构用户已有代码，也不要在这几个文件之外新增抽象。
+跑通之后先总结，再谈下一步。总结要说清：接了什么被测对象、Adapter、Experiment 与评估用例各在哪、`niceeval exp <实验路径>` 和 `niceeval view` 怎么跑、第一次运行的结果是什么样。不要在没被要求的情况下顺手重构用户已有代码，也不要在这几个文件之外新增抽象。
 
 ## 第 6 步：问用户要不要往深了接
 

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

@@ -10,6 +10,7 @@ import { Lifecycle } from '/snippets/widgets.jsx';
 
 ```ts
 import { defineEval, type JsonValue } from "niceeval";
+import type { SandboxLayer } from "niceeval/sandbox";
 
 export default defineEval({
   description?: string;
@@ -17,34 +18,29 @@ export default defineEval({
   judge?: JudgeConfig;
   reporters?: Reporter[];
   timeoutMs?: number;
-  environment?: string;
+  sandbox?: SandboxLayer;
   metadata?: Record<string, JsonValue>;
   async setup(sandbox, ctx) { /* task fixture + progress/diagnostic */ },
   async test(t) { /* interactions + assertions */ },
 });
 ```
 
-## `tags` 与 `environment`
+## `tags` 与 `sandbox`
 
 ```ts
+import { defineEval } from "niceeval";
+import { dockerSandbox } from "niceeval/sandbox";
+
 // evals/coding/fix-button.eval.ts → id: coding/fix-button
 export default defineEval({
   description: "修复 Button 组件",
   tags: ["coding", "frontend"],
-  environment: "node-22",
+  sandbox: dockerSandbox({ source: { type: "image", image: "node:22-slim" } }),
   async test(t) { /* coding task */ },
 });
-
-// evals/research/gpu-literature.eval.ts → id: research/gpu-literature
-export default defineEval({
-  description: "在 GPU 环境检索论文",
-  tags: ["research"],
-  environment: "gpu",
-  async test(t) { /* research task */ },
-});
 ```
 
-`tags` 可供 `--tag` 和 experiment 的 `evals` 谓词读取。`environment` 只声明环境 profile。具体 image / template 由 experiment 使用的 Sandbox 配置映射。
+`tags` 可供 `--tag` 和 Experiment 的 `evals` 谓词读取。任务本身拥有起始环境时，在评估用例上声明 `sandbox`；如果 template-bearing Sandbox layer 由 Experiment 提供，这里就省略。每个实际评估用例 × Experiment 配对必须恰好有一方提供 template-bearing layer。
 
 ## 单轮评估
 
@@ -117,7 +113,7 @@ export default rows.map((row) =>
 
 ## Sandbox workspace
 
-Coding-agent 评估用例仍然是普通 `.eval.ts` 文件，只是 test 里会准备 Sandbox workspace、发送任务并检查文件结果：
+Coding Agent 评估用例仍然是普通 `.eval.ts` 文件，只是 test 里会准备 Sandbox workspace、发送任务并检查文件结果：
 
 ```ts
 import { defineEval } from "niceeval";

package/docs-site/zh/tutorials/ci-integration.mdx

@@ -8,7 +8,7 @@ CI 运行 Experiment 时，进程退出状态决定门禁是否通过。`--json`
 
 ## 基本命令
 
-只要存在 mismatched 的 Boolean condition、低于阈值的 measurement 或执行错误，[NiceEval](https://niceeval.com/) 就以非零状态码退出。需要阻止合并的要求直接写在评估用例源码中，CI 与本地运行读取同一套判定。
+只要存在 mismatched 的 Boolean condition、低于明确 `.gate(n)` 阈值的 measurement 或执行错误，[NiceEval](https://niceeval.com/) 就以非零状态码退出。`.atLeast(n)` 只记录局部 condition，本身不改变判定或退出状态。需要阻止合并的要求直接写在评估用例源码中，CI 与本地运行读取同一套判定。
 
 ```sh
 npx niceeval exp ci --json --junit ./artifacts/niceeval-junit.xml
@@ -36,11 +36,11 @@ JUnit 和外部平台文件不拥有 Record。Verdict、Usage、断言和诊断
     exit "${PIPESTATUS[0]}"
 
 - name: 上传 JUnit
-if: always()
-uses: actions/upload-artifact@v4
-with:
-  name: niceeval-junit
-  path: ./artifacts/niceeval-junit.xml
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: niceeval-junit
+    path: ./artifacts/niceeval-junit.xml
 ```
 
 将模型凭据作为 CI secret 注入命令运行所需的变量。不要把凭据写入 Experiment、receipt、JUnit 或日志。

package/docs-site/zh/tutorials/compare-runs.mdx

@@ -0,0 +1,61 @@
+---
+title: "比较多个固定 Run"
+sidebarTitle: "比较多个 Run"
+description: "用明确 Run ID 固定比较分母，核对结果覆盖，再比较通过率、得分、成本与时长，而不让新结果改变已打开的比较。"
+---
+
+比较模型、提示词或 Agent 版本时，先固定要看的 Run。不要用“最新结果”代替实验边界；新 Run 发布后不应悄悄改变已经开始的比较。
+
+## 取得每次运行的 Run ID
+
+TTY 完成反馈会显示 Run ID。机器流程从 `exp --json` 最后一条 receipt 读取 `runIds`：
+
+```sh
+pnpm exec niceeval exp baseline --json > baseline.ndjson
+pnpm exec niceeval exp candidate --json > candidate.ndjson
+```
+
+保留这两个固定 ID。它们定义比较使用的计划与 expected-slot 分母。
+
+## 先分别核对结果覆盖
+
+```sh
+pnpm exec niceeval show --run <baseline-run-id>
+pnpm exec niceeval show --run <candidate-run-id>
+```
+
+先看每个 Run 有多少位置是已执行、自动沿用、人工采用、未派发或中断。结果覆盖不足时，不要把缺失位置当成失败、零分或成功。
+
+如果一个 Run 因预算、首过即停或部分采用留下 `not-dispatched`，应先决定补跑、接受不完整分母，还是只比较两边共同且明确的范围。
+
+## 在同一个固定选择中比较
+
+```sh
+pnpm exec niceeval show \
+  --run <baseline-run-id> \
+  --run <candidate-run-id>
+```
+
+浏览器需要完整页面时使用同一组参数：
+
+```sh
+pnpm exec niceeval view \
+  --run <baseline-run-id> \
+  --run <candidate-run-id>
+```
+
+通过制评估比较通过率，计分制评估比较 earned score。混合 Experiment 分别保留两种主读数，不把它们合成一个百分比。
+
+成本和时长只在有完整 Observability 时比较。缺失、部分采集或不支持的数据必须保持可见，不能填成零。
+
+## 下钻差异来源
+
+从 Run 页面复制 Attempt locator：
+
+```sh
+pnpm exec niceeval show @1K1P0VJAPVJ12
+```
+
+详情页用于核对 Assertion、Judge 理由、工具调用、用量、时间和 File Changes。Run 页面解释本次位置为何使用该 Attempt；Attempt 页面解释这次执行实际发生了什么。
+
+需要自定义分组、成本 Profile 或专用页面时，继续阅读[编写自定义报告](/zh/tutorials/custom-reports)。

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

@@ -65,7 +65,7 @@ import { Picker, Schedule } from '/snippets/widgets.jsx';
 | --- | --- | --- | --- |
 | 全局并发位 | `--max-concurrency`，或 `niceeval.config.ts` 的 `maxConcurrency` | 本次运行的总吞吐 | 各算各的，两个终端的值相加 |
 | 实验并发上限 | 实验文件的 `maxConcurrency` | 这一个实验同时跑几条 | 各算各的，两个终端的值相加 |
-| 共享状态租约 | 实验文件的 `sharedState.key` | 同一 checkpoint 的完整恢复、执行与回存 | 同 key 的窗口串行 |
+| 共享状态租约 | 实验文件的 `sharedState.key` | 同一 checkpoint 的完整恢复、执行与回存区间 | 同 key 的区间串行 |
 
 全局值的解析顺序是 `--max-concurrency` → 配置里的 `maxConcurrency` → 当前 Sandbox Provider 的推荐默认值（`docker` 10、`e2b` 20、`vercel` 1、`local` 1）。推荐值反映的是 Provider 侧的约束。你自己 Agent 接口的限速用 `--max-concurrency` 压。
 
@@ -147,10 +147,11 @@ export default defineExperiment({
 });
 ```
 
-`maxConcurrency: 1` 只串行本 Invocation 的 Attempt。`sharedState.key` 才跨终端保护同一 checkpoint。
-租约在 Experiment 和 Sandbox 的 `setup` 之前取得，到 Sandbox `teardown`、Provider finalizer 与 Experiment `teardown` 完成后才释放。等待方不创建 Sandbox。租约释放后，等待方继续自己的既定计划；它不读取或沿用另一 Record 的结果。
+`maxConcurrency: 1` 只串行本 Invocation 的 Attempt。`sharedState.key` 会在同一项目 Coordination 域内保护跨 Invocation 的同一 checkpoint。租约在 Experiment 与 Sandbox `setup` 前取得，直到 Sandbox `teardown`、Provider finalizer 和 Experiment `teardown` 全部完成才释放。等待方不会提前创建 Sandbox；拿到租约后继续自己的计划，不读取或沿用另一个 Run 的结果。
 
-`sharedState` 只做互斥，不替你存 checkpoint，也不能回滚强杀前的半次写入。做不到原子回存时，换新 key 和干净 cohort 从头重建。
+`sharedState` 只提供互斥，不负责 checkpoint 存储、原子提交、回滚或强杀后的半次写入恢复。能原子回存时应原子回存，否则换新 key，从干净 cohort 重建。跨机器协调仍归外部编排。
+
+NiceEval 不会根据超时、PID 或 heartbeat 自动接管租约。原 owner 暂停时仍然拥有租约；强杀或 cleanup 失败后，等待方继续阻塞，避免两条 Invocation 同时改同一份状态。确认原 owner 已终止、外部状态已静止后，按[运行被强杀后恢复](/zh/troubleshooting/recover-after-kill#恢复共享状态租约)里的公开命令检查 owner token，并显式恢复。
 
 只有一个 Agent 服务频繁限流时，同样在这个实验上设 `maxConcurrency: N`，不要去降全局上限——降全局会连累同批其它实验。实验级并发上限退避时不放行第 N+1 条，所以服务不会在已经限流时继续被加压。
 
@@ -170,7 +171,7 @@ const fixtures = new WeakMap<Sandbox, { repoUrl: string; destroy(): Promise<void
 Attempt，并复用至多一台 Sandbox；不同组和未分组评估用例继续竞争剩余并发位。你不需要把
 整个 Experiment 设成 `maxConcurrency: 1`。
 
-`evals` 数组只声明成员，不声明业务顺序。Runner 按规范化 Eval ID 稳定串行；
+`evals` 数组只声明成员，不声明业务顺序。Runner 按规范化评估用例 ID 稳定串行；
 `attempts > 1` 时，同一成员需要真实派发的各次 Attempt 连续进入组内泳道。完整目录、
 Experiment 写法和 `--dry` 输出见[用评估组复用 Sandbox](/zh/tutorials/eval-groups)。
 
@@ -195,23 +196,23 @@ export default defineExperiment({
 });
 ```
 
-## 多开终端时隔离 Record
+## 多开终端时共用 Record
 
-同一 Record root 不支持两条 Invocation 自动分工。确认本机、Provider 和 Agent 服务还有余量时，为第二个终端指定不同 root：
+同一 Record root 允许多个 append writer 并发，但不会让两条 Invocation 自动分工。确认本机、Provider 和 Agent 服务还有余量时，两个终端可以使用同一个 root：
 
 ```bash
-niceeval exp compare --record .niceeval/record-a --max-concurrency 2
-niceeval exp compare --record .niceeval/record-b --max-concurrency 2
+niceeval exp compare --record .niceeval/record --max-concurrency 2
+niceeval exp compare --record .niceeval/record --max-concurrency 2
 ```
 
-两边各自规划完整选择，可能重复执行相同评估用例，也不会读取或携入对方运行中的 Attempt。每个 root 独立产生 Run、Sample 和 Report；NiceEval 不自动合并它们。
+两边各自规划完整选择，可能重复执行相同评估用例，因为双方都不会读取对方尚未发布的 Attempt。完整 Run 会原子发布到共享 Record。只有确实需要隔离 Run、Sample 与 Report 时才使用不同 root；NiceEval 不自动合并分开的 root。
 
 三个边界：
 
 - 两边的 CLI 上限会相加，Provider 容量不会。配额紧张时把两边都调低。
 - 实验自己的 `maxConcurrency` 也是每个终端各算各的：两条命令都声明 3 时，合计最多跑六条。
-- 两个终端的 Sandbox 池也各自独立。只有确实共享外部 checkpoint 时才声明 `sharedState.key`；这不会合并 Record。
-- 指向同一 root 的第二条命令立即失败，不等待、不接管，也不读取第一条命令的中间数据。
+- 两个终端的 Sandbox 池也各自独立。只有确实共享外部 checkpoint 时才声明 `sharedState.key`；它不会合并 Record。
+- 并发 append writer 可以共用 root。Record maintenance 仍然独占；遇到 `record-maintenance-busy` 时，先停掉 reader 和 writer 再重试。
 
 ## 边界
 

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

@@ -15,7 +15,7 @@ import { ConfigLayers } from '/snippets/diagram-config-layers.jsx';
 
 ## 配置：想让这个值活多久，就写在哪一层
 
-同一个值出现在多层时，按 **CLI flag → experiment → eval → config → 内置默认** 取，前面有值就不看后面。config 是默认来源，不是覆盖层——评估用例自己声明的 `timeoutMs` 不会被项目默认压掉。
+同一个值出现在多层时，按 **CLI flag → experiment → 评估用例 → config → 内置默认** 取，前面有值就不看后面。config 是默认来源，不是覆盖层——评估用例自己声明的 `timeoutMs` 不会被项目默认压掉。
 
 <ConfigLayers />
 
@@ -79,10 +79,8 @@ export default defineConfig({
 | --- | --- | --- |
 | `ANTHROPIC_API_KEY` | `claudeCodeAgent()` | 工厂参数 `apiKey` 可覆盖 |
 | `ANTHROPIC_BASE_URL` | `claudeCodeAgent()` | 网关地址，工厂参数 `baseUrl` 可覆盖 |
-| `CODEX_API_KEY` | `codexAgent()` | 不是 `OPENAI_API_KEY`。工厂参数 `apiKey` 可覆盖 |
-| `CODEX_BASE_URL` | `codexAgent()` | OpenAI 兼容代理地址，工厂参数 `baseUrl` 可覆盖 |
-| `BUB_API_KEY` | `bubAgent()` | 工厂参数 `apiKey` 可覆盖 |
-| `BUB_API_BASE` | `bubAgent()` | 工厂参数 `apiBase` 可覆盖 |
+| `OPENAI_API_KEY` | `codexAgent()`、`bubAgent()` | 工厂参数 `apiKey` 可覆盖 |
+| `OPENAI_BASE_URL` | `codexAgent()`、`bubAgent()` | OpenAI 兼容代理地址，工厂参数 `baseUrl` / `apiBase` 可覆盖 |
 | `OPENCLAW_API_KEY` / `OPENCLAW_BASE_URL` | `openClawAgent()` | key 省略时回落 `ANTHROPIC_API_KEY` |
 | `OPENCODE_API_KEY` / `OPENCODE_BASE_URL` | `openCodeAgent()` | key 省略时回落 `ANTHROPIC_API_KEY` |
 | `HERMES_API_KEY` / `HERMES_API_BASE` | `hermesAgent()` | key 省略时依次回落 `OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY` |
@@ -148,7 +146,7 @@ NICEEVAL_JUDGE_KEY=sk-...
 | Judge 模型与端点 | config 或评估用例的 `judge.model` / `judge.baseUrl` |
 | OTel 接收地址 | config 的 `telemetry: { host, port }` |
 
-Judge 的 key 只从 `NICEEVAL_JUDGE_KEY`（或 `judge.apiKeyEnv` 指定的变量）读，端点只从 `judge.baseUrl` 读。被测应用把标准的 `OPENAI_*` 挪作它用时，Judge 不会跟着串味。
+Judge 默认从 `NICEEVAL_JUDGE_KEY` 读取 key，也可以改读 `judge.apiKeyEnv` 指定的变量；端点只从 `judge.baseUrl` 读。它不会借用被测应用的 `OPENAI_API_KEY`。
 
 ## 接着看
 

package/docs-site/zh/tutorials/connect-your-agent.mdx

@@ -18,7 +18,7 @@ description: "写一个 Adapter、配置一个 Experiment，并运行第一条
     评估 Claude Code / Codex / bub 这种独立的 Agent：用内置 Sandbox Agent。
   </Card>
   <Card title="其它 AI Agent" icon="plug">
-    自己的 Agent 需要 [编写 Send](/zh/tutorials/write-send)。如应用已有 OTel 埋点，可 [接入OTel ](/zh/tutorials/connect-otel)
+    自己的 Agent 需要 [编写 Send](/zh/tutorials/write-send)。如应用已有 OTel 埋点，可[接入 OTel](/zh/tutorials/connect-otel)。
   </Card>
 </CardGroup>
 

package/docs-site/zh/tutorials/control-run-cost.mdx

@@ -0,0 +1,58 @@
+---
+title: "控制一次运行的成本"
+sidebarTitle: "控制运行成本"
+description: "用 attempts、首过即停、budget、并发和结果沿用分别控制统计样本、停止派发、花费保护与资源占用。"
+---
+
+控制成本前先判断你要减少什么。不同开关回答不同问题，不能互相替代。
+
+| 目标 | 使用方式 |
+| --- | --- |
+| 测完整稳定性分布 | 设置 `attempts: N`，默认跑满。 |
+| 只确认至少能成功一次 | 使用 `--early-exit`。 |
+| 给每个 Experiment 的花费加保护 | 使用 `--budget <美元>`。 |
+| 限制同时占用的资源 | 使用 `--max-concurrency <数量>`。 |
+| 跳过没有受影响的结果 | 使用默认沿用或 `--rerun`。 |
+| 分摊 Sandbox 创建和准备成本 | 使用 `sandboxReuse`。 |
+
+## 先预览运行矩阵
+
+```sh
+pnpm exec niceeval exp regression --dry
+```
+
+先确认评估用例数量、Experiment 数量和 Attempt 数量。`--dry` 不预测最终模型费用，但能在派发前发现范围选错或重复次数过大。
+
+## 只关心能否成功时首过即停
+
+```sh
+pnpm exec niceeval exp regression --early-exit
+```
+
+某条评估用例的一个 Attempt 得到 `passed` 后，尚未派发的剩余 Attempt 会写成 `not-dispatched`。同一评估用例已经在运行的 Attempt 会通过 `ctx.signal` 收到取消信号；Adapter 是否及时观察它，决定这个 Attempt 能否尽快结束。
+
+一次通过触发首过即停后才返回的同一评估用例 Attempt 不会进入结果。
+
+`failed`、`errored` 或 `skipped` 不触发首过即停。需要完整通过率分布时不要打开这个选项。
+
+## 给花费设置保护上限
+
+```sh
+pnpm exec niceeval exp regression --budget 25
+```
+
+预算按每个 Experiment ID 分别计算。每条已完成的 Attempt，NiceEval 从 Experiment 的 `model`、上报的 token 用量和 Config/runtime price table 推得 `estimatedCostUSD`，再把这个估算累加进预算。`usage.costUSD` 是 Provider 或 Adapter 上报的 observed 值，绝不驱动预算。累计 estimate 到达上限后，NiceEval 停止派发新 Attempt；已经在运行的任务不会被中途终止。
+
+因此 `--budget` 是保护上限，不是精确账单。并发任务尚未结算时，最终花费可能短暂超过设置值。缺少 model、token 用量或匹配的价格时，NiceEval 无法产生 `estimatedCostUSD`，`usage.costUSD` 也不能补上。Runner 会给出警告，而不是假装预算仍可执行。
+
+预算耗尽会留下 `budget_exhausted` diagnostic，未派发位置写成 `not-dispatched`，命令以非零状态退出。提高预算后重跑同一范围，合格的已完成 Attempt 会沿用，只补剩余位置。
+
+## 并发只控制资源占用
+
+```sh
+pnpm exec niceeval exp regression --max-concurrency 4
+```
+
+并发上限限制同时运行的评估用例，不是费用上限。费用保护仍使用 `--budget`。Sandbox 构建并发由独立的 `--max-build-concurrency` 控制。
+
+需要进一步分摊环境准备成本时，阅读[复用 Sandbox](/zh/tutorials/sandbox-reuse)。需要选择只重跑失败项或全部重验时，阅读[重跑与沿用结果](/zh/tutorials/rerun-and-cache)。

package/docs-site/zh/tutorials/criteria-files.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "隐藏测试判分"
 description: "用 loadText 在模块顶层读入隐藏测试、跑测脚本等判据文件，文件内容进入 fingerprint：改一字节自动重跑，不靠人工 --rerun。"
 ---
 
-沙箱 coding 题常用一份隐藏测试判分：Agent 改完代码后，评估用例把测试文件写进 Sandbox 执行，
+Sandbox Coding 任务常用一份隐藏测试判分：Agent 改完代码后，评估用例把测试文件写进 Sandbox 执行，
 测试通过就算过。这份测试文件就是判分标准本体——改了它，等于换了一道题，旧结果不能再采信。
 
 用 `loadText` 读它，NiceEval 会把文件内容算进这条评估用例的 fingerprint：
@@ -63,6 +63,6 @@ description: "用 loadText 在模块顶层读入隐藏测试、跑测脚本等
 - **`loadText` 必须写在模块顶层。** 缓存判断发生在运行之前，写进 `test(t)` 里运行期才读就来不及了，
   NiceEval 会直接报错并提示挪到顶层。
 - **读 Agent 的产物用 `t.sandbox`，不用 `loadText`。** Sandbox 里 Agent 跑出来的文件是本次运行的证据，
-  每次都不同，不属于 fingerprint。用 `t.sandbox.file(...)` 一类断言去读。
+  每次都不同，不属于 fingerprint。用 `await t.sandbox.readText(path)` 读取，再把返回的字符串交给 `t.check`。
 - 判据是结构化数据（case 对照表）时用 `loadYaml` / `loadJson`，
   见[数据驱动测试](/zh/tutorials/dataset-fanout)。

package/docs-site/zh/tutorials/custom-reports.mdx

@@ -134,8 +134,8 @@ const pricing = definePricingProfile({
 ```
 
 在组件中只调用 `costUSD(pricing)` 或 `totalCostUSD(pricing)`；二者没有零参数形式。Analysis 计算 slot-provider ledger、exact total 和
-`numerator / denominator` mean，Report Host 只验证 Profile、捕获闭包和呈现结果。Runner `estimatedCostUSD` 即使 observed 成本存在也独立计算，
-只供 `maxCost` 使用，Report 不读取它。
+`numerator / denominator` mean，Report Host 只验证 Profile、捕获闭包和呈现结果。Runner `estimatedCostUSD` 即使 observed 成本存在也独立计算；
+Experiment budget 与 `maxCost` 使用它，Report 不读取它。
 
 `aggregate(ctx.scope, { values: { cost: costUSD(pricing) } })` 的 `cost` cell 是可观察的 `CostMetricValue`，其 `cell.projection` 是
 `CostProjectionValue`。这两个类型以及 projection 的 state、basis、ledger 和 reason data types 都从 `niceeval/report` 以 type-only

package/docs-site/zh/tutorials/debug-lifecycle-plan.mdx

@@ -0,0 +1,46 @@
+---
+title: "运行前检查生命周期计划"
+sidebarTitle: "检查生命周期计划"
+description: "用 niceeval debug 查看一个 Experiment 与评估用例配对的 Plugin、Sandbox、Agent、Fixture 和 teardown 顺序，而不创建任何运行资源。"
+---
+
+`exp --dry` 适合确认运行矩阵。需要检查一条评估在 Sandbox 里会按什么顺序准备、安装、执行和收尾时，使用 `niceeval debug`。
+
+## 选择一个精确配对
+
+```sh
+pnpm exec niceeval debug compare/codex memory/commit0
+```
+
+Experiment 和评估用例 selector 都必须唯一。精确 ID 优先；前缀命中多个候选时，CLI 会列出候选并停止。
+
+评估用例只能从该 Experiment 已选择的范围中匹配。选择一个评估组成员不会把其它成员加入计划，但输出仍会显示评估组生命周期包裹。
+
+## 按顺序阅读计划
+
+计划会依次显示：
+
+1. Plugin lifecycle；
+2. 作者声明的 prepare；
+3. Agent ensure、setup 与 teardown；
+4. Sandbox materialize 与 Provider finalizer；
+5. 评估组和物理 Sandbox lifecycle；
+6. Fixture、test 与 cleanup。
+
+静态 `shell()` 和 `command()` 会展开实际命令。普通 callback 标为 `Opaque`，因为它只能在运行时执行。路径、凭据、环境变量值和不安全的远端 locator 不会泄露到 Human 输出。
+
+## 给工具读取结构化计划
+
+```sh
+pnpm exec niceeval debug compare/codex memory/commit0 --json > debug-plan.json
+```
+
+JSON 保留结构化步骤和精确度标记，不包含终端框线。`debug` 只接受 `--json`；预算、重跑、并发等运行 flag 不适用于这个命令。
+
+## 确认它不会执行资源操作
+
+`debug` 不运行 setup、test、teardown、ensure、materialize 或 finalizer，也不创建 Invocation、Run、Record、锁、Sandbox 或构建任务。
+
+它会加载受信任定义并执行 Experiment 的选择 predicate。Provider planner 也可能读取本地文件、调用只读 CLI 或查询远端控制面，因此仍应只在可信项目中运行。
+
+矩阵和 Attempt 数量先用[选择并预览运行范围](/zh/tutorials/select-and-preview)确认。真实执行失败后需要进入保留现场时，使用[保留 Sandbox 现场排查问题](/zh/troubleshooting/debug-sandbox)。