niceeval 0.13.2-canary.35 → 0.13.2

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,15 +178,15 @@ 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，
+NixOS 宿主先按照[在 NixOS 上配置 Managed DinD](/zh/tutorials/nixos-managed-dind)部署并验证 profile，
 再配置下面的 Experiment。
 
 ```ts title="experiments/dind-managed.ts"
@@ -229,7 +235,7 @@ export default defineExperiment({
 });
 ```
 
-profile缺失、拼错、attestation失败或容量不足时，NiceEval会在模型调用前失败，绝不降级成 raw
+profile 缺失、拼错、attestation 失败或容量不足时，NiceEval 会在模型调用前失败，绝不降级成 raw
 privileged。宿主部署完成后先检查 profile：
 
 ```bash
@@ -238,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 设置运行并发
 
@@ -273,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";
@@ -294,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 的建议
 

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/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,29 +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 会先原子预检所有输入，避免只接受一半。
 
-新 Run 保留该 Experiment 当前完整的 expected-slot 分母。命令中选中的 slot 写作 `accepted`，同 Run 中没有被选中的 sibling slot 写作 `not-dispatched`。因此一次只接受一个 locator 时，这个 Run 的其它位置可能没有指标输入。
-
-每次 `accept` 调用都会发布新 Run，不会修改或合并上一次调用。连续接受同一 Experiment 的多个 locator 后，`project-current` 会保留这些仍匹配的 Run occurrence。默认 Overview 会在有边框的 `Result coverage` 区域提示只有部分预期结果可用；这里的可用数是结果覆盖率，不是通过率或 score。
-
-需要接受同一 Experiment 的多个结果时，把 locator 放进同一条命令：
-
-```sh
-npx niceeval accept @1K1P0VJAPVJ12 @1K1P0VJAPVJ13
-```
-
-同一次调用会为该 Experiment 发布一个 Run，并让两个目标 slot 都成为 `accepted`。需要核对某次接受的精确分母时，复制成功反馈中的 Run ID：
-
-```sh
-npx niceeval show --run <accepted-run-id>
-```
+候选 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";