niceeval 0.6.1 → 0.6.2

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)。

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

@@ -0,0 +1,210 @@
+---
+title: "排查失败与复盘历史运行"
+sidebarTitle: "Debug 手册"
+description: "一份按场景组织的排查手册：断言失败怎么定位、环境错误怎么进沙箱、agent 改了什么怎么看、旧的运行怎么翻出来复盘——每一步都有命令顺序和输出示例。"
+---
+
+跑完一次 `niceeval exp`，失败的 Attempt 都带一个 `@` 开头的定位符（如 `@1qrdcfq8`）。它出现在运行摘要、CI 日志和报告里，定位符本身不会过期——只要 `.niceeval/` 里对应的结果快照还在，今天的定位符下周还能用同一条命令打开同一次 Attempt。所有排查都从它开始。
+
+## 第一步永远是 `niceeval show @<定位符>`
+
+不带任何参数打开 Attempt，第一页就是为排查设计的：判定、失败的断言、耗时分布、改动概览，以及下一步可用的命令。
+
+```text
+$ niceeval show @1qrdcfq8
+@1qrdcfq8 · memory/swelancer-manager-proposals · dev-e2b/codex-e2b · failed
+snapshot 2026-07-12T10:08:29.361Z · attempt 1 · 50.0s · 58.5k tokens · $0.05
+
+assertions: 3 passed · 1 gate failed
+eval source: evals/memory/swelancer-manager-proposals.eval.ts · sha256:ee33b9c4…
+
+failures:
+  gate · Issue 15193: selected proposal matches the one maintainers accepted
+    assertion: equals(4)
+    expected: 4
+    received: 1
+    source: evals/memory/swelancer-manager-proposals.eval.ts:40:11
+
+execution: 12 events · 0 skill loads · 7 tool calls · 4 AI messages
+timing: sandbox.queue 0.2s · sandbox.create 5.6s · sandbox.setup 3.5s · agent.setup 12.1s ·
+        eval.run 26.3s · workspace.diff 0.3s · scoring.evaluate 1.4s · teardown +0.8s
+
+changes: 2 files changed by agent · M manager_decisions.json · A notes/decision-log.md
+
+available:
+  niceeval show @1qrdcfq8 --eval
+  niceeval show @1qrdcfq8 --execution
+  niceeval show @1qrdcfq8 --timing
+  niceeval show @1qrdcfq8 --diff
+```
+
+看这一页先回答一个问题：**是 agent 答错了（`failed`），还是环境根本没跑起来（`errored`）？** 两种情况的排查路线完全不同。
+
+## 场景一：断言失败（failed）——agent 跑完了，但结果不对
+
+排查顺序是「哪条断言挂了 → agent 当时做了什么 → 它到底改了什么」。
+
+**1. 把断言放回源码。** `--eval` 显示运行时保存的那份 eval 源码（不是你工作区里可能已经改过的版本），失败的断言直接标在对应行上；`t.send(...)` 的调用行标出它产生的那一轮——轮标签（`s1/t1`，与 `--execution` / `--timing` 用同一套）、这轮成没成、花了多久：
+
+```text
+$ niceeval show @1qrdcfq8 --eval
+21✓     await t.send("Review the proposals and record your decision…");
+    s1/t1 · completed · 22.4s
+38      for (const [issue, label] of Object.entries(expected)) {
+39        await t.group(`Issue ${issue}: selected proposal matches…`, async () => {
+40✗         t.check(Number(decisions[issue]?.selected_proposal_id), equals(label.selected_proposal_id));
+    gate · Issue 15193 · equals(4) · expected 4 · received 1
+41        });
+42      }
+```
+
+**2. 看 agent 当时做了什么。** `--execution` 把这次 Attempt 的对话按时间线展开——用户消息、assistant 回复、每次工具调用的入参和结果：
+
+```text
+$ niceeval show @1qrdcfq8 --execution
+TURN s1/t1 · completed · 22.4s · 12.4k tok · $0.02
+  USER
+    Review the proposals and record your decision for each issue…
+
+  ASSISTANT
+    I'll inspect the task layout and the decision format first…
+
+  TOOL · command_execution  +12.8s · 1.3s
+    input
+      /bin/bash -lc 'cat tasks/15193/proposals.md'
+    result · completed · exit 0
+      Proposal 1: …
+```
+
+对话按轮分段，每轮头行给出编号（`s1/t1`）、状态、耗时和用量——这个编号和 `--diff`、`--timing` 里的轮次标签是同一套，能互相对照。
+
+**3. 看它到底改了什么。** `--diff` 只显示 **agent 自己改动的文件**——你上传的起始文件、跑完后写入的验证材料不会混在里面，所以列表里的每一行都真的是 agent 干的：
+
+```text
+$ niceeval show @1qrdcfq8 --diff
+2 files changed by agent
+  M manager_decisions.json   +6 -2    s1/t1, s1/t2
+  A notes/decision-log.md    +18      s1/t2
+
+single file: niceeval show @1qrdcfq8 --diff=manager_decisions.json
+```
+
+行尾的 `s1/t1` 表示这个文件是在第几轮对话里被改的，能和 `--execution` 的轮次对上。要看单个文件的逐行改动，用 `=` 连写文件路径：
+
+```text
+$ niceeval show @1qrdcfq8 --diff=manager_decisions.json
+M manager_decisions.json · changed in s1/t1, s1/t2
+@@ -1,5 +1,7 @@
+ {
+-  "15193": { "selected_proposal_id": 1 },
++  "15193": { "selected_proposal_id": 4 },
+```
+
+到这里通常能下结论：是任务描述有歧义、agent 理解错了，还是断言本身写得太死。
+
+**要看文件本身，而不只是改动？** 落盘的证据刻意不保存整个工作区——`--diff` 只有 agent 改过的文件，agent 该写没写的文件、你上传的起始材料、setup 装出来的东西都不在里面。想看它们的实际内容，进活现场：重跑这一条 eval 加 `--keep-sandbox`（`failed` 的 Attempt 同样会保留，不只是环境错误），用下面场景二的方式进沙箱，workdir 里就是这次跑完时的完整文件树。
+
+## 场景二：环境错误（errored）——agent 根本没跑起来
+
+`errored` 的第一页不列断言，而是列出错误发生在哪个阶段、什么原因：
+
+```text
+$ niceeval show @12h8m4k1
+@12h8m4k1 · memory/agent-029-use-cache · compare/claude-e2b · errored
+
+error:
+  phase: sandbox.create
+  code: sandbox-rate-limit
+  message: E2B sandbox allocation failed after 5 attempts
+  cause: RateLimitError · too many concurrent sandboxes
+
+execution: unavailable (attempt failed before telemetry was configured)
+timing: sandbox.queue 1.2s · sandbox.create 2m 6s ✗ failed here
+```
+
+`phase` 直接告诉你死在哪一步，而且决定了下一步走哪条路：
+
+**`sandbox.create` 失败——沙箱根本没创建出来，没有现场可留。** 这类错误（配额、限流、凭据、镜像 / 模板不存在）在你自己的机器和账号侧排查：核对 API key 和配额、降低 `--max-concurrency`、确认镜像 / 模板名。示例里的 rate-limit 就属于这类，重跑加 `--keep-sandbox` 只会原地再死一次。
+
+**`sandbox.setup` / `agent.setup` / `eval.run` 失败——沙箱活过，值得留现场。** 装依赖失败、agent CLI 起不来、跑到一半超时，这类问题事件流往往是空的，落盘证据帮不上忙，最快的办法是留住现场进去手动重跑一遍出错的命令：
+
+```bash
+# 只重跑这一条 eval，失败时保留沙箱
+npx niceeval exp compare memory/agent-029 --keep-sandbox
+```
+
+```text
+Kept sandboxes (1)
+  @18c1m2qx  memory/agent-029-use-cache #1  errored  docker · a3f9c2d1
+             enter: niceeval sandbox enter a3f9c2d1
+Stop them with: niceeval sandbox stop --all
+```
+
+`niceeval sandbox enter a3f9c2d1` 会唤醒现场并在 workdir 打开 shell——手动执行安装命令看真实报错、翻 `$HOME` 下的配置、检查 `PATH`，这些都在 artifact 之外，只有活现场能回答；退出 shell 后现场自动回到休眠，不白烧资源。保留策略、各 provider 的差别见[保留沙箱现场](/zh/guides/debug-sandbox)。
+
+## 查看和清理留下的沙箱
+
+保留下来的沙箱不会一直烧资源：Docker 容器停驻在磁盘上，E2B 微 VM 暂停计费，进入时自动唤醒。用 `niceeval sandbox` 管理：
+
+```text
+$ niceeval sandbox list
+ID        PROVIDER  STATE            FROM
+a3f9c2d1  docker    dormant          memory/agent-029-use-cache #1 · errored · @18c1m2qx · 2026-07-14 15:02
+            enter: niceeval sandbox enter a3f9c2d1
+9f21c07b  vercel    expired          onboarding/tool-first #2 · failed  · @1x7f3q8a · 2026-07-14 14:31
+            expired 2026-07-14 14:36 — remove with: niceeval sandbox stop 9f21c07b
+```
+
+`dormant` 是「睡着但随时能进」，`expired` 是「现场已经没了，只剩记录」。排查完记得清理：
+
+```bash
+niceeval sandbox stop a3f9c2d1     # id 可以只写唯一前缀
+niceeval sandbox stop --all
+```
+
+## 场景三：复盘旧的运行
+
+每次运行都会在 `.niceeval/<实验>/<时间戳>/` 下留一份完整的结果快照，判定、断言、事件流、diff 都在里面，**不会被下一次运行覆盖**。复盘有三个入口：
+
+**用旧定位符直接打开。** 从上周的终端记录、CI 日志或报告里复制 `@` 定位符，`niceeval show @<定位符>` 照常工作，上面的 `--eval` / `--execution` / `--diff` 全部可用——包括那份运行时的 eval 源码，哪怕你后来把 eval 改了。
+
+**按实验回看当前水位。** 不记得定位符时，从实验入手：
+
+```bash
+niceeval show --experiment compare/bub        # 这个实验每道题现在的判定
+niceeval show memory/swelancer --experiment compare/bub   # 收窄到某道题
+```
+
+列表里每道题、每次 Attempt 都带定位符，接着往深处钻就回到上面的场景一 / 场景二。
+
+**在浏览器里翻。** 复盘一批失败、对比多次 Attempt 时，网页比终端顺手：
+
+```bash
+niceeval view
+```
+
+首页是成本 × 通过率总览和实验对比表；每个 Attempt 的详情页有判定、断言、完整时间树、对话、trace 和 diff，还有「Copy fix prompt」按钮——把失败整理成一段可以直接交给 coding agent 的修复提示词。报告里的 Attempt 深链和 `show` 用同一套定位符。
+
+**打开归档或别人发来的结果。** 结果目录是自包含的——从 CI 下载的、同事拷给你的、发布到静态站前生成的目录，都能直接指过去：
+
+```bash
+niceeval show --run tmp/ci-artifacts/results
+niceeval view --run site-data/run
+```
+
+一个注意点：如果本地清理过旧快照目录，之后的运行里「沿用上次结果」的条目会找不到原始证据（显示为缺失）。要长期归档某次运行，先用 [`copySnapshots`](/zh/guides/results-data) 复制出一份再删。
+
+## 速查：症状 → 命令
+
+| 症状 | 命令顺序 |
+|---|---|
+| 断言挂了，不知道为什么 | `show @loc` → `show @loc --eval` |
+| 想知道 agent 当时做了什么 | `show @loc --execution` |
+| 想确认 agent 改了哪些文件 | `show @loc --diff` → `--diff=<path>` |
+| 哪一步慢 / 超时死在哪 | `show @loc`（看 `timing:` 行）→ `show @loc --timing` |
+| 沙箱创建就失败（配额 / 凭据 / 镜像） | `show @loc` 看 error 的 code 与 cause → 查账号配额、核对凭据、降 `--max-concurrency`（没有现场可留） |
+| 装依赖失败、CLI 起不来、跑一半超时 | 重跑该 eval 加 `--keep-sandbox` → `niceeval sandbox enter <id>` |
+| 想看文件实际内容（agent 没改的、起始材料、`$HOME`） | 重跑加 `--keep-sandbox`（failed 也留）→ `sandbox enter` 进 workdir 看 |
+| 留了哪些沙箱、清理 | `sandbox list` → `sandbox stop <id>` / `--all` |
+| 复盘上周那次失败 | 翻出旧定位符 → `show @loc`；不记得就 `show --experiment <实验>` |
+| 一批失败一起看 | `niceeval view` → Attempt 详情 → Copy fix prompt |

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

@@ -35,7 +35,7 @@ export default defineExperiment({
 npx niceeval exp compare-models   # 把同组各 model 并排出报告
 ```
 
-这样每个配置独立成文件：可命名、可 diff、可单独 review，"这一组就是对照"在文件结构上就讲清楚了。
+这样每个配置独立成文件：可命名、可 diff、可单独 review，"这一组就是对照"在文件结构上就讲清楚了。默认 `niceeval show` / `view` 也沿用这条边界：只把同一文件夹下的 experiment 放进同一张成本 × 端到端成功率图和实验表，不同文件夹分别显示。
 
 某一格结果反常、需要单独复现时，用该配置的完整 id（`组/文件名`）精确只跑这一格，不用先跑完整组：
 
@@ -50,8 +50,8 @@ npx niceeval exp compare-models/gpt-5.4
 - 不同 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/guides/sandbox-providers#环境钩子)。
 - 同一任务的 pass@N。
 
 Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/concepts/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 集合稳定，避免比较时混入新变量。