niceeval 0.9.0 → 0.10.0

package/docs-site/zh/tutorials/custom-reports.mdx

@@ -0,0 +1,453 @@
+---
+title: "编写自定义报告"
+sidebarTitle: "自定义报告"
+description: "用 defineReport、内置报告组件和双面组件编写一份同时用于 niceeval show 与 niceeval view 的自定义报告。"
+---
+
+[查看结果](/zh/tutorials/viewing-results)介绍 `niceeval show` 的终端输出和 `niceeval view` 的网页输出。本教程用相同的结果数据编写考试成绩单、代码行数表和质量 × 成本图等自定义报告。
+
+一份报告对应一个报告文件：一棵由内置组件搭起来的树。`niceeval show` 和 `niceeval view` 打开结果、选出当前范围（Scope），交给这棵树渲染。把文件路径传给 `--report`，同一份定义在终端和网页都能渲染。自定义报告同样支持 Attempt 证据链接、`--results` 指定结果根和静态导出。
+
+## show / view 的默认报告也是一份报告文件
+
+`niceeval show` / `view` 不传 `--report` 时渲染的默认报告不是私有实现，而是包里自带的一个普通报告文件：报告、Attempts、追踪三个导航页，加一个不进导航、按 Attempt 定位符打开的详情页，每页都由 `niceeval/report` 公开导出的组件搭成。
+
+这份默认报告本身以 `standard` 为名从 `niceeval/report/built-in` 导出。只想在默认报告上加站点标题、GitHub 链接或统计脚本时，用 `extends` 在它上面叠自己的外壳，页面内容一行不用写；NiceEval 升级带来的页面改进也会自动跟过来：
+
+```tsx
+// reports/branded.tsx —— 默认报告整站 + 自己的标题和链接
+import { defineReport } from "niceeval/report";
+import { standard } from "niceeval/report/built-in";
+
+export default defineReport({
+  extends: standard,
+  title: "Memory Evals",
+  links: [{ label: "GitHub", href: "https://github.com/you/repo" }],
+});
+```
+
+`niceeval/report/built-in` 是内置报告的集合，每份一个名字；今天只有 `standard`，以后新增的内置报告也从这里按名字导入。想改页面内容本身，用同一批公开组件自己搭——你的报告文件能逐字写出同样的首页，也能只留自己要的部分：
+
+```tsx
+import { ExperimentComparison } from "niceeval/report";
+
+<ExperimentComparison />
+```
+
+`ExperimentComparison` 就是默认首页：一行组件直接对当前 Scope 计算范围摘要、成本 × 端到端成功率散点图和实验明细表，不需要额外取数。
+
+|  | 网页（人看） | 终端（agent 和你看） |
+| --- | --- | --- |
+| 官方默认 | 分组比较报告（网页面） | 同一分组比较报告（文本面） |
+| 自定义报告 | `niceeval view --report reports/exam.tsx` | `niceeval show --report reports/exam.tsx` |
+
+自定义报告分为三个层次：
+
+1. **调整布局**：用内置组件和 `Row` / `Col` 重新排列版面，需要自己分组或过滤时写一个组合组件。
+2. **换口径**：`defineMetric` 定义自己的指标，`flag()` / `label()` / `runConfig()` 定义自己的分组和坐标轴。
+3. **自定义组件**：表格用 `<Table>` 自定义列，其它展示用 `defineComponent` 分别实现网页和终端渲染。
+
+## 创建报告文件
+
+先交代唯一的前置：报告文件是 `.tsx`，写它的项目要装 `react`（写自定义组件的 web 面还要 `@types/react`），tsconfig 里 `compilerOptions.jsx` 设为 `"react-jsx"`。裸跑 `niceeval show` / `niceeval view` 不需要这些——只有自己写报告文件才需要。
+
+用 `defineReport` 声明一棵树。宿主打开结果目录(包括 `--results` 指定的结果根)，按默认规则选出当前 Scope,再把这份 Scope 交给树里每个组件——组件自己知道怎么从 Scope 取数,报告文件不需要手工传参:
+
+```tsx
+// reports/exam.tsx —— 终端和网页共用一份定义
+import {
+  defineReport, Col, Section,
+  ExperimentComparison, Scoreboard, examScore,
+} from "niceeval/report";
+
+export default defineReport(
+  <Col>
+    <ExperimentComparison />
+    <Section title="考试成绩单">
+      <Scoreboard
+        rows="agent"
+        questions={["security/sql-injection", "correctness/retry"]}
+        score={examScore}
+      />
+    </Section>
+  </Col>,
+);
+```
+
+```bash
+niceeval show --report reports/exam.tsx    # 终端：同一棵树走文本面
+niceeval view --report reports/exam.tsx    # 网页：渲染网页面，Attempt 链接进入证据页
+```
+
+`ExperimentComparison`、`Scoreboard` 这类组件省略 `input` 时都默认吃宿主选出的当前 Scope——不用在报告文件里手工取数再喂给它们。Scope 的挑选规则是：对每个实验、每道评估用例，取该实验历史运行里最新的那次判定；只按前缀重跑了一部分评估用例时，其余评估用例的判定从更早的运行补齐,不会因为一次局部重跑就整体退回某一份残缺快照。
+
+默认挑法不合口径,或者要按子集分别展示时,不能在报告树里直接写 JavaScript——树只负责声明,取数发生在组合组件里。用 `defineComponent` 写一个组合组件,函数体里能拿到 `ctx.scope`(当前 Scope)和 `ctx.results`(结果根的完整读取面,取历史快照用它),用普通 JavaScript 加工后再传给下游组件:
+
+```tsx
+import { ScopeSummary, Section, defineComponent } from "niceeval/report";
+
+const ProdSummary = defineComponent((_props: {}, ctx) => (
+  <Section title="生产实验">
+    <ScopeSummary input={ctx.scope.filter((s) => s.experimentId.startsWith("prod/"))} />
+  </Section>
+));
+```
+
+命令行的范围先作用在挑选上,组件拿到的就是收窄到这个范围后的 Scope:位置参数的评估用例 id 前缀收窄 Scope 覆盖的评估用例(覆盖提醒的分母同样收窄到范围内),`--results` 把结果根换成指定目录,`--exp` 让 Scope 只留该实验。`--history` 与 `--report` 互斥——趋势在报告里用 `ctx.results` 自己组织;证据视图(`--source` / `--execution` / `--diff`)只看证据,不渲染报告。
+
+报告树里的组件有两种数据形态。像上面这样省略 `data`、直接传计算选项(`rows`、`columns`、`questions` 这类)是 spec 形态,组件自己在渲染前取数;需要先用 JavaScript 过滤或加工时,改用组件配套的 `xxxData(scope, options)` 函数手工取数,再把结果传给 `data` prop——两种写法产出完全相同,选哪种只看要不要在取数和渲染之间插入自己的逻辑。完整的双形态契约和每个组件的字段见[报告组件](/zh/reference/report-components)。
+
+选择警告(`ScopeWarnings`)组件显示覆盖不全、快照过期、运行未完成和快照读取失败等提醒,按实验分组,组头列出实验名、问题标签和可复制的重跑命令,每条原文位于可展开区域中。默认报告的每一页都包含该组件;自定义报告需要显示提醒时,在页首添加 `<ScopeWarnings />`。
+
+页面里的每个组件都是**双面**的:网页面是 React 渲染,终端面是字符渲染,两面吃同一份算好的数据。实体列表按 experiment → Eval → Attempt 展示事实;指标表、矩阵、条形图、成绩单、散点图、趋势图和差异表展示聚合值。完整清单见[报告组件](/zh/reference/report-components)。网页面的实体、格子和点深链到 Attempt 详情,终端面印出对应的 `niceeval show <eval id>` 下钻命令。
+
+默认报告没有特权:它的四个页面全部由公开组件搭成。需要同样的当前 Scope 比较就写 `<ExperimentComparison />`;要子集就在报告里先 `filter`,或从 CLI 用 `--exp` 收窄。
+
+## 排版:内置排版原语
+
+排版原语也是双面组件,同一份布局会分别渲染到网页和终端:
+
+- **`<Col>`**:纵向依次排列——网页是块级堆叠,终端是逐块输出。
+- **`<Row>`**:并排——网页是横向排布,终端是字符分栏;终端宽度不够时自动降级为纵向,不硬挤。
+- **`<Grid columns={N}>` / `<Stat>`**:自由摘要格,一格一个 label-value 卡片;`columns` 是网页宽屏下最多摆几列,窄屏和终端都会自动减列,不丢格。见下文「自由摘要格」。
+- **`<Section title="…">`**:带标题的块,网页是标题层级,终端是标题行加缩进;可选 `meta` 是标题行右侧的短元信息,网页同行右对齐,终端放不下时换行。
+- **`<Text>`**:说明文字,网页是段落,终端是折行文本。
+- **`<Table>`**:自定义列的表——网页是 `<table>`,终端是按显示宽度对齐的字符表,中文列不撕歪。
+- **`<Tabs>` / `<Tab title="…">`**:一页里的并列视图,网页是可切换的 tab 条,终端按顺序全部输出——tab 是浏览状态,不是页面,内容多到终端读不动时是升级成单独页面的信号。
+
+```tsx
+<Row>
+  <Scoreboard rows="agent" questions={["security/sql-injection", "correctness/retry"]} score={examScore} />
+  <MetricTable rows="agent" columns={[endToEndPassRate, costUSD]} />
+</Row>
+```
+
+```text
+$ niceeval show --report reports/exam.tsx
+考试成绩单                          │  agent  pass  cost
+agent  总分       security  correctness │  bub    87%   $0.42
+bub    86.5/100   45/50    41.5/50  │  codex  80%   $0.51
+```
+
+页面树里只放双面组件和排版原语,不放裸 HTML 标签——终端面没法渲染一个 `<div>`。要自由内容,说明文字用 `<Text>`,更自由的走下面的自定义组件。
+
+## 按子集分组:组合组件 + filter
+
+需要按目录前缀把 Experiment 分成几组、每组单独摆一块摘要时,不需要专门的分组组件——写一个组合组件,在 `ctx.scope` 上 `filter`,把收窄后的 Scope 交给 `ScopeSummary`:
+
+```tsx
+// reports/groups.tsx —— 按 experiment id 前缀分组,每组一块 ScopeSummary
+import { Col, ScopeSummary, Section, defineComponent, defineReport } from "niceeval/report";
+
+const GroupBlocks = defineComponent((_props: {}, ctx) => {
+  const prefixes = ["agents/codex/", "agents/claude/"];
+
+  return (
+    <Col>
+      {prefixes.map((prefix) => (
+        <Section key={prefix} title={prefix}>
+          <ScopeSummary input={ctx.scope.filter((s) => s.experimentId.startsWith(prefix))} />
+        </Section>
+      ))}
+    </Col>
+  );
+});
+
+export default defineReport(<GroupBlocks />);
+```
+
+```text
+$ niceeval show --report reports/groups.tsx
+agents/codex/
+Pass rate 60% · 2 experiments · 6 evals · failed 1 · errored 1 · $1.50
+```
+
+在分组块后面加散点图或 Experiment 列表时,把同一份收窄后的 Scope 当 `input` 传给它们,或者用 `await experimentListData(scoped)` 拿到可自行过滤的数组。需要按其它维度(不是路径前缀)分组比较,用下文的 `MetricTable` 加自定义维度更直接。
+
+## 换口径:自定义指标
+
+实验、Eval、Attempt 的固定诊断字段由三个实体列表承接。下面的例子是另一种需求:用通用 `MetricTable` 自由换指标口径——每个指标的计算逻辑都挂在自己身上,换口径只需要换 `columns`:
+
+```tsx
+// reports/golf.tsx —— code-golf:只比通过方案的改动行数
+import {
+  MetricTable, costUSD, defineMetric, defineReport, endToEndPassRate,
+} from "niceeval/report";
+
+const changedLines = defineMetric({
+  name: "changed-lines",
+  label: { en: "Changed lines", "zh-CN": "改动行数" },
+  unit: "lines",
+  better: "lower",
+  where: (attempt) => attempt.result.verdict === "passed",
+  async value(attempt) {
+    const diff = await attempt.diff();
+    if (!diff) return null;
+    return Object.keys(diff.files)
+      .reduce((sum, path) => sum + (diff.get(path) ?? "").split("\n").length, 0);
+  },
+});
+
+export default defineReport(
+  <MetricTable
+    rows="agent"
+    columns={[endToEndPassRate, changedLines, costUSD]}
+    sort={endToEndPassRate}
+  />,
+);
+```
+
+```text
+$ niceeval show --report reports/golf.tsx
+agent   pass rate   changed lines   cost
+bub     87%         312 lines       $0.42
+codex   80%         355 lines       $0.51
+```
+
+格子里的终值是**两级折叠**出来的:同一道题的多个 attempt 先折成题级值(`perEval`),再跨题折成格子值(`acrossEvals`),两级默认都是平均。分两级不是形式主义——失败的题天然比通过的题 attempt 多(重试跑满、通过即停),平铺求均值会让分数和重试策略纠缠在一起。两级都能在 `defineMetric` 的 `aggregate` 里换:`aggregate: { perEval: "max", acrossEvals: "mean" }` 就是 pass@k(题内取最好一次,跨题取占比)。
+
+两个面继承同一套诚实契约:排序方向随指标的 `better`,覆盖不全的格子带 `12/15` 角标(15 个 attempt 里 12 个测得了该指标),缺数据渲染成 `—` 而不是 0。指标只定义一次,两个面共用——人在网页上看到的数字,就是 agent 在 stdout 里读到的数字,判断口径永远一致。给 agent 的指引也只多一行:跑 `niceeval show --report reports/golf.tsx`,读 stdout。
+
+`label` 可以是一份文案,也可以按语言给:`label: { en: "Changed lines", "zh-CN": "改动行数" }`——查看器界面切语言时,按语言给的 label 跟着切;只给一份就两种语言都用它。指标算出来的数字本身不分语言。
+
+内置指标里 `endToEndPassRate` / `taskPassRate` / `executionReliability` / `costUSD` / `durationMs` / `tokens` 只读 Attempt 自带的判定、用量这些字段,任何一份结果目录都算得出。没有限定词的"成功率"使用 `endToEndPassRate`:passed 记 1,failed 和 errored 都记 0。`taskPassRate` 只在形成可信判定的样本上衡量答题质量,errored 不参与;展示它时应明确写"可判定任务通过率",不能简称成功率。要区分答题质量和执行问题,把 `endToEndPassRate`、`taskPassRate`、`executionReliability` 三列并排。`assistantTurns`(o11y 事件流里的 assistant turn 数)不一样,它读 `attempt.o11y()`——这份数据 `copySnapshots` 缺省会随行,但如果发布脚本显式给了 `artifacts` 列表又没把 `"o11y"` 写进去,它就不在发布根里(见[结果数据 API](/zh/reference/results-data)的"发布"一节),指标渲染成 `—`,不是 0。自己写的指标只要读了 `o11y()` / `diff()` 这类 artifact(就像上面 `changedLines` 读 `attempt.diff()`),发布前都要过一遍同样的检查。
+
+## 换分组:三种来源
+
+维度决定分组——表的行、矩阵的行列、散点的点、趋势图的 x 轴。每个维度槽收三种值:
+
+- **内置维度**:`"agent"`、`"model"`、`"experiment"`、`"eval"`、`"evalGroup"`、`"snapshot"`,结果里现成的身份字段。
+- **自定义维度**:`{ name, of }`,一个纯函数吃 attempt、吐组名。定义只住在报告文件里,不用改任何 experiment 文件。
+- **声明式变量**:`flag()` / `label()` / `runConfig()`,分别引用 experiment 用 `flags`、`labels` 声明的变量和顶层运行配置。
+
+### 自定义维度:从已有数据派生分组
+
+分组能从现有结果数据**计算**出来时用自定义维度,不要求为了展示方式去改任何 experiment 文件。比如把不同模型折成厂商,按厂商比通过率:
+
+```tsx
+// reports/vendor.tsx
+import { MetricTable, costUSD, defineReport, endToEndPassRate } from "niceeval/report";
+import type { CustomDimension } from "niceeval/report";
+
+const vendor: CustomDimension = {
+  name: "vendor",
+  of: (a) => (a.snapshot.model?.startsWith("gpt-") ? "OpenAI" : "Anthropic"),
+};
+
+export default defineReport(
+  <MetricTable rows={vendor} columns={[endToEndPassRate, costUSD]} />,
+);
+```
+
+`of` 能读 attempt 的全部已有数据:`evalId`、`experimentId`、快照与判定里的字段。它只能派生、不能补造:如果两组 experiment 的差别只体现在文件命名里(`bub-baseline.ts` / `bub-mempal.ts`),`of` 就只能去解析这个名字——命名约定一改,分组静默散掉。这种时候变量该搬回配置,往下看。
+
+### 声明式变量:`flag()` / `label()` / `runConfig()`
+
+画"并行 agent 数 × 模拟延迟 × 得分"这类 scaling 趋势时,图上的变量不该编码进 experiment id(`ultra-16agents-300ms`),再在报告里解析字符串抠出来——那是约定不是配置,改个命名整张图就散。变量的家是 experiment 文件里声明的字段,三种来源对应三个构造器,不猜:
+
+- **`flag()` / `numericFlag()`** 读 `ExperimentDef.flags`——agent 和 eval 运行时也能看见的参数,比如并发数、延迟档位。
+- **`label()` / `numericLabel()`** 读 `ExperimentDef.labels`——只用于报告归类的标注,运行时不可见。
+- **`runConfig()` / `numericRunConfig()`** 读顶层运行配置(`model`、`reasoningEffort`、`budget`、`runs` 这类),名字点明读的是这次运行落盘的配置。
+
+```ts
+// experiments/ultra/agents-16.ts
+import { defineExperiment } from "niceeval";
+import { bub } from "../../agents/bub.ts";
+
+export default defineExperiment({
+  agent: bub({ mode: "ultra" }),
+  flags: { agents: 16, latencyMs: 300 },
+});
+```
+
+维度槽(`series` / `rows` / `columns` / `points`)用不加 `numeric` 前缀的版本按声明值分组;数值轴(`MetricLine` 的 `x`)必须用 `numericFlag()` / `numericLabel()` / `numericRunConfig()`,因为刻度要求真实数值:
+
+```tsx
+import { MetricLine, defineReport, endToEndPassRate, flag, numericFlag } from "niceeval/report";
+
+const agents = flag("agents", { label: "并行 agent 数" });
+const latency = numericFlag("latencyMs", { label: "Simulated latency", unit: "ms" });
+
+export default defineReport(
+  <MetricLine x={latency} series={agents} y={endToEndPassRate} />,
+);
+```
+
+未声明该变量的 Experiment 在分组时归入"未配置",用作坐标轴时不绘制该点并在注脚中计数。Flags 和 labels 随快照落盘,因此历史 run 也能按当时声明的变量重新分组。
+
+## 换形态:表格用 Table,摘要卡片用 Grid/Stat,其余自己画
+
+内置组件未覆盖的展示分三类:表格使用排版原语 `<Table>`;label-value 的自由摘要卡片使用 `<Grid>` / `<Stat>`;通过率条形图、预算燃尽图和项目徽章这类真正需要自己画的展示,才用 `defineComponent` 编写双面组件。
+
+### 一张表:`<Table>`
+
+列是你定的,格子是你算好的显示值,`<Table>` 负责把网页和终端两个面都排整齐:
+
+```tsx
+// reports/cost-board.tsx
+import {
+  defineReport, defineComponent, Table,
+  costUSD, endToEndPassRate, metricTableData,
+} from "niceeval/report";
+
+const CostBoard = defineComponent(async (_props: {}, ctx) => {
+  const board = await metricTableData(ctx.scope, {
+    rows: "agent",
+    columns: [endToEndPassRate, costUSD],
+  });
+  return (
+    <Table
+      columns={[
+        { key: "agent", header: "Agent" },
+        { key: "pass", header: "通过率", align: "right" },
+        { key: "cost", header: "成本", align: "right" },
+      ]}
+      rows={board.rows.map((r) => ({
+        key: r.key,
+        cells: {
+          agent: r.key,
+          pass: r.cells[endToEndPassRate.name].display,
+          // 缺数据交 null,组件渲染成 —;不要自己填 0
+          cost: r.cells[costUSD.name].value === null ? null : r.cells[costUSD.name].display,
+        },
+      }))}
+    />
+  );
+});
+
+export default defineReport(<CostBoard />);
+```
+
+```text
+$ niceeval show --report reports/cost-board.tsx
+Agent    通过率    成本
+bub         87%   $0.42
+codex       80%   $0.51
+克劳德        —       —
+```
+
+列宽按**终端显示宽度**计算,一个汉字占 2 列。`align: "right"` 让数字列右对齐。单元格值为 `null` 时渲染 `—`,不补 0。行上包含 `locator` 时会增加 Attempt 列;网页链接进入 Attempt 证据页,终端把 locator 交给 `niceeval show`。完整字段见[报告组件](/zh/reference/report-components)的"表格"一节。
+
+### 自由摘要格:`<Grid>` / `<Stat>`
+
+耗时、成本、参与率这类 label-value 速览数字,不用写 `defineComponent`——`<Grid>` 摆格子,`<Stat>` 摆每格的 label / 主值 / 辅助信息,两个面自动排版:
+
+```tsx
+// reports/run-summary.tsx
+import { Grid, Section, Stat, defineReport } from "niceeval/report";
+
+export default defineReport(
+  <Section title="运行速览" meta="4/4 完成">
+    <Grid columns={2} variant="boxed">
+      <Stat label="总耗时" value="12m 30s" />
+      <Stat label="总成本" value="$1.86" />
+      <Stat label="通过率" value="87%" tone="positive" />
+      <Stat label="失败数" value={2} detail="见下方 Attempt 列表" tone="negative" />
+    </Grid>
+  </Section>,
+);
+```
+
+`columns` 是宽屏下最多摆几列,窄屏和终端都会自动减列,不丢任何一格;加 `variant="boxed"` 给每格描边,省略就是默认的 `plain` 无框。`value` 收 `LocalizedText`、`number` 或 `null`——`null` 显示 `—`,数字 `0` 照常显示成 `0`,不当成缺数据;`tone`(`positive` / `negative` / `warning`,默认 `neutral`)是你自己对这个数字的判断,只给主值上色,组件不会替你从正负号猜。
+
+`Grid` 只管排版,不读 Scope、不聚合指标,`Stat.value` 必须是你已经算好的显示值。需要保留 `12/15` 这样的覆盖率角标和证据引用时,继续用[报告组件](/zh/reference/report-components)里的指标表这类数据组件;只有这种自由摘要卡片才用 `Grid` / `Stat`。
+
+### 不是表:`defineComponent` 加文本排版函数
+
+`defineComponent` 声明两个渲染面,和 `defineExperiment` / `defineMetric` / `defineReport` 同一个家族。终端面要自己排字符,用 `niceeval/report` 导出的这组函数——官方组件排的就是这几把尺子:
+
+| 函数 | 用途 |
+| --- | --- |
+| `stringWidth(text)` | 显示宽度:CJK 和全角字符记 2 列,其余记 1 列 |
+| `padEnd(text, width)` | 按显示宽度在右侧补齐(左对齐) |
+| `padStart(text, width)` | 按显示宽度在左侧补齐(右对齐,数字列用) |
+| `wrapText(text, width)` | 按显示宽度折行,返回若干行 |
+| `indent(block, prefix)` | 每行加缩进 |
+| `bar(ratio, width)` | 字符条:`█` 填充、`░` 补齐到 `width` |
+| `columns(blocks, widths, separator?)` | 多块并排 |
+
+**不要用 `String.prototype.padEnd` / `padStart` 对齐终端输出。** 它们数的是 UTF-16 码元,不是显示列宽:一个汉字占 2 列,却只算 1 个码元。用它们补齐,中文一进来列就错位,而中文 agent 名和中文题目名恰恰是最常见的情形。列宽也要随内容和 `ctx.width` 算,不要硬编码一个数字。
+
+```tsx
+// reports/passbars.tsx
+import {
+  defineReport, defineComponent, Col, Style, metricTableData,
+  bar, padEnd, stringWidth, endToEndPassRate,
+} from "niceeval/report";
+
+interface BarRow { key: string; ratio: number | null; display: string }
+
+const PassBars = defineComponent<{ rows: BarRow[] }>({
+  web({ rows }) {
+    return (
+      <ul className="passbars">
+        {rows.map((r) => (
+          <li key={r.key}>
+            <span>{r.key}</span>
+            <i style={{ width: `${(r.ratio ?? 0) * 100}%` }} />
+            <b>{r.ratio === null ? "—" : r.display}</b>
+          </li>
+        ))}
+      </ul>
+    );
+  },
+  text({ rows }, { width }) {
+    const label = Math.max(...rows.map((r) => stringWidth(r.key)));  // 列宽随内容
+    const barWidth = Math.min(20, width - label - 8);                // 也随可用列宽
+    return rows
+      .map((r) => {
+        const chart = r.ratio === null ? padEnd("—", barWidth) : bar(r.ratio, barWidth);
+        return `${padEnd(r.key, label)}  ${chart}  ${r.display}`;
+      })
+      .join("\n");
+  },
+});
+
+const PassBarsSection = defineComponent(async (_props: {}, ctx) => {
+  const board = await metricTableData(ctx.scope, { rows: "agent", columns: [endToEndPassRate] });
+  const rows = board.rows.map((r) => ({
+    key: r.key,
+    ratio: r.cells[endToEndPassRate.name].value,   // 格子键锚在指标对象上,不裸写字符串
+    display: r.cells[endToEndPassRate.name].display,
+  }));
+  return (
+    <Col>
+      <Style>{`.passbars li { display: flex; gap: 8px; } .passbars i { background: #4a7; height: 12px; }`}</Style>
+      <PassBars rows={rows} />
+    </Col>
+  );
+});
+
+export default defineReport(<PassBarsSection />);
+```
+
+```text
+$ niceeval show --report reports/passbars.tsx
+bub     █████████████████░░░  87%
+codex   ████████████████░░░░  80%
+克劳德  —                     —
+```
+
+组件的契约:
+
+- **计算发生在拿到 `ctx` 的地方,渲染面是纯函数。** 组合组件的函数体里能 `await` 读 attempt 句柄、折数据;双面组件的 `web` 和 `text` 只认已经算好的 props,零 IO、同步——这条边界让同一棵树能被烘进静态导出。
+- **渲染面接收上下文参数。** `text(props, ctx)` 的 `ctx.width` 是可用列宽(`Row` 分栏后会变窄),`ctx.attemptCommand(ref)` 生成查看命令;`web(props, ctx)` 的 `ctx.attemptHref(ref)` 生成 Attempt 证据链接。自定义组件与内置组件使用相同证据页。
+- **网页面静态渲染,不 hydrate。** 宿主在计算侧把 `web` 面渲染成静态 HTML,不打包你的代码进查看器:交互用普通链接和 `<details>`,与官方组件同一条静态契约。
+- **样式随树带走。** 静态导出不打包你的代码,`className` 引用的 CSS 用内置原语 `<Style>{css}</Style>` 放进页面树——web 面吐 `<style>` 标签,text 面渲染为空,上面的例子就是这么给 `.passbars` 上样式的。
+- **诚实契约同样适用。** 缺数据渲染 `—` 不补 0,截断如实标注剩余数量——上面例子里 `克劳德` 没有样本就是 `—`。
+
+## 发布:导出即静态站
+
+发布自定义报告和发布官方查看器是同一个动作——`--out` 加上 `--report`:
+
+```bash
+niceeval view --report reports/exam.tsx --out site
+```
+
+产物是纯静态文件。报告页是首页,transcript、trace 和代码等 Attempt 证据位于同一站点,报告中的数值可以链接到对应证据。组件不 hydrate;页面内联脚本提供表头排序、行过滤和图表悬停。浏览器禁用 JavaScript 时页面仍完整可读。CI 上没有 `.niceeval/` 时,先用 `copySnapshots` 生成经过大小检查的结果目录,再执行导出,流程见[查看结果](/zh/tutorials/viewing-results#导出与静态托管)。
+
+双面组件的网页面是普通 React 组件,`xxxData` 函数是普通 TypeScript 函数。需要在现有内部面板中复用指标表时,可以 import 组件并传入数据。计算与渲染分开部署时(例如 CI 生成 JSON、另一个应用 fetch),两侧必须使用相同 NiceEval 版本;组件数据不带版本信息,兼容性跟随包版本。
+
+## 自定义报告的边界
+
+一次只渲染一份报告,`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里,随文件一起递入,宿主不为它们长任何注册面。不传 `--report` 时渲染的就是默认报告,你的报告和它是同级实现。

package/docs-site/zh/{how-to → tutorials}/dataset-fanout.mdx

@@ -1,7 +1,7 @@
 ---
-title: "数据驱动测试（dataset fan-out）：用多份数据运行同一套 eval"
+title: "数据驱动测试（dataset fan-out）：用多份数据运行同一套评估用例"
 sidebarTitle: "数据驱动测试"
-description: "从 .eval.ts 文件导出数组或 keyed record，将一套 eval 逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。"
+description: "从 .eval.ts 文件导出数组或 keyed record，将一套评估逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。"
 ---
 
 数据驱动测试（dataset fan-out）适合大量结构相同、输入不同的测试。例如 SQL 生成、意图分类、检索问答和工具选择。
@@ -76,7 +76,7 @@ cases:
     sql: SELECT COUNT(*) FROM users;
 ```
 
-## 过滤数据集 eval
+## 过滤数据集评估用例
 
 ```bash
 # 运行整个数据集
@@ -101,5 +101,5 @@ npx niceeval exp local swelancer/15193
 </Tabs>
 
 <Tip>
-  数据集适合“横向覆盖”，独立 eval 文件适合“行为复杂”的场景。
+  数据集适合”横向覆盖”，独立评估用例文件适合”行为复杂”的场景。
 </Tip>

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

@@ -0,0 +1,103 @@
+---
+title: "实验矩阵：用运行矩阵比较 agents 和 models"
+sidebarTitle: "实验矩阵"
+description: "使用 NiceEval experiments 让同一批评估用例横跨多个 agents、models 和 flags，比较 pass rate、成本和延迟。"
+---
+
+Experiment 用于比较多组运行配置。典型比较包括 Claude Code 与 Codex 在同一批 Coding Agent 任务上的通过率、prompt 改动前后的成本，以及不同模型的延迟与质量。
+
+## 基本形状
+
+**一个实验文件 = 一个配置**（一个 agent × 一个 model）。路径只生成 experiment id 和支持前缀选择：
+
+```text
+experiments/
+  models/openai/gpt-5.4.ts
+  models/deepseek/v4-pro.ts
+```
+
+```ts
+// experiments/models/openai/gpt-5.4.ts
+import { defineExperiment } from "niceeval";
+import { webAgent } from "../../adapter/adapter.ts";
+
+export default defineExperiment({
+  description: "gpt-5.4: 对比模型",
+  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
+  model: "gpt-5.4",   // 单个字符串;另一个模型就复制一份文件改这一行
+  runs: 2,
+  earlyExit: true,
+});
+```
+
+```bash
+npx niceeval exp models
+```
+
+另一个模型写另一个文件。默认 `show` / `view` 直接比较当前结果范围里的 experiments，不需要额外分组字段。
+
+多层目录只负责 id 和批量选择：
+
+某一格结果反常、需要单独复现时，用该配置的完整 id（`目录路径/文件名`）精确只跑这一格，不用先批量运行同目录配置：
+
+```bash
+npx niceeval exp models/openai/gpt-5.4   # 精确 id
+npx niceeval exp models/openai           # 这一层目录下全部 experiment
+```
+
+目录里如果还有 `gpt-5.4-mini.ts` 这类共享前缀的变体，可以用文件名前缀选择：
+
+```bash
+npx niceeval exp models/openai/gpt
+```
+
+`defineExperiment` 的字段配置与 `flags` 传递方式见[写实验](/zh/tutorials/write-experiment)。
+
+## 可比较的运行维度
+
+- 不同 Adapters。
+- 不同模型（Tier 1 接入即可：应用接口暴露模型选择，`model` 经 `ctx.model` 透传）。
+- 不同 prompts 或 feature flags（要求 Tier 3 接入：变体在应用内部，需要应用把它暴露成 experiment 可选的 flag，经 `flags` → `ctx.flags` 透传）。
+- 不同 sandbox provider。
+- 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` Hook 里，一个变体一个 experiment 文件，见 [Sandbox provider · 生命周期](/zh/tutorials/sandbox-providers#生命周期)。
+- 同一任务的 pass@N。
+
+Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/explanation/tier)。
+
+## 查看结果
+
+Experiment 输出通常按 `(agent, model, eval)` 维度展示：
+
+```text
+api-validation   claude-code+zod-skill   pass@3 = 3/3 (100%)   mean 34s
+api-validation   claude-code             pass@3 = 1/3 (33%)    mean 41s
+```
+
+除了 pass rate，还应该看平均耗时、token、成本和失败类型。
+
+```bash
+npx niceeval show --exp models
+npx niceeval view
+```
+
+每个 experiment 用自己的 `evals` 选择评估用例。函数形式会遍历所有已发现的评估用例：
+
+```ts
+evals: (eval) =>
+  eval.id.startsWith("coding/") &&
+  eval.tags.includes("coding") &&
+  eval.environment !== "gpu"
+```
+
+`eval.id` 是文件路径推导出的项目内 ID，不是绝对路径，可以直接用 `startsWith` / `includes` 判断。在[评估用例](/zh/tutorials/authoring#tags-与-environment)里的两个例子中，`coding/fix-button` 会被选中，`research/gpu-literature` 不会。实验快照记录解析后的 `selectedEvalIds`；报告直接读取它。
+
+## 设计 experiment 的建议
+
+- 保持评估用例集合稳定，避免比较时混入新变量。
+- 每个 cell 跑多个 attempts，尤其是非确定性 coding agent。
+- 把预算和并发写清楚。
+- 对“失败原因”做归类，不只看总分。
+
+## 与普通运行的关系
+
+`npx niceeval exp <路径或 id>` 按文件身份运行；每个文件的 `evals` 决定它覆盖哪些评估用例，结果以 `selectedEvalIds` 落盘。

package/docs-site/zh/{how-to → tutorials}/fixtures.mdx

@@ -1,7 +1,7 @@
 ---
-title: "沙箱 Fixture：用任务评估 coding agents"
+title: "Sandbox Fixture：用任务评估 coding agents"
 sidebarTitle: "Fixture"
-description: "用 .eval.ts 给 coding agent 准备隔离 workspace、发送真实任务，并用 sandbox 文件、命令、diff 和 judge 验证结果。"
+description: "用 .eval.ts 给 coding agent 准备隔离 workspace、发送真实任务，并用 Sandbox 文件、命令、diff 和 judge 验证结果。"
 ---
 
 评估 coding agent 时，单纯检查一段回复不够。你通常要给它一个真实项目，让它读写文件、运行命令、提交改动，然后检查产物是否正确。[NiceEval](https://niceeval.com/) 的当前推荐写法是：用普通 `.eval.ts` 文件显式准备 sandbox workspace、发送任务并断言结果。
@@ -30,11 +30,11 @@ experiments/
 └─ with-skill.ts
 ```
 
-`workspaces/` 放 agent 可见的初始项目。`.eval.ts` 控制什么时候上传 workspace、发什么 prompt、检查什么结果。`experiments/` 决定用哪个 agent、哪个模型、是否注入 Skill 或插件。
+`workspaces/` 存放 Agent 可见的初始项目。`.eval.ts` 控制 Workspace 上传时机、任务 prompt 和结果检查。`experiments/` 选择 Agent、模型，以及是否注入 Skill 或插件。
 
 ## 准备 workspace
 
-在 eval 里把初始项目上传到 sandbox：
+在评估用例里把初始项目上传到 sandbox：
 
 ```ts
 import { defineEval } from "niceeval";
@@ -51,7 +51,7 @@ export default defineEval({
 });
 ```
 
-也可以用 `t.sandbox.writeFiles()` 在单个 eval 里补充种子文件，适合小任务或安全探针。
+也可以用 `t.sandbox.writeFiles()` 在单个评估用例里补充种子文件，适合小任务或安全探针。
 
 ## 写任务 prompt
 
@@ -88,7 +88,7 @@ t.check(code, excludes(/process\.env\.\w+\s*\?\?/));
 t.sandbox.fileChanged("src/config/env.ts");
 ```
 
-`t.sandbox.fileChanged()` 是作用域断言：它在运行结束后用 sandbox diff 判断目标文件是否真的被修改。
+`t.sandbox.fileChanged()` 是作用域断言：它在运行结束后用 Sandbox diff 判断目标文件是否真的被修改。
 
 ## 运行项目测试或探针脚本
 
@@ -125,7 +125,7 @@ t.check(result, commandSucceeded());
 
 ## 用 experiment 做对照组
 
-不要把 agent 名、插件名或 URL 放进位置参数。experiment 决定“对着哪个 agent、怎么跑”；CLI 的 eval 位置参数只过滤 eval ID。
+不要把 Agent 名、插件名或 URL 放进位置参数。Experiment 选择 Agent 并固定运行配置；CLI 的评估用例位置参数只过滤评估用例 ID。
 
 ```bash
 pnpm exec niceeval exp compare
@@ -136,9 +136,9 @@ pnpm exec niceeval exp compare api-validation
 
 - `experiments/baseline.ts`：裸 agent。
 - `experiments/with-skill.ts`：同一 agent + setup hook 注入 `CLAUDE.md`。
-- 两组使用同一批 eval、同一模型、同一 runs 和预算。
+- 两组使用同一批评估用例、同一模型、同一 runs 和预算。
 
-## 何时用 sandbox fixture
+## Sandbox Fixture 的适用场景
 
 - 需要 agent 修改真实文件。
 - 需要运行项目测试、构建或 lint。