niceeval 0.6.1 → 0.7.0

package/docs-site/zh/{guides → how-to}/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 → how-to}/connect-otel.mdx

@@ -4,11 +4,11 @@ sidebarTitle: "OTel 接入"
 description: "把应用已经在发的 OTel span 也发给 NiceEval 一份，niceeval view 里就有每轮的调用瀑布图。断言不从这里来——接好 send 那一刻断言就齐了。"
 ---
 
-先说清这条接入**不**改变什么：断言。`t.calledTool`、`t.maxTokens`、耗时这些判定的依据，全部来自你的 adapter 在 `send` 里返回的 `Turn`（`events` + `usage`）——接好 send 的那一刻，全套断言就齐了，和 OTel 没有关系（见[接入你的 agent](/zh/guides/connect-your-agent)）。
+先说清这条接入**不**改变什么：断言。`t.calledTool`、`t.maxTokens`、耗时这些判定的依据，全部来自你的 adapter 在 `send` 里返回的 `Turn`（`events` + `usage`）——接好 send 的那一刻，全套断言就齐了，和 OTel 没有关系（见[接入你的 agent](/zh/how-to/connect-your-agent)）。
 
 OTel 接入买到的是另一样东西：**`niceeval view` 里的调用瀑布图**。应用内部每次模型调用、每次工具执行、各自的耗时和 token，按轮铺开成一条时间线——失败的 eval 为什么失败、慢的轮次慢在哪一步，经常一眼就在瀑布图里。
 
-如果你的应用已经在发 OTel trace——AI SDK 的 telemetry、LangGraph 的 LangSmith 导出、OpenLLMetry / OpenInference 自动埋点，或自己按 GenAI 语义埋的点——那瀑布图的数据你已经在生产了：让应用把 span 也发给 [NiceEval](https://niceeval.com/) 一份即可，应用代码一行不改，仍是无侵入（见 [Tier](/zh/concepts/tier)）。
+如果你的应用已经在发 OTel trace——AI SDK 的 telemetry、LangGraph 的 LangSmith 导出、OpenLLMetry / OpenInference 自动埋点，或自己按 GenAI 语义埋的点——那瀑布图的数据你已经在生产了：让应用把 span 也发给 [NiceEval](https://niceeval.com/) 一份即可，应用代码一行不改，仍是无侵入（见 [Tier](/zh/explanation/tier)）。
 
 ## 原理（一段话）
 
@@ -197,12 +197,12 @@ export default defineAgent({
 
 ## 边界
 
-- **断言相关的一切都在 send**。想断工具调用，把它映射进 `events`（官方转换器或手写映射，见[写 send](/zh/guides/write-send)）；想断 usage，`send` 返回里带上。不存在"span 里有、events 里没有，于是断言看 span"的路径。
-- **多轮会话、HITL 不归 span 管**。span 没有"等人输入"语义，会话续接也是应用协议的事——这两样照常在 `send` 里做（会话续接见[写 send](/zh/guides/write-send)，HITL 概念见 [HITL](/zh/concepts/hitl)）。
+- **断言相关的一切都在 send**。想断工具调用，把它映射进 `events`（官方转换器或手写映射，见[写 send](/zh/how-to/write-send)）；想断 usage，`send` 返回里带上。不存在"span 里有、events 里没有，于是断言看 span"的路径。
+- **多轮会话、HITL 不归 span 管**。span 没有"等人输入"语义，会话续接也是应用协议的事——这两样照常在 `send` 里做（会话续接见[写 send](/zh/how-to/write-send)，HITL 概念见 [HITL](/zh/explanation/hitl)）。
 - **收不到 span 会有提示**。整个 run 0 span 通常是端点没接上（env 没注入、服务没重启），[NiceEval](https://niceeval.com/) 会在日志里提示；瀑布图为空，断言照常判。
 
 ## 相关阅读
 
-- [接入你的 agent](/zh/guides/connect-your-agent) —— 断言从哪来：send 的事件映射。
-- [写 send](/zh/guides/write-send) —— 手写 adapter 的完整教程，第六步就是本页的 adapter 侧接法。
+- [接入你的 agent](/zh/how-to/connect-your-agent) —— 断言从哪来：send 的事件映射。
+- [写 send](/zh/how-to/write-send) —— 手写 adapter 的完整教程，第六步就是本页的 adapter 侧接法。
 - [事件流参考](/zh/reference/events) —— 断言消费的事件长什么样。

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

@@ -14,11 +14,11 @@ description: "接入的全景：写一个 adapter、配一个 experiment、跑
   <Card title="AI SDK 应用" icon="bolt" href="/zh/reference/builtin-agents">
     用 Vercel AI SDK（`useChat` 后端）写的应用：内置 `uiMessageStreamAgent` 无侵入接它的 HTTP 接口，零映射、含 HITL，有完整的 before/after 示例。不用读本文。
   </Card>
-  <Card title="Coding agent CLI" icon="terminal" href="/zh/guides/sandbox-agent">
+  <Card title="Coding agent CLI" icon="terminal" href="/zh/how-to/sandbox-agent">
     评 claude-code / codex / bub 这类改文件的 coding agent：用内置 sandbox agent。
   </Card>
   <Card title="其它 AI Agent" icon="plug">
-    自研 agent loop、LangGraph / OpenAI Agents SDK 应用、已部署 agent：手写 send（本文 + [写 send](/zh/guides/write-send)）。应用已埋 OTel 的话顺手接上，`niceeval view` 多一张调用瀑布图（[OTel 接入](/zh/guides/connect-otel)）。
+    自研 agent loop、LangGraph / OpenAI Agents SDK 应用、已部署 agent：手写 send（本文 + [写 send](/zh/how-to/write-send)）。应用已埋 OTel 的话顺手接上，`niceeval view` 多一张调用瀑布图（[OTel 接入](/zh/how-to/connect-otel)）。
   </Card>
 </CardGroup>
 
@@ -51,7 +51,7 @@ export default defineAgent({
 });
 ```
 
-URL 先写死没关系——怎么把它从 experiment 传进来，见下文[「参数怎么进」](#参数怎么进：experiment-声明，adapter-消费)。`send` 的完整契约（`TurnInput` / `AgentContext` / `Turn` 各字段）见 [Adapter](/zh/concepts/adapter)。
+URL 先写死没关系——怎么把它从 experiment 传进来，见下文[「参数怎么进」](#参数怎么进：experiment-声明，adapter-消费)。`send` 的完整契约（`TurnInput` / `AgentContext` / `Turn` 各字段）见 [Adapter](/zh/explanation/adapter)。
 
 就算 agent runtime 和 eval 在同一个代码库里，也照样走 HTTP，不要把 `fetch` 换成进程内的函数直调：
 
@@ -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 评分都能用了。想要更多断言（工具、多轮、审批流），见文末的增量地图。
@@ -171,9 +171,35 @@ export default defineExperiment({
 | `signal` | 运行器（超时与取消） | 挂到发出的每个请求上 |
 | `model` | experiment 的 `model` | 应用接口收模型选择就随请求转发；不收就忽略 |
 | `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` 里可见 |
+| `telemetry` | 配置了 OTel 接入时出现 | 只碰 `headers`：每轮新的 W3C `traceparent`，spread 进请求头。接收端点每次运行都一样，在 `defineConfig` 里固定、应用启动时指向它，不从 send 传——见 [OTel 接入](/zh/how-to/connect-otel) |
+| `session` | 运行器（每条会话线一份） | 会话续接与 HITL 停轮现场的存取器都在它上面：`history()`、`id` / `capture()`、`hold()` / `take()`，见[写 send](/zh/how-to/write-send) |
+| `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 文件、两份工厂参数：
 
@@ -196,7 +222,7 @@ npx niceeval exp local
 npx niceeval exp prod
 ```
 
-不要把 URL 放进 CLI 位置参数——experiment 名之后的位置参数只用于过滤 eval ID。experiment 的完整字段（`runs`、`budget`、并发、`sandbox`）见[写实验](/zh/guides/write-experiment)。
+不要把 URL 放进 CLI 位置参数——experiment 名之后的位置参数只用于过滤 eval ID。experiment 的完整字段（`runs`、`budget`、并发、`sandbox`）见[写实验](/zh/how-to/write-experiment)。
 
 ## 之后的增量：一张地图
 
@@ -204,13 +230,13 @@ npx niceeval exp prod
 
 | 想解锁什么 | 给 adapter 加什么 | 去哪看 |
 |---|---|---|
-| 工具断言（`calledTool` / `toolOrder` / 负断言） | 把应用返回映射成标准事件流 | [写 send](/zh/guides/write-send)、[事件流参考](/zh/reference/events) |
-| 多轮对话、`t.newSession()` 隔离 | 接上 `ctx.session`：`history()` 或 `id` + `capture()` | [写 send](/zh/guides/write-send) |
-| 审批流（HITL，人工介入） | 停轮返回 `waiting` + `input.requested`，回答轮续跑 | [HITL](/zh/concepts/hitl) |
-| `niceeval view` 的调用瀑布图 | 应用把 OTel span 发给 NiceEval（不影响断言） | [OTel 接入](/zh/guides/connect-otel) |
-| feature A/B 对比 | 应用把变体暴露成 `flags` 可切换的配置 | [Tier](/zh/concepts/tier)、[写实验](/zh/guides/write-experiment) |
+| 工具断言（`calledTool` / `toolOrder` / 负断言） | 把应用返回映射成标准事件流 | [写 send](/zh/how-to/write-send)、[事件流参考](/zh/reference/events) |
+| 多轮对话、`t.newSession()` 隔离 | 接上 `ctx.session`：`history()` 或 `id` + `capture()` | [写 send](/zh/how-to/write-send) |
+| 审批流（HITL，人工介入） | 停轮返回 `waiting` + `input.requested`，回答轮续跑 | [HITL](/zh/explanation/hitl) |
+| `niceeval view` 的调用瀑布图 | 应用把 OTel span 发给 NiceEval（不影响断言） | [OTel 接入](/zh/how-to/connect-otel) |
+| feature A/B 对比 | 应用把变体暴露成 `flags` 可切换的配置 | [Tier](/zh/explanation/tier)、[写实验](/zh/how-to/write-experiment) |
 
-这些增量落在哪一档、各档买到什么，见 [Tier](/zh/concepts/tier)。
+这些增量落在哪一档、各档买到什么，见 [Tier](/zh/explanation/tier)。
 
 ## 参考实现
 
@@ -218,9 +244,9 @@ npx niceeval exp prod
 
 ## 相关阅读
 
-- [官方适配器一览](/zh/guides/official-adapters) —— 被测对象能直接用官方 Adapter 时，Sandbox / 非 Sandbox 各有哪些、配置项怎么写。
-- [写 send](/zh/guides/write-send) —— 手写 Adapter 的完整教程：七步递进，从发一条消息到 HITL、OTel、flags。
-- [Adapter](/zh/concepts/adapter) —— `send` 的契约：`TurnInput` / `AgentContext` / `Turn` 逐字段。
-- [OTel 接入](/zh/guides/connect-otel) —— 把应用的 span 也发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
-- [Tier](/zh/concepts/tier) —— 三档接入各投入什么、买到什么。
-- [写实验](/zh/guides/write-experiment) —— `defineExperiment` 的完整字段。
+- [官方适配器一览](/zh/reference/official-adapters) —— 被测对象能直接用官方 Adapter 时，Sandbox / 非 Sandbox 各有哪些、配置项怎么写。
+- [写 send](/zh/how-to/write-send) —— 手写 Adapter 的完整教程：七步递进，从发一条消息到 HITL、OTel、flags。
+- [Adapter](/zh/explanation/adapter) —— `send` 的契约：`TurnInput` / `AgentContext` / `Turn` 逐字段。
+- [OTel 接入](/zh/how-to/connect-otel) —— 把应用的 span 也发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
+- [Tier](/zh/explanation/tier) —— 三档接入各投入什么、买到什么。
+- [写实验](/zh/how-to/write-experiment) —— `defineExperiment` 的完整字段。

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

@@ -4,23 +4,23 @@ sidebarTitle: "自定义报告"
 description: "一份报告就是一个报告文件：官方宿主打开结果、注入数据，双面组件让同一份自定义报告同时用于 niceeval show 与 niceeval view。"
 ---
 
-[查看结果](/zh/guides/viewing-results)讲「用」：官方两扇门 `niceeval show`（终端）和 `niceeval view`（网页）怎么看。本页讲「写」：官方摆法不够时，怎么写一份自己的报告——考试成绩单、代码行数榜、质量 × 成本 frontier。
+[查看结果](/zh/how-to/viewing-results)讲「用」：官方两扇门 `niceeval show`（终端）和 `niceeval view`（网页）怎么看。本页讲「写」：官方摆法不够时，怎么写一份自己的报告——考试成绩单、代码行数榜、质量 × 成本 frontier。
 
 一份报告就是一个报告文件。你不用打开结果目录、不用写渲染代码、不用起自己的应用：`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>
@@ -62,7 +59,7 @@ 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` 是宿主替你挑好的那份结果。挑选规则是：对每个实验、每道 eval，取该实验历史运行里最新的那次判定——只按前缀重跑了一部分 eval，其余 eval 的判定从更早的运行补齐，不会因为一次局部重跑就整体退回某一份残缺快照。默认报告吃的就是这份 `selection`，快照在 `selection.snapshots`，挑选提醒在 `selection.warnings`。默认挑法不合口径时，拿 `results` 自己挑，手工挑的 `Snapshot[]` 数组同样能喂给每个组件。
+注入的上下文只有两样，全部是[结果数据 API](/zh/reference/results-data) 的原语，宿主没有私有通道：`results` 就是 `openResults(".niceeval")` 的返回（实验、历次快照、attempt 级 `diff()`、`trace()` 都在上面）；`selection` 是宿主替你挑好的那份结果。挑选规则是：对每个实验、每道 eval，取该实验历史运行里最新的那次判定——只按前缀重跑了一部分 eval，其余 eval 的判定从更早的运行补齐，不会因为一次局部重跑就整体退回某一份残缺快照。默认报告吃的就是这份 `selection`，快照在 `selection.snapshots`，挑选提醒在 `selection.warnings`。默认挑法不合口径时，拿 `results` 自己挑，手工挑的 `Snapshot[]` 数组同样能喂给每个组件。
 
 报告文件里有两种数据形态。实体列表的 `.data(selection)` 返回普通数组：`ExperimentListItem[]`、`EvalListItem[]`、`AttemptListItem[]`。报告作者用 JavaScript `.filter()` / `.slice()` 决定展示哪些实体，再把数组作为 `items` 传给列表；组件不藏另一套过滤 DSL。指标图形和汇总组件收算好的 `data`；其中 `MetricScatter` 也提供 `selection` 简写，由宿主在渲染前计算。计算后的组件只渲染传入数据，不碰结果目录。
 
@@ -70,9 +67,9 @@ niceeval view --report reports/exam.tsx    # 网页：同一棵树走网页面
 
 命令行的范围先作用在挑选上，报告拿到的就是收窄到这个范围后的 `selection`：位置参数的 eval id 前缀收窄 Selection 覆盖的 eval（覆盖提醒的分母同样收窄到范围内），`--run` 把结果根换成指定目录，`--experiment` 让 Selection 只留该实验。`--history` 与 `--report` 互斥——趋势在报告里用 `exp.snapshots` 自己摆；证据切面（`--eval` / `--execution` / `--diff`）只看证据，不渲染报告。
 
-页面里的每个组件都是**双面**的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据。实体列表按 experiment → Eval → Attempt 展示事实；指标表、矩阵、条形图、成绩单、散点图、趋势图和差异表展示聚合值。完整清单见[报告组件](/zh/guides/report-components)。网页面的实体、格子和点深链到 Attempt 详情，终端面印出对应的 `niceeval show <eval id>` 下钻命令。
+页面里的每个组件都是**双面**的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据。实体列表按 experiment → Eval → Attempt 展示事实；指标表、矩阵、条形图、成绩单、散点图、趋势图和差异表展示聚合值。完整清单见[报告组件](/zh/reference/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/reference/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,
           },
@@ -302,7 +297,7 @@ codex       80%   $0.51
 克劳德        —       —
 ```
 
-列宽按**终端显示宽度**算：一个汉字占 2 列，所以中文 agent 名、中文题目名都不会把表撕歪。`align: "right"` 让数字列右对齐。格子给 `null` 就渲染 `—`，不补 0。行上带 `locator` 就多出一列 attempt，网页面点进证据室、终端面把 locator 交给 `niceeval show`。完整字段见[报告组件](/zh/guides/report-components)的「表格」一节。
+列宽按**终端显示宽度**算：一个汉字占 2 列，所以中文 agent 名、中文题目名都不会把表撕歪。`align: "right"` 让数字列右对齐。格子给 `null` 就渲染 `—`，不补 0。行上带 `locator` 就多出一列 attempt，网页面点进证据室、终端面把 locator 交给 `niceeval show`。完整字段见[报告组件](/zh/reference/report-components)的「表格」一节。
 
 ### 不是表：`defineComponent` 加文本排版函数
 
@@ -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>
@@ -394,10 +389,10 @@ codex   ████████████████░░░░  80%
 niceeval view --report reports/exam.tsx --out site
 ```
 
-产物是纯静态文件：你的报告页是首页，证据室（transcript、trace、代码视图）在同一站内，报告里的每个数字点进去就是证据。组件不 hydrate；页面内联一小段官方脚本，提供表头排序、行过滤、图表悬停这些浏览操作，浏览器禁用 JS 时页面仍完整可读。交给任何静态托管即可。CI 上没有 `.niceeval/` 时，先用 `copySnapshots` 把快照瘦身进仓库再导出，流程见[查看结果](/zh/guides/viewing-results#导出与静态托管)。
+产物是纯静态文件：你的报告页是首页，证据室（transcript、trace、代码视图）在同一站内，报告里的每个数字点进去就是证据。组件不 hydrate；页面内联一小段官方脚本，提供表头排序、行过滤、图表悬停这些浏览操作，浏览器禁用 JS 时页面仍完整可读。交给任何静态托管即可。CI 上没有 `.niceeval/` 时，先用 `copySnapshots` 把快照瘦身进仓库再导出，流程见[查看结果](/zh/how-to/viewing-results#导出与静态托管)。
 
 双面组件的网页面就是普通 React 组件，`data` 函数就是普通 TS 函数——想把某一块指标表嵌进已有的内部面板，import 组件喂数据就行。那是零件的复用，不是另一套报告系统：报告的家在官方宿主。算数据与渲染分离部署时（CI 落 JSON、另一个应用 fetch），两侧锁同一个 niceeval 版本是硬要求——组件数据不带版本戳，兼容性跟随包版本。
 
 ## 界线：内置命令不长配置
 
-一次只渲染一份报告，`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里，随文件一起递入，宿主不为它们长任何注册面。不传 `--report` 时渲染的就是内置的 `CostPassRateComparison`，你的报告和它是同级实现。
+一次只渲染一份报告，`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里，随文件一起递入，宿主不为它们长任何注册面。不传 `--report` 时渲染的就是内置的 `ExperimentComparison`，你的报告和它是同级实现。

package/docs-site/zh/{guides → how-to}/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 → how-to}/experiments.mdx

@@ -35,7 +35,7 @@ export default defineExperiment({
 npx niceeval exp compare-models   # 把同组各 model 并排出报告
 ```
 
-这样每个配置独立成文件：可命名、可 diff、可单独 review，"这一组就是对照"在文件结构上就讲清楚了。
+这样每个配置独立成文件：可命名、可 diff、可单独 review，"这一组就是对照"在文件结构上就讲清楚了。默认 `niceeval show` / `view` 也沿用这条边界：只把同一文件夹下的 experiment 放进同一张成本 × 端到端成功率图和实验表，不同文件夹分别显示。
 
 某一格结果反常、需要单独复现时，用该配置的完整 id（`组/文件名`）精确只跑这一格，不用先跑完整组：
 
@@ -43,18 +43,18 @@ npx niceeval exp compare-models   # 把同组各 model 并排出报告
 npx niceeval exp compare-models/gpt-5.4
 ```
 
-`defineExperiment` 的字段怎么写、`flags` 怎么透传到 adapter，见[写实验](/zh/guides/write-experiment)。
+`defineExperiment` 的字段怎么写、`flags` 怎么透传到 adapter，见[写实验](/zh/how-to/write-experiment)。
 
 ## 适合比较什么
 
 - 不同 Adapters。
 - 不同模型（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-providers#环境钩子)。
+- 不同 sandbox provider。
+- 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` 钩子里，一个变体一个 experiment 文件，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 - 同一任务的 pass@N。
 
-Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/concepts/tier)。
+Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/explanation/tier)。
 
 ## 查看结果
 
@@ -67,6 +67,13 @@ api-validation   claude-code             pass@3 = 1/3 (33%)    mean 41s
 
 除了 pass rate，还应该看平均耗时、token、成本和失败类型。
 
+```bash
+npx niceeval show --experiment compare-models
+npx niceeval view
+```
+
+`show --experiment` 按路径段匹配 id 前缀，所以组名会选中组内所有配置，但不会误中名字只是在字符串上相似的另一个组。`view` 默认加载完整结果，直接在页面里选组；`--experiment` 对它只是可选的启动时收窄。
+
 ## 设计 experiment 的建议
 
 - 保持 eval 集合稳定，避免比较时混入新变量。