niceeval 0.6.1 → 0.7.0

package/src/report/react/ExperimentComparison.tsx

@@ -0,0 +1,73 @@
+// ExperimentComparison 的 web 面:完整持有所有可比组,组选择只切换已经独立计算好的 panel。
+// 静态 HTML 用原生 <details> 保留每组完整内容(第一组默认展开、无 JS 完整可读);
+// enhance.js 再把上方摘要卡变成单选切换。切组是纯浏览状态,不重新计算任何数字。
+
+import type { ReactElement } from "react";
+import type { ExperimentComparisonData } from "../types.ts";
+import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../locale.ts";
+import { ScopeSummary } from "./ScopeSummary.tsx";
+import { MetricScatter } from "./MetricScatter.tsx";
+import { ExperimentList } from "./ExperimentList.tsx";
+import type { AttemptLocator } from "../../results/locator.ts";
+import { cx } from "./format.ts";
+
+export function ExperimentComparisonView({
+  data,
+  className,
+  locale = DEFAULT_REPORT_LOCALE,
+  attemptHref,
+}: {
+  data: ExperimentComparisonData;
+  className?: string;
+  locale?: ReportLocale;
+  attemptHref?: (locator: AttemptLocator) => string;
+}): ReactElement {
+  if (data.groups.length === 0) {
+    return (
+      <div className={cx("nre", "nre-experiment-comparison", className)}>
+        <p className="nre-experiment-groups-empty">{localeText(locale, "experimentComparison.empty")}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cx("nre", "nre-experiment-comparison", className)} data-nre-experiment-groups>
+      <div
+        className="nre-experiment-group-tabs"
+        role="tablist"
+        aria-label={localeText(locale, "experimentComparison.groups")}
+      >
+        {data.groups.map((group, index) => (
+          <div
+            key={group.key}
+            className="nre-experiment-group-tab"
+            role="tab"
+            tabIndex={index === 0 ? 0 : -1}
+            aria-selected={index === 0 ? "true" : "false"}
+            aria-label={localeText(locale, "experimentComparison.selectGroup", { group: group.key })}
+            data-nre-experiment-group-select={index}
+          >
+            <strong className="nre-experiment-group-name">{group.key}</strong>
+            <ScopeSummary data={group.summary} locale={locale} />
+          </div>
+        ))}
+      </div>
+
+      <div className="nre-experiment-group-panels">
+        {data.groups.map((group, index) => (
+          <details
+            key={group.key}
+            className="nre-experiment-group-panel"
+            data-nre-experiment-group-panel={index}
+            role="tabpanel"
+            open={index === 0}
+          >
+            <summary>{group.key}</summary>
+            <MetricScatter data={group.scatter} locale={locale} />
+            <ExperimentList data={group.experiments} filter locale={locale} relativeTo={group.key} attemptHref={attemptHref} />
+          </details>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/report/react/ExperimentList.tsx

@@ -1,17 +1,20 @@
-// ExperimentList:实体列表的第一级。web 面是一行一个 experiment 的固定列比较表；
-// 每行用原生 <details> 展开到 Eval 与 Attempt locator。数据仍完全来自
-// ExperimentList.data(),不恢复旧 ExperimentTable 的混合实体计算层。
+// ExperimentList:实体列表的第一级。web 面是一行一个 experiment 的固定八列比较表
+// (Experiment / Model / Agent / Avg duration / End-to-end pass rate / Tokens / Cost / Result),
+// 每行用原生 <details> 展开到 Eval 与 Attempt locator。数据完全来自 experimentListData(),
+// 组件不重算、不推断组边界。
 
 import type { ReactElement } from "react";
 import type { AttemptLocator } from "../../results/locator.ts";
 import type { AttemptListItem, ExperimentListEvalRow, ExperimentListItem } from "../types.ts";
-import { attemptItemReason } from "../format.ts";
+import { experimentDisplayName } from "../format.ts";
 import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../locale.ts";
-import { AttemptLocatorBadge } from "./AttemptList.tsx";
+import { AttemptLocatorBadge, failureSummaryText } from "./AttemptList.tsx";
 import { MetricCellView } from "./cell.tsx";
 import { colorClassForKey } from "./colors.ts";
 import { cx, formatDurationMs, formatUSD, verdictMark } from "./format.ts";
 
+const DEFAULT_ATTEMPT_HREF = (locator: AttemptLocator): string => `#/attempt/${locator}`;
+
 const verdictOrder = ["passed", "failed", "errored", "skipped"] as const;
 
 function passRateTone(value: number | null): string | undefined {
@@ -34,8 +37,8 @@ function formatDate(value: string, locale: ReportLocale): string {
 
 function VerdictSummary({ item, locale }: { item: ExperimentListItem; locale: ReportLocale }): ReactElement {
   const parts = verdictOrder
-    .filter((verdict) => item.verdicts[verdict] > 0)
-    .map((verdict) => `${item.verdicts[verdict]} ${localeText(locale, `verdict.${verdict}`)}`);
+    .filter((verdict) => item.evalVerdicts[verdict] > 0)
+    .map((verdict) => `${item.evalVerdicts[verdict]} ${localeText(locale, `verdict.${verdict}`)}`);
   return <span className="nre-experiment-pill">{parts.join(" / ") || "—"}</span>;
 }
 
@@ -43,12 +46,14 @@ function ExperimentAttemptRow({
   attempt,
   last,
   attemptHref,
+  locale,
 }: {
   attempt: AttemptListItem;
   last: boolean;
   attemptHref: (locator: AttemptLocator) => string;
+  locale: ReportLocale;
 }): ReactElement {
-  const reason = attemptItemReason(attempt);
+  const reason = failureSummaryText(attempt, locale);
   return (
     <li className={cx("nre-experiment-attempt-row", `nre-eval-${attempt.verdict}`)}>
       <span className="nre-attempt-branch" aria-hidden="true">{last ? "└─" : "├─"}</span>
@@ -57,8 +62,9 @@ function ExperimentAttemptRow({
       </span>
       <span className="nre-eval-attempt-metrics">
         {formatDurationMs(attempt.durationMs)}
-        {attempt.costUSD !== undefined && <> · {formatUSD(attempt.costUSD)}</>}
+        {attempt.costUSD !== null && <> · {formatUSD(attempt.costUSD)}</>}
       </span>
+      {/* passed attempt 的 Result 是 —,不罗列通过的 assertions */}
       <span className="nre-eval-reason">{reason ?? "—"}</span>
     </li>
   );
@@ -73,18 +79,19 @@ function EvalAttempts({
   attemptHref: (locator: AttemptLocator) => string;
   locale: ReportLocale;
 }): ReactElement {
+  const duration = row.durationMs.value === null ? localeText(locale, "cell.missing") : formatDurationMs(row.durationMs.value);
+  const cost = row.costUSD.value === null ? localeText(locale, "cell.missing") : formatUSD(row.costUSD.value);
   return (
     <li className="nre-experiment-eval">
+      {/* Eval 父行只显示折叠判定、Attempt 数与题级平均;失败原因只在 Attempt 子行 */}
       <div className={cx("nre-experiment-eval-header", `nre-eval-${row.verdict}`)}>
         <span className={cx("nre-eval-verdict", `nre-verdict-${row.verdict}`)}>{verdictMark(row.verdict)}</span>
         <span className="nre-eval-id">{row.evalId}</span>
         <span className="nre-eval-attempt-count">{localeText(locale, "overview.attemptsCount", { n: row.attempts.length })}</span>
-        <span className="nre-eval-summary">
-          {row.verdict === "passed"
-            ? [formatDurationMs(row.duration.value ?? 0), row.cost.value === null ? undefined : formatUSD(row.cost.value)]
-                .filter((value): value is string => value !== undefined)
-                .join(" · ")
-            : row.reason}
+        <span className="nre-eval-rollup">
+          {localeText(locale, "entityList.average", { value: duration })}
+          {" · "}
+          {localeText(locale, "entityList.average", { value: cost })}
         </span>
       </div>
       <ul className="nre-experiment-attempts">
@@ -94,6 +101,7 @@ function EvalAttempts({
             attempt={attempt}
             last={index === row.attempts.length - 1}
             attemptHref={attemptHref}
+            locale={locale}
           />
         ))}
       </ul>
@@ -107,7 +115,7 @@ function Flags({ flags, locale }: { flags: Record<string, unknown> | undefined;
     <div className="nre-experiment-flags">
       <span>{localeText(locale, "experimentList.flags")}</span>
       {Object.entries(flags).map(([key, value]) => (
-        <b key={key}>{key}={String(value)}</b>
+        <b key={key}>{key}={typeof value === "string" ? value : JSON.stringify(value)}</b>
       ))}
     </div>
   );
@@ -117,16 +125,21 @@ function ExperimentRow({
   item,
   attemptHref,
   locale,
+  relativeTo,
 }: {
   item: ExperimentListItem;
   attemptHref: (locator: AttemptLocator) => string;
   locale: ReportLocale;
+  relativeTo?: string;
 }): ReactElement {
   return (
     <details className="nre-experiment-entry">
       <summary className="nre-experiment-summary">
+        {/* relativeTo 只影响显示末段;完整 id 仍是排序 / 着色 / 过滤 / 折叠的键 */}
         <span className="nre-experiment-name" data-sort-value={item.experimentId}>
-          <b className={cx("nre-experiment-id", "nre-key", colorClassForKey(item.experimentId))}>{item.experimentId}</b>
+          <b className={cx("nre-experiment-id", "nre-key", colorClassForKey(item.experimentId))}>
+            {experimentDisplayName(item.experimentId, relativeTo)}
+          </b>
           <small>
             {localeText(locale, "overview.evalsCount", { n: item.evals })}
             {item.attempts > item.evals ? ` · ${localeText(locale, "overview.attemptsCount", { n: item.attempts })}` : ""}
@@ -135,19 +148,22 @@ function ExperimentRow({
         </span>
         <span data-sort-value={item.model ?? ""}>{item.model ?? localeText(locale, "experimentList.defaultModel")}</span>
         <span data-sort-value={item.agent}>{item.agent}</span>
-        <span className="nre-num" data-sort-value={item.duration.value ?? ""}>
-          <MetricCellView cell={item.duration} locale={locale} />
+        <span className="nre-num" data-sort-value={item.durationMs.value ?? ""}>
+          <MetricCellView cell={item.durationMs} locale={locale} />
         </span>
-        <span className={cx("nre-num", passRateTone(item.passRate.value))} data-sort-value={item.passRate.value ?? ""}>
-          <MetricCellView cell={item.passRate} locale={locale} />
+        <span
+          className={cx("nre-num", passRateTone(item.endToEndPassRate.value))}
+          data-sort-value={item.endToEndPassRate.value ?? ""}
+        >
+          <MetricCellView cell={item.endToEndPassRate} locale={locale} />
         </span>
         <span className="nre-num" data-sort-value={item.tokens.value ?? ""}>
           <MetricCellView cell={item.tokens} locale={locale} />
         </span>
-        <span className="nre-num" data-sort-value={item.cost.value ?? ""}>
-          <MetricCellView cell={item.cost} locale={locale} />
+        <span className="nre-num" data-sort-value={item.costUSD.value ?? ""}>
+          <MetricCellView cell={item.costUSD} locale={locale} />
         </span>
-        <span data-sort-value={item.verdicts.passed}><VerdictSummary item={item} locale={locale} /></span>
+        <span data-sort-value={item.evalVerdicts.passed}><VerdictSummary item={item} locale={locale} /></span>
       </summary>
       <div className="nre-experiment-detail">
         <Flags flags={item.flags} locale={locale} />
@@ -162,17 +178,19 @@ function ExperimentRow({
 }
 
 export function ExperimentList({
-  items,
-  attemptHref,
+  data,
+  attemptHref = DEFAULT_ATTEMPT_HREF,
   filter = false,
   className,
   locale = DEFAULT_REPORT_LOCALE,
+  relativeTo,
 }: {
-  items: ExperimentListItem[];
-  attemptHref: (locator: AttemptLocator) => string;
+  data: readonly ExperimentListItem[];
+  attemptHref?: (locator: AttemptLocator) => string;
   filter?: boolean;
   className?: string;
   locale?: ReportLocale;
+  relativeTo?: string;
 }): ReactElement {
   const labels = [
     localeText(locale, "experimentList.experiment"),
@@ -181,7 +199,7 @@ export function ExperimentList({
     localeText(locale, "experimentList.avgDuration"),
     localeText(locale, "experimentList.passRate"),
     localeText(locale, "experimentList.tokens"),
-    localeText(locale, "experimentList.estimatedCost"),
+    localeText(locale, "experimentList.cost"),
     localeText(locale, "experimentList.result"),
   ];
   const board = (
@@ -198,9 +216,9 @@ export function ExperimentList({
           </button>
         ))}
       </div>
-      {items.length === 0 && <p className="nre-experiment-list-empty">{localeText(locale, "attemptList.empty")}</p>}
-      {items.map((item) => (
-        <ExperimentRow key={item.experimentId} item={item} attemptHref={attemptHref} locale={locale} />
+      {data.length === 0 && <p className="nre-experiment-list-empty">{localeText(locale, "attemptList.empty")}</p>}
+      {data.map((item) => (
+        <ExperimentRow key={item.experimentId} item={item} attemptHref={attemptHref} locale={locale} relativeTo={relativeTo} />
       ))}
     </div>
   );

package/src/report/react/MetricBars.tsx

@@ -6,7 +6,7 @@
 import type { ReactElement } from "react";
 import type { MatrixData, MetricCell } from "../types.ts";
 import type { AttemptLocator } from "../../results/locator.ts";
-import { DEFAULT_REPORT_LOCALE, resolveMetricLabel, type ReportLocale } from "../locale.ts";
+import { DEFAULT_REPORT_LOCALE, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
 import { colorClassForKey, seriesClassForKey } from "./colors.ts";
 import { cx } from "./format.ts";
 
@@ -52,7 +52,7 @@ export function MetricBars({
         className="nre-bars-svg"
         viewBox={`0 0 ${WIDTH} ${HEIGHT}`}
         role="img"
-        aria-label={`${metricLabel} by ${data.rows} × ${data.columns}`}
+        aria-label={`${metricLabel} by ${data.rowDimension} × ${data.columnDimension}`}
       >
         {groupKeys.map((group, gi) => {
           const x0 = PLOT.left + gi * groupWidth;
@@ -71,7 +71,8 @@ export function MetricBars({
                 const h = Math.max(1, ratioOf(cell.value as number) * plotHeight);
                 const x = startX + si * barWidth;
                 const y = PLOT.bottom - h;
-                const title = `${group} · ${series}: ${cell.display}(${cell.samples}/${cell.total})`;
+                const display = resolveLocalizedText(cell.display, locale);
+                const title = `${group} · ${series}: ${display}(${cell.samples}/${cell.total})`;
                 const rect = (
                   <rect
                     className={cx("nre-bar", seriesClassForKey(series))}
@@ -89,7 +90,7 @@ export function MetricBars({
                     {attemptHref && locator ? <a href={attemptHref(locator)}>{rect}</a> : rect}
                     {/* 柱顶标数值;覆盖不全时把 samples/total 一并标出,不藏 */}
                     <text className="nre-bar-value" x={x + barWidth / 2} y={y - 4} textAnchor="middle">
-                      {cell.samples < cell.total ? `${cell.display} ${cell.samples}/${cell.total}` : cell.display}
+                      {cell.samples < cell.total ? `${display} ${cell.samples}/${cell.total}` : display}
                     </text>
                   </g>
                 );

package/src/report/react/MetricLine.tsx

@@ -7,7 +7,7 @@
 
 import type { ReactElement } from "react";
 import type { LineData } from "../types.ts";
-import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
+import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
 import { seriesClassForKey } from "./colors.ts";
 import { cx } from "./format.ts";
 
@@ -52,6 +52,7 @@ export function MetricLine({
   const missing = data.rows.filter((r) => r.x === null || r.y.value === null);
   const drawableRows = data.rows.filter((r) => r.x !== null && r.y.value !== null);
   const yLabel = resolveMetricLabel(data.y.label, locale, data.y.key);
+  const xLabel = resolveMetricLabel(data.x.label, locale, data.x.key);
 
   const missingNote =
     missing.length > 0 ? (
@@ -83,7 +84,7 @@ export function MetricLine({
     series: r.series,
     xValue: r.x as number,
     yValue: r.y.value as number,
-    title: `${r.key}\n${data.x.label}: ${r.xDisplay}\n${yLabel}: ${r.y.display}(${r.y.samples}/${r.y.total})`,
+    title: `${r.key}\n${xLabel}: ${resolveLocalizedText(r.xDisplay, locale)}\n${yLabel}: ${resolveLocalizedText(r.y.display, locale)}(${r.y.samples}/${r.y.total})`,
     px: xScale.scale(r.x as number),
     py: yScale.scale(r.y.value as number),
   }));
@@ -103,10 +104,14 @@ export function MetricLine({
 
   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 xDisplayFor = (value: number) =>
-    drawableRows.find((r) => r.x === value)?.xDisplay ?? String(value);
-  const yDisplayFor = (value: number) =>
-    drawableRows.find((r) => r.y.value === value)?.y.display ?? String(value);
+  const xDisplayFor = (value: number) => {
+    const row = drawableRows.find((r) => r.x === value);
+    return row === undefined ? String(value) : resolveLocalizedText(row.xDisplay, locale);
+  };
+  const yDisplayFor = (value: number) => {
+    const row = drawableRows.find((r) => r.y.value === value);
+    return row === undefined ? String(value) : resolveLocalizedText(row.y.display, locale);
+  };
 
   return (
     <figure className={cx("nre", "nre-metric-line", className)}>
@@ -114,7 +119,7 @@ export function MetricLine({
         className="nre-line-svg"
         viewBox={`0 0 ${WIDTH} ${HEIGHT}`}
         role="img"
-        aria-label={`${yLabel} by ${data.x.label}`}
+        aria-label={`${yLabel} by ${xLabel}`}
       >
         <rect
           className="nre-line-plot"
@@ -125,7 +130,7 @@ export function MetricLine({
           fill="none"
         />
         <text className="nre-line-xlabel" x={(PLOT.left + PLOT.right) / 2} y={HEIGHT - 8} textAnchor="middle">
-          {data.x.label}
+          {xLabel}
           {data.x.unit ? `(${data.x.unit})` : ""}
         </text>
         <text

package/src/report/react/MetricMatrix.tsx

@@ -40,13 +40,13 @@ export function MetricMatrix({
         {resolveMetricLabel(data.metric.label, locale, data.metric.key)}
         {data.metric.unit && <span className="nre-unit">({data.metric.unit})</span>}
         <span className="nre-matrix-axes">
-          {data.rows} × {data.columns}
+          {data.rowDimension} × {data.columnDimension}
         </span>
       </caption>
       <thead>
         <tr>
           <th scope="col" className="nre-dimension">
-            {data.rows}
+            {data.rowDimension}
           </th>
           {columnKeys.map((column) => (
             // 列键 = 维度键(如 agent):稳定散列上色,与 scatter 的线、DeltaTable 的行同色

package/src/report/react/MetricScatter.tsx

@@ -1,6 +1,8 @@
 // MetricScatter:质量 × 成本 frontier 的积木,内联 SVG、零图表库、零 hooks。
-// 轴向随 better:"lower" 的轴反向画,「好」的角落恒在右上(成本轴 $20 → $0 就是这么来的);
-// niceTicks 刻度 + 网格线;每个点直接标注(防撞布局,被挤开时补 leader line);
+// 轴向随 better:"lower" 的轴反向画(值大在左/下),「更好」恒指向右上;方向提示恒为
+// 「越靠右上越好」且仅当两轴都声明 better 时显示;刻度显示真实值。
+// niceTicks 刻度 + 网格线;每个点直接标注(placePointLabels 候选位择优:避开其它标签、
+// 数据点与画布边界,离开左右紧邻位时补 leader line);
 // 同系列的点按 x 值排序连线,系列图例列在图下。x 或 y 为 null 的点不画,
 // 底部注脚如实报「n 个点缺数据」;hover 信息退化为 SVG <title>,不 hydrate 也在
 // (enhance.js 在场时升级为样式化 tooltip)。配色走类名(nre-series-cN)由 CSS 上色,
@@ -9,8 +11,8 @@
 import type { ReactElement } from "react";
 import type { MetricColumn, ScatterData } from "../types.ts";
 import { formatMetricValue } from "../format.ts";
-import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
-import { layoutLabelOffsets, niceTicks } from "./chart-math.ts";
+import { DEFAULT_REPORT_LOCALE, countText, localeText, resolveLocalizedText, resolveMetricLabel, type ReportLocale } from "../locale.ts";
+import { niceTicks, placePointLabels } from "./chart-math.ts";
 import { colorClassForKey, seriesClassForKey } from "./colors.ts";
 import { cx } from "./format.ts";
 
@@ -32,22 +34,54 @@ interface DrawablePoint {
   py: number;
 }
 
-/** 点的直接标签:experiment id 的末段(完整 id 在 <title> 里)。 */
-function pointLabel(key: string): string {
-  return key.split("/").filter(Boolean).at(-1) ?? key;
+/**
+ * 点的直接标签:末段在当前 data 中唯一才缩成末段;重名时逐步加长为能区分它们的最短
+ * 路径后缀(完整 id 与两轴值仍进 <title>)。
+ */
+function pointLabels(keys: readonly string[]): Map<string, string> {
+  const segsOf = (key: string) => key.split("/").filter(Boolean);
+  const depth = new Map<string, number>(keys.map((key) => [key, 1]));
+  for (;;) {
+    const byLabel = new Map<string, string[]>();
+    for (const key of keys) {
+      const segs = segsOf(key);
+      const label = segs.slice(-Math.min(depth.get(key)!, segs.length)).join("/") || key;
+      byLabel.set(label, [...(byLabel.get(label) ?? []), key]);
+    }
+    let grew = false;
+    for (const group of byLabel.values()) {
+      if (group.length < 2) continue;
+      for (const key of group) {
+        const segs = segsOf(key);
+        if (depth.get(key)! < segs.length) {
+          depth.set(key, depth.get(key)! + 1);
+          grew = true;
+        }
+      }
+    }
+    if (!grew) {
+      const out = new Map<string, string>();
+      for (const key of keys) {
+        const segs = segsOf(key);
+        out.set(key, segs.slice(-Math.min(depth.get(key)!, segs.length)).join("/") || key);
+      }
+      return out;
+    }
+  }
 }
 
 /**
- * 一根轴:niceTicks 撑出整齐的值域,值 → 像素做线性映射;
- * better: "lower" 时反向,好的一端固定在右 / 上。
+ * 一根轴:niceTicks 撑出整齐的值域,值 → 像素做线性映射。轴方向跟随指标的 `better`:
+ * `better: "lower"` 的轴反向渲染(值大的一端在左 / 下),「更好」因此恒指向右与上;
+ * 刻度标签始终显示真实值,反向只改方向不改数字(docs/feature/reports/library/metric-views.md)。
  */
-function axisScale(values: number[], better: MetricColumn["better"], pixelLo: number, pixelHi: number) {
+function axisScale(values: number[], pixelLo: number, pixelHi: number, invert: boolean) {
   const ticks = niceTicks(Math.min(...values), Math.max(...values), 5);
   const lo = ticks[0];
   const hi = ticks[ticks.length - 1];
   const scale = (v: number) => {
     let t = (v - lo) / (hi - lo || 1);
-    if (better === "lower") t = 1 - t; // 反向:值越低越靠「好」的一端
+    if (invert) t = 1 - t;
     return pixelLo + t * (pixelHi - pixelLo);
   };
   return { ticks, scale };
@@ -90,9 +124,24 @@ export function MetricScatter({
 
   const axisLabel = (label: string, col: MetricColumn) => `${label}${col.unit ? `(${col.unit})` : ""}`;
 
-  const xScale = axisScale(drawableRows.map((r) => r.x.value as number), data.x.better, MARGIN.left, MARGIN.left + PLOT_W);
-  // y 像素轴向下增长:better:"higher" 高值在上 → 映射到 [bottom, top];"lower" 由 axisScale 反向后同样落到上方
-  const yScale = axisScale(drawableRows.map((r) => r.y.value as number), data.y.better, MARGIN.top + PLOT_H, MARGIN.top);
+  // 轴方向跟随 better:lower 反向(值大在左 / 下),higher 与未声明正向。
+  const xScale = axisScale(
+    drawableRows.map((r) => r.x.value as number),
+    MARGIN.left,
+    MARGIN.left + PLOT_W,
+    data.x.better === "lower",
+  );
+  // y 像素轴向下增长:正向 = 高值在上 → 映射到 [bottom, top];lower 反向 = 高值在下。
+  const yScale = axisScale(
+    drawableRows.map((r) => r.y.value as number),
+    MARGIN.top + PLOT_H,
+    MARGIN.top,
+    data.y.better === "lower",
+  );
+  const labelByKey = pointLabels(drawableRows.map((r) => r.key));
+  // 方向提示恒为「越靠右上越好」,仅当两轴都声明 better 时显示——任一轴未声明,
+  // 组件不猜「更好」朝哪边,整图无提示。
+  const showBetterHint = data.x.better !== undefined && data.y.better !== undefined;
 
   const points: DrawablePoint[] = drawableRows.map((r) => {
     const xValue = r.x.value as number;
@@ -100,12 +149,11 @@ export function MetricScatter({
     return {
       key: r.key,
       series: r.series,
-      label: pointLabel(r.key),
+      label: labelByKey.get(r.key) ?? r.key,
       xValue,
       yValue,
-      // hover 内容:experiment(点键)+ 系列(series,ExperimentComparison 传的是 agent 维度,
-      // 有则加一行;无系列的散点没有这行)+ 两轴 display 与 samples/total(docs/feature/reports/library.md「MetricScatter」行为清单)
-      title: `${r.key}${r.series !== undefined ? `\n${r.series}` : ""}\n${xLabel}: ${r.x.display}(${r.x.samples}/${r.x.total})\n${yLabel}: ${r.y.display}(${r.y.samples}/${r.y.total})`,
+      // hover 内容:experiment(点键)+ 系列(有则加一行)+ 两轴 display 与 samples/total
+      title: `${r.key}${r.series !== undefined ? `\n${r.series}` : ""}\n${xLabel}: ${resolveLocalizedText(r.x.display, locale)}(${r.x.samples}/${r.x.total})\n${yLabel}: ${resolveLocalizedText(r.y.display, locale)}(${r.y.samples}/${r.y.total})`,
       px: xScale.scale(xValue),
       py: yScale.scale(yValue),
     };
@@ -124,12 +172,11 @@ export function MetricScatter({
   }
   for (const list of bySeries.values()) list.sort((a, b) => a.xValue - b.xValue);
 
-  // 直接标签的防撞布局:靠右的点把标签锚到左侧,重叠的往下推、补 leader line
-  const positions = points.map((p) => {
-    const anchorLeft = p.px >= MARGIN.left + PLOT_W * 0.72;
-    return { cx: p.px, cy: p.py, anchorLeft, width: p.label.length * 6.4 + 10 };
-  });
-  const labelOffsets = layoutLabelOffsets(positions);
+  // 直接标签的候选位择优布局:锚向、避让方向都由布局按空间决定,画布边界含边距
+  const labels = placePointLabels(
+    points.map((p) => ({ cx: p.px, cy: p.py, width: p.label.length * 6.4 + 10 })),
+    { x0: 2, y0: 2, x1: WIDTH - 2, y1: HEIGHT - 2 },
+  );
 
   return (
     <figure className={cx("nre", "nre-metric-scatter", className)}>
@@ -149,10 +196,17 @@ export function MetricScatter({
           ))}
         </g>
 
-        {/* 「好」的角落恒在右上:轴向已按 better 反转,这里只是把这句契约写在图上 */}
-        <text className="nre-scatter-better-hint" x={MARGIN.left + PLOT_W - 6} y={MARGIN.top + 14} textAnchor="end">
-          {localeText(locale, "scatter.betterHint")}
-        </text>
+        {/* 轴向已随 better 反正,「更好」恒指向右上;提示只在两轴都声明 better 时出现 */}
+        {showBetterHint && (
+          <text
+            className="nre-scatter-better-hint"
+            x={MARGIN.left + PLOT_W - 6}
+            y={MARGIN.top + 14}
+            textAnchor="end"
+          >
+            {localeText(locale, "scatter.betterUpperRight")}
+          </text>
+        )}
 
         {/* 刻度:已格式化的整齐值(formatMetricValue 与计算侧同一套) */}
         <g className="nre-scatter-axis nre-scatter-axis-y">
@@ -202,20 +256,18 @@ export function MetricScatter({
         {/* 点:g 内带 <title>(无 JS 的原生 hover)、直接标签与 leader line;
             pointHref 时包普通 <a>,静态导出也能下钻 */}
         {points.map((p, i) => {
-          const { anchorLeft } = positions[i];
-          const labelX = p.px + (anchorLeft ? -10 : 10);
-          const labelY = p.py + 4 + labelOffsets[i];
+          const label = labels[i];
           const group = (
             <g
               className={cx("nre-scatter-point", p.series !== undefined ? seriesClassForKey(p.series) : "nre-series-none")}
               data-key={p.key}
             >
               <title>{p.title}</title>
-              {/* 标签被挤开时补一条 leader line,避免脱离原点看不出对应关系 */}
-              {labelOffsets[i] !== 0 && <line className="nre-leader" x1={p.px} y1={p.py} x2={labelX} y2={labelY - 4} />}
+              {/* 标签不在紧邻位时补一条 leader line,避免脱离原点看不出对应关系 */}
+              {label.leader && <line className="nre-leader" x1={p.px} y1={p.py} x2={label.x} y2={label.y - 4} />}
               <circle className="nre-scatter-hit" cx={p.px} cy={p.py} r={12} />
               <circle className="nre-scatter-dot" cx={p.px} cy={p.py} r={4.5} />
-              <text className="nre-scatter-point-label" x={labelX} y={labelY} textAnchor={anchorLeft ? "end" : "start"}>
+              <text className="nre-scatter-point-label" x={label.x} y={label.y} textAnchor={label.anchor}>
                 {p.label}
               </text>
             </g>