niceeval 0.5.3 → 0.5.4

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

@@ -109,6 +109,10 @@ interface Agent {
 
 `send` 是唯一要实现的函数。它的签名里只有三个类型，分开看。
 
+<Note>
+  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
+</Note>
+
 ### 传入：`TurnInput`
 
 ```ts
@@ -188,6 +192,7 @@ interface AgentContext {
   readonly reasoningEffort?: string;  // 推理努力程度：experiment.reasoningEffort 透传，归属与 model 一致
   readonly telemetry?: Telemetry;  // Tier 2：本轮的 W3C trace context（headers，每轮一个新 traceparent）
   readonly flags: Readonly<Record<string, unknown>>;  // Tier 3 的 feature A/B：experiment.flags 透传；没配时是 {}
+  readonly experimentId?: string;  // 路径推导的实验 id，与结果里的 experimentId 同源；不经 experiment 跑时是 undefined
 
   readonly sandbox?: Sandbox;      // 仅 defineSandboxAgent 构造的 Agent 会拿到
 }
@@ -209,7 +214,7 @@ interface AgentSession {
 }
 ```
 
-`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。
+`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、快照 tag 按它分区），见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
 
 `session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（eval 的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器都在它上面，"第一轮"就是新会话线的自然形态——`id` 是 `undefined`、`history.get()` 是空数组，没有要判断的分支；`state` 是这些存取器之外的逃生舱，框架从不往里写数据。
 

package/docs-site/zh/concepts/experiment.mdx

@@ -25,6 +25,8 @@ export default defineExperiment({
 - `model` / `flags`：透传语义。[NiceEval](https://niceeval.com/) 不解释它们的含义，原样经 `ctx` 递给 Adapter，由 Adapter 随请求转发、应用按需切换——这正是 [Tier](/zh/concepts/tier) 里模型对比（Tier 1）和 feature A/B（Tier 3）的通道。
 - `runs`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[写实验](/zh/guides/write-experiment)。
 
+Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
+
 ## 矩阵对比
 
 要比较的每个变体写一个 experiment 文件：两个模型就是两个文件，只差 `model` 一行；prompt A/B 就是只差一个参数。同一批 eval 在多个 experiment 下各跑一遍，pass rate、成本、延迟就有了可比的横截面——`niceeval view` 里叠着看。适合比什么、结果怎么读，见[实验矩阵](/zh/guides/experiments)。

package/docs-site/zh/guides/custom-reports.mdx

@@ -1,7 +1,7 @@
 ---
 title: "用报告积木搭自己的口径"
 sidebarTitle: "自定义报告"
-description: "一份报告就是一个报告文件：官方宿主打开结果、注入数据，Row / Col 负责排版，双面组件同时渲染网页与终端——niceeval show 与 niceeval view 渲染的官方榜单，就是出厂预装的那份报告。"
+description: "一份报告就是一个报告文件：官方宿主打开结果、注入数据，Row / Col 负责排版，双面组件同时渲染网页与终端——niceeval show 与 niceeval view 默认渲染的默认报告，就是内置的那份报告文件。"
 ---
 
 [查看结果](/zh/guides/viewing-results)讲「用」：官方两扇门 `niceeval show`（终端）和 `niceeval view`（网页）怎么看。本页讲「写」：官方摆法不够时，怎么写一份自己的报告——考试成绩单、代码行数榜、质量 × 成本 frontier。
@@ -10,7 +10,7 @@ description: "一份报告就是一个报告文件：官方宿主打开结果、
 
 ## 官方默认报告也是一份报告文件
 
-`niceeval view` 和 `niceeval show` 渲染的官方榜单不是私有实现，而是出厂预装的一份报告：`niceeval view` 就等于 `niceeval view --report <内置默认报告>`，`show` 同理。我们自己用的零件和给你的完全一样，没有私有数据通道，官方榜单上的每个数字你都能用同样几行代码原样重算出来。
+`niceeval view` 和 `niceeval show` 不传 `--report` 时渲染的默认报告不是私有实现，而是内置的一份报告文件：`niceeval view` 就等于 `niceeval view --report <内置默认报告>`，`show` 同理。我们自己用的零件和给你的完全一样，没有私有数据通道，默认报告上的每个数字你都能用同样几行代码原样重算出来。
 
 |  | 网页（人看） | 终端（agent 和你看） |
 | --- | --- | --- |
@@ -52,15 +52,15 @@ niceeval show --report reports/exam.tsx    # 终端：同一棵树走文本面
 niceeval view --report reports/exam.tsx    # 网页：同一棵树走网页面，attempt 深链直达证据室
 ```
 
-注入的上下文只有两样，全部是[结果数据 API](/zh/guides/results-data) 的原语，宿主没有私有通道：`results` 就是 `openResults(".niceeval")` 的返回（实验、历次快照、attempt 级 `diff()`、`trace()` 都在上面）；`selection` 就是 `results.latest()` 的返回选集——宿主按「每个实验取最新」挑好的现刻水位，与官方榜单同口径，快照在 `selection.snapshots`，挑选警告在 `selection.warnings`。组件的 `data` 函数直接吃选集，警告随行——`RunOverview` 会把残缺快照的警告如实显示，不用你另外接线；默认挑法不合口径时，拿 `results` 自己挑，手工挑的 `Snapshot[]` 数组同样能喂给每个 `data` 函数。
+注入的上下文只有两样，全部是[结果数据 API](/zh/guides/results-data) 的原语，宿主没有私有通道：`results` 就是 `openResults(".niceeval")` 的返回（实验、历次快照、attempt 级 `diff()`、`trace()` 都在上面）；`selection` 就是 `results.latest()` 的返回选集——宿主按「每个实验取最新」挑好的现刻水位，与默认报告同口径，快照在 `selection.snapshots`，挑选警告在 `selection.warnings`。组件的 `data` 函数直接吃选集，警告随行——`RunOverview` 会把残缺快照的警告如实显示，不用你另外接线；默认挑法不合口径时，拿 `results` 自己挑，手工挑的 `Snapshot[]` 数组同样能喂给每个 `data` 函数。
 
-命令行的范围先作用在挑选上，报告拿到的就是范围内的水位：位置参数的 eval id 前缀收窄选集覆盖的 eval（覆盖警告的分母同样收窄到范围内），`--run` 把结果根换成指定目录，`--experiment` 让选集只留该实验。`--history` 与 `--report` 互斥——趋势在报告里用 `exp.snapshots` 自己摆；证据切面（`--transcript` / `--trace` / `--diff`）走证据室，不渲染报告槽。
+命令行的范围先作用在挑选上，报告拿到的就是范围内的水位：位置参数的 eval id 前缀收窄选集覆盖的 eval（覆盖警告的分母同样收窄到范围内），`--run` 把结果根换成指定目录，`--experiment` 让选集只留该实验。`--history` 与 `--report` 互斥——趋势在报告里用 `exp.snapshots` 自己摆；证据切面（`--transcript` / `--trace` / `--diff`）只看证据，不渲染报告。
 
 `<DefaultReport />` 零 props、纯声明：官方水位只读瘦身条目（不碰 diff 这类重工件），宿主总是替你备好，摆不摆在你。它渲染的是**宿主注入的那份选集**的官方水位——跟随命令行范围，但不跟随你在报告里自己另挑的口径；这正是它的意义：当官方锚点，和你的口径并排对照。要「官方摆法 + 自选口径」，用它脚下的同一批组件自己摆——它没有任何私有零件。
 
 页面里的每个组件都是**双面**的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据。你在报告文件里只见到组件本身，从不碰某一面——走哪扇门由宿主决定。官方组件覆盖常见摆法——榜单 `MetricTable`、逐题格子 `MetricMatrix`、分组条形 `MetricBars`、成绩单 `Scoreboard`、质量 × 成本 frontier `MetricScatter`、趋势线 `MetricLine`、成对对比 `DeltaTable`、失败清单 `CaseList`——每个组件回答什么问题、怎么调用、终端字符输出长什么样，逐个见[报告组件](/zh/guides/report-components)。它们在宿主里自动接上证据室：网页面的格子深链到 attempt 弹窗，终端面在条目下印出 `niceeval show <eval id>` 下钻命令。
 
-默认榜单没有特权：报告槽只有一个，`<DefaultReport />` 只是出厂填充。「官方水位 + 自己的口径」像上面那样把它摆进自己的树；不要官方水位就不摆——组合发生在你的 tsx 里，没有 tab、没有注册表、没有配置。
+默认报告没有特权：`<DefaultReport />` 只是不传 `--report` 时渲染的那份内置报告，本身也是一个普通组件。「官方水位 + 自己的口径」像上面那样把它摆进自己的树；不要官方水位就不摆——组合发生在你的 tsx 里，没有 tab、没有注册表、没有配置。
 
 ## 排版：Row 与 Col 在两个面都成立
 
@@ -90,7 +90,7 @@ codex  78.0/100   40/50    38/50    │  codex  80%   $0.51
 
 ## 换口径：自定义指标
 
-官方榜单的口径拆开就是 `MetricTable.data(selection, { rows: "experiment", columns: [passRate, costUSD, durationMs] })`——每个组件的数据算法挂在它自己身上，组件名后打个点就找到；换口径只是把 columns 换成自己的指标：
+默认报告里那张逐实验指标表的口径拆开就是 `MetricTable.data(selection, { rows: "experiment", columns: [passRate, costUSD, durationMs] })`——每个组件的数据算法挂在它自己身上，组件名后打个点就找到；换口径只是把 columns 换成自己的指标：
 
 ```tsx
 // reports/golf.tsx —— code-golf：谁写出能用的代码，谁写得短

package/docs-site/zh/guides/experiments.mdx

@@ -45,6 +45,7 @@ npx niceeval exp compare-models   # 把同组各 model 并排出报告
 - 不同模型（Tier 1 接入即可：应用接口暴露模型选择，`model` 经 `ctx.model` 透传）。
 - 不同 prompts 或 feature flags（要求 Tier 3 接入：变体在应用内部，需要应用把它暴露成 experiment 可选的 flag，经 `flags` → `ctx.flags` 透传）。
 - 不同 sandbox 后端。
+- 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` 钩子里，一个变体一个 experiment 文件，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
 - 同一任务的 pass@N。
 
 Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/concepts/tier)。

package/docs-site/zh/guides/publish-report.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "CI 发布报告"
 description: "把报告站接进 CI:.niceeval/ 提交进仓库,构建命令一行 view --out,push 即发布。发布的站和本地 niceeval view 完全一样;零可读结果时构建失败,保住上一次部署。"
 ---
 
-`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:榜单、快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/guides/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里——把 `.niceeval/` 提交进仓库,仓库本身就是数据源。本地跑完 eval,提交并 push 就是发布,不需要任何脚本或本地构建命令。
+`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/guides/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里——把 `.niceeval/` 提交进仓库,仓库本身就是数据源。本地跑完 eval,提交并 push 就是发布,不需要任何脚本或本地构建命令。
 
 ## `.gitignore` 只排除 `diff.json`
 
@@ -24,7 +24,7 @@ npx niceeval view --out site
 
 ## 发布自定义报告
 
-不传 `--report` 时,发布出来的首页是官方榜单。想让首页换成自己的报告,把 [`defineReport` 报告文件](/zh/guides/custom-reports)传给 `--report` 就行——attempt 证据页(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
+不传 `--report` 时,发布出来的首页是默认报告。想让首页换成自己的报告,把 [`defineReport` 报告文件](/zh/guides/custom-reports)传给 `--report` 就行——attempt 证据页(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
 
 ```bash
 npx niceeval view --report reports/exam.tsx --out site
@@ -84,7 +84,7 @@ jobs:
         uses: actions/deploy-pages@v4
 ```
 
-日常循环从此只有两步:本地跑 eval,提交 `.niceeval/` 并 push。发布出去的站带完整历史——同事打开链接,看到的和你本地 `niceeval view` 一模一样;仓库、本地查看器、线上报告三处同一个真相源。仓库体积随落盘增长(`diff.json` 已排除,增长主要来自 transcript 和 trace 工件),不想保留的旧 run 直接删对应目录即可,查看器和榜单跟着仓库走。
+日常循环从此只有两步:本地跑 eval,提交 `.niceeval/` 并 push。发布出去的站带完整历史——同事打开链接,看到的和你本地 `niceeval view` 一模一样;仓库、本地查看器、线上报告三处同一个真相源。仓库体积随落盘增长(`diff.json` 已排除,增长主要来自 transcript 和 trace 工件),不想保留的旧 run 直接删对应目录即可,查看器和报告跟着仓库走。
 
 ## 发布的是完整证据
 

package/docs-site/zh/guides/results-data.mdx

@@ -105,7 +105,7 @@ for (const s of results.skipped) {
 
 ## 选快照：`results.latest()`
 
-多数场景先回答「现在什么水位」，选择器替你挑「每个实验最新一次」——这也是官方榜单的口径。返回的是一个**选集（Selection）**，快照和警告绑在一起走：
+多数场景先回答「现在什么水位」，选择器替你挑「每个实验最新一次」——这也是默认报告的口径。返回的是一个**选集（Selection）**，快照和警告绑在一起走：
 
 ```typescript
 const latest = results.latest({

package/docs-site/zh/guides/sandbox-agent.mdx

@@ -86,17 +86,22 @@ export default defineExperiment({
 
 ```text
 createSandbox
+  → sandbox spec 的 .setup() 钩子?    # 环境准备（按实验装东西）；没挂就跳过
   → git init && git commit
-  → adapter.setup?                 # 装 CLI / 写 agent 配置
-  → test(t): uploadDirectory(...)   # 写入这条 eval 的起始文件
+  → adapter.setup?                   # 装 CLI / 写 agent 配置
+  → test(t): uploadDirectory(...)     # 写入这条 eval 的起始文件
   → adapter.send(input, ctx)
-  → test(t): runCommand(...)        # 手工运行验证命令
-  → collectGeneratedFiles()         # git diff HEAD
+  → test(t): runCommand(...)          # 手工运行验证命令
+  → collectGeneratedFiles()           # git diff HEAD
+  → adapter.teardown?                 # agent 收尾
+  → sandbox spec 的 .teardown() 钩子?  # 环境收尾（如回存状态），销毁前最后跑
   → sandbox.stop()
 ```
 
 起始文件和验证命令都写在 `test(t)` 中。agent 执行阶段只能看到你已经写进 sandbox 的文件。
 
+环境钩子（`.setup()` / `.teardown()`）挂在 experiment `sandbox` 字段的 spec 上，用来做"按实验变化的环境准备"——装某个实验专属的二进制、预热、跨 attempt 载入和回存状态。它排在 git 基线之前，所以写下的文件不会被算进 agent 产出的 diff。写法和规则见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
+
 ## 自定义 sandbox agent
 
 ```ts

package/docs-site/zh/guides/sandbox-backends.mdx

@@ -49,6 +49,33 @@ 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)`。它们解决一类具体问题：**有些东西你本想直接做进 Docker 镜像或 E2B 模板，但它要按实验变化**——比如某个实验要装一个额外的二进制、预热一次模型、写一份 hook 文件，或者在多次 attempt 之间载入和回存状态。静态镜像做不到"每个实验装不同的东西"，这两个钩子就是运行时补上的那一层。
+
+```ts
+export default defineExperiment({
+  agent: codexAgent({ mcpServers: [mempalMcp] }),
+  sandbox: e2bSandbox({ template: "fasteval-agents" })
+    .setup(mempalSetup("codex"))        // 装二进制、预热、写 hook、载入状态
+    .teardown(mempalTeardown("codex")), // 回存状态
+  maxConcurrency: 1,                    // 载入和回存之间不能并发，声明串行
+});
+```
+
+规则一览：
+
+- **签名**：钩子函数和 Adapter 的 `setup` / `teardown` 一样是 `(sandbox, ctx)`；`setup` 可以返回一个清理函数。
+- **不可变**：每次 `.setup()` / `.teardown()` 都返回一个新 spec，原对象不变，可以继续链。
+- **多个钩子**：多个 `.setup()` 按追加顺序执行；多个 `.teardown()` 按追加的逆序执行。
+- **执行时机**：`setup` 钩子在 sandbox 创建后、git 基线之前最先跑——它写下的文件会进基线，不会被算进 agent 产出的 diff；`teardown` 钩子在 Adapter 的 `teardown` 之后、sandbox 销毁之前最后跑——把状态回存到外部正好用这个时机。
+- **失败语义**：`setup` 钩子抛错，这次 attempt 记为 `errored`（环境问题，不是 agent 做错题）；`teardown` 钩子报错只记日志，不改变已产出的结果。
+- **不带 sandbox 的 Agent**：`defineAgent` 构造的 Agent 没有 sandbox，`sandbox` 字段对它不生效，钩子自然不会跑。
+
+钩子里可以用 `ctx.experimentId`（路径推导的实验 id）当状态隔离的键，比如不同实验各自维护一份跨 attempt 的缓存。跨 attempt 状态的载入和回存是你自己在钩子里写的普通代码——[NiceEval](https://niceeval.com/) 不提供状态存储；要保证同一实验的 attempt 不并发读写同一份状态，在 experiment 上声明 `maxConcurrency: 1`。
+
+和另外两处 setup 的分工：Adapter 的 `setup` 管"怎么连被测 agent"（装 CLI、写鉴权配置）；eval 里 `test(t)` 开头的代码管"这道题需要哪些起始文件"；sandbox 的 `.setup()` 管"这次实验的环境里要多装什么"。三层各写各的，互相不知道对方的内容。MCP server、Skill、model 这些被测 agent 的配置仍然只从 Adapter 工厂参数进——环境钩子不做 Adapter 的事。
+
 ## Docker
 
 Docker 适合本地开发和标准 CI。优点是简单、可控、无云端依赖；缺点是机器资源有限，冷启动和安装依赖可能较慢。

package/docs-site/zh/guides/viewing-results.mdx

@@ -60,7 +60,7 @@ niceeval show weather/brooklyn --history      # 跨 run 时间轴：抖动与回
 
 同一个实验多次跑会留下多份结果，默认视图只回答一个问题——「现在什么水位」：每个 experiment × eval 取时间上最新的那份判决，跨 run 合成。按前缀只重跑了部分 eval 时，其余 eval 的判决从更早的 run 补齐，榜单永远是全局水位，不会因为一次局部重跑变残缺。合成是有标注的：每行带判决产生的时间，榜单头写明合成自几个 run。合成状态可能混着不同版本的被测代码——所以收工判决以 `--force` 全量重跑为准，迭代途中的 `show` 负责快、收尾的全量跑负责真。
 
-多 experiment、多 attempt 时，证据切面默认挑最新一次失败的 attempt；用 `--experiment` 与 `--attempt` 指定其它，用 `--run <目录>` 钉死看某一次历史 run，用 `--history` 看跨 run 趋势（见下文）。默认榜单只是报告槽的出厂填充：`--report <文件>` 可以把它整槽换成你自己的口径，同一个文件也能喂给 `view`，见[自定义报告](/zh/guides/custom-reports)。位置前缀、`--run`、`--experiment` 对 `--report` 同样生效（收窄报告拿到的选集）；`--history` 与 `--report` 互斥，证据切面 flag 出现时走证据室、不渲染报告槽。
+多 experiment、多 attempt 时，证据切面默认挑最新一次失败的 attempt；用 `--experiment` 与 `--attempt` 指定其它，用 `--run <目录>` 钉死看某一次历史 run，用 `--history` 看跨 run 趋势（见下文）。不带 `--report` 时 `show` 渲染的是默认报告；`--report <文件>` 换成你自己的报告，同一个文件也能喂给 `view`，见[自定义报告](/zh/guides/custom-reports)。位置前缀、`--run`、`--experiment` 对 `--report` 同样生效（收窄报告拿到的选集）；`--history` 与 `--report` 互斥，证据切面 flag 出现时只看证据、不渲染报告。
 
 `niceeval view` 的每个视图都有 CLI 对应物：
 
@@ -179,7 +179,7 @@ npx niceeval view
   失败后立刻运行 `npx niceeval view`，可以直接打开刚刚那次运行的 artifacts。
 </Tip>
 
-view 的结构是「报告槽 + 证据室」：报告槽默认装官方榜单，`--report <文件>` 整槽换成你自己的报告（与 `show --report` 吃同一个文件），见[自定义报告](/zh/guides/custom-reports)；证据室（attempt 弹窗、transcript、trace 瀑布）始终保留，报告里的数字点进去就是证据。
+view 的首页是一份报告：不传 `--report` 时是默认报告，传了就换成你自己的报告（与 `show --report` 吃同一个文件），见[自定义报告](/zh/guides/custom-reports)；证据部分（attempt 弹窗、transcript、trace 瀑布）始终保留，报告里的数字点进去就是证据。
 
 ## 导出与静态托管
 

package/docs-site/zh/guides/write-experiment.mdx

@@ -96,6 +96,20 @@ npx niceeval exp prompt-variants
 | `timeoutMs` | 单个 attempt 的超时 |
 | `budget` | 这一格配置的预算上限 |
 | `maxConcurrency` | 这一格配置的并发上限 |
-| `sandbox` | sandbox agent 使用的后端，如 `dockerSandbox()` / `e2bSandbox()` |
+| `sandbox` | sandbox agent 使用的后端，如 `dockerSandbox()` / `e2bSandbox()`；spec 上可以链 `.setup()` / `.teardown()` 挂按实验变化的环境钩子 |
+
+Experiment 本身是纯配置数据，没有 `setup` / `teardown` 这类字段。要在跑 agent 前按实验准备环境（装二进制、预热、跨 attempt 载入和回存状态），挂在 `sandbox` 字段的 spec 上：
+
+```ts
+export default defineExperiment({
+  agent: codexAgent({ mcpServers: [mempalMcp] }),
+  sandbox: e2bSandbox({ template: "fasteval-agents" })
+    .setup(mempalSetup("codex"))        // 装二进制、预热、写 hook、载入状态
+    .teardown(mempalTeardown("codex")), // 回存状态
+  maxConcurrency: 1,                    // 载入和回存之间不能并发，声明串行
+});
+```
+
+钩子的执行时机、多钩子顺序和失败语义见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
 
 跨配置比较的设计建议见[实验矩阵](/zh/guides/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/concepts/adapter)。

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

@@ -82,7 +82,7 @@ npx niceeval exp compare-models weather
 | `--experiment` | string | `show` / `view` 命令专用:选集只留该实验。 |
 | `--attempt` | number | `show` 命令专用:指定详情 / 证据切面看第几次 attempt(与展示一致的 1 计序号)。 |
 | `--run` | string | `show` / `view` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 |
-| `--report` | string | `show` / `view` 命令专用:把默认榜单整槽换成你的报告文件(默认导出 `defineReport(...)`)。 |
+| `--report` | string | `show` / `view` 命令专用:用你的报告文件替换默认报告(文件默认导出 `defineReport(...)`)。 |
 | `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行。 |
 | `--quiet` | boolean | 关闭控制台 / live 进度输出(reporter 仍会写 artifacts)。 |
 | `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |

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

@@ -227,6 +227,18 @@ experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment
 读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 CLI 解析出的
 `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。
 
+#### `experimentId`
+
+```ts
+readonly experimentId?: string;
+```
+
+路径推导出的实验 id(与结果归属 `runWho` / `AgentRun.experimentId` 同源);不经
+experiment 跑(如脱离 CLI、直接构造 `AgentRun` 的场景)时为 undefined。典型用途:
+`SandboxSpec.setup` 钩子按实验隔离跨 attempt 的状态(缓存目录名、快照 tag 等按
+`ctx.experimentId` 分区),或 adapter 按实验切换鉴权 / 路由。与 `flags`(实验条件的
+具体取值)是两个维度——这里只是「跑的是哪个实验」的稳定标识,不携带条件内容。
+
 #### `sandbox`
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",

package/src/agents/bub.ts

@@ -89,7 +89,8 @@ async function ensureBub(sb: Sandbox, home: string): Promise<void> {
 
   const inflight = installsInProgress.get(home);
   if (inflight) {
-    await inflight;
+    // leader 失败(多为沙箱瞬态网络错)不级联杀 waiter:兜掉后走下面自己的安装路径重试。
+    await inflight.catch(() => {});
     const after = memCheckpoints.get(home);
     if (after) { await restoreCheckpoint(sb, after); return; }
   }
@@ -97,6 +98,9 @@ async function ensureBub(sb: Sandbox, home: string): Promise<void> {
   let resolveInstall!: () => void;
   let rejectInstall!: (e: unknown) => void;
   const installPromise = new Promise<void>((res, rej) => { resolveInstall = res; rejectInstall = rej; });
+  // 失败经由下方 throw e 传播给本 attempt;这把锁可能自始至终没有 waiter,
+  // 不兜住 rejection 会变 unhandledRejection,把整个 runner 进程连同全矩阵杀掉。
+  installPromise.catch(() => {});
   installsInProgress.set(home, installPromise);
 
   try {

package/src/agents/index.ts

@@ -79,6 +79,8 @@ export type {
   Agent,
   AgentContext,
   AgentSession,
+  AgentSetup,
+  AgentTeardown,
   AgentTracing,
   SpanMapper,
   Telemetry,

package/src/agents/types.ts

@@ -161,6 +161,14 @@ export interface AgentContext {
    * `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。
    */
   readonly flags: Readonly<Record<string, unknown>>;
+  /**
+   * 路径推导出的实验 id(与结果归属 `runWho` / `AgentRun.experimentId` 同源);不经
+   * experiment 跑(如脱离 CLI、直接构造 `AgentRun` 的场景)时为 undefined。典型用途:
+   * `SandboxSpec.setup` 钩子按实验隔离跨 attempt 的状态(缓存目录名、快照 tag 等按
+   * `ctx.experimentId` 分区),或 adapter 按实验切换鉴权 / 路由。与 `flags`(实验条件的
+   * 具体取值)是两个维度——这里只是「跑的是哪个实验」的稳定标识,不携带条件内容。
+   */
+  readonly experimentId?: string;
   /** 仅沙箱型 agent 有(运行器按 --sandbox 备好)。 */
   readonly sandbox: Sandbox;
   readonly session: AgentSession;

package/src/cli.ts

@@ -125,7 +125,7 @@ const FLAG_OPTIONS = {
   attempt: { type: "string" },
   /** `show` / `view` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 */
   run: { type: "string" },
-  /** `show` / `view` 命令专用:把默认榜单整槽换成你的报告文件(默认导出 `defineReport(...)`)。 */
+  /** `show` / `view` 命令专用:用你的报告文件替换默认报告(文件默认导出 `defineReport(...)`)。 */
   report: { type: "string" },
   /** 只打印本次会匹配到的 eval × 运行配置,不实际执行。 */
   dry: { type: "boolean" },

package/src/context/context.ts

@@ -62,6 +62,8 @@ export interface ContextDeps {
   model?: string;
   reasoningEffort?: string;
   flags: Record<string, unknown>;
+  /** 路径推导出的实验 id(经 send ctx 透给 adapter,见 AgentContext.experimentId)。 */
+  experimentId?: string;
   signal: AbortSignal;
   log(msg: string): void;
   judge: JudgeConfig | undefined;
@@ -93,6 +95,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     model: deps.model,
     reasoningEffort: deps.reasoningEffort,
     flags: deps.flags,
+    experimentId: deps.experimentId,
     signal: deps.signal,
     log: deps.log,
     telemetry: deps.telemetry,

package/src/context/session.ts

@@ -91,6 +91,8 @@ export interface SessionDeps {
   flags: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
+  /** 路径推导出的实验 id(经 send ctx 透给 adapter,见 AgentContext.experimentId)。 */
+  experimentId?: string;
   /** tracing agent 的 OTLP 端点(经 send ctx 透给 adapter,用于注入导出 env)。 */
   telemetry?: Telemetry;
   /** 非沙箱 tracing agent 的共享 OTLP 通道(runner 从 run 级池取,经它做逐轮 span 归属)。 */
@@ -139,6 +141,7 @@ export class SessionManager {
       model: this.deps.model,
       reasoningEffort: this.deps.reasoningEffort,
       flags: this.deps.flags,
+      experimentId: this.deps.experimentId,
       sandbox: this.deps.sandbox,
       session,
       telemetry: this.deps.telemetry,

package/src/define.test.ts

@@ -0,0 +1,82 @@
+// SandboxSpec 链式钩子(.setup()/.teardown())的构造期契约:不可变、多次追加按顺序累加。
+// 执行顺序(setup 正序 / teardown 逆序 / LIFO cleanup)是 runner 的事,见
+// test/e2e-sandbox-hooks.test.ts;这里只测 dockerSandbox()/vercelSandbox()/e2bSandbox()/
+// defineSandbox() 这四个工厂产出的 spec 对象本身的构造行为。
+import { describe, expect, it } from "vitest";
+import { dockerSandbox, e2bSandbox, vercelSandbox, defineSandbox } from "./define.ts";
+import type { AgentSetup, AgentTeardown } from "./types.ts";
+
+const noopSetup: AgentSetup = () => {};
+const noopTeardown: AgentTeardown = () => {};
+
+describe("sandbox factories: .setup()/.teardown() chain", () => {
+  it("dockerSandbox() starts with empty hook arrays", () => {
+    const spec = dockerSandbox({ image: "custom:latest" });
+    expect(spec.backend).toBe("docker");
+    expect(spec.image).toBe("custom:latest");
+    expect(spec.setupHooks).toEqual([]);
+    expect(spec.teardownHooks).toEqual([]);
+  });
+
+  it(".setup() returns a new spec and does not mutate the original", () => {
+    const base = dockerSandbox();
+    const withSetup = base.setup(noopSetup);
+    expect(withSetup).not.toBe(base);
+    expect(base.setupHooks).toEqual([]);
+    expect(withSetup.setupHooks).toEqual([noopSetup]);
+  });
+
+  it("multiple .setup() calls accumulate in append order", () => {
+    const a: AgentSetup = () => {};
+    const b: AgentSetup = () => {};
+    const spec = dockerSandbox().setup(a).setup(b);
+    expect(spec.setupHooks).toEqual([a, b]);
+  });
+
+  it("multiple .teardown() calls accumulate in append order (execution order is the runner's job)", () => {
+    const x: AgentTeardown = () => {};
+    const y: AgentTeardown = () => {};
+    const spec = dockerSandbox().teardown(x).teardown(y);
+    expect(spec.teardownHooks).toEqual([x, y]);
+  });
+
+  it("chaining preserves backend-specific fields and stacks across calls", () => {
+    const spec = dockerSandbox({ image: "img" }).setup(noopSetup).teardown(noopTeardown).setup(noopSetup);
+    expect(spec.backend).toBe("docker");
+    expect(spec.image).toBe("img");
+    expect(spec.setupHooks).toHaveLength(2);
+    expect(spec.teardownHooks).toHaveLength(1);
+  });
+
+  it("vercelSandbox() / e2bSandbox() chain the same way and keep their own fields", () => {
+    const vercel = vercelSandbox({ snapshotId: "snap-1" }).setup(noopSetup);
+    expect(vercel.backend).toBe("vercel");
+    expect(vercel.snapshotId).toBe("snap-1");
+    expect(vercel.setupHooks).toEqual([noopSetup]);
+
+    const e2b = e2bSandbox({ template: "niceeval-agents" }).teardown(noopTeardown);
+    expect(e2b.backend).toBe("e2b");
+    expect(e2b.template).toBe("niceeval-agents");
+    expect(e2b.teardownHooks).toEqual([noopTeardown]);
+  });
+
+  it("defineSandbox() (custom backend) chains too and keeps create()/name", async () => {
+    const create = async () => {
+      throw new Error("not called in this test");
+    };
+    const spec = defineSandbox({ name: "my-backend", create }).setup(noopSetup).setup(noopSetup);
+    expect(spec.backend).toBe("my-backend");
+    expect(spec.create).toBe(create);
+    expect(spec.setupHooks).toHaveLength(2);
+  });
+
+  it("each chain call produces an independent object (no shared mutable state)", () => {
+    const base = dockerSandbox();
+    const other: AgentSetup = () => {};
+    const branchA = base.setup(noopSetup);
+    const branchB = base.setup(other);
+    expect(branchA.setupHooks).toEqual([noopSetup]);
+    expect(branchB.setupHooks).toEqual([other]);
+    expect(branchA.setupHooks).not.toBe(branchB.setupHooks);
+  });
+});

package/src/define.ts

@@ -3,6 +3,8 @@
 
 import type {
   Agent,
+  AgentSetup,
+  AgentTeardown,
   Config,
   CustomSandboxSpec,
   DockerSandboxSpec,
@@ -11,6 +13,7 @@ import type {
   ExperimentDef,
   RemoteAgentDef,
   SandboxAgentDef,
+  SandboxHooks,
   VercelSandboxSpec,
 } from "./types.ts";
 import { t } from "./i18n/index.ts";
@@ -71,20 +74,70 @@ export function defineConfig(config: Config): Config {
 // ───────────────────────── Sandbox 工厂 ─────────────────────────
 // Sandbox 与 agent 一样用数据结构带参数(见 docs/sandbox.md)。这些工厂只是把
 // 后端 + 参数包成 spec 对象;真正的行为在 sandbox/<backend>.ts 里,由 resolve.ts 派发。
+//
+// 四个工厂都要挂上 `.setup()` / `.teardown()` 链式方法(见 sandbox/types.ts 的
+// SandboxHooks<Self>):累积的钩子数组随 `HookState` 传递,每次链式调用都重新调
+// `build()` 产出一个新对象,原 spec 不被修改。
+
+/** 链式追加中累积的钩子(setup 按追加顺序执行,teardown 执行时逆序,见 SandboxHooks)。 */
+interface HookState {
+  readonly setupHooks: readonly AgentSetup[];
+  readonly teardownHooks: readonly AgentTeardown[];
+}
+
+/** 四个工厂共用:把当前钩子状态包成 `.setup()` / `.teardown()` 方法,调用即用新状态重新 build。 */
+function hookMethods<TSpec>(
+  state: HookState,
+  rebuild: (state: HookState) => TSpec,
+): Pick<SandboxHooks<TSpec>, "setup" | "teardown"> {
+  return {
+    setup: (fn) => rebuild({ setupHooks: [...state.setupHooks, fn], teardownHooks: state.teardownHooks }),
+    teardown: (fn) => rebuild({ setupHooks: state.setupHooks, teardownHooks: [...state.teardownHooks, fn] }),
+  };
+}
+
+const EMPTY_HOOKS: HookState = { setupHooks: [], teardownHooks: [] };
 
 /** Docker 沙箱:本地容器。`image` 可覆盖默认 `node:*-slim`(预制模板:烘焙好 agent CLI 的镜像)。 */
-export function dockerSandbox(opts: Omit<DockerSandboxSpec, "backend"> = {}): DockerSandboxSpec {
-  return { backend: "docker", ...opts };
+export function dockerSandbox(
+  opts: Omit<DockerSandboxSpec, "backend" | keyof SandboxHooks<unknown>> = {},
+): DockerSandboxSpec {
+  const build = (state: HookState): DockerSandboxSpec => ({
+    backend: "docker",
+    ...opts,
+    setupHooks: state.setupHooks,
+    teardownHooks: state.teardownHooks,
+    ...hookMethods(state, build),
+  });
+  return build(EMPTY_HOOKS);
 }
 
 /** Vercel Sandbox:microVM。`snapshotId` 从已有快照起(预制模板:烘焙好 agent CLI 的快照)。 */
-export function vercelSandbox(opts: Omit<VercelSandboxSpec, "backend"> = {}): VercelSandboxSpec {
-  return { backend: "vercel", ...opts };
+export function vercelSandbox(
+  opts: Omit<VercelSandboxSpec, "backend" | keyof SandboxHooks<unknown>> = {},
+): VercelSandboxSpec {
+  const build = (state: HookState): VercelSandboxSpec => ({
+    backend: "vercel",
+    ...opts,
+    setupHooks: state.setupHooks,
+    teardownHooks: state.teardownHooks,
+    ...hookMethods(state, build),
+  });
+  return build(EMPTY_HOOKS);
 }
 
 /** E2B 沙箱。`template` 选 e2b 模板名/ID(预制模板:如 `"niceeval-agents"`);省略用 e2b 默认 `"base"`。 */
-export function e2bSandbox(opts: Omit<E2BSandboxSpec, "backend"> = {}): E2BSandboxSpec {
-  return { backend: "e2b", ...opts };
+export function e2bSandbox(
+  opts: Omit<E2BSandboxSpec, "backend" | keyof SandboxHooks<unknown>> = {},
+): E2BSandboxSpec {
+  const build = (state: HookState): E2BSandboxSpec => ({
+    backend: "e2b",
+    ...opts,
+    setupHooks: state.setupHooks,
+    teardownHooks: state.teardownHooks,
+    ...hookMethods(state, build),
+  });
+  return build(EMPTY_HOOKS);
 }
 
 /**
@@ -98,5 +151,13 @@ export function defineSandbox(def: {
 }): CustomSandboxSpec {
   if (!def.name) throw new Error(t("define.sandboxNameRequired"));
   if (typeof def.create !== "function") throw new Error(t("define.sandboxCreateRequired"));
-  return { backend: def.name, create: def.create, recommendedConcurrency: def.recommendedConcurrency };
+  const build = (state: HookState): CustomSandboxSpec => ({
+    backend: def.name,
+    create: def.create,
+    recommendedConcurrency: def.recommendedConcurrency,
+    setupHooks: state.setupHooks,
+    teardownHooks: state.teardownHooks,
+    ...hookMethods(state, build),
+  });
+  return build(EMPTY_HOOKS);
 }

package/src/i18n/en.ts

@@ -186,6 +186,8 @@ export const en = {
   "runner.startAgentSetup": "agent setup (install CLI / write config)...",
   "runner.startAgentTracing": "agent tracing (write OTEL export config)...",
   "runner.startSandbox": "starting sandbox...",
+  "runner.startSandboxSetup": "sandbox setup (environment provisioning hooks)...",
+  "runner.startSandboxTeardown": "sandbox teardown (environment provisioning hooks)...",
   "runner.timeout": "attempt timed out ({{timeoutMs}}ms)\nRecent progress:\n{{recentLogs}}",
   "runner.traceSelected": " -> kept {{count}} semantic spans",
   "runner.resumeCarry": "  · reusing {{carried}} passing results from last run, re-running {{retry}} evals\n",

package/src/i18n/zh-CN.ts

@@ -183,6 +183,8 @@ export const zhCN = {
   "runner.startAgentSetup": "agent setup(装 CLI / 写配置)…",
   "runner.startAgentTracing": "agent tracing(写 otel 导出配置)…",
   "runner.startSandbox": "起沙箱…",
+  "runner.startSandboxSetup": "sandbox setup(环境预置钩子)…",
+  "runner.startSandboxTeardown": "sandbox teardown(环境预置钩子)…",
   "runner.timeout": "attempt 超时({{timeoutMs}}ms)\n最近进度:\n{{recentLogs}}",
   "runner.traceSelected": " → 留 {{count}}(按语义)",
   "runner.resumeCarry": "  · 复用上次 {{carried}} 个通过的结果,重跑 {{retry}} 个 eval\n",

package/src/report/report.ts

@@ -18,7 +18,7 @@ import {
 import { prepareDefaultReportData, runWithDefaultReportData } from "./default-report.tsx";
 
 export interface ReportContext {
-  /** results.latest() 挑好的选集:现刻水位快照 + 结构化挑选警告,同官方榜单口径。 */
+  /** results.latest() 挑好的选集:现刻水位快照 + 结构化挑选警告,同默认报告口径。 */
   selection: Selection;
   /** 默认挑法不合口径时,全量数据自己挑(见 docs/results-lib.md)。 */
   results: Results;

package/src/runner/attempt.ts

@@ -24,6 +24,8 @@ import { captureGeneratedFiles, initGitAndCommit } from "./sandbox-prep.ts";
 import { createRemoteSandbox, withEvalLocalPaths } from "./remote-sandbox.ts";
 import type {
   AgentContext,
+  AgentSetup,
+  AgentTeardown,
   Cleanup,
   Config,
   EvalResult,
@@ -88,6 +90,9 @@ export function runAttemptEffect(
 
   return Effect.scoped(
     Effect.gen(function* () {
+      // run.sandbox ?? config.sandbox 是同一个 SandboxSpec 对象,既用来起沙箱后端,
+      // 也是 sandbox.setup / sandbox.teardown 钩子(SandboxSpec.setup()/.teardown() 链式挂的)的来源。
+      const sandboxSpec = run.sandbox ?? config.sandbox;
       const sandbox =
         run.agent.kind === "sandbox"
           ? yield* sandboxSem.withPermits(1)(
@@ -96,7 +101,7 @@ export function runAttemptEffect(
                 // sandboxSem 只覆盖「容器创建」阶段;容器起好后立即释放,后续 npm install / agent 不占位。
                 log(t("runner.startSandbox"));
                 return yield* createSandbox({
-                  sandbox: run.sandbox ?? config.sandbox,
+                  sandbox: sandboxSpec,
                   timeout: timeoutMs,
                   runtime: "node24",
                 });
@@ -161,6 +166,8 @@ export function runAttemptEffect(
       return yield* Effect.promise((interruptSignal) =>
         runAttemptBody(a, config, t0, base, {
           sandbox,
+          sandboxSetupHooks: sandboxSpec?.setupHooks ?? [],
+          sandboxTeardownHooks: sandboxSpec?.teardownHooks ?? [],
           receiver,
           telemetry,
           otel: otelChannel,
@@ -203,6 +210,10 @@ function causeToError(cause: Cause.Cause<never>): string {
 
 interface AttemptResources {
   sandbox: Sandbox;
+  /** SandboxSpec.setup() 链式挂的钩子,按追加顺序;非沙箱 agent 传空数组(usesSandbox 挡住不会跑)。 */
+  sandboxSetupHooks: readonly AgentSetup[];
+  /** SandboxSpec.teardown() 链式挂的钩子,按追加顺序保存,执行时逆序。 */
+  sandboxTeardownHooks: readonly AgentTeardown[];
   receiver?: TraceReceiver;
   telemetry?: Telemetry;
   /** 非沙箱 tracing agent 的共享 OTLP 通道(run 级池持有,不随 attempt 关)。 */
@@ -221,7 +232,7 @@ async function runAttemptBody(
   res: AttemptResources,
 ): Promise<EvalResult> {
   const { evalDef, run, attempt } = a;
-  const { sandbox, receiver, telemetry, otel, signal, log } = res;
+  const { sandbox, sandboxSetupHooks, sandboxTeardownHooks, receiver, telemetry, otel, signal, log } = res;
   const usesSandbox = run.agent.kind === "sandbox";
   // 整个 attempt 共用一份 agent ctx(sandbox 钩子 / agent setup / tracing configure / teardown 都用它)。
   const attemptCtx: AgentContext = {
@@ -229,6 +240,7 @@ async function runAttemptBody(
     model: run.model,
     reasoningEffort: run.reasoningEffort,
     flags: run.flags,
+    experimentId: run.experimentId,
     sandbox,
     session: createAgentSession(),
     telemetry,
@@ -236,8 +248,20 @@ async function runAttemptBody(
   };
   let agentCleanup: Cleanup | void = undefined;
   let agentDidSetup = false;
+  // SandboxSpec.setup() 返回的 cleanup 闭包,按调用顺序收集;finally 里 LIFO 跑(见下)。
+  const sandboxCleanups: Cleanup[] = [];
   try {
     if (usesSandbox) {
+      // 沙箱级生命周期钩子(SandboxSpec.setup):环境预置层,先于 workspace 上传 / git 基线 /
+      // eval.setup 跑——改动进 git 基线,不会被误算进 agent 产出的 diff。按追加顺序依次执行;
+      // 单个抛错走下面的执行错误路径(与 eval.setup / agent.setup 同一条),已跑过的 cleanup /
+      // sandbox.teardown 钩子仍在 finally 里跑(见 catch/finally)。
+      if (sandboxSetupHooks.length > 0) log(t("runner.startSandboxSetup"));
+      for (const hook of sandboxSetupHooks) {
+        const cleanup = await hook(sandbox, attemptCtx);
+        if (typeof cleanup === "function") sandboxCleanups.push(cleanup);
+      }
+
       await initGitAndCommit(sandbox);
 
       // eval 级 setup(starter prep:npm install / 装系统依赖等)。命令默认非 root;
@@ -271,6 +295,7 @@ async function runAttemptBody(
       model: run.model,
       reasoningEffort: run.reasoningEffort,
       flags: run.flags,
+      experimentId: run.experimentId,
       signal,
       log,
       judge,
@@ -406,7 +431,8 @@ async function runAttemptBody(
     };
   } finally {
     // teardown / cleanup 一律在 finally 跑(失败也跑),不改判决,各自兜错(diagnostic)。
-    // LIFO:先 agent(setup 最晚),再沙箱 Scope。
+    // LIFO:agent 级(setup 最晚 → cleanup / teardown 先跑)在前,sandbox 级(最早就绪)收尾在后
+    //(即 sandbox.setup 返回的 cleanup、sandbox.teardown 钩子最后跑,沙箱销毁前)。
     // 沙箱 stop / 接收器 close 不在这里 —— 由 runAttemptEffect 的 Scope 在本函数返回后回收。
     try {
       if (typeof agentCleanup === "function") await agentCleanup();
@@ -414,6 +440,27 @@ async function runAttemptBody(
     } catch {
       // teardown 失败只是 diagnostic,不影响已出的结果
     }
+    if (usesSandbox) {
+      // sandbox.setup 返回的 cleanup:LIFO(后 setup 先 cleanup),与 agent 级同构。
+      for (let i = sandboxCleanups.length - 1; i >= 0; i--) {
+        try {
+          await sandboxCleanups[i]();
+        } catch {
+          // 同上,只作 diagnostic
+        }
+      }
+      // sandbox.teardown 钩子:按追加的逆序执行,沙箱销毁前最后一步。
+      if (sandboxTeardownHooks.length > 0) {
+        log(t("runner.startSandboxTeardown"));
+        for (let i = sandboxTeardownHooks.length - 1; i >= 0; i--) {
+          try {
+            await sandboxTeardownHooks[i](sandbox, attemptCtx);
+          } catch {
+            // 同上,只作 diagnostic
+          }
+        }
+      }
+    }
   }
 }
 

package/src/sandbox/types.ts

@@ -1,6 +1,8 @@
 // sandbox 域类型:Sandbox 接口、后端 spec(可辨识联合)、命令与文件 IO 的形状。
 // 「在哪里跑、如何隔离」的全部契约在这里;后端实现见本目录各文件,分发见 resolve.ts。
 
+import type { AgentSetup, AgentTeardown } from "../agents/types.ts";
+
 export interface CommandResult {
   stdout: string;
   stderr: string;
@@ -51,25 +53,64 @@ export type SandboxBackend = "docker" | "vercel" | "e2b";
 /** 镜像/模板里的 Node 运行时版本。 */
 export type SandboxRuntime = "node20" | "node24";
 
+/**
+ * SandboxSpec 四个变体共有的沙箱生命周期钩子挂载点:`.setup(fn)` / `.teardown(fn)` 链式方法,
+ * 由 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()` 产出的对象上
+ * 直接可调。
+ *
+ * **语义**:环境预置层,俗称「动态镜像层」——本想直接烘进镜像/快照/模板,但内容要按实验
+ * (`ctx.flags` / `ctx.experimentId`)动态变化的东西:装某个实验专属的二进制、预热缓存、
+ * 写运行期才知道内容的 hook 文件、按 `ctx.experimentId` 载入/回存跨 attempt 的状态。
+ *
+ * **与另外两层 setup 的分工**(三者都在同一个沙箱生命周期里,各管一层):
+ *   · `sandbox.setup`(这里)—— 环境层,不知道具体跑哪个 eval / 接哪个 agent;
+ *   · `eval.setup` —— 任务层,准备这次 eval 的素材(如 `npm install` 起始项目依赖);
+ *   · `agent.setup` —— 协议层,接入被测 agent(装 CLI、写鉴权 / 模型配置)。
+ *
+ * **执行顺序**:沙箱就绪 → `sandbox.setup` 钩子 → workspace 上传 / git 基线 / `eval.setup` →
+ * `agent.setup` → `agent.tracing.configure` → 逐轮 `send`。`sandbox.setup` 特意排在 git
+ * 基线之前——它的改动会被提交进基线,不会被误算进 agent 产出的 diff。收尾按 LIFO:
+ * agent 级 cleanup / `agent.teardown` 先跑,`sandbox.teardown` 钩子最后跑(沙箱销毁前)。
+ *
+ * **多钩子**:`.setup(a).setup(b)` 按追加顺序依次执行(a 先 b 后);`.teardown(x).teardown(y)`
+ * 按追加的**逆序**执行(y 先 x 后)。每次调用都返回一个新 spec(不改变原对象),可继续链式。
+ *
+ * **失败语义**:`setup` 钩子抛错按执行错误计——与 `eval.setup` / `agent.setup` 抛错走同一条
+ * 路径,不新增错误分类;但不阻断该 attempt 已进入的收尾(已跑过的 setup 返回的 cleanup、
+ * `teardown` 钩子仍会在 finally 里跑)。`teardown` 钩子报错只作诊断(吞掉 / 记 log),不改变
+ * 已产出的结果——与 `agent.teardown` 现状一致。
+ */
+export interface SandboxHooks<Self> {
+  /** 已挂载的 setup 钩子,按追加顺序保存(内部读取,一般用不到)。 */
+  readonly setupHooks?: readonly AgentSetup[];
+  /** 已挂载的 teardown 钩子,按追加顺序保存,执行时逆序(内部读取,一般用不到)。 */
+  readonly teardownHooks?: readonly AgentTeardown[];
+  /** 追加一个沙箱级 setup 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
+  setup(fn: AgentSetup): Self;
+  /** 追加一个沙箱级 teardown 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
+  teardown(fn: AgentTeardown): Self;
+}
+
 /**
  * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/sandbox.md)。
  * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
  * 放进 config / experiment 的 `sandbox` 字段 —— 字段类型只接受这个数据结构,不接受裸字符串。
  * 各后端的参数互不相同 —— 这是个按 `backend` 区分的可辨识联合(discriminated union)。
+ * 四个变体都带 {@link SandboxHooks} 的 `.setup()` / `.teardown()` 链式方法。
  */
-export interface DockerSandboxSpec {
+export interface DockerSandboxSpec extends SandboxHooks<DockerSandboxSpec> {
   readonly backend: "docker";
   /** 覆盖默认镜像;默认按 runtime 选 `node:*-slim`。预制模板:传烘焙好 agent CLI 的镜像名。 */
   readonly image?: string;
   readonly runtime?: SandboxRuntime;
 }
-export interface VercelSandboxSpec {
+export interface VercelSandboxSpec extends SandboxHooks<VercelSandboxSpec> {
   readonly backend: "vercel";
   /** 从已有快照起 microVM。预制模板:烘焙好 agent CLI 的 snapshotId。 */
   readonly snapshotId?: string;
   readonly runtime?: SandboxRuntime;
 }
-export interface E2BSandboxSpec {
+export interface E2BSandboxSpec extends SandboxHooks<E2BSandboxSpec> {
   readonly backend: "e2b";
   /** e2b 模板名/ID。预制模板:烘焙好 agent CLI 的模板(如 `"niceeval-agents"`)。省略用 e2b 默认 `"base"`。 */
   readonly template?: string;
@@ -80,7 +121,7 @@ export interface E2BSandboxSpec {
  * 用户自定义后端:`create` 直接产出一个 `Sandbox` 实例,不经 resolve.ts 的内置 backend switch。
  * 用 `defineSandbox()` 构造(见 src/define.ts)。`backend` 只用于展示 / 日志,不参与分发。
  */
-export interface CustomSandboxSpec {
+export interface CustomSandboxSpec extends SandboxHooks<CustomSandboxSpec> {
   readonly backend: string;
   readonly runtime?: SandboxRuntime;
   readonly recommendedConcurrency?: number;

package/src/show/compose.ts

@@ -4,7 +4,7 @@
 // results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出残缺快照;
 // 榜单承诺「不会因为一次局部重跑变残缺」,所以宿主在实验的全部历史快照上逐 eval
 // 向更早的 run 补齐,再把合成好的选集注入报告槽——内置默认报告与 --report 吃同一份,
-// 官方榜单口径 = 宿主注入口径。本文件只消费 niceeval/results 的读取面。
+// 默认报告口径 = 宿主注入口径。本文件只消费 niceeval/results 的读取面。
 
 import { foldEvalOutcome } from "../shared/outcome.ts";
 import { evalPrefixPredicate } from "../report/aggregate.ts";

package/src/view/app/App.tsx

@@ -15,7 +15,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "./components/ui/tabs.t
 import { RunsView } from "./pages/RunsPage.tsx";
 import { TracesView } from "./pages/TracesPage.tsx";
 
-// 报告槽只有一个:默认装官方榜单(Experiments tab);--report 整槽替换成用户报告。
+// 首页报告只有一份:不传 --report 时是默认报告(Experiments tab),传了整页替换成用户报告。
 // 证据室(Runs / Traces / AttemptModal)是 view 本体,两种模式下原样保留。
 export const navItems: { id: Tab; label: MessageKey }[] = [
   { id: "experiments", label: "nav.experiments" },

package/src/view/app/lib/rows.ts

@@ -10,7 +10,7 @@ import { evalLevelStats } from "../../../shared/outcome.ts";
 import { displayExperimentName, fallbackExperimentLabel, sumMaybe } from "../../../shared/aggregate.ts";
 import { formatConfigValue } from "./format.ts";
 
-/** 官方榜单格子的列键(= 内置指标的 metric.name,见 src/report/metrics.ts)。 */
+/** 默认报告格子的列键(= 内置指标的 metric.name,见 src/report/metrics.ts)。 */
 export const CELL_KEYS = {
   passRate: "pass-rate",
   duration: "duration",

package/src/view/app/types.ts

@@ -48,7 +48,7 @@ export interface ViewRow {
   model?: string;
   /** 该快照的 startedAt(ISO)—— 榜单「每行带判决产生的时间」。 */
   lastRunAt: string;
-  /** 官方榜单格子(pass-rate / duration / tokens / cost),display 已格式化。 */
+  /** 默认报告格子(pass-rate / duration / tokens / cost),display 已格式化。 */
   cells: Partial<Record<string, MetricCell>>;
   /** 快照内 attempt 总数。 */
   runs: number;

package/src/view/data.test.ts

@@ -182,7 +182,7 @@ describe("loadViewScan · 跨快照去重(--resume 携带的复印件只算一
 });
 
 describe("loadViewScan · createRunWriter 写出的落盘直接可读(writer/reader 同一契约)", () => {
-  it("writer roundtrip:官方榜单、快照与 attemptRef 都从写入面产物算出", async () => {
+  it("writer roundtrip:默认报告、快照与 attemptRef 都从写入面产物算出", async () => {
     const root = await makeRoot();
     const writer = await createRunWriter(root, { producer: { name: "niceeval", version: "0.4.6" } });
     const snap = writer.snapshot({

package/src/view/data.ts

@@ -251,7 +251,7 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
 
 /**
  * 报告槽渲染:装载报告文件(dev server 语义 —— 文件变更下次请求整页重算,经 mtime
- * cache-busting)→ 注入与官方榜单同口径的选集 → web 面 renderToStaticMarkup 成静态 HTML。
+ * cache-busting)→ 注入与默认报告同口径的选集 → web 面 renderToStaticMarkup 成静态 HTML。
  * react-dom 只在 --report 在场时动态加载,默认 CLI 路径不背 react。
  * attemptHref 缺省即 `#/attempt/<run>/<result>`(view 的 attempt 深链路由)。
  */

package/src/view/shared/types.ts

@@ -72,7 +72,7 @@ export interface ViewData {
   composedRuns: number;
   /** 官方 KPI(RunOverview.data 产物):totals + 选中快照元信息 + 选集 warnings 随行。 */
   overview: OverviewData;
-  /** 官方榜单(MetricTable.data,rows: "experiment"):每个实验最新一次快照的口径。 */
+  /** 默认报告(MetricTable.data,rows: "experiment"):每个实验最新一次快照的口径。 */
   table: TableData;
   /** 整体单行(MetricTable.data,常量维度):hero 的官方通过率,同一台聚合引擎。 */
   overall: TableData;