niceeval 0.9.0 → 0.10.0

package/dist/report/web.d.ts

@@ -1,32 +0,0 @@
-import type { AttemptLocator } from "../results/locator.ts";
-import type { Scope } from "../results/types.ts";
-import { type ReportLocale } from "./locale.ts";
-import { type ReportDefinition, type ReportHostContext } from "./report.ts";
-export interface StaticHtmlOptions {
-    /** 渲染哪一页;缺省第一页。未命中抛 ReportPageNotFoundError。 */
-    pageId?: string;
-    /** 证据室深链;缺省用 view 的 attempt 路由 `#/attempt/@<locator>`(单段、不透明)。 */
-    attemptHref?: (locator: AttemptLocator) => string;
-    /** 官方组件 chrome 文案的 locale;默认 "en"。 */
-    locale?: ReportLocale;
-}
-/**
- * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
- * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外另设警告通道——
- * 挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是
- * 作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
- */
-export declare function renderReportToStaticHtml(definition: ReportDefinition, ctx: ReportHostContext, options?: StaticHtmlOptions): Promise<string>;
-/**
- * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
- * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
- * ctx.report 是宿主规范化后的声明。
- */
-export declare function renderReportTreeToStaticHtml(tree: import("./tree.ts").ReportNode, ctx: {
-    scope: Scope;
-    results: import("../results/types.ts").Results;
-    report: import("./report.ts").ReportMeta;
-}, options?: {
-    attemptHref?: (locator: AttemptLocator) => string;
-    locale?: ReportLocale;
-}): Promise<string>;

package/dist/report/web.js

@@ -1,48 +0,0 @@
-// web 宿主(view --report)的装载入口:同一棵树走 web 面,renderToStaticMarkup 吐静态
-// HTML 烘进查看器的报告槽。只有这一侧真正 import react-dom(import 边界即运行时边界),
-// 所以本文件不从 niceeval/report 的入口 re-export —— 宿主与测试按源路径 import。
-import { renderToStaticMarkup } from "react-dom/server";
-import { resolveReportTree, runWithWebContext, validateReportTree, ResolveMemo, } from "./tree.js";
-import { DEFAULT_REPORT_LOCALE } from "./locale.js";
-import { buildReportMeta, pickReportPage } from "./report.js";
-/**
- * web 宿主的装载语义:选页 → resolve(组合展开 + spec 取数,唯一的 await 边界)→
- * 树校验(与 text 宿主同一遍)→ 静态渲染 web 面。宿主不在报告树外另设警告通道——
- * 挑选警告的呈现件是 `ScopeWarnings` 组件,内建报告每页都放它,自定义报告放不放是
- * 作者义务(docs/feature/reports/architecture.md「Scope 是计算入口」)。
- */
-export async function renderReportToStaticHtml(definition, ctx, options) {
-    const page = pickReportPage(definition, options?.pageId);
-    const meta = buildReportMeta(definition, ctx.scope, page.id);
-    const resolved = await resolveReportTree(page.content, {
-        scope: ctx.scope,
-        results: ctx.results,
-        report: meta,
-        memo: new ResolveMemo(),
-    });
-    validateReportTree(resolved);
-    const webCtx = {
-        attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
-        locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
-    };
-    return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
-}
-/**
- * 渲染一页报告树的 web 面(宿主逐页调用;页选择归宿主):resolve → validate → 静态渲染。
- * 挑选警告由页内的 `ScopeWarnings` 组件呈现,宿主不前置任何树外块。
- * ctx.report 是宿主规范化后的声明。
- */
-export async function renderReportTreeToStaticHtml(tree, ctx, options) {
-    const resolved = await resolveReportTree(tree, {
-        scope: ctx.scope,
-        results: ctx.results,
-        report: ctx.report,
-        memo: new ResolveMemo(),
-    });
-    validateReportTree(resolved);
-    const webCtx = {
-        attemptHref: options?.attemptHref ?? ((locator) => `#/attempt/${locator}`),
-        locale: options?.locale ?? DEFAULT_REPORT_LOCALE,
-    };
-    return runWithWebContext(webCtx, () => renderToStaticMarkup(resolved));
-}

package/docs-site/zh/how-to/authoring.mdx

@@ -1,162 +0,0 @@
----
-title: "编写 eval: 单轮、多轮和数据集模式"
-sidebarTitle: "编写 eval"
-description: "学习如何用 defineEval 编写 NiceEval eval，包括单轮断言、多轮对话、数据驱动测试和 sandbox workspace。"
----
-
-每个 [NiceEval](https://niceeval.com/) eval 都是一个 TypeScript 文件，默认导出 `defineEval(...)`。核心原则是：**路径即身份**、**一个文件一个 eval**、**线性书写并就地断言**。
-
-## `defineEval` 的结构
-
-```ts
-import { defineEval } from "niceeval";
-
-export default defineEval({
-  description?: string;
-  tags?: string[];
-  judge?: JudgeConfig;
-  reporters?: Reporter[];
-  timeoutMs?: number;
-  metadata?: Record<string, unknown>;
-  async setup(sandbox, ctx) { /* task fixture + progress/diagnostic */ },
-  async test(t) { /* interactions + assertions */ },
-});
-```
-
-<Warning>
-  不要设置 `id` 或 `name`。`evals/weather/brooklyn.eval.ts` 会自动变成 ID `weather/brooklyn`。
-</Warning>
-
-## 单轮 eval
-
-```ts
-import { defineEval } from "niceeval";
-import { includes } from "niceeval/expect";
-
-export default defineEval({
-  description: "Brooklyn weather query",
-  async test(t) {
-    await t.send("What's the weather like in Brooklyn today?");
-    t.succeeded();
-    t.calledTool("get_weather", { input: { city: "Brooklyn" }, count: 1 });
-    t.check(t.reply, includes("sunny"));
-  },
-});
-```
-
-`t.send()` 驱动一次交互，`t.succeeded()` 和 `t.calledTool()` 是作用域断言，`t.check()` 是立即记录的值断言。
-
-### `Turn` 对象
-
-| 属性 | 说明 |
-|---|---|
-| `turn.events` | 标准事件流，主要事实来源 |
-| `turn.data` | 结构化输出 |
-| `turn.status` | `"completed"`、`"failed"` 或 `"waiting"` |
-| `turn.usage` | token / cost 等 usage |
-| `turn.message` | assistant 文本回复 |
-| `turn.toolCalls` | 本轮工具调用 |
-
-## 多轮 eval
-
-```ts
-export default defineEval({
-  description: "Draft an email, then send it on confirmation",
-  async test(t) {
-    const draft = await t.send("Draft a follow-up email.");
-    draft.succeeded();
-    t.check(draft.message, includes("Best"));
-
-    await t.send("Looks good, send it.");
-    t.calledTool("send_email");
-  },
-});
-```
-
-需要并行独立会话时，用 `t.newSession()`。
-
-## 数据驱动测试（dataset fan-out）
-
-一个文件可以导出 eval 数组：
-
-```ts
-export default rows.map((row) =>
-  defineEval({
-    description: row.task,
-    async test(t) {
-      await t.send(row.prompt);
-      t.check(t.reply, equals(row.expected));
-    },
-  }),
-);
-```
-
-生成 ID 为 `sql/0000`、`sql/0001` 等。详见 [数据驱动测试](/zh/how-to/dataset-fanout)。
-
-## Sandbox workspace
-
-Coding-agent eval 仍然是普通 `.eval.ts` 文件，只是 test 里会准备 sandbox workspace、发送任务并检查文件结果：
-
-```ts
-import { defineEval } from "niceeval";
-
-export default defineEval({
-  description: "Create a Button component",
-  async test(t) {
-    await t.sandbox.uploadDirectory("../workspaces/ts-starter");
-    await t.send("Create src/components/Button.tsx with label and onClick props.").then((turn) => turn.succeeded());
-    t.sandbox.fileChanged("src/components/Button.tsx");
-  },
-});
-```
-
-详见 [Fixtures](/zh/how-to/fixtures)。
-
-## 从 Eval 报告长步骤和诊断
-
-`setup` 用于这条 Eval 的任务夹具。第二个参数绑定到 eval setup 阶段；`test(t)` 里的反馈绑定到 eval run 阶段：
-
-```ts
-export default defineEval({
-  async setup(sandbox, ctx) {
-    ctx.progress({ message: "安装 fixture 依赖" });
-    await sandbox.runCommand("npm", ["install"]);
-  },
-
-  async test(t) {
-    t.progress({ message: "上传隐藏测试", current: 1, total: 2 });
-    await t.sandbox.uploadDirectory("../fixtures/project");
-
-    const preflight = await inspectFixture();
-    if (preflight.usedFallback) {
-      t.diagnostic({
-        code: "fixture-check-degraded",
-        level: "warning",
-        message: "Fixture 预检使用了备用检查器",
-        data: { checker: preflight.checker },
-      });
-    }
-
-    await t.send("完成任务");
-  },
-});
-```
-
-`progress` 只更新运行中的短期状态，不进入结果。`diagnostic` 会写进当前 Attempt 的 `result.json`，但不会代替断言或自动改变判定：业务结论仍用 `t.check` / `t.require` / gate；基础设施无法继续时抛出异常。
-
-## 命名约定
-
-<CardGroup cols={2}>
-  <Card title="文件名" icon="file">
-    只有 `.eval.ts` 会被 runner 发现。
-  </Card>
-  <Card title="目录分组" icon="folder">
-    `evals/billing/refund.eval.ts` 的 ID 是 `billing/refund`。
-  </Card>
-  <Card title="数据集" icon="database">
-    适合大量结构相同、输入不同的 case。
-  </Card>
-  <Card title="Sandbox workspace" icon="box">
-    适合 coding agent，需要真实文件系统、命令和 diff。
-  </Card>
-</CardGroup>

package/docs-site/zh/how-to/custom-reports.mdx

@@ -1,414 +0,0 @@
----
-title: "用报告积木搭自己的口径"
-sidebarTitle: "自定义报告"
-description: "一份报告就是一个报告文件：官方宿主打开结果、注入数据，双面组件让同一份自定义报告同时用于 niceeval show 与 niceeval view。"
----
-
-[查看结果](/zh/how-to/viewing-results)讲「用」：官方两扇门 `niceeval show`（终端）和 `niceeval view`（网页）怎么看。本页讲「写」：官方摆法不够时，怎么写一份自己的报告——考试成绩单、代码行数榜、质量 × 成本 frontier。
-
-一份报告就是一个报告文件。你不用打开结果目录、不用写渲染代码、不用起自己的应用：`niceeval show` / `niceeval view` 本体就是宿主——替你打开结果、把数据注入进来，你用官方组件和 `Row` / `Col` 摆版面，写完把文件路径递给 `--report`，终端和网页两扇门就都认它——官方的证据深链、`--results` 换根、静态导出，自定义报告全部原样享有。
-
-## show / view 的默认报告也是一份报告文件
-
-`niceeval show` / `view` 不传 `--report` 时渲染的默认报告不是私有实现，而是包里自带的一个普通报告文件：三个页面（报告、Attempts、追踪），每页由 `niceeval/report` 公开导出的组件搭成——页首的标题区（`Hero`）、选择警告（`ScopeWarnings`），首页的比较组件 `ExperimentComparison`，Attempts 页的 Attempt 列表（`AttemptList`），追踪页的追踪瀑布（`TraceWaterfall`）。
-
-这份默认报告本身以 `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`，以后新增的内置报告也从这里按名字导入。想改页面内容本身，用同一批公开组件自己搭——你的报告文件能逐字写出同样的页面，也能只留自己要的部分：
-
-```ts
-import { ExperimentComparison, Hero, ScopeWarnings } from "niceeval/report";
-```
-
-`ExperimentComparison` 先按 experiment id 的父目录切成可比组，再为每组分别计算成本 × 端到端成功率散点图和实验明细表。`compare/bub` 与 `compare/codex` 可以同图，`dev-e2b/bub` 必须在另一个组；顶层 experiment 各自成为单例组。网页持有全部组并一次聚焦一组；终端命中多组时只列索引和单组查看命令，命中单组时才展开详情。两面都不会生成跨组总榜。
-
-|  | 网页（人看） | 终端（agent 和你看） |
-| --- | --- | --- |
-| 官方默认 | 分组比较报告（网页面） | 同一分组比较报告（文本面） |
-| 自定义摆法 | `niceeval view --report reports/exam.tsx` | `niceeval show --report reports/exam.tsx` |
-
-四个格子是同一个宿主。自定义只有三个层次，逐层深入：
-
-1. **换摆法**：用官方组件和 `Row` / `Col` 重摆版面——大多数「要自己的口径」到这层就够了。
-2. **换口径**：`defineMetric` 定义自己的指标，自定义维度和 `flag()` 定义自己的分组。
-3. **换形态**：官方组件摆不出的展示——是表就用 `<Table>` 自定义列，不是表就用 `defineComponent` 写自己的组件，网页怎么渲染、终端字符怎么排，两个面你都说了算。
-
-## 一份报告 = 一个报告文件
-
-先交代唯一的前置：报告文件是 `.tsx`，写它的项目要装 `react`（写自定义组件的 web 面还要 `@types/react`），tsconfig 里 `compilerOptions.jsx` 设为 `"react-jsx"`。裸跑 `niceeval show` / `niceeval view` 不需要这些——只有自己写报告文件才需要。
-
-报告基座是 `defineReport`：宿主打开结果目录（含 `--results` 指定的结果根）、按官方口径挑好结果快照，注入给你的函数；你只负责折数据和摆积木：
-
-```tsx
-// reports/exam.tsx —— 一份定义，两扇门共用
-import {
-  defineReport, Col, Section,
-  ExperimentComparison, Scoreboard,
-} from "niceeval/report";
-
-export default defineReport(async ({ selection }) => {
-  return (
-    <Col>
-      <ExperimentComparison data={await ExperimentComparison.data(selection)} />
-      <Section title="考试成绩单">
-        <Scoreboard data={await Scoreboard.data(selection, { rows: "agent", subjects: "evalGroup" })} />
-      </Section>
-    </Col>
-  );
-});
-```
-
-```bash
-niceeval show --report reports/exam.tsx    # 终端：同一棵树走文本面
-niceeval view --report reports/exam.tsx    # 网页：同一棵树走网页面，attempt 深链直达证据室
-```
-
-注入的上下文只有两样，全部是[结果数据 API](/zh/reference/results-data) 的原语，宿主没有私有通道：`results` 就是 `openResults(".niceeval")` 的返回（实验、历次快照、attempt 级 `diff()`、`trace()` 都在上面）；`selection` 是宿主替你挑好的那份结果。挑选规则是：对每个实验、每道 eval，取该实验历史运行里最新的那次判定——只按前缀重跑了一部分 eval，其余 eval 的判定从更早的运行补齐，不会因为一次局部重跑就整体退回某一份残缺快照。默认报告吃的就是这份 `selection`，快照在 `selection.snapshots`，挑选提醒在 `selection.warnings`。默认挑法不合口径时，拿 `results` 自己挑，手工挑的 `Snapshot[]` 数组同样能喂给每个组件。
-
-报告文件里有两种数据形态。实体列表的 `.data(selection)` 返回普通数组：`ExperimentListItem[]`、`EvalListItem[]`、`AttemptListItem[]`。报告作者用 JavaScript `.filter()` / `.slice()` 决定展示哪些实体，再把数组作为 `items` 传给列表；组件不藏另一套过滤 DSL。指标图形和汇总组件收算好的 `data`；其中 `MetricScatter` 也提供 `selection` 简写，由宿主在渲染前计算。计算后的组件只渲染传入数据，不碰结果目录。
-
-挑选提醒（覆盖不全、快照过期、有没跑完的运行、读不出来的快照）由选择警告（`ScopeWarnings`）组件显示：提醒按实验归组，组头列出实验名、问题标签和一条可复制的重跑命令，每条提醒的原文收在组内可展开的折叠块里（提醒少时默认展开），读不出来的快照单独归成一组。默认报告每一页都摆了它；自己的报告想显示提醒，就在页首摆一个 `<ScopeWarnings />`——不摆就不显示，数字是否附带完整性提醒由你对读者负责。
-
-命令行的范围先作用在挑选上，报告拿到的就是收窄到这个范围后的 `selection`：位置参数的 eval id 前缀收窄 Selection 覆盖的 eval（覆盖提醒的分母同样收窄到范围内），`--results` 把结果根换成指定目录，`--experiment` 让 Selection 只留该实验。`--history` 与 `--report` 互斥——趋势在报告里用 `exp.snapshots` 自己摆；证据切面（`--eval` / `--execution` / `--diff`）只看证据，不渲染报告。
-
-页面里的每个组件都是**双面**的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据。实体列表按 experiment → Eval → Attempt 展示事实；指标表、矩阵、条形图、成绩单、散点图、趋势图和差异表展示聚合值。完整清单见[报告组件](/zh/reference/report-components)。网页面的实体、格子和点深链到 Attempt 详情，终端面印出对应的 `niceeval show <eval id>` 下钻命令。
-
-默认报告没有特权：它的三个页面全部由公开组件搭成，你的报告和它同级。需要同样的“按目录分组、组内比较”摆法就直接写 `<ExperimentComparison />`，需要 Attempts 页就写带过滤的 `<AttemptList />`，不需要就不摆——包括页首标题区和 `Powered by NiceEval` 品牌行：它们分别是 `Hero` 和 `PoweredBy` 组件，用了就带、不用就没有，组件本身不提供开关。自己直接组合 `MetricScatter` / `ExperimentList` 时，通用组件只消费你传入的数据，不会自动分组；把跨组数据传进去就表示你明确要做跨组分析。
-
-## 排版：Row 与 Col 在两个面都成立
-
-排版原语也是双面组件，一次摆放，两个面各自成立：
-
-- **`<Col>`**：纵向依次排列——网页是块级堆叠，终端是逐块输出。
-- **`<Row>`**：并排——网页是横向排布，终端是字符分栏；终端宽度不够时自动降级为纵向，不硬挤。
-- **`<Section title="…">`**：带标题的块，网页是标题层级，终端是标题行加缩进。
-- **`<Text>`**：说明文字，网页是段落，终端是折行文本。
-- **`<Table>`**：自定义列的表——网页是 `<table>`，终端是按显示宽度对齐的字符表，中文列不撕歪。
-
-```tsx
-<Row>
-  <Scoreboard data={board} />
-  <MetricTable data={bench} />
-</Row>
-```
-
-```text
-$ niceeval show --report reports/exam.tsx
-考试成绩单                          │  benchmark 榜
-agent  总分       algebra  geometry │  agent  pass  cost
-bub    86.5/100   45/50    41.5/50  │  bub    87%   $0.42
-codex  78.0/100   40/50    38/50    │  codex  80%   $0.51
-```
-
-页面树里只放双面组件和排版原语，不放裸 HTML 标签——终端面没法渲染一个 `<div>`。要自由内容，说明文字用 `<Text>`，更自由的走下面的自定义组件。
-
-## 按组摘要：GroupSummary
-
-想把实验按目录前缀分组、每组顶部摆一块紧凑统计（通过率、experiment/eval 数、failed/errored、总成本、最后运行时间），用官方组件 `GroupSummary`。它的计算函数 `GroupSummary.data` 只吃一份已经收窄好的 Selection——不管你怎么分组，把对应组的 Selection 传进去，就是同一套折叠口径（eval 级折叠计票、null-safe 总成本、组内最后运行时间的最大值），不是另一套近似公式。
-
-常见的分法是按 experiment id 的目录前缀（`compare/bub-low` 属于组 `compare`，顶层实验以自己的完整 id 形成单例组）；用 `Selection.filter` 收窄出每组的 Selection，就能一组摆一块：
-
-```tsx
-// reports/groups.tsx —— 按 experiment id 前缀分组，每组顶部摆一块统计
-import { defineReport, Col, Section, GroupSummary } from "niceeval/report";
-import type { Snapshot } from "niceeval/report";
-
-// experiment id 的完整父路径当组名；顶层 experiment 各自成为单例组。
-function groupOf(snapshot: Snapshot): string {
-  const parts = snapshot.experimentId.split("/");
-  return parts.length > 1 ? parts.slice(0, -1).join("/") : snapshot.experimentId;
-}
-
-export default defineReport(async ({ selection }) => {
-  const groups = [...new Set(selection.snapshots.map(groupOf))];
-  return (
-    <Col>
-      {await Promise.all(
-        groups.map(async (key) => {
-          const scoped = selection.filter((s) => groupOf(s) === key);
-          const summary = <GroupSummary data={await GroupSummary.data(scoped)} />;
-          return <Section key={key} title={key}>{summary}</Section>;
-        }),
-      )}
-    </Col>
-  );
-});
-```
-
-```text
-$ niceeval show --report reports/groups.tsx
-compare
-Pass rate 60% · 2 experiments · 6 evals · failed 1 · errored 1 · $1.50
-latest 2026-07-01T11:30:00Z
-```
-
-`GroupSummary` 之后想接着摆散点图或实验列表，把同一份 `scoped` Selection 传给散点图，再用 `await ExperimentList.data(scoped)` 得到可自行过滤的 experiment 数组。想自由换行维度和指标列，再用下面的通用 `MetricTable`。
-
-## 换口径：自定义指标
-
-实验、Eval、Attempt 的固定诊断字段由三个实体列表承接。下面的例子是另一种需求：用通用 `MetricTable` 自由换指标口径——每个组件的数据算法都挂在自己身上，换口径只需换 columns：
-
-```tsx
-// reports/golf.tsx —— code-golf：谁写出能用的代码，谁写得短
-import {
-  defineReport, Col, MetricTable,
-  defineMetric, endToEndPassRate, costUSD,
-} from "niceeval/report";
-
-// 项目自己的口径：只比能用的代码的行数
-const codeLines = defineMetric({
-  name: "code-lines",
-  label: "代码行数",
-  better: "lower",
-  unit: "lines",
-  where: (a) => a.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(async ({ selection }) => (
-  <Col>
-    <MetricTable data={await MetricTable.data(selection, {
-      rows: "agent",
-      columns: [endToEndPassRate, codeLines, costUSD],
-      sort: endToEndPassRate,
-    })} />
-  </Col>
-));
-```
-
-```text
-$ niceeval show --report reports/golf.tsx
-agent   pass rate   code lines   cost
-bub     87%         312 lines    $0.42
-codex   80%         355 lines    $0.51
-```
-
-格子里的终值是**两级折叠**出来的：同一道题的多个 attempt 先折成题级值，再跨题折成格子值，两级默认都是平均。分两级不是形式主义——失败的题天然比通过的题 attempt 多（重试跑满、通过即停），平铺求均值会让分数和重试策略纠缠在一起。两级都能在 `defineMetric` 的 `aggregate` 里换：`aggregate: { perEval: "max", across: "mean" }` 就是 pass@k（题内取最好一次，跨题取占比）。
-
-两个面继承同一套诚实契约：排序方向随指标的 `better`，覆盖不全的格子带 `12/15` 角标（15 个 attempt 里 12 个测得了该指标），缺数据渲染成 `—` 而不是 0。指标只定义一次，两个面共用——人在网页上看到的数字，就是 agent 在 stdout 里读到的数字，判断口径永远一致。给 agent 的指引也只多一行：跑 `niceeval show --report reports/golf.tsx`，读 stdout。
-
-`label` 可以是一份文案，也可以按语言给：`label: { en: "Code lines", "zh-CN": "代码行数" }`——查看器界面切语言时，按语言给的 label 跟着切；只给一份就两种语言都用它。指标算出来的数字本身不分语言。
-
-内置指标里 `endToEndPassRate` / `taskPassRate` / `executionReliability` / `costUSD` / `durationMs` / `tokens` 只读 Attempt 自带的判定、用量这些字段，任何一份结果目录都算得出。没有限定词的“成功率”使用 `endToEndPassRate`：passed 记 1，failed 和 errored 都记 0。`taskPassRate` 只在形成可信判定的样本上衡量答题质量，errored 不参与；展示它时应明确写“可判定任务通过率”，不能简称成功率。要区分答题质量和执行问题，把 `endToEndPassRate`、`taskPassRate`、`executionReliability` 三列并排。`turns`（Agent 的总轮次）不一样，它读 `attempt.o11y()`——这份数据 `copySnapshots` 缺省会随行，但如果发布脚本显式给了 `artifacts` 列表又没把 `"o11y"` 写进去，它就不在发布根里（见[结果数据 API](/zh/reference/results-data)的「发布」一节），指标渲染成 `—`，不是 0。自己写的指标只要读了 `o11y()` / `diff()` 这类 artifact（就像上面 `codeLines` 读 `attempt.diff()`），发布前都要过一遍同样的检查。
-
-## 换分组：三种维度
-
-维度决定分组——表的行、矩阵的行列、散点的点。每个维度槽收三种值：
-
-- **内置维度**：`"agent"`、`"model"`、`"experiment"`、`"eval"`、`"evalGroup"`、`"snapshot"`，结果里现成的身份字段。
-- **自定义维度**：`{ name, of }`，一个纯函数吃 attempt、吐组名。定义只住在报告文件里，不用改任何 experiment 文件。
-- **`flag()`**：引用 experiment 用 `flags` 声明的变量。
-
-选哪种看变量住在哪：分组能从结果已有数据**算**出来的，用自定义维度——报告只管「怎么摆」，不反过来要求 experiment 为一种摆法改配置；变量是 experiment 本身的**配置**——scaling 档位、要当数值轴用、要在 experiment 定义处一眼看到的——才声明成 `flags`，报告用 `flag()` 引用。数值轴（`MetricLine` 的 `x`）只收 `flag()`：刻度必须来自声明的数值，函数派生的组名当不了刻度。
-
-### 自定义维度：从已有数据派生分组
-
-比如把不同模型折成厂商，按厂商比通过率——分组从 `result.model` 算出来，experiment 文件一个都不用碰：
-
-```tsx
-import type { Dimension } from "niceeval/report";
-
-const vendor: Dimension = {
-  name: "vendor",
-  of: (a) => (a.result.model?.startsWith("gpt-") ? "OpenAI" : "Anthropic"),
-};
-
-<MetricTable data={await MetricTable.data(selection, {
-  rows: vendor,
-  columns: [endToEndPassRate, costUSD],
-})} />
-```
-
-`of` 能读 attempt 的全部已有数据：`evalId`、`experimentId`、`result` 里的判定与 experiment 元数据。它只能派生、不能补造：如果两组 experiment 的差别只体现在文件命名里（`bub-baseline.ts` / `bub-mempal.ts`），`of` 就只能去解析这个名字——命名约定一改，分组静默散掉。这种时候变量该搬回配置，往下看。
-
-### `flag()`：变量来自配置，不来自命名
-
-画「并行 agent 数 × 模拟延迟 × 得分」这类 scaling 趋势时，图上的变量不该编码进 experiment id（`ultra-16agents-300ms`），再在报告里解析字符串抠出来——那是约定不是配置，改个命名整张图就散。变量的家是 experiment 文件的 `flags`：一文件一个档位，把变量声明成数据：
-
-```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 },
-});
-```
-
-报告侧用 `flag()` 把声明的值直接当维度或轴用，不解析任何名字：
-
-```tsx
-<MetricLine data={await MetricLine.data(selection, {
-  x: flag("latencyMs", { label: "Simulated latency", unit: "ms" }),
-  series: flag("agents", { label: (v) => `${v} agents` }),
-  y: endToEndPassRate,
-})} />
-```
-
-`flag()` 用在维度槽（`series` / `rows` / `columns` / `points`）就按声明值分组，用在轴槽（`x`）就要求数值并驱动刻度。没有声明该 flag 的 experiment 不猜：分组时如实归入「未配置」一组，作轴时该点不画、注脚报数。flags 随快照落盘，所以历史 run 也能按当时声明的变量重摆——报告读的是配置的事实，不是命名的巧合。
-
-## 换形态：表格用 Table，其余自己画
-
-官方组件摆不出来的展示分两种，各走一条路：是一张表，用排版原语 `<Table>`；不是表（通过率条形、预算燃尽、项目自己的徽章），用 `defineComponent` 写自己的双面组件。
-
-### 一张表：`<Table>`
-
-列是你定的，格子是你算好的显示值，`<Table>` 负责把网页和终端两个面都排整齐：
-
-```tsx
-// reports/cost-board.tsx
-import { defineReport, Col, Table, MetricTable, costUSD, endToEndPassRate } from "niceeval/report";
-
-export default defineReport(async ({ selection }) => {
-  const board = await MetricTable.data(selection, {
-    rows: "agent",
-    columns: [endToEndPassRate, costUSD],
-  });
-  return (
-    <Col>
-      <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,
-          },
-        }))}
-      />
-    </Col>
-  );
-});
-```
-
-```text
-$ niceeval show --report reports/cost-board.tsx
-Agent    通过率    成本
-bub         87%   $0.42
-codex       80%   $0.51
-克劳德        —       —
-```
-
-列宽按**终端显示宽度**算：一个汉字占 2 列，所以中文 agent 名、中文题目名都不会把表撕歪。`align: "right"` 让数字列右对齐。格子给 `null` 就渲染 `—`，不补 0。行上带 `locator` 就多出一列 attempt，网页面点进证据室、终端面把 locator 交给 `niceeval show`。完整字段见[报告组件](/zh/reference/report-components)的「表格」一节。
-
-### 不是表：`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, MetricTable,
-  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");
-  },
-});
-
-export default defineReport(async ({ selection }) => {
-  const board = await MetricTable.data(selection, { 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>
-  );
-});
-```
-
-```text
-$ niceeval show --report reports/passbars.tsx
-bub     █████████████████░░░  87%
-codex   ████████████████░░░░  80%
-克劳德  —                     —
-```
-
-组件的契约：
-
-- **计算在报告函数体里，渲染面是纯函数。** 读 attempt 句柄、`await` 折数据都发生在 `defineReport` 的函数体里；`web` 和 `text` 只认算好的数据，零 IO、同步——这条边界让同一棵树能被烘进静态导出。
-- **面收第二参上下文。** `text(props, ctx)` 的 `ctx.width` 是可用列宽（`Row` 分栏后会变窄），`ctx.attemptCommand(ref)` 生成下钻命令；`web(props, ctx)` 的 `ctx.attemptHref(ref)` 生成证据室深链——自定义组件和官方组件通到同一间证据室。
-- **网页面静态渲染，不 hydrate。** 宿主在计算侧把 `web` 面渲染成静态 HTML，不打包你的代码进查看器：交互用普通链接和 `<details>`，与官方组件同一条静态契约。
-- **样式随树带走。** 静态导出不打包你的代码，`className` 引用的 CSS 用内置原语 `<Style>{css}</Style>` 放进页面树——web 面吐 `<style>` 标签，text 面渲染为空，上面的例子就是这么给 `.passbars` 上样式的。
-- **诚实契约同样适用。** 缺数据渲染 `—` 不补 0，截断如实标注剩余数量——上面例子里 `claude` 没有样本就是 `—`。
-
-## 发布：导出即静态站
-
-发布自定义报告和发布官方查看器是同一个动作——`--out` 加上 `--report`：
-
-```bash
-niceeval view --report reports/exam.tsx --out site
-```
-
-产物是纯静态文件：你的报告页是首页，证据室（transcript、trace、代码视图）在同一站内，报告里的每个数字点进去就是证据。组件不 hydrate；页面内联一小段官方脚本，提供表头排序、行过滤、图表悬停这些浏览操作，浏览器禁用 JS 时页面仍完整可读。交给任何静态托管即可。CI 上没有 `.niceeval/` 时，先用 `copySnapshots` 把快照瘦身进仓库再导出，流程见[查看结果](/zh/how-to/viewing-results#导出与静态托管)。
-
-双面组件的网页面就是普通 React 组件，`data` 函数就是普通 TS 函数——想把某一块指标表嵌进已有的内部面板，import 组件喂数据就行。那是零件的复用，不是另一套报告系统：报告的家在官方宿主。算数据与渲染分离部署时（CI 落 JSON、另一个应用 fetch），两侧锁同一个 niceeval 版本是硬要求——组件数据不带版本戳，兼容性跟随包版本。
-
-## 界线：内置命令不长配置
-
-一次只渲染一份报告，`--report` 收显式文件路径——没有 `reports/` 目录自动发现、没有插件注册表、没有配置文件。自定义指标和自定义组件都住在你的报告文件里，随文件一起递入，宿主不为它们长任何注册面。不传 `--report` 时渲染的就是默认报告，你的报告和它是同级实现。