niceeval 0.6.1 → 0.6.2

package/src/report/locale.ts

@@ -2,7 +2,7 @@
 // 只覆盖组件自带的固定文案(verdict 词、缺数据、覆盖率角标、注脚、占位符等);
 // 数据本身(display、维度键、warnings 的 message)不经这里。
 // 刻意不 import src/i18n/(CLI 专用字典,locale 来源与 key 面完全不同);
-// zh-CN 译法与 src/view/app/i18n.ts 现有词保持一致(成功率/平均耗时/预估成本…)。
+// zh-CN 译法与默认 Reports 契约保持一致(端到端成功率/平均耗时/预估成本…)。
 
 /** 报告渲染的 locale;默认 "en"(text 面缺省即 en,`niceeval show` 输出不变)。 */
 export type ReportLocale = "en" | "zh-CN";
@@ -34,7 +34,7 @@ const en = {
   "table.attempt": "attempt",
   "experimentList.experiment": "Experiment",
   "experimentList.avgDuration": "Avg duration",
-  "experimentList.passRate": "Pass rate",
+  "experimentList.passRate": "End-to-end pass rate",
   "experimentList.tokens": "Tokens",
   "experimentList.estimatedCost": "Est. cost",
   "experimentList.result": "Result",
@@ -45,6 +45,7 @@ const en = {
   "experimentList.filterPlaceholder": "Filter experiments…",
   "experimentList.defaultModel": "default",
   "experimentList.flags": "Flags",
+  "entityList.average": "{value} avg",
   /** <Table> 压到下限仍放不下时,从右侧丢列并如实报数。 */
   "table.columnsHidden.one": "({n} more column not shown)",
   "table.columnsHidden.other": "({n} more columns not shown)",
@@ -52,7 +53,7 @@ const en = {
   "overview.snapshots": "Snapshots",
   "overview.evals": "Evals",
   "overview.attempts": "attempts",
-  "overview.passRate": "Pass rate",
+  "overview.passRate": "End-to-end pass rate",
   "overview.totalCost": "Total cost",
   "overview.totalDuration": "Total duration",
   "overview.source": "Source: {n} snapshots",
@@ -64,6 +65,14 @@ const en = {
   /** GroupSummary 的 KPI dt 标签(其余字段复用 verdict.* / overview.* 已有 key)。 */
   "groupSummary.experiments": "Experiments",
 
+  "experimentComparison.groups": "Experiment groups",
+  "experimentComparison.group": "Experiment group",
+  "experimentComparison.results": "Results",
+  "experimentComparison.lastRun": "Last run",
+  "experimentComparison.selectGroup": "Select experiment group {group}",
+  "experimentComparison.command": "Details: {command}",
+  "experimentComparison.empty": "No experiment groups",
+
   "composedFrom.one": "composed from {n} run",
   "composedFrom.other": "composed from {n} runs",
   "latestRun": "latest {run}",
@@ -80,6 +89,7 @@ const en = {
   "attemptList.truncated": "and {n} more not shown",
   "attemptList.truncatedText": "({n} more not shown)",
   "attemptList.score": "score {score}",
+  "attemptList.unavailable": "unavailable",
   "attemptList.details": "details",
 
   "scoreboard.total": "Total",
@@ -123,7 +133,7 @@ const zhCN: Record<ReportMessageKey, string> = {
   "table.attempt": "Attempt",
   "experimentList.experiment": "实验",
   "experimentList.avgDuration": "平均耗时",
-  "experimentList.passRate": "成功率",
+  "experimentList.passRate": "端到端成功率",
   "experimentList.tokens": "Tokens",
   "experimentList.estimatedCost": "预估成本",
   "experimentList.result": "结果",
@@ -134,13 +144,14 @@ const zhCN: Record<ReportMessageKey, string> = {
   "experimentList.filterPlaceholder": "筛选实验…",
   "experimentList.defaultModel": "默认",
   "experimentList.flags": "Flags",
+  "entityList.average": "平均 {value}",
   "table.columnsHidden.one": "(还有 {n} 列未列出)",
   "table.columnsHidden.other": "(还有 {n} 列未列出)",
 
   "overview.snapshots": "快照",
   "overview.evals": "题目",
   "overview.attempts": "尝试",
-  "overview.passRate": "通过率",
+  "overview.passRate": "端到端成功率",
   "overview.totalCost": "总成本",
   "overview.totalDuration": "总耗时",
   "overview.source": "数据来源:{n} 个快照",
@@ -151,6 +162,14 @@ const zhCN: Record<ReportMessageKey, string> = {
 
   "groupSummary.experiments": "实验数",
 
+  "experimentComparison.groups": "实验组",
+  "experimentComparison.group": "实验组",
+  "experimentComparison.results": "结果",
+  "experimentComparison.lastRun": "最后运行",
+  "experimentComparison.selectGroup": "选择实验组 {group}",
+  "experimentComparison.command": "查看：{command}",
+  "experimentComparison.empty": "没有实验组",
+
   "composedFrom.one": "合成自 {n} 个 run",
   "composedFrom.other": "合成自 {n} 个 run",
   "latestRun": "最新 {run}",
@@ -166,6 +185,7 @@ const zhCN: Record<ReportMessageKey, string> = {
   "attemptList.truncated": "还有 {n} 条未列出",
   "attemptList.truncatedText": "(还有 {n} 条未列出)",
   "attemptList.score": "得分 {score}",
+  "attemptList.unavailable": "评不了",
   "attemptList.details": "详情",
 
   "scoreboard.total": "总分",

package/src/report/metrics.ts

@@ -1,15 +1,18 @@
 // defineMetric 与内置指标。
 //
 // null ≠ 0:null = 此 attempt 测不了这个指标(不进聚合);0 = 测了,结果是零(照常进)。
-// 哪个 verdict 落哪边必须显式表态,内置指标按 docs/feature/reports/library.md「内置指标」的表格:
+// 哪个 verdict 落哪边必须显式表态,内置指标按 docs/feature/reports/library.md「内置指标」的表格。
+// 三个通过率指标把「Agent 答错」与「基建没跑起来」拆开,不互相伪装:
 //
-//   指标(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
+//   指标(name)                                    skipped  errored          failed  passed        better
+//   taskPassRate(task-pass-rate)                   null     null             0       1             higher
+//   executionReliability(execution-reliability)    null     0                1       1             higher
+//   endToEndPassRate(end-to-end-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 选择都算得出,内置报告
@@ -39,10 +42,58 @@ export function attemptCostUSD(result: EvalResult): number | null {
   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).",
+/**
+ * 条件答题质量:passed = 1,failed = 0,errored 记 null 不进分母。
+ * 这是「已形成可信判定」条件下的诊断指标,不能简称默认成功率
+ * (docs/feature/reports/library.md「内置指标」)。
+ */
+export const taskPassRate = defineMetric({
+  name: "task-pass-rate",
+  label: { en: "Task pass rate", "zh-CN": "可判定任务通过率" },
+  description: "Conditional task quality among attempts that formed a trustworthy verdict: passed = 1, failed = 0; errored is null.",
+  better: "higher",
+  unit: "%",
+  value(a) {
+    switch (a.result.verdict) {
+      case "passed":
+        return 1;
+      case "failed":
+        return 0;
+      default:
+        // errored = 没形成可信判定 → null 不进这个条件指标;skipped 同为 null。
+        return null;
+    }
+  },
+});
+
+/** 执行可靠性:跑到可判定(passed / failed)= 1,errored = 0;skipped → null。 */
+export const executionReliability = defineMetric({
+  name: "execution-reliability",
+  label: { en: "Execution reliability", "zh-CN": "执行可靠性" },
+  description: "Execution reliability: reached a trustworthy verdict (passed / failed) = 1, errored = 0.",
+  better: "higher",
+  unit: "%",
+  value(a) {
+    switch (a.result.verdict) {
+      case "passed":
+      case "failed":
+        return 1;
+      case "errored":
+        return 0;
+      default:
+        return null; // skipped
+    }
+  },
+});
+
+/**
+ * 端到端合成:passed = 1,failed / errored = 0;哪边拖累用
+ * taskPassRate / executionReliability 拆开看。
+ */
+export const endToEndPassRate = defineMetric({
+  name: "end-to-end-pass-rate",
+  label: { en: "End-to-end pass rate", "zh-CN": "端到端成功率" },
+  description: "End-to-end composite: passed = 1, failed / errored = 0. Split blame with taskPassRate and executionReliability.",
   better: "higher",
   unit: "%",
   value: (a) =>
@@ -62,9 +113,11 @@ export const examScore = defineMetric({
     // 字面实现会让条件空真成立、崩溃反而得满分 —— 交白卷是 0 分,不是缺数据,更不是满分。
     // failed 同理得 0:--strict 下被翻成 failed 的哪怕 soft 分不低也是 0(报告不重新判卷)。
     if (verdict !== "passed") return 0;
-    const soft = assertions.filter((x) => x.severity === "soft");
+    // unavailable 没有分数:不计入均分分母(评不了 ≠ 0 分;非 optional 的 unavailable
+    // 早已把 verdict 拖成 errored,走不到这个分支)。
+    const soft = assertions.filter((x) => x.severity === "soft" && x.outcome !== "unavailable");
     if (soft.length === 0) return 1;
-    return soft.reduce((sum, x) => sum + x.score, 0) / soft.length;
+    return soft.reduce((sum, x) => sum + (x.outcome === "unavailable" ? 0 : x.score), 0) / soft.length;
   },
 });
 

package/src/report/primitives.tsx

@@ -128,6 +128,12 @@ export interface TableColumn {
   header: string;
   /** 对齐方向,默认 `"left"`;`"right"` 按显示宽度右对齐,数字列用。 */
   align?: ColumnAlign;
+  /**
+   * text 面:单元格折行后的最大物理行数,放不下的部分以 `…` 收口;省略则不限行数。
+   * 摘要类列(如比较列表的 Result)用它保证「格子是可扫读的预览」;完整值在下钻面。
+   * web 面不消费——网页的高度约束是组件自己的 CSS 决定。
+   */
+  maxLines?: number;
 }
 
 /** 一行的数据:身份键、已格式化的格子、可选的 attempt locator。 */

package/src/report/react/AttemptList.tsx

@@ -1,5 +1,5 @@
-// AttemptList:实体列表的叶子层——每项一个 Attempt,固定展示判定、断言、error、Judge 评语
-// (assertions 的 detail/evidence)与证据引用(locator)。它不预设只看失败,
+// AttemptList:实体列表的叶子层——每项一个 Attempt,固定展示判定、一条主失败摘要或 error
+// 摘要与证据引用(locator)。完整 assertions / evidence 只经 locator 下钻。它不预设只看失败,
 // 报告作者过滤 items、用 .slice() 限量,total 让渲染面如实报告剩余数量,不静默截断。
 // ExperimentList / EvalList 的下钻数组是同一个 AttemptListItem[],这里的渲染逻辑因此
 // 也是它们展开区里"逐条 attempt"那一层的唯一实现(通过 AttemptRow 导出复用,不重写一遍)。
@@ -8,6 +8,7 @@ import type { ReactElement } from "react";
 import type { AttemptListItem } from "../types.ts";
 import type { AttemptLocator } from "../../results/locator.ts";
 import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../locale.ts";
+import { attemptItemReason } from "../format.ts";
 import { colorClassForKey } from "./colors.ts";
 import { cx, formatDurationMs, formatUSD, verdictMark } from "./format.ts";
 
@@ -30,35 +31,16 @@ export function AttemptLocatorBadge({
   );
 }
 
-function AssertionRow({ assertion, locale }: { assertion: AttemptListItem["assertions"][number]; locale: ReportLocale }): ReactElement {
-  return (
-    <li className={cx("nre-assertion", `nre-assertion-${assertion.severity}`, !assertion.passed && "nre-assertion-failed")}>
-      <span className="nre-assertion-severity">{assertion.severity}</span>
-      <span className="nre-assertion-name">{assertion.name}</span>
-      <span className="nre-assertion-score">
-        {localeText(locale, "attemptList.score", { score: assertion.score })}
-      </span>
-      {(assertion.detail || assertion.evidence) && (
-        <details className="nre-assertion-more">
-          <summary>{localeText(locale, "attemptList.details")}</summary>
-          {assertion.detail && <p className="nre-assertion-detail">{assertion.detail}</p>}
-          {assertion.evidence && <blockquote className="nre-assertion-evidence">{assertion.evidence}</blockquote>}
-        </details>
-      )}
-    </li>
-  );
-}
-
-/** 一条 Attempt 的完整卡片:AttemptList 自己的一项,也是 EvalList 展开区里的一行。 */
+/** 一条 Attempt 的比较卡片；完整 assertions 通过 locator 下钻，不在列表内展开。 */
 export function AttemptRow({
   item,
   attemptHref,
-  locale = DEFAULT_REPORT_LOCALE,
 }: {
   item: AttemptListItem;
   attemptHref: (locator: AttemptLocator) => string;
   locale?: ReportLocale;
 }): ReactElement {
+  const reason = attemptItemReason(item);
   return (
     <li className={cx("nre-attempt", `nre-attempt-${item.verdict}`)}>
       <div className="nre-attempt-head">
@@ -70,14 +52,7 @@ export function AttemptRow({
         <span className="nre-attempt-duration">{formatDurationMs(item.durationMs)}</span>
         {item.costUSD !== undefined && <span className="nre-attempt-cost">{formatUSD(item.costUSD)}</span>}
       </div>
-      {item.error && <p className="nre-attempt-error">{item.error}</p>}
-      {item.assertions.length > 0 && (
-        <ul className="nre-assertions">
-          {item.assertions.map((a, i) => (
-            <AssertionRow key={i} assertion={a} locale={locale} />
-          ))}
-        </ul>
-      )}
+      {reason && <p className="nre-attempt-result">{reason}</p>}
     </li>
   );
 }

package/src/report/react/ExperimentComparison.tsx

@@ -0,0 +1,68 @@
+// ExperimentComparison 的 web 面：完整持有所有可比组，组选择只切换已经独立计算好的 panel。
+// 静态 HTML 用原生 <details> 保留每组完整内容；enhance.js 再把上方摘要卡变成单选切换。
+
+import type { ReactElement } from "react";
+import type { ExperimentComparisonData } from "../built-ins/experiment-comparison.tsx";
+import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../locale.ts";
+import { ExperimentList, MetricScatter } from "../components.tsx";
+import { GroupSummary } from "./GroupSummary.tsx";
+import { cx } from "./format.ts";
+
+export function ExperimentComparisonView({
+  data,
+  className,
+  locale = DEFAULT_REPORT_LOCALE,
+}: {
+  data: ExperimentComparisonData;
+  className?: string;
+  locale?: ReportLocale;
+}): 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>
+            <GroupSummary 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 items={group.experiments} filter locale={locale} relativeTo={group.key} />
+          </details>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/report/react/ExperimentList.tsx

@@ -5,7 +5,7 @@
 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 { attemptItemReason, experimentDisplayName } from "../format.ts";
 import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../locale.ts";
 import { AttemptLocatorBadge } from "./AttemptList.tsx";
 import { MetricCellView } from "./cell.tsx";
@@ -73,18 +73,18 @@ function EvalAttempts({
   attemptHref: (locator: AttemptLocator) => string;
   locale: ReportLocale;
 }): ReactElement {
+  const duration = row.duration.value === null ? localeText(locale, "cell.missing") : formatDurationMs(row.duration.value);
+  const cost = row.cost.value === null ? localeText(locale, "cell.missing") : formatUSD(row.cost.value);
   return (
     <li className="nre-experiment-eval">
       <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">
@@ -117,16 +117,20 @@ 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">
         <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 })}` : ""}
@@ -167,12 +171,14 @@ export function ExperimentList({
   filter = false,
   className,
   locale = DEFAULT_REPORT_LOCALE,
+  relativeTo,
 }: {
   items: ExperimentListItem[];
   attemptHref: (locator: AttemptLocator) => string;
   filter?: boolean;
   className?: string;
   locale?: ReportLocale;
+  relativeTo?: string;
 }): ReactElement {
   const labels = [
     localeText(locale, "experimentList.experiment"),
@@ -200,7 +206,7 @@ export function ExperimentList({
       </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} />
+        <ExperimentRow key={item.experimentId} item={item} attemptHref={attemptHref} locale={locale} relativeTo={relativeTo} />
       ))}
     </div>
   );

package/src/report/react/MetricScatter.tsx

@@ -1,6 +1,7 @@
 // MetricScatter:质量 × 成本 frontier 的积木,内联 SVG、零图表库、零 hooks。
 // 轴向随 better:"lower" 的轴反向画,「好」的角落恒在右上(成本轴 $20 → $0 就是这么来的);
-// niceTicks 刻度 + 网格线;每个点直接标注(防撞布局,被挤开时补 leader line);
+// niceTicks 刻度 + 网格线;每个点直接标注(placePointLabels 候选位择优:避开其它标签、
+// 数据点与画布边界,离开左右紧邻位时补 leader line);
 // 同系列的点按 x 值排序连线,系列图例列在图下。x 或 y 为 null 的点不画,
 // 底部注脚如实报「n 个点缺数据」;hover 信息退化为 SVG <title>,不 hydrate 也在
 // (enhance.js 在场时升级为样式化 tooltip)。配色走类名(nre-series-cN)由 CSS 上色,
@@ -10,7 +11,7 @@ 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 { niceTicks, placePointLabels } from "./chart-math.ts";
 import { colorClassForKey, seriesClassForKey } from "./colors.ts";
 import { cx } from "./format.ts";
 
@@ -124,12 +125,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)}>
@@ -202,20 +202,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>

package/src/report/react/chart-math.test.ts

@@ -0,0 +1,85 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 分区「MetricScatter 点标签布局(web 面)」:对 placePointLabels 直接断言标签框与点框的几何关系,不经 HTML。
+
+import { describe, expect, it } from "vitest";
+import { placePointLabels, type LabelBounds, type PlacedPointLabel, type PointLabelInput } from "./chart-math.ts";
+
+const BOUNDS: LabelBounds = { x0: 2, y0: 2, x1: 638, y1: 358 };
+const WIDTH = 90;
+
+interface Box {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+
+// 与契约声明的标签框一致:基线上方 10px、下方 2px,锚向决定水平延伸方向
+function labelBox(l: PlacedPointLabel, width: number): Box {
+  const x0 = l.anchor === "start" ? l.x : l.anchor === "end" ? l.x - width : l.x - width / 2;
+  return { x0, y0: l.y - 10, x1: x0 + width, y1: l.y + 2 };
+}
+
+function dotBox(p: PointLabelInput): Box {
+  return { x0: p.cx - 6, y0: p.cy - 6, x1: p.cx + 6, y1: p.cy + 6 };
+}
+
+function overlaps(a: Box, b: Box): boolean {
+  return a.x0 < b.x1 && a.x1 > b.x0 && a.y0 < b.y1 && a.y1 > b.y0;
+}
+
+describe("placePointLabels", () => {
+  it("近重合点簇:标签框两两不叠、不压任何数据点(只向下推的级联会把第三个标签推到下方点上)", () => {
+    // 三点近重合 + 右下方另一点:down-only 布局把第三个标签推到 y∈[122,134]、x≥310,
+    // 正好压住 (330,128) 的点框;候选位择优必须避开
+    const points: PointLabelInput[] = [
+      { cx: 300, cy: 100, width: WIDTH },
+      { cx: 303, cy: 102, width: WIDTH },
+      { cx: 298, cy: 104, width: WIDTH },
+      { cx: 330, cy: 128, width: WIDTH },
+    ];
+    const labels = placePointLabels(points, BOUNDS);
+    const boxes = labels.map((l) => labelBox(l, WIDTH));
+
+    for (let i = 0; i < boxes.length; i++) {
+      for (let j = i + 1; j < boxes.length; j++) {
+        expect(overlaps(boxes[i], boxes[j]), `标签 ${i} 与标签 ${j} 重叠`).toBe(false);
+      }
+      for (let j = 0; j < points.length; j++) {
+        expect(overlaps(boxes[i], dotBox(points[j])), `标签 ${i} 压住点 ${j}`).toBe(false);
+      }
+    }
+    // 离开左右紧邻位的标签必须带 leader 标记,渲染层据此连回原点
+    for (let i = 0; i < labels.length; i++) {
+      const adjacent =
+        labels[i].y === points[i].cy + 4 &&
+        ((labels[i].anchor === "start" && labels[i].x === points[i].cx + 10) ||
+          (labels[i].anchor === "end" && labels[i].x === points[i].cx - 10));
+      expect(labels[i].leader, `标签 ${i} 的 leader 标记与位置不符`).toBe(!adjacent);
+    }
+  });
+
+  it("无冲突取右侧紧邻位不带 leader;右缘点锚到左侧紧邻位且标签框不越出画布", () => {
+    const sparse = placePointLabels(
+      [
+        { cx: 100, cy: 100, width: WIDTH },
+        { cx: 400, cy: 250, width: WIDTH },
+      ],
+      BOUNDS,
+    );
+    for (const [i, l] of sparse.entries()) {
+      expect(l.anchor).toBe("start");
+      expect(l.x).toBe([100, 400][i] + 10);
+      expect(l.leader).toBe(false);
+    }
+
+    const [edge] = placePointLabels([{ cx: 630, cy: 200, width: WIDTH }], BOUNDS);
+    const box = labelBox(edge, WIDTH);
+    expect(edge.anchor).toBe("end");
+    expect(edge.leader).toBe(false);
+    expect(box.x0).toBeGreaterThanOrEqual(BOUNDS.x0);
+    expect(box.x1).toBeLessThanOrEqual(BOUNDS.x1);
+    expect(box.y0).toBeGreaterThanOrEqual(BOUNDS.y0);
+    expect(box.y1).toBeLessThanOrEqual(BOUNDS.y1);
+  });
+});