niceeval 0.9.0 → 0.10.0

package/src/report/components/site-components/faces.ts

@@ -0,0 +1,80 @@
+// 站点组件族(HeroCard / ScopeWarnings / TraceWaterfall)的 text 面:同一份算好的数据,
+// 渲染成终端字符(niceeval show 的形态)。零 react、零 IO、纯同步。
+
+import type { HeroData, ScopeWarning, TraceWaterfallRow } from "../../model/types.ts";
+import type { LocalizedText } from "../../model/locale.ts";
+import type { TextContext } from "../../definition/tree.ts";
+import { countText, localeText, resolveLocalizedText } from "../../model/locale.ts";
+import { formatDurationMs } from "../../model/format.ts";
+import { groupScopeWarnings } from "./scope-warnings.ts";
+
+/** ISO 时间 → "YYYY-MM-DD HH:mm"(本地时区);不可解析原样返回。 */
+function formatDateTimeMinute(iso: string): string {
+  const date = new Date(iso);
+  if (Number.isNaN(date.valueOf())) return iso;
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+// ───────────────────────── 站点组件(HeroCard / ScopeWarnings / TraceWaterfall)─────────────────────────
+
+/**
+ * HeroCard 的 text 面:标题行 + meta 行(最后运行时间;空范围为内置「暂无运行」文案;
+ * 多快照时标注合成来源),不含品牌行(品牌行是纯 web 件,text 面零输出)。
+ */
+export function heroCardText(title: LocalizedText, data: HeroData, ctx: TextContext): string {
+  const locale = ctx.locale;
+  const meta =
+    data.latestStartedAt === null
+      ? localeText(locale, "hero.noRuns")
+      : [
+          localeText(locale, "hero.lastRun", { time: formatDateTimeMinute(data.latestStartedAt) }),
+          ...(data.snapshots > 1 ? [localeText(locale, "hero.composedSnapshots", { n: data.snapshots })] : []),
+        ].join(" · ");
+  return `${resolveLocalizedText(title, locale)}\n${meta}`;
+}
+
+/**
+ * ScopeWarnings 的 text 面:按动作聚合(../scope-warnings.ts,与 web 面共用),同构但不折叠——
+ * 多组时首行 "! <分类计数汇总>";每组一行组头 "! <标题> — <徽标> → <组头命令>",其下缩进
+ * 逐条原样打印 message(已以下一步收尾,不截断掉尾段)。空警告集零输出。
+ */
+export function scopeWarningsText(warnings: readonly ScopeWarning[], ctx: TextContext): string {
+  if (warnings.length === 0) return "";
+  const { summary, groups } = groupScopeWarnings(warnings, ctx.locale);
+  const lines: string[] = [];
+  // 汇总行只在多组时打印;单组时组头即汇总,不另起一行(web 面则恒以汇总行作外层 <summary>)。
+  if (groups.length > 1) lines.push(`! ${summary}`);
+  for (const group of groups) {
+    const badges = group.badges.length > 0 ? ` — ${group.badges.map((b) => b.text).join(" · ")}` : "";
+    const command = group.headCommand !== null ? ` → ${group.headCommand}` : "";
+    lines.push(`! ${group.title}${badges}${command}`);
+    for (const w of group.warnings) lines.push(`!   ${w.message}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * TraceWaterfall 的 text 面:每 attempt 一行——locator、总耗时(缺 trace 如实显示缺失)、
+ * 顶层 span 计数与失败标记,行尾是可复制的 `--timing` 下钻命令(经宿主注入的 attemptCommand
+ * 通道拼出,携带宿主上下文)。当前报告没有 attempt-input page 时 `ctx.attemptCommand`
+ * 不存在,行退化为纯文本,不生成假命令(architecture.md「Attempt 详情是一张参数化 page」)。
+ */
+export function traceWaterfallText(rows: readonly TraceWaterfallRow[], ctx: TextContext): string {
+  const locale = ctx.locale;
+  if (rows.length === 0) return localeText(locale, "traceWaterfall.empty");
+  return rows
+    .map((row) => {
+      const failedSpans = row.spans.filter((span) => span.failed).length;
+      const parts = [
+        row.locator,
+        row.evalId,
+        row.durationMs === null ? localeText(locale, "traceWaterfall.noTrace") : formatDurationMs(row.durationMs),
+        countText(locale, "traceWaterfall.spans", row.spans.length),
+        ...(failedSpans > 0 ? [`✗ ${countText(locale, "traceWaterfall.failedSpans", failedSpans)}`] : []),
+      ];
+      const line = parts.join(" · ");
+      return ctx.attemptCommand ? `${line}   ${ctx.attemptCommand(row.locator)} --timing` : line;
+    })
+    .join("\n");
+}

package/src/report/components/site-components/index.tsx

@@ -0,0 +1,265 @@
+// 官方双面组件的装配点:web 面(./HeroCard.tsx 等纯 React 组件)+ text 面(./faces.ts)+
+// resolve 解析面(spec 形态由管线代调配套 ./compute.ts)。Hero 是组合组件(装配 HeroCard),
+// 不产生自己的 data;PoweredBy 无 props,没有对应的计算函数或 validate。
+
+import { defineComponent, type ReportComponent } from "../../definition/tree.ts";
+import type { CopyFixPromptData, HeroData, ScopeWarning, TraceWaterfallRow } from "../../model/types.ts";
+import type { LocalizedText } from "../../model/locale.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import {
+  arrayProblem,
+  dataShapeError,
+  isObject,
+  makeDataComponent,
+  hrefOf,
+  type ChromeProps,
+  type DataProps,
+  type Validator,
+} from "../shared.ts";
+import { copyFixPromptData, heroData, scopeWarningsData, traceWaterfallData } from "./compute.ts";
+import { heroCardText, scopeWarningsText, traceWaterfallText } from "./faces.ts";
+import { HeroCard as HeroCardWeb } from "./HeroCard.tsx";
+import { PoweredBy as PoweredByWeb } from "./PoweredBy.tsx";
+import { ScopeWarnings as ScopeWarningsWeb } from "./ScopeWarnings.tsx";
+import { CopyFixPrompt as CopyFixPromptWeb } from "./CopyFixPrompt.tsx";
+import { TraceWaterfall as TraceWaterfallWeb } from "./TraceWaterfall.tsx";
+
+export const validateHeroData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (!(data.latestStartedAt === null || typeof data.latestStartedAt === "string")) {
+    return '"latestStartedAt" must be a string or null';
+  }
+  if (typeof data.snapshots !== "number") return '"snapshots" must be a number';
+  return null;
+};
+
+const UNREADABLE_SNAPSHOT_REASONS = ["incompatible-version", "malformed", "incomplete"];
+
+/**
+ * ScopeWarning(src/results/types.ts「警告 kind 全集」):按 `kind` 判别的联合,已登记 kind
+ * 各自的必填字段单独校验——`unreadable-snapshot` 没有 experimentId(非实验作用域)、
+ * `command` 恒可选。未登记的 `kind`(如未来版本新增的 warning)只要求 `kind` / `message`
+ * 这份两族共用的最小形状,不拒绝——`ScopeWarnings` 的分组渲染对未识别 kind 有专门的
+ * 单独成组回退(message 原样、按 integrity 归位),这条前向兼容路径本身就是契约的一部分,
+ * 结构校验不能比渲染逻辑更严。
+ */
+function scopeWarningProblem(value: unknown, path: string): string | null {
+  if (!isObject(value)) return `"${path}" must be a ScopeWarning object`;
+  if (typeof value.kind !== "string") return `"${path}.kind" must be a string`;
+  if (typeof value.message !== "string") return `"${path}.message" must be a string`;
+  switch (value.kind) {
+    case "partial-coverage":
+      if (typeof value.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+      if (typeof value.covered !== "number") return `"${path}.covered" must be a number`;
+      if (typeof value.total !== "number") return `"${path}.total" must be a number`;
+      if (typeof value.command !== "string") return `"${path}.command" must be a string`;
+      return null;
+    case "stale-snapshot":
+      if (typeof value.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+      if (typeof value.startedAt !== "string") return `"${path}.startedAt" must be a string`;
+      if (typeof value.latestStartedAt !== "string") return `"${path}.latestStartedAt" must be a string`;
+      if (typeof value.command !== "string") return `"${path}.command" must be a string`;
+      return null;
+    case "unfinished-snapshot":
+      if (typeof value.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+      if (typeof value.startedAt !== "string") return `"${path}.startedAt" must be a string`;
+      if (typeof value.dir !== "string") return `"${path}.dir" must be a string`;
+      if (typeof value.command !== "string") return `"${path}.command" must be a string`;
+      return null;
+    case "unreadable-snapshot":
+      if (typeof value.dir !== "string") return `"${path}.dir" must be a string`;
+      if (typeof value.reason !== "string" || !UNREADABLE_SNAPSHOT_REASONS.includes(value.reason)) {
+        return `"${path}.reason" must be one of ${JSON.stringify(UNREADABLE_SNAPSHOT_REASONS)}`;
+      }
+      if (value.command !== undefined && typeof value.command !== "string") {
+        return `"${path}.command" must be a string when present`;
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+
+export const validateScopeWarningsData: Validator = (data) => arrayProblem(data, "data", scopeWarningProblem);
+
+export const validateCopyFixPromptData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (typeof data.prompt !== "string") return '"prompt" must be a string';
+  if (typeof data.failures !== "number") return '"failures" must be a number';
+  return null;
+};
+
+const TRACE_SPAN_KINDS = ["agent", "model", "tool", "other"];
+
+/** TraceSpanSummary(src/report/model/types.ts):瀑布行里的一个顶层 span 摘要。 */
+function traceSpanSummaryProblem(value: unknown, path: string): string | null {
+  if (!isObject(value)) return `"${path}" must be a TraceSpanSummary { name, kind, startOffsetMs, durationMs, failed }`;
+  if (typeof value.name !== "string") return `"${path}.name" must be a string`;
+  if (typeof value.kind !== "string" || !TRACE_SPAN_KINDS.includes(value.kind)) {
+    return `"${path}.kind" must be one of ${JSON.stringify(TRACE_SPAN_KINDS)}`;
+  }
+  if (typeof value.startOffsetMs !== "number") return `"${path}.startOffsetMs" must be a number`;
+  if (typeof value.durationMs !== "number") return `"${path}.durationMs" must be a number`;
+  if (typeof value.failed !== "boolean") return `"${path}.failed" must be a boolean`;
+  return null;
+}
+
+export const validateTraceWaterfallData: Validator = (data) =>
+  arrayProblem(data, "data", (row, path) => {
+    if (!isObject(row)) return `"${path}" must be an object`;
+    if (typeof row.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+    if (typeof row.evalId !== "string") return `"${path}.evalId" must be a string`;
+    if (typeof row.locator !== "string") return `"${path}.locator" must be a string`;
+    if (!(row.durationMs === null || typeof row.durationMs === "number")) {
+      return `"${path}.durationMs" must be a number or null`;
+    }
+    return arrayProblem(row.spans, `${path}.spans`, traceSpanSummaryProblem);
+  });
+
+// ───────────────────────── 站点组件(Hero / PoweredBy / ScopeWarnings / CopyFixPrompt / TraceWaterfall)─────────────────────────
+
+/** `Hero` 的 props:标题缺省取 `ctx.report.title`(回退链后的站点标题)。 */
+export interface HeroProps {
+  /** 覆盖标题;省略时取 ctx.report.title(回退链后的站点标题)。 */
+  title?: LocalizedText;
+  className?: string;
+}
+
+/** HeroCard 的 data 校验入口(它不经 makeDataComponent,数据形态是唯一形态)。 */
+const assertHeroData = (data: unknown): HeroData => {
+  const problem = validateHeroData(data);
+  if (problem !== null) throw dataShapeError("HeroCard", "heroData", "HeroData", problem);
+  return data as HeroData;
+};
+
+/**
+ * `HeroCard`:Hero 的渲染件,双面组件,只收 data 形态——标题输入是站点声明与 Scope 的
+ * 合成物,没有单独的 spec 等价形。web 面渲染 hero 标题(h1)、按渲染 locale 格式化的运行
+ * meta(latestStartedAt 为 null 时内置「暂无运行」文案)与品牌行(等同 PoweredBy,恒含、
+ * 无拆除 prop);text 面输出标题行与 meta 行,不含品牌行
+ * (docs/feature/reports/library/site-components.md「HeroCard」)。
+ */
+export const HeroCard = defineComponent<HeroCardProps>({
+  web: (props, ctx) => {
+    assertHeroData(props.data);
+    return <HeroCardWeb title={props.title} data={props.data} className={props.className} locale={ctx.locale} />;
+  },
+  text: (props, ctx) => {
+    assertHeroData(props.data);
+    return heroCardText(props.title, props.data, ctx);
+  },
+});
+HeroCard.displayName = "HeroCard";
+
+/** `HeroCard` 的 props:标题 + `heroData()` 的产物,只有 data 形态。 */
+export interface HeroCardProps {
+  title: LocalizedText;
+  data: HeroData;
+  className?: string;
+}
+
+/**
+ * `Hero`:页首的站点标题区——标题、最后运行时间、快照合成来源,恒含品牌行。官方组合组件,
+ * 与手写 `<HeroCard title={title ?? ctx.report.title} data={await heroData(ctx.scope)} />`
+ * 严格等价、没有私有能力;读 `ctx.report` 意味着输出跟随站点,要站点无关的标题区直接用
+ * `HeroCard` 显式传值(docs/feature/reports/library/site-components.md「Hero」)。
+ */
+export const Hero = defineComponent<HeroProps>(async ({ title, className }, ctx) => (
+  <HeroCard title={title ?? ctx.report.title} data={await heroData(ctx.scope)} className={className} />
+));
+Hero.displayName = "Hero";
+
+/**
+ * `PoweredBy`:唯一的品牌件,无 props 双面组件。web 面渲染指向 niceeval 官网的一行品牌色
+ * 小字(`utm_source=report&utm_medium=powered-by`,`rel` 仅 `noopener` 以保留 Referer);
+ * text 面零输出。没有任何配置——品牌契约是「提供一个组件,不给开关」:不想要品牌就不用
+ * 这些组件、自己写替代组件(docs/feature/reports/library/site-components.md「PoweredBy」)。
+ */
+export const PoweredBy = defineComponent<Record<never, never>>({
+  web: () => <PoweredByWeb />,
+  text: () => "",
+});
+PoweredBy.displayName = "PoweredBy";
+
+/** `ScopeWarnings` 的 props:spec 形态取宿主 Scope 的 warnings,data 形态收 `ScopeWarning[]`。 */
+export type ScopeWarningsProps = DataProps<readonly ScopeWarning[], Record<never, never>, ChromeProps>;
+
+/**
+ * `ScopeWarnings`:选择警告区,警告的唯一呈现组件。把 Scope 携带的 `ScopeWarning[]`
+ * 按「下一步动作」聚合渲染(带 experimentId 的按实验聚合、非实验作用域按 kind 聚合;
+ * integrity 组在前);web 面组头带去重后的可复制命令、明细收原生 `<details>`(总条数 ≤ 3
+ * 默认展开),text 面同构但不折叠。空警告集与裸 `Snapshot[]` 输入两面零输出
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export const ScopeWarnings = makeDataComponent<readonly ScopeWarning[], Record<never, never>, ChromeProps>({
+  name: "ScopeWarnings",
+  dataFnName: "scopeWarningsData",
+  shapeName: "ScopeWarning[]",
+  dataFn: (input) => scopeWarningsData(input),
+  specKeys: [],
+  validate: validateScopeWarningsData,
+  web: (props, ctx) =>
+    props.data.length === 0 ? null : (
+      <ScopeWarningsWeb data={props.data} locale={props.locale ?? ctx.locale} className={props.className} />
+    ),
+  text: (props, ctx) => scopeWarningsText(props.data, ctx),
+}) as unknown as ReportComponent<ScopeWarningsProps>;
+
+/** `CopyFixPrompt` 的 props:spec 形态无选项,data 形态收 `copyFixPromptData()` 的产物。 */
+export type CopyFixPromptProps = DataProps<CopyFixPromptData, Record<never, never>, ChromeProps>;
+
+/**
+ * `CopyFixPrompt`:把当前范围的全部失败整理成一段可交给 coding agent 的修复 prompt。
+ * prompt 在 resolve 阶段算好、烘进静态 HTML,无 JS 时在折叠块里完整可读,「复制」是增强层
+ * 行为;`failures` 为 0 时两面零输出;text 面恒零输出——终端里的等价能力是 `show` 的
+ * attempt 下钻命令本身(docs/feature/reports/library/site-components.md「CopyFixPrompt」)。
+ */
+export const CopyFixPrompt = makeDataComponent<CopyFixPromptData, Record<never, never>, ChromeProps>({
+  name: "CopyFixPrompt",
+  dataFnName: "copyFixPromptData",
+  shapeName: "CopyFixPromptData",
+  dataFn: (input) => copyFixPromptData(input),
+  specKeys: [],
+  validate: validateCopyFixPromptData,
+  web: (props, ctx) =>
+    props.data.failures === 0 ? null : (
+      <CopyFixPromptWeb data={props.data} locale={props.locale ?? ctx.locale} className={props.className} />
+    ),
+  text: () => "",
+}) as unknown as ReportComponent<CopyFixPromptProps>;
+
+/** `TraceWaterfall` 的 props:spec 形态无选项,data 形态收 `traceWaterfallData()` 的产物。 */
+export type TraceWaterfallProps = DataProps<
+  readonly TraceWaterfallRow[],
+  Record<never, never>,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>;
+
+/**
+ * `TraceWaterfall`:每个 attempt 一行的执行时间瀑布,用 canonical OTel 字段显示被测 agent
+ * 的原始 span(agent / model / tool)。web 面静态渲染顶层 span 分解条(失败 span 带失败
+ * 标记),行链接 attempt 详情;text 面每 attempt 一行(locator、总耗时、span 计数与失败
+ * 标记)+ 可复制的 `--timing` 下钻命令。trace 缺失的行照常出现并如实显示缺失;runner
+ * 生命周期节点不进瀑布(docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+ */
+export const TraceWaterfall = makeDataComponent<
+  readonly TraceWaterfallRow[],
+  Record<never, never>,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>({
+  name: "TraceWaterfall",
+  dataFnName: "traceWaterfallData",
+  shapeName: "TraceWaterfallRow[]",
+  dataFn: (input) => traceWaterfallData(input),
+  specKeys: [],
+  validate: validateTraceWaterfallData,
+  web: (props, ctx) => (
+    <TraceWaterfallWeb
+      data={props.data}
+      attemptHref={hrefOf(props, ctx)}
+      locale={props.locale ?? ctx.locale}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => traceWaterfallText(props.data, ctx),
+}) as unknown as ReportComponent<TraceWaterfallProps>;

package/src/report/{scope-warnings.ts → components/site-components/scope-warnings.ts}

@@ -4,9 +4,9 @@
 // (docs/feature/results/library.md「警告 kind 全集」)经 locale 词典渲染,未登记的 kind
 // 回退为单独成组、逐条 message 原样。
 
-import type { ScopeWarning } from "../results/types.ts";
-import { gapParts } from "../results/select.ts";
-import { localeText, type ReportLocale, type ReportMessageKey } from "./locale.ts";
+import type { ScopeWarning } from "../../../results/types.ts";
+import { gapParts } from "../../../results/select.ts";
+import { localeText, type ReportLocale, type ReportMessageKey } from "../../model/locale.ts";
 
 /** kind 表登记的类别:integrity(选中集合的分母可能不对)组排在 freshness(可能过期)之前。 */
 export type WarningCategory = "integrity" | "freshness";

package/src/report/{site-components.test.tsx → components/site-components/site-components.test.tsx}

@@ -7,9 +7,9 @@
 
 import { describe, expect, it } from "vitest";
 
-import type { AssertionResult, EvalResult, TraceSpan, Verdict } from "../types.ts";
-import type { AttemptHandle, Results, Scope, ScopeWarning, Snapshot } from "../results/index.ts";
-import { makeScope } from "../results/select.ts";
+import type { AssertionResult, EvalResult, TraceSpan, Verdict } from "../../../types.ts";
+import type { AttemptHandle, Results, Scope, ScopeWarning, Snapshot } from "../../../results/index.ts";
+import { makeScope } from "../../../results/select.ts";
 import {
   createTextContext,
   defineComponent,
@@ -18,20 +18,15 @@ import {
   validateReportTree,
   ResolveMemo,
   type ReportNode,
-} from "./tree.ts";
-import { buildReportMeta, defineReport, pickReportPage, renderReportToText, reportTitleText } from "./report.ts";
-import { renderReportToStaticHtml } from "./web.ts";
-import {
-  AttemptList,
-  CopyFixPrompt,
-  Hero,
-  HeroCard,
-  PoweredBy,
-  ScopeWarnings,
-  TraceWaterfall,
-} from "./components.tsx";
-import { Text } from "./primitives.tsx";
-import { attemptListData, copyFixPromptData, heroData, traceWaterfallData } from "./compute.ts";
+} from "../../definition/tree.ts";
+import { buildReportMeta, defineReport } from "../../definition/report.ts";
+import { pickReportPage, renderReportToText, reportTitleText } from "../../runtime/text.ts";
+import { renderReportToStaticHtml } from "../../runtime/web.ts";
+import { AttemptList } from "../entity-lists/index.tsx";
+import { CopyFixPrompt, Hero, HeroCard, PoweredBy, ScopeWarnings, TraceWaterfall } from "./index.tsx";
+import { Text } from "../../definition/primitives.tsx";
+import { attemptListData } from "../entity-lists/compute.ts";
+import { copyFixPromptData, heroData, traceWaterfallData } from "./compute.ts";
 
 // ───────────────────────── fake 数据(按 results 读取契约造)─────────────────────────
 
@@ -120,22 +115,29 @@ function hostCtx(scope: Scope) {
   return { scope, results: resultsOf(scope.snapshots) };
 }
 
+/** 站点组件测试固定"宿主已声明 attempt-input page"这条件,验证 attemptCommand/attemptHref 通道本身接得对;
+ * 「没有 attempt page 时退化成纯文本」由 report.test.ts / show.test.ts 的报告级测试单独覆盖。 */
+const DEFAULT_TEST_ATTEMPT_COMMAND = (locator: string) => `niceeval show ${locator}`;
+const DEFAULT_TEST_ATTEMPT_HREF = (locator: string) => `#/attempt/${locator}`;
+
 /** 管线便捷入口:装载 → resolve → validate → text 渲染(与 show 同一条管线,不带宿主前置块)。 */
 async function treeText(node: ReportNode, scope: Scope, width = 120): Promise<string> {
   const definition = defineReport(node);
-  const resolved = await resolveReportTree(pickReportPage(definition).content, {
+  const page = pickReportPage(definition);
+  const resolved = await resolveReportTree(page.content, {
     scope,
     results: resultsOf(scope.snapshots),
-    report: buildReportMeta(definition, scope, "report"),
+    report: buildReportMeta(definition, scope),
+    page: { id: page.id, input: "scope" },
     memo: new ResolveMemo(),
   });
   validateReportTree(resolved);
-  return renderNodeToText(resolved, createTextContext({ width }));
+  return renderNodeToText(resolved, createTextContext({ width, attemptCommand: DEFAULT_TEST_ATTEMPT_COMMAND }));
 }
 
 /** 管线便捷入口:web 面静态 HTML(经 renderReportToStaticHtml;测试用无警告 Scope,免宿主前置块)。 */
 async function treeHtml(node: ReportNode, scope: Scope): Promise<string> {
-  return renderReportToStaticHtml(defineReport(node), hostCtx(scope));
+  return renderReportToStaticHtml(defineReport(node), hostCtx(scope), { attemptHref: DEFAULT_TEST_ATTEMPT_HREF });
 }
 
 // ───────────────────────── 警告 fixture(按 ScopeWarning 联合造)─────────────────────────

package/src/report/components/site-components/validate.test.ts

@@ -0,0 +1,89 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// "validate*Data 递归覆盖到嵌套字段" 行:site-components 四个 validate*Data 的表驱动字段突变覆盖,重点是 ScopeWarning 的四个已登记
+// kind 各自的必填字段,以及未登记 kind 的前向兼容放行路径(与 ScopeWarnings 组件的「未知 kind
+// 单独成组」渲染回退是同一条契约,结构校验不能比渲染逻辑更严)。
+
+import { describe, expect, it } from "vitest";
+import { validateCopyFixPromptData, validateHeroData, validateScopeWarningsData, validateTraceWaterfallData } from "./index.tsx";
+
+describe("validateHeroData", () => {
+  it("合规 literal 通过,latestStartedAt 为 null 合法(空范围不编造当前时间)", () => {
+    expect(validateHeroData({ latestStartedAt: null, snapshots: 0 })).toBeNull();
+  });
+
+  it("snapshots 非数字报错", () => {
+    expect(validateHeroData({ latestStartedAt: null, snapshots: "0" })).toMatch(/"snapshots"/);
+  });
+});
+
+describe("validateScopeWarningsData — ScopeWarning 判别联合", () => {
+  it("partial-coverage 缺 covered 报错", () => {
+    const bad = [{ kind: "partial-coverage", experimentId: "exp/a", total: 6, message: "m", command: "niceeval exp exp/a" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.covered"/);
+  });
+
+  it("stale-snapshot 缺 latestStartedAt 报错", () => {
+    const bad = [{ kind: "stale-snapshot", experimentId: "exp/a", startedAt: "t1", message: "m", command: "c" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.latestStartedAt"/);
+  });
+
+  it("unfinished-snapshot 缺 dir 报错", () => {
+    const bad = [{ kind: "unfinished-snapshot", experimentId: "exp/a", startedAt: "t1", message: "m", command: "c" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.dir"/);
+  });
+
+  it("unreadable-snapshot 的 reason 不在三态枚举内报错;没有 experimentId 字段本身合法(非实验作用域)", () => {
+    const bad = [{ kind: "unreadable-snapshot", dir: "/r/snap", reason: "corrupted", message: "m" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.reason"/);
+    const ok = [{ kind: "unreadable-snapshot", dir: "/r/snap", reason: "malformed", message: "m" }];
+    expect(validateScopeWarningsData(ok)).toBeNull();
+  });
+
+  it("unreadable-snapshot 省略 command 合法(不是每个 reason 都有单条命令)", () => {
+    const ok = [{ kind: "unreadable-snapshot", dir: "/r/snap", reason: "incomplete", message: "m" }];
+    expect(validateScopeWarningsData(ok)).toBeNull();
+  });
+
+  it("未登记的 kind 只要有 kind/message 就放行——前向兼容,不拒绝未来版本产出的新 kind", () => {
+    const future = [{ kind: "future-kind", message: "something new happened" }];
+    expect(validateScopeWarningsData(future)).toBeNull();
+  });
+
+  it("未登记的 kind 缺 message 仍报错(两族共用的最小形状)", () => {
+    const bad = [{ kind: "future-kind" }];
+    expect(validateScopeWarningsData(bad)).toMatch(/"data\[0\]\.message"/);
+  });
+});
+
+describe("validateCopyFixPromptData", () => {
+  it("合规 literal 通过", () => {
+    expect(validateCopyFixPromptData({ prompt: "fix it", failures: 1 })).toBeNull();
+  });
+
+  it("failures 非数字报错", () => {
+    expect(validateCopyFixPromptData({ prompt: "x", failures: "1" })).toMatch(/"failures"/);
+  });
+});
+
+describe("validateTraceWaterfallData", () => {
+  const validSpan = { name: "turn", kind: "agent", startOffsetMs: 0, durationMs: 100, failed: false };
+  const valid = [{ experimentId: "exp/a", evalId: "q1", locator: "@1abcdef2", durationMs: 100, spans: [validSpan] }];
+
+  it("合规 literal 通过", () => {
+    expect(validateTraceWaterfallData(valid)).toBeNull();
+  });
+
+  it("durationMs 为 null 合法(trace 缺失时如实显示缺失)", () => {
+    expect(validateTraceWaterfallData([{ ...valid[0], durationMs: null }])).toBeNull();
+  });
+
+  it("spans[i].kind 不在四态枚举内报错", () => {
+    const bad = [{ ...valid[0], spans: [{ ...validSpan, kind: "runner" }] }];
+    expect(validateTraceWaterfallData(bad)).toMatch(/"data\[0\]\.spans\[0\]\.kind"/);
+  });
+
+  it("spans[i].failed 非布尔报错", () => {
+    const bad = [{ ...valid[0], spans: [{ ...validSpan, failed: "true" }] }];
+    expect(validateTraceWaterfallData(bad)).toMatch(/"data\[0\]\.spans\[0\]\.failed"/);
+  });
+});

package/src/report/{react → components/summaries}/ScopeSummary.tsx

@@ -1,13 +1,14 @@
 // ScopeSummary:一个范围的摘要卡——快照时间窗、experiment / eval / attempt 数、判定计票、
-// 端到端成功率与总成本。data 恒携带 eval 级与 attempt 级两份计票;呈现 prop `votes`
-// 只选择显示哪一级(默认 "eval"),不改变 data。成功率与总成本只渲染算好的 MetricCell,
+// 端到端通过率与总成本。data 恒携带 eval 级与 attempt 级两份计票;呈现 prop `votes`
+// 只选择显示哪一级(默认 "eval"),不改变 data。通过率与总成本只渲染算好的 MetricCell,
 // 不现场重算(docs/feature/reports/library/summaries.md「ScopeSummary」)。
 
 import type { ReactElement } from "react";
-import type { ScopeSummaryData, VerdictTally } from "../types.ts";
-import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../locale.ts";
-import { MetricCellView } from "./cell.tsx";
-import { cx } from "./format.ts";
+import type { ScopeSummaryData, VerdictTally } from "../../model/types.ts";
+import { DEFAULT_REPORT_LOCALE, localeText, type ReportLocale } from "../../model/locale.ts";
+import { formatReportDateTime, formatReportDateTimeRange } from "../../model/format.ts";
+import { MetricCellView } from "../cell.tsx";
+import { cx } from "../shared.ts";
 
 function VerdictTallyView({ tally, locale }: { tally: VerdictTally; locale: ReportLocale }): ReactElement {
   const kinds = (["passed", "failed", "errored", "skipped"] as const).filter((k) => tally[k] > 0);
@@ -36,6 +37,10 @@ export function ScopeSummary({
   locale?: ReportLocale;
 }): ReactElement {
   const tally = votes === "attempt" ? data.attemptVerdicts : data.evalVerdicts;
+  const formattedRange =
+    data.range.earliestStartedAt !== null && data.range.latestStartedAt !== null
+      ? formatReportDateTimeRange(data.range.earliestStartedAt, data.range.latestStartedAt, locale)
+      : null;
   return (
     <div className={cx("nre", "nre-scope-summary", className)} data-votes={votes}>
       <dl className="nre-scope-kpis">
@@ -66,7 +71,15 @@ export function ScopeSummary({
         <div className="nre-scope-kpi">
           <dt>{localeText(locale, "scopeSummary.totalCost")}</dt>
           <dd>
-            <MetricCellView cell={data.totalCostUSD} locale={locale} />
+            <MetricCellView cell={data.totalCostUSD} locale={locale} showCoverage={false} />
+            {data.totalCostUSD.samples < data.totalCostUSD.total && (
+              <small className="nre-scope-kpi-note">
+                {localeText(locale, "scopeSummary.costCoverage", {
+                  samples: data.totalCostUSD.samples,
+                  total: data.totalCostUSD.total,
+                })}
+              </small>
+            )}
           </dd>
         </div>
       </dl>
@@ -74,11 +87,13 @@ export function ScopeSummary({
       {data.range.latestStartedAt !== null && (
         <p className="nre-scope-summary-range">
           {data.range.earliestStartedAt !== null && data.range.earliestStartedAt !== data.range.latestStartedAt
-            ? localeText(locale, "scopeSummary.range", {
-                from: data.range.earliestStartedAt,
-                to: data.range.latestStartedAt,
+            ? localeText(locale, "scopeSummary.runRange", {
+                from: formattedRange!.from,
+                to: formattedRange!.to,
               })
-            : data.range.latestStartedAt}
+            : localeText(locale, "scopeSummary.lastRun", {
+                time: formatReportDateTime(data.range.latestStartedAt, locale),
+              })}
         </p>
       )}
     </div>

package/src/report/components/summaries/compute.ts

@@ -0,0 +1,56 @@
+// 计算函数(*Data):ReportInput → 一份组件数据。ScopeSummary 的 scopeSummaryData 住在这里
+// (docs/feature/reports/library/summaries.md)。ExperimentComparison 是纯组合组件,不产生
+// 独立的 data,没有对应的计算函数。
+//
+// 共同约定(docs/feature/reports/architecture.md「指标聚合不变量」):
+// - 第一参收 ReportInput = Scope | readonly Snapshot[];warnings 不进组件数据(宿主统一显示);
+// - 聚合前按身份键去重(dedupeAttempts;missing-startedAt 不去重、如实保留、不透出警告);
+// - null ≠ 0:缺数据不编数,覆盖率经 samples/total 如实暴露。
+
+import type { ReportInput, ScopeSummaryData } from "../../model/types.ts";
+import { collectItems, computeCell, resolveInput } from "../../model/aggregate.ts";
+import { costUSD, defineMetric, endToEndPassRate } from "../../model/metrics.ts";
+import { selectedEvalsOnly, summarizeItems, tallyOf } from "../shared-compute.ts";
+
+// ───────────────────────── scopeSummaryData ─────────────────────────
+
+/** costUSD 的求和投影:两级都 sum(题内多轮求和 + 跨题求和 = 全量求和),display 走 $。 */
+const totalCostMetric = defineMetric({
+  name: "total-cost",
+  label: costUSD.label,
+  unit: "$",
+  value: costUSD.value,
+  aggregate: { perEval: "sum", acrossEvals: "sum" },
+});
+
+/**
+ * `scopeSummaryData(input)`:范围摘要——快照时间窗、experiment / eval / attempt 数、
+ * 两级判定计票、端到端通过率与总成本(docs/feature/reports/library/summaries.md)。
+ * data 恒携带两级计票;通过率来自官方两级指标引擎,不从任一计票重算。
+ */
+export async function scopeSummaryData(input: ReportInput): Promise<ScopeSummaryData> {
+  const snapshots = selectedEvalsOnly(resolveInput(input).snapshots);
+  const items = collectItems(snapshots);
+
+  let earliest: string | null = null;
+  let latest: string | null = null;
+  for (const snapshot of snapshots) {
+    if (earliest === null || snapshot.startedAt < earliest) earliest = snapshot.startedAt;
+    if (latest === null || snapshot.startedAt > latest) latest = snapshot.startedAt;
+  }
+
+  const stats = summarizeItems(items);
+  const attemptVerdicts = tallyOf();
+  for (const item of items) attemptVerdicts[item.attempt.result.verdict] += 1;
+
+  return {
+    range: { earliestStartedAt: earliest, latestStartedAt: latest },
+    experiments: stats.experiments,
+    evals: stats.evals,
+    attempts: stats.attempts,
+    evalVerdicts: stats.verdicts,
+    attemptVerdicts,
+    endToEndPassRate: await computeCell(endToEndPassRate, items),
+    totalCostUSD: await computeCell(totalCostMetric, items),
+  };
+}