niceeval 0.5.3 → 0.6.0

package/docs-site/zh/guides/report-components.mdx

@@ -4,14 +4,36 @@ sidebarTitle: "报告组件"
 description: "报告文件里能摆的全部官方双面组件：每个组件回答什么问题、怎么调用、网页面长什么样、终端字符输出长什么样。"
 ---
 
-报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/guides/custom-reports)）。每个组件的数据算法挂在它自己身上——`<MetricTable data={await MetricTable.data(selection, …)} />`，组件名后打个点就找到，算和画永远配对。本页逐个列出官方组件：它回答什么问题、在报告里怎么调用、终端输出长什么样。
+报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/guides/custom-reports)）。每个组件的数据算法挂在它自己身上，组件名后打个点就找到，算和画永远配对。本页逐个列出官方组件：它展示哪一层数据、在报告里怎么调用、终端输出长什么样。
+
+## 名称与用途
+
+英文术语描述组件形态，API 名是代码里的导出名。组件分三类：实体列表逐项展示 experiment、Eval 或 Attempt；汇总组件概括整批 Selection；指标图形把指定维度聚合成值。三个实体列表的 `.data(selection)` 都返回普通数组，报告作者先用 JavaScript `.filter()` 收窄，再把 `items` 交给组件。过滤条件不藏在组件里。中文正文首次提到时用“中文名（`API 名`）”，后续可以只写中文名或 `API 名`。
+
+| 分类 | 中文名 | English | API | 主展示单位 |
+| --- | --- | --- | --- | --- |
+| 汇总 | 运行总览 | Run overview | `RunOverview` | 一批 Selection；汇总其中的 experiment、Eval 和 Attempt |
+| 汇总 | 组摘要 | Group summary | `GroupSummary` | 收窄后的一批 Selection；汇总一组 experiment 和 Eval |
+| 实体列表 | 实验列表 | Experiment list | `ExperimentList` | 每项一个 experiment；展开到该 experiment 的 Eval |
+| 实体列表 | Eval 列表 | Eval list | `EvalList` | 每项一个 experiment × Eval；展开到该 Eval 的 Attempt |
+| 实体列表 | Attempt 列表 | Attempt list | `AttemptList` | 每项一个 Attempt；显示断言、错误、Judge 评语和证据 |
+| 指标图形 | 指标表 | Metric table | `MetricTable` | 一个可配置行维度；每格是一个聚合指标值 |
+| 指标图形 | 指标矩阵 | Metric matrix | `MetricMatrix` | 两个可配置维度的交叉格；每格是一个聚合指标值 |
+| 指标图形 | 分组条形图 | Grouped bar chart | `MetricBars` | 两个可配置维度形成分组和系列；每根条是一个聚合指标值 |
+| 指标图形 | 成绩单 | Scoreboard | `Scoreboard` | 每行一个可配置维度值；按 Eval 和 Eval 分组计算分数 |
+| 指标图形 | 指标散点图 | Metric scatter plot | `MetricScatter` | 每点一个可配置维度值，通常是 experiment；坐标是两个聚合指标值 |
+| 指标图形 | 指标趋势图 | Metric line chart | `MetricLine` | 每点一个 experiment；横轴是 experiment flag，纵轴是聚合指标值 |
+| 指标图形 | 成对差异表 | Paired delta table | `DeltaTable` | 每行一对 experiment 或结果快照；格内是指标值及差值 |
+
+`Row`、`Col`、`Section`、`Text`、`Style` 和 `Table` 是排版原语，不计算结果，因此不算一种分析图。它们的中文统称分别是行、列、分节、文本、样式和表格；代码里始终使用 API 名。
 
 所有组件共守同一套契约，下面不再逐个重复：
 
-- **诚实渲染。** 缺数据渲染 `—` 不补 0；覆盖不全的格子带 `12/15` 角标；截断如实标注剩余数量与原始工件路径。
+- **诚实渲染。** 缺数据渲染 `—` 不补 0；覆盖不全的格子带 `12/15` 角标；截断如实标注剩余数量与原始 artifact 路径。
 - **排序与方向随指标的 `better`。** higher 的指标降序、lower 的升序，「好」的一头恒在上、在右上。
-- **证据室深链。** 网页面的格子、点和条目深链到 attempt 弹窗；终端面在条目下印 `niceeval show <eval id>` 下钻命令。
-- **两面同口径，网页面不 hydrate 也完整。** 排序在计算时由 `sort` 定死，两面预排一致；下钻是普通链接、展开折叠用 `<details>`；网页面不提供终端面没有的口径操作，静态导出零客户端 JS。
+- **证据室深链。** 网页面的格子、点和条目深链到 Attempt 详情；终端面用同一 Attempt locator 交给 `niceeval show @<id>`。
+- **终端输出形成反馈闭环。** 每个 Attempt 有一个以 `@` 开头的短 locator，例如 `@1k2m9qrs`。它唯一指向 experiment、结果快照、Eval 和 Attempt。`✓` / `✗` / `!` / `–` 是 passed / failed / errored / skipped；`[E]` 表示运行时 Eval 源码可用，`[X]` 表示执行步骤可用，`[⏱]` 表示 OTel 时间可用，`[D]` 表示工作区 diff 可用。执行步骤统一包含消息、thinking、tool call/result 和 Skill load；OTel 只给这些步骤补时间，不另开一份输出。
+- **两面同口径，网页面不依赖 JS 也完整。** 排序在计算时由 `sort` 定死，终端和网页看到同一份基准顺序；下钻是普通链接、展开折叠用 `<details>`。网页面另有一层浏览操作：点表头就地重排、榜单行过滤、图表点位悬停看数值——只影响眼前的视图，不改数据口径，刷新即回基准顺序；浏览器禁用 JS 时这些操作消失，内容一样不少（悬停信息退化为图内提示）。
 
 ## 排版原语
 
@@ -35,28 +57,47 @@ description: "报告文件里能摆的全部官方双面组件：每个组件回
   codex  78.0/100   40/50    38/50    │
 ```
 
-## `DefaultReport` —— 官方水位整块
+## 表格（`Table`）
 
-官方两扇门裸跑时渲染的就是它：跨 run 合成的现刻榜单加失败清单，表头如实标注合成来源。零 props、纯声明——官方水位只读瘦身条目，宿主总是替你备好，经上下文注入。把官方水位铺进自己的报告时摆上它，不要就不摆：
+第六个排版原语：官方组件摆不出的表，用它摆。它不计算任何东西——列由你定，格子是你算好的显示值，它只负责把两个面都排整齐。
 
 ```tsx
-<DefaultReport />
+<Table
+  columns={[
+    { key: "eval", header: "题目" },
+    { key: "pass", header: "通过率", align: "right" },
+    { key: "cost", header: "成本", align: "right" },
+  ]}
+  rows={[
+    {
+      key: "记忆/写缓存",
+      locator: "@160iuj3h",
+      cells: { eval: "记忆/写缓存", pass: "87%", cost: "$0.09" },
+    },
+    {
+      key: "浏览/表单填写",
+      locator: "@1qrdcfq8",
+      cells: { eval: "浏览/表单填写", pass: null, cost: null },
+    },
+  ]}
+/>
 ```
 
 ```text
-Current verdicts · 2 experiments · composed from 3 runs · latest 2026-07-09T10-00-00-000Z
+题目            通过率    成本   attempt
+记忆/写缓存        87%   $0.09   @160iuj3h
+浏览/表单填写        —       —   @1qrdcfq8
+```
 
-experiment              evals    pass   cost    duration
-compare/bub-gpt-5.4     13/15    87%    $0.42   4m 12s
-compare/codex-gpt-5.4   12/15    80%    $0.51   5m 03s
+列宽按**终端显示宽度**算，中文和全角字符记 2 列——中文题目名、中文 agent 名都不会把表撕歪。`align: "right"` 让数字列右对齐，小数点自然对齐。格子是 `null` 就渲染 `—`，不补 0。行上带 `locator` 就多出一列 attempt：网页面链到证据室，终端面列出 locator，直接喂给 `niceeval show <locator>`。
 
-Failing:
-  ✗ weather/brooklyn   compare/codex-gpt-5.4   gate calledTool("get_weather")   41s ago
-```
+表比终端宽时先压最宽的左对齐列（按显示宽度折行），右对齐列不折行——数字折行读不了；压到下限仍放不下，就从右侧丢列，并在表下如实报丢了几列，不静默截断。
+
+指标表、指标矩阵、成绩单和成对差异表的终端面就建在 `Table` 上，所以你的表和官方的表用的是同一把尺子。表格之外的形态要自己排字符时，用[自定义报告](/zh/guides/custom-reports)「换形态」一节里那套文本排版函数。
 
-## `RunOverview` —— 页头 KPI 条
+## 运行总览（`RunOverview`）
 
-每张报告开头「这批数据是什么」：几个配置、几道题、通过分布、总成本、何时跑的；选集里的挑选警告随数据一起进来、直接显示在条内，诚实不靠你记得接线。
+每张报告开头「这批数据是什么」：几个配置、几道题、通过分布、总成本、何时跑的；Selection 里的挑选警告随数据一起进来、直接显示在条内，诚实不用你另外传一遍。
 
 ```tsx
 <RunOverview data={await RunOverview.data(selection)} />
@@ -68,7 +109,122 @@ passed 26 · failed 12 · errored 4 · skipped 0 · $0.93 · 9m 15s
 ! snapshot compare/codex-gpt-5.4 predates latest run by 2 days
 ```
 
-## `MetricTable` —— 榜单
+## 组摘要（`GroupSummary`）
+
+一组 experiment（比如按目录前缀归在同一个 `<Section>` 里的那些 experiment）的紧凑统计块，回答「这组题综合算下来过了多少、花了多少、什么时候跑的」。组件本身不分组——先用 `Selection.filter` 把 Selection 收窄到这一组，再喂给 `GroupSummary.data`：
+
+```tsx
+const scoped = selection.filter((s) => s.experimentId.startsWith("compare/"));
+
+<Section title="compare">
+  <GroupSummary data={await GroupSummary.data(scoped)} />
+</Section>
+```
+
+```text
+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`。
+
+组摘要是普通的公开组件，`GroupSummary.data` 是普通的公开计算函数——想在自己的报告里按目录前缀分组、每组摆一块，按上面的写法收窄 Selection 再调它就行。
+
+## 实验列表（`ExperimentList`）
+
+每项固定代表一个 experiment。主行显示 experiment id、agent、model、flags、Eval 判定构成、通过率、Tokens、成本和耗时；展开后显示这个 experiment 的 Eval 列表。它不接受列配置——这是 experiment 的诊断视图，不是通用指标表。
+
+```tsx
+const experiments = await ExperimentList.data(selection);
+
+<ExperimentList
+  items={experiments.filter((exp) => exp.verdicts.errored === 0)}
+/>
+```
+
+`niceeval show` 每个 experiment 输出一行汇总，每个 Eval 只占一行。Attempt ID 后的证据位告诉 AI 能读什么，不展开重复命令：
+
+```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✓[E,X,⏱] @141bm7cx✓[E,X,⏱]   18s avg · $0.02 avg
+  ✗ weather/brooklyn    @1k2m9qrs✗[E,X,⏱] @1nx4dpqr✗[E,X] @19vq2jex✗[E,X]   gate calledTool("get_weather")
+  ! fixtures/button     @1c3h6twx![E,D]   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✓[E,X,⏱]   16s · $0.02
+  ✗ algebra/matrix      @1e2j7mxa✗[E,X] @1f5r9nab✗[E,X,⏱] @1g4w8pcd✗[E,X,⏱]   gate equals("42")
+  ✗ weather/brooklyn    @1h6t3vbe✗[E,X,⏱] @1j9m2qfg✗[E,X,⏱] @1k7c5rxh✗[E,X,⏱]   gate calledTool("get_weather")
+
+inspect: niceeval show @<id> [--eval|--execution|--diff]
+```
+
+locator 由 `experimentId + snapshot.startedAt + evalId + attempt index` 的不可变身份确定，复制或发布结果后保持不变。宿主在当前结果根解析 locator；不存在或发生冲突时直接报错，不回退到“最新一次”。`@` 前缀让它与 Eval ID 前缀选择器无歧义。
+
+`.data(selection)` 返回普通的 `ExperimentListItem[]`，顺序按 experiment id 稳定排列。要只看某个 agent、目录前缀或运行状态，直接过滤数组。组件不提供另一套 `filter` 查询语法。网页面的文本搜索只是临时浏览操作，不改变传入的 items；终端面始终输出完整的传入数组。
+
+## Eval 列表（`EvalList`）
+
+每项固定代表一个 `experimentId + evalId`，因为同一个 Eval 跑在两个 experiment 上是两条不同结果。主行显示判定、Attempt 数、聚合分数、成本、耗时和失败原因；展开后显示这个 Eval 的 Attempt 列表。
+
+```tsx
+const evals = await EvalList.data(selection);
+
+<EvalList
+  items={evals.filter((item) => item.verdict !== "passed")}
+/>
+```
+
+`niceeval show` 每个 `experiment × Eval` 输出一项，Attempt 仍用同一套紧凑 ID 和证据位。每项只给一条模板：
+
+```text
+weather/brooklyn · compare/bub-gpt-5.4 · failed
+  score 0.20 · 3 attempts · 41s avg · $0.04 avg
+  @1k2m9qrs✗[E,X,⏱] · gate calledTool("get_weather") — tool was never called
+  @1nx4dpqr✗[E,X]   · gate calledTool("get_weather") — tool was never called
+  @19vq2jex✗[E,X]   · gate calledTool("get_weather") — tool was never called
+
+fixtures/button · compare/bub-gpt-5.4 · errored
+  score — · 1 attempt · 2m 00s · $0.09
+  @1c3h6twx![E,D] · command timed out after 120s
+
+inspect: niceeval show @<id> [--eval|--execution|--diff]
+```
+
+`.data(selection)` 返回普通的 `EvalListItem[]`。按 Eval id 前缀、experiment、判定或分数过滤都使用数组 `.filter()`；组件只负责渲染传入的 items。
+
+## Attempt 列表（`AttemptList`）
+
+每项固定代表一个 Attempt，显示 experiment、Eval、Attempt 序号、判定、耗时、成本、失败断言、error、Judge 评语和证据链接。它既能列失败证据，也能列通过样本，不把 verdict 过滤写死在组件名里。
+
+```tsx
+const attempts = await AttemptList.data(selection, { redact });
+
+<AttemptList
+  items={attempts.filter((item) => item.verdict === "failed" || item.verdict === "errored")}
+/>
+```
+
+`niceeval show` 每项完整输出一个 Attempt，不再折叠到 Eval 汇总。这里已经是叶子层，只在末尾给一条与该 Attempt 可用证据对应的模板：
+
+```text
+✗ @1k2m9qrs · weather/brooklyn · compare/bub-gpt-5.4 · 41s · $0.04 · [E,X,⏱]
+  gate calledTool("get_weather") · failed
+    tool was never called
+  soft judge("回答基于实时数据") · 0.2/1
+    reply invents a temperature
+
+! @1c3h6twx · fixtures/button · compare/bub-gpt-5.4 · 2m 00s · $0.09 · [E,D]
+  command timed out after 120s
+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 项未展示”，不静默截断。
+
+## 指标表（`MetricTable`）
 
 一行一个维度值、一列一个指标的对比表，回答「谁整体更好」。行维度、指标列、排序全部可换，自定义指标（`defineMetric`）与内置指标同列。
 
@@ -86,9 +242,11 @@ bub     87%         312 lines    $0.42
 codex   80% 12/15   355 lines    $0.51
 ```
 
-两面都按 `sort` 预排，看到同一份顺序——要换排序改一行重跑，不做单面才有的交互口径。`12/15` 角标表示该格 15 个 attempt 里只有 12 个测得了这个指标。
+两面都按 `sort` 预排，基准顺序一致——要固定换一种排序，改一行重跑。`12/15` 角标表示该格 15 个 attempt 里只有 12 个测得了这个指标。
 
-## `MetricMatrix` —— 逐题格子
+`rows: "experiment"` 时每行自动带 agent 与 model 列——结果里现成的元信息，不用配置。`MetricTable` 不展开实体层级：要看 experiment、Eval 或 Attempt 的固定诊断字段，分别使用三个实体列表；要自由换维度和指标列，使用指标表。
+
+## 指标矩阵（`MetricMatrix`）
 
 行 × 列两个维度、格子里一个指标，回答「哪道题谁挂了」。稀疏渲染：没有样本的格子空着，不编数。
 
@@ -107,7 +265,7 @@ next: niceeval show geometry/area
 
 网页面点格子深链到该格的 attempt；终端面在表下印下钻命令。
 
-## `MetricBars` —— 分组条形
+## 分组条形图（`MetricBars`）
 
 同一份矩阵数据的另一种摆法（`MetricBars.data` 就是 `MetricMatrix.data` 的别名）：按组并排比大小，回答「每个科目上谁领先、差多少」。组维度一组条、系列维度一根条、条长是指标值——benchmark 发布图（Terminal-Bench、BrowseComp 各一组，每个 agent 一根柱）就是这个形状。
 
@@ -130,7 +288,7 @@ geometry
 
 网页面是竖向分组柱：柱顶标数值，系列颜色与其它组件的稳定配色一致，图例自动生成。终端面横向条形，字符宽度即刻度，同组内按值排序（方向随 `better`）。`better: "lower"` 的指标（成本、耗时）条形反向填充，短条恒为「好」。
 
-## `Scoreboard` —— 考试成绩单
+## 成绩单（`Scoreboard`）
 
 总分 + 分科小计，回答「这套题它能得几分」。逐题分值制：权重按 eval id 前缀配置，分母对所有被打分者恒定，没跑到的题挣 0 分并如实报 `missing`。
 
@@ -149,19 +307,22 @@ bub     86.5/100   45/50          41.5/50
 codex   71.0/100   40/50          31/50 (1 missing)
 ```
 
-## `MetricScatter` —— 质量 × 成本 frontier
+## 指标散点图（`MetricScatter`）
 
 每个点一个配置、两个指标各占一轴，回答「又好又便宜的是谁」。`series` 把同 agent 不同档位的点连成线；`better` 驱动轴向——`lower` 的轴反向画，「好」的角落恒在右上。
 
 ```tsx
-<MetricScatter data={await MetricScatter.data(selection, {
-  points: "experiment",     // 每个点 = 一个配置的聚合
-  series: "agent",          // 同 agent 的档位连成线
-  x: costUSD,
-  y: passRate,
-})} />
+<MetricScatter
+  selection={selection}
+  points="experiment"       // 每个点 = 一个配置的聚合
+  series="agent"            // 同 agent 的档位连成线
+  x={costUSD}
+  y={passRate}
+/>
 ```
 
+直接把 `selection` 传给它，宿主渲染前替你算好数据——默认报告就是这么写的。要在自己已经跑起来的 React 应用里嵌这张图、或数据是预先算好的，改传 `data`：`<MetricScatter data={await MetricScatter.data(selection, { points: "experiment", series: "agent", x: costUSD, y: passRate })} />`；同时传 `data` 和 `selection`、或两者都不传，类型检查都会报错。
+
 ```text
 pass ↑                                    （好 → 右上）
  90%│                                  A
@@ -174,11 +335,11 @@ pass ↑                                    （好 → 右上）
 A bub-high   B bub-medium   C codex-high   D codex-low
 ```
 
-网页面点带 hover（值与 `samples/total`）、同系列连线、点击深链下钻。终端面用字母标点、图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。维度槽也收 `flag()`——用 experiment 声明的变量分组，见[自定义报告](/zh/guides/custom-reports)的「变量来自配置」一节。
+网页面点带悬停提示（值与 `samples/total`，禁用 JS 时退化为图内提示）、同系列连线、点击深链下钻。终端面用字母标点、图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。画得出来的点是 0 个（x 或 y 全缺数据）时，两个面都明说这两个指标没有可用数据，不留一片空白；只有 1 个点时，明说「至少要两个实验才能比较」；2 个及以上才正常出图——组件从不因为点不够就整块消失，让你不知道图为什么没了。维度槽也收自定义维度（`{ name, of }`，从 attempt 已有数据算组名）和 `flag()`（experiment 声明的变量），怎么选见[自定义报告](/zh/guides/custom-reports)的「换分组」一节。
 
-## `MetricLine` —— 趋势线
+## 指标趋势图（`MetricLine`）
 
-x 是有序变量、每个系列一条线，回答「变量拧大，分数怎么走」——并行 agent 数 × 模拟延迟 × 得分这类 scaling 图就是它。与 `MetricScatter` 的分工：scatter 的两轴都是测出来的指标（找 frontier），line 的 x 是你配置的变量（看趋势）。变量在 experiment 的 `flags` 里声明，报告用 `flag()` 直接引用，不从 experiment 命名里解析。
+x 是有序变量、每个系列一条线，回答「变量拧大，分数怎么走」——并行 agent 数 × 模拟延迟 × 得分这类 scaling 图就是它。与 `MetricScatter` 的分工：散点图的两轴都是测出来的指标（找优势前沿），趋势图的 x 是你配置的变量（看趋势）。变量在 experiment 的 `flags` 里声明，报告用 `flag()` 直接引用，不从 experiment 命名里解析。
 
 ```tsx
 <MetricLine data={await MetricLine.data(selection, {
@@ -205,9 +366,9 @@ A 1 agents   B 4 agents   C 16 agents
 
 每个点是一个 experiment 的聚合，与其它组件同一台两级聚合引擎，`samples` / `total` / `refs` 一应俱全；同系列的点按 x 排序连线。网页面每个点可 hover、可深链下钻。终端面同系列共用一个字母、沿 x 排布，趋势肉眼可读；y 缺数据的点不画、注脚报数，点太密降级为坐标表。
 
-## `DeltaTable` —— 成对对比
+## 成对差异表（`DeltaTable`）
 
-每行一对配置、每列一个指标，格子里 A、B、Δ 三个值，回答「这个开关值不值」「这次修复翻转了什么」。涨跌好坏由 `better` 判定，任一侧缺数据 Δ 显示为缺，不硬算。「这次 vs 上次」（同一配置的两个快照）也是它：`pairs` 的 `a` / `b` 除 experiment id 外也收快照键 `<experimentId> @ <startedAt>`——时间轴对比要用到旧快照，`results.latest()` 里没有，配手挑的快照数组（如 `[exp.latest, exp.snapshots[1]]`）用。
+每行一对配置、每列一个指标，格子里 A、B、Δ 三个值，回答「这个开关值不值」「这次修复翻转了什么」。涨跌好坏由 `better` 判定，任一侧缺数据 Δ 显示为缺，不硬算。「这次 vs 上次」（同一配置的两个结果快照）也是它：`pairs` 的 `a` / `b` 除 experiment id 外也收快照键 `<experimentId> @ <startedAt>`——时间轴对比要用到旧快照，`results.latest()` 里没有，配手挑的快照数组（如 `[exp.latest, exp.snapshots[1]]`）用。
 
 ```tsx
 <DeltaTable data={await DeltaTable.data(selection, {
@@ -225,28 +386,6 @@ bub     87% → 93%   +6%        $0.42 → $0.45   +$0.03
 codex   80% → 80%   ±0         $0.51 → —       —
 ```
 
-## `CaseList` —— 失败案例清单
-
-失败与出错的 attempt 逐条列出：失败断言、error 摘要、judge 评语。榜单回答「多少」，它回答「为什么」。
-
-```tsx
-<CaseList data={await CaseList.data(selection, { outcomes: ["failed", "errored"], limit: 20 })} />
-```
-
-```text
-✗ weather/brooklyn · compare/codex-gpt-5.4 · failed · 41s · $0.04
-    gate calledTool("get_weather") — tool was never called
-    soft judge("回答基于实时数据") — 0.2/1: reply invents a temperature
-    → niceeval show weather/brooklyn
-✗ fixtures/button · compare/bub-gpt-5.4 · failed · 2m 10s · $0.09
-    gate fileChanged("src/components/Button.tsx")
-    → niceeval show fixtures/button
-
-(3 more not shown · limit 20)
-```
-
-自由文本（error、断言 detail、judge 评语）发布前要消毒时，用 `CaseList.data` 的 `redact` 钩子。
-
 ## 官方组件之外
 
 以上摆法都表达不了时，用 `defineComponent` 写自己的双面组件——网页怎么渲染、终端字符怎么排，两个面你都说了算，写法见[自定义报告](/zh/guides/custom-reports)的「换形态」一节。

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

@@ -46,7 +46,7 @@ export default defineEval({
 - 每个 attempt 是 Braintrust 里的一行；`runs: 3` 会产生三行，靠 metadata 里的 `attempt` 区分。
 - soft 断言按名字记为 score；gate 断言记在 `gate:` 前缀下。这样在 Braintrust 的实验对比里，gate 回归和 soft 分数回归用同一套 diff 看。
 - metrics 带开始/结束时间、token 用量和估算成本；缺的数据不写，不补零。
-- metadata 带 `agent`、`model`、`experiment`、`flags`、`outcome` 和失败断言明细，方便在 Braintrust 里按维度过滤。
+- metadata 带 `agent`、`model`、`experiment`、`flags`、`verdict` 和失败断言明细，方便在 Braintrust 里按维度过滤。
 
 ### 配置项
 
@@ -95,7 +95,7 @@ import type { Reporter } from "niceeval";
 
 const notify: Reporter = {
   async onEvalComplete(result) {
-    if (result.outcome === "failed") {
+    if (result.verdict === "failed") {
       await fetch("http://localhost:3000/notify", {
         method: "POST",
         body: JSON.stringify({ eval: result.id, agent: result.agent }),

package/docs-site/zh/guides/results-data.mdx

@@ -1,10 +1,10 @@
 ---
 title: "用 niceeval/results 直接读写结果数据"
 sidebarTitle: "结果数据 API"
-description: "报告积木脚下的数据层：openResults 把 .niceeval/ 的落盘工件 parse 成「实验 → 快照 → eval → attempt」的类型化层次，createRunWriter 把别家结果写成 NiceEval 格式，copySnapshots 负责发布瘦身。"
+description: "报告积木脚下的数据层：openResults 把 .niceeval/ 的落盘 artifact parse 成「实验 → 结果快照 → eval → attempt」的类型化层次，createResultsWriter 把别家结果写成 NiceEval 格式，copySnapshots 负责发布瘦身。"
 ---
 
-[自定义报告](/zh/guides/custom-reports)的积木——指标、计算函数、双面组件——脚下还有一层：`niceeval/results`，落盘工件的 parser。官方两扇门和全部报告积木读的都是这一层，没有私有数据通道；报告表达不了的口径，下到这层直接拿数据算。
+[自定义报告](/zh/guides/custom-reports)的积木——指标、计算函数、双面组件——脚下还有一层：`niceeval/results`，落盘 artifact 的 parser。官方两扇门和全部报告积木读的都是这一层，没有私有数据通道；报告表达不了的口径，下到这层直接拿数据算。
 
 什么时候下到这层：
 
@@ -16,7 +16,7 @@ description: "报告积木脚下的数据层：openResults 把 .niceeval/ 的落
 
 ## 读：`openResults`
 
-输入是 `.niceeval/` 目录（或单个 run 目录），输出是四层数据：**实验 → 快照（单次跑的实验）→ eval → attempt**。你从此不碰路径、不判断文件存在性、不解析 JSON：
+输入是 `.niceeval/` 目录（或 `copySnapshots` 产出的结果根目录，同一种布局），输出是四层数据：**实验 → 结果快照（单次跑的实验）→ eval → attempt**。你从此不碰路径、不判断文件存在性、不解析 JSON：
 
 ```typescript
 import { openResults } from "niceeval/results";
@@ -45,6 +45,8 @@ const snap = exp.latest;
 snap.agent;                    // 本快照自己的 agent
 snap.model;
 snap.startedAt;                // 这次实验什么时候跑的
+snap.completedAt;              // 收尾时补写;缺失 = 进程中断,已落盘的 attempt 仍可正常读
+snap.dir;                      // 快照目录的绝对路径 —— 物理落盘就是快照本身,没有更低一层
 snap.producer;                 // { name: "niceeval", version: "0.4.6" } —— 谁写的这份结果
 snap.schemaVersion;            // 结果格式版本
 ```
@@ -59,15 +61,15 @@ for (const ev of snap.evals) {
 snap.attempts;                 // 不关心题目边界时,全部 attempt 平铺
 ```
 
-**第四层，attempt**——瘦身条目直接在手上，重工件全部懒加载。唯一带 `Handle` 后缀的类型就是它：上面三层是纯数据，这一层的方法会碰磁盘：
+**第四层，attempt**——瘦身条目直接在手上，重 artifact 全部懒加载。唯一带 `Handle` 后缀的类型就是它：上面三层是纯数据，这一层的方法会碰磁盘：
 
 ```typescript
 const attempt = snap.evals[0].attempts[0];
 
 attempt.evalId;                // "algebra/quadratic" —— 属于哪道题,不用绕 result
 attempt.experimentId;          // 属于哪个实验
-attempt.result;                // EvalResult:判决、断言、用量、成本、experiment 元数据
-attempt.ref;                   // { run, result }:证据引用,与 view 深链、报告格子的 refs 同一身份
+attempt.result;                // EvalResult:判定、断言、用量、成本、experiment 元数据
+attempt.ref;                   // { snapshot, attempt }:证据引用,与 view 深链、报告格子的 refs 同一身份
 await attempt.events();        // StreamEvent[] | null
 await attempt.trace();         // TraceSpan[] | null
 await attempt.o11y();          // O11ySummary | null
@@ -77,8 +79,8 @@ await attempt.sources();       // SourceArtifact[] | null
 
 三条要点：
 
-- **懒加载即存在性判断。** 工件缺失返回 `null`，不抛错——remote agent 没有 `diff.json` 时，`await attempt.diff()` 就是 `null`，你据此决定跳过还是报缺。
-- **读不了的落盘不静默。** 版本不兼容、目录损坏的 run 进 `skipped` 并带原因；要不要展示由你定，但缺口永远被算出来。
+- **懒加载即存在性判断。** artifact 缺失返回 `null`，不抛错——remote agent 没有 `diff.json` 时，`await attempt.diff()` 就是 `null`，你据此决定跳过还是报缺。
+- **读不了的落盘不静默。** 版本不兼容、目录损坏的快照进 `skipped` 并带原因；要不要展示由你定，但缺口永远被算出来。
 - **同进程内按句柄记忆化。** 两处都读同一个 `diff()` 不会把上百 MB 读两遍。
 
 ## 版本：谁写的、读不读得了
@@ -93,19 +95,17 @@ for (const s of results.skipped) {
 }
 ```
 
-`"incomplete"` 与版本无关：run 中途 crash、没走到收尾写出 summary 的目录进这一类——已完成的 attempt 工件仍在盘上供手工排查，但没有 summary 的落盘对读取面不可见。
+`"incomplete"` 是极小概率的一种：有 attempt 落盘、却没有 `snapshot.json`——只可能出现在「快照目录建好、元数据还没写完」的极小窗口里进程死亡，或人为删了文件。它和「进程中断」的常态不是一回事：进程中断的常态是**未收尾快照**（`snapshot.json` 在，只是缺 `completedAt`），这种快照能正常读，已落盘的 attempt 全部可见，只是 `results.latest()` 选中它时会带一条 `unfinished-snapshot` 警告（见下文），不会被归进 `skipped`。
 
 旧版本的结果不会丢：磁盘上原样还在，用写它的那个工具就能看——`producer.name` 是 `"niceeval"` 时，提示用户 `npx niceeval@<producer.version> view`；是第三方 harness 时如实报出它的名字和版本，别拼一句错误的 npx 命令。`skipped` 给你的信息刚好够做对这个分支。
 
-## 为什么快照不是 run 目录
+## 快照就是这个目录
 
-一次 CLI 调用写一个 run 目录，但一个 run 目录里可以装多个 experiment（`niceeval exp compare` 整组对照进同一份汇总）。「每个 experiment 最新一次」因此没法用目录粒度表达：周一跑了整组，周二只重跑 `compare/bub-gpt-5.4`，bub 的最新在周二的目录里，codex 的还在周一的目录里。
-
-快照把「单次跑的实验」这层身份显式化——**一个 experiment 在一次落盘里的那部分结果**。物理目录仍可通过 `results.runDirs` 与 `snap.runDir` 触达（发布、排查工件路径时用），多数消费方不需要碰。
+**快照 = 单次跑的实验**，物理上就是一个快照目录（`.niceeval/<experiment>/<snapshot>/`），没有更低一层。`niceeval exp compare` 一次 CLI 调用会给涉及的每个实验各开一个独立的快照目录，互相不合并、没有跨实验的聚合落盘——「每个 experiment 最新一次」因此天然是快照粒度：周一跑了整组 compare，周二只重跑 `compare/bub-gpt-5.4`，bub 的最新快照落在周二，codex 的还在周一，`exp.latest` 各自反映各自的历史。
 
 ## 选快照：`results.latest()`
 
-多数场景先回答「现在什么水位」，选择器替你挑「每个实验最新一次」——这也是官方榜单的口径。返回的是一个**选集（Selection）**，快照和警告绑在一起走：
+多数场景先回答「现在什么水位」，选择器替你挑「每个实验最新一次」——这也是默认报告的口径。返回的是一个 **Selection**，快照和警告绑在一起走：
 
 ```typescript
 const latest = results.latest({
@@ -129,9 +129,9 @@ latest.warnings[0];
 // }
 ```
 
-字段供程序判断——CI 里「覆盖缩水就 fail」直接判 `covered < total`，不解析文本；`message` 是渲染好的英文句子，要展示就原样打。渲染与否在你，缺口永远被算出来。警告不止这一种：快照落后于选集中最新的落盘、experimentId 缺失被合成键等同样进 `warnings`，每种都带 `kind`、可判断的结构化字段和渲染好的 `message`。
+字段供程序判断——CI 里「覆盖缩水就 fail」直接判 `covered < total`，不解析文本；`message` 是渲染好的英文句子，要展示就原样打。渲染与否在你，缺口永远被算出来。警告不止这一种：快照落后于 Selection 中最新的落盘进 `stale-snapshot`、选中的快照没收尾（进程中断）进 `unfinished-snapshot`，每种都带 `kind`、可判断的结构化字段和渲染好的 `message`。
 
-选集是[报告积木](/zh/guides/custom-reports)和下文 `copySnapshots` 的通用输入：收 `Selection` 时 warnings 随行（`RunOverview` 之类的组件会如实展示），手工挑的 `Snapshot[]` 数组照收。微调官方口径不用降级成裸数组：`latest.filter((s) => s.experimentId !== "compare/broken")` 返回新选集——快照被删减，warnings 修剪到幸存的实验，provenance 不丢。`filter` 只做删减；「换成该实验上一个完整快照」这类**替换式**重挑不是它的事，回到 `exp.snapshots` 自己拿——手工挑的数组没有挑选过程，自然没有 warnings 可带，也如实。
+Selection 是[报告积木](/zh/guides/custom-reports)和下文 `copySnapshots` 的通用输入：收 `Selection` 时 warnings 随行（`RunOverview` 之类的组件会如实展示），手工挑的 `Snapshot[]` 数组照收。微调官方口径不用降级成裸数组：`latest.filter((s) => s.experimentId !== "compare/broken")` 返回新 Selection——快照被删减，warnings 修剪到幸存的实验，provenance 不丢。`filter` 只做删减；「换成该实验上一个完整快照」这类**替换式**重挑不是它的事，回到 `exp.snapshots` 自己拿——手工挑的数组没有挑选过程，自然没有 warnings 可带，也如实。
 
 ## 一个真实脚本：分布不是折叠
 
@@ -148,7 +148,7 @@ for (const exp of results.experiments) {
     points.push({
       agent: exp.latest.agent,
       eval: attempt.evalId,
-      passed: attempt.result.outcome === "passed",
+      passed: attempt.result.verdict === "passed",
       shellCommands: o11y?.shellCommands.length ?? 0,
     });
   }
@@ -157,7 +157,7 @@ for (const exp of results.experiments) {
 
 即使在这条最深的路径上也不碰磁盘布局：路径拼接、存在性、版本过滤、快照切分全被库消化。要把这份分布摆进报告页，用 [`defineComponent`](/zh/guides/custom-reports) 包一个双面组件即可。
 
-一条跨快照累计时的义务：`--resume` 会把上一轮已通过的结果原样合入新 run，同一个 attempt 因此可能存在于多份落盘。合入的条目不是空壳：它的工件仍在原 run 目录，懒加载会自动回退到那里读（原 run 目录被清理后如实返回 `null`）；`ref` 指向条目所在的落盘。身份键 `(experimentId, evalId, attempt, startedAt)` 的四个字段都在数据上——前两个是 attempt 的直达字段，序号与 `startedAt` 在 `attempt.result` 上。reader 忠实反映这份重复；跨快照聚合前用 `dedupeAttempts` 按身份键去重，重复保留最新 run 目录里的那份——报告积木的计算函数内置这条，自己写脚本时记得过一遍：
+一条跨快照累计时的义务：`--resume` 会把上一轮已通过、fingerprint 匹配的结果携带合入新快照，同一个 attempt 因此可能存在于多份落盘。携带条目不是空壳：它带着原快照的 `startedAt`(身份锚)与 `artifactBase`(指向原快照 attempt 目录的相对路径)，懒加载按候选顺序回退——先本快照的 attempt 目录，再 `artifactBase` 指向的原快照目录(原快照被清理后如实返回 `null`)；`ref` 指向条目所在的落盘，即携带入的那份新快照。身份键 `(experimentId, evalId, attempt, startedAt)` 的四个字段都在数据上——前两个是 attempt 的直达字段，序号与 `startedAt` 在 `attempt.result` 上。reader 忠实反映这份重复；跨快照聚合前用 `dedupeAttempts` 按身份键去重，重复保留最新快照里的那份——报告积木的计算函数内置这条，自己写脚本时记得过一遍：
 
 ```typescript
 import { dedupeAttempts } from "niceeval/results";
@@ -166,52 +166,53 @@ const all = exp.snapshots.flatMap((s) => s.attempts);   // 跨快照累计:历
 const { attempts, warnings } = dedupeAttempts(all);      // resume 合入的重复被折掉
 ```
 
-## 写：`createRunWriter`
+## 写：`createResultsWriter`
 
-写入面和读取面是同一组类型的两半，签名就是 roundtrip 的证明：reader 的 `attempt.result` 由两部分拼成——快照级字段（agent / model / startedAt / producer）来自 `writer.snapshot()` 的一次声明，其余全部字段就是 `writeAttempt` 第一个参数的类型；第二个参数是 reader 懒加载能拿到的那几样工件的类型。「writeAttempt 参数 + snapshot() 声明 = reader 读回的全部」由类型拼合背书：快照级字段不在 attempt 参数的类型里，不存在「谁的值为准」。用它把别家平台、自研 harness 的结果转成 NiceEval 格式：
+写入面和读取面是同一组类型的两半，签名就是 roundtrip 的证明：reader 的 `attempt.result` 由两部分拼成——快照级字段（experimentId / agent / model / startedAt / producer）来自 `writer.snapshot()` 的一次声明，其余全部字段就是 `writeAttempt` 第一个参数的类型；第二个参数是 reader 懒加载能拿到的那几样 artifact 的类型。「writeAttempt 参数 + snapshot() 声明 = reader 读回的全部」由类型拼合背书：快照级字段不在 attempt 参数的类型里，不存在「谁的值为准」。用它把别家平台、自研 harness 的结果转成 NiceEval 格式：
 
 ```typescript
-import { createRunWriter } from "niceeval/results";
+import { createResultsWriter } from "niceeval/results";
 
-const writer = await createRunWriter(".niceeval", {
+const writer = createResultsWriter(".niceeval", {
   producer: { name: "my-harness", version: "1.0.0" },
 });
 
-const snap = writer.snapshot({         // 快照级元数据的家:一个 experiment 开一个
-  experiment: "compare/my-agent",
+const snap = await writer.snapshot({   // 建快照目录(独占创建,撞名换后缀重试)+ 写 snapshot.json
+  experimentId: "compare/my-agent",
   agent: "my-agent",
   model: "gpt-5.4",
   startedAt: sourceRun.startedAt,      // 必填:去重身份键以它为锚
 });
 
 for (const r of convertedResults) {
-  await snap.writeAttempt(r.result, {  // 第一参 = attempt 级条目;快照级字段在 snapshot() 声明
-    events: r.events,                  // 第二参 = 工件,都可选;缺哪样读取面就懒加载出 null
+  await snap.writeAttempt(r.result, {  // 写 result.json(判决权威落点,一次写成)+ 拆 artifact 文件
+    events: r.events,                  // 第二参 = artifact,都可选;缺哪样读取面就懒加载出 null
     diff: r.diff,
-  });                                  // 拆工件文件、算目录、回填引用,全在库内发生
+  });                                  // 拆 artifact 文件、算目录、回填引用,全在库内发生
 }
 
-await writer.finish();                 // summary 从已写入的 attempt 推导,计数永远和条目对得上
+await writer.finish();                 // 给每个快照补 completedAt,没有任何收尾聚合
 ```
 
-`writer.snapshot()` 就是读取面「一个 run 装多份快照」的镜像：转多个 experiment 就开多个快照，agent / model / startedAt 这些快照级元数据在这里声明，不用塞进每条 attempt；可选的 `knownEvalIds`（该实验已知的 eval 并集）也在这里声明——它是残缺检测的分母，转换只覆盖部分题目时如实交代全集，下游的覆盖警告就能算出来（`copySnapshots` 发布时会自动补记这个字段，见下文）。转完的目录就是标准结果目录：`niceeval show` / `niceeval view` 直接能看，报告积木直接能算，不用抄格式文档；`producer` 会原样出现在读取面的 `snap.producer` 上。attempt 工件按完成增量落盘，但 summary 是 `finish()` 写出的收尾事实：中途 crash、没走到 `finish()` 的目录，已完成的工件仍在盘上供手工排查，读取面则把它归入 `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`
 
-把选中的快照按格式感知地复制到发布目录——只带指定工件、只带选中的 attempt：
+把选中的快照按格式感知地复制到发布目录——只带指定 artifact、只带选中的 attempt：
 
 ```typescript
 import { openResults, copySnapshots } from "niceeval/results";
 
 const results = await openResults(".niceeval");
 await copySnapshots(results.latest(), "site-data/run", {
-  artifacts: ["sources", "events", "trace"],   // diff 可达百 MB,发布时常见地不带
-});
+  artifacts: ["sources", "events", "trace", "o11y"],   // diff 可达百 MB,发布时常见地不带;
+});                                                     // o11y 只有几 KB,报告用到 turns 这类
+                                                        // 读 o11y 的指标就把它带上,不然渲染成「—」
 ```
 
 第一个参数收 `Selection` 或手工挑的 `Snapshot[]`——和报告积木同一个输入约定。`artifacts` 的合法值是 `"events" | "trace" | "o11y" | "diff" | "sources"`，缺省全带。目标目录已存在且非空时报错，不静默覆盖——发布脚本要幂等就自己先清目标目录。
 
-复制不改工件内容、不消毒；发布前给自由文本消毒用报告积木 `CaseList.data` 的 `redact` 钩子。唯一随行补记的是挑选时的**覆盖事实**：`partial-coverage` 警告的分母是实验的历史并集，而发布目录没有历史——所以每个复制出的快照带上 `knownEvalIds`（复制时刻该实验已知的 eval 并集），reader 端把它并进 `exp.evalIds` 的计算（取本地历史与快照携带值的并集）。发布目录上重新 `openResults().latest()`，残缺警告被同一套机制重新算出来，不靠发布者转述。复制出的目录就是标准结果目录，`niceeval view --run <目录>` 直接能看；要让报告站随 push 自动更新，workflow 见[通过 CI 发布报告](/zh/guides/publish-report)。
+复制不改 artifact 内容、不消毒；发布前给自由文本消毒用报告积木 `AttemptList.data` 的 `redact` 钩子。唯一随行补记的是挑选时的**覆盖事实**：`partial-coverage` 警告的分母是实验的历史并集，而发布目录没有历史——所以每个复制出的快照带上 `knownEvalIds`（复制时刻该实验已知的 eval 并集），reader 端把它并进 `exp.evalIds` 的计算（取本地历史与快照携带值的并集）。发布目录上重新 `openResults().latest()`，残缺警告被同一套机制重新算出来，不靠发布者转述。复制出的目录就是标准结果目录，`niceeval view --run <目录>` 直接能看；要让报告站随 push 自动更新，workflow 见[通过 CI 发布报告](/zh/guides/publish-report)。
 
 ## 分层速览
 
@@ -221,4 +222,4 @@ await copySnapshots(results.latest(), "site-data/run", {
 | 报告积木 | [自定义报告](/zh/guides/custom-reports)、[报告组件](/zh/guides/report-components) | 自己的口径与摆法 |
 | 结果数据 API（本页） | `niceeval/results` | 折叠表达不了的算法、接自己的系统、读写格式本身 |
 
-每层都建立在下一层之上，同一份落盘工件是唯一事实来源——上层的派生物删了随时可重算。
+每层都建立在下一层之上，同一份落盘 artifact 是唯一事实来源——上层的派生物删了随时可重算。

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

@@ -49,7 +49,7 @@ npx niceeval exp local fixtures/button --runs 5 --early-exit
 
 ## 缓存
 
-[NiceEval](https://niceeval.com/) 可以根据输入、配置和相关文件 fingerprint 跳过已通过结果。缓存适合加速迭代，但如果你在调试非确定性行为，应该明确关闭或清理相关缓存。
+[NiceEval](https://niceeval.com/) 可以根据输入、配置和相关文件 fingerprint 跳过已判定为 `passed` 或 `failed` 的结果——两者都是判定确定的终态。`errored`（超时、沙箱异常等框架/环境层面的不确定失败）永远重试。缓存适合加速迭代，但如果你在调试非确定性行为，应该明确关闭（`--force`）或清理相关缓存。
 
 ## 超时和预算
 
@@ -72,7 +72,7 @@ runner 在 eval 完成后把结果交给 reporters：
 
 ## 输出目录
 
-每次运行会写入 `.niceeval/<timestamp>/`，包括 `summary.json`，以及每个 attempt 的 `events.json`、`sources.json`、`trace.json`、`o11y.json` 和 `diff.json` 等拆分工件。
+每次运行会写入该实验的结果快照目录 `.niceeval/<experiment>/<快照>/`，包括快照级 `snapshot.json`，以及每个 attempt 的 `result.json`（判决与断言）和按需生成的 `events.json`、`sources.json`、`trace.json`、`o11y.json`、`diff.json` 等拆分 artifact。
 
 ## 推荐调试流程
 

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

@@ -67,7 +67,7 @@ export default defineExperiment({
         args: ["-y", "@anthropic/mcp-browser"],
       },
     ],
-    skills: ["Effect-TS/skills"],
+    skills: [{ kind: "repo", source: "Effect-TS/skills", ref: "8f3c1a2" }],
   }),
   model: "claude-sonnet-4-6",
   sandbox: dockerSandbox(),
@@ -86,17 +86,22 @@ export default defineExperiment({
 
 ```text
 createSandbox
+  → sandbox spec 的 .setup() 钩子?    # 环境准备（按实验装东西）；没挂就跳过
   → git init && git commit
-  → adapter.setup?                 # 装 CLI / 写 agent 配置
-  → test(t): uploadDirectory(...)   # 写入这条 eval 的起始文件
+  → adapter.setup?                   # 装 CLI / 写 agent 配置
+  → test(t): uploadDirectory(...)     # 写入这条 eval 的起始文件
   → adapter.send(input, ctx)
-  → test(t): runCommand(...)        # 手工运行验证命令
-  → collectGeneratedFiles()         # git diff HEAD
+  → test(t): runCommand(...)          # 手工运行验证命令
+  → collectGeneratedFiles()           # git diff HEAD
+  → adapter.teardown?                 # agent 收尾
+  → sandbox spec 的 .teardown() 钩子?  # 环境收尾（如回存状态），销毁前最后跑
   → sandbox.stop()
 ```
 
 起始文件和验证命令都写在 `test(t)` 中。agent 执行阶段只能看到你已经写进 sandbox 的文件。
 
+环境钩子（`.setup()` / `.teardown()`）挂在 experiment `sandbox` 字段的 spec 上，用来做"按实验变化的环境准备"——装某个实验专属的二进制、预热、跨 attempt 载入和回存状态。它排在 git 基线之前，所以写下的文件不会被算进 agent 产出的 diff。写法和规则见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+
 ## 自定义 sandbox agent
 
 ```ts