niceeval 0.13.1 → 0.13.2

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)。

package/docs-site/zh/tutorials/docker-in-docker.mdx

@@ -4,28 +4,28 @@ sidebarTitle: "Docker 与 DinD"
 description: "根据任务信任边界选择 Docker socket、raw privileged DinD 或受管 rootless DinD，并为 Agent 准备 Docker CLI 与 daemon。"
 ---
 
-当评估任务要求 Agent执行 `docker build`、`docker run`或 `docker compose`时，先按任务的信任边界
+当评估任务要求 Agent 执行 `docker build`、`docker run` 或 `docker compose` 时，先按任务的信任边界
 选择 Docker access：
 
 | 模式 | 什么时候用 | 启动成本 | 安全边界 |
 | --- | --- | --- | --- |
-| Docker socket | 可信 Agent、个人开发机、已有 daemon，优先启动速度 | 最低，共用已有 daemon | Agent拥有该 daemon的完整控制权。rootful socket通常等价宿主 root |
-| Raw privileged DinD | 一次性 VM或专用 runner，需要独立 image、network和 cache | 每个 Sandbox启动 inner daemon | outer container是 raw privileged，不是安全隔离方案 |
-| Managed rootless DinD | 不可信 Agent、共享宿主、并发评估、需要资源准入和强杀恢复 | 最高，需要宿主 profile | privileged限制在受管 rootless user namespace或专用 VM，并有 watchdog与容量契约 |
+| Docker socket | 可信 Agent、个人开发机、已有 daemon，优先启动速度 | 最低，共用已有 daemon | Agent 拥有该 daemon 的完整控制权。rootful socket 通常等价宿主 root |
+| Raw privileged DinD | 一次性 VM 或专用 runner，需要独立 image、network 和 cache | 每个 Sandbox 启动 inner daemon | outer container 是 raw privileged，不是安全隔离方案 |
+| Managed rootless DinD | 不可信 Agent、共享宿主、并发评估、需要资源准入和强杀恢复 | 最高，需要宿主 profile | privileged 限制在受管 rootless user namespace 或专用 VM，并有 watchdog 与容量契约 |
 
-三种模式都要求镜像预装 Docker CLI。两种 DinD模式只接受从官方
-`docker:<version>-dind`派生的兼容镜像。镜像需要 Docker daemon、Node和评估工具，
-但不需要自定义 NiceEval `ENTRYPOINT`。NiceEval负责启动与监督 inner daemon、
-Sandbox保活、容器内 TTL和 `docker info`探活，不会向任意镜像动态安装 Docker。
+三种模式都要求镜像预装 Docker CLI。两种 DinD 模式只接受从官方
+`docker:<version>-dind` 派生的兼容镜像。镜像需要 Docker daemon、Node 和评估工具，
+但不需要自定义 NiceEval `ENTRYPOINT`。NiceEval 负责启动与监督 inner daemon、
+Sandbox 保活、容器内 TTL 和 `docker info` 探活，不会向任意镜像动态安装 Docker。
 
-不能直接把未经派生的 `docker:<version>-dind`写成 `source.image`。该镜像没有 NiceEval supervisor
-需要的 Node，也没有被测 Agent的工具。创建时会以
-`dind-image-incompatible: missing node`失败。请使用下面的 Dockerfile，或先发布等价的派生镜像，
-再让 `source`引用它。
+不能直接把未经派生的 `docker:<version>-dind` 写成 `source.image`。该镜像没有 NiceEval supervisor
+需要的 Node，也没有被测 Agent 的工具。创建时会以
+`dind-image-incompatible: missing node` 失败。请使用下面的 Dockerfile，或先发布等价的派生镜像，
+再让 `source` 引用它。
 
 ## 方案一：直接挂 Docker socket
 
-先准备只有 CLI、Node和评估工具的镜像：
+先准备只有 CLI、Node 和评估工具的镜像：
 
 ```dockerfile title="sandbox/Dockerfile"
 FROM docker:29-cli
@@ -35,7 +35,7 @@ RUN apk add --no-cache ca-certificates git nodejs npm python3 \
   && adduser -D -u 1000 -G node node
 ```
 
-在 Experiment里显式填写宿主 Unix socket。NiceEval不会从进程环境或 Docker context猜这个路径：
+在 Experiment 里显式填写宿主 Unix socket。NiceEval 不会从进程环境或 Docker context 猜这个路径：
 
 ```ts title="experiments/docker-socket.ts"
 import { defineExperiment } from "niceeval";
@@ -59,22 +59,22 @@ export default defineExperiment({
 });
 ```
 
-NiceEval会解析 symlink、确认最终目标是 Unix socket，把它挂到 Sandbox内固定的
-`/var/run/docker.sock`，并按 socket的数值 GID给 `node`添加补充组。启动 Agent前，NiceEval会确认
-镜像没有预设 Docker endpoint或 context，而且默认 `docker info`与显式访问这个 Unix socket得到同一个
-daemon。CLI缺失、用户无法访问 socket或镜像把默认 endpoint改到别处时，Sandbox创建失败。
+NiceEval 会解析 symlink、确认最终目标是 Unix socket，把它挂到 Sandbox 内固定的
+`/var/run/docker.sock`，并按 socket 的数值 GID 给 `node` 添加补充组。启动 Agent 前，NiceEval 会确认
+镜像没有预设 Docker endpoint 或 context，而且默认 `docker info` 与显式访问这个 Unix socket 得到同一个
+daemon。CLI 缺失、用户无法访问 socket 或镜像把默认 endpoint 改到别处时，Sandbox 创建失败。
 
-这项检查只固定 Agent启动时的默认用法，不是安全边界。Agent之后仍可显式传 `docker --host`访问另一个
-endpoint。不可信任务需要依赖 managed模式的网络策略，而不是依赖 Docker CLI的默认值。
+这项检查只固定 Agent 启动时的默认用法，不是安全边界。Agent 之后仍可显式传 `docker --host` 访问另一个
+endpoint。不可信任务需要依赖 managed 模式的网络策略，而不是依赖 Docker CLI 的默认值。
 
 <Warning>
-  这不是隔离方案。Agent可以通过 socket创建 privileged容器、挂宿主目录，并操作同一 daemon上的
-  其它容器、image、volume和 network。不要给不可信 Agent挂 rootful宿主 socket。
+  这不是隔离方案。Agent 可以通过 socket 创建 privileged 容器、挂宿主目录，并操作同一 daemon 上的
+  其它容器、image、volume 和 network。不要给不可信 Agent 挂 rootful 宿主 socket。
 </Warning>
 
 ## 方案二：Docker-in-Docker
 
-DinD让每个外层 Sandbox拥有自己的 inner daemon。先创建镜像：
+DinD 让每个外层 Sandbox 拥有自己的 inner daemon。先创建镜像：
 
 ```dockerfile title="sandbox/Dockerfile"
 FROM docker:29-dind
@@ -85,7 +85,7 @@ RUN apk add --no-cache ca-certificates git nodejs npm python3 \
   && addgroup node docker
 ```
 
-生产评估应把 `FROM`钉到审核过的 digest，并把被测 Agent需要的固定 CLI烘焙进镜像。
+生产评估应把 `FROM` 钉到审核过的 digest，并把被测 Agent 需要的固定 CLI 烘焙进镜像。
 
 ### NiceEval 如何启动 DinD
 
@@ -111,15 +111,17 @@ Agent 仍以 `user: "node"` 运行。上面 Dockerfile 在构建期把 `node`
 
 ### 在 setup 中准备 Attempt 运行时
 
-Dockerfile 只烘焙固定工具、只读归档和项目初始文件。需要 inner daemon 的操作放进 Sandbox 级
-`setup`，不要放进镜像 `ENTRYPOINT`。下面的 setup 可以导入离线 image、把项目初始文件复制到可写
-workspace，并运行项目自己的 smoke check：
+Dockerfile 只烘焙固定工具和项目初始文件。需要 inner daemon 的操作放进 Sandbox 级
+`setup`，不要放进镜像 `ENTRYPOINT`。下面这个完整 setup 会创建可写 workspace 并验证 inner daemon；只有镜像确实烘焙了对应归档和文件时，才在这里加入 `docker load`、文件复制或项目 smoke-check 命令：
 
 ```ts title="lib/dind-sandbox.ts"
-import { dockerfileSandbox } from "niceeval/sandbox";
+import { dockerSandbox } from "niceeval/sandbox";
 
-export const dindSandbox = dockerfileSandbox({
-  context: new URL("../sandbox/", import.meta.url),
+export const dindSandbox = dockerSandbox({
+  source: {
+    type: "dockerfile",
+    context: new URL("../sandbox/", import.meta.url),
+  },
   user: "node",
   dockerAccess: {
     mode: "dind",
@@ -132,7 +134,11 @@ export const dindSandbox = dockerfileSandbox({
   },
 }).setup(async (sandbox, ctx) => {
   ctx.progress({ message: "准备 inner Docker 运行时" });
-  const result = await sandbox.runCommand("prepare-inner-runtime", [], {
+  const result = await sandbox.runCommand("sh", ["-lc", [
+    "set -eu",
+    "mkdir -p /workspace",
+    "docker info >/dev/null",
+  ].join("\n")], {
     user: "root",
     stream: true,
   });
@@ -148,7 +154,7 @@ Attempt 在 `sandbox.create` 阶段记为 `errored`，不会把半成品 Sandbox
 
 ### Raw privileged DinD
 
-在一次性 VM或专用 runner上，可以显式选择 raw privileged：
+在一次性 VM 或专用 runner 上，可以显式选择 raw privileged：
 
 ```ts title="experiments/dind-raw.ts"
 import { defineExperiment } from "niceeval";
@@ -172,13 +178,16 @@ export default defineExperiment({
 });
 ```
 
-必填的 `raw-privileged`字面量是风险授权。NiceEval不会把 raw模式描述成 rootless，也不会在失败时
+必填的 `raw-privileged` 字面量是风险授权。NiceEval 不会把 raw 模式描述成 rootless，也不会在失败时
 自动改用 managed profile。
 
 ### Managed rootless DinD
 
-共享宿主或不可信 Agent使用 managed模式。它在 inner daemon之外增加 profile attestation、单容器
-资源限制、跨进程容量准入、独占外层网络和 watchdog恢复：
+共享宿主或不可信 Agent 使用 managed 模式。它在 inner daemon 之外增加 profile attestation、单容器
+资源限制、跨进程容量准入、独占外层网络和 watchdog 恢复：
+
+NixOS 宿主先按照[在 NixOS 上配置 Managed DinD](/zh/tutorials/nixos-managed-dind)部署并验证 profile，
+再配置下面的 Experiment。
 
 ```ts title="experiments/dind-managed.ts"
 import { defineExperiment } from "niceeval";
@@ -226,7 +235,7 @@ export default defineExperiment({
 });
 ```
 
-profile缺失、拼错、attestation失败或容量不足时，NiceEval会在模型调用前失败，绝不降级成 raw
+profile 缺失、拼错、attestation 失败或容量不足时，NiceEval 会在模型调用前失败，绝不降级成 raw
 privileged。宿主部署完成后先检查 profile：
 
 ```bash
@@ -235,9 +244,9 @@ npx niceeval docker profile doctor default --smoke
 npx niceeval exp dind-managed
 ```
 
-`doctor --smoke`会在该 profile上启动一次 DinD容器，并实际运行内层
-`docker run --rm alpine:3.20 true`。它证明 profile支持 nested Docker，但不会检查项目自己的
-Dockerfile。项目镜像仍由默认 `docker info` readiness验证。
+`doctor --smoke` 会在该 profile 上启动一次 DinD 容器，并实际运行内层
+`docker run --rm alpine:3.20 true`。它证明 profile 支持 nested Docker，但不会检查项目自己的
+Dockerfile。项目镜像仍由默认 `docker info` readiness 验证。
 
 ### 为 DinD 设置运行并发
 
@@ -270,9 +279,9 @@ pnpm exec niceeval show @1ABC234DEF
 | Docker access compatibility timeout | 从 `niceeval show` 给出的有界 `dockerd.log` 尾部检查 daemon 启动、socket 与 storage driver |
 | 启动前提示 orphan Sandbox | 先用 `niceeval sandbox list --orphans` 只读核对，再显式运行 `niceeval sandbox prune` |
 
-## 在 Eval里验证 Docker任务
+## 在评估用例里验证 Docker 任务
 
-三种模式对 Eval暴露相同的 Docker CLI用法：
+三种模式对评估用例暴露相同的 Docker CLI 用法：
 
 ```ts title="evals/docker-compose.eval.ts"
 import { defineEval } from "niceeval";
@@ -291,5 +300,5 @@ export default defineEval({
 });
 ```
 
-socket模式的命令操作显式选择的外层 daemon。两种 DinD模式操作 Sandbox内的 inner daemon。
-`sandbox`也可以直接写在 `defineEval({ sandbox: ... })`里。多条 Eval共用配置时写在 Experiment上。
+Socket 模式的命令操作显式选择的外层 daemon。两种 DinD 模式操作 Sandbox 内的 inner daemon。
+`sandbox` 也可以直接写在 `defineEval({ sandbox: ... })` 里。多条评估用例共用配置时写在 Experiment 上。

package/docs-site/zh/tutorials/eval-groups.mdx

@@ -12,7 +12,7 @@ Sandbox，也不要为了复用而把整批任务都降成串行。`defineEvalGr
 | 你会得到什么 | 运行行为 |
 | --- | --- |
 | 公共准备少付几次 | Sandbox 创建和组级 `setup()` 每个组内实例只执行一次 |
-| 组内稳定串行 | Runner 按规范化 Eval ID 排序，同组同时只派发一条 Attempt |
+| 组内稳定串行 | Runner 按规范化评估用例 ID 排序，同组同时只派发一条 Attempt |
 | 组间保留吞吐 | 不同组和未分组评估用例可以并行 |
 | 结果仍能单独比较 | 每条 Attempt 继续拥有自己的断言、判定、用量和文件改动 |
 
@@ -69,9 +69,9 @@ export default defineEvalGroup({
 `tag` 或 `selector`。NiceEval 也不会自动收集同目录文件；成员增删和顺序变化都会明确出现在
 `eval-group.ts` 的 diff 中。
 
-`evals` 数组只声明成员，不声明业务顺序。Runner 始终按规范化 Eval ID 稳定排序；只调整
+`evals` 数组只声明成员，不声明业务顺序。Runner 始终按规范化评估用例 ID 稳定排序；只调整
 数组位置不会改变调度行为或组指纹。需要“先构建、后查询”这类结果依赖时，把两个步骤放进
-同一条 Eval。Eval Group 的业务排序 API 还没有实现。
+同一条评估用例。评估组的业务排序 API 还没有实现。
 
 `onUnavailable` 是必填策略。`"stop-group"` 在物理 Sandbox 无法创建、重置或准备时停止
 该组后续派发；`"replace-sandbox"` 会先退休当前实例，并让下一条 slot 尝试建立替代实例。
@@ -123,14 +123,14 @@ codex  workflow/01-index [group workflow]   new
 codex  workflow/02-query [group workflow]   new
 ```
 
-确认两条选中 Eval 都显示相同的组 ID 后再运行：
+确认两条选中评估用例都显示相同的组 ID 后再运行：
 
 ```bash
 npx niceeval exp codex
 ```
 
-当前调度器按规范化 Eval ID 排列成员；`attempts` 大于 1 时，同一成员的各次 Attempt 连续
-进入组内泳道，再进入下一个成员。这只是稳定的调度规则，不是跨 Eval 的数据依赖契约。
+当前调度器按规范化评估用例 ID 排列成员；`attempts` 大于 1 时，同一成员的各次 Attempt 连续
+进入组内泳道，再进入下一个成员。这只是稳定的调度规则，不是跨评估用例的数据依赖契约。
 首过即停或结果沿用没有实际派发的槽位会直接跳过。
 
 ## 把公共准备放到评估组

package/docs-site/zh/tutorials/evaluation-kinds.mdx

@@ -28,7 +28,7 @@ Boolean `matched` 进入 Verdict；`mismatched` 使最终 Verdict 为 `failed`
 
 ## 连续质量线
 
-`similarity(...)` 这类 Match 产生 `[0, 1]` 的 measurement。通过制评估用 `.gate(n)` 给它 hard 阈值：
+`similarity(...)` 这类 Match 产生 `[0, 1]` 的 measurement。它计算字符级 Levenshtein 编辑相似度，不判断语义。通过制评估用 `.gate(n)` 给它 hard 阈值：
 
 ```ts
 t.check(turn.message, similarity(expected))
@@ -44,7 +44,7 @@ t.check(turn.message, similarity(expected))
 
 ```ts
 import { defineScoreEval } from "niceeval";
-import { commandSucceeded, includes, similarity } from "niceeval/expect";
+import { commandSucceeded, includes } from "niceeval/expect";
 
 export default defineScoreEval({
   description: "安装并启动 DB-GPT",
@@ -57,7 +57,7 @@ export default defineScoreEval({
     t.check(health, commandSucceeded()).score(1).label("健康检查可达");
     t.check(health.stdout, includes("ok")).score(1).label("健康检查内容正确");
 
-    t.check(turn.message, similarity("说明安装步骤和验证结果")).score(2).label("说明质量");
+    t.check(turn.message, includes("验证")).score(2).label("回复说明验证方法");
 
     t.score(1).label("代码精简");
   },

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

@@ -84,11 +84,10 @@ pnpm exec niceeval view --experiment models
 ```ts
 evals: (eval) =>
   eval.id.startsWith("coding/") &&
-  eval.tags.includes("coding") &&
-  eval.environment !== "gpu"
+  eval.tags.includes("coding")
 ```
 
-`eval.id` 是文件路径推导出的项目内 ID，不是绝对路径，可以直接用 `startsWith` / `includes` 判断。在[评估用例](/zh/tutorials/authoring#tags-与-environment)里的两个例子中，`coding/fix-button` 会被选中，`research/gpu-literature` 不会。解析结果形成本次运行计划。报告读取实际物理 Attempts 与覆盖事实。
+`eval.id` 是文件路径推导出的项目内 ID，不是绝对路径，可以直接用 `startsWith` / `includes` 判断。在[评估用例](/zh/tutorials/authoring#tags-与-sandbox)中，`coding/fix-button` 示例同时满足两个条件。解析结果形成本次运行计划。报告读取实际物理 Attempts 与覆盖事实。
 
 ## 设计 experiment 的建议