niceeval 0.18.0 → 0.19.0

package/docs-site/zh/explanation/adapter.mdx

@@ -198,7 +198,7 @@ Adapter 侧按 `requestId` 把裁决交回应用，不按顺序猜。被人拒
 interface AgentContext {
   // 每轮都在的反馈与运行上下文
   readonly signal: AbortSignal;    // 运行器的超时与取消：透传给你发出的每个请求
-  readonly session: AgentSession;  // 本条会话线的状态槽
+  readonly session: AgentSession;  // 本条会话线的状态键
   progress(update: { message: string; current?: number; total?: number }): void;
   diagnostic(input: {
     code: string;
@@ -227,9 +227,9 @@ interface AgentSession {
   capture(id: string | undefined): void;     // 记回传的 id。只在还没记过时落地
 
   // Adapter 私有状态：客户端历史、HITL 停轮现场等
-  get<T>(slot: SessionSlot<T>): T | undefined;
-  set<T>(slot: SessionSlot<T>, value: T): void;
-  take<T>(slot: SessionSlot<T>): T | undefined; // 取到即清除，一次消费
+  get<T>(key: SessionKey<T>): T | undefined;
+  set<T>(key: SessionKey<T>, value: T): void;
+  take<T>(key: SessionKey<T>): T | undefined; // 取到即清除，一次消费
 }
 ```
 
@@ -237,7 +237,7 @@ Runner 为 Agent 的 `setup`、每次 `send` 和 `teardown` 分别绑定 lifecyc
 
 `ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 Experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义。`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头。接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/tutorials/connect-otel)。`experimentId` 是路径推导出的稳定标识，可以在动态 Sandbox callback 中按实验隔离跨 Attempt 的状态，见 [Sandbox · 按顺序准备 Sandbox](/zh/tutorials/sandbox-providers#按顺序准备-sandbox)。
 
-`session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（评估用例的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 服务端历史用 `id` / `capture` 续接。客户端历史和 HITL 停轮现场由 Adapter 在模块作用域用 `createSessionSlot<T>(name)` 创建 typed slot，再经 `get` / `set` / `take` 存取。`take` 取到即清除。slot 按 symbol 身份隔离，即使名字相同也不会冲突。
+`session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（评估用例的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 服务端历史用 `id` / `capture` 续接。客户端历史和 HITL 停轮现场由 Adapter 在模块作用域用 `createSessionKey<T>(name)` 创建 typed key，再经 `get` / `set` / `take` 存取。`take` 取到即清除。key 按 symbol 身份隔离，即使名字相同也不会冲突。
 
 ### 返回：`Turn`
 
@@ -299,7 +299,7 @@ Sandbox Agent，只有它的回调拿到带真实 `sandbox` 的 `SandboxAgentCon
 | `t` 上解锁什么 | 证据是什么 | 你写什么 |
 |---|---|---|
 | `t.send`、`t.sendFile`、`t.check`… | 任何 Agent 都有 | 无 |
-| 多次 `t.send()`、`t.reply`、`t.newSession()` | `send` 里接了 `ctx.session` 的续接存取器（typed slot 或 `id` + `capture()`）——没接则每轮各是新对话 | 无——存取器就在 `ctx` 上 |
+| 多次 `t.send()`、`t.reply`、`t.newSession()` | `send` 里接了 `ctx.session` 的续接存取器（typed key 或 `id` + `capture()`）——没接则每轮各是新对话 | 无——存取器就在 `ctx` 上 |
 | `t.respond()`、状态检查等 HITL | send 返回过 `"waiting"` + `input.requested` 事件 | 无——做到了就是有 |
 | `turn.calledTool()` / `turn.toolOrder()` 等正断言 | events 里有配对的 `operation.started` / `operation.finished` | 无——有事件就能断 |
 | `t.notCalledTool()` / `t.usedNoTools()` 等负断言**可信** | 事件来自带完整性证明的官方转换器 | 无——证明随转换器返回值走 |

package/docs-site/zh/explanation/assert.mdx

@@ -11,10 +11,10 @@ NiceEval 按 Assertion 评估，一条 Assertion 就是一项检查。调用 `t.
 ```ts
 import { includes } from "niceeval/expect";
 
-t.check(turn.message, includes("完成")).label("回复说明完成");
+t.check(turn.reply, includes("完成")).label("回复说明完成");
 turn.succeeded().label("Turn 完成");
 turn.calledTool("get_weather").label("查询天气");
-t.judge({ question, answer: turn.message }, answerQuality)
+t.judge({ question, answer: turn.reply }, answerQuality)
   .gate(0.8).label("回答质量");
 ```
 
@@ -29,10 +29,10 @@ t.judge({ question, answer: turn.message }, answerQuality)
 ```ts
 import { equals, includes, matches, satisfies, toolMatch } from "niceeval/expect";
 
-t.check(turn.message, includes("订单已确认"));
+t.check(turn.reply, includes("订单已确认"));
 t.check(turn.data, equals({ status: "refund", amount: 42 }));
 t.check(turn.data, matches(OrderSchema));
-t.check(turn.message.length, satisfies("回复不是空文本", (length) => length > 0));
+t.check(turn.reply.length, satisfies("回复不是空文本", (length) => length > 0));
 ```
 
 结果是 `matched` 还是 `mismatched`，只说明这个值是否满足这条规则，不说明规则本身写得对不对。任务允许多种正确结果时，规则要覆盖所有这些结果。
@@ -63,7 +63,7 @@ turn.calledTool(toolMatch("read_file").exactly(2)).label("读取两次");
 连续值检查和 Judge 给出 0 到 1 之间的测量值。测量值默认不影响判定，在 handle 上调用 `.gate(minimum)` 后，低于最低分才判 `failed`。
 
 ```ts
-t.judge({ task, answer: turn.message }, actionableQuality)
+t.judge({ task, answer: turn.reply }, actionableQuality)
   .gate(0.8).label("步骤可执行");
 ```
 
@@ -74,7 +74,7 @@ Assertion 默认只记录结果，不计分；加上 `.score(n)` 才贡献分数
 ```ts
 turn.calledTool("search");                       // 只保存 evaluation
 turn.calledTool("search").score(2);              // matched 时 +2
-t.check({ task, answer: turn.message }, completeness).score(5); // Measurement 0.8 时 +4
+t.check({ task, answer: turn.reply }, completeness).score(5); // Measurement 0.8 时 +4
 t.score(5);                                      // 直接 +5
 ```
 
@@ -93,7 +93,7 @@ t.score(5);                                      // 直接 +5
 ```ts
 const turn = await t.send("搜索资料并说明结论。");
 await turn.succeeded().orStop();
-const search = await t.check(turn.message, includes("结论")).orStop();
+const search = await t.check(turn.reply, includes("结论")).orStop();
 ```
 
 停止只影响 `await` 之后还没执行的代码，这部分代码不会产生结果。已经发生的普通 JavaScript 副作用不会撤销，之前启动的并发任务也不会被取消。

package/docs-site/zh/explanation/drive.mdx

@@ -13,7 +13,7 @@ description: "t.send() 和它返回的 Turn、t.sendFile()、多轮对话、t.ne
 ```ts
 const turn = await t.send("布鲁克林今天天气怎么样?");
 
-turn.message;   // 最后一条 assistant 消息
+turn.reply;   // 最后一条 assistant 消息
 turn.data;      // 结构化产物:仅当这次 send 声明了 output 时存在,类型随声明(见下)
 turn.status;    // "completed" | "failed" | "waiting"
 turn.events;    // 这一轮的 StreamEvent[]
@@ -21,7 +21,7 @@ turn.usage;     // { inputTokens, outputTokens, ... },adapter 报了才有
 turn.succeeded().label("本轮完成"); // 这一轮没失败、也没卡在未回答的 HITL 上
 ```
 
-`t.reply` 是主 session 最后一条 assistant 消息的简写，等价于最近一次 `t.send()` 返回的 `turn.message`。`t.events` 是主 session 已累积的完整事件流。
+`t.reply` 是主 session 最后一条 assistant 消息的简写，等价于最近一次 `t.send()` 返回的 `turn.reply`。`t.events` 是主 session 已累积的完整事件流。
 
 要结构化输出时，在 send 上声明 `output`（Standard Schema，zod 即可）。声明既是给应用的要求，也是 `turn.data` 的类型来源：
 
@@ -44,7 +44,7 @@ adapter 返回后运行器立刻按声明校验：`data` 不匹配，本轮直
 
 ```ts
 const turn = await t.sendFile("fixtures/invoice.png", "这张发票的总额是多少?");
-t.check(turn.message, includes("$"));
+t.check(turn.reply, includes("$"));
 ```
 
 ## 多轮对话
@@ -62,7 +62,7 @@ await t.send("好,发出去。");
 t.calledTool("send_email").label("已发送");
 ```
 
-多轮 `t.send()` 能不能真的续上上文，取决于 Adapter 的 `send` 是否接了 `ctx.session` 的会话续接存取器（typed slot 或 `id` + `capture()`）——没接时每轮各是一场新对话。怎么接见 [Adapter](/zh/explanation/adapter) 与[写 send](/zh/tutorials/write-send)。
+多轮 `t.send()` 能不能真的续上上文，取决于 Adapter 的 `send` 是否接了 `ctx.session` 的会话续接存取器（typed key 或 `id` + `capture()`）——没接时每轮各是一场新对话。怎么接见 [Adapter](/zh/explanation/adapter) 与[写 send](/zh/tutorials/write-send)。
 
 ## 独立会话 —— `t.newSession()`
 

package/docs-site/zh/explanation/hitl.mdx

@@ -61,7 +61,7 @@ HITL 对 Adapter 的全部要求就三件事——前两件发生在停下的那
 2. **每个待回答的问题吐一条 `input.requested`**，`id` 稳定、字段尽量填全——评估侧的检查和对位全靠它们。
 3. **下一次 `send` 先交裁决、再续跑**：从 `input.responses` 按 `requestId` 把裁决交回应用（不要按顺序猜），然后接着上一轮挂起的地方继续，而不是重发请求。
 
-"挂起的现场"（比如读了一半的 SSE 流）存在本会话线的 `ctx.session` 上。Adapter 用 `createSessionSlot<Pending>()` 声明私有 slot，停轮时 `ctx.session.set(slot, pending)`，回答轮 `ctx.session.take(slot)` 取回，取到即清除。怎么和流式驱动拼起来，见[写 send](/zh/tutorials/write-send#第五步：hitl) 第五步的完整骨架。
+"挂起的现场"（比如读了一半的 SSE 流）存在本会话线的 `ctx.session` 上。Adapter 用 `createSessionKey<Pending>()` 声明私有 key，停轮时 `ctx.session.set(key, pending)`，回答轮 `ctx.session.take(key)` 取回，取到即清除。怎么和流式驱动拼起来，见[写 send](/zh/tutorials/write-send#第五步：hitl) 第五步的完整骨架。
 
 和 [NiceEval](https://niceeval.com/) 的其它能力一样，HITL 没有布尔声明：**做到了就是有**。send 返回过 `"waiting"` 并吐了 `input.requested`，`t.respond` 就能工作。没做到，评估用例会在状态检查或 `requireInputRequest()` 上明确失败，而不是静默假通过。能力如何从构造中来，见 [Adapter](/zh/explanation/adapter#能力从哪来：构造证明，不是问卷)。
 
@@ -83,5 +83,5 @@ HITL 对 Adapter 的全部要求就三件事——前两件发生在停下的那
 
 - [Drive](/zh/explanation/drive#人工介入-hitl) — 评估侧的完整用法：状态检查、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`。
 - [Adapter](/zh/explanation/adapter#不同回答的入参) — 回答到 Adapter 的结构化入参，四种典型形态。
-- [写 send](/zh/tutorials/write-send) — Adapter 侧实操：typed session slot 与流式 + HITL 的完整骨架。
+- [写 send](/zh/tutorials/write-send) — Adapter 侧实操：typed session key 与流式 + HITL 的完整骨架。
 - [接入你的 Agent](/zh/tutorials/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。

package/docs-site/zh/explanation/judge.mdx

@@ -39,7 +39,7 @@ export default defineEval({
     const change = "修改持久化字段并提供回滚方案";
     const turn = await t.send(`解释这项变更：${change}`);
 
-    t.judge({ change, explanation: turn.message }, explainsRisk)
+    t.judge({ change, explanation: turn.reply }, explainsRisk)
       .gate(0.8)
       .label("风险说明质量");
   },
@@ -91,7 +91,7 @@ import { defineConfig } from "niceeval";
 import { OpenAIProvider } from "niceeval/judge";
 
 export default defineConfig({
-  judgeRuntime: OpenAIProvider({
+  judgeProvider: OpenAIProvider({
     model: "judge-model",
     baseUrl: "https://gateway.example.com/v1",
     apiKeyEnv: "JUDGE_GATEWAY_KEY",

package/docs-site/zh/introduction.mdx

@@ -44,12 +44,12 @@ export default defineEval({
     turn.succeeded().label("Turn 成功");
 
     t.calledTool("get_weather").label("调用天气工具");
-    t.check(turn.message, includes("天气")).label("说明天气");
+    t.check(turn.reply, includes("天气")).label("说明天气");
 
     const second = await t.send("那上海明天呢？");
     t.check(second.message, includes("上海")).label("第二轮接得上上下文");
 
-    t.judge({ question: turn.input, answer: turn.message }, groundedAnswer).gate(0.7)
+    t.judge({ question: turn.input, answer: turn.reply }, groundedAnswer).gate(0.7)
       .label("回答有依据");
   },
 });

package/docs-site/zh/reference/builtin-agents.mdx

@@ -11,7 +11,7 @@ description: "NiceEval 内置的 claude-code、codex、bub 适配器分别做到
 | 能力 | 对应的断言 / API |
 |---|---|
 | 收发消息（基础契约） | `t.send()`（可多次调用）、`t.reply`、`t.check(turn.data, equals(...))` / `matches(...)`、按状态判断的 `t.succeeded()` |
-| 事件流完整性 | `calledTool` / `usedNoTools` / `maxToolCalls` / `noFailedActions` / `event` 等作用域断言；`toolOrder` / `eventOrder` 只在 Turn 或 Session 上接收 matcher。消息用 `t.check(turn.message, includes(...))` 或 `t.check(turn.message, pattern(...))`。**负断言（`notCalledTool` 等）有完整事件流才可信** |
+| 事件流完整性 | `calledTool` / `usedNoTools` / `maxToolCalls` / `noFailedActions` / `event` 等作用域断言；`toolOrder` / `eventOrder` 只在 Turn 或 Session 上接收 matcher。消息用 `t.check(turn.reply, includes(...))` 或 `t.check(turn.reply, pattern(...))`。**负断言（`notCalledTool` 等）有完整事件流才可信** |
 | 会话续接 | 跨轮记忆断言、`t.newSession()` 会话隔离 |
 | HITL（人工介入） | `t.check(turn.status, equals("waiting"))`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()` |
 | `tracing` | trace decoding、`niceeval view` 的调用瀑布图 |
@@ -103,7 +103,7 @@ maxTurns?: number;
 mcpServers?: readonly McpServer[];
 ```
 
-额外 MCP server(每个 Sandbox setup 时写进用户级 ~/.claude.json)。
+额外 MCP server(每个 Sandbox before 时写进用户级 ~/.claude.json)。
 stdio 形态写 command(可带 args / env);Streamable HTTP 形态写 url(可带 headers,
 逐字进请求头),落成 { "type": "http", "url": …, "headers": … } 条目。
 
@@ -133,30 +133,30 @@ settingsFile?: string;
 一份完整的 Claude Code `settings.json`(官方格式)在本地项目里的路径 —— 相对运行
 niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
 项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
-都在 setup 阶段报错。原始字节原样上传为 Sandbox 里原本为空的用户级 `~/.claude/settings.json`
+都在 before 阶段报错。原始字节原样上传为 Sandbox 里原本为空的用户级 `~/.claude/settings.json`
 (不继承宿主机配置、不拼接、不重新序列化);保留键 `model` 与 `env` 出现在文件里
-setup 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文。
+before 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文。
 
-#### `postSetup`
+#### `before`
 
 ```ts
-postSetup?: readonly SandboxCommand[];
+before?: readonly SandboxCommand[];
 ```
 
 安装后按数组顺序运行的用户 Hook(复用 SandboxCommand 的窄上下文):在写 settings、挂 MCP、
-装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 before 脚本这类
 「安装产物就位后才能跑」的过程动作。抛错按基础设施错误计(attempt errored)。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
-#### `preTeardown`
+#### `after`
 
 ```ts
-preTeardown?: readonly SandboxCommand[];
+after?: readonly SandboxCommand[];
 ```
 
-与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
-之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
-之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+与 `before` 成对的收尾 Hook:按 `before` 的逆序语义,在 agent 自己的 after 步骤
+之前执行(LIFO 镜像 —— `before` 跑在 agent 安装之后,`after` 就跑在 agent 收尾
+之前),当且仅当 `before` 的时点走到过才触发。抛错按基础设施错误计,由 after 段
 按 teardown-failed 诊断收束。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
@@ -186,7 +186,7 @@ env?: Readonly<globalThis.Record<string, string>>;
 
 注入每次 Codex CLI 进程的额外环境变量。首轮 `codex exec` 与续轮 `codex exec resume`
 使用同一份声明；Codex 启动的 lifecycle Hook、MCP 动态 header 与命令子进程都会继承。
-值只经 Sandbox command options 传入，不拼进 shell 文本或写入 setup manifest，并全部按
+值只经 Sandbox command options 传入，不拼进 shell 文本或写入 before manifest，并全部按
 潜在敏感值从 timing / execution / error 证据中脱敏。`CODEX_API_KEY` 仍由 `apiKey` 或
 宿主同名环境变量提供，Adapter 的鉴权值会覆盖这里的同名键。
 env value 不进入 carry 身份。会改变被测行为的非敏感值必须同时声明在 Experiment flags
@@ -200,7 +200,7 @@ Sandbox factory 的 `pathPrepend`（见 docs/feature/sandbox/library.md）。
 mcpServers?: readonly McpServer[];
 ```
 
-额外 MCP server(每个 Sandbox setup 时追加进 ~/.codex/config.toml)。
+额外 MCP server(每个 Sandbox before 时追加进 ~/.codex/config.toml)。
 stdio 形态(command/args/env)写 [mcp_servers.&lt;name&gt;] 的 command 行;
 Streamable HTTP 形态(url/headers)写 url 行,headers 进 [mcp_servers.&lt;name&gt;.http_headers] 子表。
 
@@ -231,31 +231,31 @@ configFile?: string;
 一份完整的 Codex `config.toml`(官方 TOML 格式)在本地项目里的路径 —— 相对运行
 niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
 项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
-都在 setup 阶段报错。原始字节原样并入 Sandbox 里原本为空的用户级 `~/.codex/config.toml`
+都在 before 阶段报错。原始字节原样并入 Sandbox 里原本为空的用户级 `~/.codex/config.toml`
 (不继承宿主机配置、不解析后重写);保留键 `model`、`model_provider`、`model_providers`、
-`model_reasoning_effort`、`mcp_servers`、`otel` 出现在文件里 setup 报错。manifest 只记
+`model_reasoning_effort`、`mcp_servers`、`otel` 出现在文件里 before 报错。manifest 只记
 项目相对路径与字节 SHA-256,不落正文。
 
-#### `postSetup`
+#### `before`
 
 ```ts
-postSetup?: readonly SandboxCommand[];
+before?: readonly SandboxCommand[];
 ```
 
 安装后按数组顺序运行的用户 Hook(复用 SandboxCommand 的窄上下文):在写主配置、挂 MCP、
-装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 before 脚本这类
 「安装产物就位后才能跑」的过程动作。抛错按基础设施错误计(attempt errored)。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
-#### `preTeardown`
+#### `after`
 
 ```ts
-preTeardown?: readonly SandboxCommand[];
+after?: readonly SandboxCommand[];
 ```
 
-与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
-之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
-之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+与 `before` 成对的收尾 Hook:按 `before` 的逆序语义,在 agent 自己的 after 步骤
+之前执行(LIFO 镜像 —— `before` 跑在 agent 安装之后,`after` 就跑在 agent 收尾
+之前),当且仅当 `before` 的时点走到过才触发。抛错按基础设施错误计,由 after 段
 按 teardown-failed 诊断收束。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
@@ -269,10 +269,10 @@ apiKey?: string;
 
 OpenAI 兼容代理的 API key。省略时读 BUB_API_KEY env。
 
-#### `apiBase`
+#### `baseUrl`
 
 ```ts
-apiBase?: string;
+baseUrl?: string;
 ```
 
 OpenAI 兼容代理的 base URL。省略时读 BUB_API_BASE env。
@@ -292,8 +292,7 @@ skills?: SkillSpec[];
 version?: string;
 ```
 
-装哪一版 Bub(PyPI 版本号,如 `"0.5.1"`)。省略时用 NiceEval 钉的默认版本;
-永远是确定版本,不装 latest —— 被测对象的版本要能从实验配置读出来。
+固定 Bub 0.5.1 协议。省略或填写 "0.5.1"；其它版本在定义期抛出 TypeError。
 
 #### `otelPlugin`
 
@@ -303,9 +302,7 @@ otelPlugin?: string;
 
 OTel tape store 插件的 git 依赖(时间轨的来源)。省略时用 NiceEval 钉的默认 pin。
 
-插件与 Bub 的 tape 协议同代:默认 pin 从 `bub.tape` 取类型,要求 Bub ≥ 0.3.10;更早的
-插件 commit 按 republic 的类型校验,配 Bub ≤ 0.3.9。配错代不会安装失败,而是 span 全被拒、
-时间轨静默为空 —— 所以往回钉 `version` 时必须同批钉配套的插件 commit。
+自定义插件必须支持固定版本 Bub 0.5.1 的 tape 协议。
 
 #### `pythonPlugins`
 
@@ -313,29 +310,29 @@ OTel tape store 插件的 git 依赖(时间轨的来源)。省略时用 NiceEval
 pythonPlugins?: PythonPluginSpec[];
 ```
 
-额外装进 bub tool 环境的 Python Package,每个 Sandbox setup 时进 `uv tool install … --with <pkg>`。
+额外装进 bub tool 环境的 Python Package,每个 Sandbox before 时进 `uv tool install … --with <pkg>`。
 规范化后的 package 列表进安装 checkpoint key:plugin 集合不同的两个 agent 变体不会复用同一个
 安装 checkpoint(否则第二个变体会静默拿到第一个变体的环境)。
 
-#### `postSetup`
+#### `before`
 
 ```ts
-postSetup?: SandboxCommand[];
+before?: SandboxCommand[];
 ```
 
 安装后按数组顺序运行的用户 Hook(复用 SandboxCommand 的窄上下文):在装 bub、装 Skills /
 Python package、写 manifest 全部完成后执行。抛错按基础设施错误计(attempt errored)。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
-#### `preTeardown`
+#### `after`
 
 ```ts
-preTeardown?: SandboxCommand[];
+after?: SandboxCommand[];
 ```
 
-与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
-之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
-之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+与 `before` 成对的收尾 Hook:按 `before` 的逆序语义,在 agent 自己的 after 步骤
+之前执行(LIFO 镜像 —— `before` 跑在 agent 安装之后,`after` 就跑在 agent 收尾
+之前),当且仅当 `before` 的时点走到过才触发。抛错按基础设施错误计,由 after 段
 按 teardown-failed 诊断收束。
 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
 
@@ -358,7 +355,7 @@ export default uiMessageStreamAgent({
 它替你做好的能力：
 
 - **收发 + 事件流**：SSE 帧经 `ai` 包官方的框架无关 reducer `readUIMessageStream`（`useChat` 内部同款）归约，工具调用/结果/消息文本从消息 parts 直构——**不要求应用接 OTel**。
-- **会话续接**：协议是服务端零状态、「客户端带全量历史」——工厂用 Adapter 私有的 typed slot 存整份 `UIMessage[]`，每轮原样重放。新会话线（`t.newSession()` 之后）还没有写过这个 slot。
+- **会话续接**：协议是服务端零状态、「客户端带全量历史」——工厂用 Adapter 私有的 typed key 存整份 `UIMessage[]`，每轮原样重放。新会话线（`t.newSession()` 之后）还没有写过这个 key。
 - **HITL**：AI SDK v7 tool approval（工具带 `needsApproval: true`）原生映射——part 停在 `approval-requested` 时该 Turn 的 `status: "waiting"` + `input.requested`。`t.respond("approve" / "deny")` 翻译成 `approval-responded` 原地改写该 part、原样重发 `messages` 触发服务端续跑（和真实前端 `addToolApprovalResponse()` + `sendMessage()` 的协议行为一致）。它没有单独的 approve 端点。
 - **拒绝**：调用以 `rejected` 落进事件流，且默认带「不要重试」的 reason（`denyReason` 可覆盖）——不带的话模型经常原样重发同一个调用。
 - **usage / 瀑布图**：UI Message Stream 协议帧里没有 usage，所以 `t.maxTokens` 这类用量断言在这个内置件上默认没有数据（应用把 usage 放进 message metadata 属于应用自己的协议扩展）。瀑布图是另一回事：应用有 OTel 埋点（如官方 `@ai-sdk/otel`）时，按 [OTel 接入](/zh/tutorials/connect-otel)把 span 发给 [NiceEval](https://niceeval.com/)，`niceeval view` 就有完整瀑布图——span 只进瀑布图，不喂断言。
@@ -486,24 +483,24 @@ return driveFrameStream(frames, stream, ctx);         // 逐帧喂 stream.add()
 
 ## 通用「拼装方式」件：`driveFrameStream` / `deltaStream` + `ctx.session`
 
-一个手写 send 里真正互不相干的只有三段：transport（怎么发）、reduce（原始数据 → 事件，上一节的转换器管这个）、编排（会话续接 + HITL 暂停恢复）。第三段和任何具体协议无关，纯粹是控制流模式。服务端历史用 `ctx.session.id` / `capture`，客户端历史和 HITL 停轮现场用 `createSessionSlot<T>()` 声明的 Adapter 私有 slot，经 `ctx.session.get` / `set` / `take` 存取（`AgentSession`，见 [Adapter 概念](/zh/explanation/adapter#上下文：agentcontext)）。剩下真正跨协议复用的只有两个官方件：
+一个手写 send 里真正互不相干的只有三段：transport（怎么发）、reduce（原始数据 → 事件，上一节的转换器管这个）、编排（会话续接 + HITL 暂停恢复）。第三段和任何具体协议无关，纯粹是控制流模式。服务端历史用 `ctx.session.id` / `capture`，客户端历史和 HITL 停轮现场用 `createSessionKey<T>()` 声明的 Adapter 私有 key，经 `ctx.session.get` / `set` / `take` 存取（`AgentSession`，见 [Adapter 概念](/zh/explanation/adapter#上下文：agentcontext)）。剩下真正跨协议复用的只有两个官方件：
 
 | 件 | 解决什么 |
 |---|---|
-| `driveFrameStream(cursor, reducer, ctx, onFrame?)` | 逐帧喂 reducer、处理传输帧、检测 HITL 暂停信号——循环本身收成一个函数。暂停时 `cursor` 不关闭，`onFrame` 里用 `ctx.session.set(slot, cursor)` 存住它，回答轮 `ctx.session.take(slot)` 取回接着读，不重新发起请求 |
+| `driveFrameStream(cursor, reducer, ctx, onFrame?)` | 逐帧喂 reducer、处理传输帧、检测 HITL 暂停信号——循环本身收成一个函数。暂停时 `cursor` 不关闭，`onFrame` 里用 `ctx.session.set(key, cursor)` 存住它，回答轮 `ctx.session.take(key)` 取回接着读，不重新发起请求 |
 | `deltaStream(spec)` | 逐 token / 逐参数增量的通用累加器——原始 OpenAI/Anthropic 流式 API、自己手写的 token-by-token 后端这类"没有整段落地帧"的协议用它。声明"这一帧对应哪个操作"（文本增量/工具参数增量/收尾），拼接时机它自己管 |
 
 ```ts
-const pendingSlot = createSessionSlot<Pending>("my-adapter/pending");
+const pendingKey = createSessionKey<Pending>("my-adapter/pending");
 
 // send 一进来先看有没有挂起的现场（HITL 回答轮）
-const pending = ctx.session.take(pendingSlot);
+const pending = ctx.session.take(pendingKey);
 if (pending) {
   // ……按 input.responses 对位取裁决、把审批交回应用……
   return driveFrameStream(pending.cursor, pending.stream, ctx, onFrame);
 }
 
-// 正常轮：会话续接走 ctx.session.id / capture，暂停时把 cursor 存进 typed slot
+// 正常轮：会话续接走 ctx.session.id / capture，暂停时把 cursor 存进 typed key
 return driveFrameStream(cursor, stream, ctx, (frame, derived) => {
   ctx.session.capture(stream.sessionId);
   const gated = derived.find((event) =>
@@ -512,13 +509,13 @@ return driveFrameStream(cursor, stream, ctx, (frame, derived) => {
     event.operation.name === GATED_TOOL_NAME
   );
   if (gated?.type === "operation.started") {
-    ctx.session.set(pendingSlot, { cursor, stream, toolUseId: gated.operationId });
+    ctx.session.set(pendingKey, { cursor, stream, toolUseId: gated.operationId });
     return { pause: { id: gated.operationId, action: GATED_TOOL_NAME, options: [{ id: "approve" }, { id: "deny" }] } };
   }
 });
 ```
 
-三个 Tier 1 示例（claude-sdk、pi-sdk 用 `driveFrameStream` + typed slot，codex-sdk 只用 `driveFrameStream`）已经用这套件重写。Adapter 只剩 transport 与 `onFrame` 里"这一帧要不要额外处理"的判断，没有手写循环和模块级 Map。
+三个 Tier 1 示例（claude-sdk、pi-sdk 用 `driveFrameStream` + typed key，codex-sdk 只用 `driveFrameStream`）已经用这套件重写。Adapter 只剩 transport 与 `onFrame` 里"这一帧要不要额外处理"的判断，没有手写循环和模块级 Map。
 
 ## `turnFromAiSdk`：AI SDK 结果 → 事件流转换器
 
@@ -544,9 +541,9 @@ export default defineAgent({
 - 被测对象是 AI SDK 应用（`useChat` 后端）：内置 `uiMessageStreamAgent` 无侵入接入，零映射（含 HITL）。
 - 被测对象是其它 agent 系统（HTTP / gRPC 服务）：无侵入接入，手写事件映射（官方转换器能覆盖大半）——[`examples/zh/tier1`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1) 下五个示例全是这条路。应用已埋 OTel 的话顺手接上，多一张瀑布图。
 - 需要调用瀑布图（`niceeval view` 的 trace）：`claude-code` / `codex` / `bub` 三个都自发 OTLP（claude-code 走 CLI 的 beta 遥测，span 只有结构与计时）。自己写的 adapter 声明 `tracing` 即可（见 OTel 指南）。
-- 需要人工审批 / 多步确认（HITL）：`uiMessageStreamAgent` 原生支持（AI SDK v7 tool approval）。Sandbox 型三个都不支持，其它被测对象自己写 Adapter，拿 `driveFrameStream` + typed slot 拼（Tier 1 示例里 pi-sdk / claude-sdk 有现成写法）。
+- 需要人工审批 / 多步确认（HITL）：`uiMessageStreamAgent` 原生支持（AI SDK v7 tool approval）。Sandbox 型三个都不支持，其它被测对象自己写 Adapter，拿 `driveFrameStream` + typed key 拼（Tier 1 示例里 pi-sdk / claude-sdk 有现成写法）。
 - 想跑一个 coding agent 改代码、看 diff、判断工具调用：`claude-code` / `codex` / `bub`（收发 + 事件流 + 会话续接 + workspace + sandbox）。
-- 后端协议是自己发明的、没有官方 SDK 转换器可用时，别从零手写 send。挑一种 reduce 形状（整段落地写小映射，逐 token 增量用 `deltaStream`），服务端会话续接用 `ctx.session.id` / `capture`，客户端历史或 HITL 现场用 typed slot，拼起来就是 send。
+- 后端协议是自己发明的、没有官方 SDK 转换器可用时，别从零手写 send。挑一种 reduce 形状（整段落地写小映射，逐 token 增量用 `deltaStream`），服务端会话续接用 `ctx.session.id` / `capture`，客户端历史或 HITL 现场用 typed key，拼起来就是 send。
 
 ## 相关阅读
 

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

@@ -20,7 +20,7 @@ niceeval query explain [--record <file>] --request <file|->
 niceeval query run [--record <file>] --request <file|->
 ```
 
-`query` 使用带版本号的 JSON 请求协议 `niceeval.query/v1`，每一种固定的读取问题叫一个 operation。成功的结果和协议里定义的失败，都会向 stdout 写出恰好一个 JSON 文档。参数写错，或者进程出错到无法生成文档时，错误只写到 stderr。
+`query` 使用带版本号的 JSON 请求协议 `niceeval.query/v2`，每一种固定的读取问题叫一个 operation。成功的结果和协议里定义的失败，都会向 stdout 写出恰好一个 JSON 文档。参数写错，或者进程出错到无法生成文档时，错误只写到 stderr。
 
 - `discover` 列出当前版本支持的 operation ID。它不读运行记录，所以不接受 `--record`，也不返回请求的字段结构。
 - `explain` 校验完整请求，说明它会运行哪个 operation，以及接下来可以发哪些请求。
@@ -110,13 +110,13 @@ niceeval view [--run <run-id>...] [--no-open] [--port <port>] [--json]
 | `--help` | `niceeval` | boolean | 打印根命令索引。 |
 | `--version` | `niceeval` | boolean | 打印当前安装的 NiceEval 版本。 |
 | `--tag` | `niceeval check`、`niceeval exp`、`niceeval exp list` | string | 只选择带有该 tag 的评估用例。 |
-| `--help` | `niceeval check`、`niceeval exp`、`niceeval exp list`、`niceeval exp rename`、`niceeval exp --teardown`、`niceeval debug`、`niceeval accept`、`niceeval session` | boolean | 打印该命令的帮助。 |
+| `--help` | `niceeval check`、`niceeval exp`、`niceeval exp list`、`niceeval exp rename`、`niceeval exp --after`、`niceeval debug`、`niceeval accept`、`niceeval invocation` | boolean | 打印该命令的帮助。 |
 | `--experiment` | `niceeval exp` | string[] | 按 Experiment selector 缩小当前项目的结果。 |
 | `--attempts` | `niceeval exp` | number | 让每个选中的评估用例运行指定次数。 |
 | `--max-concurrency` | `niceeval exp` | number | 限制同时执行的 Attempt 数量。 |
 | `--max-build-concurrency` | `niceeval exp` | number | 限制同时准备 Sandbox build 的数量。 |
-| `--max-setup-prefix-concurrency` | `niceeval exp` | number | 限制同时准备 Sandbox setup prefix 的数量。 |
-| `--sandbox-setup-cache` | `niceeval exp` | string | Use or bypass the Sandbox setup cache. |
+| `--max-before-cache-concurrency` | `niceeval exp` | number | Limit concurrent Sandbox before-cache preparation. |
+| `--sandbox-before-cache` | `niceeval exp` | string | Use or bypass the Sandbox before cache. |
 | `--timeout` | `niceeval exp` | number | 以毫秒设置每个 Attempt 的超时时间。 |
 | `--budget` | `niceeval exp` | number | 以美元设置本次 Invocation 的预算。 |
 | `--junit` | `niceeval exp` | string | 写出必需的 JUnit 报告。 |
@@ -129,20 +129,22 @@ niceeval view [--run <run-id>...] [--no-open] [--port <port>] [--json]
 | `--run` | `niceeval exp rename` | string[] | 选择要采用到目标 Experiment 的一个精确 Run；重复传入会被拒绝。 |
 | `--dry` | `niceeval exp rename` | boolean | 预览显式 Experiment 重命名。 |
 | `--json` | `niceeval exp rename` | boolean | 写出该命令的机器文档或事件流。 |
-| `--teardown` | `niceeval exp --teardown` | boolean | 运行显式的 Experiment teardown 恢复。 |
-| `--json` | `niceeval exp --teardown` | boolean | 写出该命令的机器文档或事件流。 |
-| `--recover-shared-state` | `niceeval exp --teardown` | string | 指定要显式恢复的共享状态 key。 |
-| `--owner-token` | `niceeval exp --teardown` | string | 提供准确的共享状态 owner token。 |
-| `--confirm-owner-terminated` | `niceeval exp --teardown` | boolean | 确认记录的 owner 已终止。 |
-| `--confirm-remote-quiesced` | `niceeval exp --teardown` | boolean | 确认远端共享状态已静止。 |
+| `--after` | `niceeval exp --after` | boolean | 运行显式的 Experiment after 恢复。 |
+| `--json` | `niceeval exp --after` | boolean | 写出该命令的机器文档或事件流。 |
+| `--recover-shared-state` | `niceeval exp --after` | string | 指定要显式恢复的共享状态 key。 |
+| `--owner-token` | `niceeval exp --after` | string | 提供准确的共享状态 owner token。 |
+| `--confirm-owner-terminated` | `niceeval exp --after` | boolean | 确认记录的 owner 已终止。 |
+| `--confirm-remote-quiesced` | `niceeval exp --after` | boolean | 确认远端共享状态已静止。 |
 | `--json` | `niceeval debug` | boolean | 写出该命令的机器文档或事件流。 |
 | `--run` | `niceeval accept` | string[] | 采用一个已发布的精确 Run；重复传入会被拒绝。 |
 | `--dry` | `niceeval accept` | boolean | 完成整 Run 采用预检，但不发布新 Run。 |
-| `--all` | `niceeval session` | boolean | 包含已经完成的 Invocation 状态条目。 |
-| `--json` | `niceeval session` | boolean | 写出该命令的机器文档或事件流。 |
-| `--request` | `niceeval query` | string | 从文件或标准输入读取一个 niceeval.query/v1 request。 |
+| `--all` | `niceeval invocation` | boolean | 包含已经完成的 Invocation 状态条目。 |
+| `--json` | `niceeval invocation` | boolean | 写出该命令的机器文档或事件流。 |
+| `--request` | `niceeval query` | string | 从文件或标准输入读取一个 niceeval.query/v2 request。 |
 | `--record` | `niceeval query`、`niceeval show` | string | 读取一个外部 canonical SQLite Record。 |
 | `--help` | `niceeval query` | boolean | 打印该命令的帮助。 |
+| `--json` | `niceeval show` | boolean | 写出该命令的机器文档或事件流。 |
+| `--exp` | `niceeval show` | string[] | Show one Experiment; repeat to show more. |
 | `--run` | `niceeval show` | string[] | 显示一个已封口的 Run；可重复传入。 |
 | `--experiment` | `niceeval show` | string[] | 显示一个精确的 Experiment；可重复传入。 |
 | `--all` | `niceeval show` | boolean | 显示紧凑 Results 视图中隐藏的 Attempt。 |
@@ -172,7 +174,7 @@ niceeval view [--run <run-id>...] [--no-open] [--port <port>] [--json]
 | `--window` | `niceeval sandbox diff` | string | 选择一个已记录的改动窗口。 |
 | `--path` | `niceeval sandbox diff` | string | 选择 Sandbox diff 中的一个路径。 |
 | `--leave-running` | `niceeval sandbox enter` | boolean | 离开 shell 后继续保留 Sandbox。 |
-| `--record` | `niceeval sandbox list`、`niceeval sandbox enter`、`niceeval sandbox history`、`niceeval sandbox diff`、`niceeval sandbox stop`、`niceeval sandbox prune` | string | 使用指定的 NiceEval Record root。 |
+| `--record-root` | `niceeval sandbox list`、`niceeval sandbox enter`、`niceeval sandbox history`、`niceeval sandbox diff`、`niceeval sandbox stop`、`niceeval sandbox prune` | string | Use a specific NiceEval record root. |
 | `--orphans` | `niceeval sandbox list` | boolean | 检查已终止运行遗留的未登记 Sandbox 实例。 |
 | `--force` | `niceeval sandbox prune` | boolean | 同时清理未验证的孤儿候选项。 |
 | `--development` | `niceeval sandbox` | boolean | Diagnose the isolated Incus development domain instead of reference. |