niceeval 0.18.0 → 0.19.1-canary.101

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

@@ -144,7 +144,7 @@ readonly signal: AbortSignal;
 #### `models`
 
 ```ts
-readonly models: Readonly<Record<Slots, ResolvedModelSlot>>;
+readonly models: Readonly<Record<Roles, ResolvedModelRole>>;
 ```
 
 Frozen application model selections for this Attempt.
@@ -152,7 +152,7 @@ Frozen application model selections for this Attempt.
 #### `recordUsage`
 
 ```ts
-recordUsage(input: Omit<import("./adapter-usage.ts").AdapterUsageInput, "modelSlot"> & { readonly modelSlot?: Slots | null }): void;
+recordUsage(input: Omit<import("./adapter-usage.ts").AdapterUsageInput, "modelRole"> & { readonly modelRole?: Roles | null }): void;
 ```
 
 #### `sealUsage`
@@ -284,10 +284,10 @@ evidenceCoverage: EvidenceCoverage;
 
 该 Adapter 的常态证据覆盖声明；完整采集可用 `completeEvidenceCoverage`。
 
-#### `setup`
+#### `before`
 
 ```ts
-setup?: DirectAgentSetup;
+before?: DirectAgentBefore;
 ```
 
 每个 attempt 一次。Direct Agent 不接收 Sandbox；常用于建立连接、鉴权等一次性准备。
@@ -324,13 +324,13 @@ classifySendFailure?: SendFailureClassifier;
 
 可选 send 执行失败分类器:见 `Agent.classifySendFailure`。
 
-#### `teardown`
+#### `after`
 
 ```ts
-teardown?: DirectAgentTeardown;
+after?: DirectAgentAfter;
 ```
 
-运行结束前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),
+运行结束前的清理,当且仅当本 attempt 走到过 `before` 时点才执行(`before` 抛错不豁免),
 在 finally 里跑一次。
 
 ### `SandboxAgentDef`
@@ -376,10 +376,10 @@ installers?: readonly AgentInstaller[];
 配对安装层；省略表示这个 adapter 只提供 probe 协议，未命中时 Runner 在
 `agent.ensure` 点名缺失的精确 identity。工厂会把省略规范化成空数组。
 
-#### `setup`
+#### `before`
 
 ```ts
-setup?: AgentSetup;
+before?: AgentBefore;
 ```
 
 每条 Attempt 一次(不是每轮 send 一次):写 config.toml / 鉴权配置(model/base/auth 等
@@ -392,7 +392,7 @@ setup?: AgentSetup;
 tracing?: AgentTracing;
 ```
 
-OTLP 导出配置:Sandbox 里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。
+OTLP 导出配置:Sandbox 里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 before 拆出。
 
 #### `spanMapper`
 
@@ -418,13 +418,13 @@ classifySendFailure?: SendFailureClassifier;
 
 可选 send 执行失败分类器:见 `Agent.classifySendFailure`。
 
-#### `teardown`
+#### `after`
 
 ```ts
-teardown?: AgentTeardown;
+after?: AgentAfter;
 ```
 
-Sandbox 销毁前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),
+Sandbox 销毁前的清理,当且仅当本 attempt 走到过 `before` 时点才执行(`before` 抛错不豁免),
 在 finally 里跑一次。
 
 ### `AgentContext`
@@ -446,7 +446,7 @@ readonly signal: AbortSignal;
 readonly model?: string;
 ```
 
-本次 attempt 用的模型名,透传自 experiment 的 `model` 字段。sandbox 型 agent 通常在 setup 里用它写配置,direct 型通常在 send 里用它选模型。
+本次 attempt 用的模型名,透传自 experiment 的 `model` 字段。sandbox 型 agent 通常在 before 里用它写配置,direct 型通常在 send 里用它选模型。
 
 #### `reasoningEffort`
 
@@ -535,7 +535,7 @@ progress(update: ProgressUpdate): void;
 
 作用域反馈:报告此刻正在做什么(turn / tool / 安装进度)。短命状态——Human profile
 更新 active 行,`agent`/`ci` 不逐条打印,也不进最终结果;不要每个 token/delta 都调用。
-runner 按当前回调所处的生命周期阶段(agent.setup / agent.run / agent.teardown)归因,
+runner 按当前回调所处的生命周期阶段(agent.before / agent.run / agent.after)归因,
 调用方不能冒充其它阶段(见 docs/feature/experiments/library.md)。
 
 #### `diagnostic`
@@ -559,12 +559,12 @@ log(msg: string): void;
 
 {/* GENERATED:END agent-def */}
 
-`ctx.session`(`AgentSession`)是一条会话线的状态槽:同一条会话线的每次 `send` 拿到同一个 `ctx.session`,新会话线(评估用例第一轮 / `t.newSession()` 之后)拿到一个全新的。存取器:
+`ctx.session`(`AgentSession`)是一条会话线的状态键:同一条会话线的每次 `send` 拿到同一个 `ctx.session`,新会话线(评估用例第一轮 / `t.newSession()` 之后)拿到一个全新的。存取器:
 
 - `id?: string` / `capture(id): void` —— 会话续接·服务端记历史时用:`id` 是本线记过的会话 id(新线是 `undefined`),`capture` 记回传的 id(只在还没记过时落地)。
-- `createSessionSlot<T>(name)` —— 在 Adapter 模块作用域创建一个 typed slot。slot 按 symbol 身份隔离。
-- `get(slot)` / `set(slot, value)` —— 存取客户端历史或 Adapter 私有状态。
-- `take(slot)` —— 读取并删除 HITL 停轮现场，一次消费。
+- `createSessionKey<T>(name)` —— 在 Adapter 模块作用域创建一个 typed key。key 按 symbol 身份隔离。
+- `get(key)` / `set(key, value)` —— 存取客户端历史或 Adapter 私有状态。
+- `take(key)` —— 读取并删除 HITL 停轮现场，一次消费。
 
 完整契约见[Adapter 概念](/zh/explanation/adapter#上下文：agentcontext)。
 

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

@@ -11,7 +11,7 @@ import { defineConfig } from "niceeval";
 import { OpenAIProvider } from "niceeval/judge";
 
 export default defineConfig({
-  judgeRuntime: OpenAIProvider({ model: "gpt-5.4-mini", maxOutputTokens: 512 }),
+  judgeProvider: OpenAIProvider({ model: "gpt-5.4-mini", maxOutputTokens: 512 }),
   maxConcurrency: 4,
   timeoutMs: 300_000,
 });
@@ -33,18 +33,10 @@ name?: LocalizedText;
 项目名,显示在 `niceeval view` 顶部 hero(`<h1>`),省略则回退到通用标题。
 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
 
-#### `workspace`
+#### `judgeProvider`
 
 ```ts
-workspace?: string;
-```
-
-上传进 Sandbox 的工作区根目录,省略则用项目根;评估用例的 sandbox 视图从这里起步。
-
-#### `judgeRuntime`
-
-```ts
-judgeRuntime?: JudgeProvider;
+judgeProvider?: JudgeProvider;
 ```
 
 项目级默认 Judge Provider；Eval 与 Experiment 可替换模型或整个 Provider。
@@ -55,7 +47,7 @@ judgeRuntime?: JudgeProvider;
 reporters?: Reporter[];
 ```
 
-项目级默认 reporter 列表(如落盘 / 上传结果);EvalDef.reporters 会与它合并。
+项目级默认 reporter 列表(如落盘 / 上传结果)。
 
 #### `maxConcurrency`
 
@@ -73,10 +65,10 @@ maxBuildConcurrency?: number;
 
 Run 级 Sandbox 镜像准备并发；与 attempt 并发独立，省略时安全默认 2。
 
-#### `maxSetupPrefixConcurrency`
+#### `maxBeforeCacheConcurrency`
 
 ```ts
-maxSetupPrefixConcurrency?: number;
+maxBeforeCacheConcurrency?: number;
 ```
 
 Run 级 PreparedArtifact 前缀 DAG 准备并发；与 build / attempt 并发独立。
@@ -87,7 +79,7 @@ Run 级 PreparedArtifact 前缀 DAG 准备并发；与 build / attempt 并发独
 sandboxCache?: SandboxCacheConfig;
 ```
 
-项目级 SetupPrefix cache 默认；Experiment 与显式 CLI flag 可覆盖。
+项目级 before cache 默认；Experiment 与显式 CLI flag 可覆盖。
 
 #### `timeoutMs`
 

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

@@ -71,14 +71,6 @@ judge?: JudgeSelection;
 
 模型字符串只替换项目 Judge Provider 的模型；Provider 实例整体替换。Experiment 设置优先。
 
-#### `reporters`
-
-```ts
-reporters?: Reporter[];
-```
-
-覆盖 / 追加项目级 Config.reporters,只对这一条评估用例生效。
-
 #### `timeoutMs`
 
 ```ts
@@ -116,6 +108,12 @@ test(t: TestContext): EvalTestReturn;
 
 ## Test context: `t`
 
+`t.note(label, value)` 记录供结果审阅使用的 JSON 值或 Quantity，例如 `t.note("延迟", ms(512))`。
+它不登记 Assertion，不影响 Verdict、score 或 coverage。`null` 显示为 unavailable。
+同一 Attempt 的 label 必须唯一，最多 64 项，每项 JSON 不超过 64 KiB；违规时抛出 `TypeError`。
+`show @<locator>` 和 View 在 Assertions 后展示 Notes；JSON 与 Query 的 Attempt 结果包含 `notes`。
+`show --exp <experiment-id>` 按 label 和单位聚合数值，展示 count、min、median、p90、max。
+
 `t`（`TestContext`）是评估用例作者在 `test(t)` 里拿到的上下文。每调用一次检查方法，就登记一条断言。
 
 - `t.check(subject, match)` 用匹配条件检查你显式传入的值。
@@ -138,6 +136,14 @@ root、Session 和 Turn 上的 `judge` 都要求显式传入材料。官方提
 
 {/* 本区块由 pnpm run repo docs reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 packages/repo-tools/src/docs/reference-compiler.ts) */}
 
+#### `note`
+
+```ts
+note: AssertFirstCoreTestContext<Kind>["note"];
+```
+
+保存 JSON 值或 Quantity 供结果展示，不登记 Assertion，也不影响 Verdict、score 或 coverage。
+
 #### `evaluationKind`
 
 ```ts
@@ -285,10 +291,10 @@ readonly toolCalls: ManagedToolCalls<"attempt">;
 readonly sandbox: Sandbox<Kind>;
 ```
 
-#### `o11y`
+#### `observability`
 
 ```ts
-readonly o11y: import("../o11y/types.ts").O11ySummary;
+readonly observability: import("../o11y/types.ts").ObservabilitySummary;
 ```
 
 #### `usage`
@@ -382,14 +388,14 @@ const factualSummary = defineJudge({
 });
 
 const turn = await t.send("总结需求。");
-t.judge({ source: expected, summary: turn.message }, factualSummary)
+t.judge({ source: expected, summary: turn.reply }, factualSummary)
   .gate(0.8)
   .label("事实一致");
 ```
 
 Judge 材料可以是大小有上限的 JSON 值，也可以是 `judgeImage()` 生成的图片，登记时就会保存一份快照。
 
-Judge 用哪个模型按顺序决定：先取项目配置的 `judgeRuntime`，再应用评估用例的 `judge`，最后应用 Experiment 的 `judgeRuntime`。后一层给的是完整 Provider 时，会整体替换服务和执行配置；只给模型字符串时，只换掉已选 Provider 的模型。评估用例的 `judge` 只决定这道题用哪个模型或 Provider，不限制能用哪些匹配条件。
+Judge 用哪个模型按顺序决定：先取项目配置的 `judgeProvider`，再应用评估用例的 `judge`，最后应用 Experiment 的 `judge`。后一层给的是完整 Provider 时，会整体替换服务和执行配置；只给模型字符串时，只换掉已选 Provider 的模型。评估用例的 `judge` 只决定这道题用哪个模型或 Provider，不限制能用哪些匹配条件。
 
 通过制和计分制都可以调用 `.gate(minimum)`。计分制还可以调用 `.score(n)`，gate 失败时仍保留这一项的得分。
 
@@ -516,10 +522,10 @@ readonly eventOccurrences: ManagedEventOccurrences<"turn">;
 readonly status: "completed" | "failed" | "waiting";
 ```
 
-#### `message`
+#### `reply`
 
 ```ts
-readonly message: string;
+readonly reply: string;
 ```
 
 #### `data`

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

@@ -25,10 +25,10 @@ export default defineExperiment({
 #### `models`
 
 ```ts
-models?: Readonly<Record<string, ModelSlotSelection>>;
+models?: Readonly<Record<string, ModelRoleSelection>>;
 ```
 
-为自定义 Adapter 的各个具名模型槽选择模型；不能与单模型简写同时使用。
+为自定义 Adapter 的各个模型用途选择模型；不能与单模型简写同时使用。
 
 #### `description`
 
@@ -38,14 +38,6 @@ description?: string;
 
 一句话描述,展示在 view / CLI 里;纯说明,不影响调度或打分。
 
-#### `agent`
-
-```ts
-agent?: Agent;
-```
-
-对话 Adapter 的简写；`agent` 与 `adapter` 必须且只能提供一个。
-
 #### `adapter`
 
 ```ts
@@ -70,10 +62,10 @@ reasoningEffort?: string;
 
 模型推理努力程度(如 "low"/"medium"/"high",取值由具体模型/adapter 决定);省略=用 agent 原生默认。经 ctx.reasoningEffort 透给 adapter 与 eval。
 
-#### `judgeRuntime`
+#### `judge`
 
 ```ts
-judgeRuntime?: JudgeSelection;
+judge?: JudgeSelection;
 ```
 
 本实验的 Judge 执行配置。只覆盖 model / endpoint / credential selector / 调用预算，
@@ -180,8 +172,8 @@ sharedState?: SharedStateConfig;
 ```
 
 声明本 Experiment 需要独占的共享外部状态。相同 key 的 Invocation 在同一项目
-Coordination 域内从 Experiment/Sandbox setup 前一直互斥到 Sandbox teardown、
-provider finalizer 与 Experiment teardown 全部完成；等待者不会先创建 Sandbox，
+Coordination 域内从 Experiment/Sandbox before 前一直互斥到 Sandbox after、
+provider finalizer 与 Experiment after 全部完成；等待者不会先创建 Sandbox，
 取得租约后继续自己的 plan。它不是状态存储、事务或跨机器锁。
 
 #### `budget`
@@ -205,47 +197,34 @@ maxConcurrency?: number;
 仍按全局并发(CLI / env / config / 沙箱默认)跑。用于串行化有共享状态的实验
 (如跨 eval 累积记忆:`maxConcurrency: 1` 保证 attempt 按 eval 顺序一个个跑),
 或给撞 provider 限额的实验单独降速。名额与 attempt 同生命周期:从沙箱创建前一直握到
-teardown 与沙箱销毁完成才归还,中途任何等待(含 turn 重试退避)都不松手——
+after 与沙箱销毁完成才归还,中途任何等待(含 turn 重试退避)都不松手——
 `maxConcurrency: 1` 因此是严格的临界区,不会被同实验的下一个 attempt 提前闯入。
 它不跨 Invocation；跨 Invocation 的共享外部状态请声明 `sharedState`。
 
-#### `classifyFailure`
-
-```ts
-classifyFailure?: AttemptFailureClassifier;
-```
-
-本实验的失败分类器:识别以第三方错误形态浮出的自家共享基建死因(对自家隧道 host 的拒连
-一类),返回 `undefined` 表示「不认识,交给后续链路」。本实验任意 per-attempt 阶段的失败
-都会问到它;send 失败链上它排在 adapter 的 `classifySendFailure` 之前——按自家坐标过滤的
-特异性高于协议通用形状,两者同时认领时空间轴才赢得下来。分类器要快、纯、不抛错(抛错按
-`undefined` 回落并被吞掉);只声明决策轴与 `reason` 词,重试与落闸策略归执行体。
-见 docs/feature/error-classification/library.md「实验 / eval 作者:声明死因的波及范围」。
-
-#### `setup`
+#### `before`
 
 ```ts
-setup?: ExperimentHook;
+before?: ExperimentHook;
 ```
 
-实验级生命周期钩子对的 setup 侧:整场至多一次、宿主机侧,管「每实验一份、所有 attempt
+实验级生命周期钩子对的 before 侧:整场至多一次、宿主机侧,管「每实验一份、所有 attempt
 共享」的宿主机资源(隧道、mock server、license 租约)。本实验第一个通过派发许可的
 attempt 触发(memoized,并发 attempt 等同一个结果;全部结果被 carry 携入时不执行)。
-setup 不返回值;产物写模块级变量,`teardown` 与同文件 agent / sandbox 钩子从闭包读,
-runner 不做值的中介。setup 抛错 → 本实验所有 Attempt 形成 `errored` Verdict
-(code `"experiment-setup-failed"`、phase `"experiment.setup"`),同批其它实验不受影响。
+before 不返回值;产物写模块级变量,`after` 与同文件 agent / sandbox 钩子从闭包读,
+runner 不做值的中介。before 抛错 → 本实验所有 Attempt 形成 `errored` Verdict
+(code `"experiment-setup-failed"`、phase `"experiment.before"`),同批其它实验不受影响。
 函数体不进 fingerprint,改了钩子逻辑用 `--rerun all` 明确全部重跑。
 见 docs/feature/experiments/architecture.md「实验级生命周期」。
 
-#### `teardown`
+#### `after`
 
 ```ts
-teardown?: ExperimentHook;
+after?: ExperimentHook;
 ```
 
-实验级生命周期钩子对的 teardown 侧:本实验全部 attempt 收尾后执行(运行被中断也执行),
-当且仅当 setup 时点走到过——setup 抛错不豁免(半初始化现场同样要扫尾,teardown 对可能
-未赋值的闭包变量做防御),未声明 setup 不影响触发;一个 attempt 都不派发则跳过。
+实验级生命周期钩子对的 after 侧:本实验全部 attempt 收尾后执行(运行被中断也执行),
+当且仅当 before 时点走到过——before 抛错不豁免(半初始化现场同样要扫尾,after 对可能
+未赋值的闭包变量做防御),未声明 before 不影响触发;一个 attempt 都不派发则跳过。
 抛错或超 30s 清理上限只记运行级 diagnostic(`experiment-teardown-failed`),不改判定。
 
 {/* GENERATED:END experiment-fields */}

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

@@ -199,7 +199,7 @@ token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表
 
 | 事件 | 说什么 | 消费它的断言 / API |
 |---|---|---|
-| `message` | agent（或用户）说了一段话 | `turn.message`、`turn.event(eventMatch("message", ...))`、Judge 的材料 |
+| `message` | agent（或用户）说了一段话 | `turn.reply`、`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 | 保留在原始事件和报告里；没有子 agent 专用断言 |

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

@@ -24,6 +24,27 @@ const config = await t.check(rawConfig, pattern(/runtime/)).orStop();
 | `await handle.orStop()` | 同一 handle 的 async barrier；mismatch 或 below 时停止当前 continuation |
 | `handle.score(n)` / `t.score(n)` | 在计分制评估中让该项贡献分数，或直接登记 contribution |
 
+## 数值单位
+
+先用普通数值计算，再用 `ms`、`seconds`、`tokens`、`usd`、`ratio`、`count` 或 `bytes` 包装结果。它们返回冻结的 `Quantity<U>`，通过 `.value` 读取数值，通过 `.unit` 读取单位。Quantity 不参与算术，也不自动换算单位。
+
+所有构造函数只接受有限数；`ratio(n)` 还要求 `0 ≤ n ≤ 1`，否则抛出 `RangeError`。
+
+```ts
+import { atMost, between, measured, ms, quantile, ratio } from "niceeval/expect";
+
+const latency = measured(ms(512), { unavailable: "missing" });
+t.check(latency, atMost(ms(600)));
+t.check(quantile([ms(100), ms(200)], 0.9), between(ms(100), ms(200)));
+t.check(t.usage.cacheRead.rate(), atMost(ratio(0.9)));
+```
+
+`measured` 接受 `number | null` 或 `Quantity<U> | null`；`quantile` 接受普通数值数组或单位一致的 Quantity 数组，并保留单位。混合单位、混合普通数值与 Quantity 的数组会抛出 `TypeError`。空数组和缺失观测保留 unavailable，不补零。
+
+`atLeast`、`atMost`、`greaterThan`、`lessThan` 的阈值必须与观测单位相同。`between(minimum, maximum)` 检查含端点的区间，两端也必须同单位且按大小排列。普通数值只接受普通数值阈值。
+
+TypeScript 拒绝跨单位调用。JavaScript 绕过类型时，该检查返回 unavailable 并说明单位不符。`show` 和 `view` 按单位显示，例如 `512 ms`、`61.2%`、`$0.031`。
+
 ## Matchers
 
 下面每个 matcher 的签名和说明从 `niceeval/expect` 的源码生成，和当前实现保持同步。

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

@@ -23,7 +23,7 @@ description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么
   Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.claude/settings.json`。不继承宿主机配置，也不 deep merge 或重新序列化。`model` 和 `env` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。
 
   Secret 走环境变量，别写进配置文件。
-- **安装后脚本**：`postSetup: SandboxCommand[]`，在写 settings、挂 MCP、装 Skill 与 Plugin 全部完成后，按数组顺序在 Sandbox 里跑 command。典型用途是运行插件自带的 setup 脚本（比如它要往全局配置里登记 hook）——这类脚本必须等安装文件就位才能跑。与它成对的收尾是 `preTeardown: SandboxCommand[]`：按逆序、在 agent 自己的 teardown 步骤之前执行，当且仅当 `postSetup` 的时点已经走到才触发。Command 抛错算基础设施错误（Attempt 记 errored），不算 agent 答题失败。
+- **安装后脚本**：`before: SandboxCommand[]`，在写 settings、挂 MCP、装 Skill 与 Plugin 全部完成后，按数组顺序在 Sandbox 里跑 command。典型用途是运行插件自带的 setup 脚本（比如它要往全局配置里登记 hook）——这类脚本必须等安装文件就位才能跑。与它成对的收尾是 `after: SandboxCommand[]`：按逆序、在 agent 自己的 teardown 步骤之前执行，当且仅当 `before` 的时点已经走到才触发。Command 抛错算基础设施错误（Attempt 记 errored），不算 agent 答题失败。
 - **tracing**：claude CLI 的 beta 原生遥测（`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`），span 只有结构和计时，细节见 [OTel 接入](/zh/tutorials/connect-otel)。
 
 例如，用 `configs/claude-code/no-web.json` 关闭内置联网检索：
@@ -79,7 +79,7 @@ export default defineExperiment({
   Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.codex/config.toml`。不继承宿主机配置，也不拼接、deep merge 或解析后重写。`model`、`model_provider`、`model_providers`、`model_reasoning_effort`、`mcp_servers`、`otel` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。
 
   Secret 走环境变量，别写进配置文件。
-- **安装后脚本**：`postSetup: SandboxCommand[]`，语义与 claude-code 相同：全部安装步骤完成后按序在 Sandbox 里跑 command，适合运行插件自带的 setup 脚本。成对的 `preTeardown: SandboxCommand[]` 按逆序在 agent teardown 之前收尾，当且仅当 `postSetup` 的时点已经走到才触发。脚本往 codex 全局配置登记的 hook 不需要交互式信任确认——运行时 `codex exec` 已绕过 hook 信任门槛，hook 直接生效。
+- **安装后脚本**：`before: SandboxCommand[]`，语义与 claude-code 相同：全部安装步骤完成后按序在 Sandbox 里跑 command，适合运行插件自带的 setup 脚本。成对的 `after: SandboxCommand[]` 按逆序在 agent teardown 之前收尾，当且仅当 `before` 的时点已经走到才触发。脚本往 codex 全局配置登记的 hook 不需要交互式信任确认——运行时 `codex exec` 已绕过 hook 信任门槛，hook 直接生效。
 - **tracing**：内置，通过 `config.toml` 的 `[otel.trace_exporter.otlp-http]` 段配置，协议 `http/json`。
 
 例如，用 `configs/codex/no-web.toml` 关闭内置联网检索：
@@ -120,12 +120,14 @@ export default defineExperiment({
 
 ### bub
 
-- **鉴权**：`BUB_API_KEY` + `BUB_API_BASE`（OpenAI 兼容代理），工厂参数 `apiKey` / `apiBase` 可覆盖。
+Bub 固定使用 `0.5.1`。省略 `version` 或填写 `"0.5.1"`；其它值在定义期报错。自定义 `otelPlugin` 必须支持该版本的 tape 协议。
+
+- **鉴权**：`BUB_API_KEY` + `BUB_API_BASE`（OpenAI 兼容代理），工厂参数 `apiKey` / `baseUrl` 可覆盖。
 - **装 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 环境 · 从官方基线继续构建](/zh/tutorials/prebuilt-sandbox#从官方基线继续构建)。
 - bub 没有 `mcpServers`——MCP 只属于支持它的 Adapter，Config 上压根没有这个字段。
-- **安装后脚本**：`postSetup: SandboxCommand[]`，语义与另外两个 Adapter 相同：全部安装步骤完成后按序在 Sandbox 里跑 command。成对的 `preTeardown: SandboxCommand[]` 按逆序在 agent teardown 之前收尾，当且仅当 `postSetup` 的时点已经走到才触发。
+- **安装后脚本**：`before: SandboxCommand[]`，语义与另外两个 Adapter 相同：全部安装步骤完成后按序在 Sandbox 里跑 command。成对的 `after: SandboxCommand[]` 按逆序在 agent teardown 之前收尾，当且仅当 `before` 的时点已经走到才触发。
 - **安装方式**：走 `uv tool install`（PyPI 包，不是 npm 包），首次安装会建 checkpoint 缓存加速后续 Sandbox。
 - **tracing**：内置，通过环境变量注入，协议 `http/protobuf`。
 
@@ -155,7 +157,7 @@ export default defineExperiment({
 | 原生 Plugin | ✅ `plugins: ClaudeCodePluginSpec[]` | ✅ `plugins: CodexPluginSpec[]` | ❌ |
 | 官方配置文件 | ✅ `settingsFile`（完整 settings.json） | ✅ `configFile`（完整 config.toml） | ❌ |
 | Python Plugin | ❌ | ❌ | ✅ `pythonPlugins: PythonPluginSpec[]` |
-| 安装后脚本 | ✅ `postSetup` / `preTeardown` | ✅ `postSetup` / `preTeardown` | ✅ `postSetup` / `preTeardown` |
+| 安装后脚本 | ✅ `before` / `after` | ✅ `before` / `after` | ✅ `before` / `after` |
 | tracing | ✅（beta，仅结构与计时） | ✅ | ✅ |
 | 安装方式 | npm 全局包（需镜像自带 Node） | 自带运行时的原生包（解压即用，镜像无需 Node） | `uv tool install`（PyPI） |
 
@@ -195,3 +197,8 @@ export default defineExperiment({
 - [内置 Agent 能力参考](/zh/reference/builtin-agents) — 每个适配器逐能力盘点、非 Sandbox 适配器的完整代码示例。
 - [OTel 接入](/zh/tutorials/connect-otel) — 把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
 - [Adapter 参考](/zh/reference/define-agent) — `defineAgent` / `defineSandboxAgent` 完整参数。
+
+## Bub 与 OpenCode 的事件协议
+
+Bub 解析固定版本的 tape JSONL，OpenCode 解析 `1.18.5` 的 JSONL 与完整 session export。未知事件不进入 `Turn.events`。
+每条 Attempt 在收尾时生成一条 `agent-event-unrecognized` warning，列出未知事件类型和次数。运行 `niceeval show @locator` 查看诊断；该轮事件和动作证据会标为 partial。

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

@@ -70,7 +70,7 @@ query discover
 | 找不到项目的结果文件 | 确认在项目目录里运行，并检查 `.niceeval/record.sqlite` 是否存在。 |
 | `--record` 指定的文件被拒绝 | 确认它是运行结束后复制的完整单文件，复制期间没有别的进程在写。不要删除还没合并的 WAL 文件。外部文件会经过完整性和数据一致性校验。 |
 | 不支持的格式版本或数据库无效 | 保留原文件，核实写入它的 NiceEval 版本。支持的历史格式会自动升级；未知格式或损坏的数据不会被修补，也不会只读一部分。 |
-| Run 仍为 `active`，但原进程已经终止 | 先用 `pnpm exec niceeval run show <run-id>` 核对，再运行 `pnpm exec niceeval run recover <run-id> --yes`。 |
+| Run 仍为 `active`，但原进程已经终止 | 先用 `pnpm exec niceeval show --run <run-id>` 核对，再运行 `pnpm exec niceeval run recover <run-id> --yes`。 |
 
 已发布的结果不能手动修改。需要不同的结果时，重新运行创建新的 Run。`niceeval run recover` 只会结束能证明原进程已经终止的 Run，已经发布的 Attempt 都会保留。完整步骤见[运行被强杀后恢复](/zh/troubleshooting/recover-after-kill)。
 
@@ -78,7 +78,7 @@ query discover
 
 这里的格式版本是结果文件内部的标识，和 NiceEval 的 npm 包版本无关。不要通过修改数据库里的版本字段尝试升级。
 
-`show`、`query`、`run list`、`run show` 与 `view` 可以直接读取 0.15、0.16、0.17 格式的历史结果文件。读取时 NiceEval 在私有副本里自动升级，原文件、Run、Attempt 和引用都保持不变，不需要先运行评估。
+`show`、`query`、`run list`、`show --run` 与 `view` 可以直接读取 0.15、0.16、0.17 格式的历史结果文件。读取时 NiceEval 在私有副本里自动升级，原文件、Run、Attempt 和引用都保持不变，不需要先运行评估。
 
 用 `--record` 读取时，文件必须是已经交付的完整单文件，读取期间不能被其它进程修改。文件还带着未合并的 WAL、仍有运行在写，或无法确认写入进程是否已经结束时，命令会拒绝读取。不要删除旁边的文件来绕过检查。
 

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

@@ -14,7 +14,7 @@ description: "进程被 kill -9、CI 超时或断电中断后，保留已经跑
 
 ```bash
 pnpm exec niceeval run list --invocation <invocation-id>
-pnpm exec niceeval run show <run-id>
+pnpm exec niceeval show --run <run-id>
 pnpm exec niceeval show --run <run-id>
 ```
 

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

@@ -49,7 +49,7 @@ import { defineConfig } from "niceeval";
 import { OpenAIProvider } from "niceeval/judge";
 
 export default defineConfig({
-  judgeRuntime: OpenAIProvider({
+  judgeProvider: OpenAIProvider({
     model: "gpt-5.4-mini",                // 必填：没有内置默认模型
     // 使用 OpenAI 兼容网关时显式加下列两项：
     // baseUrl: "https://api.deepseek.com/v1",
@@ -65,7 +65,7 @@ export default defineConfig({
 - **配错不会假装通过。** 读不到模型或 key、请求超时时，Judge 断言记为 `unavailable` 并带上原因；网关拒绝请求、返回格式不对时记为 `errored`。结果里不会把拿不到的分数显示成不通过或零分。
 - **配完先验一次。** 用 `defineJudge` 声明 rubric 和 anchors，再调用 `t.judge(material, definition).gate(0.8)`。跑完后用 `pnpm exec niceeval show --run <run-id>` 查看分数，步骤见[配置并验证 Judge](/zh/tutorials/verify-judge)。
 - **没有用户在场（自治接入）时不要直接跳过 Judge**：先看环境里是否已有与所选 Provider 对应的 key。有就验证；没有时先写精确 Match，并在收尾说明 Judge 没有配置。
-- Judge 模型要**与被测 Agent 分离**，避免同一个模型给自己的输出打分。执行配置从 Experiment 和项目配置的 `judgeRuntime` 求值；定义与材料见 [Judge](/zh/explanation/judge)。
+- Judge 模型要**与被测 Agent 分离**，避免同一个模型给自己的输出打分。执行配置从 Experiment 和项目配置的 `judgeProvider` 求值；定义与材料见 [Judge](/zh/explanation/judge)。
 
 ## 第 3 步：写 Adapter、Experiment 和评估用例
 

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

@@ -68,7 +68,7 @@ t.calledTool("get_weather").label("调用了天气工具");
 
 | 属性 | 内容 |
 |---|---|
-| `turn.message` | 助手的文本回复 |
+| `turn.reply` | 助手的文本回复 |
 | `turn.toolCalls` | 这一轮的工具调用 |
 | `turn.data` | 结构化输出 |
 | `turn.status` | `"completed"`、`"failed"` 或 `"waiting"` |
@@ -111,7 +111,7 @@ const grounded = defineJudge({
 export default defineEval({
   async test(t) {
     const turn = await t.send("北京今天天气怎么样？");
-    t.judge({ question: turn.input, answer: turn.message }, grounded).gate(0.7).label("回答有依据");
+    t.judge({ question: turn.input, answer: turn.reply }, grounded).gate(0.7).label("回答有依据");
   },
 });
 ```

package/docs-site/zh/tutorials/compare-runs.mdx

@@ -23,7 +23,7 @@ View 会同时打开两个 Run，你可以逐题对照通过与否、分数、
 ```sh
 pnpm --silent exec niceeval query run --request - <<'JSON'
 {
-  "protocol": "niceeval.query/v1",
+  "protocol": "niceeval.query/v2",
   "operation": {
     "kind": "runs.compare",
     "mode": "paired",

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

@@ -80,23 +80,23 @@ pnpm exec niceeval exp compare --max-concurrency 19
 
 ## 名额怎么分
 
-下面是一批混跑：全局 3 个并发位，`fast` 是普通实验，`slow` 声明了 `maxConcurrency: 1`。
+下面是一批混跑：全局 3 个并发名额，`fast` 是普通实验，`slow` 声明了 `maxConcurrency: 1`。
 
 <Schedule
   title="全局 3 位 · slow 实验自己限 1"
   hint="竖线是时间，悬停暂停"
   lanes={[
-    { label: "并发位 1", bars: [
+    { label: "并发名额 1", bars: [
       { text: "slow · a1", from: 1, to: 5, tone: "serial" },
       { text: "slow · a2", from: 5, to: 9, tone: "serial" },
       { text: "slow · a3", from: 9, to: 13, tone: "serial" },
     ] },
-    { label: "并发位 2", bars: [
+    { label: "并发名额 2", bars: [
       { text: "fast · a1", from: 1, to: 4 },
       { text: "fast · a3", from: 4, to: 8 },
       { text: "fast · a5", from: 8, to: 13 },
     ] },
-    { label: "并发位 3", bars: [
+    { label: "并发名额 3", bars: [
       { text: "fast · a2", from: 1, to: 3 },
       { text: "fast · a4", from: 3, to: 7 },
       { text: "fast · a6", from: 7, to: 13 },
@@ -108,7 +108,7 @@ pnpm exec niceeval exp compare --max-concurrency 19
   legend={[
     { text: "普通实验，抢空出来的位" },
     { tone: "serial", text: "声明了 maxConcurrency: 1，永远只占一条" },
-    { tone: "backoff", text: "退避重试，让出并发位但仍计 running" },
+    { tone: "backoff", text: "退避重试，让出并发名额但仍计 running" },
   ]}
 />
 
@@ -118,9 +118,9 @@ pnpm exec niceeval exp compare --max-concurrency 19
 - **名额优先给还要跑最多轮的实验。** 快慢实验放在一条命令里跑是安全的，不需要手工分批，也不需要给快任务预留名额。快的任务会自动补上空位。
 - **退避重试中的 Attempt 让出全局位，但不让出实验自己的位。** 所以撞上限流时，live 面板的 `running` 会超过上限，超出的数量正好是正在退避的数量。任一时刻真正在执行的仍然不超过上限，这不是并发失效。
 
-等待实验级 `setup`（起隧道、起共享服务）的 Attempt 不占并发位，计数里显示为 `queued`。所以隧道启动慢时，面板长时间显示 “0 running、N queued”，问题在 `setup`，不在并发配置。
+等待实验级 `setup`（起隧道、起共享服务）的 Attempt 不占并发名额，计数里显示为 `queued`。所以隧道启动慢时，面板长时间显示 “0 running、N queued”，问题在 `setup`，不在并发配置。
 
-等待 Docker profile 容量的 Attempt 也显示为 `queued`，排队原因是 `provider-capacity`。它不会显示 `creating sandbox`，也不占普通并发位。profile 有空余后，它重新拿到并发位，分到资源才进入 `running`。同批用其它 Provider 的 Attempt 可以继续启动，不会被排在前面的 Docker 任务卡住。
+等待 Docker profile 容量的 Attempt 也显示为 `queued`，排队原因是 `provider-capacity`。它不会显示 `creating sandbox`，也不占普通并发名额。profile 有空余后，它重新拿到并发名额，分到资源才进入 `running`。同批用其它 Provider 的 Attempt 可以继续启动，不会被排在前面的 Docker 任务卡住。
 
 ## 在 live 面板确认并发生效
 
@@ -178,7 +178,7 @@ const fixtures = new WeakMap<Sandbox, { repoUrl: string; destroy(): Promise<void
 
 ## 让相关评估按组复用 Sandbox
 
-只有几组评估需要共享环境时，用 `defineEvalGroup()` 列出同组成员。每个组同一时刻只跑一个 Attempt，最多复用一台 Sandbox；不同组和没分组的评估用例继续用剩下的并发位。你不需要把整个 Experiment 设成 `maxConcurrency: 1`。
+只有几组评估需要共享环境时，用 `defineEvalGroup()` 列出同组成员。每个组同一时刻只跑一个 Attempt，最多复用一台 Sandbox；不同组和没分组的评估用例继续用剩下的并发名额。你不需要把整个 Experiment 设成 `maxConcurrency: 1`。
 
 `evals` 数组只列成员，不决定顺序。组内按评估用例 ID 排序执行；`attempts > 1` 时，同一道题的几次 Attempt 连续跑完再轮到下一道。完整目录、Experiment 写法和 `--dry` 检查见[用评估组复用 Sandbox](/zh/tutorials/eval-groups)。