niceeval 0.13.1 → 0.13.2

package/docs-site/zh/reference/define-agent.mdx

@@ -61,7 +61,7 @@ export default defineSandboxAgent({
   name: "my-cli-agent",
   evidenceCoverage: completeEvidenceCoverage,
   ensure: {
-    identity: { agent: "my-cli-agent", version: "1.0.0" },
+    identity: { agent: "my-cli-agent", version: "1.0.0", revision: "1" },
     probe: command("my-agent", ["--version"]),
   },
   async send(input, ctx) {
@@ -303,7 +303,7 @@ SandboxLayer command 按实验隔离跨 attempt 的基础设施内容，或 adap
 readonly evalId?: string;
 ```
 
-当前 Attempt 对应的 eval id。NiceEval runner 始终从 discovery 后的 Eval 身份填入；
+当前 Attempt 对应的 eval ID。NiceEval Runner 始终从 discovery 后的评估用例身份填入；
 第三方直接构造 AgentContext 时可省略。Adapter 可用它定位与题目同目录的只读宿主资产，
 但不能据此绕过 Sandbox 的隐藏判据隔离。
 
@@ -316,7 +316,7 @@ readonly evalGroup?: {
 };
 ```
 
-当前 Attempt 的 Eval Group；未分组 Eval 省略。
+当前 Attempt 的评估组；未分组评估用例省略。
 
 #### `attempt`
 
@@ -388,12 +388,137 @@ log(msg: string): void;
 
 ## Sandbox 接口
 
-Sandbox 型 agent 的 `ctx.sandbox`(`Sandbox`)是当前隔离环境的句柄。`CommandOptions` 是 `runCommand` / `runShell` 的可选项：
+Sandbox 型 agent 的 `ctx.sandbox`(`Sandbox`)是当前隔离环境的句柄。`Sandbox` 继承 `SandboxOperations` 与 `SandboxTransferOperations`，下方按声明接口列出全部成员。`CommandOptions` 是 `runCommand` / `runShell` 的可选项：
 
 {/* GENERATED:BEGIN sandbox-methods */}
 
 {/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
 
+### `SandboxOperations`
+
+#### `workdir`
+
+```ts
+readonly workdir: string;
+```
+
+Sandbox 内项目/工作区根目录的绝对路径(agent 命令的默认 cwd,也是 git baseline 提交的位置)。各方法的相对路径都以此为基准解析,省略 `cwd`/`targetDir` 时也落到这里。
+
+#### `runCommand`
+
+```ts
+runCommand(cmd: string, args?: readonly string[], opts?: CommandOptions): Promise<CommandResult>;
+```
+
+执行单个命令,`args` 作为独立 argv 传递、不经 shell 解释(无 `&&`、管道、通配符展开)。
+只想跑一个可执行文件、参数来自外部输入、担心注入时优先用它。
+
+#### `runShell`
+
+```ts
+runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
+```
+
+执行一整段脚本,经 shell(bash)解释,支持 `&&`、管道、`$()`、重定向等。
+需要拼多条命令或做条件判断时用它。
+
+#### `runCommandOrThrow`
+
+```ts
+runCommandOrThrow(
+  cmd: string,
+  args?: readonly string[],
+  opts?: CommandOptions,
+): Promise<SuccessfulCommandResult>;
+```
+
+像 `runCommand` 一样执行单个命令，但非零退出时抛出 `SandboxCommandExitError`。错误消息附带
+有界、已清理和脱敏的 stderr 尾部；stderr 为空时回退 stdout。完整输出保留在异常的
+`result` 字段中。成功结果的 `exitCode` 在类型上固定为 `0`。
+
+#### `runShellOrThrow`
+
+```ts
+runShellOrThrow(script: string, opts?: CommandOptions): Promise<SuccessfulCommandResult>;
+```
+
+像 `runShell` 一样执行 shell 脚本，但非零退出时抛出 `SandboxCommandExitError`。错误摘要、
+完整输出和成功结果的语义与 `runCommandOrThrow` 相同。
+
+#### `readText`
+
+```ts
+readText(path: string): Promise<string>;
+```
+
+读取 Sandbox 内文件的文本内容(UTF-8)。文件不存在时抛错。
+
+#### `writeText`
+
+```ts
+writeText(path: string, content: string): Promise<void>;
+```
+
+写入 Sandbox 内一个 UTF-8 文本文件；父目录不存在时自动创建。
+
+#### `readBytes`
+
+```ts
+readBytes(path: string): Promise<Uint8Array>;
+```
+
+精确读取 Sandbox 内文件字节；公共契约不绑定 Node Buffer。
+
+#### `writeBytes`
+
+```ts
+writeBytes(path: string, content: Uint8Array): Promise<void>;
+```
+
+精确写入 Sandbox 内文件字节；父目录不存在时自动创建。
+
+#### `pathExists`
+
+```ts
+pathExists(path: string): Promise<boolean>;
+```
+
+检查 Sandbox 内文件或目录路径是否存在。
+
+### `SandboxTransferOperations`
+
+#### `uploadFile`
+
+```ts
+uploadFile(source: string | URL, targetPath: string): Promise<void>;
+```
+
+#### `uploadDirectory`
+
+```ts
+uploadDirectory(
+  sourceDir: string | URL,
+  targetDir?: string,
+  options?: { readonly ignore?: readonly string[] },
+): Promise<void>;
+```
+
+#### `downloadFile`
+
+```ts
+downloadFile(sourcePath: string, target: string | URL): Promise<void>;
+```
+
+#### `downloadDirectory`
+
+```ts
+downloadDirectory(
+  sourceDir: string,
+  targetDir: string | URL,
+  options?: { readonly ignore?: readonly string[] },
+): Promise<void>;
+```
+
 ### `Sandbox`
 
 #### `stop`
@@ -508,7 +633,7 @@ docs/feature/sandbox/library.md「执行身份」)。
 
 语义跨 provider 一致,各 provider 映射到自己的原生机制(docker:`exec --user`;E2B:
 `{ user }`;Vercel:只认 `"root"`,映射 `{ sudo: true }`,其它值报错;local:任何值都报错)。
-本就全程 root 的 provider视作 no-op;完全无法换身份的 provider 可不支持(抛错)—— 但**省略与
+本就全程 root 的 provider 视作 no-op；完全无法换身份的 provider 可不支持（抛错）——但**省略与
 显式值的语义保持一致**,不因 provider 而变。
 
 #### `timeoutMs`

package/docs-site/zh/reference/define-config.mdx

@@ -128,6 +128,6 @@ pricing?: globalThis.Record<string, PriceOverride>;
 
 {/* GENERATED:END config-fields */}
 
-> 成本边界：这里的 `pricing` 只提供 Runner 的 Config/runtime price table 输入，Runner 会独立产生 `estimatedCostUSD`，不论是否已有 `Usage.costUSD`。`maxCost` 只使用该 estimate。Report 不读取此配置；它必须在 Report module 以 `definePricingProfile()` 显式声明自己的 USD Profile，并只对 sealed Usage 做 Analysis 投影。
+> 成本边界：这里的 `pricing` 只提供 Runner 的 Config/runtime price table 输入。Runner 不论是否已有 `Usage.costUSD`，都会从 `model`、上报的 token 用量和这个表独立产生 `estimatedCostUSD`。Experiment 的预算与 `t.maxCost()` 使用该 estimate，`Usage.costUSD` 不驱动它。Report 不读取此配置；它必须在 Report module 以 `definePricingProfile()` 显式声明自己的 USD Profile，并只对 sealed Usage 做 Analysis 投影。
 
-[NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：评估用例自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 setup。`Config` 刻意没有 `sandbox` 字段，也不自动探测 provider。请在 Eval 或 Experiment 上声明 template-bearing `SandboxLayer`，让 link planning 在创建任何资源前确定它的 owner 与配对结果。
+[NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：评估用例自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 setup。`Config` 刻意没有 `sandbox` 字段，也不自动探测 provider。请在评估用例或 Experiment 上声明 template-bearing `SandboxLayer`，让 link planning 在创建任何资源前确定它的 owner 与配对结果。

package/docs-site/zh/reference/define-eval.mdx

@@ -51,7 +51,7 @@ sandbox?: SandboxLayer;
 ```
 
 这道题贡献的 Sandbox 声明层。省略等价于空 command-only layer，不提供隐式 template。
-每个实际 Eval x Experiment 配对必须恰好一方提供 template-bearing layer。
+每个实际评估用例 × Experiment 配对必须恰好一方提供 template-bearing layer。
 
 #### `plugins`
 
@@ -59,7 +59,7 @@ sandbox?: SandboxLayer;
 plugins?: readonly PluginInstance<"eval">[];
 ```
 
-Explicit, immutable Eval Plugin occurrences; no directory inheritance exists.
+显式且不可变的评估用例 Plugin occurrence；不存在目录继承。
 
 #### `judge`
 
@@ -116,7 +116,7 @@ test(t: TestContext): EvalTestReturn;
 
 `t`（`TestContext`）是评估用例作者拿到的高层上下文。每一次作者入口调用都直接登记一条 Assertion。`t.check(value, match)` 严格接收两个参数。`t.succeeded()`、`session.succeeded()`、`turn.succeeded()`、`calledTool(...)`、`notCalledTool(...)` 与 Judge recipe 也直接登记 Assertion。handle 只配置同一条 entry 的 `key`、`label`、`.atLeast(n)`、`.gate(n)` 与 `.score(n)`。`.orStop()` 也只作用于此 entry，绝不登记第二条 Assertion。
 
-Pass Eval 用 Boolean condition 折叠 Attempt Verdict。measurement 用 `.gate(n)` 才进入 failed，`.atLeast(n)` 只增加局部 condition；`await handle.orStop()` 在 mismatch 或 below 时停止当前 continuation。
+通过制评估用 Boolean condition 折叠 Attempt Verdict。measurement 用 `.gate(n)` 才进入 failed，`.atLeast(n)` 只增加局部 condition；`await handle.orStop()` 在 mismatch 或 below 时停止当前 continuation。
 
 `defineScoreEval` 的 `ScoreTestContext` 额外提供 `t.score(n)` 直接登记 contribution，`n` 必须 finite 且不小于零；已有 Assertion 用 `.score(n)` 贡献分数，`n` 必须 finite 且大于零。`calledTool` 与 `notCalledTool` 的完整契约见 [Scoped assertions](https://github.com/NiceEval/NiceEval/blob/main/docs/feature/assertions/library/scoped-assertions.md)。全部成员：
 
@@ -332,7 +332,7 @@ turn.judge.autoevals.closedQA(question).gate(0.7).label("回答质量");
 turn.judge.autoevals.summarizes(sourceText).score(20).label("摘要质量");
 ```
 
-`t.judge.autoevals` 的根级 recipe 额外接收 `{ input, output }` 字符串材料。`turn.judge` 已绑定 immutable Turn 材料。模型配置按 Eval、Experiment、项目配置解析一次；没有单次模型覆盖或 `{ on }` 选项。Pass Eval 使用 `.gate(n)`；Score Eval 直接 `.score(n)`。
+`t.judge.autoevals` 的根级 recipe 额外接收 `{ input, output }` 字符串材料。`turn.judge` 已绑定 immutable Turn 材料。模型配置按评估用例、Experiment、项目配置解析一次；没有单次模型覆盖或 `{ on }` 选项。通过制评估使用 `.gate(n)`；计分制评估直接 `.score(n)`。
 
 ## `Turn` 返回类型
 

package/docs-site/zh/reference/events.mdx

@@ -87,7 +87,7 @@ token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表
 
 {/* GENERATED:END usage-fields */}
 
-> 成本边界：`Usage.costUSD` 只表示 provider / adapter 返回的 USD observed 成本，绝不由 token、模型目录或本地价目表推导。Runner 从 Config/runtime price table 独立计算 `estimatedCostUSD`，即使 observed 成本存在也照常计算，且只有 `maxCost` 消费它。Report 成本投影只接受显式 `PricingProfile` 与 sealed Usage，不读取 Runner estimate。
+> 成本边界：`Usage.costUSD` 只表示 Provider / Adapter 返回的 USD observed 成本，绝不由 token、模型目录或本地价目表推导。Runner 即使已有 observed 成本，也会从 `model`、上报的 token 用量和 Config/runtime price table 独立计算 `estimatedCostUSD`。Experiment 的预算与 `t.maxCost()` 使用这个 estimate，`Usage.costUSD` 不驱动它。Report 成本投影只接受显式 `PricingProfile` 与 sealed Usage，不读取 Runner estimate。
 
 ## StreamEvent 变体一览
 
@@ -200,14 +200,14 @@ token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表
 | `message` | agent（或用户）说了一段话 | `turn.message`、`turn.event(eventMatch("message", ...))`、Judge 的材料 |
 | `operation.started`（`kind: "tool"`） | 发起一次工具调用 | `turn.calledTool(...)`、`turn.toolOrder(...)`、`turn.event(...)` |
 | `operation.finished`（`kind: "tool"`） | 该次工具调用的结果 | 带状态条件的 `ToolMatch` |
-| `operation.started`（`kind: "subagent"`） | 委派一个子 agent | `turn.event(eventMatch("operation.started", ...))` |
-| `operation.finished`（`kind: "subagent"`） | 子 agent 返回 | `turn.event(eventMatch("operation.finished", ...))` |
-| `input.requested` | 停下来等人输入（HITL） | `t.requireInputRequest()`、`turn.event(...)` |
-| `thinking` | 思考文本 | `turn.event(eventMatch("thinking", ...))`、view 展示 |
-| `compaction` | 上下文被压缩 | `turn.event(eventMatch("compaction"))` |
-| `error` | 本轮出错 | `turn.event(eventMatch("error", ...))`、view 展示 |
+| `operation.started`（`kind: "subagent"`） | 委派一个子 agent | 原始事件与报告；当前没有子 agent 专用断言 |
+| `operation.finished`（`kind: "subagent"`） | 子 agent 返回 | 原始事件与报告；失败会进入 `noFailedActions()` 的汇总事实 |
+| `input.requested` | 停下来等人输入（HITL） | `t.check(turn.status, equals("waiting"))`、`t.requireInputRequest()` |
+| `thinking` | 思考文本 | view 展示；当前没有 `eventMatch` selector |
+| `compaction` | 上下文被压缩 | view 展示；当前没有 `eventMatch` selector |
+| `error` | 本轮出错 | view 展示；当前没有 `eventMatch` selector |
 
-事件断言共用三个入口：`event(match)`、`notEvent(match)` 与 `eventOrder(matches)`；它们都接收 `eventMatch(...)`，不另造 selector object 或匿名事件 predicate。
+事件断言共用三个入口：`event(match)`、`notEvent(match)` 与 `eventOrder(matches)`；它们都接收 `eventMatch(...)`，不另造 selector object 或匿名事件 predicate。当前 `eventMatch` 只有 `message`、工具 `operation.started` 与工具 `operation.finished` 三种形状，不能把全部原始 `StreamEvent` 当成可断言 selector。
 
 ## 逐事件说明
 
@@ -280,7 +280,7 @@ events.push({
   output?: JsonValue, status: "completed" | "failed" }
 ```
 
-被测系统把任务委派给子 agent（等它返回）时吐这一对，`operationId` 配对规则同上。评估作者用 `eventMatch("operation.started", ...)` / `eventMatch("operation.finished", ...)` 比较对应事件。
+被测系统把任务委派给子 agent（等它返回）时吐这一对，`operationId` 配对规则同上。它们会保留在原始事件流与报告中，但当前公开 Assert-first API 没有 `calledSubagent`，`eventMatch(...)` 也不能选择子 agent operation；不要凭空换成另一个 selector。
 
 ### `input.requested` —— 停下等人（HITL）
 
@@ -304,11 +304,11 @@ agent 停轮等人时，每个待回答的问题吐一条，同时该 Turn 的 `
 { type: "error", message: string }
 ```
 
-有就吐，没有不硬造。`compaction` 主要来自 coding agent CLI（上下文满了自动压缩）。
+有就吐，没有不硬造。`compaction` 主要来自 coding agent CLI（上下文满了自动压缩）。这几种原始事件保留给报告与诊断；当前公开 `eventMatch` 不能选择它们。
 
 ## 映射的三条纪律
 
-1. **时序即事实**：事件按真实发生顺序排。`toolOrder` / `eventOrder` 用单调 cursor 匹配不同 occurrence 的子序列，顺序错了断言就失真。
+1. **时序即事实**：事件按真实发生顺序排。`toolOrder` / `eventOrder` 用单调 cursor 匹配不同 occurrence 的子序列，顺序错了断言就失真。`eventOrder` 只排公开 `eventMatch` 支持的事件。
 2. **`operationId` 配对**：每个 started operation 都要有同 `kind`、同 id 的 finished operation。只有配对完成，框架才能把状态与 input 归到同一个逻辑工具 occurrence。
 3. **完整性必须显式**：官方转换器按实际 adapter 能力声明 evidence coverage。负向断言在相关输入或 action coverage 不完整时是 `unavailable`，不会把“没观察到”冒充“没有发生”。手工映射同样要如实声明覆盖范围，见[能力位参考](/zh/reference/capabilities)。
 

package/docs-site/zh/reference/official-adapters.mdx

@@ -16,7 +16,7 @@ description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么
 
 - **鉴权**：`ANTHROPIC_API_KEY`（工厂参数 `apiKey` 可覆盖），可选 `ANTHROPIC_BASE_URL`（工厂参数 `baseUrl`）。
 - **装 MCP server**：`mcpServers` 配置项，`setup` 阶段写进 Sandbox 里用户级的 `~/.claude.json`（顶层 `mcpServers` 字段）。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）。远程 Streamable HTTP 端点写 `url`（可带 `headers`，逐字进请求头，常用于 `Authorization`），写成 `{ "type": "http", "url": …, "headers": … }` 条目。`url` 要 Sandbox 内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
-- **装 Skill**：`skills: SkillSpec[]`。本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进 Sandbox 的 project 级 `.claude/skills/<name>/`，claude CLI 原生发现（原生 `Skill` 工具调用被 adapter 归一为 `skill.loaded` 事件，不重复记成工具调用。用 `t.loadedSkill()` 断言，不是 `t.calledTool("Skill", ...)`）。
+- **装 Skill**：`skills: SkillSpec[]`。本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进 Sandbox 的 project 级 `.claude/skills/<name>/`，claude CLI 原生发现。adapter 会把原生 `Skill` 调用归一为 `skill.loaded` 原始事件，不重复记成工具调用；当前公开 Assert-first API 没有专用 Skill 断言，也不能把它伪装成 `calledTool("Skill", ...)`。
 - **装原生 Plugin**：`plugins: ClaudeCodePluginSpec[]`，每一项声明 Marketplace 连接（`name` / `source` / 可选 `ref`）和其中的 Plugin 名。这个类型只属于 claude-code，传不进 codex。复用 Sandbox 的 Experiment 不用额外处理残留：每条 Attempt 开始前，同名 marketplace 注册与已装 Plugin 都会按声明的 `source` / `ref` 重新安装。
 - **官方配置文件**：`settingsFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径。它指向一份完整的 Claude Code `settings.json`。路径相对项目根，只允许普通相对路径或 `./` 前缀。`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。
 
@@ -64,8 +64,8 @@ export default defineExperiment({
 
 ### codex
 
-- **鉴权**：`CODEX_API_KEY`（工厂参数 `apiKey` 可覆盖，不是 `OPENAI_API_KEY`），可选 `CODEX_BASE_URL`（工厂参数 `baseUrl`）接 OpenAI 兼容代理。
-- **Agent 进程环境**：`env` 会注入每次 `codex exec` 与 `codex exec resume`。Codex 启动的 Session 生命周期 Hook、MCP 动态请求头和命令子进程都会继承。值不会拼进 shell 文本或写入安装清单，并按潜在敏感值从 timing、execution 与错误证据中脱敏。`CODEX_API_KEY` 仍由 `apiKey` 或宿主环境提供，并覆盖 `env` 里的同名键。`PATH` 是 Sandbox 受管变量，不接受经 `env` 声明——出现即在 `codexAgent()` 调用时报错，改用 Sandbox 的 `pathPrepend`（见 [Sandbox provider](/zh/tutorials/sandbox-providers)）。
+- **鉴权**：`OPENAI_API_KEY`（工厂参数 `apiKey` 可覆盖），可选 `OPENAI_BASE_URL`（工厂参数 `baseUrl`）接 OpenAI 兼容代理。
+- **Agent 进程环境**：`env` 会注入每次 `codex exec` 与 `codex exec resume`。Codex 启动的 Session 生命周期 Hook、MCP 动态请求头和命令子进程都会继承。值不会拼进 shell 文本或写入安装清单，并按潜在敏感值从 timing、execution 与错误证据中脱敏。`OPENAI_API_KEY` 仍由 `apiKey` 或宿主环境提供，并覆盖 `env` 里的同名键。`PATH` 是 Sandbox 受管变量，不接受经 `env` 声明——出现即在 `codexAgent()` 调用时报错，改用 Sandbox 的 `pathPrepend`（见 [Sandbox provider](/zh/tutorials/sandbox-providers)）。
 - **装 MCP server**：`mcpServers` 配置项，`setup` 阶段追加进 `~/.codex/config.toml` 的 `[mcp_servers.<name>]` 段。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）。远程 Streamable HTTP 端点写 `url`（可带 `headers`，写成 `[mcp_servers.<name>.http_headers]` 子表）。`url` 要 Sandbox 内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
 
   <Warning>
@@ -120,7 +120,7 @@ export default defineExperiment({
 
 ### bub
 
-- **鉴权**：`BUB_API_KEY` + `BUB_API_BASE`（OpenAI 兼容代理），工厂参数 `apiKey` / `apiBase` 可覆盖。
+- **鉴权**：`OPENAI_API_KEY` + `OPENAI_BASE_URL`（OpenAI 兼容代理），工厂参数 `apiKey` / `apiBase` 可覆盖。
 - **装 Skill**：`skills: SkillSpec[]`，与另外两个 Adapter 同一个类型。装进 `.agents/skills/<name>/`，发现指引写进 AGENTS.md。
 - **装插件**：`pythonPlugins: PythonPluginSpec[]`（`{ package }`：PyPI 包、版本约束或 git URL），`setup` 阶段进 `uv tool install … --with <package>`。这个类型只属于 bub。package 集合进安装 checkpoint key，插件不同的两个变体不会复用同一份安装缓存。
 - **预制 Bub**：NiceEval 的 E2B 配方会把 Bub、OTel 插件和 Python 插件集合算成安装指纹。Adapter 只复用指纹完全一致的环境。仅在 PATH 里放一个 `bub` 不足以证明兼容。构建入口见 [Sandbox provider · 从官方基线继续构建以提速](/zh/tutorials/sandbox-providers#从官方基线继续构建以提速)。
@@ -148,7 +148,7 @@ export default defineExperiment({
 
 | | claude-code | codex | bub |
 |---|---|---|---|
-| 鉴权环境变量 | `ANTHROPIC_API_KEY` | `CODEX_API_KEY` | `BUB_API_KEY` + `BUB_API_BASE` |
+| 鉴权环境变量 | `ANTHROPIC_API_KEY` | `OPENAI_API_KEY` + 可选 `OPENAI_BASE_URL` | `OPENAI_API_KEY` + `OPENAI_BASE_URL` |
 | 额外 Agent 进程环境 | ❌ | ✅ `env` | ❌ |
 | MCP server | ✅ `mcpServers`（stdio + HTTP） | ✅ `mcpServers`（stdio + HTTP） | ❌ |
 | Skill | ✅ `skills: SkillSpec[]`（原生发现） | ✅ `skills: SkillSpec[]`（+ 发现指引） | ✅ `skills: SkillSpec[]`（+ 发现指引） |
@@ -159,7 +159,7 @@ export default defineExperiment({
 | tracing | ✅（beta，仅结构与计时） | ✅ | ✅ |
 | 安装方式 | npm 全局包（需镜像自带 Node） | 自带运行时的原生包（解压即用，镜像无需 Node） | `uv tool install`（PyPI） |
 
-装了什么有据可查：Adapter 在 `setup` 收尾把安装清单交给运行器，存成 Attempt Artifact `agent-setup.json`（库里读 `attempt.agentSetup()`。清单不落沙箱磁盘，agent 看不到它）。清单只记来源、ref、Skill/Plugin 名、解析出的版本，以及官方配置文件的项目相对路径和 SHA-256。不保存配置正文、API Key 或环境变量值。MCP server 同理只记非敏感字段：stdio 形态记 `name` / `command` / `args` 不记 `env`，HTTP 形态记 `name` / `url` 不记 `headers`。
+装了什么有据可查：Adapter 在 `setup` 收尾把安装清单交给运行器，存成 Attempt Artifact `agent-setup.json`（库里读 `attempt.agentSetup()`。清单不落 Sandbox 磁盘，Agent 看不到它）。清单只记来源、ref、Skill/Plugin 名、解析出的版本，以及官方配置文件的项目相对路径和 SHA-256。不保存配置正文、API Key 或环境变量值。MCP server 同理只记非敏感字段：stdio 形态记 `name` / `command` / `args` 不记 `env`，HTTP 形态记 `name` / `url` 不记 `headers`。
 
 ## 非 Sandbox 适配器
 

package/docs-site/zh/reference/results-data.mdx

@@ -12,6 +12,8 @@ Sample 固定本次选择的 Run、logical Slot 与分母。每个位置保留 `
 
 `--run` 保留指定 Run 的完整计划范围。`project-current` 只保留仍与当前项目身份匹配的范围。两种选择都不会因为某个度量缺少输入而缩小分母。
 
+`project-current` 的成员单位是匹配的 Run slot occurrence，不是去重后的 `(experiment, eval, ordinal)`。同一位置出现在多个匹配 Run 中时，每个 occurrence 都进入 `MetricValue.total`。重复运行或逐条 `accept` 因此可能增加分母。
+
 Sample 只能在 `load()`、Page 或组合组件执行期间传给 Report facade。回调结束后，页面只保留已经关闭的值，不能再次读取结果。
 
 ## 用 `aggregate()` 取得 rows
@@ -58,6 +60,10 @@ Attempt Evidence、Observability、File Changes、Sources 和 Sandbox history
 
 `available`、`partial`、`empty`、`unsupported` 和 `failed` 都是不同状态。不要把 `null` 当成零，也不要用只剩下的可见行数替换总分母。
 
+例如 `formatMetricValue()` 输出的 `2 / 4 slot · partial` 表示四个已选 occurrence 中只有两个提供该 Measure 的输入。这组计数只描述覆盖率；它不是 earned score、通过率或工作完成比例。Measure 自己的 `value` 才是读数。
+
+默认 Overview 不把这组计数重复追加到每个指标单元格。它按题型显示通过率或 earned score，并在结果不完整时用独立的 `Result coverage` 区域显示可用结果数。终端把这个区域渲染成有标题的边框；底层 `MetricValue` 的字段保持不变。
+
 ## 相关页面
 
 - [报告 API](/zh/reference/report-components)：Page、组件、JSON 和全站构建边界。

package/docs-site/zh/troubleshooting/debugging.mdx

@@ -66,7 +66,7 @@ Measure 和领域视图会把自己的状态与问题带进页面：
 
 `npx niceeval exp <experiment> --json` 只有在成功建立 Invocation 后，最后才会输出 receipt。命令在建立 Invocation 前就因输入错误退出时，没有 `runIds` 可读取。
 
-先修正 Experiment、Eval 选择或命令参数，再重新运行。成功时，使用 receipt 的 `runIds` 运行 `show`、`view` 或 `view --out`。
+先修正 Experiment、评估用例选择或命令参数，再重新运行。成功时，使用 receipt 的 `runIds` 运行 `show`、`view` 或 `view --out`。
 
 ## 静态报告站无法导出
 

package/docs-site/zh/troubleshooting/recover-after-kill.mdx

@@ -1,25 +1,27 @@
 ---
 title: "运行被强杀后恢复"
-description: "进程被 kill -9、CI 超时或断电杀掉后，重跑同一条命令续跑没跑完的部分，用 niceeval sandbox prune 收回没清理的容器，用 --teardown 补齐实验收尾。"
+description: "进程被 kill -9、CI 超时或断电杀掉后，从已发布结果重跑、收回遗留 Sandbox、补齐实验收尾，并显式恢复共享状态租约。"
 ---
 
 `niceeval exp` 跑到一半被 `kill -9`、CI 时限或断电直接杀掉时，进程没有机会做任何清理。你会碰到三种残留：没跑完的评估、还在 Provider 侧占资源的 Sandbox 实例、实验 `setup` 起过但没关掉的外部服务（隧道、共享服务、license 席位）。三种各有一个恢复入口，都不需要手工翻 Docker 或云控制台。
 
 正常的 Ctrl+C 或 SIGTERM 不在本页范围：那些路径 NiceEval 会自己走完全部收尾，不留残留。
 
-## 重跑同一条命令，续跑没跑完的部分
+## 从已发布结果重跑
 
-已经跑完并落盘的 Attempt 是可信结果，重跑时自动带入，不再花一次 Agent 和 Sandbox 的成本：
+只有成功 seal、完整发布的 Run 里的 Attempt 才是 Record 事实。重跑可以自动沿用其中仍符合资格的结果，不再花一次 Agent 和 Sandbox 的成本。强杀 Invocation 留下的 incomplete Run directory 会被整体忽略：里面的草稿 Attempt 不展示、不引用、也不沿用。
 
 ```bash
 niceeval exp compare/bub-e2b memory/commit0
 ```
 
-- 只补跑缺的部分：`--attempts 5` 已经落盘 3 次，就只再跑 2 次。
+- 如果另一个完整 Run 已经为 `--attempts 5` 发布 3 个符合资格的 Attempt，就只再跑 2 次。如果那 3 个草稿只存在于强杀 Run、尚未到达 `complete` 发布点，它们一个也不会沿用，5 个位置都可能重跑。
 - 被强杀的实验如果留了没做完的收尾，重跑会先补一次实验级 `teardown` 再开始，泄漏不会越积越多。
 - 判定为 `errored` 的 Attempt 不复用，照常重跑。
 - 想全部重来，加 `--rerun all`。
 
+确认没有活跃 Invocation 占用 Record root 后，运行 `niceeval clean` 删除 incomplete Run 残留。清理不会把草稿 Attempt 变成可复用结果。
+
 ## 收回没清理的 Sandbox 实例
 
 先核对有哪些实例属于已经死掉的运行：
@@ -57,7 +59,37 @@ niceeval exp compare/bub-e2b --teardown
 - 随时可以执行，不依赖上次运行留下的记录。`teardown` 自身要能容忍重复执行。
 - 强杀后原进程的内存已经丢失，`teardown` 里要从容器名、pid 文件或幂等的关停脚本这类持久信息找回要关的资源，不要依赖 `setup` 存在内存里的对象。
 
+## 恢复共享状态租约
+
+声明了 `sharedState.key` 的实验会把租约持有到 Sandbox teardown、Provider finalizer 和实验 `teardown` 全部成功。进程被强杀或其中一项 cleanup 失败时，租约会保留；同 key 的新 Invocation 会继续等待，不会根据 PID、超时或 heartbeat 自动接管。
+
+先只检查当前 owner evidence，不带 token 或确认参数：
+
+```bash
+niceeval exp compare/bub-e2b --teardown \
+  --recover-shared-state mempal/codex/cohort-a
+```
+
+命令会显示 key、Experiment、owner token、host、PID、process identity 和最新 heartbeat，然后以非零状态退出。先确认原 owner 已终止，再确认它操作的 checkpoint、远端服务和回存流程都已静止。这个恢复入口只补跑实验 `teardown`，不会回滚已经写到一半的业务状态。
+
+核对完后，复制刚显示的完整 owner token，并显式确认两个条件：
+
+```bash
+niceeval exp compare/bub-e2b --teardown \
+  --recover-shared-state mempal/codex/cohort-a \
+  --owner-token <displayed-token> \
+  --confirm-owner-terminated \
+  --confirm-remote-quiesced
+```
+
+- 同机的原进程仍然存活时，NiceEval 拒绝恢复；暂停的进程仍算存活。
+- 错误或过期的 token 不会修改租约，也不会释放后来 owner 的租约。
+- 两条恢复命令同时竞争时，只有一条能取得恢复 ownership。
+- 补偿 `teardown` 失败时，租约继续保留。解决 teardown 问题后重新检查，再用当前显示的 token 重试。
+- 成功后，同 key 的等待 Invocation 才能取得租约并开始 Experiment setup 或创建 Sandbox。
+
 ## 预防：让下一次强杀无害
 
-- 长任务放在有时限的环境（CI、外部看门狗）里跑时，把时限内跑不完当成常态：靠上面的续跑机制分多次跑完，不必强求单次完成。
+- 长任务放在有时限的环境（CI、外部看门狗）里跑时，要为 Run 留出到达 `complete` 发布点的时间。后续运行只能沿用完整 Run 已经发布的结果。
 - 实验 `teardown` 写成幂等的：重复执行不报错、目标已经关掉也算成功。这是补收尾机制正确工作的前提。
+- 使用 `sharedState.key` 时，让 checkpoint 回存具备原子性或可补偿性。显式恢复协调租约不能修复半次业务写入。

package/docs-site/zh/tutorials/accept-results.mdx

@@ -0,0 +1,72 @@
+---
+title: "审阅并采用历史 Attempt"
+sidebarTitle: "采用历史 Attempt"
+description: "从 --dry 取得候选 locator，核对不可变 Attempt，再用 niceeval accept 原子采用明确结果，并用新 Run ID 验证分母与来源。"
+---
+
+配置身份改变后，自动沿用可能被拒绝。如果你已经核对某个历史 Attempt，确认它在新配置下仍然成立，可以用 `niceeval accept` 明确采用它。
+
+不要用这个命令跨过真实的评估条件变化。任务、断言、Agent 行为或 Sandbox 起点已经改变时，应重新运行并取得新证据。
+
+## 从计划取得候选 locator
+
+先预览当前目标：
+
+```sh
+pnpm exec niceeval exp checkout --dry
+```
+
+被身份差异挡住的历史结果会显示完整 Attempt locator 和可执行的 `accept` 提示。Locator 是本次授权的唯一范围；命令不会隐含选择同一 Run 或同一 Experiment 的其它结果。
+
+## 核对历史 Attempt
+
+使用完整 locator 查看不可变结果：
+
+```sh
+pnpm exec niceeval show @1K1P0VJAPVJ12
+```
+
+核对 Verdict、Assertion、用量、时间和详情页中的证据。需要回看来源 Run 的完整分母时，再使用：
+
+```sh
+pnpm exec niceeval show --run <source-run-id>
+```
+
+## 一次采用需要的结果
+
+```sh
+pnpm exec niceeval accept @1K1P0VJAPVJ12
+```
+
+同一个 Experiment 有多个结果需要采用时，把 locator 放进同一条命令：
+
+```sh
+pnpm exec niceeval accept @1K1P0VJAPVJ12 @1K1P0VJAPVJ13
+```
+
+NiceEval 会先预检全部输入。任一 locator 无效、不符合资格或与另一个输入冲突时，整条命令都不会发布业务结果。
+
+成功后，每个目标 slot 以 `reference` 指向原 Attempt，并记录 `accepted` action。源 Attempt 的事实、来源 Run 和 locator 都不会被修改或复制。
+
+## 核对新 Run
+
+成功反馈会显示新 Run ID：
+
+```sh
+pnpm exec niceeval show --run <accepted-run-id>
+```
+
+这个 Run 保留当前 Experiment 的完整 expected-slot 分母。命令中选择的位置是 `accepted`；没有选择的 sibling slot 是 `not-dispatched`。一次只采用部分位置时，报告会如实显示结果覆盖不足。
+
+每次 `accept` 都发布新 Run，不会修改或合并上一次调用。需要同一批结果组成同一个采用边界时，应放在同一条命令中。
+
+## 常见失败
+
+| 错误 | 下一步 |
+| --- | --- |
+| `malformed-locator` | 从 `--dry` 或 `show` 复制完整的大写 locator，不使用旧 UUID 或模糊前缀。 |
+| `locator-not-found` | 确认读取的是同一 Record；其它结果根显式传 `--record`。 |
+| `accept-ineligible` | 按提示检查 Verdict、timeout、身份或 Observability；不能证明仍成立时重新运行。 |
+| `duplicate-accept-member` | 每个目标 slot 只保留一个 locator，去掉重复或冲突输入。 |
+
+自动沿用与强制重跑的选择见[重跑与沿用结果](/zh/tutorials/rerun-and-cache)。

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";