niceeval 0.3.0 → 0.4.1

package/src/report/index.ts

@@ -0,0 +1,40 @@
+// niceeval/report —— 报告积木的第二档:指标 × 计算函数,纯数据、零渲染。
+// 契约见 docs/reports.md「指标与聚合」「计算函数与数据契约」。
+//
+// import 边界即运行时边界:本层的计算函数会经句柄触碰文件系统(懒加载工件),
+// 只能进服务端 / 脚本;React 组件(第一档)在 niceeval/report/react,纯渲染。
+// 句柄与证据身份(SnapshotHandle / AttemptHandle / AttemptRef)来自 niceeval/results。
+
+export { defineMetric, passRate, examScore, durationMs, tokens, costUSD } from "./metrics.ts";
+
+export { table, matrix, scoreboard, scatter, overview, delta, cases } from "./compute.ts";
+
+export type {
+  TableOptions,
+  MatrixOptions,
+  ScoreboardOptions,
+  ScatterOptions,
+  OverviewOptions,
+  DeltaOptions,
+  DeltaPair,
+  CasesOptions,
+} from "./compute.ts";
+
+export type {
+  Aggregator,
+  MetricAggregate,
+  Metric,
+  Dimension,
+  MetricColumn,
+  MetricCell,
+  AttemptRef,
+  TableData,
+  MatrixData,
+  ScoreboardData,
+  ScatterData,
+  OverviewData,
+  DeltaData,
+  CaseListData,
+} from "./types.ts";
+
+export type { SnapshotHandle, AttemptHandle, RunHandle } from "../results/types.ts";

package/src/report/metrics.ts

@@ -0,0 +1,96 @@
+// defineMetric 与内置指标。
+//
+// null ≠ 0:null = 此 attempt 测不了这个指标(不进聚合);0 = 测了,结果是零(照常进)。
+// 哪个 outcome 落哪边必须显式表态,内置指标按 docs/reports.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
+
+import type { EvalResult } from "../types.ts";
+import type { Metric } from "./types.ts";
+
+/**
+ * 定义一个指标。内置指标与自定义指标是同一个类型,没有特权;
+ * 校验只管「能进计算」的最低要求,聚合语义见 docs/reports.md。
+ */
+export function defineMetric(def: Metric): Metric {
+  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: EvalResult): number | null {
+  return result.usage?.costUSD ?? result.estimatedCostUSD ?? null;
+}
+
+export const passRate = defineMetric({
+  name: "pass-rate",
+  label: "Pass rate",
+  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,
+});
+
+export const examScore = defineMetric({
+  name: "exam-score",
+  label: "Exam score",
+  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 全过才得分」的
+    // 字面实现会让条件空真成立、崩溃反而得满分 —— 交白卷是 0 分,不是缺数据,更不是满分。
+    // failed 同理得 0:--strict 下被翻成 failed 的哪怕 soft 分不低也是 0(报告不重新判卷)。
+    if (outcome !== "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: "Duration",
+  description: "Wall-clock duration of the attempt.",
+  better: "lower",
+  unit: "ms",
+  value: (a) => (a.result.outcome === "skipped" ? null : a.result.durationMs),
+});
+
+export const tokens = defineMetric({
+  name: "tokens",
+  label: "Tokens",
+  description: "Input + output tokens (cache reads/writes excluded).",
+  better: "lower",
+  unit: "tokens",
+  value(a) {
+    if (a.result.outcome === "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: "Cost",
+  description: "USD cost per attempt (gateway-measured beats estimated).",
+  better: "lower",
+  unit: "$",
+  value: (a) => (a.result.outcome === "skipped" ? null : attemptCostUSD(a.result)),
+});

package/src/report/react/CaseList.tsx

@@ -0,0 +1,70 @@
+// CaseList:失败案例清单——报告回答完「多少」,这里回答「为什么」。
+// 逐条列出失败断言 / error 摘要 / judge 评语(evidence),每条带 attemptHref 下钻;
+// truncated 如实报「还有 n 条没列」。长文本收进 <details>,零 JS 也能展开。
+
+import type { ReactElement } from "react";
+import type { AttemptRef, CaseListData } from "./data.ts";
+import { colorClassForKey } from "./colors.ts";
+import { cx, formatDurationMs, formatUSD } from "./format.ts";
+
+export function CaseList({
+  data,
+  attemptHref,
+  className,
+}: {
+  data: CaseListData;
+  attemptHref?: (ref: AttemptRef) => string;
+  className?: string;
+}): ReactElement {
+  return (
+    <section className={cx("nre", "nre-case-list", className)}>
+      {data.rows.length === 0 && <p className="nre-case-empty">No failed or errored attempts</p>}
+      <ol className="nre-cases">
+        {data.rows.map((row) => (
+          <li key={`${row.ref.run}:${row.ref.result}`} className={cx("nre-case", `nre-case-${row.outcome}`)}>
+            <div className="nre-case-head">
+              <span className={cx("nre-case-outcome", `nre-outcome-${row.outcome}`)}>{row.outcome}</span>
+              <span className="nre-case-eval">{row.eval}</span>
+              {/* agent 键:稳定散列上色,与其它块同键同色 */}
+              <span className={cx("nre-case-agent", "nre-key", colorClassForKey(row.agent))}>{row.agent}</span>
+              <span className="nre-case-experiment">{row.experimentId}</span>
+              <span className="nre-case-duration">{formatDurationMs(row.durationMs)}</span>
+              {row.costUSD !== undefined && <span className="nre-case-cost">{formatUSD(row.costUSD)}</span>}
+              {attemptHref && (
+                <a className="nre-case-link" href={attemptHref(row.ref)}>
+                  查看 attempt
+                </a>
+              )}
+            </div>
+
+            {/* errored 的错误摘要(计算侧已过 redact) */}
+            {row.error && <p className="nre-case-error">{row.error}</p>}
+
+            {row.failedAssertions.length > 0 && (
+              <ul className="nre-assertions">
+                {row.failedAssertions.map((assertion, j) => (
+                  <li key={j} className="nre-assertion">
+                    <span className="nre-assertion-name">{assertion.name}</span>
+                    <span className="nre-assertion-score">score {assertion.score}</span>
+                    {/* detail / evidence 可能很长:<details> 收起,不 hydrate 也能展开 */}
+                    {(assertion.detail || assertion.evidence) && (
+                      <details className="nre-assertion-more">
+                        <summary>details</summary>
+                        {assertion.detail && <p className="nre-assertion-detail">{assertion.detail}</p>}
+                        {assertion.evidence && (
+                          <blockquote className="nre-assertion-evidence">{assertion.evidence}</blockquote>
+                        )}
+                      </details>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            )}
+          </li>
+        ))}
+      </ol>
+      {/* limit 之外还有几条,如实报,不静默截断 */}
+      {data.truncated > 0 && <p className="nre-truncated">and {data.truncated} more not shown</p>}
+    </section>
+  );
+}

package/src/report/react/DeltaTable.tsx

@@ -0,0 +1,79 @@
+// DeltaTable:成对对比(B 相对 A)。每格三个值:A、B、Δ;
+// Δ 的涨跌好坏由指标的 better 判定并配色(涨不一定是好——成本涨了是坏);
+// 任一侧缺数据时 Δ 显示为缺,不硬算(数据侧已给 delta: null,这里只如实渲染)。
+
+import type { ReactElement } from "react";
+import type { DeltaData, MetricColumn } from "./data.ts";
+import { MetricCellView } from "./cell.tsx";
+import { colorClassForKey } from "./colors.ts";
+import { MISSING_TEXT, cx } from "./format.ts";
+
+/** Δ 的语义配色 class:好/坏由 better 方向判定,不看正负号本身。 */
+function deltaToneClass(delta: number | null, better: MetricColumn["better"]): string {
+  if (delta === null) return "nre-delta-missing";
+  if (delta === 0) return "nre-delta-flat";
+  if (!better) return "nre-delta-neutral"; // 指标没表态方向,只显示不评判
+  const improved = better === "higher" ? delta > 0 : delta < 0;
+  return improved ? "nre-delta-good" : "nre-delta-bad";
+}
+
+export function DeltaTable({
+  data,
+  className,
+}: {
+  data: DeltaData;
+  className?: string;
+}): ReactElement {
+  return (
+    <table className={cx("nre", "nre-delta-table", className)}>
+      <thead>
+        <tr>
+          <th scope="col" className="nre-dimension">
+            对比(A → B)
+          </th>
+          {data.columns.map((col) => (
+            <th scope="col" key={col.key} className="nre-metric-col">
+              {col.label}
+              {col.unit && <span className="nre-unit">({col.unit})</span>}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {data.rows.map((row) => (
+          <tr key={row.key}>
+            <th scope="row" className="nre-pair">
+              {/* pair 的 label(如 agent 名):稳定散列上色,与 scatter 的线同色 */}
+              <span className={cx("nre-row-key", "nre-key", colorClassForKey(row.key))}>{row.key}</span>
+              <span className="nre-pair-ids">
+                {row.a.experimentId} → {row.b.experimentId}
+              </span>
+            </th>
+            {data.columns.map((col) => {
+              const cell = row.cells[col.key];
+              if (!cell) return <td key={col.key} className="nre-td-empty" />;
+              return (
+                <td key={col.key} className="nre-delta-cell">
+                  {/* A/B 走统一的 MetricCellView:缺数据文案与覆盖率角标同一套 */}
+                  <span className="nre-delta-side nre-delta-a">
+                    <span className="nre-delta-tag">A</span>
+                    <MetricCellView cell={cell.a} />
+                  </span>
+                  <span className="nre-delta-side nre-delta-b">
+                    <span className="nre-delta-tag">B</span>
+                    <MetricCellView cell={cell.b} />
+                  </span>
+                  <span className={cx("nre-delta-side", "nre-delta-d", deltaToneClass(cell.delta, col.better))}>
+                    <span className="nre-delta-tag">Δ</span>
+                    {/* 任一侧 null → delta null:显示缺,不硬算 */}
+                    {cell.delta === null ? <span className="nre-missing">{MISSING_TEXT}</span> : cell.display}
+                  </span>
+                </td>
+              );
+            })}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

package/src/report/react/MetricMatrix.tsx

@@ -0,0 +1,75 @@
+// MetricMatrix:行 × 列 × 单指标(如 eval × agent × passRate)。
+// cells 是稀疏的——没有样本的格子在数据里不出现,这里就空着,不补 0;
+// 行/列顺序取 cells 里的首次出现顺序(排序是数据侧的事)。
+// cell.refs + attemptHref:「哪道题谁挂了」之后的下一步「给我看那次 attempt」
+// 是格子里的普通 <a>,不 hydrate 也能点。
+
+import type { ReactElement } from "react";
+import type { AttemptRef, MatrixData } from "./data.ts";
+import { MetricCellView } from "./cell.tsx";
+import { colorClassForKey } from "./colors.ts";
+import { cx } from "./format.ts";
+
+export function MetricMatrix({
+  data,
+  attemptHref,
+  className,
+}: {
+  data: MatrixData;
+  attemptHref?: (ref: AttemptRef) => string;
+  className?: string;
+}): ReactElement {
+  // 稀疏 cells → 首次出现顺序的行/列键 + 查找表;组件只整理形状,不碰数值
+  const rowKeys: string[] = [];
+  const columnKeys: string[] = [];
+  // 键用 \u0000 拼接:行/列键都是用户可见 id,普通分隔符可能撞键
+  const byPosition = new Map<string, MatrixData["cells"][number]["cell"]>();
+  for (const entry of data.cells) {
+    if (!rowKeys.includes(entry.row)) rowKeys.push(entry.row);
+    if (!columnKeys.includes(entry.column)) columnKeys.push(entry.column);
+    byPosition.set(`${entry.row}\u0000${entry.column}`, entry.cell);
+  }
+
+  return (
+    <table className={cx("nre", "nre-metric-matrix", className)}>
+      <caption className="nre-matrix-caption">
+        {data.metric.label}
+        {data.metric.unit && <span className="nre-unit">({data.metric.unit})</span>}
+        <span className="nre-matrix-axes">
+          {data.rows} × {data.columns}
+        </span>
+      </caption>
+      <thead>
+        <tr>
+          <th scope="col" className="nre-dimension">
+            {data.rows}
+          </th>
+          {columnKeys.map((column) => (
+            // 列键 = 维度键(如 agent):稳定散列上色,与 scatter 的线、DeltaTable 的行同色
+            <th scope="col" key={column} className={cx("nre-col-key", "nre-key", colorClassForKey(column))}>
+              {column}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {rowKeys.map((row) => (
+          <tr key={row}>
+            <th scope="row" className="nre-row-key">
+              {row}
+            </th>
+            {columnKeys.map((column) => {
+              const cell = byPosition.get(`${row}\u0000${column}`);
+              return (
+                <td key={column} className={cx("nre-td", !cell && "nre-td-empty")}>
+                  {/* 稀疏格子:没有样本就空着(数据里不存在),不是 0 也不是缺数据文案 */}
+                  {cell ? <MetricCellView cell={cell} attemptHref={attemptHref} /> : null}
+                </td>
+              );
+            })}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}

package/src/report/react/MetricScatter.tsx

@@ -0,0 +1,217 @@
+// MetricScatter:质量 × 成本 frontier 的积木,内联 SVG、零图表库。
+// 轴向随 better:"lower" 的轴反向画,「好」的角落恒在右上(成本轴 $20 → $0 就是这么来的);
+// 同系列的点按 x 值排序连线,系列名标在线旁;x 或 y 为 null 的点不画,
+// 底部注脚如实报「n 个点缺数据」;hover 信息退化为 SVG <title>,不 hydrate 也在。
+
+import type { ReactElement } from "react";
+import type { MetricColumn, ScatterData } from "./data.ts";
+import { colorHexForKey } from "./colors.ts";
+import { MISSING_TEXT, cx } from "./format.ts";
+
+// 画布与边距:右侧留白给系列名,底部给 x 轴标签
+const WIDTH = 640;
+const HEIGHT = 400;
+const PLOT = { left: 64, right: WIDTH - 140, top: 24, bottom: HEIGHT - 56 };
+
+/** 可画的点:x/y 都有值。组件内部的整理结果,不改数据。 */
+interface DrawablePoint {
+  key: string;
+  series?: string;
+  xValue: number;
+  yValue: number;
+  xDisplay: string;
+  yDisplay: string;
+  title: string;
+  px: number;
+  py: number;
+}
+
+/** 一根轴的线性映射:值 → 像素;better:"lower" 时反向,好的一端固定在右/上。 */
+function axisScale(values: number[], better: MetricColumn["better"], pixelLo: number, pixelHi: number) {
+  const lo = Math.min(...values);
+  const hi = Math.max(...values);
+  // 单值域:铺 ±1 让唯一的点落在正中,而不是除零
+  const span = hi - lo || 2;
+  const padded = { lo: lo - (hi - lo ? span * 0.08 : 1), hi: hi + (hi - lo ? span * 0.08 : 1) };
+  const scale = (v: number) => {
+    let t = (v - padded.lo) / (padded.hi - padded.lo);
+    if (better === "lower") t = 1 - t; // 反向:值越低越靠「好」的一端
+    return pixelLo + t * (pixelHi - pixelLo);
+  };
+  return { lo, hi, scale };
+}
+
+export function MetricScatter({
+  data,
+  pointHref,
+  className,
+}: {
+  data: ScatterData;
+  pointHref?: (row: ScatterData["rows"][number]) => string;
+  className?: string;
+}): ReactElement {
+  const missing = data.rows.filter((r) => r.x.value === null || r.y.value === null);
+  const drawableRows = data.rows.filter((r) => r.x.value !== null && r.y.value !== null);
+
+  const missingNote =
+    missing.length > 0 ? (
+      <p className="nre-scatter-missing" title={missing.map((r) => r.key).join(", ")}>
+        {missing.length} {missing.length === 1 ? "point" : "points"} missing data
+      </p>
+    ) : null;
+
+  // 一张全缺的图不画空坐标系:缺数据文案 + 注脚,与表格的「绝不画 0」同一态度
+  if (drawableRows.length === 0) {
+    return (
+      <figure className={cx("nre", "nre-metric-scatter", className)}>
+        <p className="nre-missing">{MISSING_TEXT}</p>
+        {missingNote}
+      </figure>
+    );
+  }
+
+  const xScale = axisScale(drawableRows.map((r) => r.x.value as number), data.x.better, PLOT.left, PLOT.right);
+  // y 像素轴向下增长:better:"higher" 高值在上 → 映射到 [bottom, top];"lower" 由 axisScale 反向后同样落到上方
+  const yScale = axisScale(drawableRows.map((r) => r.y.value as number), data.y.better, PLOT.bottom, PLOT.top);
+
+  const points: DrawablePoint[] = drawableRows.map((r) => {
+    const xValue = r.x.value as number;
+    const yValue = r.y.value as number;
+    return {
+      key: r.key,
+      series: r.series,
+      xValue,
+      yValue,
+      xDisplay: r.x.display,
+      yDisplay: r.y.display,
+      // hover 内容:display 与 samples/total(docs/reports.md 行为清单)
+      title: `${r.key}\n${data.x.label}: ${r.x.display}(${r.x.samples}/${r.x.total})\n${data.y.label}: ${r.y.display}(${r.y.samples}/${r.y.total})`,
+      px: xScale.scale(xValue),
+      py: yScale.scale(yValue),
+    };
+  });
+
+  // 同系列的点按 x 值排序连线;无系列的点只画点不连线
+  const seriesOrder: string[] = [];
+  const bySeries = new Map<string, DrawablePoint[]>();
+  for (const p of points) {
+    if (p.series === undefined) continue;
+    if (!bySeries.has(p.series)) {
+      bySeries.set(p.series, []);
+      seriesOrder.push(p.series);
+    }
+    bySeries.get(p.series)!.push(p);
+  }
+  for (const list of bySeries.values()) list.sort((a, b) => a.xValue - b.xValue);
+
+  // 轴端刻度打在真实极值点的位置上(值域有 padding,角落不等于极值)
+  const xTicks = xScale.lo === xScale.hi ? [xScale.lo] : [xScale.lo, xScale.hi];
+  const yTicks = yScale.lo === yScale.hi ? [yScale.lo] : [yScale.lo, yScale.hi];
+  const displayFor = (axis: "x" | "y", value: number) =>
+    points.find((p) => (axis === "x" ? p.xValue : p.yValue) === value)?.[axis === "x" ? "xDisplay" : "yDisplay"] ??
+    String(value);
+
+  const axisLabel = (col: MetricColumn) => `${col.label}${col.unit ? `(${col.unit})` : ""}`;
+
+  return (
+    <figure className={cx("nre", "nre-metric-scatter", className)}>
+      <svg
+        className="nre-scatter-svg"
+        viewBox={`0 0 ${WIDTH} ${HEIGHT}`}
+        role="img"
+        aria-label={`${axisLabel(data.x)} × ${axisLabel(data.y)}`}
+      >
+        {/* 坐标框 */}
+        <rect
+          className="nre-scatter-plot"
+          x={PLOT.left}
+          y={PLOT.top}
+          width={PLOT.right - PLOT.left}
+          height={PLOT.bottom - PLOT.top}
+          fill="none"
+          stroke="#d4d4d4"
+        />
+        {/* 「好」的角落恒在右上:轴向已按 better 反转,这里只是把这句契约写在图上 */}
+        <text className="nre-scatter-better-hint" x={PLOT.right - 6} y={PLOT.top + 14} textAnchor="end" fontSize={11} fill="#9ca3af">
+          better ↗
+        </text>
+
+        {/* 轴标签 */}
+        <text className="nre-scatter-xlabel" x={(PLOT.left + PLOT.right) / 2} y={HEIGHT - 8} textAnchor="middle" fontSize={12} fill="#525252">
+          {axisLabel(data.x)}
+        </text>
+        <text
+          className="nre-scatter-ylabel"
+          x={16}
+          y={(PLOT.top + PLOT.bottom) / 2}
+          textAnchor="middle"
+          fontSize={12}
+          fill="#525252"
+          transform={`rotate(-90 16 ${(PLOT.top + PLOT.bottom) / 2})`}
+        >
+          {axisLabel(data.y)}
+        </text>
+
+        {/* 轴端刻度:标在真实极值的位置上,文案用该点已格式化的 display */}
+        {xTicks.map((v) => (
+          <text key={`x${v}`} className="nre-scatter-tick" x={xScale.scale(v)} y={PLOT.bottom + 16} textAnchor="middle" fontSize={11} fill="#737373">
+            {displayFor("x", v)}
+          </text>
+        ))}
+        {yTicks.map((v) => (
+          <text key={`y${v}`} className="nre-scatter-tick" x={PLOT.left - 6} y={yScale.scale(v) + 4} textAnchor="end" fontSize={11} fill="#737373">
+            {displayFor("y", v)}
+          </text>
+        ))}
+
+        {/* 系列连线 + 线旁的系列名(标在视觉上最靠右的点旁) */}
+        {seriesOrder.map((series) => {
+          const list = bySeries.get(series)!;
+          const color = colorHexForKey(series);
+          const labelAt = list.reduce((a, b) => (b.px > a.px ? b : a));
+          return (
+            <g key={series} className="nre-scatter-series" data-series={series}>
+              {list.length > 1 && (
+                <polyline
+                  className="nre-scatter-line"
+                  points={list.map((p) => `${p.px},${p.py}`).join(" ")}
+                  fill="none"
+                  stroke={color}
+                  strokeWidth={1.5}
+                />
+              )}
+              <text className="nre-scatter-series-label" x={labelAt.px + 8} y={labelAt.py + 4} fontSize={12} fill={color}>
+                {series}
+              </text>
+            </g>
+          );
+        })}
+
+        {/* 点(带 <title> 的 hover;pointHref 时包普通 <a>,静态导出也能下钻) */}
+        {points.map((p, i) => {
+          const circle = (
+            <circle
+              className="nre-scatter-point"
+              data-key={p.key}
+              cx={p.px}
+              cy={p.py}
+              r={4.5}
+              fill={p.series !== undefined ? colorHexForKey(p.series) : "#525252"}
+            >
+              <title>{p.title}</title>
+            </circle>
+          );
+          const row = drawableRows[i];
+          return pointHref ? (
+            <a key={p.key} className="nre-scatter-point-link" href={pointHref(row)}>
+              {circle}
+            </a>
+          ) : (
+            <g key={p.key}>{circle}</g>
+          );
+        })}
+      </svg>
+      {missingNote}
+    </figure>
+  );
+}

package/src/report/react/MetricTable.tsx

@@ -0,0 +1,71 @@
+// MetricTable:行维度 × 指标列。
+// 行按传入顺序渲染——排序发生在计算侧(table() 的 sort 参数),组件不重排;
+// 「点列头重排」是后续的渐进增强,不 hydrate 时以数据侧预排的顺序呈现即完整。
+// 列头以箭头标注 better 方向;samples < total 的格子带覆盖率角标;
+// 一组全 null 渲染成「缺数据」,绝不画 0(逻辑在 MetricCellView)。
+
+import type { ReactElement } from "react";
+import type { AttemptRef, TableData } from "./data.ts";
+import { MetricCellView } from "./cell.tsx";
+import { colorClassForKey } from "./colors.ts";
+import { cx } from "./format.ts";
+
+export function MetricTable({
+  data,
+  attemptHref,
+  className,
+}: {
+  data: TableData;
+  attemptHref?: (ref: AttemptRef) => string;
+  className?: string;
+}): ReactElement {
+  return (
+    <table className={cx("nre", "nre-metric-table", className)}>
+      <thead>
+        <tr>
+          <th scope="col" className="nre-dimension">
+            {data.dimension}
+          </th>
+          {data.columns.map((col) => (
+            <th scope="col" key={col.key} className="nre-metric-col">
+              {col.label}
+              {col.unit && <span className="nre-unit">({col.unit})</span>}
+              {/* better 方向提示:↑ 越高越好 / ↓ 越低越好 */}
+              {col.better && (
+                <span
+                  className="nre-better"
+                  title={col.better === "higher" ? "higher is better" : "lower is better"}
+                >
+                  {col.better === "higher" ? "↑" : "↓"}
+                </span>
+              )}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {data.rows.map((row) => (
+          <tr key={row.key}>
+            {/* 行键 = 维度键(如 agent):稳定散列上色,跨块同键同色 */}
+            <th scope="row" className={cx("nre-row-key", "nre-key", colorClassForKey(row.key))}>
+              {row.key}
+            </th>
+            {data.columns.map((col) => {
+              const cell = row.cells[col.key];
+              return (
+                <td key={col.key} className="nre-td">
+                  {cell ? (
+                    <MetricCellView cell={cell} attemptHref={attemptHref} />
+                  ) : (
+                    // 数据侧没给这个格子(理论上 table() 不会缺列)——按空处理,不编数
+                    <span className="nre-empty" />
+                  )}
+                </td>
+              );
+            })}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}