niceeval 0.6.1 → 0.7.0

package/docs-site/zh/{guides → reference}/report-components.mdx

@@ -4,14 +4,15 @@ sidebarTitle: "报告组件"
 description: "报告文件里能摆的全部官方双面组件：每个组件回答什么问题、怎么调用、网页面长什么样、终端字符输出长什么样。"
 ---
 
-报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/guides/custom-reports)）。每个组件的数据算法挂在它自己身上，组件名后打个点就找到，算和画永远配对。本页逐个列出官方组件：它展示哪一层数据、在报告里怎么调用、终端输出长什么样。
+报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/how-to/custom-reports)）。每个组件的数据算法挂在它自己身上，组件名后打个点就找到，算和画永远配对。本页逐个列出官方组件：它展示哪一层数据、在报告里怎么调用、终端输出长什么样。
 
 ## 名称与用途
 
-英文术语描述组件形态，API 名是代码里的导出名。组件分三类：实体列表逐项展示 experiment、Eval 或 Attempt；汇总组件概括整批 Selection；指标图形把指定维度聚合成值。三个实体列表的 `.data(selection)` 都返回普通数组，报告作者先用 JavaScript `.filter()` 收窄，再把 `items` 交给组件。过滤条件不藏在组件里。中文正文首次提到时用“中文名（`API 名`）”，后续可以只写中文名或 `API 名`。
+英文术语描述组件形态，API 名是代码里的导出名。组件分四类：默认组合件按可比组组织完整比较；实体列表逐项展示 experiment、Eval 或 Attempt；汇总组件概括整批 Selection；指标图形把指定维度聚合成值。三个实体列表的 `.data(selection)` 都返回普通数组，报告作者先用 JavaScript `.filter()` 收窄，再把 `items` 交给组件。过滤条件不藏在组件里。中文正文首次提到时用“中文名（`API 名`）”，后续可以只写中文名或 `API 名`。
 
 | 分类 | 中文名 | English | API | 主展示单位 |
 | --- | --- | --- | --- | --- |
+| 组合 | 实验组比较 | Experiment comparison | `ExperimentComparison` | 按 experiment 父目录分组；每组独立的摘要、散点与实验列表 |
 | 汇总 | 运行总览 | Run overview | `RunOverview` | 一批 Selection；汇总其中的 experiment、Eval 和 Attempt |
 | 汇总 | 组摘要 | Group summary | `GroupSummary` | 收窄后的一批 Selection；汇总一组 experiment 和 Eval |
 | 实体列表 | 实验列表 | Experiment list | `ExperimentList` | 每项一个 experiment；展开到该 experiment 的 Eval |
@@ -93,7 +94,19 @@ description: "报告文件里能摆的全部官方双面组件：每个组件回
 
 表比终端宽时先压最宽的左对齐列（按显示宽度折行），右对齐列不折行——数字折行读不了；压到下限仍放不下，就从右侧丢列，并在表下如实报丢了几列，不静默截断。
 
-指标表、指标矩阵、成绩单和成对差异表的终端面就建在 `Table` 上，所以你的表和官方的表用的是同一把尺子。表格之外的形态要自己排字符时，用[自定义报告](/zh/guides/custom-reports)「换形态」一节里那套文本排版函数。
+指标表、指标矩阵、成绩单和成对差异表的终端面就建在 `Table` 上，所以你的表和官方的表用的是同一把尺子。表格之外的形态要自己排字符时，用[自定义报告](/zh/how-to/custom-reports)「换形态」一节里那套文本排版函数。
+
+## 实验组比较（`ExperimentComparison`）
+
+`niceeval show` / `view` 不传 `--report` 时使用的默认组合件。它先按 experiment id 的完整父目录分组，再为每组分别计算组摘要、成本 × 端到端成功率散点和实验列表：
+
+```tsx
+<ExperimentComparison data={await ExperimentComparison.data(selection)} />
+```
+
+`compare/bub` 与 `compare/codex` 属于 `compare`，可以横向比较；`dev-e2b/bub` 属于另一个组，不会进入同一张图、同一条 series 或同一张表。顶层 experiment 没有父目录时，以自己的完整 id 形成单例组。网页面持有完整组索引并一次聚焦一组，切组不重新读取 Selection；终端面命中多组时只显示组索引与单组查看命令，命中单组时才展开详情。浏览器禁用 JS 时，每组仍以独立 `<details>` 保留完整内容。
+
+这个分区只属于默认组合件。下面的 `MetricScatter`、`MetricTable` 和 `ExperimentList` 都忠实消费调用方传入的数据；自定义报告把跨组 Selection 传给它们，就表示明确选择跨组分析。
 
 ## 运行总览（`RunOverview`）
 
@@ -126,13 +139,15 @@ Pass rate 73.3% · 2 experiments · 15 evals · failed 3 · errored 1 · $0.93
 latest 2026-07-09T10:00:00Z
 ```
 
-通过率是 eval 级折叠计票口径：同一 eval 的多轮 attempt 先折成一个判定（任一轮通过则算通过，否则取最严重的），`passed / (passed + failed + errored)`，`skipped` 不进分母——与页头 `RunOverview` 那个两级聚合、带 partial credit 的 `passRate` 是两码事，两者服务不同问题：`GroupSummary` 回答「这组题过了几道」，`RunOverview` 回答「整体质量几分」，不要互相替代。`evals` 按 `experimentId + eval id` 的完整身份键去重——组里两个 experiment 各自的同名 eval 算两道题，不会被误合并成一道。`errored` 为 0 时这一段省略，但 `verdicts.errored` 这个数据字段本身永远在，省略只发生在渲染层。`totalCostUSD` 是组内可测 attempt 成本求和，一个 attempt 都没报成本时是 `null`，两面都渲染缺数据而不是 `$0`。
+通过率是 eval 级折叠计票口径：同一 eval 的多轮 attempt 先折成一个判定（任一轮通过则算通过，否则取最严重的），`passed / (passed + failed + errored)`，`skipped` 不进分母。页头 `RunOverview` 使用 `endToEndPassRate` 的两级聚合：先算同一道题各 Attempt 的端到端成功率，再跨题平均。两者的聚合粒度不同，但都会让 errored 降低成功率。`GroupSummary` 回答「这组题最终过了几道」，`RunOverview` 回答「每次实际运行交付成功结果的比例」，不要互相替代。`evals` 按 `experimentId + eval id` 的完整身份键去重——组里两个 experiment 各自的同名 eval 算两道题，不会被误合并成一道。`errored` 为 0 时这一段省略，但 `verdicts.errored` 这个数据字段本身永远在，省略只发生在渲染层。`totalCostUSD` 是组内可测 attempt 成本求和，一个 attempt 都没报成本时是 `null`，两面都渲染缺数据而不是 `$0`。
 
 组摘要是普通的公开组件，`GroupSummary.data` 是普通的公开计算函数——想在自己的报告里按目录前缀分组、每组摆一块，按上面的写法收窄 Selection 再调它就行。
 
 ## 实验列表（`ExperimentList`）
 
-每项固定代表一个 experiment。主行显示 experiment id、agent、model、flags、Eval 判定构成、通过率、Tokens、成本和耗时；展开后显示这个 experiment 的 Eval 列表。它不接受列配置——这是 experiment 的诊断视图，不是通用指标表。
+每项固定代表一个 experiment。主行显示 experiment id、agent、model、flags、Eval 判定构成、通过率、Tokens、成本和耗时；展开后显示这个 experiment 的 Eval 列表。Eval 父行显示折叠判定、Attempt 数、平均耗时和平均成本；下面每个 Attempt 再显示该轮自己的失败摘要。失败内容只出现一次，不会在 Eval 与唯一 Attempt 上重复。它不接受列配置——这是 experiment 的诊断视图，不是通用指标表。默认 `ExperimentComparison` 每次只把一个可比组的 items 交给它；组件本身不猜组边界。
+
+默认比较已经用组名作面板 / 段落标题，所以组内每行的 experiment 标签会去掉这层文件夹前缀，只显示 id 末段（和同组散点的点标签一致），不在每行重复文件夹名；完整 id 仍是排序、着色和身份的依据。独立使用 `ExperimentList`、不告诉它相对哪个组时，显示完整 id。
 
 ```tsx
 const experiments = await ExperimentList.data(selection);
@@ -142,22 +157,19 @@ const experiments = await ExperimentList.data(selection);
 />
 ```
 
-`niceeval show` 每个 experiment 输出一行汇总，每个 Eval 只占一行。Attempt ID 后的证据位告诉 AI 能读什么，不展开重复命令：
+`niceeval show` 先输出 experiment 比较表，再按 experiment 展开 Eval / Attempt 父子表。Eval 父行给题级平均值，Attempt 子行给这一轮的失败摘要和 locator：
 
 ```text
-compare/bub-gpt-5.4 · bub · gpt-5.4
-  pass 87% · 13 passed / 1 failed / 1 errored · 42 attempts · 4m 12s · $0.42
-  ✓ algebra/quadratic   @12f9k3aq✓ @141bm7cx✓   18s avg · $0.02 avg
-  ✗ weather/brooklyn    @1k2m9qrs✗ @1nx4dpqr✗ @19vq2jex✗   gate calledTool("get_weather")
-  ! fixtures/button     @1c3h6twx!   command timed out after 120s
-
-compare/codex-gpt-5.4 · codex · gpt-5.4
-  pass 80% · 12 passed / 3 failed · 45 attempts · 5m 03s · $0.51
-  ✓ algebra/quadratic   @1d8p4kwz✓   16s · $0.02
-  ✗ algebra/matrix      @1e2j7mxa✗ @1f5r9nab✗ @1g4w8pcd✗   gate equals("42")
-  ✗ weather/brooklyn    @1h6t3vbe✗ @1j9m2qfg✗ @1k7c5rxh✗   gate calledTool("get_weather")
-
-inspect: niceeval show @<id> [--eval|--execution|--diff]
+Experiment      Model     Agent   Avg duration   E2E pass rate   Result                 Tokens   Est. cost
+bub-gpt-5.4     gpt-5.4   bub     41.0s          50%             1 passed / 1 failed     42k      $0.08
+
+bub-gpt-5.4
+Status      Eval / Attempt       Result                                  Duration    Cost
+✓ passed    algebra/quadratic                                             18.0s avg   $0.02 avg
+  ✓         └─ @12f9k3aq         —                                       18.0s       $0.02
+✗ failed    weather/brooklyn                                              42.0s avg   $0.04 avg
+  ✗         ├─ @1k2m9qrs         calledTool("get_weather") · no calls    41.0s       $0.04
+  ✗         └─ @1nx4dpqr         calledTool("get_weather") · no calls    43.0s       $0.04
 ```
 
 locator 由 `experimentId + snapshot.startedAt + evalId + attempt index` 的不可变身份确定，复制或发布结果后保持不变。宿主在当前结果根解析 locator；不存在或发生冲突时直接报错，不回退到“最新一次”。`@` 前缀让它与 Eval ID 前缀选择器无歧义。
@@ -166,7 +178,7 @@ locator 由 `experimentId + snapshot.startedAt + evalId + attempt index` 的不
 
 ## Eval 列表（`EvalList`）
 
-每项固定代表一个 `experimentId + evalId`，因为同一个 Eval 跑在两个 experiment 上是两条不同结果。主行显示判定、Attempt 数、聚合分数、成本、耗时和失败原因；展开后显示这个 Eval 的 Attempt 列表。
+每项固定代表一个 `experimentId + evalId`，因为同一个 Eval 跑在两个 experiment 上是两条不同结果。主行显示判定、Attempt 数、聚合分数、平均成本和平均耗时；展开后显示这个 Eval 的 Attempt 列表，由每个 Attempt 行显示该轮自己的失败原因。Eval 主行不挑某一轮的失败原因冒充题级结论。
 
 ```tsx
 const evals = await EvalList.data(selection);
@@ -196,7 +208,7 @@ inspect: niceeval show @<id> [--eval|--execution|--diff]
 
 ## Attempt 列表（`AttemptList`）
 
-每项固定代表一个 Attempt，显示 experiment、Eval、Attempt 序号、判定、耗时、成本、失败断言、error、Judge 评语和证据链接。它既能列失败证据，也能列通过样本，不把 verdict 过滤写死在组件名里。
+每项固定代表一个 Attempt，显示 experiment、Eval、Attempt 序号、判定、耗时、成本、失败断言、结构化 error 的一层摘要、Judge 评语和证据链接。diagnostics、cause 和 stack 留给 locator 下钻详情，避免比较列表被基础设施日志撑开。它既能列失败证据，也能列通过样本，不把 verdict 过滤写死在组件名里。
 
 ```tsx
 const attempts = await AttemptList.data(selection, { redact });
@@ -206,7 +218,7 @@ const attempts = await AttemptList.data(selection, { redact });
 />
 ```
 
-`niceeval show` 每项完整输出一个 Attempt，不再折叠到 Eval 汇总。这里已经是叶子层，只在末尾给一条与该 Attempt 可用证据对应的模板：
+`niceeval show` 每项完整输出一个 Attempt，不折叠到 Eval 汇总。这里已经是叶子层，只在末尾给一条与该 Attempt 可用证据对应的模板：
 
 ```text
 ✗ @1k2m9qrs · weather/brooklyn · compare/bub-gpt-5.4 · 41s · $0.04
@@ -222,7 +234,7 @@ inspect: niceeval show @<id> [--eval|--execution|--diff]
 (3 more not shown · showing 20 of 23)
 ```
 
-发布前要消毒 error、断言 detail 或 Judge 评语时，把 `redact` 交给 `.data()`；要展示哪些 Attempt，过滤返回的 `AttemptListItem[]`。`limit` 也由报告作者在数组上用 `.slice(0, 20)` 表达，截断时把原始数量交给组件的 `total`，组件据此显示“还有 n 项未展示”，不静默截断。
+要在页面显示前遮蔽 error message/cause/stack、diagnostic message/data、断言 detail 或 Judge 评语，把 `redact` 交给 `.data()`；稳定 code、lifecycle operation、experiment、Eval 和 locator 不改。它只影响这份组件数据，管不到发布目录里的 artifact 文件——发布数据集的消毒用 [`copySnapshots` 的 `redact` 选项](/zh/reference/results-data)。要展示哪些 Attempt，过滤返回的 `AttemptListItem[]`。`limit` 也由报告作者在数组上用 `.slice(0, 20)` 表达，截断时把原始数量交给组件的 `total`，组件据此显示“还有 n 项未展示”，不静默截断。
 
 ## 指标表（`MetricTable`）
 
@@ -231,8 +243,8 @@ inspect: niceeval show @<id> [--eval|--execution|--diff]
 ```tsx
 <MetricTable data={await MetricTable.data(selection, {
   rows: "agent",
-  columns: [passRate, codeLines, costUSD],
-  sort: passRate,
+  columns: [endToEndPassRate, codeLines, costUSD],
+  sort: endToEndPassRate,
 })} />
 ```
 
@@ -251,7 +263,7 @@ codex   80% 12/15   355 lines    $0.51
 行 × 列两个维度、格子里一个指标，回答「哪道题谁挂了」。稀疏渲染：没有样本的格子空着，不编数。
 
 ```tsx
-<MetricMatrix data={await MetricMatrix.data(selection, { rows: "eval", columns: "agent", cell: passRate })} />
+<MetricMatrix data={await MetricMatrix.data(selection, { rows: "eval", columns: "agent", cell: endToEndPassRate })} />
 ```
 
 ```text
@@ -273,7 +285,7 @@ next: niceeval show geometry/area
 <MetricBars data={await MetricBars.data(selection, {
   rows: "evalGroup",        // 一组条 = 一个科目/benchmark
   columns: "agent",         // 一根条 = 一个 agent
-  cell: passRate,
+  cell: endToEndPassRate,
 })} />
 ```
 
@@ -317,11 +329,11 @@ codex   71.0/100   40/50          31/50 (1 missing)
   points="experiment"       // 每个点 = 一个配置的聚合
   series="agent"            // 同 agent 的档位连成线
   x={costUSD}
-  y={passRate}
+  y={endToEndPassRate}
 />
 ```
 
-直接把 `selection` 传给它，宿主渲染前替你算好数据——默认报告就是这么写的。要在自己已经跑起来的 React 应用里嵌这张图、或数据是预先算好的，改传 `data`：`<MetricScatter data={await MetricScatter.data(selection, { points: "experiment", series: "agent", x: costUSD, y: passRate })} />`；同时传 `data` 和 `selection`、或两者都不传，类型检查都会报错。
+直接把 `selection` 传给它，宿主渲染前替你算好数据。`MetricScatter` 不根据 experiment id 自动分组；默认 `ExperimentComparison` 会先收窄到一个可比组，再逐组调用它。要在自己已经跑起来的 React 应用里嵌这张图、或数据是预先算好的，改传 `data`：`<MetricScatter data={await MetricScatter.data(selection, { points: "experiment", series: "agent", x: costUSD, y: endToEndPassRate })} />`；同时传 `data` 和 `selection`、或两者都不传，类型检查都会报错。
 
 ```text
 pass ↑                                    （好 → 右上）
@@ -335,7 +347,7 @@ pass ↑                                    （好 → 右上）
 A bub-high   B bub-medium   C codex-high   D codex-low
 ```
 
-网页面点带悬停提示（值与 `samples/total`，禁用 JS 时退化为图内提示）、同系列连线、点击深链下钻。终端面用字母标点、图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。画得出来的点是 0 个（x 或 y 全缺数据）时，两个面都明说这两个指标没有可用数据，不留一片空白；只有 1 个点时，明说「至少要两个实验才能比较」；2 个及以上才正常出图——组件从不因为点不够就整块消失，让你不知道图为什么没了。维度槽也收自定义维度（`{ name, of }`，从 attempt 已有数据算组名）和 `flag()`（experiment 声明的变量），怎么选见[自定义报告](/zh/guides/custom-reports)的「换分组」一节。
+网页面点带悬停提示（值与 `samples/total`，禁用 JS 时退化为图内提示）、同系列连线、点击深链下钻。终端面用字母标点、图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。画得出来的点是 0 个（x 或 y 全缺数据）时，两个面都明说这两个指标没有可用数据，不留一片空白；1 个点也照常出图——组件从不因为点不够就整块消失，让你不知道图为什么没了。维度槽也收自定义维度（`{ name, of }`，从 attempt 已有数据算组名）和 `flag()`（experiment 声明的变量），怎么选见[自定义报告](/zh/how-to/custom-reports)的「换分组」一节。
 
 ## 指标趋势图（`MetricLine`）
 
@@ -345,7 +357,7 @@ x 是有序变量、每个系列一条线，回答「变量拧大，分数怎么
 <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,
 })} />
 ```
 
@@ -376,7 +388,7 @@ A 1 agents   B 4 agents   C 16 agents
     { a: "compare/bub", b: "compare/bub--agents-md", label: "bub" },
     { a: "compare/codex", b: "compare/codex--agents-md", label: "codex" },
   ],
-  metrics: [passRate, costUSD],
+  metrics: [endToEndPassRate, costUSD],
 })} />
 ```
 
@@ -388,4 +400,4 @@ codex   80% → 80%   ±0         $0.51 → —       —
 
 ## 官方组件之外
 
-以上摆法都表达不了时，用 `defineComponent` 写自己的双面组件——网页怎么渲染、终端字符怎么排，两个面你都说了算，写法见[自定义报告](/zh/guides/custom-reports)的「换形态」一节。
+以上摆法都表达不了时，用 `defineComponent` 写自己的双面组件——网页怎么渲染、终端字符怎么排，两个面你都说了算，写法见[自定义报告](/zh/how-to/custom-reports)的「换形态」一节。

package/docs-site/zh/{guides → reference}/results-data.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "结果数据 API"
 description: "报告积木脚下的数据层：openResults 把 .niceeval/ 的落盘 artifact parse 成「实验 → 结果快照 → eval → attempt」的类型化层次，createResultsWriter 把别家结果写成 NiceEval 格式，copySnapshots 负责发布瘦身。"
 ---
 
-[自定义报告](/zh/guides/custom-reports)的积木——指标、计算函数、双面组件——脚下还有一层：`niceeval/results`，落盘 artifact 的 parser。官方两扇门和全部报告积木读的都是这一层，没有私有数据通道；报告表达不了的口径，下到这层直接拿数据算。
+[自定义报告](/zh/how-to/custom-reports)的积木——指标、计算函数、双面组件——脚下还有一层：`niceeval/results`，落盘 artifact 的 parser。官方两扇门和全部报告积木读的都是这一层，没有私有数据通道；报告表达不了的口径，下到这层直接拿数据算。
 
 什么时候下到这层：
 
@@ -68,7 +68,7 @@ const attempt = snap.evals[0].attempts[0];
 
 attempt.evalId;                // "algebra/quadratic" —— 属于哪道题,不用绕 result
 attempt.experimentId;          // 属于哪个实验
-attempt.result;                // EvalResult:判定、断言、用量、成本、experiment 元数据
+attempt.result;                // EvalResult:判定、断言、结构化 error/diagnostics、用量、成本
 attempt.ref;                   // { snapshot, attempt }:证据引用,与 view 深链、报告格子的 refs 同一身份
 await attempt.events();        // StreamEvent[] | null
 await attempt.trace();         // TraceSpan[] | null
@@ -83,6 +83,8 @@ await attempt.sources();       // SourceArtifact[] | null
 - **读不了的落盘不静默。** 版本不兼容、目录损坏的快照进 `skipped` 并带原因；要不要展示由你定，但缺口永远被算出来。
 - **同进程内按句柄记忆化。** 两处都读同一个 `diff()` 不会把上百 MB 读两遍。
 
+`attempt.result.error` 是让 Attempt 进入 `errored` 的唯一致命执行错误，包含稳定 `code`、人可读 `message`、发生错误的 lifecycle operation，以及可选的有限 cause/stack。`attempt.result.diagnostics` 可以与任意判定共存，保存运行仍可继续或收尾时发现的问题。瞬时 `progress` 不落盘；OTel trace 也不是错误存储的前提。
+
 ## 超大输出会被截断
 
 Agent 跑一条命令，输出可以大得离谱——一次递归 `grep` 扫进 `node_modules`，撞上压缩过的 JS 文件，单行就有几 MB。这种输出会同时进 `events.json` 和 `trace.json`，不管的话一个 attempt 就能占上百 MB。
@@ -106,7 +108,9 @@ for (const e of events ?? []) {
 }
 ```
 
-`diff.json` 不截断——里面每个文件都要完整才能用来核对 agent 改了什么。它是唯一可能拖到上百 MB 的 artifact，所以发布时通常不带它（见下面的 `copySnapshots`）。
+这条上限管的是**单个字符串值**，不是整个 JSON 文件。一个文件可以有很多正常值；`diff.json` 和源码也不能截断，因为它们要保持完整语义。所以 `.niceeval/` 适合做本地事实根，不默认适合直接提交进 Git。发布前用下面的 `copySnapshots` 做 artifact 选择和整文件大小检查。
+
+截断发生在持久化边界，不能替 agent runtime 限制发给模型的工具输出。如果 runtime 先把 50 MB 工具结果完整塞进模型请求并收到 413，NiceEval 仍会把 Attempt 记为 `errored`；这里只保证失败后的 events / trace 不再被同一段输出撑爆。
 
 ## 版本：谁写的、读不读得了
 
@@ -156,7 +160,7 @@ latest.warnings[0];
 
 字段供程序判断——CI 里「覆盖缩水就 fail」直接判 `covered < total`，不解析文本；`message` 是渲染好的英文句子，要展示就原样打。渲染与否在你，缺口永远被算出来。警告不止这一种：快照落后于 Selection 中最新的落盘进 `stale-snapshot`、选中的快照没收尾（进程中断）进 `unfinished-snapshot`，每种都带 `kind`、可判断的结构化字段和渲染好的 `message`。
 
-Selection 是[报告积木](/zh/guides/custom-reports)和下文 `copySnapshots` 的通用输入：收 `Selection` 时 warnings 随行（`RunOverview` 之类的组件会如实展示），手工挑的 `Snapshot[]` 数组照收。微调官方口径不用降级成裸数组：`latest.filter((s) => s.experimentId !== "compare/broken")` 返回新 Selection——快照被删减，warnings 修剪到幸存的实验，provenance 不丢。`filter` 只做删减；「换成该实验上一个完整快照」这类**替换式**重挑不是它的事，回到 `exp.snapshots` 自己拿——手工挑的数组没有挑选过程，自然没有 warnings 可带，也如实。
+Selection 是[报告积木](/zh/how-to/custom-reports)和下文 `copySnapshots` 的通用输入：收 `Selection` 时 warnings 随行（`RunOverview` 之类的组件会如实展示），手工挑的 `Snapshot[]` 数组照收。微调官方口径不用降级成裸数组：`latest.filter((s) => s.experimentId !== "compare/broken")` 返回新 Selection——快照被删减，warnings 修剪到幸存的实验，provenance 不丢。`filter` 只做删减；「换成该实验上一个完整快照」这类**替换式**重挑不是它的事，回到 `exp.snapshots` 自己拿——手工挑的数组没有挑选过程，自然没有 warnings 可带，也如实。
 
 ## 一个真实脚本：分布不是折叠
 
@@ -180,9 +184,9 @@ for (const exp of results.experiments) {
 }
 ```
 
-即使在这条最深的路径上也不碰磁盘布局：路径拼接、存在性、版本过滤、快照切分全被库消化。要把这份分布摆进报告页，用 [`defineComponent`](/zh/guides/custom-reports) 包一个双面组件即可。
+即使在这条最深的路径上也不碰磁盘布局：路径拼接、存在性、版本过滤、快照切分全被库消化。要把这份分布摆进报告页，用 [`defineComponent`](/zh/how-to/custom-reports) 包一个双面组件即可。
 
-一条跨快照累计时的义务：`--resume` 会把上一轮已通过、fingerprint 匹配的结果携带合入新快照，同一个 attempt 因此可能存在于多份落盘。携带条目不是空壳：它带着原快照的 `startedAt`(身份锚)与 `artifactBase`(指向原快照 attempt 目录的相对路径)，懒加载按候选顺序回退——先本快照的 attempt 目录，再 `artifactBase` 指向的原快照目录(原快照被清理后如实返回 `null`)；`ref` 指向条目所在的落盘，即携带入的那份新快照。身份键 `(experimentId, evalId, attempt, startedAt)` 的四个字段都在数据上——前两个是 attempt 的直达字段，序号与 `startedAt` 在 `attempt.result` 上。reader 忠实反映这份重复；跨快照聚合前用 `dedupeAttempts` 按身份键去重，重复保留最新快照里的那份——报告积木的计算函数内置这条，自己写脚本时记得过一遍：
+一条跨快照累计时的义务：NiceEval 默认把上一轮已有确定判定（passed / failed）、且 eval 代码和配置没变的结果携带合入新快照（`--force` 全部重跑），同一个 attempt 因此可能存在于多份落盘。携带条目不是空壳：它带着原快照的 `startedAt`(身份锚)与 `artifactBase`(指向原快照 attempt 目录的相对路径)，懒加载按候选顺序回退——先本快照的 attempt 目录，再 `artifactBase` 指向的原快照目录(原快照被清理后如实返回 `null`)；`ref` 指向条目所在的落盘，即携带入的那份新快照。身份键 `(experimentId, evalId, attempt, startedAt)` 的四个字段都在数据上——前两个是 attempt 的直达字段，序号与 `startedAt` 在 `attempt.result` 上。reader 忠实反映这份重复；跨快照聚合前用 `dedupeAttempts` 按身份键去重，重复保留最新快照里的那份——报告积木的计算函数内置这条，自己写脚本时记得过一遍：
 
 ```typescript
 import { dedupeAttempts } from "niceeval/results";
@@ -210,7 +214,7 @@ const snap = await writer.snapshot({   // 建快照目录(独占创建,撞名换
 });
 
 for (const r of convertedResults) {
-  await snap.writeAttempt(r.result, {  // 写 result.json(判决权威落点,一次写成)+ 拆 artifact 文件
+  await snap.writeAttempt(r.result, {  // 写 result.json(判定权威落点,一次写成)+ 拆 artifact 文件
     events: r.events,                  // 第二参 = artifact,都可选;缺哪样读取面就懒加载出 null
     diff: r.diff,
   });                                  // 拆 artifact 文件、算目录、回填引用,全在库内发生
@@ -219,7 +223,7 @@ for (const r of convertedResults) {
 await writer.finish();                 // 给每个快照补 completedAt,没有任何收尾聚合
 ```
 
-`writer.snapshot()` 就是读取面「实验 → 快照」层次的镜像：转多个 experiment 就开多个快照目录，experimentId / agent / model / startedAt 这些快照级元数据在这里声明一次，不用塞进每条 attempt；可选的 `knownEvalIds`（该实验已知的 eval 并集）也在这里声明——它是残缺检测的分母，转换只覆盖部分题目时如实交代全集，下游的覆盖警告就能算出来（`copySnapshots` 发布时会自动补记这个字段，见下文）。转完的目录就是标准结果目录：`niceeval show` / `niceeval view` 直接能看，报告积木直接能算，不用抄格式文档；`producer` 会原样出现在读取面的 `snap.producer` 上。**每个文件恰好写入一次**是写入面的核心承诺:`snapshot.json` 开跑即写、收尾只补 `completedAt`;`result.json` 与 artifact 随 attempt 完成落盘。进程中断只丢未完成的 attempt,已完成的判决与 artifact 已经在盘上——真正「有 attempt 落盘却没有 `snapshot.json`」的极端情况才归 `skipped("incomplete")`,未收尾但元数据齐全的快照能正常读,只带一条警告。
+`writer.snapshot()` 就是读取面「实验 → 快照」层次的镜像：转多个 experiment 就开多个快照目录，experimentId / agent / model / startedAt 这些快照级元数据在这里声明一次，不用塞进每条 attempt；可选的 `knownEvalIds`（该实验已知的 eval 并集）也在这里声明——它是残缺检测的分母，转换只覆盖部分题目时如实交代全集，下游的覆盖警告就能算出来（`copySnapshots` 发布时会自动补记这个字段，见下文）。转完的目录就是标准结果目录：`niceeval show` / `niceeval view` 直接能看，报告积木直接能算，不用抄格式文档；`producer` 会原样出现在读取面的 `snap.producer` 上。**每个文件恰好写入一次**是写入面的核心承诺:`snapshot.json` 开跑即写、收尾只补 `completedAt`;`result.json` 与 artifact 随 attempt 完成落盘。进程中断只丢未完成的 attempt,已完成的判定与 artifact 已经在盘上——真正「有 attempt 落盘却没有 `snapshot.json`」的极端情况才归 `skipped("incomplete")`,未收尾但元数据齐全的快照能正常读,只带一条警告。
 
 ## 发布：`copySnapshots`
 
@@ -230,22 +234,26 @@ import { openResults, copySnapshots } from "niceeval/results";
 
 const results = await openResults(".niceeval");
 await copySnapshots(results.latest(), "site-data/run", {
-  artifacts: ["sources", "events", "trace", "o11y"],   // diff 不截断、可达百 MB,发布时常见地不带;
-});                                                     // events / trace 有 256 KiB 上限,带上是安全的;
+  artifacts: ["sources", "events", "trace", "o11y"],   // diff 不截断,缺省也不带;
+  redact: (text) => text.replaceAll(/sk-[A-Za-z0-9]+/g, "[redacted]"),
+});                                                     // redact 必填:函数消毒,或 false 显式声明原文发布;
+                                                        // 每个待发布文件还会经过 50 MiB 预检;
                                                         // o11y 只有几 KB,报告用到 turns 这类
                                                         // 读 o11y 的指标就把它带上,不然渲染成「—」
 ```
 
-第一个参数收 `Selection` 或手工挑的 `Snapshot[]`——和报告积木同一个输入约定。`artifacts` 的合法值是 `"events" | "trace" | "o11y" | "diff" | "sources"`，缺省全带。目标目录已存在且非空时报错，不静默覆盖——发布脚本要幂等就自己先清目标目录。
+第一个参数收 `Selection` 或手工挑的 `Snapshot[]`——和报告积木同一个输入约定。`artifacts` 的合法值是 `"events" | "trace" | "o11y" | "agentSetup" | "diff" | "sources"`；缺省带除 `diff` 外的五类。目标目录已存在且非空时报错，不静默覆盖——发布脚本要幂等就自己先清目标目录。
+
+复制开始前，NiceEval 会规划全部目标文件并检查序列化后的大小。任一文件超过固定的 50 MiB，整次复制在创建目标目录前失败，错误会列出路径、实际大小和处理建议。你可以从 `artifacts` 排除那类证据；如果是旧版本留下的超大 events / trace，用当前版本重跑后再发布。这个检查既覆盖没有逐值截断的源码 / diff，也覆盖单值都正常但累计过大的 JSON，避免直到 `git push` 才撞上 Git host 的单文件限制。
 
-复制不改 artifact 内容、不消毒；发布前给自由文本消毒用报告积木 `AttemptList.data` 的 `redact` 钩子。唯一随行补记的是挑选时的**覆盖事实**：`partial-coverage` 警告的分母是实验的历史并集，而发布目录没有历史——所以每个复制出的快照带上 `knownEvalIds`（复制时刻该实验已知的 eval 并集），reader 端把它并进 `exp.evalIds` 的计算（取本地历史与快照携带值的并集）。发布目录上重新 `openResults().latest()`，残缺警告被同一套机制重新算出来，不靠发布者转述。复制出的目录就是标准结果目录，`niceeval view --run <目录>` 直接能看；要让报告站随 push 自动更新，workflow 见[通过 CI 发布报告](/zh/guides/publish-report)。
+大小预检只决定整次复制成功或失败，不会从一个超大文件中间删内容。消毒不是可选项——`copySnapshots` 要求显式传 `redact`：给一个函数就改写复制出来的所有文件里的自由文本（events、trace、源码、diff、运行摘要都在内；id、事件类型这类标识字段不动），确定这批数据可以原文公开就传 `redact: false`，两个都不传会直接报错。注意报告积木 `AttemptList.data` 的 `redact` 只影响页面上显示的数据，管不到发布目录里的 artifact 文件；发布场景一律在 `copySnapshots` 这一步消毒。唯一随行补记的是挑选时的**覆盖事实**：`partial-coverage` 警告的分母是实验的历史并集，而发布目录没有历史——所以每个复制出的快照带上 `knownEvalIds`（复制时刻该实验已知的 eval 并集），reader 端把它并进 `exp.evalIds` 的计算（取本地历史与快照携带值的并集）。发布目录上重新 `openResults().latest()`，残缺警告被同一套机制重新算出来，不靠发布者转述。复制出的目录就是标准结果目录，`niceeval view --run <目录>` 直接能看；要让报告站随 push 自动更新，workflow 见[通过 CI 发布报告](/zh/how-to/publish-report)。
 
 ## 分层速览
 
 | 层 | 入口 | 回答 |
 | --- | --- | --- |
 | 官方两扇门 | `niceeval show` / `niceeval view` | 零代码看官方摆法 |
-| 报告积木 | [自定义报告](/zh/guides/custom-reports)、[报告组件](/zh/guides/report-components) | 自己的口径与摆法 |
+| 报告积木 | [自定义报告](/zh/how-to/custom-reports)、[报告组件](/zh/reference/report-components) | 自己的口径与摆法 |
 | 结果数据 API（本页） | `niceeval/results` | 折叠表达不了的算法、接自己的系统、读写格式本身 |
 
 每层都建立在下一层之上，同一份落盘 artifact 是唯一事实来源——上层的派生物删了随时可重算。

package/docs-site/zh/troubleshooting/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/troubleshooting/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/how-to/viewing-results)。

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

@@ -0,0 +1,212 @@
+---
+title: "排查失败与复盘历史运行"
+sidebarTitle: "Debug 手册"
+description: "一份按场景组织的排查手册：断言失败怎么定位、环境错误怎么进沙箱、agent 改了什么怎么看、旧的运行怎么翻出来复盘——每一步都有命令顺序和输出示例。"
+---
+
+跑完一次 `niceeval exp`，失败的 Attempt 都带一个 `@` 开头的定位符（如 `@1qrdcfq8`）。它出现在运行摘要、CI 日志和报告里，定位符本身不会过期——只要 `.niceeval/` 里对应的结果快照还在，今天的定位符下周还能用同一条命令打开同一次 Attempt。所有排查都从它开始。
+
+先说一条通用规则：NiceEval 自己的报错和警告都在消息末尾直接给出下一步。能用一条命令解决的，消息里就是替换好实验名的完整命令，复制执行即可（网页里还可以一键复制）；可以不管的警告会写明「什么情况下可以忽略」。所以看到报错先读完最后一句；本手册处理的是消息之外还需要人工判断的场景——判定失败了怎么定位、环境错误怎么进现场。
+
+## 第一步永远是 `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/troubleshooting/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/reference/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 |