niceeval 0.5.4 → 0.6.1

package/dist/report/format.js

@@ -0,0 +1,109 @@
+// unit 驱动的内置格式化(docs/feature/reports/library.md「指标」):
+//   "%" → 87%    "ms" → 1.2s    "$" → $0.31    其余 → 1.2k 缩写(带 unit 后缀)
+// metric.display 可整体覆盖;这里只负责默认。
+/** 一位小数、去掉无意义的 ".0" 尾巴。 */
+function trimmed(n) {
+    const s = n.toFixed(1);
+    return s.endsWith(".0") ? s.slice(0, -2) : s;
+}
+/** 1.2k / 3.4M / 5.6B 式缩写(输入为非负数)。 */
+function abbreviate(abs) {
+    if (abs >= 1e9)
+        return `${trimmed(abs / 1e9)}B`;
+    if (abs >= 1e6)
+        return `${trimmed(abs / 1e6)}M`;
+    if (abs >= 1e3)
+        return `${trimmed(abs / 1e3)}k`;
+    return Number.isInteger(abs) ? String(abs) : trimmed(abs);
+}
+function formatDuration(absMs) {
+    if (absMs < 1000)
+        return `${Math.round(absMs)}ms`;
+    if (absMs < 60_000)
+        return `${trimmed(absMs / 1000)}s`;
+    const totalSeconds = Math.round(absMs / 1000);
+    return `${Math.floor(totalSeconds / 60)}m ${totalSeconds % 60}s`;
+}
+function formatDollars(abs) {
+    if (abs >= 1000)
+        return abbreviate(abs);
+    if (abs >= 0.01 || abs === 0)
+        return abs.toFixed(2);
+    // 小额成本保留有效位,不四舍成 "$0.00" 假零
+    return abs.toFixed(4);
+}
+export function formatMetricValue(value, unit) {
+    const sign = value < 0 ? "-" : "";
+    const abs = Math.abs(value);
+    if (unit === "%")
+        return `${sign}${trimmed(Math.round(abs * 1000) / 10)}%`;
+    if (unit === "ms")
+        return sign + formatDuration(abs);
+    if (unit === "$")
+        return `${sign}$${formatDollars(abs)}`;
+    const n = abbreviate(abs);
+    return unit ? `${sign}${n} ${unit}` : `${sign}${n}`;
+}
+/** 无单位纯数字(scoreboard 总分等):一位小数,去尾零。 */
+export function formatPlainNumber(value) {
+    const sign = value < 0 ? "-" : "";
+    return sign + trimmed(Math.round(Math.abs(value) * 10) / 10);
+}
+// ── 以下是两个渲染面共用的展示格式化:MetricCell 一律自带 display(格式化发生在
+//    计算侧),渲染面不重算;这里只服务 OverviewData 这类携带裸数字的字段。──
+/** 全 null / 无样本的统一文案。绝不画 0(docs/feature/reports/architecture.md「指标聚合不变量」)。 */
+export const MISSING_TEXT = "no data";
+/** 毫秒 → 人读耗时("850ms" / "1.2s" / "4m 20s" / "1h 4m")。 */
+export function formatDurationMs(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const s = ms / 1000;
+    if (s < 60)
+        return `${s.toFixed(1)}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${Math.round(s % 60)}s`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m`;
+}
+/** 美元金额;小额保留更多位数,不四舍五入成 $0.00 的假零。 */
+export function formatUSD(usd) {
+    if (usd === 0)
+        return "$0";
+    const digits = Math.abs(usd) >= 0.01 ? 2 : 4;
+    return `$${usd.toFixed(digits)}`;
+}
+/** 0..1 的比率 → 整数百分比。 */
+export function formatPercent(ratio) {
+    return `${Math.round(ratio * 100)}%`;
+}
+// ── 实体列表(ExperimentList / EvalList / AttemptList)共用的判定符 ──
+/** passed / failed / errored / skipped 的判定符。 */
+export function verdictMark(verdict) {
+    switch (verdict) {
+        case "passed":
+            return "✓";
+        case "failed":
+            return "✗";
+        case "errored":
+            return "!";
+        case "skipped":
+            return "–";
+    }
+}
+/**
+ * 一个 AttemptListItem 的失败原因摘要,按优先级取第一个在场的:`error` → 未通过的 gate 断言
+ * (原始声明顺序,`name`,detail 在场则 `"name: detail"`,多条用「, 」连接)→ 缺席。与
+ * compute.ts 的 `reasonFor(EvalResult)` 同一口径,只是输入换成瘦身后的 AttemptListItem——
+ * 没有 `skipReason` 字段(AttemptListItem 不携带),skipped 的 attempt 因此没有原因摘要,
+ * 这与它们本来就不该出现在「为什么失败」列表里的事实一致。EvalList / ExperimentList 的
+ * 逐 attempt 徽标行用它给每个 attempt 自己的原因(而不是复用整道题的代表原因)。
+ */
+export function attemptItemReason(item) {
+    if (item.error !== undefined)
+        return item.error;
+    const gates = item.assertions.filter((a) => !a.passed && a.severity === "gate");
+    if (gates.length === 0)
+        return undefined;
+    return gates.map((a) => (a.detail ? `${a.name}: ${a.detail}` : a.name)).join(", ");
+}

package/dist/report/index.d.ts

@@ -0,0 +1,19 @@
+export { defineMetric, passRate, examScore, durationMs, tokens, costUSD, turns } from "./metrics.ts";
+export { flag } from "./flag.ts";
+export { defineReport, isReportDefinition, renderReportToText } from "./report.ts";
+export type { ReportContext, ReportDefinition } from "./report.ts";
+export { defineComponent } from "./tree.ts";
+export type { ComponentFaces, ReportComponent, ReportElement, ReportNode, TextContext, TextRenderOptions, WebContext, } from "./tree.ts";
+export { Row, Col, Section, Text, Style, Table } from "./primitives.tsx";
+export type { LayoutProps, SectionProps, StyleProps, TableColumn, TableProps, TableRow } from "./primitives.tsx";
+export { stringWidth, padDisplay as padEnd, padStartDisplay as padStart, wrapDisplay as wrapText, indentBlock as indent, textBar as bar, joinColumns as columns, } from "./text/layout.ts";
+export type { ColumnAlign } from "./text/layout.ts";
+export { ExperimentComparison } from "./built-ins/index.ts";
+export { DEFAULT_REPORT_LOCALE, resolveMetricLabel } from "./locale.ts";
+export type { LocalizedLabel, ReportLocale } from "./locale.ts";
+export { AttemptList, DeltaTable, EvalList, ExperimentList, GroupSummary, MetricBars, MetricLine, MetricMatrix, MetricScatter, MetricTable, RunOverview, Scoreboard, } from "./components.tsx";
+export type { AttemptListProps, DeltaTableProps, EvalListProps, ExperimentListProps, GroupSummaryProps, MetricLineProps, MetricMatrixProps, MetricScatterProps, MetricTableProps, RunOverviewProps, ScoreboardProps, } from "./components.tsx";
+export type { AttemptListDataOptions, DeltaDataOptions, DeltaPair, LineDataOptions, MatrixDataOptions, ScatterDataOptions, ScoreboardDataOptions, TableDataOptions, } from "./compute.ts";
+export type { Aggregator, AttemptListItem, AttemptLocator, DeltaData, Dimension, DimensionInput, EvalListItem, ExperimentListEvalRow, ExperimentListItem, GroupSummaryData, LineAxis, LineData, MatrixData, Metric, MetricAggregate, MetricCell, MetricColumn, OverviewData, FlagRef, ScatterData, ScoreboardData, SelectionWarning, TableData, TableRowMeta, } from "./types.ts";
+export type { AttemptHandle, Results, Selection, Snapshot } from "../results/types.ts";
+export { experimentGroupOf } from "../shared/aggregate.ts";

package/dist/report/index.js

@@ -0,0 +1,30 @@
+// niceeval/report —— 报告积木:指标 × 计算函数 × 双面组件 × defineReport。
+// 契约见 docs/feature/reports/README.md;公开叙事的准绳是 docs-site/zh/guides/custom-reports.mdx
+// 与 report-components.mdx。
+//
+// import 边界即运行时边界:计算函数(挂在组件上的 .data)会经句柄触碰文件系统
+// (懒加载 artifact),只能进服务端 / 脚本;组件的渲染面纯同步零 IO。text 宿主遍历渲染
+// 不需要 react-dom(renderReportToText);web 宿主的 renderReportToStaticHtml 在
+// ./web.ts,只有那一侧 import react-dom。写报告文件的项目要装 react(.tsx 编译产物
+// import react/jsx-runtime)。
+// 指标与 flag
+export { defineMetric, passRate, examScore, durationMs, tokens, costUSD, turns } from "./metrics.js";
+export { flag } from "./flag.js";
+// 报告基座与双面组件基座
+export { defineReport, isReportDefinition, renderReportToText } from "./report.js";
+export { defineComponent } from "./tree.js";
+// 排版原语(六个内置双面组件)
+export { Row, Col, Section, Text, Style, Table } from "./primitives.js";
+// 文本排版工具箱:自定义组件的 text 面用的就是官方组件那把尺子。
+// 表格有 <Table> 承担,这里只给表以外的形态用 —— 尤其别拿 String.prototype.padEnd 对齐:
+// 它数 UTF-16 码元不数显示列宽,一带中文列就撕歪。renderAlignedRows 刻意不导出。
+export { stringWidth, padDisplay as padEnd, padStartDisplay as padStart, wrapDisplay as wrapText, indentBlock as indent, textBar as bar, joinColumns as columns, } from "./text/layout.js";
+// 内置报告(show / view 裸跑时报告槽的出厂填充,一份普通 ReportDefinition,无 renderer 特权)
+export { ExperimentComparison } from "./built-ins/index.js";
+// locale:官方组件 chrome 文案的语言(en / zh-CN);指标 label 可按 locale 给字典
+export { DEFAULT_REPORT_LOCALE, resolveMetricLabel } from "./locale.js";
+// 官方双面组件(各自带 data 计算函数;MetricBars.data = MetricMatrix.data)
+export { AttemptList, DeltaTable, EvalList, ExperimentList, GroupSummary, MetricBars, MetricLine, MetricMatrix, MetricScatter, MetricTable, RunOverview, Scoreboard, } from "./components.js";
+// experiment id 的组键推导(id 的目录前缀,如 `compare/bub-low` 的 `compare`)。
+// 重新导出,让自定义报告能按同一份口径把 experiment 分组,不必自己重写这两行逻辑。
+export { experimentGroupOf } from "../shared/aggregate.js";

package/dist/report/load.d.ts

@@ -0,0 +1,12 @@
+import { type ReportDefinition } from "./report.ts";
+/** 可预期的装载错误:宿主打一句英文直说问题与下一步,不抛堆栈。 */
+export declare class ReportLoadError extends Error {
+}
+export interface LoadReportOptions {
+    /**
+     * 按文件 mtime 追加 query 绕开 ESM 模块缓存:同一文件未变时命中缓存,
+     * 变更后重新装载。dev server(view)传 true;一次性进程(show / --out)不需要。
+     */
+    freshImport?: boolean;
+}
+export declare function loadReportFile(cwd: string, path: string, options?: LoadReportOptions): Promise<ReportDefinition>;

package/dist/report/load.js

@@ -0,0 +1,56 @@
+// --report 的装载:两个宿主(show / view)共用的中性入口。复用跑用户 .ts 配置的
+// 同一 tsx 加载机制(bin 里已 register)。show 一进程一次装载;view 的 dev server
+// 每次请求现读现渲染 —— ESM 模块缓存永不失效,所以按文件 mtime 做 cache-busting
+// (freshImport):报告文件变更 → 下次请求拿到新模块,整页重算(docs/feature/reports/view.md
+// 裁决记录 6)。装载环境坑见 memory/tsx-dynamic-import-require-cycle.md。
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isReportDefinition } from "./report.js";
+/** 可预期的装载错误:宿主打一句英文直说问题与下一步,不抛堆栈。 */
+export class ReportLoadError extends Error {
+}
+export async function loadReportFile(cwd, path, options) {
+    const abs = resolve(cwd, path);
+    if (!existsSync(abs)) {
+        throw new ReportLoadError(`Report file not found: ${abs}. Pass --report an explicit path to a module whose default export is defineReport(...).`);
+    }
+    const plain = pathToFileURL(abs);
+    const url = new URL(plain.href);
+    if (options?.freshImport) {
+        // 只 bust 报告文件本体:它 import 的模块仍走缓存,与「报告文件变更整页重算」的
+        // 装载语义一致(依赖变更不追踪)。tsx 与 Node 原生 ESM 都认 file URL 的 query。
+        url.searchParams.set("mtime", String(statSync(abs).mtimeMs));
+    }
+    let mod;
+    try {
+        mod = (await import(__rewriteRelativeImportExtension(url.href)));
+    }
+    catch (e) {
+        // 个别装载环境(如 vitest 的 vite-node)按「扩展名 + query」误判文件类型;
+        // 退化为普通 import(失去变更重载,不失去功能)。仍失败才是真错误。
+        if (url.href !== plain.href) {
+            try {
+                mod = (await import(__rewriteRelativeImportExtension(plain.href)));
+            }
+            catch {
+                throw new ReportLoadError(`Cannot load report file ${abs}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        else {
+            throw new ReportLoadError(`Cannot load report file ${abs}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (!isReportDefinition(mod.default)) {
+        throw new ReportLoadError(`${path} does not default-export a report. Export default defineReport(async ({ selection, results }) => ...) from "niceeval/report".`);
+    }
+    return mod.default;
+}

package/dist/report/locale.d.ts

@@ -0,0 +1,94 @@
+/** 报告渲染的 locale;默认 "en"(text 面缺省即 en,`niceeval show` 输出不变)。 */
+export type ReportLocale = "en" | "zh-CN";
+export declare const DEFAULT_REPORT_LOCALE: ReportLocale;
+declare const en: {
+    readonly "verdict.passed": "passed";
+    readonly "verdict.failed": "failed";
+    readonly "verdict.errored": "errored";
+    readonly "verdict.skipped": "skipped";
+    /** 全 null / 无样本的统一文案,绝不画 0。 */
+    readonly "cell.missing": "no data";
+    readonly "cell.measuredTitle": "{samples}/{total} attempts measured";
+    readonly "cell.noneMeasurableTitle": "0/{total} attempts measurable";
+    readonly "cell.coverageTitle": "coverage {samples}/{total}: this metric is null for the remaining attempts";
+    readonly "table.higherBetter": "higher is better";
+    readonly "table.lowerBetter": "lower is better";
+    readonly "table.model": "Model";
+    readonly "table.agent": "Agent";
+    readonly "table.verdicts": "Verdicts";
+    readonly "table.filterPlaceholder": "Filter rows…";
+    readonly "table.eval": "Eval";
+    readonly "table.reason": "Reason";
+    readonly "table.viewBreakdown": "Per-eval breakdown";
+    /** <Table> 的 locator 列表头(行带 locator 时自动追加)。 */
+    readonly "table.attempt": "attempt";
+    readonly "experimentList.experiment": "Experiment";
+    readonly "experimentList.avgDuration": "Avg duration";
+    readonly "experimentList.passRate": "Pass rate";
+    readonly "experimentList.tokens": "Tokens";
+    readonly "experimentList.estimatedCost": "Est. cost";
+    readonly "experimentList.result": "Result";
+    readonly "experimentList.status": "Status";
+    readonly "experimentList.evalAttempt": "Eval / Attempt";
+    readonly "experimentList.duration": "Duration";
+    readonly "experimentList.cost": "Cost";
+    readonly "experimentList.filterPlaceholder": "Filter experiments…";
+    readonly "experimentList.defaultModel": "default";
+    readonly "experimentList.flags": "Flags";
+    /** <Table> 压到下限仍放不下时,从右侧丢列并如实报数。 */
+    readonly "table.columnsHidden.one": "({n} more column not shown)";
+    readonly "table.columnsHidden.other": "({n} more columns not shown)";
+    readonly "overview.snapshots": "Snapshots";
+    readonly "overview.evals": "Evals";
+    readonly "overview.attempts": "attempts";
+    readonly "overview.passRate": "Pass rate";
+    readonly "overview.totalCost": "Total cost";
+    readonly "overview.totalDuration": "Total duration";
+    readonly "overview.source": "Source: {n} snapshots";
+    readonly "overview.experiments.one": "{n} experiment";
+    readonly "overview.experiments.other": "{n} experiments";
+    readonly "overview.evalsCount": "{n} evals";
+    readonly "overview.attemptsCount": "{n} attempts";
+    /** GroupSummary 的 KPI dt 标签(其余字段复用 verdict.* / overview.* 已有 key)。 */
+    readonly "groupSummary.experiments": "Experiments";
+    readonly "composedFrom.one": "composed from {n} run";
+    readonly "composedFrom.other": "composed from {n} runs";
+    readonly latestRun: "latest {run}";
+    readonly "scatter.betterHint": "better ↗";
+    readonly "scatter.betterUpperRight": "better → upper right";
+    readonly "scatter.axisReversed": "(axis reversed: right = better)";
+    /** 0 个可画点:x/y 指标没有可用数据。 */
+    readonly "scatter.noData": "No data to plot {x} × {y}";
+    readonly "pointsMissing.one": "{n} point missing data";
+    readonly "pointsMissing.other": "{n} points missing data";
+    readonly "attemptList.empty": "No attempts";
+    readonly "attemptList.truncated": "and {n} more not shown";
+    readonly "attemptList.truncatedText": "({n} more not shown)";
+    readonly "attemptList.score": "score {score}";
+    readonly "attemptList.details": "details";
+    readonly "scoreboard.total": "Total";
+    readonly "scoreboard.totalText": "total";
+    readonly "scoreboard.missing.one": "{n} eval missing, scored 0";
+    readonly "scoreboard.missing.other": "{n} evals missing, scored 0";
+    readonly "scoreboard.missingText": "({n} missing)";
+    readonly "scoreboard.weights": "weights:";
+    readonly "scoreboard.allWeights": "all evals ×1";
+    readonly "scoreboard.othersWeight": "others ×1";
+    readonly "scoreboard.subjectTitle": "{evals} evals, weighted {earned} of {possible}";
+    readonly "delta.pairHeader": "pair (A → B)";
+    readonly "board.currentVerdicts": "Current verdicts";
+    readonly "board.failing": "Failing:";
+};
+export type ReportMessageKey = keyof typeof en;
+/** 查字典 + 简单插值({name} 占位符)。缺 locale 回退 en。 */
+export declare function localeText(locale: ReportLocale, key: ReportMessageKey, vars?: Record<string, string | number>): string;
+/** 带单复数的计数文案:n === 1 用 `<base>.one`,其余 `<base>.other`(zh-CN 两键同值)。 */
+export declare function countText(locale: ReportLocale, base: "overview.experiments" | "composedFrom" | "pointsMissing" | "scoreboard.missing" | "table.columnsHidden", n: number): string;
+/** 指标 label 的可本地化形态:字符串,或按 locale 给的字典(缺项回退 en,再回退任一非空值)。 */
+export type LocalizedLabel = string | Partial<Record<ReportLocale, string>>;
+/**
+ * 按 locale 解析指标 label:字符串原样;字典取当前 locale,缺项回退 en,
+ * 再回退字典里任一值;全空回退 fallback(= metric.name)。渲染面(web / text)共用。
+ */
+export declare function resolveMetricLabel(label: LocalizedLabel | undefined, locale: ReportLocale, fallback: string): string;
+export {};

package/dist/report/locale.js

@@ -0,0 +1,183 @@
+// 官方组件 chrome 文案的 locale 字典(en / zh-CN 两份)。
+// 只覆盖组件自带的固定文案(verdict 词、缺数据、覆盖率角标、注脚、占位符等);
+// 数据本身(display、维度键、warnings 的 message)不经这里。
+// 刻意不 import src/i18n/(CLI 专用字典,locale 来源与 key 面完全不同);
+// zh-CN 译法与 src/view/app/i18n.ts 现有词保持一致(成功率/平均耗时/预估成本…)。
+export const DEFAULT_REPORT_LOCALE = "en";
+const en = {
+    "verdict.passed": "passed",
+    "verdict.failed": "failed",
+    "verdict.errored": "errored",
+    "verdict.skipped": "skipped",
+    /** 全 null / 无样本的统一文案,绝不画 0。 */
+    "cell.missing": "no data",
+    "cell.measuredTitle": "{samples}/{total} attempts measured",
+    "cell.noneMeasurableTitle": "0/{total} attempts measurable",
+    "cell.coverageTitle": "coverage {samples}/{total}: this metric is null for the remaining attempts",
+    "table.higherBetter": "higher is better",
+    "table.lowerBetter": "lower is better",
+    "table.model": "Model",
+    "table.agent": "Agent",
+    "table.verdicts": "Verdicts",
+    "table.filterPlaceholder": "Filter rows…",
+    "table.eval": "Eval",
+    "table.reason": "Reason",
+    "table.viewBreakdown": "Per-eval breakdown",
+    /** <Table> 的 locator 列表头(行带 locator 时自动追加)。 */
+    "table.attempt": "attempt",
+    "experimentList.experiment": "Experiment",
+    "experimentList.avgDuration": "Avg duration",
+    "experimentList.passRate": "Pass rate",
+    "experimentList.tokens": "Tokens",
+    "experimentList.estimatedCost": "Est. cost",
+    "experimentList.result": "Result",
+    "experimentList.status": "Status",
+    "experimentList.evalAttempt": "Eval / Attempt",
+    "experimentList.duration": "Duration",
+    "experimentList.cost": "Cost",
+    "experimentList.filterPlaceholder": "Filter experiments…",
+    "experimentList.defaultModel": "default",
+    "experimentList.flags": "Flags",
+    /** <Table> 压到下限仍放不下时,从右侧丢列并如实报数。 */
+    "table.columnsHidden.one": "({n} more column not shown)",
+    "table.columnsHidden.other": "({n} more columns not shown)",
+    "overview.snapshots": "Snapshots",
+    "overview.evals": "Evals",
+    "overview.attempts": "attempts",
+    "overview.passRate": "Pass rate",
+    "overview.totalCost": "Total cost",
+    "overview.totalDuration": "Total duration",
+    "overview.source": "Source: {n} snapshots",
+    "overview.experiments.one": "{n} experiment",
+    "overview.experiments.other": "{n} experiments",
+    "overview.evalsCount": "{n} evals",
+    "overview.attemptsCount": "{n} attempts",
+    /** GroupSummary 的 KPI dt 标签(其余字段复用 verdict.* / overview.* 已有 key)。 */
+    "groupSummary.experiments": "Experiments",
+    "composedFrom.one": "composed from {n} run",
+    "composedFrom.other": "composed from {n} runs",
+    "latestRun": "latest {run}",
+    "scatter.betterHint": "better ↗",
+    "scatter.betterUpperRight": "better → upper right",
+    "scatter.axisReversed": "(axis reversed: right = better)",
+    /** 0 个可画点:x/y 指标没有可用数据。 */
+    "scatter.noData": "No data to plot {x} × {y}",
+    "pointsMissing.one": "{n} point missing data",
+    "pointsMissing.other": "{n} points missing data",
+    "attemptList.empty": "No attempts",
+    "attemptList.truncated": "and {n} more not shown",
+    "attemptList.truncatedText": "({n} more not shown)",
+    "attemptList.score": "score {score}",
+    "attemptList.details": "details",
+    "scoreboard.total": "Total",
+    "scoreboard.totalText": "total",
+    "scoreboard.missing.one": "{n} eval missing, scored 0",
+    "scoreboard.missing.other": "{n} evals missing, scored 0",
+    "scoreboard.missingText": "({n} missing)",
+    "scoreboard.weights": "weights:",
+    "scoreboard.allWeights": "all evals ×1",
+    "scoreboard.othersWeight": "others ×1",
+    "scoreboard.subjectTitle": "{evals} evals, weighted {earned} of {possible}",
+    "delta.pairHeader": "pair (A → B)",
+    "board.currentVerdicts": "Current verdicts",
+    "board.failing": "Failing:",
+};
+const zhCN = {
+    "verdict.passed": "通过",
+    "verdict.failed": "失败",
+    "verdict.errored": "错误",
+    "verdict.skipped": "跳过",
+    "cell.missing": "无数据",
+    "cell.measuredTitle": "{samples}/{total} 次 attempt 测得",
+    "cell.noneMeasurableTitle": "0/{total} 次 attempt 可测",
+    "cell.coverageTitle": "覆盖率 {samples}/{total}:其余 attempt 测不了这个指标",
+    "table.higherBetter": "越高越好",
+    "table.lowerBetter": "越低越好",
+    "table.model": "模型",
+    "table.agent": "Agent",
+    "table.verdicts": "结果",
+    "table.filterPlaceholder": "筛选行…",
+    "table.eval": "题目",
+    "table.reason": "原因",
+    "table.viewBreakdown": "逐题明细",
+    "table.attempt": "Attempt",
+    "experimentList.experiment": "实验",
+    "experimentList.avgDuration": "平均耗时",
+    "experimentList.passRate": "成功率",
+    "experimentList.tokens": "Tokens",
+    "experimentList.estimatedCost": "预估成本",
+    "experimentList.result": "结果",
+    "experimentList.status": "状态",
+    "experimentList.evalAttempt": "题目 / Attempt",
+    "experimentList.duration": "耗时",
+    "experimentList.cost": "成本",
+    "experimentList.filterPlaceholder": "筛选实验…",
+    "experimentList.defaultModel": "默认",
+    "experimentList.flags": "Flags",
+    "table.columnsHidden.one": "(还有 {n} 列未列出)",
+    "table.columnsHidden.other": "(还有 {n} 列未列出)",
+    "overview.snapshots": "快照",
+    "overview.evals": "题目",
+    "overview.attempts": "尝试",
+    "overview.passRate": "通过率",
+    "overview.totalCost": "总成本",
+    "overview.totalDuration": "总耗时",
+    "overview.source": "数据来源:{n} 个快照",
+    "overview.experiments.one": "{n} 个实验",
+    "overview.experiments.other": "{n} 个实验",
+    "overview.evalsCount": "{n} 道题",
+    "overview.attemptsCount": "{n} 次 attempt",
+    "groupSummary.experiments": "实验数",
+    "composedFrom.one": "合成自 {n} 个 run",
+    "composedFrom.other": "合成自 {n} 个 run",
+    "latestRun": "最新 {run}",
+    "scatter.betterHint": "更好 ↗",
+    "scatter.betterUpperRight": "更好 → 右上",
+    "scatter.axisReversed": "(轴反向:右 = 更好)",
+    "scatter.noData": "{x} × {y} 没有可绘制的数据",
+    "pointsMissing.one": "{n} 个点缺数据",
+    "pointsMissing.other": "{n} 个点缺数据",
+    "attemptList.empty": "没有 attempt",
+    "attemptList.truncated": "还有 {n} 条未列出",
+    "attemptList.truncatedText": "(还有 {n} 条未列出)",
+    "attemptList.score": "得分 {score}",
+    "attemptList.details": "详情",
+    "scoreboard.total": "总分",
+    "scoreboard.totalText": "总分",
+    "scoreboard.missing.one": "{n} 道题缺席,按 0 计",
+    "scoreboard.missing.other": "{n} 道题缺席,按 0 计",
+    "scoreboard.missingText": "(缺 {n} 题)",
+    "scoreboard.weights": "权重:",
+    "scoreboard.allWeights": "全部题 ×1",
+    "scoreboard.othersWeight": "其余 ×1",
+    "scoreboard.subjectTitle": "{evals} 道题,加权得分 {earned}/{possible}",
+    "delta.pairHeader": "对比 (A → B)",
+    "board.currentVerdicts": "现刻判定",
+    "board.failing": "失败清单:",
+};
+const dictionaries = {
+    en,
+    "zh-CN": zhCN,
+};
+/** 查字典 + 简单插值({name} 占位符)。缺 locale 回退 en。 */
+export function localeText(locale, key, vars) {
+    const template = dictionaries[locale]?.[key] ?? dictionaries.en[key];
+    if (!vars)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (m, name) => name in vars ? String(vars[name]) : m);
+}
+/** 带单复数的计数文案:n === 1 用 `<base>.one`,其余 `<base>.other`(zh-CN 两键同值)。 */
+export function countText(locale, base, n) {
+    return localeText(locale, `${base}.${n === 1 ? "one" : "other"}`, { n });
+}
+/**
+ * 按 locale 解析指标 label:字符串原样;字典取当前 locale,缺项回退 en,
+ * 再回退字典里任一值;全空回退 fallback(= metric.name)。渲染面(web / text)共用。
+ */
+export function resolveMetricLabel(label, locale, fallback) {
+    if (label === undefined)
+        return fallback;
+    if (typeof label === "string")
+        return label;
+    return label[locale] ?? label.en ?? Object.values(label).find((v) => v !== undefined) ?? fallback;
+}

package/dist/report/metrics.d.ts

@@ -0,0 +1,21 @@
+import type { EvalResult } from "../types.ts";
+import type { Metric } from "./types.ts";
+/**
+ * 定义一个指标。内置指标与自定义指标是同一个类型,没有特权;
+ * 校验只管「能进计算」的最低要求,聚合语义见 docs/feature/reports/architecture.md「指标聚合不变量」。
+ * name 是 const 泛型:产物的 name 保持字面量,`row.cells[metric.name]` 才有编译期列键。
+ */
+export declare function defineMetric<const Name extends string>(def: Metric<Name>): Metric<Name>;
+/** 单 attempt 成本:网关实测(usage.costUSD)优先于价格表估算(estimatedCostUSD);都缺 → null,不编 0。 */
+export declare function attemptCostUSD(result: EvalResult): number | null;
+export declare const passRate: Metric<"pass-rate">;
+export declare const examScore: Metric<"exam-score">;
+export declare const durationMs: Metric<"duration">;
+export declare const tokens: Metric<"tokens">;
+export declare const costUSD: Metric<"cost">;
+/**
+ * 唯一读 artifact(o11y,懒加载)的内置指标——其余五个只读瘦身字段。
+ * 发布时若该 attempt 没带 o11y(如 copySnapshots 的 artifacts 选项漏了它),
+ * value 如实返回 null,渲染成「—」,不冒充 0——见 docs/feature/reports/library.md「内置指标」。
+ */
+export declare const turns: Metric<"turns">;

package/dist/report/metrics.js

@@ -0,0 +1,115 @@
+// defineMetric 与内置指标。
+//
+// null ≠ 0:null = 此 attempt 测不了这个指标(不进聚合);0 = 测了,结果是零(照常进)。
+// 哪个 verdict 落哪边必须显式表态,内置指标按 docs/feature/reports/library.md「内置指标」的表格:
+//
+//   指标(name)             skipped  errored          failed  passed        better
+//   passRate(pass-rate)     null     0                0       1             higher
+//   examScore(exam-score)   null     0                0       soft 均分      higher
+//   durationMs(duration)    null     实测             实测     实测          lower
+//   tokens(tokens)          null     实测;无 usage→null 同左   同左          lower
+//   costUSD(cost)           null     同上             同左     同左          lower
+//   turns(turns)             null     实测;o11y 缺失→null 同左  同左          lower
+//
+// 两档指标(docs/feature/reports/library.md「内置指标」):以上除 turns 外全部只读 attempt.result
+// 的瘦身字段——任何 producer、任何 copySnapshots artifacts 选择都算得出,内置报告
+// ExperimentComparison 只用这一档。turns 读 attempt.o11y()(懒加载 artifact),发布时若
+// o11y 没随行就诚实渲染缺数据「—」,不算 0——报告作者自己摆时心里要有这根弦,内置报告不用它。
+/**
+ * 定义一个指标。内置指标与自定义指标是同一个类型,没有特权;
+ * 校验只管「能进计算」的最低要求,聚合语义见 docs/feature/reports/architecture.md「指标聚合不变量」。
+ * name 是 const 泛型:产物的 name 保持字面量,`row.cells[metric.name]` 才有编译期列键。
+ */
+export function defineMetric(def) {
+    if (typeof def.name !== "string" || def.name.length === 0) {
+        throw new Error("defineMetric: metric name must be a non-empty string.");
+    }
+    if (typeof def.value !== "function") {
+        throw new Error(`defineMetric: metric "${def.name}" must provide a value(attempt) function.`);
+    }
+    return { ...def };
+}
+/** 单 attempt 成本:网关实测(usage.costUSD)优先于价格表估算(estimatedCostUSD);都缺 → null,不编 0。 */
+export function attemptCostUSD(result) {
+    return result.usage?.costUSD ?? result.estimatedCostUSD ?? null;
+}
+export const passRate = defineMetric({
+    name: "pass-rate",
+    label: { en: "Pass rate", "zh-CN": "成功率" },
+    description: "Share of evals that passed (skipped attempts excluded).",
+    better: "higher",
+    unit: "%",
+    value: (a) => a.result.verdict === "skipped" ? null : a.result.verdict === "passed" ? 1 : 0,
+});
+export const examScore = defineMetric({
+    name: "exam-score",
+    label: { en: "Exam score", "zh-CN": "考试得分" },
+    description: "Per-eval score: gates decide pass, soft assertions grade quality.",
+    better: "higher",
+    unit: "%",
+    value(a) {
+        const { verdict, assertions } = a.result;
+        if (verdict === "skipped")
+            return null;
+        // 先按 verdict 分派,再看断言:errored 的断言是空数组,「gate 全过才得分」的
+        // 字面实现会让条件空真成立、崩溃反而得满分 —— 交白卷是 0 分,不是缺数据,更不是满分。
+        // failed 同理得 0:--strict 下被翻成 failed 的哪怕 soft 分不低也是 0(报告不重新判卷)。
+        if (verdict !== "passed")
+            return 0;
+        const soft = assertions.filter((x) => x.severity === "soft");
+        if (soft.length === 0)
+            return 1;
+        return soft.reduce((sum, x) => sum + x.score, 0) / soft.length;
+    },
+});
+export const durationMs = defineMetric({
+    name: "duration",
+    label: { en: "Duration", "zh-CN": "平均耗时" },
+    description: "Wall-clock duration of the attempt.",
+    better: "lower",
+    unit: "ms",
+    value: (a) => (a.result.verdict === "skipped" ? null : a.result.durationMs),
+});
+export const tokens = defineMetric({
+    name: "tokens",
+    label: { en: "Tokens", "zh-CN": "Tokens" },
+    description: "Input + output tokens (cache reads/writes excluded).",
+    better: "lower",
+    unit: "tokens",
+    value(a) {
+        if (a.result.verdict === "skipped")
+            return null;
+        const usage = a.result.usage;
+        if (!usage)
+            return null;
+        // 只加 input + output:缓存读写量大但便宜,计进去会把缓存热的 agent 画成 token 大户;
+        // 花钱多少本来就有 costUSD 负责。
+        return usage.inputTokens + usage.outputTokens;
+    },
+});
+export const costUSD = defineMetric({
+    name: "cost",
+    label: { en: "Cost", "zh-CN": "预估成本" },
+    description: "USD cost per attempt (gateway-measured beats estimated).",
+    better: "lower",
+    unit: "$",
+    value: (a) => (a.result.verdict === "skipped" ? null : attemptCostUSD(a.result)),
+});
+/**
+ * 唯一读 artifact(o11y,懒加载)的内置指标——其余五个只读瘦身字段。
+ * 发布时若该 attempt 没带 o11y(如 copySnapshots 的 artifacts 选项漏了它),
+ * value 如实返回 null,渲染成「—」,不冒充 0——见 docs/feature/reports/library.md「内置指标」。
+ */
+export const turns = defineMetric({
+    name: "turns",
+    label: { en: "Turns", "zh-CN": "轮次" },
+    description: "Total agent turns (assistant replies) per attempt. Reads o11y — “—” if not published alongside this attempt.",
+    better: "lower",
+    unit: "turns",
+    async value(a) {
+        if (a.result.verdict === "skipped")
+            return null;
+        const o11y = await a.o11y();
+        return o11y?.totalTurns ?? null;
+    },
+});