niceeval 0.13.1 → 0.13.2

package/docs-site/zh/tutorials/handle-execution-failures.mdx

@@ -49,18 +49,26 @@ export default defineEval({
 });
 ```
 
-共享服务无法访问时，改用 `ExperimentFatalError` 停止同一实验的剩余 Attempt：
+共享服务无法访问时，把检查写进真实评估用例的 `test(t)` callback。先把
+`serviceHealthUrl` 换成服务的健康检查地址，再用 `ExperimentFatalError` 停止同一实验的剩余 Attempt：
 
 ```ts
-import { ExperimentFatalError } from "niceeval";
-
-const health = await t.sandbox.runCommand("curl", ["-fsS", serviceHealthUrl]);
-if (health.exitCode !== 0) {
-  throw new ExperimentFatalError(
-    "共享服务无法访问。请检查服务和隧道，然后重跑实验。",
-    { cause: health.stderr },
-  );
-}
+// evals/coding/shared-service-health.eval.ts
+import { defineEval, ExperimentFatalError } from "niceeval";
+
+const serviceHealthUrl = "https://service.example.test/health";
+
+export default defineEval({
+  async test(t) {
+    const health = await t.sandbox.runCommand("curl", ["-fsS", serviceHealthUrl]);
+    if (health.exitCode !== 0) {
+      throw new ExperimentFatalError(
+        "共享服务无法访问。请检查服务和隧道，然后重跑实验。",
+        { cause: health.stderr },
+      );
+    }
+  },
+});
 ```
 
 错误消息会出现在终端和运行记录中。请写明发生了什么，以及下一步怎么修复。

package/docs-site/zh/tutorials/install-custom-sandbox-agent.mdx

@@ -13,10 +13,12 @@ Node.js CLI 可以使用 `createNpmCliInstaller`。下面的代码把 npm 包 `m
 ```ts
 // agents/my-agent.ts
 import {
-  completeEvidenceCoverage,
   createNpmCliInstaller,
   defineSandboxAgent,
-  resolveAgentBin,
+  agentBin,
+  responsesEvidenceCoverage,
+  turnFromResponses,
+  type ResponseLike,
 } from "niceeval/adapter";
 
 const { ensure, installer } = createNpmCliInstaller({
@@ -36,7 +38,7 @@ const { ensure, installer } = createNpmCliInstaller({
 
 export default defineSandboxAgent({
   name: "my-agent",
-  evidenceCoverage: completeEvidenceCoverage,
+  evidenceCoverage: responsesEvidenceCoverage,
   ensure,
   installers: [installer],
 
@@ -45,16 +47,22 @@ export default defineSandboxAgent({
   },
 
   async send(input, ctx) {
-    const bin = await resolveAgentBin(ctx.sandbox, "my-agent");
-    const result = await ctx.sandbox.runCommand(bin, ["run", "--json", input.text]);
+    const result = await ctx.sandbox.runCommand("sh", [
+      "-lc",
+      `exec ${agentBin("my-agent")} run --json "$1"`,
+      "my-agent",
+      input.text,
+    ]);
     if (result.exitCode !== 0) {
       throw new Error(`my-agent 退出码 ${result.exitCode}: ${result.stderr}`);
     }
-    return parseTurn(result.stdout);
+    return turnFromResponses(JSON.parse(result.stdout) as ResponseLike);
   },
 });
 ```
 
+这个示例约定 `my-agent run --json` 输出一个 OpenAI Responses 兼容的 JSON 对象。`turnFromResponses` 会把其中的 `output` 项与 usage 转成 NiceEval 的 `Turn`；如果 CLI 输出的是另一套 schema，就把这一行替换成对 `events`、`status` 与 `usage` 的显式映射。
+
 `identity.version` 是 CLI 的精确版本。同一版本的安装步骤变化时，同时更新 `identity.revision`。不要在这里使用 `latest`。
 
 `setup` 只写鉴权和运行配置。CLI 安装由 `installer` 负责，因此每个 Attempt 都会先完成版本检查。
@@ -72,7 +80,7 @@ import myAgent from "../agents/my-agent.ts";
 export default defineExperiment({
   agent: myAgent,
   model: "acme-model-v2",
-  sandbox: dockerSandbox({ source: { type: "image", image: "debian:bookworm-slim" } }),
+  sandbox: dockerSandbox({ source: { type: "image", image: "node:22-slim" } }),
 });
 ```
 
@@ -80,7 +88,7 @@ export default defineExperiment({
 npx niceeval exp my-agent fixtures/button
 ```
 
-Sandbox 不需要 Node.js 或 npm。`createNpmCliInstaller` 在宿主机上下载 npm 包，再通过 Sandbox 的文件接口安装。Sandbox 如果已有正确版本，NiceEval 会直接使用它。
+普通 npm 包要求 Sandbox 提供 Node.js 与 npm。`createNpmCliInstaller` 在宿主机打包、上传，再在 Sandbox 内执行 `npm install -g`。Sandbox 如果已有正确版本，NiceEval 会直接使用它。只有真正自包含的 `platformPackage` 才能省掉这项运行时前置条件。
 
 ## 检查安装失败
 

package/docs-site/zh/tutorials/nixos-managed-dind.mdx

@@ -0,0 +1,160 @@
+---
+title: "在 NixOS 上配置 Managed DinD"
+sidebarTitle: "NixOS Managed DinD"
+description: "使用 NiceEval 的 NixOS module 部署 managed rootless Docker profile，并通过 doctor 验证宿主环境。"
+---
+
+Managed rootless DinD 适合在共享 NixOS 宿主上运行不可信 Agent。NiceEval 的 NixOS module 会创建专用
+系统用户、rootless Docker daemon、容量受限的数据盘、资源 slice 和 watchdog。日常运行 NiceEval
+不需要 `sudo`，但首次部署和更新系统配置需要管理员权限。
+
+如果任务可以信任 Agent，或者只在一次性 VM 中运行，先阅读[让 Sandbox 使用 Docker](/zh/tutorials/docker-in-docker)
+选择 Docker socket 或 raw privileged DinD。它们不需要本页的宿主 profile。
+
+## 前置条件
+
+开始前确认：
+
+- NixOS 使用 flake 管理系统配置；
+- 宿主使用 systemd 和 cgroup v2；
+- 你知道日常运行 NiceEval 的 NixOS 用户名；
+- 宿主有足够的 CPU、内存和磁盘留给评估容器。
+
+下面假设系统配置仓库已经有 `flake.nix`，配置名是 `my-host`，日常用户名是 `alice`。请把它们替换成
+自己的值。
+
+## 引入 NiceEval module
+
+在系统配置的 `flake.nix` 中加入 NiceEval input，并把 module 放进主机的 `modules`：
+
+```nix title="flake.nix"
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    niceeval.url = "github:NiceEval/NiceEval";
+  };
+
+  outputs = { self, nixpkgs, niceeval, ... }: {
+    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        niceeval.nixosModules.default
+        ./configuration.nix
+      ];
+    };
+  };
+}
+```
+
+第一次运行 Nix 命令后，Nix 会把 NiceEval 的具体 commit 写进你的 `flake.lock`。提交这份锁文件，避免
+不同机器在未确认的时间使用不同 module 版本。
+
+## 声明 profile
+
+在 NixOS 配置中声明一个名为 `default` 的 profile：
+
+```nix title="configuration.nix"
+{ ... }:
+{
+  services.niceeval.dockerProfiles.default = {
+    enable = true;
+    accessUsers = [ "alice" ];
+
+    capacity = {
+      cpus = 4;
+      memory = "8G";
+      pids = 4096;
+      maxContainers = 2;
+      maxBuilds = 1;
+    };
+
+    aggregate = {
+      cpus = 6;
+      memory = "12G";
+      pids = 6144;
+    };
+
+    storage = {
+      size = "30G";
+      backing = "loop-ext4";
+    };
+  };
+}
+```
+
+`capacity` 是 NiceEval 可以分配给评估任务的预算。`aggregate` 是 daemon、构建进程、watchdog 和评估
+容器共同受到的硬限制，因此每一项都不能小于 `capacity`。两者之间的余量留给宿主侧开销。
+
+`loop-ext4` 会在 `/var/lib/niceeval/docker-profiles/default.img` 创建稀疏镜像，并挂载为 Docker
+data root。`size` 是这个 profile 的磁盘上限，不代表 rebuild 时立即占用同等物理空间。
+
+## 应用系统配置
+
+先检查配置能够求值，再切换系统：
+
+```bash
+nix flake check
+sudo nixos-rebuild switch --flake .#my-host
+```
+
+module 会把 `alice` 加入 profile 的 access group。rebuild 完成后退出当前登录会话并重新登录，让新组
+成员身份生效。只在旧 shell 中重新运行命令不会刷新 supplementary groups。
+
+重新登录后检查服务：
+
+```bash
+systemctl status niceeval-docker-profile-default.service
+systemctl status niceeval-docker-profile-watchdog-default.service
+```
+
+两个服务都应显示 `active (running)`。失败时读取对应 unit 的日志：
+
+```bash
+journalctl -u niceeval-docker-profile-default.service -b
+journalctl -u niceeval-docker-profile-watchdog-default.service -b
+```
+
+## 验证 profile
+
+进入已经安装 NiceEval 的评估项目，以日常用户运行：
+
+```bash
+pnpm exec niceeval docker profile list
+pnpm exec niceeval docker profile doctor default --smoke
+```
+
+`list` 应显示 `default`。`doctor --smoke` 会检查 descriptor、Unix socket、cgroup、容量和 watchdog，
+然后启动一个受限的外层容器及一个内层 Alpine 容器。所有项目都通过后，宿主 profile 才可以用于正式
+评估。
+
+不要用 `sudo pnpm exec niceeval ...` 绕过权限错误。日常用户无法访问 profile 时，先确认用户名已经写入
+`accessUsers`，再重新登录并重跑 doctor。
+
+## 在 Experiment 中使用
+
+宿主通过验收后，在 Experiment 的 Docker Sandbox 中引用同一个别名：
+
+```ts
+dockerAccess: {
+  mode: "dind",
+  isolation: "managed-rootless",
+  profile: "default",
+},
+```
+
+Experiment 还必须声明单容器 CPU、内存、PID、只读 rootfs 和 tmpfs。完整配置见
+[让 Sandbox 使用 Docker](/zh/tutorials/docker-in-docker#managed-rootless-dind)。先用较小的
+`maxConcurrency` 运行一次，再根据 profile 的 `capacity` 增加并发。
+
+## 更新 module
+
+需要更新 NiceEval module 时，在系统配置仓库更新对应 input，检查 diff 后重新构建：
+
+```bash
+nix flake update niceeval
+nix flake check
+sudo nixos-rebuild switch --flake .#my-host
+```
+
+更新会改变宿主服务，不能只更新评估项目里的 npm 依赖。保留旧 generation，确认 doctor 和实际评估都
+通过后再清理 NixOS generation。

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

@@ -39,6 +39,15 @@ export const memory = definePlugin<MemoryOptions>({
     teardown: (_sandbox, ctx) => ctx.progress({ message: "断开当前 Sandbox" }),
   }),
 });
+
+export const telemetry = definePlugin({
+  name: "acme.telemetry",
+  behaviorRevision: "1",
+  experiment: () => ({
+    setup: (ctx) => ctx.progress({ message: "启动 telemetry 收集" }),
+    teardown: (ctx) => ctx.progress({ message: "停止 telemetry 收集" }),
+  }),
+});
 ```
 
 `name` 命名 Plugin family。`instanceKey(options)` 区分同一 family 的不同配置。实现语义改变时提高 `behaviorRevision`，让旧结果不再被精确沿用。
@@ -50,6 +59,11 @@ export const memory = definePlugin<MemoryOptions>({
 `plugins` 始终接收数组：
 
 ```ts
+import { defineExperiment } from "niceeval";
+import { codexAgent } from "niceeval/adapter";
+import { dockerSandbox } from "niceeval/sandbox";
+import { memory, telemetry } from "./shared/memory.ts";
+
 export default defineExperiment({
   agent: codexAgent({
     skills: [{ kind: "local", path: ".agents/skills/memory" }],

package/docs-site/zh/tutorials/rerun-and-cache.mdx

@@ -62,13 +62,15 @@ npx niceeval exp checkout --rerun all
 
 ## 明确接受已有 Attempt
 
-当自动采用条件不满足，但你确认某个已有 Attempt 仍可用时，使用完整 locator：
+身份变化不一定表示历史结果已经失效，但 NiceEval 不会替操作者猜测。先从 dry run 或结果页取得完整 locator，核对候选 Attempt；确认它在新配置下仍然成立时，明确接受它：
 
 ```sh
 npx niceeval accept @1K1P0VJAPVJ12
 ```
 
-`accept` 先检查所有输入，再发布一个以 `reference` 采用该 Attempt 的新 Run。操作者理由、差异和资格会随该 Run 保存。它不会修改源 Attempt，也不会复制源 Attempt 的业务值。
+`accept` 会发布一个新的采用 Run，不会修改原 Attempt。一次需要接受多个结果时，把全部 locator 放在同一条命令中；NiceEval 会先原子预检所有输入，避免只接受一半。
+
+候选 locator 的取得方式、审阅项目、原子预检和失败处理见[审阅并采用历史 Attempt](/zh/tutorials/accept-results)。
 
 ## 发布后不可修改
 

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

@@ -13,16 +13,16 @@ Sandbox agent 会在隔离环境中启动 coding-agent CLI，给它 workspace
     运行 Anthropic Claude Code CLI，需要 `ANTHROPIC_API_KEY`。
   </Card>
   <Card title="codex" icon="terminal">
-    运行 OpenAI Codex CLI，需要 `CODEX_API_KEY`。
+    运行 OpenAI Codex CLI，需要 `OPENAI_API_KEY`。
   </Card>
   <Card title="bub" icon="robot">
-    运行 bub coding agent，鉴权遵循 bub CLI 自身约定。
+    运行 bub coding agent，需要 `OPENAI_API_KEY` 与 `OPENAI_BASE_URL`。
   </Card>
 </CardGroup>
 
 ## 运行内置 agent
 
-在 Eval 或 Experiment 上设置 `sandbox`，选择 [NiceEval](https://niceeval.com/) 在哪里创建隔离环境：
+在评估用例或 Experiment 上设置 `sandbox`，选择 [NiceEval](https://niceeval.com/) 在哪里创建隔离环境：
 
 ```ts
 // experiments/local.ts
@@ -45,7 +45,7 @@ npx niceeval exp local fixtures/button --attempts 10
 ```
 
 <Note>
-  没有对应的 CLI flag，也没有项目级默认 provider。Eval 与 Experiment 都没贡献 template-bearing layer 时，link planning 会在创建任何 Sandbox 前失败。
+  没有对应的 CLI flag，也没有项目级默认 provider。评估用例与 Experiment 都没贡献 template-bearing layer 时，link planning 会在创建任何 Sandbox 前失败。
 </Note>
 
 云端跑 coding agent 时，可以直接使用 NiceEval 已发布的 E2B 公共模板，避免每个 Attempt 安装 CLI：
@@ -95,8 +95,10 @@ export default defineExperiment({
 | Agent | 必需变量 |
 |---|---|
 | `claude-code` | `ANTHROPIC_API_KEY` |
-| `codex` | `CODEX_API_KEY` |
-| `bub` | 遵循 bub CLI 鉴权 |
+| `codex` | `OPENAI_API_KEY` |
+| `bub` | `OPENAI_API_KEY`、`OPENAI_BASE_URL` |
+
+省略工厂参数时，NiceEval 的 `bubAgent()` 与 `codexAgent()` 都读取这组 OpenAI-compatible 变量。旧的 `BUB_API_KEY`、`BUB_API_BASE`、`CODEX_API_KEY`、`CODEX_BASE_URL` 不再读取；运行 Experiment 前要完成改名。
 
 ## 工作流程
 
@@ -140,7 +142,7 @@ export default defineEval({
 
 pattern 是 gitignore 风格，以 workdir 根为基准：不带 `/` 的匹配任意深度的同名项，带 `/` 的从 workdir 根匹配，末尾 `/` 表示目录。项目自己的 `.gitignore` 不参与判断，被项目忽略的文件照常记录。清单在第一次记账时冻结，agent 事后改 `.gitignore` 影响不了它。
 
-单个 `t.send()` 窗口最多采 10,000 个路径、64 MiB 内容。超了这一步直接报执行错误，不会伪装成「一个文件都没改」让文件断言假通过。
+单个 `t.send()` 窗口最多扫描 100,000 个路径和 256 MiB 去重文本。扫描结果中，File Changes 最多保留 10,000 条 change；候选更多时，它保存确定性前缀，并用 `collection-cap-reached` 把 collection 标为 `partial`。只有超过扫描上限才会报执行错误，不会伪装成「一个文件都没改」让文件断言假通过。异常大的 workspace 应用 `diff.include` 或 `diff.ignore` 收窄。
 
 生命周期（`.setup()` / `.teardown()`）挂在 experiment `sandbox` 字段的 spec 上，用来做"按实验变化的环境准备"——装某个实验专属的二进制、预热、跨 attempt 载入和回存状态。它写下的文件属于环境，不会被算进 agent 产出的 diff。写法和规则见 [Sandbox provider · 生命周期](/zh/tutorials/sandbox-providers#生命周期)。
 
@@ -151,7 +153,7 @@ import {
   completeEvidenceCoverage,
   createNpmCliInstaller,
   defineSandboxAgent,
-  resolveAgentBin,
+  agentBin,
 } from "niceeval/adapter";
 
 const { ensure, installer } = createNpmCliInstaller({
@@ -167,8 +169,12 @@ export default defineSandboxAgent({
   installers: [installer],
   async send(input, ctx) {
     ctx.progress({ message: "运行 my-agent CLI" });
-    const bin = await resolveAgentBin(ctx.sandbox, "my-agent");
-    await ctx.sandbox.runCommand(bin, ["run", input.text, "--json-out", "agent-events.json"]);
+    await ctx.sandbox.runCommand("sh", [
+      "-lc",
+      `exec ${agentBin("my-agent")} run "$1" --json-out agent-events.json`,
+      "my-agent",
+      input.text,
+    ]);
     const transcript = await ctx.sandbox.readText("agent-events.json");
     if (transcript.trim() === "") {
       ctx.diagnostic({
@@ -185,7 +191,7 @@ export default defineSandboxAgent({
 });
 ```
 
-`createNpmCliInstaller` 会在宿主机准备 npm 包，再把它送入 Sandbox。Sandbox 里不需要安装 Node.js 或 npm。完整步骤见[为自定义 Sandbox Agent 安装 CLI](/zh/tutorials/install-custom-sandbox-agent)。
+`createNpmCliInstaller` 会在宿主机准备 npm 包、送入 Sandbox，再用 npm 安装普通包。这类 Sandbox 需要 Node.js 与 npm；只有自包含的 `platformPackage` 才能省掉它们。完整步骤见[为自定义 Sandbox Agent 安装 CLI](/zh/tutorials/install-custom-sandbox-agent)。
 
 `setup`、每次 `send` 和 `teardown` 都拿到各自作用域的反馈方法：
 

package/docs-site/zh/tutorials/sandbox-providers.mdx

@@ -42,7 +42,7 @@ export default defineExperiment({
 });
 ```
 
-Eval 与 Experiment 都没声明 template-bearing layer 时，link planning 会在创建任何 Sandbox 前失败，而不会猜一个 provider。
+评估用例与 Experiment 都没声明 template-bearing layer 时，link planning 会在创建任何 Sandbox 前失败，而不会猜一个 provider。
 
 三个内置 provider 的 SDK 不随 NiceEval 一起安装——用哪个就装哪个，避免把用不到的依赖（以及它们的原生构建脚本）带进你的项目：
 
@@ -70,11 +70,11 @@ sandbox: dockerComposeSandbox({
 
 `workspaceService` 指定 Compose 文件里哪个 service 是主 Sandbox。Agent、`t.sandbox` 的命令与文件操作、`workdir`、变更 diff，全部只落在这一个容器上。Compose 文件里的其它 service（数据库、mock server 之类）是伴随资源，不经过 `Sandbox` 接口——不能对它们 `runCommand`、上传或读写文件，也看不到它们的 diff。要用到这些伴随 service，只能靠题目自己的网络访问，例如从 `client` 容器里用 Compose 内置 DNS 访问 `db:5432`。
 
-### 让 Agent自己运行 Docker
+### 让 Agent 自己运行 Docker
 
-如果 Agent需要执行 `docker build`、`docker run`或 `docker compose`，可以显式挂已有 Unix socket，
-也可以选择 raw privileged或 managed rootless Docker-in-Docker。三种模式的适用场景、Dockerfile和
-完整配置见[让 Sandbox使用 Docker](/zh/tutorials/docker-in-docker)。
+如果 Agent 需要执行 `docker build`、`docker run` 或 `docker compose`，可以显式挂已有 Unix socket，
+也可以选择 raw privileged 或 managed rootless Docker-in-Docker。三种模式的适用场景、Dockerfile 和
+完整配置见[让 Sandbox 使用 Docker](/zh/tutorials/docker-in-docker)。
 
 ## 生命周期
 
@@ -88,7 +88,7 @@ sandbox: dockerComposeSandbox({
 import type { SandboxHook, SandboxHookContext } from "niceeval/sandbox";
 ```
 
-稳定且体积大的依赖不要在这里重复安装。系统包、Agent CLI、编译好的二进制和大模型缓存应该先做进 Docker image、Vercel 沙箱快照或 E2B template。每个 Attempt 从预制环境启动，`.setup()` 只做薄薄的一层动态配置和 fail-fast 检查。
+稳定且体积大的依赖不要在这里重复安装。系统包、Agent CLI、编译好的二进制和大模型缓存应该先做进 Docker image、Vercel Sandbox 快照或 E2B template。每个 Attempt 从预制环境启动，`.setup()` 只做薄薄的一层动态配置和 fail-fast 检查。
 
 ```ts
 export default defineExperiment({
@@ -97,6 +97,7 @@ export default defineExperiment({
     .setup(mempalSetup("codex"))        // 预检、写 hook、载入状态
     .teardown(mempalTeardown("codex")), // 回存状态
   maxConcurrency: 1,                    // 载入和回存之间不能并发，声明串行
+  sharedState: { key: "mempal/codex/cohort-a" },
 });
 ```
 
@@ -176,17 +177,19 @@ vercelSandbox({ snapshotId: "snap_abc123" })
 e2bSandbox({ template: "my-evals" })
 ```
 
-Docker image、Vercel 沙箱快照和 E2B template 的凭据、构建上下文、发布和过期方式不同。项目应使用 provider 的官方工具维护构建脚本，把最终 ID 或名字放进 experiment。适合预制的判断很简单：如果所有 Attempt 都要下载或安装同一份内容，而且它稳定、昂贵或体积大，就把它移到预制环境。
+Docker image、Vercel Sandbox 快照和 E2B template 的凭据、构建上下文、发布和过期方式不同。项目应使用 provider 的官方工具维护构建脚本，把最终 ID 或名字放进 experiment。适合预制的判断很简单：如果所有 Attempt 都要下载或安装同一份内容，而且它稳定、昂贵或体积大，就把它移到预制环境。
 
 ### 从官方基线继续构建以提速
 
 稳定、体积大、每个 Attempt 都相同的内容——系统包、Agent CLI、编译好的二进制、大模型缓存——应在跑评估用例之前烘焙进 provider 的可发布构建输出，让每个 Attempt 从预制环境启动、跳过运行时安装。三个内置 provider 都能从官方基线继续派生，不必从空白环境装 Agent。但它们的构建工具、凭据和发布语义不同，NiceEval 只统一**消费**产物 ID（`image` / `snapshotId` / `template`），不伪造跨 provider 的构建 DSL。
 
-Adapter 与 Sandbox 不互相猜配置：Adapter 负责检查所需 CLI，Sandbox spec 负责选择 provider 和构建输出。Claude Code 与 Codex 缺少 CLI 时会回退到运行时安装（构建输出在题面网络之外准备，经文件 API 送入），所以烘焙纯粹是提速。Codex 送进去的是该平台自带运行时的原生包，任务镜像不带 Node 也能装，Claude Code 仍要求镜像里有 npm。Bub 还会核对版本、OTel 插件和 Python 插件集合的安装指纹，不能仅凭 `command -v bub` 跳过安装，必须用预制环境。三个 provider 的构建都只在环境依赖变化时跑一次，产物换一个版本化名字，不要写入每个 Attempt 的 `.setup()`。
+Adapter 与 Sandbox 不互相猜配置：Adapter 负责检查所需 CLI，Sandbox spec 负责选择 provider 和构建输出。Claude Code 与 Codex 缺少 CLI 时会回退到运行时安装（构建输出在题面网络之外准备，经文件 API 送入），所以烘焙纯粹是提速。Codex 送进去的是该平台自带运行时的原生包，任务镜像不带 Node 也能装，Claude Code 仍要求镜像里有 npm。
+
+默认 Bub 0.4.0 配方除 OTel 插件外，还固定 `any-llm-sdk==1.17.0` 和 `openai==2.31.0`。安装指纹同时覆盖 Bub requirement、这两个 client override、OTel 插件和规范化后的 Python 插件集，不能仅凭 `command -v bub` 跳过安装。旧 marker 的预制环境会重装一次；显式选择其它 Bub 版本时，传递依赖闭包仍由调用方负责。三个 provider 的构建都只在环境依赖变化时跑一次，产物换一个版本化名字，不要写入每个 Attempt 的 `.setup()`。
 
 #### E2B：从官方与公共模板派生
 
-E2B 已提供 Claude Code 的 `claude` template 和 Codex 的 `codex` template。NiceEval 提供一个 E2B 专属的薄封装，让你从这两个官方起点继续链原生 E2B API。E2B 暂无 Bub 官方 template，因此 Bub 分支使用 NiceEval 固定版本的安装配方（Bub 版本 + 同代 OTel 插件）：
+E2B 已提供 Claude Code 的 `claude` template 和 Codex 的 `codex` template。NiceEval 提供一个 E2B 专属的薄封装，让你从这两个官方起点继续链原生 E2B API。E2B 暂无 Bub 官方 template，因此默认 Bub 分支与 `bubAgent()` 使用同一份完整 client 闭包和 OTel 插件：
 
 NiceEval 同时发布了三份任何 E2B Team 都能引用的公共模板。完整 namespace 与版本由 NiceEval 自己维护，
 下游直接取完整引用：
@@ -203,7 +206,7 @@ e2bSandbox({ template: NICEEVAL_CODEX_E2B_TEMPLATE })
 e2bSandbox({ template: NICEEVAL_BUB_E2B_TEMPLATE })
 ```
 
-这些基线都实际启动验证过：Claude Code `2.1.207`、Codex `0.144.1`、Bub `0.4.0`（安装指纹随版本与 OTel 插件 pin 一起变）。模板的版本号跟着它装的那个 Agent 走（形如 `0.144.1-r1`：Agent 版本 + NiceEval 配方修订号），三个 Agent 各自独立发版，NiceEval 库自己的版本不参与命名。所以业务仓库直接用常量，不复制这些字符串、也不跟踪版本。派生模板需要记录 base 身份时，同样用常量的值。
+这些基线都实际启动验证过：Claude Code `2.1.207`、Codex `0.144.1`、Bub `0.4.0`（安装指纹随 Bub requirement、client override、OTel 插件和 Python 插件 pin 一起变）。模板的版本号跟着它装的那个 Agent 走（形如 `0.144.1-r1`：Agent 版本 + NiceEval 配方修订号），三个 Agent 各自独立发版，NiceEval 库自己的版本不参与命名。所以业务仓库直接用常量，不复制这些字符串、也不跟踪版本。派生模板需要记录 base 身份时，同样用常量的值。
 
 当前这批公共模板中，Claude Code 模板沿用 E2B 官方 `/usr` npm prefix，普通用户不能直接写全局模块。需要在运行时追加 pnpm、yarn 等全局 Node 工具时，显式把它们装到两个模板都已加入 PATH 的 `/usr/local`：
 
@@ -315,7 +318,7 @@ Docker Sandbox 沿用镜像自己声明的执行身份：上面这份 Dockerfile
 
 #### Vercel：从官方 runtime 拍快照
 
-Vercel 没有 E2B 式的 template registry，也没有 Dockerfile。沙箱快照是从一台跑起来的 microVM 拍出来的。用 Vercel SDK 从官方 runtime（`node24`）起一台 Sandbox，装好 Agent CLI，调 `.snapshot()` 拿到 `snap_...`，再把它交给 `vercelSandbox({ snapshotId })`：
+Vercel 没有 E2B 式的 template registry，也没有 Dockerfile。Sandbox 快照是从一台跑起来的 microVM 拍出来的。用 Vercel SDK 从官方 runtime（`node24`）起一台 Sandbox，装好 Agent CLI，调 `.snapshot()` 拿到 `snap_...`，再把它交给 `vercelSandbox({ snapshotId })`：
 
 ```ts title="scripts/build-vercel-snapshot.ts"
 import { Sandbox } from "@vercel/sandbox";
@@ -359,7 +362,8 @@ await restoreCheckpoint(nextSandbox, data);
 这适合运行时缓存，不会创建可发布的 image/template/snapshot，也不管理共享、版本和过期。归档或恢复失败会直接抛错。
 
 如果这些目录或快照要跨 Attempt 延续，把 `restoreCheckpoint()` 放进 `SandboxLayer.setup()`，把 `createCheckpoint()` 放进配对的 `teardown()`。`setup()` 在实际 Sandbox 创建后恢复，因此新 run 也走同一边界。`teardown()` 在实例退休、Provider finalizer 前回存。
-`sandboxReuse: true` 只让同一个物理实例在本 Invocation 内继续存在。多个 Invocation 读写同一 checkpoint 时，在 Experiment 顶层声明 `sharedState: { key }`，让另一边在创建 Sandbox 前等待。
+
+`sandboxReuse: true` 只让同一个物理实例在本 Invocation 内继续存在。多个 Invocation 会读写同一 checkpoint 时，在 Experiment 顶层声明 `sharedState: { key }`。NiceEval 在 Experiment setup 或创建 Sandbox 前取得租约，等 checkpoint 回存、Provider finalizer 与 Experiment teardown 完成后释放。它只提供互斥，不负责 checkpoint 存储、事务恢复或跨机器协调。
 
 ## 瞬时错误重试
 
@@ -405,7 +409,7 @@ NiceEval 只观察、不还原：Agent 改了什么会真实落在你的工作
 
 ## 自定义 Provider
 
-用 `defineSandbox` 接入其它服务。`create` 的 `feedback` 已绑定到 `sandbox.create` 阶段，可以报告分配实例、拉镜像或恢复沙箱快照的状态：
+用 `defineSandbox` 接入其它服务。`create` 的 `feedback` 已绑定到 `sandbox.create` 阶段，可以报告分配实例、拉镜像或恢复 Sandbox 快照的状态：
 
 ```ts
 import { defineSandbox } from "niceeval/sandbox";

package/docs-site/zh/tutorials/sandbox-reuse.mdx

@@ -64,18 +64,11 @@ export default defineExperiment({
 
 ## 多开终端时 Sandbox 不共享
 
-Sandbox 复用只发生在一次 Invocation 里。两个终端同时跑一个实验时，两边有各自的 Run 和 Sandbox 池。NiceEval 不把运行中的 Sandbox handle 交给另一个进程。同一个 Record root 同时只允许一项操作；第二个终端指向同一个 root 会立即得到 `record-root-busy`，不会和第一个终端并行写入。
+Sandbox 复用只发生在一次 Invocation 里。两个终端同时跑一个实验时，两边有各自的 Run 和 Sandbox 池。NiceEval 不把运行中的 Sandbox handle 交给另一个进程；两个 Invocation 可以并发向同一个 Record root 追加已发布结果。
 
-确实需要并行时，给两个终端不同的 Record root：
+Record maintenance 是独占操作。`clean` 或其它维护命令报告 `record-maintenance-busy` 时，先停止占用该 root 的 reader 和 writer，再重试维护命令。正常并发运行不需要为了避开 writer 冲突而拆成多个 Record root。
 
-```bash
-niceeval exp experiments/mempal.ts --record .niceeval/mempal-a
-niceeval exp experiments/mempal.ts --record .niceeval/mempal-b
-```
-
-两个 root 各自形成完整结果，NiceEval 不自动合并它们。
-
-如果 Sandbox 只保留自己的临时状态，两边可以同时跑不同评估用例。两边都会在 Sandbox `setup()` 恢复同一 checkpoint，并在 `teardown()` 回存时，再给实验声明稳定的非密 key：
+如果 Sandbox 只保留自己的临时状态，两边可以同时跑不同评估用例。Sandbox Hook 恢复、回存同一个外部 checkpoint 时，为 Experiment 声明稳定且不含秘密的 key：
 
 ```typescript
 export default defineExperiment({
@@ -88,9 +81,9 @@ export default defineExperiment({
 });
 ```
 
-NiceEval 会在创建 Sandbox 前独占这个 key，到 Sandbox `teardown`、Provider finalizer 和实验 `teardown` 后才释放。等待方不创建 Sandbox。租约释放后，等待方继续自己的既定计划；它不读取或沿用另一 Record 的结果。
+NiceEval 会在 Experiment setup 或创建 Sandbox 前取得这个 key，直到 Sandbox `teardown`、Provider finalizer 与 Experiment `teardown` 全部完成才释放。等待方不会创建 Sandbox；租约释放后，它继续自己的计划，不读取或采用另一条 Run 的结果。
 
-key 会进入结果的配置身份。换 key 表示换了状态 cohort，旧结果不会混入。这个租约只按 `sharedState.key` 保护外部 checkpoint，不替代 Record root 的独占规则。不同机器或工作副本需要外部分布式互斥。
+key 会进入结果的配置身份。更换 key 就是更换状态 cohort，旧结果不会混进来。租约只保护外部 checkpoint，与 Record root 无关；普通 append writer 仍可并发使用同一个 root。不同机器或 working copy 仍需外部分布式锁。
 
 ## 生命周期：谁跑几次
 
@@ -120,8 +113,9 @@ key 会进入结果的配置身份。换 key 表示换了状态 cohort，旧结
   `.setup()`。它每个 Sandbox 只跑一次，产物成为题间重置点的一部分，每道题白拿。
 - **只有这道题要的素材**（它自己的仓库、数据、依赖）→ 评估用例自己的 `setup` 或
   `test(t)`。每题重置后重放，所以必须是重放一遍还对的代码。每题各自 clone 时，
-  临时 clone 目录整个实验统一用一个名字、加进 `diff.ignore`，clone 前先
-  `rm -rf .git <临时目录>` 清掉上一题的残留——`.git` 会活过题间重置。
+  整个 Experiment 使用同一个具名临时目录，例如 `.niceeval-task-clone`，并把它加进
+  `diff.ignore`。clone 前只运行 `rm -rf .niceeval-task-clone` 清掉上一题的残留。
+  绝不能删除 `workdir` 根的 `.git`：题间 `git reset` 依赖它，且它会活过题间重置。
 - **起了后台进程、占了端口** → 评估用例的 `teardown` 自己收，题间重置不杀进程。
 
 ## 幂等是硬要求：一反一正
@@ -164,12 +158,11 @@ npm install          # 调和到 package.json/lockfile 声明的状态，本身
 `setup`。marketplace 拉取太慢时用 `sparse` 只拉插件路径，或把插件烘进 template
 并从 `plugins` 里拿掉声明——代价是安装 manifest 里就没有插件与解析版本的记录了。
 
-## 一批里混了不同环境
+## 一批里混了不同 Sandbox layer
 
-选中的评估用例用 `environment` 解析到不同预制产物时，不需要拆命令。Runner 按解析后的
-环境 profile 分组：同一个 Sandbox 只承接同组 Attempt，每组建立自己的题间重置点，
-组之间不共享 Sandbox 也不共享 Sandbox 级 `setup` 的产物。实验的 `maxConcurrency`
-约束的是所有组加起来的同时执行数。
+选中的评估用例声明不同 template-bearing `sandbox` layer 时，不需要拆命令。Link planning
+逐条解析评估用例 × Experiment 配对。物理 Sandbox identity 不同的 Attempt 不共享 Sandbox，
+也不共享 Sandbox 级 `setup` 产物；实验的 `maxConcurrency` 约束全部选中工作的同时执行数。
 
 ## 典型节奏
 

package/docs-site/zh/tutorials/select-and-preview.mdx

@@ -0,0 +1,65 @@
+---
+title: "选择并预览运行范围"
+sidebarTitle: "选择并预览运行范围"
+description: "先列出 Experiment，再用路径、评估用例前缀和 tag 收窄范围，最后用 --dry 确认计划后再花费模型与 Sandbox 成本。"
+---
+
+仓库里有多组 Experiment 和大量评估用例时，先确认定义，再预览本次计划。不要靠文件名猜 ID，也不要直接启动一批可能选错的任务。
+
+## 列出可运行的 Experiment
+
+```sh
+pnpm exec niceeval exp list
+pnpm exec niceeval exp list compare/codex
+```
+
+每行会显示 Experiment ID、描述、Agent、模型、Attempt 数量、选中的评估用例数量和 labels。`exp list` 只做发现与选择，不创建 Invocation、Sandbox 或模型调用。
+
+脚本需要完整清单时使用 JSON：
+
+```sh
+pnpm exec niceeval exp list --json > experiments.json
+```
+
+## 用位置参数收窄范围
+
+第一个位置参数选择 Experiment ID、目录或文件名前缀。后续参数只从这些 Experiment 已经选择的评估用例中继续按 ID 前缀收窄：
+
+```sh
+pnpm exec niceeval exp compare/codex memory/commit0
+```
+
+精确 Experiment ID 优先于前缀。目录段必须精确匹配；评估用例前缀不能把 Experiment 长期范围之外的题目加回来。
+
+只想运行带有某个标签的评估用例时使用 `--tag`：
+
+```sh
+pnpm exec niceeval exp compare --tag smoke
+```
+
+长期范围应写进 Experiment 的 `evals`。位置参数和 `--tag` 只负责一次调用的临时收窄。
+
+## 用 `--dry` 检查计划
+
+在真实运行前加上 `--dry`：
+
+```sh
+pnpm exec niceeval exp compare/codex memory/commit0 --dry
+```
+
+计划会列出评估用例、运行配置、Attempt 序号，以及每个位置会执行还是采用历史结果。它不会创建 Invocation、Run、Sandbox 或模型调用，也不会写 JUnit。
+
+机器需要读取计划时组合 `--json`：
+
+```sh
+pnpm exec niceeval exp compare/codex memory/commit0 --dry --json > plan.json
+```
+
+确认数量、模型、Attempt 和历史结果处置都符合预期后，去掉 `--dry` 运行同一条命令。
+
+## 处理选择失败
+
+- Experiment 零命中时，CLI 会列出可浏览的目录，并提示先运行 `exp <path> --dry`。
+- 评估用例零命中时，CLI 会明确报告 `No evals selected`，不会退回整个 Experiment 范围。
+- 想查看生命周期命令而不是运行矩阵时，使用[运行前检查生命周期计划](/zh/tutorials/debug-lifecycle-plan)。
+- 想决定哪些旧结果可以沿用时，继续阅读[重跑与沿用结果](/zh/tutorials/rerun-and-cache)。