niceeval 0.5.2 → 0.5.4

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 瀑布）始终保留，报告里的数字点进去就是证据。
 
 ## 导出与静态托管
 
@@ -195,30 +195,14 @@ NiceEval 写入 `<dir>/index.html`，并把查看器要读取的工件（`source
 
 `--out` 只接受目录。没有单文件导出：代码视图、transcript 和 trace 依赖工件文件，单个 HTML 装不下完整证据。要把结果发给别人，托管整站发链接即可。
 
+零可读结果时 `view` 直接报错、非零退出——本地服务起不来，`--out` 不导出空页面。错误逐条列出被跳过的 run 目录与原因；落盘 schemaVersion 与当前版本不兼容时，还给出能直接查看旧落盘的 `npx niceeval@<版本> view` 命令。
+
 两点限制：
 
 - `diff.json` 和 `o11y.json` 不会被复制。查看器不读取它们，且 diff 可能达到上百 MB。
 - 用 `file://` 直接打开 `index.html` 时浏览器不允许 fetch 工件，代码视图会提示源码不可用。本地预览用 http 服务打开。
 
-最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。`.niceeval/` 通常不进版本库，如果构建发生在别的机器（CI、托管平台），先用 `copySnapshots` 把要发布的快照瘦身复制进仓库，再对着快照目录导出：
-
-```typescript
-// scripts/snapshot.ts —— 跑完 eval 后执行，产物提交进仓库
-import { openResults, copySnapshots } from "niceeval/results";
-
-const results = await openResults(".niceeval");
-await copySnapshots(results.latest(), "site-data/run", {
-  artifacts: ["sources", "events", "trace"],
-});
-```
-
-```bash
-npx niceeval view --run site-data/run --out site   # CI 上对着快照构建
-```
-
-结果目录经 `--run` 递入，与 `show --run` 同一语义——位置参数永远留给 eval id 前缀。
-
-`results.latest()` 按实验挑最新快照，而不是挑最新的 run——某次运行只跑了部分实验时，其它实验仍保留上一轮的结果。
+最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。要让站点随 push 自动更新，把 `.niceeval/` 提交进仓库、CI 上一行 `view --out` 导出——workflow 与平台接线见[通过 CI 发布报告](/zh/guides/publish-report)。
 
 ## Artifact 说明
 

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

@@ -1,10 +1,10 @@
 ---
 title: "写实验：用 defineExperiment 固定运行配置"
 sidebarTitle: "写实验"
-description: "学习如何在 experiments/ 里用 defineExperiment 选择 agent、传 model 和 params、设置 runs、预算、并发与 sandbox。"
+description: "学习如何在 experiments/ 里用 defineExperiment 选择 agent、传 model 和 flags、设置 runs、预算、并发与 sandbox。"
 ---
 
-Experiment 是可签入的运行配置：同一批 eval 对着哪个 adapter、哪个模型、哪些参数、跑几次、预算多少，都写在 `experiments/` 里。CLI 的位置参数只负责筛 eval，不负责临时改 agent 或运行配置。
+Experiment 是可签入的运行配置：同一批 eval 对着哪个 adapter、哪个模型、开哪些 flags、跑几次、预算多少，都写在 `experiments/` 里。CLI 的位置参数只负责筛 eval，不负责临时改 agent 或运行配置。
 
 ## 最小实验
 
@@ -20,7 +20,7 @@ export default defineExperiment({
 
 `agent` 放的是已经配置好的 agent 实例。被测系统的 URL、鉴权、协议细节通常传给 adapter 工厂；运行器不会单独保存一个 `agentConfig` 字段。
 
-## 传 model 和 params
+## 传 model 和 flags
 
 ```ts
 // experiments/concise.ts
@@ -34,7 +34,7 @@ export default defineExperiment({
     apiKey: process.env.STAGING_AGENT_API_KEY,
   }),
   model: "gpt-5.4",
-  params: {
+  flags: {
     promptVariant: "concise",
     webResearch: false,
   },
@@ -46,7 +46,7 @@ export default defineExperiment({
 
 `model` 会作为 `ctx.model` 传给 adapter；应用接口支持模型选择时，adapter 把它放进请求体、header 或 CLI 参数即可。
 
-`params` 会作为 `ctx.params` 传给 adapter，也会作为 `t.params` 出现在 eval 里。它适合表达 experiment 维度的 feature 开关，例如 prompt 版本、工具集、检索开关。真正按参数切换行为的是你的应用或 adapter，[NiceEval](https://niceeval.com/) 只负责原样透传。
+`flags` 会作为 `ctx.flags` 传给 adapter，也会作为 `t.flags` 出现在 eval 里。语义就是产品 A/B 测试里的 feature flag：一个 experiment 就是一组 flag 取值，例如 prompt 版本、工具集、检索开关；值可以是任意 JSON（变体名、数字、配置对象），不限于布尔。真正按 flag 切换行为的是你的应用或 adapter，[NiceEval](https://niceeval.com/) 只负责原样透传。它与命令行开关是两回事——后者在文档里一律写作 CLI flag 或字面的 `--xxx`。
 
 ```ts
 // agents/web-agent.ts
@@ -57,7 +57,7 @@ async send(input, ctx) {
     body: JSON.stringify({
       message: input.text,
       model: ctx.model,
-      params: ctx.params,
+      flags: ctx.flags,
     }),
     signal: ctx.signal,
   });
@@ -66,7 +66,7 @@ async send(input, ctx) {
 
 ## 一组实验怎么写
 
-一个实验文件是一格配置。要比较多个模型、agent 或 params，就把多个文件放进同一个文件夹：
+一个实验文件是一格配置。要比较多个模型、agent 或 flag 取值，就把多个文件放进同一个文件夹：
 
 ```text
 experiments/
@@ -89,13 +89,27 @@ npx niceeval exp prompt-variants
 | `agent` | 选择并配置 adapter；必填 |
 | `model` | 单个模型名，经 `ctx.model` 透传 |
 | `reasoningEffort` | 单个推理努力程度（如 `"high"`），经 `ctx.reasoningEffort` / `t.reasoningEffort` 透传，归属与 `model` 一致 |
-| `params` | 任意 JSON 对象，经 `ctx.params` / `t.params` 透传 |
+| `flags` | 实验条件（A/B 里的 feature flag），任意 JSON 对象，经 `ctx.flags` / `t.flags` 透传 |
 | `runs` | 每个 eval × 配置最多跑几次 |
 | `earlyExit` | 多次运行里通过一次就提前停止 |
 | `evals` | 限定这一格配置跑哪些 eval |
 | `timeoutMs` | 单个 attempt 的超时 |
 | `budget` | 这一格配置的预算上限 |
 | `maxConcurrency` | 这一格配置的并发上限 |
-| `sandbox` | sandbox agent 使用的后端，如 `dockerSandbox()` / `e2bSandbox()` |
+| `sandbox` | sandbox agent 使用的后端，如 `dockerSandbox()` / `e2bSandbox()`；spec 上可以链 `.setup()` / `.teardown()` 挂按实验变化的环境钩子 |
 
-跨配置比较的设计建议见[实验矩阵](/zh/guides/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.params` 见[Adapter](/zh/concepts/adapter)。
+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/guides/write-send.mdx

@@ -1,7 +1,7 @@
 ---
 title: "如何写好 Send"
 sidebarTitle: "如何写好 Send"
-description: "手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 params。每一步只在上一步的代码上多几行，每一步解锁一组断言。"
+description: "手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 flags。每一步只在上一步的代码上多几行，每一步解锁一组断言。"
 ---
 
 [Adapter](/zh/concepts/adapter) 讲了契约：`send` 传入 `TurnInput` 和 `AgentContext`，返回 `Turn`。这一页讲怎么写它——从"发一条消息拿到回复"的最小形态起步，一步一步加到完整接入。每一步只在上一步的代码上多几行，前面已有的部分在代码里用 `// ……省略` 标出；每一步末尾说明这几行解锁了哪些断言。改完任何一步都能立刻验证：把新解锁的断言写进一条 eval 重跑 `npx niceeval exp`，`niceeval view` 里能看到这一步新增的数据——多轮轨迹、用量、工具事件、待回答请求。
@@ -303,16 +303,16 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces node server.js
 
 **这一步解锁**：`niceeval view` 里的调用瀑布图——应用内部每次模型调用、每次工具执行的耗时与 token，按轮铺成时间线。断言不变：判决依据在前几步的事件映射里已经齐了，span 只进瀑布图、不喂断言。接收器怎么起、span 怎么归属到轮，见 [OTel 接入](/zh/guides/connect-otel)。
 
-## 第七步：透传 experiment 的 params（A/B 对比）
+## 第七步：透传 experiment 的 flags（A/B 对比）
 
-应用把变体暴露成可切换的配置后，experiment 声明 `params`，运行器每轮经 `ctx.params` 原样递给 `send`；Adapter 不解释它们的含义，只随请求转发——应用按参数切换变体：
+应用把变体暴露成可切换的配置后，experiment 声明 `flags`，运行器每轮经 `ctx.flags` 原样递给 `send`；Adapter 不解释它们的含义，只随请求转发——应用按参数切换变体：
 
 ```ts
       // ……send 其余部分同前，省略
       body: JSON.stringify({
         messages,
         model: ctx.model,        // ← 第一步就转发的 experiment.model；这里一起列出
-        params: ctx.params,      // ← experiment.params 原样透传；没配时是 {}
+        flags: ctx.flags,      // ← experiment.flags 原样透传；没配时是 {}
       }),
 ```
 
@@ -324,11 +324,11 @@ import chatApp from "../agents/chat-app.ts";
 export default defineExperiment({
   agent: chatApp,
   model: "gpt-5.4",                      // ← 经 ctx.model 到 send
-  params: { promptVariant: "concise" },  // ← 每轮经 ctx.params 到 send
+  flags: { promptVariant: "concise" },  // ← 每轮经 ctx.flags 到 send
 });
 ```
 
-两个 experiment 文件各声明一份 `params`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/concepts/tier)；`params` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/guides/write-experiment)。
+两个 experiment 文件各声明一份 `flags`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/concepts/tier)；`flags` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/guides/write-experiment)。
 
 **这一步解锁**：同一批 eval 跨变体的成绩对比。
 

package/docs-site/zh/index.mdx

@@ -87,7 +87,7 @@ eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告
 | 概念 | 一句话 |
 |---|---|
 | [Eval](/zh/concepts/evals) | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
-| [Experiment](/zh/concepts/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 params。 |
+| [Experiment](/zh/concepts/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
 | [Adapter](/zh/concepts/adapter) | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
 | [Sandbox](/zh/guides/sandbox-backends) | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | [Tier](/zh/concepts/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |

package/docs-site/zh/introduction.mdx

@@ -114,7 +114,7 @@ NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「
 | 概念 | 一句话 |
 |---|---|
 | Eval | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
-| Experiment | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 params。 |
+| Experiment | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
 | Adapter | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
 | Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |

package/docs-site/zh/reference/builtin-agents.mdx

@@ -56,6 +56,8 @@ description: "NiceEval 内置的 claude-code、codex、bub 适配器分别做到
 
 {/* GENERATED:BEGIN builtin-agent-config */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 ### `ClaudeCodeConfig`
 
 #### `apiKey`
@@ -196,6 +198,8 @@ export default uiMessageStreamAgent({
 
 {/* GENERATED:BEGIN ui-message-stream-options */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `name`
 
 ```ts

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

@@ -4,7 +4,7 @@ sidebarTitle: "命令行"
 description: "NiceEval CLI 参考：exp、init、list、clean 和 view 命令，以及 experiment、eval 过滤、sandbox、并发、预算和 JUnit CI 输出。"
 ---
 
-[NiceEval](https://niceeval.com/) CLI 是发现、运行和查看 eval 的入口。实际执行 eval 时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按 eval ID 前缀过滤。agent、model 和 params 写在 `experiments/`，不靠临时 CLI 参数。
+[NiceEval](https://niceeval.com/) CLI 是发现、运行和查看 eval 的入口。实际执行 eval 时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按 eval ID 前缀过滤。agent、model 和 flags 写在 `experiments/`，不靠临时 CLI 参数。
 
 ## 命令
 
@@ -56,10 +56,12 @@ npx niceeval exp compare-models weather
 
 ## 常用 flags
 
-下表由 CLI 的 flag 解析表生成。**没有**用于选择 sandbox 后端的 CLI flag：sandbox 后端只能写在代码里——在 experiment（`defineExperiment`）里设置 `sandbox`，或者在 `niceeval.config.ts`（`defineConfig`）里设置作为项目级兜底，值来自 `niceeval/sandbox` 的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()`；在 CLI 上尝试传入 `--sandbox` 会直接报错并以非零状态退出。`--watch` / `--json` 是文档曾接受、尚未实现的 flag，容忍解析（no-op）但不接任何行为，同样不在下表出现。
+下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 sandbox 后端的 CLI flag：sandbox 后端只能写在代码里——在 experiment（`defineExperiment`）里设置 `sandbox`，或者在 `niceeval.config.ts`（`defineConfig`）里设置作为项目级兜底，值来自 `niceeval/sandbox` 的 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()`。
 
 {/* GENERATED:BEGIN cli-flags */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 | Flag | 类型 | 说明 |
 |---|---|---|
 | `--agent` | string | experiment 运行不支持该 flag。要换 agent,请在 `experiments/` 下新增或复制一个配置文件。 |
@@ -70,16 +72,17 @@ npx niceeval exp compare-models weather
 | `--budget` | number | 整次运行的预算上限(美元)。 |
 | `--tag` | string | 只运行带有该 tag 的 eval(见 `defineEval` 的 `tags`)。 |
 | `--junit` | string | 额外写一份 JUnit XML 报告到指定路径,供 CI 消费。 |
+| `--json` | string | 额外写一份 JSON 结果(`RunSummary` 原样序列化)到指定路径,供 CI 或下游脚本消费。 |
 | `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
 | `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
 | `--transcript` | boolean | `show` 命令专用:渲染单个 eval 的完整对话与工具调用(证据切面)。 |
 | `--trace` | boolean | `show` 命令专用:渲染单个 eval 的 trace 瀑布文本版(证据切面)。 |
 | `--diff` | boolean | `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 |
 | `--history` | boolean | `show` 命令专用:跨 run 时间轴,只列真实执行;与 `--report` 互斥。 |
-| `--experiment` | string | `show` 命令专用:选集只留该实验。 |
+| `--experiment` | string | `show` / `view` 命令专用:选集只留该实验。 |
 | `--attempt` | number | `show` 命令专用:指定详情 / 证据切面看第几次 attempt(与展示一致的 1 计序号)。 |
-| `--run` | string | `show` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 |
-| `--report` | string | `show` 命令专用:把默认榜单整槽换成你的报告文件(默认导出 `defineReport(...)`)。 |
+| `--run` | string | `show` / `view` 命令专用:钉死看某一个结果目录(历史 run 或 `copySnapshots` 产物)。 |
+| `--report` | string | `show` / `view` 命令专用:用你的报告文件替换默认报告(文件默认导出 `defineReport(...)`)。 |
 | `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行。 |
 | `--quiet` | boolean | 关闭控制台 / live 进度输出(reporter 仍会写 artifacts)。 |
 | `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |
@@ -106,7 +109,7 @@ npx niceeval exp compare-models
 npx niceeval exp compare-models weather-tool
 ```
 
-运行命名 experiment，用矩阵比较 agents、models 或 params。第二个参数开始是 eval ID 前缀过滤。
+运行命名 experiment，用矩阵比较 agents、models 或 flags。第二个参数开始是 eval ID 前缀过滤。
 
 ## `view`
 

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

@@ -80,6 +80,8 @@ export default defineExperiment({
 
 {/* GENERATED:BEGIN agent-def */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 ### `RemoteAgentDef`
 
 #### `name`
@@ -214,17 +216,29 @@ readonly reasoningEffort?: string;
 
 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。
 
-#### `params`
+#### `flags`
 
 ```ts
-readonly params: Readonly<Record<string, unknown>>;
+readonly flags: Readonly<Record<string, unknown>>;
 ```
 
-experiment 的 `params` 字段原样透传,内容和结构完全由 experiment 作者自定义
+experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义
 (如 `{ webResearch: true }`、`{ systemPrompt: "..." }`)。adapter 按自己的约定
 读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 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
@@ -280,6 +294,8 @@ log(msg: string): void;
 
 {/* GENERATED:BEGIN sandbox-methods */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 ### `Sandbox`
 
 #### `workdir`

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

@@ -4,7 +4,7 @@ sidebarTitle: "defineConfig"
 description: "defineConfig 参考：judge、reporters、并发、超时和 sandbox 默认值。"
 ---
 
-`defineConfig` 从根目录的 `niceeval.config.ts` 默认导出，只放项目级默认值。agent、model、params、runs 和实验预算写在 `experiments/` 下的 `defineExperiment` 文件里。
+`defineConfig` 从根目录的 `niceeval.config.ts` 默认导出，只放项目级默认值。agent、model、flags、runs 和实验预算写在 `experiments/` 下的 `defineExperiment` 文件里。
 
 ```ts
 import { defineConfig } from "niceeval";
@@ -20,6 +20,8 @@ export default defineConfig({
 
 {/* GENERATED:BEGIN config-fields */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `name`
 
 ```ts

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

@@ -26,6 +26,8 @@ export default defineEval({
 
 {/* GENERATED:BEGIN defineeval-options */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `id`
 
 ```ts
@@ -108,6 +110,8 @@ eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。
 
 {/* GENERATED:BEGIN test-context */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `send`
 
 ```ts
@@ -207,13 +211,13 @@ readonly reasoningEffort?: string;
 
 本次 attempt 的推理努力程度(如 "low"/"medium"/"high",取值由 adapter/模型决定)。
 
-#### `params`
+#### `flags`
 
 ```ts
-readonly params: Readonly<Record<string, unknown>>;
+readonly flags: Readonly<Record<string, unknown>>;
 ```
 
-本次 attempt 生效的 params(experiment.params 与 CLI flag 合并后的只读视图)。
+本次 attempt 生效的实验 flags(experiment.flags 的只读视图;实验条件,非命令行开关)。
 
 #### `log`
 
@@ -440,6 +444,8 @@ t.judge.autoevals.summarizes(sourceText, { on: t.reply }).atLeast(0.7);
 
 {/* GENERATED:BEGIN turn-handle */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `events`
 
 ```ts

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

@@ -23,6 +23,8 @@ interface Turn {
 
 {/* GENERATED:BEGIN usage-fields */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `inputTokens`
 
 ```ts
@@ -81,6 +83,8 @@ token 用量或 OTel span 反推得到)。存在时优先于按价格表(`define
 
 {/* GENERATED:BEGIN stream-events */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `message`
 
 ```ts

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

@@ -29,6 +29,8 @@ t.require(turn.status, equals("completed"));
 
 {/* GENERATED:BEGIN expect-matchers */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `includes`
 
 ```ts
@@ -150,6 +152,8 @@ t.check(t.reply, includes("nice to have").atLeast(0.7));
 
 {/* GENERATED:BEGIN value-assertion */}
 
+{/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
+
 #### `name`
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -100,7 +100,8 @@
     "shiki": "^4.3.0",
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.1",
-    "typescript": "^5.6.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "vite": "^8.1.0",
     "vitest": "^4.1.9"
   },

package/src/agents/ai-sdk.test.ts

@@ -454,7 +454,7 @@ function fakeCtx(opts: { id?: string } = {}): AgentContext {
   return {
     signal: new AbortController().signal,
     model: undefined,
-    params: {},
+    flags: {},
     sandbox: undefined as unknown as AgentContext["sandbox"],
     session,
     log: () => {},

package/src/agents/ai-sdk.ts

@@ -367,7 +367,7 @@ export interface AiSdkGenerateContext<M = unknown> {
   /** 实验钉的推理努力程度(ctx.reasoningEffort);省略 → 用应用自己的默认。应用自己决定怎么塞进 providerOptions(如 OpenAI 的 reasoningEffort)。 */
   readonly reasoningEffort?: string;
   readonly signal: AbortSignal;
-  readonly params: Readonly<Record<string, unknown>>;
+  readonly flags: Readonly<Record<string, unknown>>;
   /**
    * 配了 `tracing`(如 `aiSdkOtel()`)才有:直接放进 generateText / streamText 的
    * `telemetry` 选项。OTel provider、per-attempt 端点绑定和轮末 flush 都由工厂做,
@@ -505,7 +505,7 @@ export function aiSdkAgent<M = unknown>(options: AiSdkAgentOptions<M>): Agent {
           model: ctx.model,
           reasoningEffort: ctx.reasoningEffort,
           signal: ctx.signal,
-          params: ctx.params,
+          flags: ctx.flags,
           telemetry: otel?.settings,
         });
       } catch (error) {

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/claude-code.ts

@@ -94,7 +94,7 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       const args = ["--print", "--dangerously-skip-permissions"];
       if (ctx.model) args.push("--model", ctx.model);
       if (config?.maxTurns != null) args.push("--max-turns", String(config.maxTurns));
-      if (ctx.params.webResearch) args.push("--allowedTools", "WebSearch,WebFetch");
+      if (ctx.flags.webResearch) args.push("--allowedTools", "WebSearch,WebFetch");
       if (ctx.session.id) args.push("--resume", ctx.session.id);
       args.push(input.text);
 

package/src/agents/codex.ts

@@ -9,7 +9,7 @@ import type { Agent, McpServer } from "../types.ts";
 //
 // 连接方式:在沙箱里 spawn `codex exec --json`,stdout JSONL → parseCodex → 标准事件流。
 // 配置:鉴权本地(config / env),模型交给实验(ctx.model),推理努力程度经 ctx.reasoningEffort
-// (兼容旧的 ctx.params.effort),其余参数经 ctx.params。
+// (兼容旧的 ctx.flags.effort),其余参数经 ctx.flags。
 // ───────────────────────────────────────────────────────────────────────────
 
 export interface CodexConfig {
@@ -44,7 +44,7 @@ export function codexAgent(config?: CodexConfig): Agent {
       // model 归属:实验决定(ctx.model);省略时不写 model 行,交给 codex CLI 原生默认,
       // 不在 adapter 里硬编码一个会过期的模型名。
       const modelLine = ctx.model ? `model = "${ctx.model}"\n` : "";
-      const effort = ctx.reasoningEffort ?? (ctx.params.effort as string | undefined) ?? "medium";
+      const effort = ctx.reasoningEffort ?? (ctx.flags.effort as string | undefined) ?? "medium";
       const base = getBaseUrl();
 
       if (base) {

package/src/agents/index.ts

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

package/src/agents/streaming.test.ts

@@ -9,7 +9,7 @@ import { createAgentSession } from "../context/session.ts";
 function lineCtx(): AgentContext {
   return {
     signal: new AbortController().signal,
-    params: {},
+    flags: {},
     session: createAgentSession(),
     sandbox: undefined as never,
     log() {},

package/src/agents/types.ts

@@ -155,12 +155,20 @@ export interface AgentContext {
   /** 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。 */
   readonly reasoningEffort?: string;
   /**
-   * experiment 的 `params` 字段原样透传,内容和结构完全由 experiment 作者自定义
+   * experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义
    * (如 `{ webResearch: true }`、`{ systemPrompt: "..." }`)。adapter 按自己的约定
    * 读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 CLI 解析出的
    * `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。
    */
-  readonly params: Readonly<Record<string, unknown>>;
+  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/agents/ui-message-stream.test.ts

@@ -73,7 +73,7 @@ function ctx(overrides: Partial<{ model: string }> = {}): AgentContext {
   return {
     signal: new AbortController().signal,
     model: overrides.model,
-    params: {},
+    flags: {},
     sandbox: undefined as never,
     // 同一个 ctx 重复用 = 同一条会话线(续接,同一个 ctx.session);新造 = 新线。
     session: createAgentSession(),