niceeval 0.9.0 → 0.10.0

package/docs-site/zh/{how-to → tutorials}/publish-report.mdx

@@ -4,11 +4,11 @@ sidebarTitle: "CI 发布报告"
 description: "把经过 copySnapshots 大小预检的结果目录提交进仓库,CI 用一行 view --results 导出报告站;超大文件在 commit 前就会得到可执行错误。"
 ---
 
-`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、结果快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/how-to/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里，但不要直接提交本地事实根 `.niceeval/`：逐字符串截断能防一条失控输出膨胀，不能保证整个文件小于 Git host 的限制。先用 `copySnapshots` 生成经过 50 MiB 单文件预检的发布结果根，再提交这个目录。
+`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、结果快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/tutorials/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里，但不要直接提交本地事实根 `.niceeval/`：逐字符串截断能防一条失控输出膨胀，不能保证整个文件小于 Git host 的限制。先用 `copySnapshots` 生成经过 50 MiB 单文件预检的发布结果根，再提交这个目录。
 
 ## 生成可提交的结果目录
 
-新建 `scripts/publish-results.ts`（项目里 eval 和配置本来就是 TypeScript，脚本也用 `.ts`，由 `tsx` 直接运行）：
+新建 `scripts/publish-results.ts`（项目里评估用例和配置本来就是 TypeScript，脚本也用 `.ts`，由 `tsx` 直接运行）：
 
 ```javascript
 import { rm } from "node:fs/promises";
@@ -31,11 +31,17 @@ await copySnapshots(results.latest(), output, {
 npx niceeval view --results report-data --out site
 ```
 
+只发布一部分实验时,把收窄直接交给导出命令,页面和证据都只含收窄后的范围(见[查看结果 · 导出与静态托管](/zh/tutorials/viewing-results#导出与静态托管)):
+
+```bash
+npx niceeval view --results report-data --exp compare --out site
+```
+
 `view` 对零可读结果直接报错、非零退出,不会导出一张空报告——`report-data/` checkout 坏掉,或所有落盘与当前 niceeval 的 schemaVersion 不兼容被整批跳过时,构建失败,Vercel / GitHub Pages 保留上一次部署。错误逐条列出被跳过的快照目录与原因,schemaVersion 场景还给出能直接查看旧落盘的 `npx niceeval@<版本> view` 命令。
 
 ## 发布自定义报告
 
-不传 `--report` 时,发布出来的站点就是默认报告的三个页面(报告、Attempts、追踪)。想换成自己的页面,把 [`defineReport` 报告文件](/zh/how-to/custom-reports)传给 `--report` 就行——attempt 详情(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
+不传 `--report` 时,发布出来的站点就是默认报告的三个页面(报告、Attempts、追踪)。想换成自己的页面,把 [`defineReport` 报告文件](/zh/tutorials/custom-reports)传给 `--report` 就行——attempt 详情(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
 
 ```bash
 npx niceeval view --results report-data --report reports/exam.tsx --out site
@@ -133,8 +139,8 @@ jobs:
         uses: actions/deploy-pages@v4
 ```
 
-日常循环是:本地跑 eval，运行 `npx tsx scripts/publish-results.ts`，提交更新后的 `report-data/` 并 push。发布目录只保留每个实验的最新结果快照；要发布其它选择策略，在脚本里替换 `results.latest()`。本地 `.niceeval/` 可以保留完整历史和 diff，不需要为了 Git 限制削掉调试证据。
+日常循环是:本地跑评估用例，运行 `npx tsx scripts/publish-results.ts`，提交更新后的 `report-data/` 并 push。发布目录只保留每个实验的最新结果快照；要发布其它选择策略，在脚本里替换 `results.latest()`。本地 `.niceeval/` 可以保留完整历史和 diff，不需要为了 Git 限制削掉调试证据。
 
 ## 发布的是选中的证据
 
-整站导出会带上发布结果根里选中的 transcript、源码快照和 trace。新写入的超大 events / trace 字符串可能带结构化截断标记。`copySnapshots` 只做选择和整文件大小预检，不改写任何内容。发布的站点谁都能翻到 prompt 和工具输出，发布到公网前确认结果内容适合公开——NiceEval 在记录时就不把环境变量值和命令输出写进结果文件，transcript 里是 Agent 自己的输入输出和你的 eval 任务本身。
+整站导出会带上发布结果根里选中的 transcript、源码快照和 trace。新写入的超大 events / trace 字符串可能带结构化截断标记。`copySnapshots` 只做选择和整文件大小预检，不改写任何内容。发布的站点谁都能翻到 prompt 和工具输出，发布到公网前确认结果内容适合公开——NiceEval 在记录时就不把环境变量值和命令输出写进结果文件，transcript 里是 Agent 自己的输入输出和你的评估用例任务本身。

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

@@ -1,12 +1,12 @@
 ---
 title: "为你的 Agent 项目设置评估"
 sidebarTitle: "快速开始"
-description: "安装 NiceEval，写三个文件，10 分钟内对你自己的应用跑通第一条 eval。"
+description: "安装 NiceEval，写三个文件，10 分钟内对你自己的应用跑通第一条评估用例。"
 ---
 
-接入你自己的应用只需要三个文件：一个 **adapter**（怎么调你的应用）、一个 **experiment**（评谁、跑几次）、一条 **eval**（断言什么）。下面是完整的最短路径；写给 coding agent 的一键接入和场景示例在后面。
+接入应用需要三个文件：一个 **Adapter** 负责调用应用，一个 **Experiment** 固定被测对象和运行次数，一条**评估用例**定义断言。以下步骤提供完整的最短路径，并分别覆盖 Coding Agent 自动接入和人工接入。
 
-## 让 AI 帮你接入 (推荐)
+## 使用 Coding Agent 接入（推荐）
 <Steps>
   <Step title="安装">
     ```text
@@ -21,7 +21,7 @@ description: "安装 NiceEval，写三个文件，10 分钟内对你自己的应
   </Step>
   <Step title="查看结果">
     ```bash
-    pnpm exec niceeval show         # 终端摘要，适合直接交给 AI 阅读
+    pnpm exec niceeval show         # 终端摘要，适合 Coding Agent 读取
     pnpm exec niceeval view         # 网页查看器，适合人浏览证据
     ```
   </Step>
@@ -36,14 +36,14 @@ pnpm exec niceeval init
 ```
 
 ### Adapter
-Adapter 是连接 Agent 与 [NiceEval](https://niceeval.com/) 的中间层。有三种不同程序的接入方式，从无侵入式到部分修改你的 Agent 代码，来解锁更有用的评估功能。 见[Tier](/zh/explanation/tier)。
+Adapter 连接 Agent 与 [NiceEval](https://niceeval.com/)。三种接入等级从无侵入连接到修改 Agent 配置，分别提供不同的评估能力，见 [Tier](/zh/explanation/tier)。
 
 ```ts
-// agents/my-bot.ts
+// agents/my-agent.ts
 import { defineAgent } from "niceeval/adapter";
 
 export default defineAgent({
-  name: "my-bot",
+  name: "my-agent",
   async send(input, ctx) {
     // 示例地址：换成你自己 agent 的真实端点（HTTP、CLI、SDK 都行，只要 send 里能拿到回复文本）
     const r = await fetch("http://localhost:3000/chat", {
@@ -64,19 +64,19 @@ export default defineAgent({
 ### Experiment
 
 ```ts
-// experiments/my-bot.ts
+// experiments/my-agent.ts
 import { defineExperiment } from "niceeval";
-import myBot from "../agents/my-bot.ts";
+import myAgent from "../agents/my-agent.ts";
 
 export default defineExperiment({
-  description: "my-bot 基线",
+  description: "my-agent 基线",
   model: "gpt-4o",
-  agent: myBot,
+  agent: myAgent,
   runs: 1,
 });
 ```
 
-### Eval
+### 评估用例
 
 ```ts
 // evals/refund-policy.eval.ts
@@ -94,18 +94,18 @@ export default defineEval({
 ```
 
 ```bash
-pnpm exec niceeval exp my-bot   # 跑起来
+pnpm exec niceeval exp my-agent   # 跑起来
 pnpm exec niceeval show         # 在终端读结果；失败项会给出继续下钻的命令
 pnpm exec niceeval view         # 需要交互浏览时打开本地查看器
 ```
 
-到这里第一条 eval 已经跑通。
+到这里第一条评估用例已经跑通。
 
-这个最小 adapter 是**单轮**的——第二轮不会记得第一轮说了什么，因为还没告诉应用怎么接上历史。多轮会话和工具调用事件（解锁 `t.calledTool()`）、HITL、tracing 一样，都是之后给 adapter 加的可选增量：顺着[接入你的 Agent](/zh/how-to/connect-your-agent)逐层往下走即可，已写的 eval 不用改。
+这个最小 Adapter 只支持**单轮**调用，第二轮不会携带第一轮的历史。多轮会话、工具调用事件（供 `t.calledTool()` 使用）、HITL 和 tracing 都是后续可选能力。按[接入你的 Agent](/zh/tutorials/connect-your-agent)继续扩展时，已有评估用例不需要修改。
 
 ## 对照完整项目
 
-第一条 Eval 跑通后，再到 [Examples](/zh/examples) 按被测对象选择完整项目。那里提供可运行源码；通用操作步骤仍以 How-to Guides 为准。
+第一条评估用例跑通后，再到 [Examples](/zh/examples) 按被测对象选择完整项目。那里提供可运行源码；通用操作步骤在 Tutorials 的对应任务页中。
 
 ## 放进 CI
 
@@ -119,9 +119,9 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
       - run: npm ci
-      - run: npm exec niceeval exp my-bot
+      - run: npm exec niceeval exp my-agent
 ```
 
 <Tip>
-  接下来读 [编写 eval](/zh/how-to/authoring) 和 [评分指南](/zh/how-to/scoring-guide)，把示例替换成你的真实场景。
+  阅读 [编写评估用例](/zh/tutorials/authoring) 和 [评分指南](/zh/tutorials/scoring-guide)，再把示例替换成真实场景。
 </Tip>

package/docs-site/zh/{how-to → tutorials}/reporters.mdx

@@ -1,15 +1,15 @@
 ---
 title: "把结果上报到 Braintrust 与其它目的地"
 sidebarTitle: "Reporter 上报"
-description: "用内置 reporters 把 eval 结果送到 Braintrust 实验、JUnit XML 或自定义目的地。"
+description: "用内置 reporters 把评估用例结果送到 Braintrust 实验、JUnit XML 或自定义目的地。"
 ---
 
 [NiceEval](https://niceeval.com/) 自己跑、自己判分；Reporter 负责把完成结果送到其它目的地。运行中的 Human/Agent/CI 反馈由 `niceeval exp --output ...` 选择，不是用户配置的 Reporter；`.niceeval/` results artifacts 始终开启。其余 Reporter 从 `niceeval/reporters` 导入，按需挂载。
 
 挂载位置有两个：
 
-- `niceeval.config.ts` 的 `reporters`：观测整次运行的每个 eval。共享目的地（比如一个 Braintrust 实验）通常写在这里。
-- 单个 eval 的 `reporters`：实例只观测引用它的 eval。多个 eval 引用同一个实例时合并观测，结果落进同一个目的地；已经写在 config 里的实例在 eval 上再列一遍也不会重复上报。
+- `niceeval.config.ts` 的 `reporters`：观测整次运行的每个评估用例。共享目的地（比如一个 Braintrust 实验）通常写在这里。
+- 单个评估用例的 `reporters`：实例只观测引用它的评估用例。多个评估用例引用同一个实例时合并观测，结果落进同一个目的地；已经写在 config 里的实例在评估用例上再列一遍也不会重复上报。
 
 ## Braintrust
 
@@ -24,7 +24,7 @@ export default defineConfig({
 });
 ```
 
-只想上报部分 eval 时，挂在 eval 上：
+只想上报部分评估用例时，挂在评估用例上：
 
 ```ts evals/forecast.eval.ts
 import { defineEval } from "niceeval";
@@ -105,9 +105,9 @@ const notify: Reporter = {
 };
 ```
 
-- `onRunStart(evals, agent, shape)`：运行开始，收到本次实际要跑的 eval 列表和运行规模。
+- `onRunStart(evals, agent, shape)`：运行开始，收到本次实际要跑的评估用例列表和运行规模。
 - `onEvalComplete(result)`：每个 attempt 完成即时触发，回调串行化，不会交错。
 - `onRunComplete(summary)`：运行结束，收到聚合汇总。
 - `onEvent(event)`：更细粒度的事件流（`eval:start`、`run:budgetExceeded` 等）。
 
-用户在 config/eval 中挂载的 Reporter 默认是 best-effort：抛错会形成永久 diagnostic，但不会中断在飞 Attempt。CLI 显式要求的 `--json` / `--junit` 与默认 results artifacts 是 required 输出，写失败会让最终运行判红。只有目的地没被内置覆盖时才需要自定义——`.niceeval/` 的 artifacts 已经记录了完整结果，事后分析直接读它（见[查看结果](./viewing-results)）。
+用户在 config/评估用例中挂载的 Reporter 默认是 best-effort：抛错会形成永久 diagnostic，但不会中断在飞 Attempt。CLI 显式要求的 `--json` / `--junit` 与默认 results artifacts 是 required 输出，写失败会让最终运行判红。只有目的地没被内置覆盖时才需要自定义——`.niceeval/` 的 artifacts 已经记录了完整结果，事后分析直接读它（见[查看结果](./viewing-results)）。

package/docs-site/zh/{how-to → tutorials}/sandbox-agent.mdx

@@ -1,6 +1,6 @@
 ---
-title: "沙箱 Agent：评估 Claude Code、Codex 和 bub"
-sidebarTitle: "沙箱 Agent"
+title: "Sandbox Agent：评估 Claude Code、Codex 和 bub"
+sidebarTitle: "Sandbox Agent"
 description: "使用 NiceEval 内置 agents 或自定义 adapter，在 Docker 或云端 sandbox 中运行 coding-agent CLI。"
 ---
 
@@ -63,7 +63,7 @@ export default defineExperiment({
 });
 ```
 
-Claude Code 使用 `correctroads-default-team/niceeval-claude-code:v0.6.1`，Bub 使用 `correctroads-default-team/niceeval-bub:v0.6.1`。版本 tag 适合 CI；省略 tag 会跟随当前稳定构建。如何继续增加系统包、二进制或模型缓存，见 [沙箱 provider · 从官方基线继续构建以提速](/zh/how-to/sandbox-providers#从官方基线继续构建以提速)。
+Claude Code 使用 `correctroads-default-team/niceeval-claude-code:v0.6.1`，Bub 使用 `correctroads-default-team/niceeval-bub:v0.6.1`。版本 tag 适合 CI；省略 tag 会跟随当前稳定构建。添加系统包、二进制或模型缓存的步骤见 [Sandbox Provider · 从官方基线继续构建以提速](/zh/tutorials/sandbox-providers#从官方基线继续构建以提速)。
 
 内置 agent 从 `niceeval/adapter` 导出的是工厂函数。需要配置鉴权、代理、MCP 或 GitHub skill 时，把这些写进工厂参数；模型仍然写在 experiment 的 `model` 字段，sandbox provider 仍然写在 `sandbox` 字段：
 
@@ -104,7 +104,7 @@ export default defineExperiment({
 ```text
 createSandbox
   → sandbox spec 的 .setup() 钩子?    # 环境准备（按实验装东西）；没挂就跳过
-  → eval 的 setup?                   # 这条 eval 的任务夹具（如果定义了）
+  → eval 的 setup?                   # 这条 eval 的 Fixture（如果定义了）
   → adapter.setup?                   # 装 CLI / 写 agent 配置
   → test(t): uploadDirectory(...)     # 写入这条 eval 的起始文件
   → adapter.send(input, ctx)          # agent 在这一步改动的文件才进 diff
@@ -120,7 +120,7 @@ createSandbox
 
 `t.sandbox.diff` 与 `t.sandbox.fileChanged()` 只包含 **agent 在 `t.send()` 期间改动的文件**：NiceEval 在每次 `t.send()` 前后记录一次工作区状态，把中间的变化记在 agent 名下。你上传的起始文件、`t.send()` 之后写入的验证材料都不会混进来，所以 `fileChanged("src/app.ts")` 只在 agent 真的动过这个文件时通过。
 
-环境钩子（`.setup()` / `.teardown()`）挂在 experiment `sandbox` 字段的 spec 上，用来做"按实验变化的环境准备"——装某个实验专属的二进制、预热、跨 attempt 载入和回存状态。它写下的文件属于环境，不会被算进 agent 产出的 diff。写法和规则见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
+生命周期（`.setup()` / `.teardown()`）挂在 experiment `sandbox` 字段的 spec 上，用来做"按实验变化的环境准备"——装某个实验专属的二进制、预热、跨 attempt 载入和回存状态。它写下的文件属于环境，不会被算进 agent 产出的 diff。写法和规则见 [Sandbox provider · 生命周期](/zh/tutorials/sandbox-providers#生命周期)。
 
 ## 自定义 sandbox agent
 
@@ -172,7 +172,7 @@ export default defineSandboxAgent({
 
 ## `ctx.model` 与 `ctx.flags`
 
-experiment 声明的 model 和 flags 会出现在 adapter context 中。adapter 可以决定如何把它们转成 CLI 参数或 HTTP payload。
+Experiment 声明的 model 和 flags 会出现在 Adapter context 中。Adapter 可以把它们转换成 CLI 参数或 HTTP payload。
 
 ## 在 experiment 中使用自定义 agent
 

package/docs-site/zh/{how-to → tutorials}/sandbox-providers.mdx

@@ -1,7 +1,7 @@
 ---
-title: "Sandbox provider：Docker、Vercel 与第三方"
-sidebarTitle: "沙箱 provider"
-description: "NiceEval 在 Docker 或 Vercel sandbox 中运行 coding agents。了解如何选择 provider、配置权限，并通过 warm pools 改善性能。"
+title: "Sandbox"
+sidebarTitle: "Sandbox"
+description: "官方 Sandbox Docker、Vercel 或 E2B Provider。通过预制快照加速评估"
 ---
 
 Sandbox Provider 是创建和管理隔离运行环境的基础设施。[NiceEval](https://niceeval.com/) 把它们包装成同一个 `Sandbox` 接口，所以 Adapter 不需要知道当前用的是本地 Docker、Vercel micro-VM、E2B 还是第三方云服务。
@@ -21,9 +21,9 @@ Adapter 常用操作包括：
 | `runCommand(..., { cwd })` | 单条命令临时切换工作目录；相对路径按 `workdir` 解析 |
 | `stop()` | 销毁环境 |
 
-## 选择 provider
+## 选择 Sandbox 
 
-选择 provider 只能写在代码里——没有对应的 CLI flag，[NiceEval](https://niceeval.com/) 也不会自动探测 provider。在 experiment 里设置 `sandbox` 字段（或者在 `niceeval.config.ts` 里设置作为项目级兜底），三选一：
+在实验里设置 `sandbox` 字段
 
 ```ts
 // experiments/local.ts
@@ -49,7 +49,7 @@ export default defineExperiment({
 
 漏装时不会静默失败：NiceEval 在创建 sandbox 的那一刻报错并直接给出上面的安装命令，例如 `Docker sandbox requires 'dockerode'. Install it with: pnpm add dockerode @types/dockerode`。
 
-## 环境钩子
+## 生命周期
 
 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` 返回的 spec 上有两个链式方法：`.setup(fn)` 和 `.teardown(fn)`。它们处理只有运行时才知道的环境内容，例如按实验写小配置、检查预制工具是否可用、安装 hook，或在多次 Attempt 之间载入和回存状态。
 
@@ -73,16 +73,38 @@ export default defineExperiment({
 
 规则一览：
 
-- **签名**：钩子函数是 `(sandbox, ctx)`；`setup` 可以返回一个清理函数。这里的 `ctx` 是窄的 Sandbox Hook Context，只有 experiment 身份、取消信号和反馈方法，不带 Agent 会话或 telemetry。
+- **签名**：Hook 函数是 `(sandbox, ctx)`，不返回值。这里的 `ctx` 是窄的 Sandbox Hook Context，只有 experiment 身份、取消信号和反馈方法，不带 Agent 会话或 telemetry。
 - **不可变**：每次 `.setup()` / `.teardown()` 都返回一个新 spec，原对象不变，可以继续链。
-- **多个钩子**：多个 `.setup()` 按追加顺序执行；多个 `.teardown()` 按追加的逆序执行。
-- **执行时机**：`setup` 钩子在 sandbox 创建后、git 基线之前最先跑——它写下的文件会进基线，不会被算进 agent 产出的 diff；`teardown` 钩子在 Adapter 的 `teardown` 之后、sandbox 销毁之前最后跑——把状态回存到外部正好用这个时机。
-- **失败语义**：`setup` 钩子抛错，这次 Attempt 记为 `errored`（环境问题，不是 Agent 做错题）；`teardown` 钩子可以报告 diagnostic，默认不改变已经得到的判定。某个收尾动作是结果成立的必要条件时应抛错，由 runner 明确记录为致命错误。
-- **不带 sandbox 的 Agent**：`defineAgent` 构造的 Agent 没有 sandbox，`sandbox` 字段对它不生效，钩子自然不会跑。
+- **多个 Hook**：多个 `.setup()` 按追加顺序执行；多个 `.teardown()` 按追加的逆序执行（LIFO）；`.setup()` 链中途抛错时后续 `.setup()` 不再执行，`.teardown()` 链仍完整走完——半初始化的 Sandbox 同样要扫尾。
+- **执行时机**：`setup` Hook 在 sandbox 创建后、git 基线之前最先跑——它写下的文件会进基线，不会被算进 agent 产出的 diff；`teardown` Hook 在 Adapter 的 `teardown` 之后、sandbox 销毁之前最后跑——把状态回存到外部正好用这个时机。
+- **触发规则**：`teardown` 当且仅当同一 Sandbox 的 `setup` 时点已经走到才执行——`setup` 抛错不豁免，收尾代码要对可能未赋值的句柄做防御；`setup` 没跑到（Sandbox 没创建成功）则 `teardown` 同样跳过。
+- **失败语义**：`setup` Hook 抛错，这次 Attempt 记为 `errored`（环境问题，不是 Agent 做错题）；`teardown` Hook 可以报告 diagnostic，默认不改变已经得到的判定。某个收尾动作是结果成立的必要条件时应抛错，由 runner 明确记录为致命错误。
+- **不带 sandbox 的 Agent**：`defineAgent` 构造的 Agent 没有 sandbox，`sandbox` 字段对它不生效，Hook 自然不会跑。
 
-钩子里可以用 `ctx.experimentId`（路径推导的实验 id）当状态隔离的键，比如不同实验各自维护一份跨 attempt 的缓存。跨 attempt 状态的载入和回存是你自己在钩子里写的普通代码——[NiceEval](https://niceeval.com/) 不提供状态存储；要保证同一实验的 attempt 不并发读写同一份状态，在 experiment 上声明 `maxConcurrency: 1`。
+### 把 setup 的产物传给 teardown
 
-### 从环境钩子报告进度和问题
+`setup` 不返回值，`teardown` 要用 `setup` 建立的句柄（一个已打开的连接、一个临时文件路径）时不能存进普通模块变量——同一个 spec 被多个并发 Attempt 复用同一个模块，模块变量会被后来的 Attempt 互相覆写。以 `sandbox` 实例作键存取：每个 Attempt 有自己独立的 `sandbox`，是天然的 per-attempt 键：
+
+```ts
+import type { Sandbox } from "niceeval/sandbox";
+
+// 并发 Attempt 各有自己的 sandbox：句柄按 sandbox 键控，不用普通模块变量
+const forwarders = new WeakMap<Sandbox, { stop(): Promise<void> }>();
+
+const spec = e2bSandbox({ template: "niceeval-agents" })
+  .setup(async (sandbox, ctx) => {
+    forwarders.set(sandbox, await startLogForwarder(sandbox, { signal: ctx.signal }));
+  })
+  .teardown(async (sandbox) => {
+    await forwarders.get(sandbox)?.stop(); // setup 抛错也会进来：get 不到就跳过
+  });
+```
+
+「载入 / 回存」这类收尾不需要 setup → teardown 句柄：状态键是 `ctx.experimentId` 的外部 KV，普通代码即可，见下段。
+
+Hook 里可以用 `ctx.experimentId`（路径推导的实验 id）当状态隔离的键，比如不同实验各自维护一份跨 attempt 的缓存。跨 attempt 状态的载入和回存是你自己在 Hook 里写的普通代码——[NiceEval](https://niceeval.com/) 不提供状态存储；要保证同一实验的 attempt 不并发读写同一份状态，在 experiment 上声明 `maxConcurrency: 1`。
+
+### 从 Hook 中输出进度和问题
 
 长时间安装、预热和状态恢复可以调用 `ctx.progress(...)`。它只更新当前 Attempt 的短期状态，不会把每一步都写进结果。需要运行结束后仍能看到的问题使用 `ctx.diagnostic(...)`：
 
@@ -109,7 +131,7 @@ const sandbox = e2bSandbox({ template: "niceeval-agents" })
 
 `progress` 和 `diagnostic` 都不能指定全局阶段、颜色或输出流。Runner 知道当前回调属于 `sandbox.setup`，会把 Human 终端中的阶段显示为 sandbox setup。`diagnostic` 会随 Attempt 写入 `result.json`，之后可用 `niceeval show @<locator>` 回顾；它本身不会改变判定。环境无法继续时直接抛出异常。
 
-和另外两处 setup 的分工：Adapter 的 `setup` 管"怎么连被测 agent"（装 CLI、写鉴权配置）；eval 里 `test(t)` 开头的代码管"这道题需要哪些起始文件"；sandbox 的 `.setup()` 管"这次实验的环境里要多装什么"。三层各写各的，互相不知道对方的内容。MCP server、Skill、model 这些被测 agent 的配置仍然只从 Adapter 工厂参数进——环境钩子不做 Adapter 的事。
+三种 setup 各有职责。Adapter 的 `setup` 负责连接被测 Agent，例如安装 CLI 和写入鉴权配置；评估用例中 `test(t)` 开头的代码负责准备任务起始文件；Sandbox 的 `.setup()` 负责当前实验的额外环境准备。MCP server、Skill 和 model 等被测 Agent 配置仍然只从 Adapter 工厂参数传入。
 
 ## 预制环境与运行时 checkpoint
 
@@ -125,7 +147,7 @@ Docker image、Vercel 沙箱快照和 E2B template 的凭据、构建上下文
 
 ### 从官方基线继续构建以提速
 
-稳定、体积大、每个 Attempt 都相同的内容——系统包、Agent CLI、编译好的二进制、大模型缓存——应在跑 eval 之前烘焙进 provider 的可发布制品，让每个 Attempt 从预制环境启动、跳过运行时安装。三个内置 provider 都能从官方基线继续派生，不必从空白环境装 Agent；但它们的构建工具、凭据和发布语义不同，NiceEval 只统一**消费**产物 ID（`image` / `snapshotId` / `template`），不伪造跨 provider 的构建 DSL。
+稳定、体积大、每个 Attempt 都相同的内容——系统包、Agent CLI、编译好的二进制、大模型缓存——应在跑评估用例之前烘焙进 provider 的可发布制品，让每个 Attempt 从预制环境启动、跳过运行时安装。三个内置 provider 都能从官方基线继续派生，不必从空白环境装 Agent；但它们的构建工具、凭据和发布语义不同，NiceEval 只统一**消费**产物 ID（`image` / `snapshotId` / `template`），不伪造跨 provider 的构建 DSL。
 
 Adapter 与 Sandbox 不互相猜配置：Adapter 负责检查所需 CLI，Sandbox spec 负责选择 provider 和制品。Claude Code 与 Codex 缺少 CLI 时会回退到运行时安装，所以烘焙纯粹是提速；Bub 还会核对版本、OTel 插件和 Python 插件集合的安装指纹，不能仅凭 `command -v bub` 跳过安装，必须用预制环境。三个 provider 的构建都只在环境依赖变化时跑一次，产物换一个版本化名字，不要塞进每个 Attempt 的 `.setup()`。
 
@@ -242,11 +264,11 @@ import { dockerSandbox } from "niceeval/sandbox";
 sandbox: dockerSandbox({ image: "acme-codex-evals:2026-07-13" })
 ```
 
-Docker 沙箱默认以非 root 的 `node` 用户（UID 1000）跑命令，并把 `/usr/local/bin` 放进 PATH，所以 `npm install -g` 装的全局二进制天然可见；要装到别处的 Agent（如落在 `~/.local/bin`）记得让它进 PATH。本地快速迭代可以直接省略 `image` 用默认 `node:*-slim`，稳定 CI 引用不可变 tag。
+Docker Sandbox 默认以非 root 的 `node` 用户（UID 1000）跑命令，并把 `/usr/local/bin` 放进 PATH，所以 `npm install -g` 装的全局二进制天然可见；要装到别处的 Agent（如落在 `~/.local/bin`）记得让它进 PATH。本地快速迭代可以直接省略 `image` 用默认 `node:*-slim`，稳定 CI 引用不可变 tag。
 
 #### Vercel：从官方 runtime 拍快照
 
-Vercel 没有 E2B 式的 template registry，也没有 Dockerfile；沙箱快照是从一台跑起来的 microVM 拍出来的。用 Vercel SDK 从官方 runtime（`node24`）起一台沙箱，装好 Agent CLI，调 `.snapshot()` 拿到 `snap_...`，再把它交给 `vercelSandbox({ snapshotId })`：
+Vercel 没有 E2B 式的 template registry，也没有 Dockerfile；沙箱快照是从一台跑起来的 microVM 拍出来的。用 Vercel SDK 从官方 runtime（`node24`）起一台 Sandbox，装好 Agent CLI，调 `.snapshot()` 拿到 `snap_...`，再把它交给 `vercelSandbox({ snapshotId })`：
 
 ```ts title="scripts/build-vercel-snapshot.ts"
 import { Sandbox } from "@vercel/sandbox";
@@ -291,11 +313,11 @@ await restoreCheckpoint(nextSandbox, data);
 
 ## 瞬时错误重试
 
-内置 Provider 创建沙箱时，限流、`fetch failed`、连接重置、5xx、临时网络不可达这类瞬时失败会自动做指数退避重试；模板不存在、凭据缺失这类配置错误第一次就报错。重试用尽后该 Attempt 记为 errored。`defineSandbox` 自定义 Provider 的 `create` 是你自己的函数，NiceEval 不替它重试。
+内置 Provider 创建 Sandbox 时，限流、`fetch failed`、连接重置、5xx、临时网络不可达这类瞬时失败会自动做指数退避重试；模板不存在、凭据缺失这类配置错误第一次就报错。重试用尽后该 Attempt 记为 errored。`defineSandbox` 自定义 Provider 的 `create` 是你自己的函数，NiceEval 不替它重试。
 
 `readFile`、`downloadFile`、`uploadFile`、批量写入和目录上传会对 429、5xx、`fetch failed`、连接重置等瞬时传输错误自动做有限重试。文件不存在、权限错误、取消和 Sandbox terminated 不重试。
 
-`runCommand` 与 `runShell` 不自动重试。命令可能已经产生副作用，只有你能确认它可安全重复时，才在 hook 或 eval 中显式重试。
+`runCommand` 与 `runShell` 不自动重试。命令可能已经产生副作用，只有你能确认它可安全重复时，才在 hook 或评估用例中显式重试。
 
 ## Docker
 

package/docs-site/zh/{how-to → tutorials}/scoring-guide.mdx

@@ -1,10 +1,10 @@
 ---
-title: "评分指南: 断言、judge 和成本限制"
-sidebarTitle: "评分指南"
-description: "用 NiceEval 的五种评分机制评估任意 eval：值断言、作用域断言、LLM-as-judge、test-as-scoring 和效率检查。"
+title: "断言、judge 和成本限制"
+sidebarTitle: "断言"
+description: "值断言、作用域断言、LLM-as-judge、test-as-scoring 和效率检查。"
 ---
 
-好的 eval 应该尽量把“是否成功”拆成可解释的信号。[NiceEval](https://niceeval.com/) 允许你混合精确断言、语义 judge、事件流检查和真实测试。
+好的评估用例应该尽量把”是否成功”拆成可解释的信号。[NiceEval](https://niceeval.com/) 允许你混合精确断言、语义 judge、事件流检查和真实测试。
 
 ## 选择断言类型