niceeval 0.9.1 → 0.10.0

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

@@ -4,41 +4,57 @@ sidebarTitle: "报告组件"
 description: "报告文件里能摆的全部官方双面组件：每个组件回答什么问题、怎么调用、网页面长什么样、终端字符输出长什么样。"
 ---
 
-报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/how-to/custom-reports)）。每个组件的数据算法挂在它自己身上，组件名后打个点就找到，算和画永远配对。本页逐个列出官方组件：它展示哪一层数据、在报告里怎么调用、终端输出长什么样。
+报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/tutorials/custom-reports)）。每个组件要么直接写省略取数的写法（省略 `input`/`data` 时用当前 Scope 自动取数），要么显式传入自己算好的数据——两种写法产出完全相同，选哪种只看你要不要在取数和渲染之间插入自己的 JavaScript。本页逐个列出官方组件：它展示哪一层数据、在报告里怎么调用、终端输出长什么样。
 
 ## 名称与用途
 
-英文术语描述组件形态，API 名是代码里的导出名。组件分四类：默认组合件按可比组组织完整比较；实体列表逐项展示 experiment、Eval 或 Attempt；汇总组件概括整批 Selection；指标图形把指定维度聚合成值。三个实体列表的 `.data(selection)` 都返回普通数组，报告作者先用 JavaScript `.filter()` 收窄，再把 `items` 交给组件。过滤条件不藏在组件里。中文正文首次提到时用“中文名（`API 名`）”，后续可以只写中文名或 `API 名`。
+英文术语描述组件形态，API 名是代码里的导出名。默认组合件比较当前 Scope；范围摘要概括整批结果；实体列表逐项展示 experiment、评估用例或 Attempt；指标图形把指定维度聚合成值。
 
 | 分类 | 中文名 | 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 |
-| 实体列表 | Eval 列表 | Eval list | `EvalList` | 每项一个 experiment × Eval；展开到该 Eval 的 Attempt |
+| 组合 | 实验比较 | Experiment comparison | `ExperimentComparison` | 当前 Scope 的摘要、散点与实验列表 |
+| 汇总 | 范围摘要 | Scope summary | `ScopeSummary` | 一批结果：时间窗、数量、两级判定计票、端到端通过率与总成本 |
+| 实体列表 | 实验列表 | Experiment list | `ExperimentList` | 每项一个 experiment；展开到该 experiment 的评估用例 |
+| 实体列表 | 评估用例列表 | Eval list | `EvalList` | 每项一个 experiment × 评估用例；展开到该评估用例的 Attempt |
 | 实体列表 | Attempt 列表 | Attempt list | `AttemptList` | 每项一个 Attempt；显示断言、错误、Judge 评语和证据 |
+| 实体列表 | 失败列表 | Failure list | `FailureList` | `AttemptList` 的成品过滤：只列 failed / errored，按开始时间倒序 |
 | 指标图形 | 指标表 | Metric table | `MetricTable` | 一个可配置行维度；每格是一个聚合指标值 |
 | 指标图形 | 指标矩阵 | Metric matrix | `MetricMatrix` | 两个可配置维度的交叉格；每格是一个聚合指标值 |
 | 指标图形 | 分组条形图 | Grouped bar chart | `MetricBars` | 两个可配置维度形成分组和系列；每根条是一个聚合指标值 |
-| 指标图形 | 成绩单 | Scoreboard | `Scoreboard` | 每行一个可配置维度值；按 Eval 和 Eval 分组计算分数 |
+| 指标图形 | 成绩单 | Scoreboard | `Scoreboard` | 每行一个可配置维度值；按固定题集算总分和分科得分 |
 | 指标图形 | 指标散点图 | Metric scatter plot | `MetricScatter` | 每点一个可配置维度值，通常是 experiment；坐标是两个聚合指标值 |
-| 指标图形 | 指标趋势图 | Metric line chart | `MetricLine` | 每点一个 experiment；横轴是 experiment flag，纵轴是聚合指标值 |
+| 指标图形 | 指标趋势图 | Metric line chart | `MetricLine` | 每点一个 experiment；横轴是数值配置变量，纵轴是聚合指标值 |
 | 指标图形 | 成对差异表 | Paired delta table | `DeltaTable` | 每行一对 experiment 或结果快照；格内是指标值及差值 |
 
-`Row`、`Col`、`Section`、`Text`、`Style` 和 `Table` 是排版原语，不计算结果，因此不算一种分析图。它们的中文统称分别是行、列、分节、文本、样式和表格；代码里始终使用 API 名。
+`Row`、`Col`、`Grid`、`Section`、`Stat`、`Text`、`Style`、`Table`、`Tabs` 和 `Tab` 是十个排版原语，不计算结果，因此不算一种分析图。它们的中文统称依次是行、列、网格、分节、摘要项、文本、样式、表格、标签页和标签；代码里始终使用 API 名。
 
 所有组件共守同一套契约，下面不再逐个重复：
 
 - **诚实渲染。** 缺数据渲染 `—` 不补 0；覆盖不全的格子带 `12/15` 角标；截断如实标注剩余数量与原始 artifact 路径。
 - **排序与方向随指标的 `better`。** higher 的指标降序、lower 的升序，「好」的一头恒在上、在右上。
-- **证据室深链。** 网页面的格子、点和条目深链到 Attempt 详情；终端面用同一 Attempt locator 交给 `niceeval show @<id>`。
-- **终端输出形成反馈闭环。** 每个 Attempt 有一个以 `@` 开头的短 locator，例如 `@1k2m9qrs`。它唯一指向 experiment、结果快照、Eval 和 Attempt。`✓` / `✗` / `!` / `–` 是 passed / failed / errored / skipped。列表不用字母缩写编码证据可用性——locator 本身就是证据入口；打开 attempt（`niceeval show @<locator>`）后再列出实际可用的证据命令。执行步骤统一包含消息、thinking、tool call/result 和 Skill load；OTel 只给这些步骤补时间，不另开一份输出。
-- **两面同口径，网页面不依赖 JS 也完整。** 排序在计算时由 `sort` 定死，终端和网页看到同一份基准顺序；下钻是普通链接、展开折叠用 `<details>`。网页面另有一层浏览操作：点表头就地重排、榜单行过滤、图表点位悬停看数值——只影响眼前的视图，不改数据口径，刷新即回基准顺序；浏览器禁用 JS 时这些操作消失，内容一样不少（悬停信息退化为图内提示）。
+- **深链到 Attempt 详情。** 网页面的格子、点和条目深链到 Attempt 详情页；终端面用同一 Attempt 定位符交给 `niceeval show @<id>`。
+- **终端输出形成反馈闭环。** 每个 Attempt 有一个以 `@` 开头的短定位符，例如 `@1k2m9qrs`。它唯一指向 experiment、结果快照、评估用例和 Attempt。`✓` / `✗` / `!` / `–` 是 passed / failed / errored / skipped。列表不用字母缩写编码证据可用性——定位符本身就是证据入口；打开 attempt（`niceeval show @<定位符>`）后再列出实际可用的证据命令。执行步骤统一包含消息、thinking、tool call/result 和 Skill load；OTel 只给这些步骤补时间，不另开一份输出。
+- **两面同口径，网页面不依赖 JS 也完整。** 排序在计算时由 `sort` 定死，终端和网页看到同一份基准顺序；下钻是普通链接，展开折叠用 `<details>`。网页面另有一层浏览操作：点表头就地重排、榜单行过滤、图表点位悬停看数值——只影响眼前的视图，不改数据口径，刷新即回基准顺序；浏览器禁用 JS 时这些操作消失，内容一样不少（悬停信息退化为图内提示）。
+
+## 两种写法，同一份数据
+
+每个组件的 props 分两种写法，选哪种都行：
+
+```tsx
+// 省略 input/data：用宿主注入的当前 Scope 自动取数
+<MetricTable rows="agent" columns={[endToEndPassRate, costUSD]} filter />
+
+// 自己先算好数据再传：中间可以插入任意 JavaScript 加工
+<MetricTable data={await metricTableData(scope, { rows: "agent", columns: [endToEndPassRate, costUSD] })} filter />
+```
+
+两种写法产出完全相同；同一个组件同时给出 `data` 和取数选项会报错，两者二选一。所有计算函数的第一个参数都是 Scope（或手工挑的结果快照数组）；产出的数据都是普通可序列化 JSON，可以先存下来、传给别的进程，或者原样喂给对应组件的 `data` prop。`niceeval/report/react` 入口的同名组件只收 `data`，不做取数——那一层是纯 React 渲染，见[自定义报告](/zh/tutorials/custom-reports)。
+
+`evals` 是数据获取阶段唯一的过滤选项：评估用例 id 前缀，与 CLI 位置参数同语义，在聚合**之前**收窄题集。实体列表（`ExperimentList` / `EvalList` / `AttemptList`）不设这个选项——它们逐实体成行，取数后用普通数组 `.filter()` 收窄，效果和任何专门选项完全一样。
 
 ## 排版原语
 
-`Row` / `Col` / `Section` / `Text` 负责摆版面，一次摆放两个面各自成立：`Col` 纵向堆叠；`Row` 网页横排、终端字符分栏（宽度不够自动降级纵向）；`Section` 是带标题的块；`Text` 是说明文字。另有 `<Style>{css}</Style>` 给自定义组件带样式：web 面吐 `<style>` 标签、text 面渲染为空——静态导出不打包用户代码，`className` 引用的 CSS 靠它随树走。
+`Row` / `Col` / `Section` / `Text` 负责摆版面，一次摆放两个面各自成立：`Col` 纵向堆叠；`Row` 网页横排、终端字符分栏（宽度不够自动降级纵向）；`Section` 是带标题的块；`Text` 是说明文字。另有 `<Style>{css}</Style>` 给自定义组件带样式：网页面吐 `<style>` 标签、终端面渲染为空——静态导出不打包用户代码，`className` 引用的 CSS 靠它随树走。
 
 ```tsx
 <Col>
@@ -90,78 +106,114 @@ description: "报告文件里能摆的全部官方双面组件：每个组件回
 浏览/表单填写        —       —   @1qrdcfq8
 ```
 
-列宽按**终端显示宽度**算，中文和全角字符记 2 列——中文题目名、中文 agent 名都不会把表撕歪。`align: "right"` 让数字列右对齐，小数点自然对齐。格子是 `null` 就渲染 `—`，不补 0。行上带 `locator` 就多出一列 attempt：网页面链到证据室，终端面列出 locator，直接喂给 `niceeval show <locator>`。
+列宽按**终端显示宽度**算，中文和全角字符记 2 列——中文题目名、中文 agent 名都不会把表撕歪。`align: "right"` 让数字列右对齐，小数点自然对齐。格子是 `null` 就渲染 `—`，不补 0。行上带 `locator` 就多出一列 attempt：网页面链到 Attempt 详情，终端面列出定位符，直接喂给 `niceeval show <定位符>`。
 
 表比终端宽时先压最宽的左对齐列（按显示宽度折行），右对齐列不折行——数字折行读不了；压到下限仍放不下，就从右侧丢列，并在表下如实报丢了几列，不静默截断。
 
-指标表、指标矩阵、成绩单和成对差异表的终端面就建在 `Table` 上，所以你的表和官方的表用的是同一把尺子。表格之外的形态要自己排字符时，用[自定义报告](/zh/how-to/custom-reports)「换形态」一节里那套文本排版函数。
+某一列的格子只想显示前几行时，给这一列加 `maxLines`：超出的行丢弃，最后一行按显示宽度收口成 `…`；表头不受这个限制。网页面不消费这个字段——格子的高度由你自己的样式决定。
+
+指标表、指标矩阵、成绩单和成对差异表的终端面就建在 `Table` 上，所以你的表和官方的表用的是同一把尺子。表格之外的形态要自己排字符时，用[自定义报告](/zh/tutorials/custom-reports)「换形态」一节里那套文本排版函数。
 
-## 实验组比较（`ExperimentComparison`）
+## 摘要格（`Grid` / `Stat`）
 
-`niceeval show` / `view` 不传 `--report` 时使用的默认组合件。它先按 experiment id 的完整父目录分组，再为每组分别计算组摘要、成本 × 端到端成功率散点和实验列表：
+一批 label-value 的速览数字（耗时、成本、参与率这类）用 `Grid` 摆格子、`Stat` 摆每格的内容，两面都自动排版，不用自己写 CSS 或对齐字符：
 
 ```tsx
-<ExperimentComparison data={await ExperimentComparison.data(selection)} />
+<Grid columns={3} variant="boxed">
+  <Stat label="总耗时" value="12m 30s" />
+  <Stat label="总成本" value="$1.86" />
+  <Stat label="通过率" value="87%" detail="26 / 30" tone="positive" />
+</Grid>
+```
+
+```text
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ 总耗时       │ │ 总成本       │ │ 通过率       │
+│ 12m 30s     │ │ $1.86       │ │ 87%         │
+│             │ │             │ │ 26 / 30     │
+└─────────────┘ └─────────────┘ └─────────────┘
 ```
 
-`compare/bub` 与 `compare/codex` 属于 `compare`，可以横向比较；`dev-e2b/bub` 属于另一个组，不会进入同一张图、同一条 series 或同一张表。顶层 experiment 没有父目录时，以自己的完整 id 形成单例组。网页面持有完整组索引并一次聚焦一组，切组不重新读取 Selection；终端面命中多组时只显示组索引与单组查看命令，命中单组时才展开详情。浏览器禁用 JS 时，每组仍以独立 `<details>` 保留完整内容。
+`columns` 是网页宽屏下最多摆几列，必须是正整数；容器变窄或终端变窄时两个面各自减列，不丢任何一格。`variant="boxed"` 给每一格描边，默认 `"plain"` 无框；`density="compact"` 收紧格内留白，字号也跟着降一档，不改变内容。
+
+`Stat.value` 收 `LocalizedText`、`number` 或 `null`：`null` 显示 `—`，数字 `0` 照常显示成 `0`，不会被当成缺数据。`detail` 是主值下面的一行小字，省略就不留空行。`tone`（`neutral` / `positive` / `negative` / `warning`）是你对这个数字的语义判断，只给主值上色，组件不会替你从正负号或阈值猜。
 
-这个分区只属于默认组合件。下面的 `MetricScatter`、`MetricTable` 和 `ExperimentList` 都忠实消费调用方传入的数据；自定义报告把跨组 Selection 传给它们，就表示明确选择跨组分析。
+`Grid` 只管排版，不读 Scope、不聚合指标——`Stat.value` 必须是你已经算好的显示值。需要保留覆盖率角标（`12/15`）和证据引用时，继续用指标表这类数据组件；只有真正自由的摘要卡片才用 `Grid` / `Stat`。一格里要放两个 `Stat` 时，用 `Col` 把它们包起来，`Grid` 仍然只把这个 `Col` 算作一格。
 
-## 运行总览（`RunOverview`）
+`Section` 也多一个可选的 `meta`：标题行右侧的短元信息，比如「6/6 完成」。网页面和标题同一行右对齐，终端面空间不够时换到下一行，缩进两格。
 
-每张报告开头「这批数据是什么」：几个配置、几道题、通过分布、总成本、何时跑的；Selection 里的挑选警告随数据一起进来、直接显示在条内，诚实不用你另外传一遍。
+## 实验比较（`ExperimentComparison`）
+
+`niceeval show` / `view` 不传 `--report` 时使用的默认组合件。它把同一份 Scope 显式传给 `ScopeSummary`、成本 × 端到端通过率的 `MetricScatter` 和 `ExperimentList` 三个组件，自己不产出数据，也不合并三者的结果：
 
 ```tsx
-<RunOverview data={await RunOverview.data(selection)} />
+<ExperimentComparison />
 ```
 
-```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
-```
+每个 experiment 的评估用例集合来自快照记录的 `selectedEvalIds`。网页面与终端面都显示完整 Scope；需要子集时用 `--exp` 收窄，或在自定义报告里对 Scope 先 `.filter()` 再传给 `input`。
 
-## 组摘要（`GroupSummary`）
+组卡使用 `Pass rate / 通过率`、`Experiments / 实验`、`Evals / Eval`、`Attempts / Attempt`、`Eval results / Eval 结果`、`Total cost / 总成本` 这套字段标签，不在标签里重复“数”“次”或“计票”。时间显示为本地化到分钟的 `Last run / 最近运行` 或 `Run range / 运行范围`，不直接暴露 ISO 字符串；成本数据覆盖不全时写明“`63/72 次有成本数据`”，不显示没有上下文的 `63/72`。六项 KPI 在宽卡片保持同一行，空间不足时按三项或两项一组换行，避免总成本单独掉到下一行。
 
-一组 experiment（比如按目录前缀归在同一个 `<Section>` 里的那些 experiment）的紧凑统计块，回答「这组题综合算下来过了多少、花了多少、什么时候跑的」。组件本身不分组——先用 `Selection.filter` 把 Selection 收窄到这一组，再喂给 `GroupSummary.data`：
+下面的 `MetricScatter`、`ScopeSummary` 和 `ExperimentList` 同样忠实消费调用方传入的数据，不推导隐藏范围。它等价于把三个组件按下面这样手工摆放——想自定义顺序或搭配其它组件时，照这个形状写：
 
 ```tsx
-const scoped = selection.filter((s) => s.experimentId.startsWith("compare/"));
-
-<Section title="compare">
-  <GroupSummary data={await GroupSummary.data(scoped)} />
-</Section>
+export const MyComparison = defineComponent((_props, ctx) => (
+  <Col>
+    <ScopeSummary input={ctx.scope} />
+    <MetricScatter input={ctx.scope} points="experiment" x={costUSD} y={endToEndPassRate} />
+    <ExperimentList input={ctx.scope} filter />
+  </Col>
+));
 ```
 
-```text
-Pass rate 73.3% · 2 experiments · 15 evals · failed 3 · errored 1 · $0.93
-latest 2026-07-09T10:00:00Z
+## 范围摘要（`ScopeSummary`）
+
+每张报告开头「这批数据是什么」：几个配置、几道题、通过分布、总成本、什么时候跑的。评估用例的身份键是 `experimentId + evalId`：同一个评估用例在不同 experiment 中运行时算两个独立评估用例，数量和判定计票都按这个身份算。
+
+```tsx
+<ScopeSummary />                    // 当前 Scope 的摘要，Eval 级计票（默认）
+<ScopeSummary votes="attempt" />    // 同一份数据，改看 Attempt 原始计票
 ```
 
-通过率是 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`。
+数据本身恒携带两级计票，`votes` 只决定显示哪一级：
+
+- `votes="eval"`（默认）：每个 experiment × 评估用例先按「任一轮 passed 即 passed，否则 failed > errored > skipped」折成最终判定后计票，回答「多少道题最终通过」。
+- `votes="attempt"`：Attempt 原始计票，不折叠，回答「实际跑的每一轮各是什么结果」。
+
+两级计票与端到端通过率互不换算：通过率来自官方两级指标口径，不是从计票现场重新加总。选择警告不在这份数据里——警告的呈现件是 `ScopeWarnings` 组件，同一份事实不在页面上出现两次。
 
-组摘要是普通的公开组件，`GroupSummary.data` 是普通的公开计算函数——想在自己的报告里按目录前缀分组、每组摆一块，按上面的写法收窄 Selection 再调它就行。
+收窄范围时在自定义组件里显式传 `input`：
+
+```tsx
+const CompareSummary = defineComponent((_props, ctx) => (
+  <ScopeSummary input={ctx.scope.filter((s) => s.experimentId.startsWith("compare/"))} />
+));
+```
 
 ## 实验列表（`ExperimentList`）
 
-每项固定代表一个 experiment。主行显示 experiment id、agent、model、flags、Eval 判定构成、通过率、Tokens、成本和耗时；展开后显示这个 experiment 的 Eval 列表。Eval 父行显示折叠判定、Attempt 数、平均耗时和平均成本；下面每个 Attempt 再显示该轮自己的失败摘要。失败内容只出现一次，不会在 Eval 与唯一 Attempt 上重复。它不接受列配置——这是 experiment 的诊断视图，不是通用指标表。默认 `ExperimentComparison` 每次只把一个可比组的 items 交给它；组件本身不猜组边界。
+每项固定代表一个 experiment。主行显示 experiment id、agent、model、flags、评估用例判定构成、通过率、Tokens、成本和耗时。默认 `ExperimentComparison` 把当前 Scope 的全部条目交给它；组件本身不猜边界。
 
-默认比较已经用组名作面板 / 段落标题，所以组内每行的 experiment 标签会去掉这层文件夹前缀，只显示 id 末段（和同组散点的点标签一致），不在每行重复文件夹名；完整 id 仍是排序、着色和身份的依据。独立使用 `ExperimentList`、不告诉它相对哪个组时，显示完整 id。
+默认比较显示完整 experiment id；排序、过滤和身份也使用完整 id。中文副行用“`8 个 Eval`”而不是“`8 道题`”。
 
 ```tsx
-const experiments = await ExperimentList.data(selection);
+<ExperimentList filter />
+```
 
-<ExperimentList
-  items={experiments.filter((exp) => exp.verdicts.errored === 0)}
-/>
+要按前缀、agent 或状态过滤，先取数再用普通数组 `.filter()`：
+
+```tsx
+export const ProdExperiments = defineComponent(async (_props, ctx) => {
+  const items = await experimentListData(ctx.scope);
+  return <ExperimentList data={items.filter((x) => x.experimentId.startsWith("prod/"))} filter />;
+});
 ```
 
-`niceeval show` 先输出 experiment 比较表，再按 experiment 展开 Eval / Attempt 父子表。Eval 父行给题级平均值，Attempt 子行给这一轮的失败摘要和 locator：
+`niceeval show` 先输出 experiment 比较表，再按 experiment 展开评估用例 / Attempt 父子表。评估用例父行给题级平均值，Attempt 子行给这一轮的失败摘要和定位符：
 
 ```text
-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
+Experiment      Model     Agent   Avg. time   Pass rate   Results                 Tokens   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
@@ -172,20 +224,19 @@ Status      Eval / Attempt       Result                                  Duratio
   ✗         └─ @1nx4dpqr         calledTool("get_weather") · no calls    43.0s       $0.04
 ```
 
-locator 由 `experimentId + snapshot.startedAt + evalId + attempt index` 的不可变身份确定，复制或发布结果后保持不变。宿主在当前结果根解析 locator；不存在或发生冲突时直接报错，不回退到“最新一次”。`@` 前缀让它与 Eval ID 前缀选择器无歧义。
+定位符由 `experimentId + snapshot.startedAt + evalId + attempt 序号` 的不可变身份确定，复制或发布结果后保持不变。宿主在当前结果根解析定位符；不存在或发生冲突时直接报错，不回退到“最新一次”。`@` 前缀让它与评估用例 ID 前缀选择器无歧义。
 
-`.data(selection)` 返回普通的 `ExperimentListItem[]`，顺序按 experiment id 稳定排列。要只看某个 agent、目录前缀或运行状态，直接过滤数组。组件不提供另一套 `filter` 查询语法。网页面的文本搜索只是临时浏览操作，不改变传入的 items；终端面始终输出完整的传入数组。
+`experimentListData(scope)` 返回普通的 `ExperimentListItem[]`，顺序按 experiment id 稳定排列。要只看某个 agent、目录前缀或运行状态，直接过滤数组。组件不提供另一套查询语法。网页面的文本搜索只是临时浏览操作，不改变传入的条目；终端面始终输出完整的传入数组。
 
-## Eval 列表（`EvalList`）
+## 评估用例列表（`EvalList`）
 
-每项固定代表一个 `experimentId + evalId`，因为同一个 Eval 跑在两个 experiment 上是两条不同结果。主行显示判定、Attempt 数、聚合分数、平均成本和平均耗时；展开后显示这个 Eval 的 Attempt 列表，由每个 Attempt 行显示该轮自己的失败原因。Eval 主行不挑某一轮的失败原因冒充题级结论。
+每项固定代表一个 `experimentId + evalId`，因为同一个评估用例跑在两个 experiment 上是两条不同结果。主行显示判定、Attempt 数、聚合分数、平均成本和平均耗时；展开后显示这个评估用例的 Attempt 列表，由每个 Attempt 行显示该轮自己的失败原因。评估用例主行不挑某一轮的失败原因冒充题级结论。
 
 ```tsx
-const evals = await EvalList.data(selection);
-
-<EvalList
-  items={evals.filter((item) => item.verdict !== "passed")}
-/>
+export const FailingEvals = defineComponent(async (_props, ctx) => {
+  const items = await evalListData(ctx.scope);
+  return <EvalList data={items.filter((item) => item.verdict !== "passed")} />;
+});
 ```
 
 `niceeval show` 每个 `experiment × Eval` 输出一项，Attempt 仍用同一套紧凑 ID 和证据位。每项只给一条模板：
@@ -201,24 +252,24 @@ fixtures/button · compare/bub-gpt-5.4 · errored
   score — · 1 attempt · 2m 00s · $0.09
   @1c3h6twx! · command timed out after 120s
 
-inspect: niceeval show @<id> [--eval|--execution|--diff]
+inspect: niceeval show @<id> [--source|--execution|--diff]
 ```
 
-`.data(selection)` 返回普通的 `EvalListItem[]`。按 Eval id 前缀、experiment、判定或分数过滤都使用数组 `.filter()`；组件只负责渲染传入的 items。
+`evalListData(scope)` 返回普通的 `EvalListItem[]`。按评估用例 id 前缀、experiment、判定或分数过滤都使用数组 `.filter()`；组件只负责渲染传入的条目。
 
 ## Attempt 列表（`AttemptList`）
 
-每项固定代表一个 Attempt，显示 experiment、Eval、Attempt 序号、判定、耗时、成本、失败断言、结构化 error 的一层摘要、Judge 评语和证据链接。diagnostics、cause 和 stack 留给 locator 下钻详情，避免比较列表被基础设施日志撑开。它既能列失败证据，也能列通过样本，不把 verdict 过滤写死在组件名里。
+每项固定代表一个 Attempt，显示 experiment、评估用例、Attempt 序号、判定、耗时、成本、失败断言、结构化 error 的一层摘要、Judge 评语和证据链接。diagnostics、cause 和 stack 留给定位符下钻详情，避免比较列表被基础设施日志撑开。它既能列失败证据，也能列通过样本，不把判定过滤写死在组件名里。
 
 ```tsx
-const attempts = await AttemptList.data(selection);
-
-<AttemptList
-  items={attempts.filter((item) => item.verdict === "failed" || item.verdict === "errored")}
-/>
+export const RecentFailures = defineComponent(async (_props, ctx) => {
+  const all = await attemptListData(ctx.scope);
+  const failed = all.filter((x) => x.verdict === "failed" || x.verdict === "errored");
+  return <AttemptList data={failed.slice(0, 20)} total={failed.length} />;
+});
 ```
 
-`niceeval show` 每项完整输出一个 Attempt，不折叠到 Eval 汇总。这里已经是叶子层，只在末尾给一条与该 Attempt 可用证据对应的模板：
+`niceeval show` 每项完整输出一个 Attempt，不折叠到评估用例汇总。这里已经是叶子层，只在末尾给一条与该 Attempt 可用证据对应的模板：
 
 ```text
 ✗ @1k2m9qrs · weather/brooklyn · compare/bub-gpt-5.4 · 41s · $0.04
@@ -229,41 +280,53 @@ const attempts = await AttemptList.data(selection);
 
 ! @1c3h6twx · fixtures/button · compare/bub-gpt-5.4 · 2m 00s · $0.09
   command timed out after 120s
-inspect: niceeval show @<id> [--eval|--execution|--diff]
+inspect: niceeval show @<id> [--source|--execution|--diff]
 
 (3 more not shown · showing 20 of 23)
 ```
 
-要展示哪些 Attempt，过滤返回的 `AttemptListItem[]`。`limit` 也由报告作者在数组上用 `.slice(0, 20)` 表达，截断时把原始数量交给组件的 `total`，组件据此显示“还有 n 项未展示”，不静默截断。
+要展示哪些 Attempt，过滤返回的 `AttemptListItem[]`。截断数量也由报告作者在数组上用 `.slice(0, 20)` 表达，截断时把原始数量交给组件的 `total`，组件据此显示“还有 n 项未展示”，不静默截断。
+
+## 失败列表（`FailureList`）
+
+「现在有哪些失败要处理」是每份报告都要的固定区块，工具箱直接提供成品组合件，不用每次都重写同一段取数过滤。它和上面 `AttemptList` 的手工写法完全等价，只是把最常见的一种过滤打包好了：收 `verdict` 为 failed 或 errored 的 Attempt，按开始时间倒序（最近的失败在前），截断到 `limit`（默认 20）。
+
+```tsx
+<FailureList limit={30} />
+```
+
+要按 agent、成本或其它口径筛选，回到手写 `AttemptList` 的写法自己加工数组；`FailureList` 只覆盖这一种最常见的问题。
 
 ## 指标表（`MetricTable`）
 
-一行一个维度值、一列一个指标的对比表，回答「谁整体更好」。行维度、指标列、排序全部可换，自定义指标（`defineMetric`）与内置指标同列。
+一行一个维度值，一列一个指标，回答「谁整体更好」。行维度、指标列、排序全部可换，自定义指标（`defineMetric`）与内置指标同列。
 
 ```tsx
-<MetricTable data={await MetricTable.data(selection, {
-  rows: "agent",
-  columns: [endToEndPassRate, codeLines, costUSD],
-  sort: endToEndPassRate,
-})} />
+<MetricTable
+  rows="agent"
+  columns={[endToEndPassRate, examScore, costUSD, durationMs]}
+  sort={endToEndPassRate}
+  evals="coding/"
+  filter
+/>
 ```
 
 ```text
-agent   pass rate   code lines   cost
-bub     87%         312 lines    $0.42
-codex   80% 12/15   355 lines    $0.51
+agent   pass rate   examScore   cost
+bub     87%         0.91        $0.42
+codex   80% 12/15   0.86        $0.51
 ```
 
-两面都按 `sort` 预排，基准顺序一致——要固定换一种排序，改一行重跑。`12/15` 角标表示该格 15 个 attempt 里只有 12 个测得了这个指标。
+两面都按 `sort` 预排，基准顺序一致——要固定换一种排序，改一行重跑。`12/15` 角标表示该格 15 个 attempt 里只有 12 个测得了这个指标。`sort` 必须是 `columns` 中同一个 Metric 实例且声明了 `better`，否则报错；省略时按行 key 字典序，避免为方向不明的指标猜顺序。`filter` 只给网页面加行过滤框，不改变数据或终端输出。
 
-`rows: "experiment"` 时每行自动带 agent 与 model 列——结果里现成的元信息，不用配置。`MetricTable` 不展开实体层级：要看 experiment、Eval 或 Attempt 的固定诊断字段，分别使用三个实体列表；要自由换维度和指标列，使用指标表。
+`rows: "experiment"` 时每行自动带 agent 与 model 列——结果里现成的元信息，不用配置。`MetricTable` 不展开实体层级：要看 experiment、评估用例或 Attempt 的固定诊断字段，用上面三个实体列表；要自由换维度和指标列，用指标表。
 
 ## 指标矩阵（`MetricMatrix`）
 
 行 × 列两个维度、格子里一个指标，回答「哪道题谁挂了」。稀疏渲染：没有样本的格子空着，不编数。
 
 ```tsx
-<MetricMatrix data={await MetricMatrix.data(selection, { rows: "eval", columns: "agent", cell: endToEndPassRate })} />
+<MetricMatrix rows="eval" columns="agent" cell={endToEndPassRate} />
 ```
 
 ```text
@@ -279,14 +342,14 @@ next: niceeval show geometry/area
 
 ## 分组条形图（`MetricBars`）
 
-同一份矩阵数据的另一种摆法（`MetricBars.data` 就是 `MetricMatrix.data` 的别名）：按组并排比大小，回答「每个科目上谁领先、差多少」。组维度一组条、系列维度一根条、条长是指标值——benchmark 发布图（Terminal-Bench、BrowseComp 各一组，每个 agent 一根柱）就是这个形状。
+同一份矩阵数据的另一种摆法：按组并排比大小，回答「每个科目上谁领先、差多少」。组维度一组条、系列维度一根条、条长是指标值——benchmark 发布图（Terminal-Bench、BrowseComp 各一组，每个 agent 一根柱）就是这个形状。
 
 ```tsx
-<MetricBars data={await MetricBars.data(selection, {
-  rows: "evalGroup",        // 一组条 = 一个科目/benchmark
-  columns: "agent",         // 一根条 = 一个 agent
-  cell: endToEndPassRate,
-})} />
+<MetricBars
+  rows="evalGroup"        // 一组条 = 一个科目/benchmark
+  columns="agent"         // 一根条 = 一个 agent
+  cell={endToEndPassRate}
+/>
 ```
 
 ```text
@@ -298,19 +361,24 @@ geometry
   codex   —
 ```
 
-网页面是竖向分组柱：柱顶标数值，系列颜色与其它组件的稳定配色一致，图例自动生成。终端面横向条形，字符宽度即刻度，同组内按值排序（方向随 `better`）。`better: "lower"` 的指标（成本、耗时）条形反向填充，短条恒为「好」。
+网页面是竖向分组柱：柱顶标数值，系列颜色与其它组件的稳定配色一致，图例自动生成。终端面横向条形，字符宽度即刻度，同组内按值排序（方向随 `better`）。`better: "lower"` 的指标（成本、耗时）条形反向填充，短条恒为「好」。`MetricMatrix` 和 `MetricBars` 写同一份取数选项时，两个组件不会重复计算——只要 `input` 与选项相同，底层数据只算一次。
 
 ## 成绩单（`Scoreboard`）
 
-总分 + 分科小计，回答「这套题它能得几分」。逐题分值制：权重按 eval id 前缀配置，分母对所有被打分者恒定，没跑到的题挣 0 分并如实报 `missing`。
+总分 + 分科小计，回答「这套题它能得几分」。逐题分值制：权重按评估用例 id 前缀配置，分母对所有被打分者恒定，没跑到的题挣 0 分并如实报 `missing`。
 
 ```tsx
-<Scoreboard data={await Scoreboard.data(selection, {
-  rows: "agent",
-  subjects: "evalGroup",
-  weights: { "algebra/": 2 },
-  fullMarks: 100,
-})} />
+<Scoreboard
+  rows="agent"
+  questions={[
+    "security/sql-injection",
+    "security/path-traversal",
+    "correctness/retry",
+  ]}
+  weights={{ "security/": 3, "correctness/": 2 }}
+  fullMarks={100}
+  score={examScore}
+/>
 ```
 
 ```text
@@ -319,21 +387,20 @@ bub     86.5/100   45/50          41.5/50
 codex   71.0/100   40/50          31/50 (1 missing)
 ```
 
+`questions` 是显式固定题集，不从已观测的 Attempt 并集猜——所有配置都没跑到的题仍然留在分母里按 0 分计。分数为 `null`（跑了但测不了）与完全没跑到的题分开计数（分别是 `unscorable` 和 `unrun`），成绩单能回答「这 0 分是没去考还是考了判不了」。`score` 默认是 `examScore`，每道题必须产出 `[0, 1]`；总分是 `fullMarks × earned / possible`。
+
 ## 指标散点图（`MetricScatter`）
 
 每个点一个配置、两个指标各占一轴，回答「又好又便宜的是谁」。`series` 把同 agent 不同档位的点连成线；`better` 驱动轴向——`lower` 的轴反向画，「好」的角落恒在右上。
 
 ```tsx
-<MetricScatter
-  selection={selection}
-  points="experiment"       // 每个点 = 一个配置的聚合
-  series="agent"            // 同 agent 的档位连成线
-  x={costUSD}
-  y={endToEndPassRate}
-/>
+<MetricScatter points="experiment" series="agent" x={costUSD} y={endToEndPassRate} />
+
+// 同族变体连线：同 line 值的实验一色成线，connect 连出基线 → 变体的位移
+<MetricScatter points="experiment" series={label("line")} connect x={costUSD} y={endToEndPassRate} />
 ```
 
-直接把 `selection` 传给它，宿主渲染前替你算好数据。`MetricScatter` 不根据 experiment id 自动分组；默认 `ExperimentComparison` 会先收窄到一个可比组，再逐组调用它。要在自己已经跑起来的 React 应用里嵌这张图、或数据是预先算好的，改传 `data`：`<MetricScatter data={await MetricScatter.data(selection, { points: "experiment", series: "agent", x: costUSD, y: endToEndPassRate })} />`；同时传 `data` 和 `selection`、或两者都不传，类型检查都会报错。
+`MetricScatter` 直接消费传入的 Scope，宿主渲染前替你算好数据；默认 `ExperimentComparison` 也把当前 Scope 原样交给它。要嵌预先算好的数据，改传 `data`。
 
 ```text
 pass ↑                                    （好 → 右上）
@@ -347,18 +414,15 @@ pass ↑                                    （好 → 右上）
 A bub-high   B bub-medium   C codex-high   D codex-low
 ```
 
-网页面点带悬停提示（值与 `samples/total`，禁用 JS 时退化为图内提示）、同系列连线、点击深链下钻。终端面用字母标点、图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。画得出来的点是 0 个（x 或 y 全缺数据）时，两个面都明说这两个指标没有可用数据，不留一片空白；1 个点也照常出图——组件从不因为点不够就整块消失，让你不知道图为什么没了。维度槽也收自定义维度（`{ name, of }`，从 attempt 已有数据算组名）和 `flag()`（experiment 声明的变量），怎么选见[自定义报告](/zh/how-to/custom-reports)的「换分组」一节。
+网页面点带悬停提示（值与 `samples/total`，禁用 JS 时退化为图内提示）、同系列连线、点击深链下钻。终端面用字母标点，图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。画得出来的点是 0 个时，两个面都明说这两个指标没有可用数据，不留一片空白；1 个点也照常出图。维度槽也收自定义维度和 `flag()`（experiment 声明的变量），怎么选见[自定义报告](/zh/tutorials/custom-reports)的「换分组」一节。
 
 ## 指标趋势图（`MetricLine`）
 
-x 是有序变量、每个系列一条线，回答「变量拧大，分数怎么走」——并行 agent 数 × 模拟延迟 × 得分这类 scaling 图就是它。与 `MetricScatter` 的分工：散点图的两轴都是测出来的指标（找优势前沿），趋势图的 x 是你配置的变量（看趋势）。变量在 experiment 的 `flags` 里声明，报告用 `flag()` 直接引用，不从 experiment 命名里解析。
+x 是有序变量、每个系列一条线，回答「变量拧大，分数怎么走」——并行 agent 数 × 模拟延迟 × 得分这类 scaling 图就是它。与 `MetricScatter` 的分工：散点图的两轴都是测出来的指标（找优势前沿），趋势图的 x 是你配置的变量（看趋势）。变量在 experiment 的 flags 里声明，报告用 `flag()` 或数值型 flag 助手直接引用，不从 experiment 命名里解析。
 
 ```tsx
-<MetricLine data={await MetricLine.data(selection, {
-  x: flag("latencyMs", { label: "Simulated latency", unit: "ms" }),
-  series: flag("agents", { label: (v) => `${v} agents` }),
-  y: endToEndPassRate,
-})} />
+const budget = numericFlag("budget", { label: "Token budget", unit: "tokens" });
+<MetricLine x={budget} series="agent" y={endToEndPassRate} />
 ```
 
 ```text
@@ -376,20 +440,26 @@ pass ↑
 A 1 agents   B 4 agents   C 16 agents
 ```
 
-每个点是一个 experiment 的聚合，与其它组件同一台两级聚合引擎，`samples` / `total` / `refs` 一应俱全；同系列的点按 x 排序连线。网页面每个点可 hover、可深链下钻。终端面同系列共用一个字母、沿 x 排布，趋势肉眼可读；y 缺数据的点不画、注脚报数，点太密降级为坐标表。
+每个点是一个 experiment 的聚合，与其它组件同一套指标引擎；同系列的点按 x 排序连线。网页面每个点可 hover、可深链下钻。终端面同系列共用一个字母、沿 x 排布，趋势肉眼可读；y 缺数据的点不画、注脚报数，点太密降级为坐标表。
 
 ## 成对差异表（`DeltaTable`）
 
-每行一对配置、每列一个指标，格子里 A、B、Δ 三个值，回答「这个开关值不值」「这次修复翻转了什么」。涨跌好坏由 `better` 判定，任一侧缺数据 Δ 显示为缺，不硬算。「这次 vs 上次」（同一配置的两个结果快照）也是它：`pairs` 的 `a` / `b` 除 experiment id 外也收快照键 `<experimentId> @ <startedAt>`——时间轴对比要用到旧快照，`results.latest()` 里没有，配手挑的快照数组（如 `[exp.latest, exp.snapshots[1]]`）用。
+每行一对配置、每列一个指标，格子里 A、B、Δ 三个值，回答「这个开关值不值」「这次修复翻转了什么」。涨跌好坏由 `better` 判定，任一侧缺数据 Δ 显示为缺，不硬算。
 
 ```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: [endToEndPassRate, costUSD],
-})} />
+// 字面形态：逐对声明，label 自定义
+<DeltaTable
+  by="experiment"
+  pairs={[{ label: "memory", a: "compare/baseline", b: "compare/with-memory" }]}
+  metrics={[endToEndPassRate, costUSD, durationMs]}
+/>
+
+// 派生形态：按 flag 机械配对，加实验不用改报告
+<DeltaTable
+  by="experiment"
+  pairs={pairsByFlag("memory")}
+  metrics={[endToEndPassRate, costUSD, durationMs]}
+/>
 ```
 
 ```text
@@ -398,6 +468,8 @@ bub     87% → 93%   +6%        $0.42 → $0.45   +$0.03
 codex   80% → 80%   ±0         $0.51 → —       —
 ```
 
+「这次 vs 上次」（同一配置的两个结果快照）也是它：`pairs` 的 `a` / `b` 除 experiment id 外也收快照键 `<experimentId> @ <startedAt>`——手挑的快照数组（比如某个实验的最新一次和上一次）配这种写法。`pairsByFlag(name)` 按一个 flag 机械导出全部 A/B 对：实验矩阵是「同配置开关某个 flag」时，配对关系本来就是 experiment 配置的推论，手抄 id 字面量等于把配置复写进报告，加实验后报告会静默缺行。
+
 ## 官方组件之外
 
-以上摆法都表达不了时，用 `defineComponent` 写自己的双面组件——网页怎么渲染、终端字符怎么排，两个面你都说了算，写法见[自定义报告](/zh/how-to/custom-reports)的「换形态」一节。
+以上摆法都表达不了时，用 `defineComponent` 写自己的双面组件——网页怎么渲染、终端字符怎么排，两个面你都说了算，写法见[自定义报告](/zh/tutorials/custom-reports)的「换形态」一节。