niceeval 0.5.4 → 0.6.0

package/src/report/flag.ts

@@ -1,4 +1,4 @@
-// flag():把 experiment 声明的 flags 当维度或轴(docs/reports.md「flags 与新摆法」)。
+// flag():把 experiment 声明的 flags 当维度或轴(docs/feature/reports/library.md「维度与 flags」)。
 // 变量来自配置,不来自命名 —— 报告不解析 experiment id 字符串抠变量。
 
 import type { FlagRef } from "./types.ts";

package/src/report/format.ts

@@ -1,7 +1,10 @@
-// unit 驱动的内置格式化(docs/reports.md「指标与聚合」):
+// unit 驱动的内置格式化(docs/feature/reports/library.md「指标」):
 //   "%" → 87%    "ms" → 1.2s    "$" → $0.31    其余 → 1.2k 缩写(带 unit 后缀)
 // metric.display 可整体覆盖;这里只负责默认。
 
+import type { AttemptEvidenceCapabilities } from "../results/attempt-evidence.ts";
+import type { AssertionResult, Verdict } from "../types.ts";
+
 /** 一位小数、去掉无意义的 ".0" 尾巴。 */
 function trimmed(n: number): string {
   const s = n.toFixed(1);
@@ -49,7 +52,7 @@ export function formatPlainNumber(value: number): string {
 // ── 以下是两个渲染面共用的展示格式化:MetricCell 一律自带 display(格式化发生在
 //    计算侧),渲染面不重算;这里只服务 OverviewData 这类携带裸数字的字段。──
 
-/** 全 null / 无样本的统一文案。绝不画 0(docs/reports.md「null ≠ 0」)。 */
+/** 全 null / 无样本的统一文案。绝不画 0(docs/feature/reports/architecture.md「指标聚合不变量」)。 */
 export const MISSING_TEXT = "no data";
 
 /** 毫秒 → 人读耗时("850ms" / "1.2s" / "4m 20s" / "1h 4m")。 */
@@ -74,3 +77,48 @@ export function formatUSD(usd: number): string {
 export function formatPercent(ratio: number): string {
   return `${Math.round(ratio * 100)}%`;
 }
+
+// ── 实体列表(ExperimentList / EvalList / AttemptList)共用的判定符与证据能力位 ──
+// web / text 两面对同一个 AttemptListItem 给出同一个标记(docs-site「终端输出形成反馈闭环」)。
+
+/** passed / failed / errored / skipped 的判定符。 */
+export function verdictMark(verdict: Verdict): string {
+  switch (verdict) {
+    case "passed":
+      return "✓";
+    case "failed":
+      return "✗";
+    case "errored":
+      return "!";
+    case "skipped":
+      return "–";
+  }
+}
+
+/**
+ * 证据能力标记:`[E,X,⏱]` 式方括号列表,固定顺序 eval → execution → timing → diff,
+ * 缺哪个不列哪个;四位全无时返回空串(没有证据可看,不画空 `[]`)。
+ */
+export function capabilityBadge(capabilities: AttemptEvidenceCapabilities): string {
+  const marks: string[] = [];
+  if (capabilities.eval) marks.push("E");
+  if (capabilities.execution) marks.push("X");
+  if (capabilities.timing) marks.push("⏱");
+  if (capabilities.diff) marks.push("D");
+  return marks.length > 0 ? `[${marks.join(",")}]` : "";
+}
+
+/**
+ * 一个 AttemptListItem 的失败原因摘要,按优先级取第一个在场的:`error` → 未通过的 gate 断言
+ * (原始声明顺序,`name`,detail 在场则 `"name: detail"`,多条用「, 」连接)→ 缺席。与
+ * compute.ts 的 `reasonFor(EvalResult)` 同一口径,只是输入换成瘦身后的 AttemptListItem——
+ * 没有 `skipReason` 字段(AttemptListItem 不携带),skipped 的 attempt 因此没有原因摘要,
+ * 这与它们本来就不该出现在「为什么失败」列表里的事实一致。EvalList / ExperimentList 的
+ * 逐 attempt 徽标行用它给每个 attempt 自己的原因(而不是复用整道题的代表原因)。
+ */
+export function attemptItemReason(item: { error?: string; assertions: AssertionResult[] }): string | undefined {
+  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/src/report/index.ts

@@ -1,15 +1,15 @@
 // niceeval/report —— 报告积木:指标 × 计算函数 × 双面组件 × defineReport。
-// 契约见 docs/reports.md;公开叙事的准绳是 docs-site/zh/guides/custom-reports.mdx
+// 契约见 docs/feature/reports/README.md;公开叙事的准绳是 docs-site/zh/guides/custom-reports.mdx
 // 与 report-components.mdx。
 //
 // import 边界即运行时边界:计算函数(挂在组件上的 .data)会经句柄触碰文件系统
-// (懒加载工件),只能进服务端 / 脚本;组件的渲染面纯同步零 IO。text 宿主遍历渲染
+// (懒加载 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 } from "./metrics.ts";
+export { defineMetric, passRate, examScore, durationMs, tokens, costUSD, turns } from "./metrics.ts";
 export { flag } from "./flag.ts";
 
 // 报告基座与双面组件基座
@@ -26,17 +26,38 @@ export type {
   WebContext,
 } from "./tree.ts";
 
-// 排版原语(五个内置双面组件)
-export { Row, Col, Section, Text, Style } from "./primitives.tsx";
-export type { LayoutProps, SectionProps, StyleProps } from "./primitives.tsx";
+// 排版原语(六个内置双面组件)
+export { Row, Col, Section, Text, Style, Table } from "./primitives.tsx";
+export type { LayoutProps, SectionProps, StyleProps, TableColumn, TableProps, TableRow } from "./primitives.tsx";
 
-// 官方水位整块(零 props 的锚点)
-export { DefaultReport } from "./default-report.tsx";
+// 文本排版工具箱:自定义组件的 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.ts";
+export type { ColumnAlign } from "./text/layout.ts";
+
+// 内置报告(show / view 裸跑时报告槽的出厂填充,一份普通 ReportDefinition,无 renderer 特权)
+export { CostPassRateComparison } from "./built-ins/index.ts";
+
+// locale:官方组件 chrome 文案的语言(en / zh-CN);指标 label 可按 locale 给字典
+export { DEFAULT_REPORT_LOCALE, resolveMetricLabel } from "./locale.ts";
+export type { LocalizedLabel, ReportLocale } from "./locale.ts";
 
 // 官方双面组件(各自带 data 计算函数;MetricBars.data = MetricMatrix.data)
 export {
-  CaseList,
+  AttemptList,
   DeltaTable,
+  EvalList,
+  ExperimentList,
+  GroupSummary,
   MetricBars,
   MetricLine,
   MetricMatrix,
@@ -46,8 +67,11 @@ export {
   Scoreboard,
 } from "./components.tsx";
 export type {
-  CaseListProps,
+  AttemptListProps,
   DeltaTableProps,
+  EvalListProps,
+  ExperimentListProps,
+  GroupSummaryProps,
   MetricLineProps,
   MetricMatrixProps,
   MetricScatterProps,
@@ -58,7 +82,7 @@ export type {
 
 // 计算函数的选项类型(函数本体挂在组件上,不做顶层导出)
 export type {
-  CaseListDataOptions,
+  AttemptListDataOptions,
   DeltaDataOptions,
   DeltaPair,
   LineDataOptions,
@@ -71,11 +95,16 @@ export type {
 // 数据契约(组件的 data props)
 export type {
   Aggregator,
-  AttemptRef,
-  CaseListData,
+  AttemptEvidenceCapabilities,
+  AttemptListItem,
+  AttemptLocator,
   DeltaData,
   Dimension,
   DimensionInput,
+  EvalListItem,
+  ExperimentListEvalRow,
+  ExperimentListItem,
+  GroupSummaryData,
   LineAxis,
   LineData,
   MatrixData,
@@ -89,7 +118,12 @@ export type {
   ScoreboardData,
   SelectionWarning,
   TableData,
+  TableRowMeta,
 } from "./types.ts";
 
 // 数据层输入的类型(家在 niceeval/results,这里 re-export 方便写指标 / 报告)
-export type { AttemptHandle, Results, Selection, Snapshot } from "../results/index.ts";
+export type { AttemptHandle, Results, Selection, Snapshot } from "../results/types.ts";
+
+// experiment id 的组键推导(id 的目录前缀,如 `compare/bub-low` 的 `compare`)。
+// 重新导出,让自定义报告能按同一份口径把 experiment 分组,不必自己重写这两行逻辑。
+export { experimentGroupOf } from "../shared/aggregate.ts";

package/src/report/load.ts

@@ -1,7 +1,7 @@
 // --report 的装载:两个宿主(show / view)共用的中性入口。复用跑用户 .ts 配置的
 // 同一 tsx 加载机制(bin 里已 register)。show 一进程一次装载;view 的 dev server
 // 每次请求现读现渲染 —— ESM 模块缓存永不失效,所以按文件 mtime 做 cache-busting
-// (freshImport):报告文件变更 → 下次请求拿到新模块,整页重算(docs/reports.md
+// (freshImport):报告文件变更 → 下次请求拿到新模块,整页重算(docs/feature/reports/view.md
 // 裁决记录 6)。装载环境坑见 memory/tsx-dynamic-import-require-cycle.md。
 
 import { existsSync, statSync } from "node:fs";

package/src/report/locale.ts

@@ -0,0 +1,206 @@
+// 官方组件 chrome 文案的 locale 字典(en / zh-CN 两份)。
+// 只覆盖组件自带的固定文案(verdict 词、缺数据、覆盖率角标、注脚、占位符等);
+// 数据本身(display、维度键、warnings 的 message)不经这里。
+// 刻意不 import src/i18n/(CLI 专用字典,locale 来源与 key 面完全不同);
+// zh-CN 译法与 src/view/app/i18n.ts 现有词保持一致(成功率/平均耗时/预估成本…)。
+
+/** 报告渲染的 locale;默认 "en"(text 面缺省即 en,`niceeval show` 输出不变)。 */
+export type ReportLocale = "en" | "zh-CN";
+
+export const DEFAULT_REPORT_LOCALE: ReportLocale = "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",
+  /** <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}",
+  /** 恰好 1 个可画点:比较至少要两个实验。 */
+  "scatter.needTwo": "At least 2 experiments needed to compare {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:",
+} as const;
+
+export type ReportMessageKey = keyof typeof en;
+
+const zhCN: Record<ReportMessageKey, string> = {
+  "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",
+  "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} 没有可绘制的数据",
+  "scatter.needTwo": "至少需要 2 个实验才能比较 {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: Record<ReportLocale, Record<ReportMessageKey, string>> = {
+  en,
+  "zh-CN": zhCN,
+};
+
+/** 查字典 + 简单插值({name} 占位符)。缺 locale 回退 en。 */
+export function localeText(
+  locale: ReportLocale,
+  key: ReportMessageKey,
+  vars?: Record<string, string | number>,
+): string {
+  const template = dictionaries[locale]?.[key] ?? dictionaries.en[key];
+  if (!vars) return template;
+  return template.replace(/\{(\w+)\}/g, (m, name: string) =>
+    name in vars ? String(vars[name]) : m,
+  );
+}
+
+/** 带单复数的计数文案:n === 1 用 `<base>.one`,其余 `<base>.other`(zh-CN 两键同值)。 */
+export function countText(
+  locale: ReportLocale,
+  base: "overview.experiments" | "composedFrom" | "pointsMissing" | "scoreboard.missing" | "table.columnsHidden",
+  n: number,
+): string {
+  return localeText(locale, `${base}.${n === 1 ? "one" : "other"}` as ReportMessageKey, { n });
+}
+
+/** 指标 label 的可本地化形态:字符串,或按 locale 给的字典(缺项回退 en,再回退任一非空值)。 */
+export type LocalizedLabel = string | Partial<Record<ReportLocale, string>>;
+
+/**
+ * 按 locale 解析指标 label:字符串原样;字典取当前 locale,缺项回退 en,
+ * 再回退字典里任一值;全空回退 fallback(= metric.name)。渲染面(web / text)共用。
+ */
+export function resolveMetricLabel(
+  label: LocalizedLabel | undefined,
+  locale: ReportLocale,
+  fallback: string,
+): string {
+  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/src/report/metrics.ts

@@ -1,7 +1,7 @@
 // defineMetric 与内置指标。
 //
 // null ≠ 0:null = 此 attempt 测不了这个指标(不进聚合);0 = 测了,结果是零(照常进)。
-// 哪个 outcome 落哪边必须显式表态,内置指标按 docs/reports.md 的表格:
+// 哪个 verdict 落哪边必须显式表态,内置指标按 docs/feature/reports/library.md「内置指标」的表格:
 //
 //   指标(name)             skipped  errored          failed  passed        better
 //   passRate(pass-rate)     null     0                0       1             higher
@@ -9,13 +9,19 @@
 //   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 选择都算得出,内置报告
+// CostPassRateComparison 只用这一档。turns 读 attempt.o11y()(懒加载 artifact),发布时若
+// o11y 没随行就诚实渲染缺数据「—」,不算 0——报告作者自己摆时心里要有这根弦,内置报告不用它。
 
 import type { EvalResult } from "../types.ts";
 import type { Metric } from "./types.ts";
 
 /**
  * 定义一个指标。内置指标与自定义指标是同一个类型,没有特权;
- * 校验只管「能进计算」的最低要求,聚合语义见 docs/reports.md。
+ * 校验只管「能进计算」的最低要求,聚合语义见 docs/feature/reports/architecture.md「指标聚合不变量」。
  * name 是 const 泛型:产物的 name 保持字面量,`row.cells[metric.name]` 才有编译期列键。
  */
 export function defineMetric<const Name extends string>(def: Metric<Name>): Metric<Name> {
@@ -35,27 +41,27 @@ export function attemptCostUSD(result: EvalResult): number | null {
 
 export const passRate = defineMetric({
   name: "pass-rate",
-  label: "Pass rate",
+  label: { en: "Pass rate", "zh-CN": "成功率" },
   description: "Share of evals that passed (skipped attempts excluded).",
   better: "higher",
   unit: "%",
   value: (a) =>
-    a.result.outcome === "skipped" ? null : a.result.outcome === "passed" ? 1 : 0,
+    a.result.verdict === "skipped" ? null : a.result.verdict === "passed" ? 1 : 0,
 });
 
 export const examScore = defineMetric({
   name: "exam-score",
-  label: "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 { outcome, assertions } = a.result;
-    if (outcome === "skipped") return null;
-    // 先按 outcome 分派,再看断言:errored 的断言是空数组,「gate 全过才得分」的
+    const { verdict, assertions } = a.result;
+    if (verdict === "skipped") return null;
+    // 先按 verdict 分派,再看断言:errored 的断言是空数组,「gate 全过才得分」的
     // 字面实现会让条件空真成立、崩溃反而得满分 —— 交白卷是 0 分,不是缺数据,更不是满分。
     // failed 同理得 0:--strict 下被翻成 failed 的哪怕 soft 分不低也是 0(报告不重新判卷)。
-    if (outcome !== "passed") return 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;
@@ -64,21 +70,21 @@ export const examScore = defineMetric({
 
 export const durationMs = defineMetric({
   name: "duration",
-  label: "Duration",
+  label: { en: "Duration", "zh-CN": "平均耗时" },
   description: "Wall-clock duration of the attempt.",
   better: "lower",
   unit: "ms",
-  value: (a) => (a.result.outcome === "skipped" ? null : a.result.durationMs),
+  value: (a) => (a.result.verdict === "skipped" ? null : a.result.durationMs),
 });
 
 export const tokens = defineMetric({
   name: "tokens",
-  label: "Tokens",
+  label: { en: "Tokens", "zh-CN": "Tokens" },
   description: "Input + output tokens (cache reads/writes excluded).",
   better: "lower",
   unit: "tokens",
   value(a) {
-    if (a.result.outcome === "skipped") return null;
+    if (a.result.verdict === "skipped") return null;
     const usage = a.result.usage;
     if (!usage) return null;
     // 只加 input + output:缓存读写量大但便宜,计进去会把缓存热的 agent 画成 token 大户;
@@ -89,9 +95,27 @@ export const tokens = defineMetric({
 
 export const costUSD = defineMetric({
   name: "cost",
-  label: "Cost",
+  label: { en: "Cost", "zh-CN": "预估成本" },
   description: "USD cost per attempt (gateway-measured beats estimated).",
   better: "lower",
   unit: "$",
-  value: (a) => (a.result.outcome === "skipped" ? null : attemptCostUSD(a.result)),
+  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;
+  },
 });

package/src/report/primitives.tsx

@@ -1,11 +1,15 @@
-// 排版原语 Row / Col / Section / Text / Style:五个内置双面组件,没有特殊机制。
+// 排版原语 Row / Col / Section / Text / Style / Table:六个内置双面组件,没有特殊机制。
 // web 面是普通 React 渲染;text 面用 ctx.render(child, 子宽) 显式传宽,
 // Row 分栏、宽度不足降级纵向。Style 给自定义组件带样式:web 面吐 <style> 标签,
 // text 面渲染为空 —— 静态导出不打包用户代码,className 引用的 CSS 靠它随树走。
+// Table 是自定义表的标准件,官方表状组件的 text 面也建在它上面(见 ./text/table.ts)。
 
 import type { ReactNode } from "react";
+import type { AttemptLocator } from "../results/locator.ts";
 import { defineComponent, type ReportNode } from "./tree.ts";
-import { indentBlock, joinColumns, wrapDisplay } from "./text/layout.ts";
+import { localeText, type ReportLocale } from "./locale.ts";
+import { indentBlock, joinColumns, wrapDisplay, type ColumnAlign } from "./text/layout.ts";
+import { renderTableText } from "./text/table.ts";
 
 function childArray(children: ReportNode): ReportNode[] {
   if (children === null || children === undefined || typeof children === "boolean") return [];
@@ -115,3 +119,97 @@ export const Style = defineComponent<StyleProps>({
   },
 });
 Style.displayName = "Style";
+
+/** 一列的定义:取哪个 cells 键、表头写什么、往哪边对齐。 */
+export interface TableColumn {
+  /** 取 `row.cells[key]` 的键。 */
+  key: string;
+  /** 表头文案,两个面都原样渲染。 */
+  header: string;
+  /** 对齐方向,默认 `"left"`;`"right"` 按显示宽度右对齐,数字列用。 */
+  align?: ColumnAlign;
+}
+
+/** 一行的数据:身份键、已格式化的格子、可选的 attempt locator。 */
+export interface TableRow {
+  /** 行身份。 */
+  key: string;
+  /** 已格式化的显示值;`null`(或缺这个键)渲染成 `—`,不补 0。 */
+  cells: Record<string, string | null>;
+  /** 带上就多一列 attempt:web 面链到证据室,text 面列出 locator。 */
+  locator?: AttemptLocator;
+}
+
+export interface TableProps {
+  /** 列定义;数组顺序即渲染顺序。 */
+  columns: TableColumn[];
+  /** 行数据;数组顺序即渲染顺序,组件不重排也不过滤。 */
+  rows: TableRow[];
+  /** 组件自带文案(attempt 表头、丢列提示)的语言;省略时随宿主。 */
+  locale?: ReportLocale;
+  /** web 面挂到 `<table>` 上。 */
+  className?: string;
+}
+
+const MISSING_MARK = "—";
+
+/**
+ * 自定义表的标准件:列由报告作者定,格子是算好的显示值,两个面各自排整齐。
+ *
+ * text 面列宽按**显示宽度**算(CJK / 全角记 2 列),所以中文列不会撕歪;总宽超过
+ * `ctx.width` 时先折最宽的左对齐列(右对齐列是数字,折行读不了),压到下限仍放不下
+ * 就从右侧丢列并在表下如实报丢了几列。web 面是 `<table>` + `<thead>` / `<tbody>`,
+ * 右对齐落成 `nre-align-right` 类,不用内联样式。
+ *
+ * 官方的 `MetricTable` / `MetricMatrix` / `Scoreboard` / `DeltaTable` 的 text 面就建在
+ * 这个组件上:自定义表和官方表用同一把尺子。
+ */
+export const Table = defineComponent<TableProps>({
+  web({ columns, rows, locale, className }, ctx) {
+    const chrome = locale ?? ctx.locale;
+    const hasLocator = rows.some((row) => row.locator !== undefined);
+    const alignClass = (align?: ColumnAlign) => (align === "right" ? "nre-align-right" : undefined);
+    return (
+      <table className={cx("nre", "nre-table", className)}>
+        <thead>
+          <tr>
+            {columns.map((column) => (
+              <th key={column.key} scope="col" className={alignClass(column.align)}>
+                {column.header}
+              </th>
+            ))}
+            {hasLocator ? <th scope="col">{localeText(chrome, "table.attempt")}</th> : null}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row.key}>
+              {columns.map((column) => {
+                const value = row.cells[column.key];
+                const missing = value === null || value === undefined;
+                return (
+                  <td key={column.key} className={alignClass(column.align)}>
+                    {missing ? <span className="nre-missing">{MISSING_MARK}</span> : value}
+                  </td>
+                );
+              })}
+              {hasLocator ? (
+                <td>
+                  {row.locator ? (
+                    <a className="nre-locator" href={ctx.attemptHref(row.locator)}>
+                      {row.locator}
+                    </a>
+                  ) : (
+                    <span className="nre-missing">{MISSING_MARK}</span>
+                  )}
+                </td>
+              ) : null}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    );
+  },
+  text: renderTableText,
+});
+Table.displayName = "Table";