niceeval 0.17.1 → 0.19.0

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

@@ -50,7 +50,7 @@ import { defineConfig } from "niceeval";
 import { OpenAIProvider } from "niceeval/judge";
 
 export default defineConfig({
-  judgeRuntime: OpenAIProvider({ model: "gpt-5.4-mini" }),
+  judgeProvider: OpenAIProvider({ model: "gpt-5.4-mini" }),
   maxConcurrency: 4,
   timeoutMs: 300_000,
 });
@@ -61,7 +61,7 @@ export default defineConfig({
 | 字段 | 放什么 |
 | --- | --- |
 | `name` | 项目名，显示在 `niceeval view` 顶部。可按语言给多份 |
-| `judgeRuntime` | 默认裁判 Provider，由 `niceeval/judge` 的具名工厂构造 |
+| `judgeProvider` | 默认裁判 Provider，由 `niceeval/judge` 的具名工厂构造 |
 | `workspace` | 上传进 Sandbox 的工作区根目录 |
 | `reporters` | 默认 reporter 列表（落盘、上报实验平台） |
 | `maxConcurrency` | 默认并发上限 |
@@ -80,7 +80,7 @@ export default defineConfig({
 | `ANTHROPIC_API_KEY` | `claudeCodeAgent()` | 工厂参数 `apiKey` 可覆盖 |
 | `ANTHROPIC_BASE_URL` | `claudeCodeAgent()` | 网关地址，工厂参数 `baseUrl` 可覆盖 |
 | `CODEX_API_KEY` / `CODEX_BASE_URL` | `codexAgent()` | key 必需，代理地址可选；工厂参数 `apiKey` / `baseUrl` 可覆盖 |
-| `BUB_API_KEY` / `BUB_API_BASE` | `bubAgent()` | 两者必需；工厂参数 `apiKey` / `apiBase` 可覆盖 |
+| `BUB_API_KEY` / `BUB_API_BASE` | `bubAgent()` | 两者必需；工厂参数 `apiKey` / `baseUrl` 可覆盖 |
 | `OPENCLAW_API_KEY` / `OPENCLAW_BASE_URL` | `openClawAgent()` | key 省略时回落 `ANTHROPIC_API_KEY` |
 | `OPENCODE_API_KEY` / `OPENCODE_BASE_URL` | `openCodeAgent()` | key 省略时回落 `ANTHROPIC_API_KEY` |
 | `HERMES_API_KEY` / `HERMES_API_BASE` | `hermesAgent()` | key 省略时依次回落 `OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY` |
@@ -100,7 +100,7 @@ export default defineConfig({
 import { OpenAIProvider } from "niceeval/judge";
 
 export default defineConfig({
-  judgeRuntime: OpenAIProvider({
+  judgeProvider: OpenAIProvider({
     model: "gpt-5.4-mini",
     baseUrl: "https://gateway.example.com/v1",   // 网关地址是配置，写在这里
     apiKeyEnv: "MY_GATEWAY_KEY",                  // key 是密钥，读这个环境变量
@@ -112,7 +112,7 @@ export default defineConfig({
 
 ```ts
 export default defineConfig({
-  judgeRuntime: OpenAIProvider({
+  judgeProvider: OpenAIProvider({
     model: "gpt-5.4-mini",
     baseUrl: process.env.MY_GATEWAY_URL,   // 变量名自己起，自己读
     apiKeyEnv: "MY_GATEWAY_KEY",

package/docs-site/zh/tutorials/control-run-cost.mdx

@@ -113,36 +113,36 @@ Attempt 页面先显示应用和 Judge 的合计费用：
 Headless Adapter 使用 `ctx.recordUsage` 登记真实调用，并在采集结束后调用 `ctx.sealUsage`。随后可以直接用 `t.usage.cacheRead` 设置缓存读取率门槛：
 
 ```ts
-import { atLeast } from "niceeval/expect";
+import { atLeast, ratio } from "niceeval/expect";
 
-t.check(t.usage.cacheRead.rate("planner"), atLeast(0.6)).gate();
+t.check(t.usage.cacheRead.rate("planner"), atLeast(ratio(0.6))).gate();
 // 不区分用途时，检查所有已登记调用的合计。
-t.check(t.usage.cacheRead.rate(), atLeast(0.6)).gate();
+t.check(t.usage.cacheRead.rate(), atLeast(ratio(0.6))).gate();
 ```
 
 读取率是同组调用的 **缓存读取 token 总量 / 含缓存输入 token 总量**，包括失败调用与重试。它不是逐次百分比的平均值。每次调用优先使用 `inputTotalTokens`；没有独立总量时，必须同时提供 `inputTokens`、`cacheReadTokens`、`cacheWriteTokens` 三个互斥桶。
 
-`cacheRead.total` 给出整个 Attempt 的结果，`modelSlots` 按用途分组，`models` 进一步按真实 `provider` 和 `model` 分组。未知身份保持 `null`，不会用配置值补齐。`coveredCalls / recordedCalls` 表示已登记调用的输入覆盖率；`collectionComplete` 单独表示采集是否完整。
+`cacheRead.total` 给出整个 Attempt 的结果，`roles` 按用途分组，`models` 进一步按真实 `provider` 和 `model` 分组。未知身份保持 `null`，不会用配置值补齐。`coveredCalls / recordedCalls` 表示已登记调用的输入覆盖率；`collectionComplete` 单独表示采集是否完整。
 
 缺失输入、未 seal、partial seal、unknown 调用状态、空组或零分母均返回 `unavailable`，`reasons` 列出原因。缺失不按零处理；完整且有正输入总量的零缓存读取率才是数值 0。旧账本没有明确的生产者完整性声明时，也返回不可判定。
 
 使用 `niceeval show <Attempt locator> --usage` 或 View 查看读取率、覆盖情况与原因；脚本通过 `attempt.usage` 的 `usage.cacheRead` 读取相同报告。已有 `recordUsage` 调用无需改名，但必须登记缓存 token，并在采集完成后诚实 seal。无需迁移历史结果文件。
 
 
-槽位名来自 Experiment 的 `models` 键，不是框架内置名单。`model` 单模型简写对应 `default`。
-传入未声明的槽位会在调用处报错，并列出可用名称。已声明但完整记录中没有调用的槽位返回 `slot-has-no-calls`；采集不完整时仍返回 `collection-incomplete`。
-Eval 可以被多个 Experiment 复用，因此此入口在运行回调里校验槽位，不在定义期检查动态字符串。
+角色名来自 Experiment 的 `models` 键，不是框架内置名单。`model` 单模型简写对应 `default`。
+传入未声明的角色会在调用处报错，并列出可用名称。已声明但完整记录中没有调用的角色返回 `role-has-no-calls`；采集不完整时仍返回 `collection-incomplete`。
+Eval 可以被多个 Experiment 复用，因此此入口在运行回调里校验角色，不在定义期检查动态字符串。
 
 ### 登记命令行 Agent 的用量
 
-Adapter 应按外部回执记录真实调用，并将 `modelSlot` 设为 Experiment 声明的用途，例如 `mind`。
+Adapter 应按外部回执记录真实调用，并将 `modelRole` 设为 Experiment 声明的用途，例如 `mind`。
 同一请求的流式增量和最终回执不能各登记一次；先按请求 ID 合并，收到最终回执后再登记。
 
 ```ts
 // 单次 Claude 请求的最终 usage；字段缺失时保留 null。
 ctx.recordUsage({
   callId: requestId,
-  modelSlot: "mind",
+  modelRole: "mind",
   provider: observedProvider,
   model: observedModel,
   status: observedStatus,
@@ -168,3 +168,43 @@ ctx.sealUsage({ state: "partial", reason: "usage-not-exposed" });
 ```
 
 确实拿到全部物理调用的最终记录后，再调用 `ctx.sealUsage({ state: "complete" })`。
+
+## 让模型用途名称参与类型检查
+
+从 0.18 起，共享声明让同一评估可用于多个实验，同时在编译时检查用途名称：
+
+```ts title="models.ts"
+import { defineModelRoles } from "niceeval";
+
+export const roles = defineModelRoles({
+  mind: { model: "provider/planner" },
+  speech: { model: "provider/speaker" },
+});
+```
+
+在已有 Adapter 的绑定工厂上声明要求。也可解构 `adapter.defineScoreEval`，但根入口的同名工厂不接受 `requires`：
+
+```ts title="evals/cache.eval.ts"
+import { atLeast, ratio } from "niceeval/expect";
+import { adapter } from "../adapter";
+import { roles } from "../models";
+
+export default adapter.defineScoreEval({
+  requires: { models: roles },
+  test(t) {
+    t.check(t.usage.cacheRead.rate("mind"), atLeast(ratio(0.6))).gate();
+    // rate("mimd") 会产生 TypeScript 错误；rate() 仍查询全部用途的合计。
+  },
+});
+```
+
+实验使用 `defineExperiment({ adapter, models: roles, evals: ["cache"] })`。
+其它实验可为这些用途选择不同模型；`requires` 要求用途存在，不要求模型值相同。
+加载实验时会检查它选中的全部评估，CLI 的标签或前缀过滤不能隐藏缺失用途。
+
+给 `defineAdapter` 也传入 `requires: { models: roles }`，即可同时收窄 `ctx.models` 和 `ctx.recordUsage` 的 `modelRole`。
+`null` 或省略的 `modelRole` 仍表示未归属到用途的调用。已声明但本次没有调用时，`rate` 返回原因 `role-has-no-calls` 的不可用材料。
+
+0.17.x 中省略 `requires` 的写法在 0.18 继续兼容，名称仍在调用时校验。
+迁移时先提取共享声明，再给 Adapter 和绑定评估分别添加 `requires`。
+不要先把声明标注成 `Record<string, ModelRoleSelection>`，否则 TypeScript 已丢失具体键，无法检测拼写错误。

package/docs-site/zh/tutorials/eval-groups.mdx

@@ -98,7 +98,7 @@ export default defineExperiment({
 });
 ```
 
-这里不要写 `sandboxReuse: true`。`maxConcurrency: 4` 是整个 Experiment 的上限，不会让同组同时跑四个；剩下的并发位留给其它组和没分组的评估用例。
+这里不要写 `sandboxReuse: true`。`maxConcurrency: 4` 是整个 Experiment 的上限，不会让同组同时跑四个；剩下的并发名额留给其它组和没分组的评估用例。
 
 评估组只能和在 Sandbox 里运行的 Agent、支持复用的 Provider 一起用。不带 Sandbox 的 Agent 不能运行评估组。
 

package/docs-site/zh/tutorials/evaluation-kinds.mdx

@@ -25,7 +25,7 @@ export default defineEval({
   async test(t) {
     const turn = await t.send("修复测试并说明原因。");
 
-    t.check(turn.message, includes("原因")).label("说明失败原因");
+    t.check(turn.reply, includes("原因")).label("说明失败原因");
 
     const tests = await t.sandbox.runCommand("pnpm", ["test"]);
     await t.check(tests, commandSucceeded()).label("测试通过").orStop();
@@ -40,7 +40,7 @@ Boolean `matched` 进入 Verdict；`mismatched` 使最终 Verdict 为 `failed`
 `similarity(...)` 这类 Match 产生 `[0, 1]` 的 measurement。它计算字符级 Levenshtein 编辑相似度，不判断语义。通过制评估在 handle 上用 `.gate(minimum)` 建立质量门：
 
 ```ts
-t.check(turn.message, similarity(expected))
+t.check(turn.reply, similarity(expected))
   .gate(0.8)
   .label("回答接近期望内容");
 ```
@@ -66,7 +66,7 @@ export default defineScoreEval({
     t.check(health, commandSucceeded()).score(1).label("健康检查可达");
     t.check(health.stdout, includes("ok")).score(1).label("健康检查内容正确");
 
-    t.check(turn.message, includes("验证")).score(2).label("回复说明验证方法");
+    t.check(turn.reply, includes("验证")).score(2).label("回复说明验证方法");
 
     t.score(1).label("代码精简");
   },
@@ -89,7 +89,7 @@ export default defineScoreEval({
 ## Judge 也是 Measurement
 
 `defineJudge` 声明一个受管 Judge Match。作者把完成判断所需的值组成带语义字段的材料。
-裁判可以直接传给 `t.judge`，无需在评估上登记。模型默认使用项目的 `judgeRuntime`；单题只换模型时设置 `judge: "judge-model"`。
+裁判可以直接传给 `t.judge`，无需在评估上登记。模型默认使用项目的 `judgeProvider`；单题只换模型时设置 `judge: "judge-model"`。
 
 ```ts
 const explainsMotive = defineJudge({
@@ -105,7 +105,7 @@ export default defineEval({
   async test(t) {
     const change = "把缓存键加入模型版本";
     const turn = await t.send(`说明这项变更的动机和风险：${change}`);
-    const material = { change, explanation: turn.message };
+    const material = { change, explanation: turn.reply };
     t.judge(material, explainsMotive).gate(0.8).label("变更动机");
     t.judge(material, explainsRisk).gate(0.8).label("具体风险");
   },

package/docs-site/zh/tutorials/experiment-services.mdx

@@ -1,31 +1,31 @@
 ---
 title: "启动实验共享服务"
 sidebarTitle: "实验共享服务"
-description: "用 Experiment 的 setup / teardown 启停整个实验共用的隧道、mock server 或租约，把运行时地址交给 Agent 和 Sandbox，又不让它作废已有结果。"
+description: "用 Experiment 的 before / after 启停整个实验共用的隧道、mock server 或租约，把运行时地址交给 Agent 和 Sandbox，又不让它作废已有结果。"
 ---
 
 你在评估一个接入了记忆服务的 Coding Agent。记忆服务跑在内网，每次评估前要先开一条隧道，拿到一个临时地址，再把地址告诉 Agent。隧道开一次就够，几十个 Attempt 共用；全部跑完后要记得关掉。
 
-这类“一个实验一份、所有 Attempt 共用”的资源，写进 Experiment 的 `setup` 和 `teardown`。
+这类“一个实验一份、所有 Attempt 共用”的资源，写进 Experiment 的 `before` 和 `after`。
 
-## 写一对 setup / teardown
+## 写一对 before / after
 
 ```ts
 // experiments/memory/codex.ts
 import { defineExperiment } from "niceeval";
 import { nowledgeAgent, nowledgeTunnel } from "../../agents/nowledge.ts";
 
-// setup 拿到的坐标放在模块变量里，teardown 和 Agent 都能读到
+// before 拿到的坐标放在模块变量里，after 和 Agent 都能读到
 let tunnel: { url: string; apiKey: string; stop(): Promise<void> } | undefined;
 
 export default defineExperiment({
   agent: nowledgeAgent(() => ({ url: tunnel!.url, apiKey: tunnel!.apiKey })),
   evals: ["memory/"],
-  async setup(ctx) {
+  async before(ctx) {
     ctx.progress({ message: "starting nowledge tunnel" });
     tunnel = await nowledgeTunnel({ signal: ctx.signal });
   },
-  async teardown(ctx) {
+  async after(ctx) {
     ctx.progress({ message: "stopping nowledge tunnel" });
     await tunnel?.stop();
   },
@@ -34,23 +34,23 @@ export default defineExperiment({
 
 两个回调在你自己的机器上执行，各自最多跑一次：
 
-- `setup` 在这个实验第一个要真正执行的 Attempt 之前运行。
-- `teardown` 在全部 Attempt 结束后运行，运行被中断时也会执行。
-- 只要 `setup` 开始过，`teardown` 就一定会执行，`setup` 抛错也一样。所以 `teardown` 里要防御变量还没赋值的情况，上面用的是 `tunnel?.stop()`。
+- `before` 在这个实验第一个要真正执行的 Attempt 之前运行。
+- `after` 在全部 Attempt 结束后运行，运行被中断时也会执行。
+- 只要 `before` 开始过，`after` 就一定会执行，`before` 抛错也一样。所以 `after` 里要防御变量还没赋值的情况，上面用的是 `tunnel?.stop()`。
 - 上次的结果全部能沿用、这次一个 Attempt 都不用真正执行时，两者都不会运行。
 
-`setup` 运行期间，终端 `ACTIVE` 区会显示一行 `experiment setup · <实验 id>`，`ctx.progress(...)` 的消息更新在这一行末尾。这时该实验的 Attempt 计入排队数，不是卡住了。
+`before` 运行期间，终端 `ACTIVE` 区会显示一行 `experiment before · <实验 id>`，`ctx.progress(...)` 的消息更新在这一行末尾。这时该实验的 Attempt 计入排队数，不是卡住了。
 
-## setup 失败时会发生什么
+## before 失败时会发生什么
 
-`setup` 抛错时，这个实验的每个 Attempt 都记为 `errored`，错误码是 `experiment-setup-failed`。同一批里的其它实验照常运行。环境没起来不会被算成通过，也不会拖累别的实验。
+`before` 抛错时，这个实验的每个 Attempt 都记为 `errored`，错误码是 `experiment-setup-failed`。同一批里的其它实验照常运行。环境没起来不会被算成通过，也不会拖累别的实验。
 
-## teardown 里先保证释放
+## after 里先保证释放
 
 释放资源是必须做到的事，健康检查、上报指标这类观测只是尽力而为。用 `try/finally` 包住，观测出错也不能挡住释放；运行被中断时直接跳过观测：
 
 ```ts
-async teardown(ctx) {
+async after(ctx) {
   try {
     if (!ctx.signal.aborted) {
       await tunnel?.probe({ timeoutMs: 10_000 }).catch(() => {});
@@ -76,7 +76,7 @@ export default defineExperiment({
     .before(async (sandbox) => {
       await sandbox.writeText(".nowledge/env", `NMEM_URL=${endpoint!}\n`);
     }),
-  async setup(ctx) {
+  async before(ctx) {
     endpoint = (await nowledgeTunnel({ signal: ctx.signal })).url;
   },
 });
@@ -95,12 +95,12 @@ $ pnpm exec niceeval exp compare/codex--nowledge
 判断一个值该放哪里，问一句：它是不是你想比较的实验条件？
 
 - 是，例如记忆服务的版本号 `0.10.39`，换版本行为可能真的不同，写进 `flags`，变了就该重跑。
-- 不是，只是这一次的连接坐标，留在 `setup` 和模块变量里。
+- 不是，只是这一次的连接坐标，留在 `before` 和模块变量里。
 - 只用来给报告分组的标注，写 `labels`。
 
 ## 在 Sandbox 里准备环境
 
-`setup` / `teardown` 管的是你机器上的服务。Agent 运行前要在 Sandbox 里做的准备，例如写入配置、装二进制、载入上次保存的状态，挂在 `sandbox` 的 `.before()` 上。它对每个真正执行的 Attempt 跑一次，一定晚于 `setup`，所以能读到 `setup` 赋好的变量：
+`before` / `after` 管的是你机器上的服务。Agent 运行前要在 Sandbox 里做的准备，例如写入配置、装二进制、载入上次保存的状态，挂在 `sandbox` 的 `.before()` 上。它对每个真正执行的 Attempt 跑一次，一定晚于 `before`，所以能读到 `before` 赋好的变量：
 
 ```ts
 // experiments/compare/claude--nowledge.ts
@@ -128,16 +128,16 @@ export default defineExperiment({
         await saveMemoryState(sandbox, ctx.experimentId);
       });
     }),
-  async setup(ctx) {
+  async before(ctx) {
     tunnel = await nowledgeTunnel({ signal: ctx.signal });
   },
-  async teardown() {
+  async after() {
     await tunnel?.stop();
   },
 });
 ```
 
-从上往下读，这个文件就是完整的运行说明：整个实验一份的服务在 `setup` / `teardown`，每个 Sandbox 的准备和收尾在 `.before()` 和 `ctx.onCleanup`。
+从上往下读，这个文件就是完整的运行说明：整个实验一份的服务在 `before` / `after`，每个 Sandbox 的准备和收尾在 `.before()` 和 `ctx.onCleanup`。
 
 Agent CLI、系统包这类固定不变的安装，最好先做进镜像或 template。NiceEval 会复用没变的准备步骤，不会因为评估用例改了就重装一遍。做法见 [预制 Sandbox 环境 · 从官方基线继续构建](/zh/tutorials/prebuilt-sandbox#从官方基线继续构建)。
 
@@ -164,18 +164,18 @@ export function nowledgeLifecycle() {
   let env: { url: string; apiKey: string } | undefined;
 
   return {
-    /** Agent 工厂经它读连接信息，setup 之后才有值 */
+    /** Agent 工厂经它读连接信息，before 之后才有值 */
     endpoint: () => env!,
 
-    async setup(ctx: ExperimentHookContext) {
+    async before(ctx: ExperimentHookContext) {
       instance = `exp-${ctx.experimentId.replace(/[^A-Za-z0-9]+/g, "-")}`;
       ctx.progress({ message: `[nowledge] activating ${instance}` });
       await memctl("up", instance);
       env = await readInstanceEnv(instance);
     },
 
-    async teardown() {
-      if (!instance) return; // setup 还没起实例就失败了，没有要清理的
+    async after() {
+      if (!instance) return; // before 还没起实例就失败了，没有要清理的
       await memctl("down", instance);
     },
 
@@ -198,15 +198,15 @@ const nowledge = nowledgeLifecycle();
 export default defineExperiment({
   agent: codexAgent(nowledgeCodexConfig(nowledge.endpoint)),
   sandbox: e2bSandbox({ template: CODEX_TEMPLATE }).before(nowledge.sandboxBefore()),
-  setup: nowledge.setup,
-  teardown: nowledge.teardown,
+  before: nowledge.before,
+  after: nowledge.after,
   maxConcurrency: 1,
 });
 ```
 
 这样写要守住两条，多个实验并发运行时才不会互相覆盖：
 
-- 工厂函数被调用时只创建闭包，不做 I/O，也不读配置。`niceeval exp` 在发现阶段就会 import 实验文件，这时抛错会连累同一批里无关的实验。所有可能失败的操作都放进 `setup`。
+- 工厂函数被调用时只创建闭包，不做 I/O，也不读配置。`niceeval exp` 在发现阶段就会 import 实验文件，这时抛错会连累同一批里无关的实验。所有可能失败的操作都放进 `before`。
 - 运行时坐标放在工厂闭包里，不放在模块级单例里。并行的两个实验各持一份，互不覆写。
 
 服务起多份太贵、必须让同一批实验共用一个实例时，用引用计数：第一个进来的启动，最后一个离开的关闭。
@@ -218,12 +218,12 @@ let starting: Promise<void> | undefined;
 let service: { url: string; stop(): Promise<void> } | undefined;
 
 export const sharedNowledge = {
-  async setup() {
+  async before() {
     refs += 1;
     starting ??= startNowledge().then((s) => { service = s; });
     await starting; // 并发的实验等同一次启动
   },
-  async teardown() {
+  async after() {
     refs -= 1;
     if (refs === 0) {
       await service?.stop(); // 启动失败时 service 没有值
@@ -234,10 +234,10 @@ export const sharedNowledge = {
 };
 ```
 
-因为 `setup` 开始过就一定会配对执行 `teardown`，计数总能回到 0，不会泄漏。
+因为 `before` 开始过就一定会配对执行 `after`，计数总能回到 0，不会泄漏。
 
 ## 跨多次运行存在的服务
 
-`setup` 启动的服务活不过这一次 `niceeval exp`。需要先起好、连续跑好几次的服务，用 `docker compose` 这类外部工具启停，再通过环境变量把地址传给 Adapter。
+`before` 启动的服务活不过这一次 `niceeval exp`。需要先起好、连续跑好几次的服务，用 `docker compose` 这类外部工具启停，再通过环境变量把地址传给 Adapter。
 
-`setup` 和 `teardown` 的完整参数见 [Experiment](/zh/explanation/experiment)。Sandbox 准备步骤的顺序、缓存和收尾见 [Sandbox · 按顺序准备 Sandbox](/zh/tutorials/sandbox-providers#按顺序准备-sandbox)。
+`before` 和 `after` 的完整参数见 [Experiment](/zh/explanation/experiment)。Sandbox 准备步骤的顺序、缓存和收尾见 [Sandbox · 按顺序准备 Sandbox](/zh/tutorials/sandbox-providers#按顺序准备-sandbox)。

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

@@ -95,35 +95,9 @@ export default defineEval({
 
 错误消息会出现在终端和运行记录中。请写明发生了什么，以及下一步怎么修复。
 
-## 识别运行中断开的共享服务
+## 共享服务在执行中断开
 
-有些共享服务在实验开始时正常，却在运行中断开。这种失败通常由 SDK、CLI 或网络库抛出。你可以用实验的 `classifyFailure` 识别自己的服务地址：
-
-```ts
-// experiments/compare.ts
-import { defineExperiment } from "niceeval";
-
-const serviceHost = "memory.internal.example";
-
-export default defineExperiment({
-  // agent 和 sandbox 配置省略
-  classifyFailure({ text }) {
-    const isOurService = text.includes(serviceHost);
-    const isConnectionFailure = /ECONNREFUSED|ENOTFOUND|connection refused/i.test(text);
-
-    if (isOurService && isConnectionFailure) {
-      return {
-        retryable: false,
-        scope: "experiment",
-        reason: "shared_service_unavailable",
-      };
-    }
-    return undefined;
-  },
-});
-```
-
-只识别你能确定影响范围的服务。不要把所有 `ECONNREFUSED` 都当成实验级故障，因为 Agent 访问其他站点时也可能出现同样的错误。
+在能够确认影响范围的调用边界捕获 SDK 错误，抛出 `ExperimentFatalError` 或 `EvalFatalError`，并通过 cause 保留原始错误。Experiment 不再接受 `classifyFailure`；内建重试规则与 Adapter 的 `classifySendFailure` 保留。
 
 ## 修好后补跑没完成的部分
 

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

@@ -1,176 +1,82 @@
 ---
-title: "用 Plugin 复用一整套运行条件"
+title: "用 Plugin 复用运行条件"
 sidebarTitle: "Plugin"
-description: "同一套“先在宿主机起服务、再在 Sandbox 里准备环境”的条件要在多个 Experiment、评估组或评估用例里用时，用 definePlugin 写一次，到处挂载。"
+description: "把 Agent 扩展、Sandbox 步骤与宿主生命周期装进一个可复用的实验条件。"
 ---
 
-你的几个对比实验都要接同一个记忆服务：在宿主机上开一条隧道，再在 Sandbox 里写入连接配置、装好命令行工具。把这些代码复制到每个 Experiment 里，改一处就要改好几处。
+多个 Experiment 使用相同 Skill、MCP 服务或环境准备时，把条件写成一个 Plugin，再通过 `plugins` 数组挂载。
+Plugin 声明条件；Sandbox template 仍由 Eval、Eval Group 或 Experiment 的 `sandbox` 字段提供。
 
-Plugin 把这样一整套条件写在一起：它叫什么、宿主机上要起停什么、Sandbox 里要执行哪些准备命令。写好后挂到 Experiment、评估组或评估用例上就能复用。
+## 定义实例或工厂
 
-Plugin 只负责条件本身，不负责选环境：用哪个 Docker 镜像、E2B template 或 Vercel snapshot，仍由 `sandbox` 字段决定。
-
-Agent 自己的 Skill、MCP server 和原生 Plugin 也不归这里管，它们仍传给 Agent factory，例如 `codexAgent({ plugins: [...] })`。
-
-## 第 1 步：写一个 Plugin
-
-把这套条件写成一个 Plugin，放在几个 Experiment 都能导入的位置。所有 Plugin API 从 `niceeval/plugin` 导入。
-
-下面这个例子在宿主机上起停记忆服务，并在 Sandbox 里上传插件文件、写入连接配置：
+对象定义直接得到实例，函数定义得到单参数工厂。`name` 与 `identity` 必填；`key` 默认 `"default"`。
 
 ```ts
-// experiments/shared/memory.ts
 import { definePlugin } from "niceeval/plugin";
-import {
-  changeFrequency,
-  sandboxLayer,
-  uploadDirectory,
-  writeText,
-} from "niceeval/sandbox";
-
-type MemoryOptions = {
-  readonly model: string;
-};
-
-export const memory = definePlugin<MemoryOptions>({
-  name: "acme.memory",
-  behaviorRevision: "2",
-  instanceKey: ({ model }) => model,
-
-  experiment: ({ model }) => ({
-    identity: { model },
-    setup: (context) => {
-      context.progress({ message: `启动 ${model} memory service` });
-    },
-    teardown: (context) => {
-      context.progress({ message: `停止 ${model} memory service` });
-    },
-  }),
-
-  sandbox: ({ model }) => sandboxLayer()
-    .before(uploadDirectory({
-      id: "memory-plugin-files",
-      source: new URL("fixtures/memory-plugin/", import.meta.url),
-      to: ".agents/plugins/memory",
-      changeFrequency: changeFrequency.rare,
-    }))
-    .before(writeText({
-      id: "memory-plugin-config",
-      path: ".memory/config.json",
-      text: JSON.stringify({ model }),
-      changeFrequency: changeFrequency.frequent,
-    })),
-});
-```
-
-几个字段各管一件事：
-
-- `name` 和 `instanceKey` 一起区分同一个 Plugin 的不同实例，这里按 `model` 区分。
-- `experiment` 里的 `setup` / `teardown` 在宿主机上运行，适合起停服务、开隧道。
-- `sandbox` 返回一个 `sandboxLayer()`，里面用和普通代码相同的 `.before()` / `.after()` 准备 Sandbox。
-
-Sandbox 里的准备步骤用内置的 `uploadDirectory()`、`writeText()`、`gitCheckout()`、`shell()` 等函数写。它们和 Experiment、评估用例里的准备步骤一起排序，没变的步骤在 Docker 上可以直接沿用上次的准备结果。Plugin 不需要自己处理上传或 clone。
-
-需要运行时才能决定的分支，可以在返回的 layer 里写 `.before(async (sandbox, context) => ...)`。这种回调每次都真实执行，它后面的准备步骤也不再沿用缓存。成功取得资源后，立即用 `context.onCleanup()` 登记释放。
-
-<Warning>
-  `sandbox` 必须返回 `sandboxLayer()`。返回 `dockerSandbox()`、`e2bSandbox()` 这类选择了镜像或 template 的 layer，会在加载定义时报错。Plugin 不能替换调用方选择的 Provider。
-</Warning>
-
-### 从 Git 仓库取 Plugin 源码
-
-Plugin 源码在一个能 clone 的仓库里时，用 `gitCheckout()`，`ref` 填完整的 commit ID。branch 或 tag 会移动，NiceEval 无法据此判断内容变没变，所以不接受：
-
-```ts
-import {
-  gitCheckout,
-  sandboxLayer,
-} from "niceeval/sandbox";
-
-const pluginSource = sandboxLayer().before(gitCheckout({
-  id: "memory-plugin-source",
-  repository: "https://github.com/acme/memory-plugin.git",
-  ref: "0123456789abcdef0123456789abcdef01234567",
-  to: ".agents/plugins/memory",
+import { writeText } from "niceeval/sandbox";
+
+export const memory = definePlugin(({ version }: { version: string }) => ({
+  name: "example.memory",
+  identity: { version },
+  agent: { skills: [{ kind: "local", path: "./skills/memory" }] },
+  sandbox: {
+    before: writeText({ id: "memory-mode", path: "/tmp/memory-mode", text: version }),
+  },
+  experiment: {
+    before: (ctx) => ctx.progress({ message: "Prepare memory service" }),
+    after: (ctx) => ctx.progress({ message: "Release memory service" }),
+  },
 }));
 ```
 
-源码在本地目录时用 `uploadDirectory()`，`source` 写成相对当前文件的 `new URL("...", import.meta.url)`。目录里的文件内容、权限和 symlink 变化都会被自动发现：改一个文件，只有上传这个目录的步骤和它后面的步骤会重新执行。
-
-## 第 2 步：挂到 Experiment、评估组或评估用例
-
-只用一两个 Plugin 时，直接传数组：
-
 ```ts
 export default defineExperiment({
-  agent: codexAgent(),
-  plugins: [memory({ model: "gpt-5.6-luna" })],
-  sandbox: dockerSandbox({
-    source: { type: "image", image: "niceeval/codex:0.144.1-r1" },
-  }),
+  adapter: codexAgent(),
+  plugins: [memory({ version: "1" })],
 });
 ```
 
-几个 Experiment 共用一组 Plugin、又各自再加几个时，用 `pluginStack()` 组合。`.use()` 追加一个 Plugin，`.concat()` 合并两组。每次调用都返回新值，原来那组不变，可以放心从同一个基础上分叉：
-
-```ts
-import { pluginStack } from "niceeval/plugin";
-
-const observability = pluginStack().use(telemetry());
-const withMemory = observability.use(memory({ model: "gpt-5.6-luna" }));
+`before` 与 `after` 接受一个元素或数组。共享一组条件时使用普通数组展开：`plugins: [...basePlugins, condition]`。
+同一 Attempt 的生效集合中，`name` 和 `key` 的组合必须唯一，包括跨 Experiment、Eval Group 与 Eval 的重复挂载。
 
-export default defineExperiment({
-  agent: codexAgent(),
-  plugins: withMemory,
-  sandbox: dockerSandbox({
-    source: { type: "image", image: "niceeval/codex:0.144.1-r1" },
-  }),
-});
-```
+## 选择执行范围
 
-类型检查会拦住挂错位置的 Plugin：只支持评估用例的 Plugin 不能放进 Experiment 的组合里，没有共同可挂位置的两组也不能合并。空的 `pluginStack()` 和不写 `plugins` 效果相同。
+| 字段 | 执行时机 | 允许挂载位置 |
+| --- | --- | --- |
+| `agent` | 合并进内建 Agent factory | Experiment |
+| `experiment` | 每个有 fresh Attempt 的 Run 一次 | Experiment |
+| `group` | 每条有 fresh Attempt 的 Group lane 一次 | Experiment、Eval Group |
+| `sandbox` | 每条 fresh Attempt，reset 之后 | Experiment、Eval Group、Eval |
+| `attempt` | 每条 fresh Attempt 一次 | Experiment、Eval Group、Eval |
 
-组合不会自动去重。同一个位置出现两个 `name` 和 `instanceKey` 都相同的 Plugin 时，运行会在创建 Sandbox 前报错。删掉重复的那个，或者给它不同的 `instanceKey`。
+全部沿用历史结果时，这些 Hook 与 Sandbox 创建都不执行。before 按作者、Plugin 声明顺序运行；after 按已激活顺序逆序运行。
+宿主 after 失败记录 warning，并继续其余收尾；Agent after 失败会使 Attempt 失败，但仍继续剩余 after 与 finalizer。
 
-## 宿主机上的准备每次跑几回
+回调需要 Group 时，声明 `requires: { evalGroup: true }`，即可直接读取 `ctx.evalGroup.id`。
+选中 Group 外的 Eval 会在创建资源前失败，包括全部沿用结果的情况。
 
-Plugin 可以在三个层级声明宿主机上的 `setup` / `teardown`：
+## 合并 Agent 扩展
 
-| 写在 | 运行次数 |
-| --- | --- |
-| `experiment(options)` | 每个这次确实要跑的 Experiment 一次 |
-| `group(options)` | 每个 Experiment 和评估组的组合一次 |
-| `eval(options)` | 每个确实要跑的 Attempt 一次 |
+`agent.skills` 与 `agent.mcpServers` 提供通用扩展；`agent.codex`、`agent.claudeCode` 与 `agent.bub` 提供对应工厂的原生配置。
+factory 配置在前，Plugin 按数组顺序追加。Skill 或 MCP 重名、原生插件冲突、多个 configFile 都会报错。
+Bub 不接受 MCP；自定义 Adapter 不接受 agent 扩展。声明专用子项时，必须包含当前选择的 Agent。
 
-每一层至少写 `setup` 或 `teardown` 之一，可以带 `identity`。多个 Plugin 的 `setup` 按挂载顺序运行，`teardown` 按相反顺序运行。整道题都沿用上次结果、不需要重跑时，这些回调不会运行。
+## 让条件变化触发重跑
 
-`sandbox(options)` 不是第四个层级。它只定义一次 Sandbox 准备步骤，NiceEval 把这些步骤放进 Plugin 所挂位置的 Sandbox 准备里。你不需要在 `.before()` 里再传一次 Plugin。
-
-## 修改 Plugin 后让旧结果失效
-
-Plugin 的行为变了，沿用上次的结果就不再可信。NiceEval 能看到一部分变化，另一部分要你告诉它：
-
-- 改了宿主机 `setup` / `teardown` 的行为时，把 `behaviorRevision` 加一。NiceEval 看不到函数体的变化。
-- 改了 Sandbox 里的内置准备步骤（命令、文件、commit）时，不用做任何事，这些变化会被自动发现。
-- 自定义的准备步骤只在 NiceEval 观察不到的协议变化时，才补一个 `cache.fingerprint`。
-
-改完后先用 `pnpm exec niceeval exp <experiment> --dry` 确认受影响的题会重跑。
-
-## 运行前检查 Plugin 加进了哪些步骤
-
-挂上 Plugin 后，先看它的准备步骤排在哪里，再花钱运行：
+`identity` 是条件版本。受管 Action 内容、Skill 内容与配置文件内容也参与身份；MCP headers 与 env 不参与。
+只改 Experiment 模块里的回调函数体不会改变 Plugin 身份；需要重跑时修改 `identity` 或使用 `--rerun all`。
+Eval 模块仍遵循源文件闭包规则。条件身份不会自动进入 `ctx.flags`，运行参数仍显式写在 flags 中。
 
 ```bash
 pnpm exec niceeval debug compare/codex memory/smoke
-pnpm exec niceeval debug compare/codex memory/smoke --json
+pnpm exec niceeval show --exp compare/codex
+pnpm exec niceeval show --exp compare/codex --json
 ```
 
-`debug` 把 Plugin 加入的步骤和 Experiment、评估组、评估用例、Agent 的步骤放进同一份计划。终端里每一步显示它来自哪里、执行序号、`changeFrequency`、依赖和能否沿用缓存；`--json` 给出相同的结构。
-
-Plugin 的步骤没出现在计划里时，先检查 `plugins` 是否挂在了你选中的 Experiment 或评估用例上。
+`debug` 展示展开步骤、实际 Action 顺序与 Plugin 来源。`show` 和 `view` 的 Experiment 信息列出 Plugin 的 name、key 与 identity。
 
 ## 接着看
 
-- [Sandbox · 按顺序准备 Sandbox](/zh/tutorials/sandbox-providers#按顺序准备-sandbox)——准备步骤、频率、缓存与收尾。
-- [评估组](/zh/tutorials/eval-groups)——评估组的准备步骤怎样进入同一顺序。
-- [运行前检查 Sandbox 计划](/zh/tutorials/debug-lifecycle-plan)——查看 Plugin 加入后的完整计划。
+- [Sandbox 准备](/zh/tutorials/sandbox-providers)
+- [评估组](/zh/tutorials/eval-groups)
+- [检查生命周期计划](/zh/tutorials/debug-lifecycle-plan)