niceeval 0.4.6 → 0.5.1

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

@@ -0,0 +1,252 @@
+---
+title: "报告组件一览"
+sidebarTitle: "报告组件"
+description: "报告文件里能摆的全部官方双面组件：每个组件回答什么问题、怎么调用、网页面长什么样、终端字符输出长什么样。"
+---
+
+报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/guides/custom-reports)）。每个组件的数据算法挂在它自己身上——`<MetricTable data={await MetricTable.data(selection, …)} />`，组件名后打个点就找到，算和画永远配对。本页逐个列出官方组件：它回答什么问题、在报告里怎么调用、终端输出长什么样。
+
+所有组件共守同一套契约，下面不再逐个重复：
+
+- **诚实渲染。** 缺数据渲染 `—` 不补 0；覆盖不全的格子带 `12/15` 角标；截断如实标注剩余数量与原始工件路径。
+- **排序与方向随指标的 `better`。** higher 的指标降序、lower 的升序，「好」的一头恒在上、在右上。
+- **证据室深链。** 网页面的格子、点和条目深链到 attempt 弹窗；终端面在条目下印 `niceeval show <eval id>` 下钻命令。
+- **两面同口径，网页面不 hydrate 也完整。** 排序在计算时由 `sort` 定死，两面预排一致；下钻是普通链接、展开折叠用 `<details>`；网页面不提供终端面没有的口径操作，静态导出零客户端 JS。
+
+## 排版原语
+
+`Row` / `Col` / `Section` / `Text` 负责摆版面，一次摆放两个面各自成立：`Col` 纵向堆叠；`Row` 网页横排、终端字符分栏（宽度不够自动降级纵向）；`Section` 是带标题的块；`Text` 是说明文字。另有 `<Style>{css}</Style>` 给自定义组件带样式：web 面吐 `<style>` 标签、text 面渲染为空——静态导出不打包用户代码，`className` 引用的 CSS 靠它随树走。
+
+```tsx
+<Col>
+  <Section title="考试成绩单">
+    <Row>
+      <Scoreboard data={board} />
+      <Text>algebra 权重 ×2，满分 100。</Text>
+    </Row>
+  </Section>
+</Col>
+```
+
+```text
+考试成绩单
+  agent  总分       algebra  geometry │ algebra 权重 ×2，
+  bub    86.5/100   45/50    41.5/50  │ 满分 100。
+  codex  78.0/100   40/50    38/50    │
+```
+
+## `DefaultReport` —— 官方水位整块
+
+官方两扇门裸跑时渲染的就是它：跨 run 合成的现刻榜单加失败清单，表头如实标注合成来源。零 props、纯声明——官方水位只读瘦身条目，宿主总是替你备好，经上下文注入。把官方水位铺进自己的报告时摆上它，不要就不摆：
+
+```tsx
+<DefaultReport />
+```
+
+```text
+Current verdicts · 2 experiments · composed from 3 runs · latest 2026-07-09T10-00-00-000Z
+
+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
+
+Failing:
+  ✗ weather/brooklyn   compare/codex-gpt-5.4   gate calledTool("get_weather")   41s ago
+```
+
+## `RunOverview` —— 页头 KPI 条
+
+每张报告开头「这批数据是什么」：几个配置、几道题、通过分布、总成本、何时跑的；选集里的挑选警告随数据一起进来、直接显示在条内，诚实不靠你记得接线。
+
+```tsx
+<RunOverview data={await RunOverview.data(selection)} />
+```
+
+```text
+2 experiments · 15 evals · 42 attempts · composed from 3 runs · latest 2026-07-09T10-00
+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` —— 榜单
+
+一行一个维度值、一列一个指标的对比表，回答「谁整体更好」。行维度、指标列、排序全部可换，自定义指标（`defineMetric`）与内置指标同列。
+
+```tsx
+<MetricTable data={await MetricTable.data(selection, {
+  rows: "agent",
+  columns: [passRate, codeLines, costUSD],
+  sort: passRate,
+})} />
+```
+
+```text
+agent   pass rate   code lines   cost
+bub     87%         312 lines    $0.42
+codex   80% 12/15   355 lines    $0.51
+```
+
+两面都按 `sort` 预排，看到同一份顺序——要换排序改一行重跑，不做单面才有的交互口径。`12/15` 角标表示该格 15 个 attempt 里只有 12 个测得了这个指标。
+
+## `MetricMatrix` —— 逐题格子
+
+行 × 列两个维度、格子里一个指标，回答「哪道题谁挂了」。稀疏渲染：没有样本的格子空着，不编数。
+
+```tsx
+<MetricMatrix data={await MetricMatrix.data(selection, { rows: "eval", columns: "agent", cell: passRate })} />
+```
+
+```text
+eval                bub    codex
+algebra/quadratic   100%   100%
+algebra/matrix      100%   67%
+geometry/area       50%    —
+
+next: niceeval show geometry/area
+```
+
+网页面点格子深链到该格的 attempt；终端面在表下印下钻命令。
+
+## `MetricBars` —— 分组条形
+
+同一份矩阵数据的另一种摆法（`MetricBars.data` 就是 `MetricMatrix.data` 的别名）：按组并排比大小，回答「每个科目上谁领先、差多少」。组维度一组条、系列维度一根条、条长是指标值——benchmark 发布图（Terminal-Bench、BrowseComp 各一组，每个 agent 一根柱）就是这个形状。
+
+```tsx
+<MetricBars data={await MetricBars.data(selection, {
+  rows: "evalGroup",        // 一组条 = 一个科目/benchmark
+  columns: "agent",         // 一根条 = 一个 agent
+  cell: passRate,
+})} />
+```
+
+```text
+algebra
+  bub     ██████████████████░░  91.9%
+  codex   █████████████████░░░  88.0%
+geometry
+  bub     ██████████░░░░░░░░░░  50.0%
+  codex   —
+```
+
+网页面是竖向分组柱：柱顶标数值，系列颜色与其它组件的稳定配色一致，图例自动生成。终端面横向条形，字符宽度即刻度，同组内按值排序（方向随 `better`）。`better: "lower"` 的指标（成本、耗时）条形反向填充，短条恒为「好」。
+
+## `Scoreboard` —— 考试成绩单
+
+总分 + 分科小计，回答「这套题它能得几分」。逐题分值制：权重按 eval id 前缀配置，分母对所有被打分者恒定，没跑到的题挣 0 分并如实报 `missing`。
+
+```tsx
+<Scoreboard data={await Scoreboard.data(selection, {
+  rows: "agent",
+  subjects: "evalGroup",
+  weights: { "algebra/": 2 },
+  fullMarks: 100,
+})} />
+```
+
+```text
+agent   total      algebra        geometry
+bub     86.5/100   45/50          41.5/50
+codex   71.0/100   40/50          31/50 (1 missing)
+```
+
+## `MetricScatter` —— 质量 × 成本 frontier
+
+每个点一个配置、两个指标各占一轴，回答「又好又便宜的是谁」。`series` 把同 agent 不同档位的点连成线；`better` 驱动轴向——`lower` 的轴反向画，「好」的角落恒在右上。
+
+```tsx
+<MetricScatter data={await MetricScatter.data(selection, {
+  points: "experiment",     // 每个点 = 一个配置的聚合
+  series: "agent",          // 同 agent 的档位连成线
+  x: costUSD,
+  y: passRate,
+})} />
+```
+
+```text
+pass ↑                                    （好 → 右上）
+ 90%│                                  A
+    │                     B
+ 75%│                          C
+ 60%│      D
+    └──────────────────────────────────────→ cost（轴反向：越右越省）
+     $0.60       $0.45       $0.30      $0.15
+
+A bub-high   B bub-medium   C codex-high   D codex-low
+```
+
+网页面点带 hover（值与 `samples/total`）、同系列连线、点击深链下钻。终端面用字母标点、图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。维度槽也收 `param()`——用 experiment 声明的变量分组，见[自定义报告](/zh/guides/custom-reports)的「变量来自配置」一节。
+
+## `MetricLine` —— 趋势线
+
+x 是有序变量、每个系列一条线，回答「变量拧大，分数怎么走」——并行 agent 数 × 模拟延迟 × 得分这类 scaling 图就是它。与 `MetricScatter` 的分工：scatter 的两轴都是测出来的指标（找 frontier），line 的 x 是你配置的变量（看趋势）。变量在 experiment 的 `params` 里声明，报告用 `param()` 直接引用，不从 experiment 命名里解析。
+
+```tsx
+<MetricLine data={await MetricLine.data(selection, {
+  x: param("latencyMs", { label: "Simulated latency", unit: "ms" }),
+  series: param("agents", { label: (v) => `${v} agents` }),
+  y: passRate,
+})} />
+```
+
+```text
+pass ↑
+ 80%│                   C···C
+    │            C···C            B
+ 60%│       C         B···B
+    │         B···B                        A
+ 40%│       A···A
+    │    A
+ 20%│
+    └───────────────────────────────────────────→ Simulated latency
+      1 min       5 min       10 min      20 min
+
+A 1 agents   B 4 agents   C 16 agents
+```
+
+每个点是一个 experiment 的聚合，与其它组件同一台两级聚合引擎，`samples` / `total` / `refs` 一应俱全；同系列的点按 x 排序连线。网页面每个点可 hover、可深链下钻。终端面同系列共用一个字母、沿 x 排布，趋势肉眼可读；y 缺数据的点不画、注脚报数，点太密降级为坐标表。
+
+## `DeltaTable` —— 成对对比
+
+每行一对配置、每列一个指标，格子里 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, {
+  pairs: [
+    { a: "compare/bub", b: "compare/bub--agents-md", label: "bub" },
+    { a: "compare/codex", b: "compare/codex--agents-md", label: "codex" },
+  ],
+  metrics: [passRate, costUSD],
+})} />
+```
+
+```text
+pair    pass rate              cost
+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`、`params`、`outcome` 和失败断言明细，方便在 Braintrust 里按维度过滤。
 
 ### 配置项
 

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

@@ -0,0 +1,224 @@
+---
+title: "用 niceeval/results 直接读写结果数据"
+sidebarTitle: "结果数据 API"
+description: "报告积木脚下的数据层：openResults 把 .niceeval/ 的落盘工件 parse 成「实验 → 快照 → eval → attempt」的类型化层次，createRunWriter 把别家结果写成 NiceEval 格式，copySnapshots 负责发布瘦身。"
+---
+
+[自定义报告](/zh/guides/custom-reports)的积木——指标、计算函数、双面组件——脚下还有一层：`niceeval/results`，落盘工件的 parser。官方两扇门和全部报告积木读的都是这一层，没有私有数据通道；报告表达不了的口径，下到这层直接拿数据算。
+
+什么时候下到这层：
+
+- **口径连计算函数都折不出。** 表格、矩阵、成绩单、散点都是「折叠」；分布类的看法（直方图、逐事件分析）不是折叠，要自己遍历 attempt。
+- **把结果喂进自己的系统。** 数据仓库、告警、内部平台——吃类型化数据，不吃磁盘布局。
+- **把别家平台的结果转成 NiceEval 格式。** 写入面保证「写出去的就是读得回的」，转完 `niceeval show` / `view` / 报告积木全套直接能用。
+
+这一层只管数据的读与写，不预设任何看法：不合并、不聚合、不去重，忠实反映磁盘。「怎么看」归上层的报告积木。
+
+## 读：`openResults`
+
+输入是 `.niceeval/` 目录（或单个 run 目录），输出是四层数据：**实验 → 快照（单次跑的实验）→ eval → attempt**。你从此不碰路径、不判断文件存在性、不解析 JSON：
+
+```typescript
+import { openResults } from "niceeval/results";
+
+const results = await openResults(".niceeval");
+
+results.experiments;           // Experiment[]:每个实验一项,挂着自己的全部历史
+results.skipped;               // 读不了的落盘:{ dir, reason, schemaVersion?, producer? }[]
+```
+
+**第一层，实验**——同一个 experiment id 的历次运行归在一起：
+
+```typescript
+const exp = results.experiments.find((e) => e.id === "compare/bub-gpt-5.4")!;
+
+exp.snapshots;                 // Snapshot[]:历次快照,最新在前
+exp.latest;                    // 最新一次(= snapshots[0])
+exp.evalIds;                   // 历史覆盖过的 eval 并集,残缺检测的依据
+```
+
+**第二层，快照**——单次跑的实验。它是谁、什么时候跑的、**用什么写的**，都在这一层：
+
+```typescript
+const snap = exp.latest;
+
+snap.agent;                    // 本快照自己的 agent
+snap.model;
+snap.startedAt;                // 这次实验什么时候跑的
+snap.producer;                 // { name: "niceeval", version: "0.4.6" } —— 谁写的这份结果
+snap.schemaVersion;            // 结果格式版本
+```
+
+**第三层，eval**——这次实验里的每道题，attempt（重试历史）挂在题下面：
+
+```typescript
+for (const ev of snap.evals) {
+  ev.id;                       // "algebra/quadratic"
+  ev.attempts;                 // AttemptHandle[]:该题的全部 attempt
+}
+snap.attempts;                 // 不关心题目边界时,全部 attempt 平铺
+```
+
+**第四层，attempt**——瘦身条目直接在手上，重工件全部懒加载。唯一带 `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 同一身份
+await attempt.events();        // StreamEvent[] | null
+await attempt.trace();         // TraceSpan[] | null
+await attempt.o11y();          // O11ySummary | null
+await attempt.diff();          // DiffData | null(可达上百 MB,所以必须懒)
+await attempt.sources();       // SourceArtifact[] | null
+```
+
+三条要点：
+
+- **懒加载即存在性判断。** 工件缺失返回 `null`，不抛错——remote agent 没有 `diff.json` 时，`await attempt.diff()` 就是 `null`，你据此决定跳过还是报缺。
+- **读不了的落盘不静默。** 版本不兼容、目录损坏的 run 进 `skipped` 并带原因；要不要展示由你定，但缺口永远被算出来。
+- **同进程内按句柄记忆化。** 两处都读同一个 `diff()` 不会把上百 MB 读两遍。
+
+## 版本：谁写的、读不读得了
+
+每个快照都带自己的出身：`producer` 是写这份结果的工具与版本（niceeval 自己，或经写入面转换的第三方 harness），`schemaVersion` 是磁盘格式版本。格式只在破坏兼容时递增版本，读取器只认相同版本——**版本不兼容的落盘不解析、不迁移、不猜**，整个 run 进 `skipped`：
+
+```typescript
+for (const s of results.skipped) {
+  s.reason;                    // "incompatible-version" | "malformed" | "incomplete"
+  s.schemaVersion;             // 那份结果声明的格式版本
+  s.producer;                  // { name, version }:谁写的它
+}
+```
+
+`"incomplete"` 与版本无关：run 中途 crash、没走到收尾写出 summary 的目录进这一类——已完成的 attempt 工件仍在盘上供手工排查，但没有 summary 的落盘对读取面不可见。
+
+旧版本的结果不会丢：磁盘上原样还在，用写它的那个工具就能看——`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` 触达（发布、排查工件路径时用），多数消费方不需要碰。
+
+## 选快照：`results.latest()`
+
+多数场景先回答「现在什么水位」，选择器替你挑「每个实验最新一次」——这也是官方榜单的口径。返回的是一个**选集（Selection）**，快照和警告绑在一起走：
+
+```typescript
+const latest = results.latest({
+  experiments: "compare/",     // 可选:experiment id 前缀过滤(string | string[]),同 CLI 前缀语义
+});
+
+latest.snapshots;              // Snapshot[]:每个实验最新一次
+latest.warnings;               // 结构化警告,不是渲染好的文本
+```
+
+「最新」可能残缺：只重跑一道题是正常的 debug 姿势，它产出的最新快照就只有一道题。选择器把每个选中快照的覆盖与该实验的历史并集（`exp.evalIds`）对比，缩水就写进 `warnings`：
+
+```typescript
+latest.warnings[0];
+// {
+//   kind: "partial-coverage",
+//   experimentId: "midterm/bub-gpt-5.4",
+//   covered: 1,
+//   total: 50,
+//   message: "snapshot covers 1 of 50 evals seen in history; re-run `niceeval exp midterm/bub-gpt-5.4` for a full snapshot",
+// }
+```
+
+字段供程序判断——CI 里「覆盖缩水就 fail」直接判 `covered < total`，不解析文本；`message` 是渲染好的英文句子，要展示就原样打。渲染与否在你，缺口永远被算出来。警告不止这一种：快照落后于选集中最新的落盘、experimentId 缺失被合成键等同样进 `warnings`，每种都带 `kind`、可判断的结构化字段和渲染好的 `message`。
+
+选集是[报告积木](/zh/guides/custom-reports)和下文 `copySnapshots` 的通用输入：收 `Selection` 时 warnings 随行（`RunOverview` 之类的组件会如实展示），手工挑的 `Snapshot[]` 数组照收。微调官方口径不用降级成裸数组：`latest.filter((s) => s.experimentId !== "compare/broken")` 返回新选集——快照被删减，warnings 修剪到幸存的实验，provenance 不丢。`filter` 只做删减；「换成该实验上一个完整快照」这类**替换式**重挑不是它的事，回到 `exp.snapshots` 自己拿——手工挑的数组没有挑选过程，自然没有 warnings 可带，也如实。
+
+## 一个真实脚本：分布不是折叠
+
+「每个 agent 的 shell 命令数分布」画不成表格——那是分布，不是折叠。直接遍历：
+
+```typescript
+import { openResults } from "niceeval/results";
+
+const results = await openResults(".niceeval");
+const points = [];
+for (const exp of results.experiments) {
+  for (const attempt of exp.latest.attempts) {
+    const o11y = await attempt.o11y();
+    points.push({
+      agent: exp.latest.agent,
+      eval: attempt.evalId,
+      passed: attempt.result.outcome === "passed",
+      shellCommands: o11y?.shellCommands.length ?? 0,
+    });
+  }
+}
+```
+
+即使在这条最深的路径上也不碰磁盘布局：路径拼接、存在性、版本过滤、快照切分全被库消化。要把这份分布摆进报告页，用 [`defineComponent`](/zh/guides/custom-reports) 包一个双面组件即可。
+
+一条跨快照累计时的义务：`--resume` 会把上一轮已通过的结果原样合入新 run，同一个 attempt 因此可能存在于多份落盘。合入的条目不是空壳：它的工件仍在原 run 目录，懒加载会自动回退到那里读（原 run 目录被清理后如实返回 `null`）；`ref` 指向条目所在的落盘。身份键 `(experimentId, evalId, attempt, startedAt)` 的四个字段都在数据上——前两个是 attempt 的直达字段，序号与 `startedAt` 在 `attempt.result` 上。reader 忠实反映这份重复；跨快照聚合前用 `dedupeAttempts` 按身份键去重，重复保留最新 run 目录里的那份——报告积木的计算函数内置这条，自己写脚本时记得过一遍：
+
+```typescript
+import { dedupeAttempts } from "niceeval/results";
+
+const all = exp.snapshots.flatMap((s) => s.attempts);   // 跨快照累计:历史全量
+const { attempts, warnings } = dedupeAttempts(all);      // resume 合入的重复被折掉
+```
+
+## 写：`createRunWriter`
+
+写入面和读取面是同一组类型的两半，签名就是 roundtrip 的证明：reader 的 `attempt.result` 由两部分拼成——快照级字段（agent / model / startedAt / producer）来自 `writer.snapshot()` 的一次声明，其余全部字段就是 `writeAttempt` 第一个参数的类型；第二个参数是 reader 懒加载能拿到的那几样工件的类型。「writeAttempt 参数 + snapshot() 声明 = reader 读回的全部」由类型拼合背书：快照级字段不在 attempt 参数的类型里，不存在「谁的值为准」。用它把别家平台、自研 harness 的结果转成 NiceEval 格式：
+
+```typescript
+import { createRunWriter } from "niceeval/results";
+
+const writer = await createRunWriter(".niceeval", {
+  producer: { name: "my-harness", version: "1.0.0" },
+});
+
+const snap = writer.snapshot({         // 快照级元数据的家:一个 experiment 开一个
+  experiment: "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
+    diff: r.diff,
+  });                                  // 拆工件文件、算目录、回填引用,全在库内发生
+}
+
+await writer.finish();                 // summary 从已写入的 attempt 推导,计数永远和条目对得上
+```
+
+`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")`，不认半份落盘。
+
+## 发布：`copySnapshots`
+
+把选中的快照按格式感知地复制到发布目录——只带指定工件、只带选中的 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,发布时常见地不带
+});
+```
+
+第一个参数收 `Selection` 或手工挑的 `Snapshot[]`——和报告积木同一个输入约定。`artifacts` 的合法值是 `"events" | "trace" | "o11y" | "diff" | "sources"`，缺省全带。目标目录已存在且非空时报错，不静默覆盖——发布脚本要幂等就自己先清目标目录。
+
+复制不改工件内容、不消毒；发布前给自由文本消毒用报告积木 `CaseList.data` 的 `redact` 钩子。唯一随行补记的是挑选时的**覆盖事实**：`partial-coverage` 警告的分母是实验的历史并集，而发布目录没有历史——所以每个复制出的快照带上 `knownEvalIds`（复制时刻该实验已知的 eval 并集），reader 端把它并进 `exp.evalIds` 的计算（取本地历史与快照携带值的并集）。发布目录上重新 `openResults().latest()`，残缺警告被同一套机制重新算出来，不靠发布者转述。CI 静态托管的完整流程见[查看结果 · 导出与静态托管](/zh/guides/viewing-results#导出与静态托管)。
+
+## 分层速览
+
+| 层 | 入口 | 回答 |
+| --- | --- | --- |
+| 官方两扇门 | `niceeval show` / `niceeval view` | 零代码看官方摆法 |
+| 报告积木 | [自定义报告](/zh/guides/custom-reports)、[报告组件](/zh/guides/report-components) | 自己的口径与摆法 |
+| 结果数据 API（本页） | `niceeval/results` | 折叠表达不了的算法、接自己的系统、读写格式本身 |
+
+每层都建立在下一层之上，同一份落盘工件是唯一事实来源——上层的派生物删了随时可重算。

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

@@ -29,7 +29,7 @@ npx niceeval exp local weather
 npx niceeval exp local fixtures/button
 ```
 
-不要把 agent 名放进位置参数。agent/model/flags 写进 experiment。
+不要把 agent 名放进位置参数。agent/model/params 写进 experiment。
 
 ## 并发
 

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

@@ -115,9 +115,9 @@ export default defineSandboxAgent({
 });
 ```
 
-## `ctx.model` 与 `ctx.flags`
+## `ctx.model` 与 `ctx.params`
 
-CLI 传入的模型和自定义 flags 会出现在 adapter context 中。adapter 可以决定如何把它们转成 CLI 参数或 HTTP payload。
+CLI 传入的模型和自定义 params 会出现在 adapter context 中。adapter 可以决定如何把它们转成 CLI 参数或 HTTP payload。
 
 ## 在 experiment 中使用自定义 agent