niceeval 0.6.0 → 0.6.2

package/docs-site/zh/guides/agent-feedback-loop.mdx

@@ -38,7 +38,7 @@ AI 通常按任务选择这些入口：
 <Steps>
   <Step title="运行实验">
     ```bash
-    npx niceeval exp local
+    npx niceeval exp local --output agent
     ```
 
     先读取退出码：`0` 表示所有 Eval 通过；`1` 表示至少一个 Eval 失败或出错；`2` 表示 NiceEval 自身未能完成运行。退出码决定是否继续，控制台文本用于定位原因。
@@ -49,7 +49,7 @@ AI 通常按任务选择这些入口：
     npx niceeval show @1k2m9qtr
     ```
 
-    第一条命令显示当前各实验的通过率、成本、耗时，以及每个 Eval 的紧凑 Attempt locator。`[E]` / `[X]` / `[⏱]` / `[D]` 分别表示运行时 Eval 源码、执行步骤、OTel 时间和 diff 可用。第二条命令直接打开选中的 Attempt。
+    第一条命令显示当前各实验的通过率、成本、耗时，以及每个 Eval 的紧凑 Attempt locator——locator 本身就是证据入口，不在列表里编码证据可用性。第二条命令直接打开选中的 Attempt，页面末尾的 `available:` 只列出这个 Attempt 实际可用的证据命令。
   </Step>
   <Step title="按问题读取证据">
     ```bash
@@ -59,7 +59,7 @@ AI 通常按任务选择这些入口：
 
     `--execution` 合并 AI 输出与 trace：标准事件流提供消息、thinking、tool call/result 和 Skill load；OTel 在能够关联时给同一节点补开始时间、耗时、父子关系和错误状态。没有 OTel 时步骤仍完整，只不显示时间。
 
-    不带证据 flag 时，`show @<id>` 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行与文件变化摘要。AI 应该先读这一页；只有需要回答“为什么产生这个值”时，才继续打开对应证据。
+    不带证据 flag 时，`show @<id>` 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行、生命周期阶段耗时与文件变化摘要。AI 应该先读这一页；只有需要回答“为什么产生这个值”时，才继续打开对应证据。
 
     ```text
     $ niceeval show @1k2m9qtr
@@ -68,7 +68,7 @@ AI 通常按任务选择这些入口：
     eval source: evals/weather/brooklyn.eval.ts · sha256:8d47…
 
      8  export default defineEval({
-     9    id: "weather/brooklyn",
+     9    description: "Brooklyn weather query",
     10    async test(t) {
     11      const turn = await t.send("布鲁克林今天天气怎么样？");
     12 ✗    turn.calledTool("get_weather");
@@ -88,19 +88,17 @@ AI 通常按任务选择这些入口：
         received: 1
         source: evals/memory/swelancer-manager-proposals.eval.ts:40:11
 
-    execution [X,⏱]
-    agent run                     ▕████████████████████▏ 41.2s
-    ├─ inference                  ▕█████░░░░░░░░░░░░░░░▏ 10.1s · "布鲁克林今天大约 24°C，晴。"
-    ├─ inference                  ▕░░░░░█████████░░░░░░▏ 18.3s
-    └─ inference                  ▕░░░░░░░░░░░░░░██████▏ 12.4s
-    no tool calls
+    execution: 3 events · 0 skill loads · 0 tool calls · 1 AI messages
+    timing: eval.run 40.4s · scoring.evaluate 0.5s · teardown +0.2s
 
     changes · diff unavailable
     reason: this Attempt did not produce workspace file changes
 
-    evidence: Eval source [E] · execution [X] · OTel timing [⏱]
-    full eval source: …/weather/brooklyn/a2/eval-source.ts
-    next: niceeval show @1k2m9qtr [--eval|--execution|--diff]
+    full eval source: …/weather/brooklyn/a2/sources.json
+    available:
+      niceeval show @1k2m9qtr --eval
+      niceeval show @1k2m9qtr --execution
+      niceeval show @1k2m9qtr --timing
     ```
 
     `--execution` 把 AI 消息、Skill load、工具调用和工具结果排成一棵执行树。它只展示 Agent 可理解的事件；没有关联到这些事件的 SDK / runtime span 不逐行输出，只报告省略数量并保留 `trace.json` 路径。下面的 Attempt 有 OTel，所以能关联的节点同时带相对时间与耗时：
@@ -155,7 +153,7 @@ AI 通常按任务选择这些入口：
     full events: …/weather/brooklyn/a2/events.json
     ```
 
-    diff 是被测 Agent 在 Sandbox 工作区造成的文件变化，不是 Eval 源码的新旧差异。它只会出现在带 `[D]` 的 locator 上。默认先给文件级摘要，避免把大段补丁塞进 Agent 上下文；`--diff=<文件>` 再展开单个文件，原始 artifact 路径始终保留：
+    diff 是被测 Agent 在 Sandbox 工作区造成的文件变化，不是 Eval 源码的新旧差异。只有 sandbox eval 才会收集到 diff——非 sandbox eval 或 agent 确实没碰任何文件时，attempt 页的 `available:` 列表会省略 `--diff`。默认先给文件级摘要，避免把大段补丁塞进 Agent 上下文；`--diff=<文件>` 再展开单个文件，原始 artifact 路径始终保留：
 
     ```text
     $ niceeval show @1c3h6tbn --diff
@@ -173,9 +171,10 @@ AI 通常按任务选择这些入口：
 
     | 要回答的问题 | 入口 | 输出必须包含 |
     | --- | --- | --- |
-    | 快速判断一次 Attempt 发生了什么 | `niceeval show @<id>` | Eval 断言、执行步骤、可选 OTel 时间、diff 摘要及各块可用性 |
+    | 快速判断一次 Attempt 发生了什么 | `niceeval show @<id>` | Eval 断言、执行步骤、生命周期阶段耗时摘要、diff 摘要及各块可用性 |
     | Eval 实际检查了什么，哪条 gate / soft 为什么通过或失败 | `niceeval show @<id> --eval` | 运行时 Eval 源码、源码哈希、断言所在行、严重度、分数与原因 |
-    | AI 做了什么、调用了什么、时间花在哪里 | `niceeval show @<id> --execution` | 消息、thinking、Skill load、工具调用与结果；有 OTel 时在同一节点显示时间、父子关系和错误状态 |
+    | AI 做了什么、调用了什么 | `niceeval show @<id> --execution` | 消息、thinking、Skill load、工具调用与结果；有 OTel 时在同一节点附时间、父子关系和错误状态 |
+    | 整个 Attempt 的时间花在哪里 | `niceeval show @<id> --timing` | lifecycle → hook/turn → shell → OTel 的统一时间树；出错的 Attempt 标出已知的最深失败节点 |
     | Sandbox 工作区文件变成什么 | `niceeval show @<id> --diff` | 文件摘要、增删行数、具体补丁和原始 diff 路径；无文件工作区时明确 unavailable |
   </Step>
   <Step title="提出假设并修改">
@@ -193,7 +192,7 @@ AI 通常按任务选择这些入口：
   </Step>
   <Step title="局部重跑并验证假设">
     ```bash
-    npx niceeval exp local weather/brooklyn --force
+    npx niceeval exp local weather/brooklyn --output agent --force
     npx niceeval show weather/brooklyn
     ```
 
@@ -201,7 +200,7 @@ AI 通常按任务选择这些入口：
   </Step>
   <Step title="全量确认没有回归">
     ```bash
-    npx niceeval exp local --force
+    npx niceeval exp local --output agent --force
     npx niceeval show
     ```
 
@@ -211,19 +210,22 @@ AI 通常按任务选择这些入口：
 
 ## AI 应该从输出里读什么
 
-`exp` 运行结束后会给出三类信息：失败摘要、结果统计和结果快照目录。典型输出如下：
+`--output agent` 运行中只向 stderr 追加低频 checkpoint（存活信号，不是结果数据源），结束时向 stdout 打印一个有界 handoff block——这才是 AI 应该解析的部分：
 
 ```text
-Failing:
-  ✗ weather/brooklyn · @1k2m9qtr[E,X,⏱]
-      gate calledTool("get_weather"): tool was never called
-
-Results: 14 passed, 1 failed, 0 errored, 0 skipped
-Structured results: .niceeval/local/2026-07-09T10-00-00-000Z-x1f2/
-  (snapshot.json + 每 attempt 的 result.json / events.json / trace.json / diff.json)
+NICEEVAL RESULT failed
+summary: 14 passed, 1 failed, 0 errored (0 reused)
+snapshots:
+  - .niceeval/local/2026-07-09T10-00-00-000Z-x1f2/
+failures:
+  - @1k2m9qtr weather/brooklyn [local]
+    gate: tool was never called
+next:
+  niceeval show @1k2m9qtr
+  niceeval show @1k2m9qtr --execution
 ```
 
-AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval show @<id>` 或对应证据 flag，不要从头解析运行期间不断刷新的进度行。需要机器读取时，结果快照是事实来源：
+AI 应先从 `failures` 选中 Attempt locator，再按证据位执行 `next` 给出的 `niceeval show @<id>` 或对应证据 flag，不要解析运行期间 stderr 上低频追加的 checkpoint 行——那些只用于判断进程是否存活。失败条数超过上限（默认 5 条）时,handoff 只展开前几条并给出总数,完整清单读结果快照。需要机器读取时，结果快照是事实来源：
 
 ```text
 .niceeval/<experiment>/<快照>/
@@ -236,7 +238,7 @@ AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval sh
 ```
 
 - `snapshot.json` 记录实验身份、运行配置、格式版本和时间。
-- `result.json` 记录该 Attempt 的判定、断言、错误和用量。
+- `result.json` 记录该 Attempt 的判定、断言、结构化错误、diagnostics 和用量；瞬时 progress 不落盘。
 - `events.json` 是对话与工具调用事件，`trace.json` 是调用链，`diff.json` 是 Sandbox 文件变化。
 - 某类证据不存在时，对应文件不会生成。先以 `show` 的提示为准，不要假设每个目录都有全部文件。
 
@@ -266,12 +268,14 @@ AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval sh
 
 ```text
 读取 node_modules/niceeval/INDEX.md，再按索引读取与任务有关的文档。
-运行 npx niceeval exp local，并根据退出码和失败摘要决定下一步。
+运行 npx niceeval exp local --output agent，并根据退出码和失败 locator 决定下一步。
 对每个失败的 Eval，从报告选择一个 Attempt locator；再运行 niceeval show @<id>
-并按问题选择默认 Eval 源码面、--execution 或 --diff。写出失败原因的假设，并判断应该修改被测程序、
+并按问题选择 --eval、--execution、--timing 或 --diff；--timing 从 lifecycle 展开 setup/teardown
+hook、shell 命令、每轮 send 与可关联的 OTel model/tool，回答整个 Attempt 的时间花在哪里。
+写出失败原因的假设，并判断应该修改被测程序、
 Eval，还是实验环境。修改后用 --force 重跑对应 Eval，比较新的判定和证据。
 同一问题连续三轮没有新证据或改善时停止并汇报，不要靠放宽断言碰绿。
-全部局部失败清零后，用 npx niceeval exp local --force 全量验证；退出码 0 才完成。
+全部局部失败清零后，用 npx niceeval exp local --output agent --force 全量验证；退出码 0 才完成。
 ```
 
 真实 Agent 的运行可能产生费用。实验阶段可以加 `--budget <美元>` 限制本轮累计成本；预算只能限制单次命令，不能替代上面的停止条件。

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

@@ -18,6 +18,7 @@ export default defineEval({
   reporters?: Reporter[];
   timeoutMs?: number;
   metadata?: Record<string, unknown>;
+  async setup(sandbox, ctx) { /* task fixture + progress/diagnostic */ },
   async test(t) { /* interactions + assertions */ },
 });
 ```
@@ -111,6 +112,38 @@ export default defineEval({
 
 详见 [Fixtures](/zh/guides/fixtures)。
 
+## 从 Eval 报告长步骤和诊断
+
+`setup` 用于这条 Eval 的任务夹具。第二个参数绑定到 eval setup 阶段；`test(t)` 里的反馈绑定到 eval run 阶段：
+
+```ts
+export default defineEval({
+  async setup(sandbox, ctx) {
+    ctx.progress({ message: "安装 fixture 依赖" });
+    await sandbox.runCommand("npm", ["install"]);
+  },
+
+  async test(t) {
+    t.progress({ message: "上传隐藏测试", current: 1, total: 2 });
+    await t.sandbox.uploadDirectory("../fixtures/project");
+
+    const preflight = await inspectFixture();
+    if (preflight.usedFallback) {
+      t.diagnostic({
+        code: "fixture-check-degraded",
+        level: "warning",
+        message: "Fixture 预检使用了备用检查器",
+        data: { checker: preflight.checker },
+      });
+    }
+
+    await t.send("完成任务");
+  },
+});
+```
+
+`progress` 只更新运行中的短期状态，不进入结果。`diagnostic` 会写进当前 Attempt 的 `result.json`，但不会代替断言或自动改变判定：业务结论仍用 `t.check` / `t.require` / gate；基础设施无法继续时抛出异常。
+
 ## 命名约定
 
 <CardGroup cols={2}>

package/docs-site/zh/guides/ci-integration.mdx

@@ -11,9 +11,15 @@ Evals 应该和测试一样进入 CI。它们能在 PR 阶段发现 agent 行为
 默认情况下，只要存在失败的 gate，[NiceEval](https://niceeval.com/) 将以非零状态码退出。CI 中通常使用 `--strict`，让失败更明确。
 
 ```bash
-npx niceeval exp ci --strict
+NICEEVAL_LANG=en npx niceeval exp ci \
+  --output ci \
+  --strict \
+  --json .niceeval/ci-summary.json \
+  --junit .niceeval/junit.xml
 ```
 
+CI profile 不输出 ANSI、spinner 或动态表格。日志使用单一有序 stdout 流，只追加 start、低频 heartbeat、失败/错误、diagnostic 和最终 result；通过的 Attempt 不逐条打印。
+
 ## GitHub Actions 示例
 
 ```yaml
@@ -32,8 +38,12 @@ jobs:
           node-version: 22
           cache: npm
       - run: npm ci
-      - run: npx niceeval exp ci --strict
+      - run: >-
+          npx niceeval exp ci --output ci --strict
+          --json .niceeval/ci-summary.json
+          --junit .niceeval/junit.xml
         env:
+          NICEEVAL_LANG: en
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
@@ -52,18 +62,19 @@ jobs:
   </Step>
 </Steps>
 
-## JUnit reporter
-
-```ts
-import { defineConfig } from "niceeval";
-import { Console, JUnit } from "niceeval/reporters";
+## JSON、JUnit 和结构化错误
 
-export default defineConfig({
-  reporters: [Console(), JUnit(".niceeval/junit.xml")],
-});
+```text
+niceeval: start total=24 configs=3 concurrency=10 reused=18
+niceeval: errored locator=@12h8m4k1 eval=fixtures/button experiment=ci/codex phase=sandbox.create reason="E2B sandbox allocation failed after 5 attempts"
+niceeval: result=failed passed=23 failed=0 errored=1 reused=18 duration=128s
+niceeval: json=.niceeval/ci-summary.json
+niceeval: junit=.niceeval/junit.xml
 ```
 
-CI 可以上传 JUnit XML，让失败出现在测试报告 UI 里。想把结果同时上报到 Braintrust 这类实验平台，见 [Reporter 上报](./reporters)。
+退出码是第一层红绿信号；JSON、JUnit 和结果快照是完整机器接口，日志行只用于搜索和 annotation。`errored` 行带 locator、eval/experiment 身份、已知时的正式 phase，以及一层 `reason` 摘要。详细 cause、stack 和 diagnostics 保存在 Attempt 的 `result.json`，可在保留 artifact 后运行 `niceeval show @<locator>` 回顾。
+
+CLI 显式要求的 JSON/JUnit 和默认 results artifact 都是 required 输出：写入失败必须让 job 判红，不能只留 warning 后退出 0。想把结果同时上报到 Braintrust 这类实验平台，见 [Reporter 上报](./reporters)。
 
 ## 只检查发现
 
@@ -80,7 +91,7 @@ npx niceeval list
 ## 控制并发
 
 ```bash
-npx niceeval exp ci --max-concurrency 2
+npx niceeval exp ci --output ci --max-concurrency 2
 ```
 
 标准 GitHub-hosted runner 上，sandbox eval 并发不宜过高。远程 HTTP eval 可以按服务限流能力调高。

package/docs-site/zh/guides/connect-your-agent.mdx

@@ -101,12 +101,12 @@ npx niceeval exp my-bot refund # 只跑 ID 以 refund 开头的
 npx niceeval view              # 本地查看器里看结果
 ```
 
-**跑通的样子**：终端里每条 eval 一行判定，末尾汇总 `N passed, N failed`；`npx niceeval view` 里能看到每条 eval 逐轮的输入、事件和评分明细。
+**跑通的样子**：人在终端运行时会看到一个动态 dashboard，完成和排队数量只在原位更新；失败、错误和 warning 会永久留在上方。结束时只打印摘要、失败 locator 和结果路径。`npx niceeval view` 里能看到每条 Eval 逐轮的输入、事件和评分明细。
 
 没跑通时，按报错的位置分三类排查：
 
 - **`fetch` 直接抛错**（连接被拒等）：应用没起来，或 `send` 里的 URL 不对——先用 `curl` 对那个接口发一次同样的请求确认。
-- **`t.succeeded()` 没过、本轮判定是 failed**：请求发出去了但应用回了非 2xx。在 `send` 里用 `ctx.log()` 打印响应体，`niceeval view` 的本轮日志里能看到。
+- **`t.succeeded()` 没过、本轮判定是 failed**：请求发出去了，但应用返回的 Turn 是 `failed`。把协议中的失败映射到 `Turn.status` 或标准 `error` event；需要额外保留的有限上下文用 `ctx.diagnostic(...)`，不要打印完整响应体。
 - **只有内容断言没过**：接入本身已经通了——在 `view` 里对照 `t.reply` 的实际值，调断言或调应用。
 
 到这里接入已经完成：文本断言和 judge 评分都能用了。想要更多断言（工具、多轮、审批流），见文末的增量地图。
@@ -173,7 +173,33 @@ export default defineExperiment({
 | `flags` | experiment 的 `flags` | 原样转发（请求体、header 都行），应用按参数切换变体 |
 | `telemetry` | 配置了 OTel 接入时出现 | 只碰 `headers`：每轮新的 W3C `traceparent`，spread 进请求头。接收端点每次运行都一样，在 `defineConfig` 里固定、应用启动时指向它，不从 send 传——见 [OTel 接入](/zh/guides/connect-otel) |
 | `session` | 运行器（每条会话线一份） | 会话续接与 HITL 停轮现场的存取器都在它上面：`history()`、`id` / `capture()`、`hold()` / `take()`，见[写 send](/zh/guides/write-send) |
-| `log(msg)` | 运行器 | 写进本轮日志，`niceeval view` 里可见 |
+| `progress(update)` | 运行器（绑定当前 `agent.run`） | 报告 Turn/tool 的短期状态；Human dashboard 可显示，结果不保存 |
+| `diagnostic(input)` | 运行器（绑定当前 `agent.run`） | 保存协议退化、响应不完整等 warning/error；可由 locator 下钻回顾 |
+
+### Adapter 里的进度、诊断和致命错误
+
+```ts
+async send(input, ctx) {
+  ctx.progress({ message: "等待上游模型" });
+  const response = await callAgent(input, { signal: ctx.signal });
+
+  if (response.eventsIncomplete) {
+    ctx.diagnostic({
+      code: "incomplete-event-stream",
+      level: "warning",
+      message: "上游响应缺少工具结果事件",
+      data: { requestId: response.requestId },
+      dedupeKey: `incomplete-event-stream:${response.requestId}`,
+    });
+  }
+
+  return toTurn(response);
+}
+```
+
+`progress` 是可覆盖的短期状态；`diagnostic` 是运行结束后仍能回顾的有界记录。两者都不能指定 phase 或输出流，也不会自动改变 `Turn.status` 或 Attempt 判定。连接失败、解析无法继续等基础设施错误应抛出异常；正常收到的被测 Agent 失败通过 `Turn.status: "failed"` 表达。
+
+终端只显示错误的一层摘要和 locator。完整 code、message、cause、stack 与 diagnostics 在 `result.json` 中，使用 `niceeval show @<locator>` 查看。OTel trace 只补充调用关系和耗时，不是错误记录的前提。
 
 同一个 agent 对着本地和生产分别跑，就是两个 experiment 文件、两份工厂参数：
 

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

@@ -8,19 +8,19 @@ description: "一份报告就是一个报告文件：官方宿主打开结果、
 
 一份报告就是一个报告文件。你不用打开结果目录、不用写渲染代码、不用起自己的应用：`niceeval show` / `niceeval view` 本体就是宿主——替你打开结果、把数据注入进来，你用官方组件和 `Row` / `Col` 摆版面，写完把文件路径递给 `--report`，终端和网页两扇门就都认它——官方的证据室深链、`--run` 历史切换、静态导出，自定义报告全部原样享有。
 
-## view 的默认报告也是一份报告定义
+## show / view 的默认报告也是一份报告定义
 
-`niceeval view` 不传 `--report` 时渲染的默认报告不是私有实现，而是 `niceeval/report` 公开导出的一个值，也可显式传给 `niceeval show --report`：
+`niceeval show` / `view` 不传 `--report` 时渲染的默认报告不是私有实现，而是 `niceeval/report` 公开导出的一个值：
 
 ```ts
-import { CostPassRateComparison } from "niceeval/report";
+import { ExperimentComparison } from "niceeval/report";
 ```
 
-`niceeval view` 缺省选择 `CostPassRateComparison`：一张成本 × 通过率散点图加一张实验明细表，没有私有数据通道。裸 `niceeval show` 使用更适合终端的 Attempt 索引；显式自定义报告（包括这份 definition）仍可由两个宿主按同一双面协议渲染。
+`ExperimentComparison` 先按 experiment id 的父目录切成可比组，再为每组分别计算成本 × 端到端成功率散点图和实验明细表。`compare/bub` 与 `compare/codex` 可以同图，`dev-e2b/bub` 必须在另一个组；顶层 experiment 各自成为单例组。网页持有全部组并一次聚焦一组；终端命中多组时只列索引和单组查看命令，命中单组时才展开详情。两面都不会生成跨组总榜。
 
 |  | 网页（人看） | 终端（agent 和你看） |
 | --- | --- | --- |
-| 官方默认 | 分析报告 | Attempt 索引 |
+| 官方默认 | 分组比较报告（网页面） | 同一分组比较报告（文本面） |
 | 自定义摆法 | `niceeval view --report reports/exam.tsx` | `niceeval show --report reports/exam.tsx` |
 
 四个格子是同一个宿主。自定义只有三个层次，逐层深入：
@@ -39,16 +39,13 @@ import { CostPassRateComparison } from "niceeval/report";
 // reports/exam.tsx —— 一份定义，两扇门共用
 import {
   defineReport, Col, Section,
-  MetricScatter, ExperimentList, EvalList, AttemptList, Scoreboard,
-  costUSD, passRate,
+  ExperimentComparison, Scoreboard,
 } from "niceeval/report";
 
 export default defineReport(async ({ selection }) => {
-  const experiments = await ExperimentList.data(selection);
   return (
     <Col>
-      <MetricScatter selection={selection} points="experiment" series="agent" x={costUSD} y={passRate} />
-      <ExperimentList items={experiments} />
+      <ExperimentComparison data={await ExperimentComparison.data(selection)} />
       <Section title="考试成绩单">
         <Scoreboard data={await Scoreboard.data(selection, { rows: "agent", subjects: "evalGroup" })} />
       </Section>
@@ -72,7 +69,7 @@ niceeval view --report reports/exam.tsx    # 网页：同一棵树走网页面
 
 页面里的每个组件都是**双面**的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据。实体列表按 experiment → Eval → Attempt 展示事实；指标表、矩阵、条形图、成绩单、散点图、趋势图和差异表展示聚合值。完整清单见[报告组件](/zh/guides/report-components)。网页面的实体、格子和点深链到 Attempt 详情，终端面印出对应的 `niceeval show <eval id>` 下钻命令。
 
-默认报告没有特权：它就是上面导出的那个值 `CostPassRateComparison`，正文是一张 `MetricScatter` 加一份 `ExperimentList`。你的报告和它同级；需要相同摆法时 import 同样的公开组件，不需要就不摆。
+默认报告没有特权：它就是上面导出的 `ExperimentComparison`。你的报告和它同级；需要同样的“按目录分组、组内比较”摆法就直接引用它，不需要就不摆。自己直接组合 `MetricScatter` / `ExperimentList` 时，通用组件只消费你传入的数据，不会自动分组；把跨组 Selection 传进去就表示你明确要做跨组分析。
 
 ## 排版：Row 与 Col 在两个面都成立
 
@@ -105,17 +102,17 @@ codex  78.0/100   40/50    38/50    │  codex  80%   $0.51
 
 想把实验按目录前缀分组、每组顶部摆一块紧凑统计（通过率、experiment/eval 数、failed/errored、总成本、最后运行时间），用官方组件 `GroupSummary`。它的计算函数 `GroupSummary.data` 只吃一份已经收窄好的 Selection——不管你怎么分组，把对应组的 Selection 传进去，就是同一套折叠口径（eval 级折叠计票、null-safe 总成本、组内最后运行时间的最大值），不是另一套近似公式。
 
-常见的分法是按 experiment id 的目录前缀（`compare/bub-low` 属于组 `compare`，顶层实验不属于任何组）；用 `Selection.filter` 收窄出每组的 Selection，就能一组摆一块：
+常见的分法是按 experiment id 的目录前缀（`compare/bub-low` 属于组 `compare`，顶层实验以自己的完整 id 形成单例组）；用 `Selection.filter` 收窄出每组的 Selection，就能一组摆一块：
 
 ```tsx
 // reports/groups.tsx —— 按 experiment id 前缀分组，每组顶部摆一块统计
 import { defineReport, Col, Section, GroupSummary } from "niceeval/report";
 import type { Snapshot } from "niceeval/report";
 
-// experiment id 的目录前缀当组名：顶层实验（id 无 "/"）不属于任何组。
-function groupOf(snapshot: Snapshot): string | undefined {
+// experiment id 的完整父路径当组名；顶层 experiment 各自成为单例组。
+function groupOf(snapshot: Snapshot): string {
   const parts = snapshot.experimentId.split("/");
-  return parts.length > 1 ? parts.slice(0, -1).join("/") : undefined;
+  return parts.length > 1 ? parts.slice(0, -1).join("/") : snapshot.experimentId;
 }
 
 export default defineReport(async ({ selection }) => {
@@ -126,9 +123,7 @@ export default defineReport(async ({ selection }) => {
         groups.map(async (key) => {
           const scoped = selection.filter((s) => groupOf(s) === key);
           const summary = <GroupSummary data={await GroupSummary.data(scoped)} />;
-          return key === undefined ? summary : (
-            <Section key={key} title={key}>{summary}</Section>
-          );
+          return <Section key={key} title={key}>{summary}</Section>;
         }),
       )}
     </Col>
@@ -153,7 +148,7 @@ latest 2026-07-01T11:30:00Z
 // reports/golf.tsx —— code-golf：谁写出能用的代码，谁写得短
 import {
   defineReport, Col, MetricTable,
-  defineMetric, passRate, costUSD,
+  defineMetric, endToEndPassRate, costUSD,
 } from "niceeval/report";
 
 // 项目自己的口径：只比能用的代码的行数
@@ -166,8 +161,8 @@ const codeLines = defineMetric({
   async value(attempt) {
     const diff = await attempt.diff();
     if (!diff) return null;
-    return Object.values(diff.generatedFiles)
-      .reduce((n, src) => n + src.split("\n").length, 0);
+    return Object.keys(diff.files)
+      .reduce((sum, path) => sum + (diff.get(path) ?? "").split("\n").length, 0);
   },
 });
 
@@ -175,8 +170,8 @@ export default defineReport(async ({ selection }) => (
   <Col>
     <MetricTable data={await MetricTable.data(selection, {
       rows: "agent",
-      columns: [passRate, codeLines, costUSD],
-      sort: passRate,
+      columns: [endToEndPassRate, codeLines, costUSD],
+      sort: endToEndPassRate,
     })} />
   </Col>
 ));
@@ -195,7 +190,7 @@ codex   80%         355 lines    $0.51
 
 `label` 可以是一份文案，也可以按语言给：`label: { en: "Code lines", "zh-CN": "代码行数" }`——查看器界面切语言时，按语言给的 label 跟着切；只给一份就两种语言都用它。指标算出来的数字本身不分语言。
 
-内置指标里 `passRate` / `costUSD` / `durationMs` / `tokens` 只读 attempt 自带的判定、用量这些字段，任何一份结果目录都算得出。`turns`（agent 的总轮次）不一样，它读 `attempt.o11y()`——这份数据发布时不一定随行，`copySnapshots` 要显式把 `"o11y"` 加进 `artifacts` 才带得上（见[结果数据 API](/zh/guides/results-data)的「发布」一节），漏了就渲染成 `—`，不是 0。自己写的指标只要读了 `o11y()` / `diff()` 这类 artifact（就像上面 `codeLines` 读 `attempt.diff()`），发布前都要过一遍同样的检查。
+内置指标里 `endToEndPassRate` / `taskPassRate` / `executionReliability` / `costUSD` / `durationMs` / `tokens` 只读 Attempt 自带的判定、用量这些字段，任何一份结果目录都算得出。没有限定词的“成功率”使用 `endToEndPassRate`：passed 记 1，failed 和 errored 都记 0。`taskPassRate` 只在形成可信判定的样本上衡量答题质量，errored 不参与；展示它时应明确写“可判定任务通过率”，不能简称成功率。要区分答题质量和执行问题，把 `endToEndPassRate`、`taskPassRate`、`executionReliability` 三列并排。`turns`（Agent 的总轮次）不一样，它读 `attempt.o11y()`——这份数据 `copySnapshots` 缺省会随行，但如果发布脚本显式给了 `artifacts` 列表又没把 `"o11y"` 写进去，它就不在发布根里（见[结果数据 API](/zh/guides/results-data)的「发布」一节），指标渲染成 `—`，不是 0。自己写的指标只要读了 `o11y()` / `diff()` 这类 artifact（就像上面 `codeLines` 读 `attempt.diff()`），发布前都要过一遍同样的检查。
 
 ## 换分组：三种维度
 
@@ -221,7 +216,7 @@ const vendor: Dimension = {
 
 <MetricTable data={await MetricTable.data(selection, {
   rows: vendor,
-  columns: [passRate, costUSD],
+  columns: [endToEndPassRate, costUSD],
 })} />
 ```
 
@@ -248,7 +243,7 @@ export default defineExperiment({
 <MetricLine data={await MetricLine.data(selection, {
   x: flag("latencyMs", { label: "Simulated latency", unit: "ms" }),
   series: flag("agents", { label: (v) => `${v} agents` }),
-  y: passRate,
+  y: endToEndPassRate,
 })} />
 ```
 
@@ -264,12 +259,12 @@ export default defineExperiment({
 
 ```tsx
 // reports/cost-board.tsx
-import { defineReport, Col, Table, MetricTable, costUSD, passRate } from "niceeval/report";
+import { defineReport, Col, Table, MetricTable, costUSD, endToEndPassRate } from "niceeval/report";
 
 export default defineReport(async ({ selection }) => {
   const board = await MetricTable.data(selection, {
     rows: "agent",
-    columns: [passRate, costUSD],
+    columns: [endToEndPassRate, costUSD],
   });
   return (
     <Col>
@@ -283,7 +278,7 @@ export default defineReport(async ({ selection }) => {
           key: r.key,
           cells: {
             agent: r.key,
-            pass: r.cells[passRate.name].display,
+            pass: r.cells[endToEndPassRate.name].display,
             // 缺数据交 null,组件渲染成 —;不要自己填 0
             cost: r.cells[costUSD.name].value === null ? null : r.cells[costUSD.name].display,
           },
@@ -324,7 +319,7 @@ codex       80%   $0.51
 // reports/passbars.tsx
 import {
   defineReport, defineComponent, Col, Style, MetricTable,
-  bar, padEnd, stringWidth, passRate,
+  bar, padEnd, stringWidth, endToEndPassRate,
 } from "niceeval/report";
 
 interface BarRow { key: string; ratio: number | null; display: string }
@@ -356,11 +351,11 @@ const PassBars = defineComponent<{ rows: BarRow[] }>({
 });
 
 export default defineReport(async ({ selection }) => {
-  const board = await MetricTable.data(selection, { rows: "agent", columns: [passRate] });
+  const board = await MetricTable.data(selection, { rows: "agent", columns: [endToEndPassRate] });
   const rows = board.rows.map((r) => ({
     key: r.key,
-    ratio: r.cells[passRate.name].value,   // 格子键锚在指标对象上,不裸写字符串
-    display: r.cells[passRate.name].display,
+    ratio: r.cells[endToEndPassRate.name].value,   // 格子键锚在指标对象上,不裸写字符串
+    display: r.cells[endToEndPassRate.name].display,
   }));
   return (
     <Col>
@@ -400,4 +395,4 @@ niceeval view --report reports/exam.tsx --out site
 
 ## 界线：内置命令不长配置
 
-一次只渲染一份报告，`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里，随文件一起递入，宿主不为它们长任何注册面。不传 `--report` 时渲染的就是内置的 `CostPassRateComparison`，你的报告和它是同级实现。
+一次只渲染一份报告，`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里，随文件一起递入，宿主不为它们长任何注册面。不传 `--report` 时渲染的就是内置的 `ExperimentComparison`，你的报告和它是同级实现。

package/docs-site/zh/guides/dataset-fanout.mdx

@@ -1,14 +1,14 @@
 ---
 title: "数据驱动测试（dataset fan-out）：用多份数据运行同一套 eval"
 sidebarTitle: "数据驱动测试"
-description: "从 .eval.ts 文件导出数组，将一套 eval 逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。"
+description: "从 .eval.ts 文件导出数组或 keyed record，将一套 eval 逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。"
 ---
 
 数据驱动测试（dataset fan-out）适合大量结构相同、输入不同的测试。例如 SQL 生成、意图分类、检索问答和工具选择。
 
 ## 工作原理
 
-一个 `.eval.ts` 文件默认导出数组：
+没有外部业务 ID 时，一个 `.eval.ts` 文件默认导出数组：
 
 ```ts
 import { defineEval } from "niceeval";
@@ -41,6 +41,25 @@ sql/0001
 
 序号零填充，便于稳定引用和过滤。
 
+数据源已经带稳定 case、issue 或 benchmark ID 时，默认导出 keyed record：
+
+```ts
+export default Object.fromEntries(
+  rows.map((row) => [
+    row.issueId,
+    defineEval({
+      description: row.title,
+      async test(t) {
+        await t.send(row.prompt);
+        t.succeeded();
+      },
+    }),
+  ]),
+);
+```
+
+文件是 `evals/swelancer.eval.ts`、key 是 `15193` 时，ID 就是 `swelancer/15193`。key 必须是一个非空路径片段：不能是 `.` / `..`，不能含 `/`、`\\` 或控制字符。NiceEval 按 key 字典序发现，数据源返回顺序变化不会改变运行顺序。
+
 ## 从 YAML / JSON 加载
 
 ```ts
@@ -63,8 +82,11 @@ cases:
 # 运行整个数据集
 npx niceeval exp local sql
 
-# 只运行第一个 case
+# 只运行第一个数组 case
 npx niceeval exp local sql/0000
+
+# 运行一个 keyed case
+npx niceeval exp local swelancer/15193
 ```
 
 ## 数据集 vs 独立文件

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

@@ -0,0 +1,57 @@
+---
+title: "保留沙箱现场排查问题"
+sidebarTitle: "保留沙箱现场"
+description: "用 --keep-sandbox 把失败 Attempt 的沙箱保留成可随时唤醒的现场，用 niceeval sandbox enter 进去手动排查，用 sandbox list / stop 查看和清理。"
+---
+
+沙箱默认在每个 Attempt 结束后销毁，排查依据是落盘的 artifact：`niceeval show` 能看到判定、断言、diff 和事件流。大多数问题到这里就够了——完整的排查路线见 [Debug 手册](/zh/guides/debugging)。
+
+但有些问题只能进活的环境里看：
+
+- **环境起不来**——setup 阶段装依赖失败、agent CLI 启动不了。这时 agent 还没开始跑，事件流是空的，最快的办法是进沙箱手动重跑一遍安装命令。
+- **改动落在 `git diff` 之外**——全局装了什么包、`$HOME` 下写了什么配置、`PATH` 实际是什么，artifact 里没有。
+- **重跑太慢**——冷启动加安装要几分钟，想逐条验证猜测时，留着现场比每次重跑快得多。
+
+## 跑的时候保留现场
+
+```bash
+npx niceeval exp local onboarding/tool-first --keep-sandbox        # 等价 --keep-sandbox=failed
+npx niceeval exp local onboarding/tool-first --keep-sandbox=all    # 通过的也保留
+```
+
+`--keep-sandbox` 是 `niceeval exp` 的运行参数，两档：`failed`（缺省值）保留判定为 `failed` 或 `errored` 的 Attempt（包括超时打断的）；`all` 连通过的也保留——调 setup 钩子、核对通过环境的真实状态时用它，不用故意弄挂一条 eval。不带这个参数时全部销毁。
+
+运行结束后，摘要里会列出保留了哪些沙箱、怎么进去：
+
+```text
+Kept sandboxes (1)
+  @1x7f3q9k  onboarding/tool-first #1  errored  docker · a3f9c2d1
+             enter: niceeval sandbox enter a3f9c2d1
+Stop them with: niceeval sandbox stop --all
+```
+
+每行给三样东西：Attempt 定位符（用 `niceeval show @1x7f3q9k` 看落盘证据）、沙箱实例 id、进入现场的命令。保留下来的沙箱不会一直跑着烧资源——Docker 容器停在磁盘上，E2B 微 VM 暂停计费，Vercel 保存文件系统。`niceeval sandbox enter` 会先唤醒再进入，在 workdir 打开 shell；退出 shell 后现场自动回到休眠（想让它保持运行，加 `--leave-running`）。进去之后就是这次 Attempt 跑完时的环境，可以手动执行命令、翻文件、复现失败。
+
+## 查看和清理
+
+保留下来的沙箱逐条记录在 `.niceeval/sandboxes/` 里，用 `niceeval sandbox` 管理：
+
+```bash
+niceeval sandbox list              # 列出保留的沙箱和现场状态
+niceeval sandbox enter a3f9c2d1    # 唤醒并进入；退出后自动回到休眠
+niceeval sandbox stop a3f9c2d1     # 销毁指定沙箱（id 可以只写唯一前缀）
+niceeval sandbox stop --all        # 全部销毁
+```
+
+`stop` 是幂等的：沙箱已经不在了（手动删过、云端过期）不算错误，只会把记录移掉并说明。如果 provider 销毁失败，命令会保留记录并返回错误，方便稍后重试，不会把仍活着的资源从列表里藏掉。忘了清也有提醒——下次运行开始时，如果还有上次保留的沙箱，会打一行提示。
+
+## 各 Provider 的差别
+
+- **Docker**：保留 = 容器停在磁盘上（不占内存，重启 Docker 也还在），进入时自动启动。容器不会自己消失，是唯一需要主动清理的 provider。除了 `niceeval sandbox stop`，也可以用 `docker ps -a -f label=niceeval.keep-candidate=true` 直接核对。
+- **E2B**：保留 = 暂停微 VM——文件和内存整体保存，暂停期间停止计费、无限期保留，进入时自动恢复。
+- **Vercel Sandbox**：保留 = 停止微 VM——文件系统保存、之后可恢复，但内存状态不保留，唤醒后进程要重新启动；超过 provider 的保留期限后 `niceeval sandbox list` 标成 `expired`。
+- **自定义 Provider**：`defineSandbox` 产出的 provider 不支持留存，因为事后的 `sandbox stop` 不加载用户配置，无法在新进程里安全找回自定义销毁函数。
+
+## 边界
+
+保留的沙箱只用来排查，不能续跑或重新评分；判定、断言、diff 这些结论仍以 artifact 为准。查看 artifact 的方法见[查看结果](/zh/guides/viewing-results)。