niceeval 0.6.1 → 0.7.0

package/docs-site/zh/how-to/publish-report.mdx

@@ -0,0 +1,105 @@
+---
+title: "通过 CI 发布报告"
+sidebarTitle: "CI 发布报告"
+description: "把经过 copySnapshots 大小预检的结果目录提交进仓库,CI 用一行 view --run 导出报告站;超大文件在 commit 前就会得到可执行错误。"
+---
+
+`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、结果快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/how-to/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里，但不要直接提交本地事实根 `.niceeval/`：逐字符串截断能防一条失控输出膨胀，不能保证整个文件小于 Git host 的限制。先用 `copySnapshots` 生成经过 50 MiB 单文件预检的发布结果根，再提交这个目录。
+
+## 生成可提交的结果目录
+
+新建 `scripts/publish-results.ts`（项目里 eval 和配置本来就是 TypeScript，脚本也用 `.ts`，由 `tsx` 直接运行）：
+
+```javascript
+import { rm } from "node:fs/promises";
+import { copySnapshots, openResults } from "niceeval/results";
+
+const output = "report-data";
+const results = await openResults(".niceeval");
+
+await rm(output, { recursive: true, force: true });
+await copySnapshots(results.latest(), output, {
+  artifacts: ["sources", "events", "trace", "o11y", "agentSetup"],
+  redact: (text) => text.replaceAll(/sk-[A-Za-z0-9]+/g, "[redacted]"),
+});
+```
+
+`redact` 是必填项：给一个函数改写待发布文件里的自由文本，或者确认这批数据可以原文公开、显式传 `redact: false`。要发布的站点谁都能翻到 prompt 和工具输出，这个选择必须写在脚本里。
+
+运行 `npx tsx scripts/publish-results.ts`，然后提交 `report-data/`。`copySnapshots` 在创建目录前检查所有待发布文件；任何文件超过 50 MiB 时整体失败并列出路径、大小和处理建议，不会留下半份目录。`diff` 缺省不发布；需要 diff 时显式加进 `artifacts`，它也受同一个预算约束。历史版本留下的超大 events / trace 不会被悄悄改写，预检会要求你排除这类证据或用当前版本重跑。
+
+## 构建命令就是导出命令
+
+```bash
+npx niceeval view --run report-data --out site
+```
+
+`view` 对零可读结果直接报错、非零退出,不会导出一张空报告——`report-data/` checkout 坏掉,或所有落盘与当前 niceeval 的 schemaVersion 不兼容被整批跳过时,构建失败,Vercel / GitHub Pages 保留上一次部署。错误逐条列出被跳过的快照目录与原因,schemaVersion 场景还给出能直接查看旧落盘的 `npx niceeval@<版本> view` 命令。
+
+## 发布自定义报告
+
+不传 `--report` 时,发布出来的首页是默认报告。想让首页换成自己的报告,把 [`defineReport` 报告文件](/zh/how-to/custom-reports)传给 `--report` 就行——attempt 证据页(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
+
+```bash
+npx niceeval view --run report-data --report reports/exam.tsx --out site
+```
+
+报告文件和 `report-data/` 一样提交在仓库里,改完版面 push,线上就跟着更新。用下面的 `vercel.json` / workflow 时,把构建命令换成这一行即可,其余配置不用动。
+
+## 接托管平台
+
+**Vercel**:仓库根放一个 `vercel.json`,导入项目后 push 即部署。
+
+```json
+{
+  "installCommand": "pnpm install --frozen-lockfile",
+  "buildCommand": "npx niceeval view --run report-data --out site",
+  "outputDirectory": "site"
+}
+```
+
+**GitHub Pages**:仓库 Settings → Pages 把 Source 设为 GitHub Actions,再加 workflow:
+
+```yaml
+# .github/workflows/report.yml
+name: report
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: npx niceeval view --run report-data --out site
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+日常循环是:本地跑 eval，运行 `npx tsx scripts/publish-results.ts`，提交更新后的 `report-data/` 并 push。发布目录只保留每个实验的最新结果快照；要发布其它选择策略，在脚本里替换 `results.latest()`。本地 `.niceeval/` 可以保留完整历史和 diff，不需要为了 Git 限制削掉调试证据。
+
+## 发布的是选中的证据
+
+整站导出会带上发布结果根里选中的 transcript、源码快照和 trace。新写入的超大 events / trace 字符串可能带结构化截断标记。`copySnapshots` 只在你给了消毒函数时改写自由文本（`redact` 是必填项，见上），其余只做选择和整文件大小预检；传 `redact: false` 的目录再导出时还要加 `--allow-sensitive-artifacts` 确认一次。发布到公网前确认结果里没有密钥或敏感数据。

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

@@ -4,7 +4,7 @@ sidebarTitle: "Reporter 上报"
 description: "用内置 reporters 把 eval 结果送到 Braintrust 实验、JUnit XML 或自定义目的地。"
 ---
 
-[NiceEval](https://niceeval.com/) 自己跑、自己判分；reporter 负责把结果送出去。控制台输出和 `.niceeval/` artifacts 本身就是内置 reporter，始终开启。其余 reporter 从 `niceeval/reporters` 导入，按需挂载。
+[NiceEval](https://niceeval.com/) 自己跑、自己判分；Reporter 负责把完成结果送到其它目的地。运行中的 Human/Agent/CI 反馈由 `niceeval exp --output ...` 选择，不是用户配置的 Reporter；`.niceeval/` results artifacts 始终开启。其余 Reporter 从 `niceeval/reporters` 导入，按需挂载。
 
 挂载位置有两个：
 
@@ -110,4 +110,4 @@ const notify: Reporter = {
 - `onRunComplete(summary)`：运行结束，收到聚合汇总。
 - `onEvent(event)`：更细粒度的事件流（`eval:start`、`run:budgetExceeded` 等）。
 
-reporter 抛错只会打一条诊断信息，不会让运行中断。只有目的地没被内置覆盖时才需要自定义——`.niceeval/` 的 artifacts 已经记录了全部结果，事后分析直接读它（见[查看结果](./viewing-results)）。
+用户在 config/eval 中挂载的 Reporter 默认是 best-effort：抛错会形成永久 diagnostic，但不会中断在飞 Attempt。CLI 显式要求的 `--json` / `--junit` 与默认 results artifacts 是 required 输出，写失败会让最终运行判红。只有目的地没被内置覆盖时才需要自定义——`.niceeval/` 的 artifacts 已经记录了完整结果，事后分析直接读它（见[查看结果](./viewing-results)）。

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

@@ -41,14 +41,31 @@ export default defineExperiment({
 export ANTHROPIC_API_KEY=sk-ant-...
 npx niceeval exp local fixtures/button
 
-npx niceeval exp local fixtures/button --runs 10 --early-exit
+npx niceeval exp local fixtures/button --runs 10
 ```
 
 <Note>
-  没有对应的 CLI flag——后端选择完全写在代码里。如果 experiment 和 `niceeval.config.ts` 都没设置 `sandbox`，[NiceEval](https://niceeval.com/) 在创建 sandbox 时会直接报错，不会自动探测。
+  没有对应的 CLI flag——provider 选择完全写在代码里。如果 experiment 和 `niceeval.config.ts` 都没设置 `sandbox`，[NiceEval](https://niceeval.com/) 在创建 sandbox 时会直接报错，不会自动探测。
 </Note>
 
-内置 agent 从 `niceeval/adapter` 导出的是工厂函数。需要配置鉴权、代理、MCP 或 GitHub skill 时，把这些写进工厂参数；模型仍然写在 experiment 的 `model` 字段，sandbox 后端仍然写在 `sandbox` 字段：
+云端跑 coding agent 时，可以直接使用 NiceEval 已发布的 E2B 公共模板，避免每个 Attempt 安装 CLI：
+
+```ts
+import { codexAgent } from "niceeval/adapter";
+import { e2bSandbox } from "niceeval/sandbox";
+
+export default defineExperiment({
+  agent: codexAgent(),
+  model: "gpt-5.4",
+  sandbox: e2bSandbox({
+    template: "correctroads-default-team/niceeval-codex:v0.6.1",
+  }),
+});
+```
+
+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#从官方基线继续构建以提速)。
+
+内置 agent 从 `niceeval/adapter` 导出的是工厂函数。需要配置鉴权、代理、MCP 或 GitHub skill 时，把这些写进工厂参数；模型仍然写在 experiment 的 `model` 字段，sandbox provider 仍然写在 `sandbox` 字段：
 
 ```ts
 import { defineExperiment } from "niceeval";
@@ -87,13 +104,13 @@ export default defineExperiment({
 ```text
 createSandbox
   → sandbox spec 的 .setup() 钩子?    # 环境准备（按实验装东西）；没挂就跳过
-  → git init && git commit
   → eval 的 setup?                   # 这条 eval 的任务夹具（如果定义了）
   → adapter.setup?                   # 装 CLI / 写 agent 配置
   → test(t): uploadDirectory(...)     # 写入这条 eval 的起始文件
-  → adapter.send(input, ctx)
+  → adapter.send(input, ctx)          # agent 在这一步改动的文件才进 diff
   → test(t): runCommand(...)          # 手工运行验证命令
-  → collectGeneratedFiles()           # git diff HEAD
+  → 汇总 agent 改动的文件              # 供 t.sandbox.diff / fileChanged 使用
+  → 评分与判定
   → adapter.teardown?                 # agent 收尾
   → sandbox spec 的 .teardown() 钩子?  # 环境收尾（如回存状态），销毁前最后跑
   → sandbox.stop()
@@ -101,7 +118,9 @@ createSandbox
 
 起始文件和验证命令都写在 `test(t)` 中。agent 执行阶段只能看到你已经写进 sandbox 的文件。
 
-环境钩子（`.setup()` / `.teardown()`）挂在 experiment `sandbox` 字段的 spec 上，用来做"按实验变化的环境准备"——装某个实验专属的二进制、预热、跨 attempt 载入和回存状态。它排在 git 基线之前，所以写下的文件不会被算进 agent 产出的 diff。写法和规则见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+`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#环境钩子)。
 
 ## 自定义 sandbox agent
 
@@ -110,9 +129,21 @@ import { defineSandboxAgent } from "niceeval/adapter";
 
 export default defineSandboxAgent({
   name: "my-agent",
+  async setup(sandbox, ctx) {
+    ctx.progress({ message: "检查 my-agent 安装" });
+    await sandbox.runCommand("npm", ["install", "-g", "my-agent"]);
+  },
   async send(input, ctx) {
+    ctx.progress({ message: "运行 my-agent CLI" });
     await ctx.sandbox.runCommand("my-agent", ["run", input.text, "--json-out", "agent-events.json"]);
     const transcript = await ctx.sandbox.readFile("agent-events.json");
+    if (transcript.trim() === "") {
+      ctx.diagnostic({
+        code: "empty-transcript",
+        level: "warning",
+        message: "my-agent 没有写出 transcript，工具断言可能缺少证据",
+      });
+    }
     return {
       status: "completed",
       events: parseTranscript(transcript),
@@ -121,6 +152,24 @@ export default defineSandboxAgent({
 });
 ```
 
+`setup`、每次 `send` 和 `teardown` 都拿到各自作用域的反馈方法：
+
+- `ctx.progress({ message, current?, total? })` 更新当前短期状态，适合安装 CLI、运行 Turn、读取 transcript；不要逐 token 或逐 JSONL frame 调用。
+- `ctx.diagnostic({ code, level, message, data?, dedupeKey? })` 保存协议退化、transcript 缺失和清理问题。它会进入终端永久事件和 `result.json`。
+- 无法继续运行时抛出异常，runner 会把 Attempt 标为 `errored`，并保存发生阶段、错误码、message、cause 和 stack。
+
+不要从 Adapter 直接调用 `console.log/error` 或写 `process.stdout/stderr`。它们会打散 Human dashboard，也会破坏 CI 日志顺序。
+
+运行中看到 Sandbox 或 Adapter 错误时，终端会给出 Attempt locator：
+
+```text
+✗ @12h8m4k1 fixtures/button [local] errored · agent setup
+    agent-install-failed: npm install my-agent exited with code 1
+    Inspect: niceeval show @12h8m4k1
+```
+
+运行 `niceeval show @12h8m4k1` 可查看结构化错误、diagnostics 和已完成的生命周期阶段；`--timing` 给有界诊断时间树（排队、Sandbox 启动、setup/teardown hook 里的 shell、Agent CLI 安装与启动命令、每轮 send、可关联的 OTel model/tool、收尾），可直接看出错误或超时发生在哪一层、之前的时间花在哪里。树超过 80 个细节节点时会保留失败、慢点和首尾样本并提示省略数量；需要逐节点审计时使用 `--timing=full`。`--execution` 则以事件为骨架查看 agent 做了什么，有 OTel 时只把时间贴到能唯一关联的事件旁。Sandbox 创建失败可能发生在 telemetry 建立前，所以错误回顾不依赖 trace。
+
 ## `ctx.model` 与 `ctx.flags`
 
 experiment 声明的 model 和 flags 会出现在 adapter context 中。adapter 可以决定如何把它们转成 CLI 参数或 HTTP payload。

package/docs-site/zh/how-to/sandbox-providers.mdx

@@ -0,0 +1,350 @@
+---
+title: "Sandbox provider：Docker、Vercel 与第三方"
+sidebarTitle: "沙箱 provider"
+description: "NiceEval 在 Docker 或 Vercel sandbox 中运行 coding agents。了解如何选择 provider、配置权限，并通过 warm pools 改善性能。"
+---
+
+Sandbox Provider 是创建和管理隔离运行环境的基础设施。[NiceEval](https://niceeval.com/) 把它们包装成同一个 `Sandbox` 接口，所以 Adapter 不需要知道当前用的是本地 Docker、Vercel micro-VM、E2B 还是第三方云服务。
+
+## `Sandbox` 接口
+
+Adapter 常用操作包括：
+
+| 方法 | 用途 |
+|---|---|
+| `runCommand(cmd, args)` | 运行命令 |
+| `runShell(script)` | 运行 shell 脚本 |
+| `readFile(path)` | 读取文件 |
+| `writeFiles(files)` | 写入一组文件 |
+| `uploadFiles(files)` | 上传 workspace 或测试文件 |
+| `workdir` | provider 真实工作目录；省略的 `cwd` / `targetDir` 都解析到这里 |
+| `runCommand(..., { cwd })` | 单条命令临时切换工作目录；相对路径按 `workdir` 解析 |
+| `stop()` | 销毁环境 |
+
+## 选择 provider
+
+选择 provider 只能写在代码里——没有对应的 CLI flag，[NiceEval](https://niceeval.com/) 也不会自动探测 provider。在 experiment 里设置 `sandbox` 字段（或者在 `niceeval.config.ts` 里设置作为项目级兜底），三选一：
+
+```ts
+// experiments/local.ts
+import { defineExperiment } from "niceeval";
+import { dockerSandbox } from "niceeval/sandbox";
+
+export default defineExperiment({
+  agent: myCodingAgent,
+  model: "claude-sonnet-4-6",
+  sandbox: dockerSandbox(), // 或 vercelSandbox() / e2bSandbox()
+});
+```
+
+如果 experiment 和 `niceeval.config.ts` 都没有设置 `sandbox`，[NiceEval](https://niceeval.com/) 在创建 sandbox 时会直接报错，而不会猜一个 provider。
+
+三个内置 provider 的 SDK 不随 NiceEval 一起安装——用哪个就装哪个，避免把用不到的依赖（以及它们的原生构建脚本）带进你的项目：
+
+| provider | 安装命令 |
+|---|---|
+| `dockerSandbox()` | `pnpm add dockerode @types/dockerode` |
+| `vercelSandbox()` | `pnpm add @vercel/sandbox` |
+| `e2bSandbox()` | `pnpm add e2b` |
+
+漏装时不会静默失败：NiceEval 在创建 sandbox 的那一刻报错并直接给出上面的安装命令，例如 `Docker sandbox requires 'dockerode'. Install it with: pnpm add dockerode @types/dockerode`。
+
+## 环境钩子
+
+`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` 返回的 spec 上有两个链式方法：`.setup(fn)` 和 `.teardown(fn)`。它们处理只有运行时才知道的环境内容，例如按实验写小配置、检查预制工具是否可用、安装 hook，或在多次 Attempt 之间载入和回存状态。
+
+共享 helper 需要显式标注回调类型时，从公开入口导入，不要从某个 provider 的 spec 反推：
+
+```ts
+import type { SandboxHook, SandboxHookContext } from "niceeval/sandbox";
+```
+
+稳定且体积大的依赖不要在这里重复安装。系统包、Agent CLI、编译好的二进制和大模型缓存应该先做进 Docker image、Vercel 沙箱快照或 E2B template。每个 Attempt 从预制环境启动，`.setup()` 只做薄薄的一层动态配置和 fail-fast 检查。
+
+```ts
+export default defineExperiment({
+  agent: codexAgent({ mcpServers: [mempalMcp] }),
+  sandbox: e2bSandbox({ template: "fasteval-agents-mempal" }) // 已包含二进制和模型缓存
+    .setup(mempalSetup("codex"))        // 预检、写 hook、载入状态
+    .teardown(mempalTeardown("codex")), // 回存状态
+  maxConcurrency: 1,                    // 载入和回存之间不能并发，声明串行
+});
+```
+
+规则一览：
+
+- **签名**：钩子函数是 `(sandbox, ctx)`；`setup` 可以返回一个清理函数。这里的 `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` 字段对它不生效，钩子自然不会跑。
+
+钩子里可以用 `ctx.experimentId`（路径推导的实验 id）当状态隔离的键，比如不同实验各自维护一份跨 attempt 的缓存。跨 attempt 状态的载入和回存是你自己在钩子里写的普通代码——[NiceEval](https://niceeval.com/) 不提供状态存储；要保证同一实验的 attempt 不并发读写同一份状态，在 experiment 上声明 `maxConcurrency: 1`。
+
+### 从环境钩子报告进度和问题
+
+长时间安装、预热和状态恢复可以调用 `ctx.progress(...)`。它只更新当前 Attempt 的短期状态，不会把每一步都写进结果。需要运行结束后仍能看到的问题使用 `ctx.diagnostic(...)`：
+
+```ts
+const sandbox = e2bSandbox({ template: "niceeval-agents" })
+  .setup(async (sandbox, ctx) => {
+    ctx.progress({ message: "安装 memory helper", current: 1, total: 2 });
+    await sandbox.runCommand("npm", ["install", "-g", "memory-helper"]);
+
+    ctx.progress({ message: "预热 memory index", current: 2, total: 2 });
+    try {
+      await warmIndex(sandbox);
+    } catch (error) {
+      ctx.diagnostic({
+        code: "memory-warmup-degraded",
+        level: "warning",
+        message: "预热失败，本次使用冷索引继续运行",
+        data: { reason: String(error) },
+        dedupeKey: "memory-warmup-degraded",
+      });
+    }
+  });
+```
+
+`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 的事。
+
+## 预制环境与运行时 checkpoint
+
+NiceEval 用 typed spec 统一引用预制环境，但不提供一个假的通用构建命令：
+
+```ts
+dockerSandbox({ image: "my-evals:node24" })
+vercelSandbox({ snapshotId: "snap_abc123" })
+e2bSandbox({ template: "my-evals" })
+```
+
+Docker image、Vercel 沙箱快照和 E2B template 的凭据、构建上下文、发布和过期方式不同。项目应使用 provider 的官方工具维护构建脚本，把最终 ID 或名字放进 experiment。适合预制的判断很简单：如果所有 Attempt 都要下载或安装同一份内容，而且它稳定、昂贵或体积大，就把它移到预制环境。
+
+### 从官方基线继续构建以提速
+
+稳定、体积大、每个 Attempt 都相同的内容——系统包、Agent CLI、编译好的二进制、大模型缓存——应在跑 eval 之前烘焙进 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()`。
+
+#### E2B：从官方与公共模板派生
+
+E2B 已提供 Claude Code 的 `claude` template 和 Codex 的 `codex` template。NiceEval 提供一个 E2B 专属的薄封装，让你从这两个官方起点继续链原生 E2B API。E2B 暂无 Bub 官方 template，因此 Bub 分支使用 NiceEval 固定到不可变 commit 的安装配方：
+
+NiceEval 同时发布了三份任何 E2B Team 都能引用的公共模板。完整 namespace 与经过验证的 release
+tag 由 NiceEval 自己维护，下游直接取完整引用：
+
+```ts
+import {
+  NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE,
+  NICEEVAL_CODEX_E2B_TEMPLATE,
+  NICEEVAL_BUB_E2B_TEMPLATE,
+} from "niceeval/sandbox/e2b-template";
+
+e2bSandbox({ template: NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE })
+e2bSandbox({ template: NICEEVAL_CODEX_E2B_TEMPLATE })
+e2bSandbox({ template: NICEEVAL_BUB_E2B_TEMPLATE })
+```
+
+这些基线已实际启动验证：Claude Code `2.1.207`、Codex `0.144.1`，Bub 安装指纹 `83770925b77a`。每个值都是带 tag 的完整跨 Team 引用；业务仓库不应复制这些字符串，也不应维护或读取另一份 NiceEval release 常量。派生模板需要记录 base 身份时，直接使用所选的完整 template ref。
+
+```ts title="scripts/build-e2b-template.ts"
+import { Template } from "e2b";
+import { e2bCodingAgentTemplate } from "niceeval/sandbox/e2b-template";
+
+const template = e2bCodingAgentTemplate("codex")
+  .aptInstall(["ripgrep", "jq"])
+  .runCmd("corepack enable && pnpm --version")
+  .copy("fixtures/toolchain.lock", "/opt/evals/toolchain.lock");
+
+await Template.build(template, "acme-codex-evals:2026-07-13", {
+  cpuCount: 2,
+  memoryMB: 4096,
+});
+```
+
+```bash
+e2b auth login
+pnpm tsx scripts/build-e2b-template.ts
+```
+
+然后在 Experiment 里只引用构建结果：
+
+```ts
+import { e2bSandbox } from "niceeval/sandbox";
+
+sandbox: e2bSandbox({ template: "acme-codex-evals:2026-07-13" })
+```
+
+也可以直接从 NiceEval 公共模板继续派生，只支付项目依赖的构建成本：
+
+```ts
+import { NICEEVAL_CODEX_E2B_TEMPLATE } from "niceeval/sandbox/e2b-template";
+
+const template = Template()
+  .fromTemplate(NICEEVAL_CODEX_E2B_TEMPLATE)
+  .aptInstall(["ripgrep", "jq"])
+  .runCmd("corepack enable");
+```
+
+`e2bCodingAgentTemplate("claude-code" | "codex" | "bub")` 返回原生 `TemplateBuilder`，不是 NiceEval 私有构建 DSL。你可以继续使用 `.aptInstall()`、`.runCmd()`、`.copy()` 等 E2B 能力。构建自己的 alias 会把官方起点和项目依赖冻结在同一个可复现制品里；依赖变更时重建并换一个版本化 alias。
+
+若 Bub Adapter 配了 `pythonPlugins`，构建模板时把同一组 package 传给 factory，插件集合才会进入兼容性指纹并真正命中预装环境：
+
+```ts
+e2bCodingAgentTemplate("bub", {
+  bubPythonPackages: ["bub-plugin-memory==1.3.0"],
+})
+```
+
+#### Docker：使用 NiceEval 维护的镜像，或从官方 node 基础镜像派生
+
+要直接运行 NiceEval 内置的 `claude-code`、`codex` 或 `bub` Adapter，可以使用对应的公开镜像：
+[`niceeval/claude-code`](https://hub.docker.com/r/niceeval/claude-code)、
+[`niceeval/codex`](https://hub.docker.com/r/niceeval/codex) 或
+[`niceeval/bub`](https://hub.docker.com/r/niceeval/bub)。每个镜像只包含自己的 Agent CLI，并为
+`linux/amd64` 和 `linux/arm64` 发布 manifest；每个 NiceEval release 都有同名 tag。稳定 CI 要固定
+release tag 或 digest，不要依赖会移动的 `latest`：
+
+```ts
+import { dockerSandbox } from "niceeval/sandbox";
+
+sandbox: dockerSandbox({ image: "niceeval/codex:v0.6.1" })
+```
+
+这个镜像是 NiceEval 维护的公开镜像，不是 Docker 的 `library/*` Official Image。它随 NiceEval
+release 更新，里面的 Agent CLI 版本由该 release 的构建配方固定。
+
+如果只需要一个 Agent，或还要加入项目专有依赖，写 Dockerfile 从 Docker 的官方基线
+`node:24-slim` 派生。省略 `image` 时，NiceEval 也会按 runtime 使用该默认镜像：
+
+```dockerfile title="Dockerfile"
+FROM node:24-slim
+# slim 镜像不带 ca-certificates / git，Agent 和 npm 都要用
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends ca-certificates git \
+  && rm -rf /var/lib/apt/lists/*
+# npm 全局装进 /usr/local/bin，正好落在沙箱注入的 PATH 上
+RUN npm install -g @openai/codex@0.144.1
+```
+
+```bash
+docker build -t acme-codex-evals:2026-07-13 .
+```
+
+然后在 Experiment 里只引用构建结果：
+
+```ts
+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。
+
+#### Vercel：从官方 runtime 拍快照
+
+Vercel 没有 E2B 式的 template registry，也没有 Dockerfile；沙箱快照是从一台跑起来的 microVM 拍出来的。用 Vercel SDK 从官方 runtime（`node24`）起一台沙箱，装好 Agent CLI，调 `.snapshot()` 拿到 `snap_...`，再把它交给 `vercelSandbox({ snapshotId })`：
+
+```ts title="scripts/build-vercel-snapshot.ts"
+import { Sandbox } from "@vercel/sandbox";
+
+const sandbox = await Sandbox.create({ runtime: "node24" }); // 官方 runtime 起 microVM
+await sandbox.runCommand({
+  cmd: "npm",
+  args: ["install", "-g", "@openai/codex@0.144.1"],
+  sudo: true, // 全局装进 /usr/local/bin，落在沙箱 PATH 上
+});
+const { snapshotId } = await sandbox.snapshot();
+console.log(snapshotId); // snap_...
+await sandbox.stop();
+```
+
+```bash
+pnpm tsx scripts/build-vercel-snapshot.ts
+```
+
+然后在 Experiment 里引用打印出的 ID：
+
+```ts
+import { vercelSandbox } from "niceeval/sandbox";
+
+sandbox: vercelSandbox({ snapshotId: "snap_xxx" })
+```
+
+Vercel snapshot 不支持 E2B 式公共发布：snapshot ID 受创建它的 Team/Project 权限控制，同项目成员可以复用，外部用户必须在自己的 Vercel Project 重拍一份。NiceEval 维护项目当前验证过的永不过期 snapshot 是 `snap_7sIjfs71xfmVly0WEUTGhTBoMGeL`，但它不是跨账号公共 ID。
+
+### 运行时 checkpoint
+
+`createCheckpoint()` / `restoreCheckpoint()` 是另一件事。它们把指定的 Linux 路径打包成 `Buffer`，可以在已创建的 Sandbox 之间恢复文件系统片段：
+
+```ts
+import { createCheckpoint, restoreCheckpoint } from "niceeval/sandbox";
+
+const data = await createCheckpoint(sandbox, ["/home/user/.cache/tool"]);
+await restoreCheckpoint(nextSandbox, data);
+```
+
+这适合运行时缓存，不会创建可发布的 image/template/snapshot，也不管理共享、版本和过期。归档或恢复失败会直接抛错。
+
+## 瞬时错误重试
+
+内置 Provider 创建沙箱时，限流、`fetch failed`、连接重置、5xx、临时网络不可达这类瞬时失败会自动做指数退避重试；模板不存在、凭据缺失这类配置错误第一次就报错。重试用尽后该 Attempt 记为 errored。`defineSandbox` 自定义 Provider 的 `create` 是你自己的函数，NiceEval 不替它重试。
+
+`readFile`、`downloadFile`、`uploadFile`、批量写入和目录上传会对 429、5xx、`fetch failed`、连接重置等瞬时传输错误自动做有限重试。文件不存在、权限错误、取消和 Sandbox terminated 不重试。
+
+`runCommand` 与 `runShell` 不自动重试。命令可能已经产生副作用，只有你能确认它可安全重复时，才在 hook 或 eval 中显式重试。
+
+## Docker
+
+Docker 适合本地开发和标准 CI。优点是简单、可控、无云端依赖；缺点是机器资源有限，冷启动和安装依赖可能较慢。
+
+## Vercel Sandbox
+
+Vercel Sandbox 适合需要云端隔离、更多资源或更稳定环境的任务。需要相应 token 或 OIDC 配置。
+
+## 自定义 Provider
+
+用 `defineSandbox` 接入其它服务。`create` 的 `feedback` 已绑定到 `sandbox.create` 阶段，可以报告分配实例、拉镜像或恢复沙箱快照的状态：
+
+```ts
+import { defineSandbox } from "niceeval/sandbox";
+
+export default defineSandbox({
+  name: "modal",
+  recommendedConcurrency: 8,
+  async create({ timeout, runtime, feedback }) {
+    feedback.progress({ message: "分配 Modal Sandbox" });
+    const instance = await allocateModal({ timeout, runtime });
+
+    if (instance.usedFallbackRegion) {
+      feedback.diagnostic({
+        code: "modal-fallback-region",
+        level: "warning",
+        message: `主区域不可用，使用 ${instance.region}`,
+        data: { region: instance.region },
+      });
+    }
+
+    return new ModalSandbox(instance);
+  },
+});
+```
+
+返回值实现 `Sandbox` 接口即可。Provider SDK 的原始日志不要直接写宿主进程的 `stdout` / `stderr`；短期状态走 `feedback.progress`，需要保留的问题走 `feedback.diagnostic`，无法创建环境时抛错。这样 Human dashboard 不会被日志打散，CI 也能保持单一有序输出。
+
+## 权限和 root
+
+不同 provider 对 root 权限、网络、文件系统和进程生命周期的约束不同。编写 fixture 时尽量避免依赖宿主机环境，把依赖写进 `package.json` 或 fixture setup。
+
+## 性能建议
+
+- 把稳定重依赖做进 image/template/snapshot，不在每个 Attempt 的 `.setup()` 重装。
+- 减少 fixture 依赖体积。
+- 对动态内容使用小而明确的缓存或预检。
+- 控制 `maxConcurrency`（experiment 字段或 `--max-concurrency`），避免本地 Docker 资源耗尽。
+- 把慢测试拆成必要的 gate 和可选的 soft 检查。
+
+Warm pools 和复用属于 runner / scheduler 层面的能力，详见 [Runner](/zh/explanation/runner)。

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

@@ -10,7 +10,7 @@ description: "用 NiceEval 的五种评分机制评估任意 eval：值断言、
 
 | 目标 | 推荐机制 |
 |---|---|
-| 回复包含固定字段 | `includes` / `matches` |
+| 回复包含固定子串或命中正则 | `includes` |
 | 结构化 JSON 完全匹配 | `equals` |
 | 工具调用是否发生 | `t.calledTool` / `t.notCalledTool` |
 | 输出是否语义正确 | `t.judge.*` |
@@ -20,14 +20,14 @@ description: "用 NiceEval 的五种评分机制评估任意 eval：值断言、
 ## 值断言
 
 ```ts
-import { includes, equals, matches } from "niceeval/expect";
+import { includes, equals } from "niceeval/expect";
 
 t.check(t.reply, includes("refund"));
 t.check(turn.data, equals({ intent: "refund" }));
-t.check(t.reply, matches(/order #\d+/));
+t.check(t.reply, includes(/order #\d+/));
 ```
 
-值断言适合精确、稳定、低歧义的结果。
+`includes` 同时接受子串和正则；`matches` 只接受 Standard Schema / Zod schema，用于结构校验，不做正则匹配。值断言适合精确、稳定、低歧义的结果。
 
 ## 作用域断言