niceeval 0.8.0 → 0.9.0

package/src/report/components.tsx

@@ -21,35 +21,42 @@ import {
   type TextContext,
   type WebContext,
 } from "./tree.ts";
-import type { ReportLocale } from "./locale.ts";
+import type { LocalizedText, ReportLocale } from "./locale.ts";
 import type { AttemptLocator } from "../results/locator.ts";
 import type {
   AttemptListItem,
+  CopyFixPromptData,
   DeltaData,
-  EntityListDataOptions,
   EvalListItem,
   ExperimentComparisonData,
   ExperimentListItem,
+  HeroData,
   LineData,
   MatrixData,
   ReportInput,
   ScatterData,
   ScopeSummaryData,
+  ScopeWarning,
   ScoreboardData,
   TableData,
+  TraceWaterfallRow,
 } from "./types.ts";
 import {
   attemptListData,
+  copyFixPromptData,
   deltaTableData,
   evalListData,
   experimentComparisonData,
   experimentListData,
+  heroData,
   metricLineData,
   metricMatrixData,
   metricScatterData,
   metricTableData,
   scopeSummaryData,
+  scopeWarningsData,
   scoreboardData,
+  traceWaterfallData,
   type DeltaTableOptions,
   type MetricLineOptions,
   type MetricMatrixOptions,
@@ -65,18 +72,26 @@ import {
   experimentComparisonText,
   experimentListText,
   barsText,
+  heroCardText,
   lineText,
   matrixText,
   scatterText,
+  scopeWarningsText,
   scoreboardText,
   scopeSummaryText,
   tableText,
+  traceWaterfallText,
 } from "./text/faces.ts";
 import { ScopeSummary as ScopeSummaryWeb } from "./react/ScopeSummary.tsx";
 import { ExperimentComparisonView } from "./react/ExperimentComparison.tsx";
 import { ExperimentList as ExperimentListWeb } from "./react/ExperimentList.tsx";
 import { EvalList as EvalListWeb } from "./react/EvalList.tsx";
 import { AttemptList as AttemptListWeb } from "./react/AttemptList.tsx";
+import { HeroCard as HeroCardWeb } from "./react/HeroCard.tsx";
+import { PoweredBy as PoweredByWeb } from "./react/PoweredBy.tsx";
+import { ScopeWarnings as ScopeWarningsWeb } from "./react/ScopeWarnings.tsx";
+import { CopyFixPrompt as CopyFixPromptWeb } from "./react/CopyFixPrompt.tsx";
+import { TraceWaterfall as TraceWaterfallWeb } from "./react/TraceWaterfall.tsx";
 import { MetricTable as MetricTableWeb } from "./react/MetricTable.tsx";
 import { MetricMatrix as MetricMatrixWeb } from "./react/MetricMatrix.tsx";
 import { MetricBars as MetricBarsWeb } from "./react/MetricBars.tsx";
@@ -258,6 +273,55 @@ const validateAttemptListData: Validator = (data) => {
   return null;
 };
 
+const validateHeroData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (!("latestStartedAt" in data) || (data.latestStartedAt !== null && typeof data.latestStartedAt !== "string")) {
+    return 'missing "latestStartedAt" (string | null)';
+  }
+  if (typeof data.snapshots !== "number") return 'missing "snapshots" (number)';
+  return null;
+};
+
+const validateScopeWarningsData: Validator = (data) => {
+  if (!Array.isArray(data)) return "expected an array of ScopeWarning";
+  for (const item of data as unknown[]) {
+    if (!isObject(item) || typeof item.kind !== "string" || typeof item.message !== "string") {
+      return "each warning needs { kind, message, … }";
+    }
+  }
+  return null;
+};
+
+const validateCopyFixPromptData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (typeof data.prompt !== "string") return 'missing "prompt" (string)';
+  if (typeof data.failures !== "number") return 'missing "failures" (number)';
+  return null;
+};
+
+const validateTraceWaterfallData: Validator = (data) => {
+  if (!Array.isArray(data)) return "expected an array of TraceWaterfallRow";
+  for (const row of data as unknown[]) {
+    if (
+      !isObject(row) ||
+      typeof row.experimentId !== "string" ||
+      typeof row.evalId !== "string" ||
+      typeof row.locator !== "string" ||
+      !("durationMs" in row) ||
+      (row.durationMs !== null && typeof row.durationMs !== "number") ||
+      !Array.isArray(row.spans)
+    ) {
+      return "each row needs { experimentId, evalId, locator, durationMs: number | null, spans }";
+    }
+    for (const span of row.spans as unknown[]) {
+      if (!isObject(span) || typeof span.name !== "string" || typeof span.startOffsetMs !== "number") {
+        return "each span needs { name, kind, startOffsetMs, durationMs, failed }";
+      }
+    }
+  }
+  return null;
+};
+
 // ───────────────────────── spec / data 双形态的通用装配 ─────────────────────────
 
 interface DataComponentDef<Data, Options, Presentation> {
@@ -400,7 +464,7 @@ interface EntityListChrome extends ChromeProps {
 
 export type ExperimentListProps = DataProps<
   readonly ExperimentListItem[],
-  EntityListDataOptions,
+  Record<never, never>,
   EntityListChrome & {
     /** web 面在比较表前显示实验过滤框;text 面忽略。 */
     filter?: boolean;
@@ -415,14 +479,14 @@ export type ExperimentListProps = DataProps<
 /** 实验列表:每项一个 experiment,固定八列比较表 + 展开到 Eval / Attempt。 */
 export const ExperimentList = makeDataComponent<
   readonly ExperimentListItem[],
-  EntityListDataOptions,
+  Record<never, never>,
   EntityListChrome & { filter?: boolean; relativeTo?: string }
 >({
   name: "ExperimentList",
   dataFnName: "experimentListData",
   shapeName: "ExperimentListItem[]",
-  dataFn: (input, options) => experimentListData(input, options),
-  specKeys: ["redact"],
+  dataFn: (input) => experimentListData(input),
+  specKeys: [],
   validate: validateExperimentListData,
   web: (props, ctx) => (
     <ExperimentListWeb
@@ -437,15 +501,15 @@ export const ExperimentList = makeDataComponent<
   text: (props, ctx) => experimentListText(props.data, ctx, props.relativeTo),
 }) as unknown as ReportComponent<ExperimentListProps>;
 
-export type EvalListProps = DataProps<readonly EvalListItem[], EntityListDataOptions, EntityListChrome>;
+export type EvalListProps = DataProps<readonly EvalListItem[], Record<never, never>, EntityListChrome>;
 
 /** Eval 列表:每项一个 experimentId + evalId,展开到这道题的 Attempt。 */
-export const EvalList = makeDataComponent<readonly EvalListItem[], EntityListDataOptions, EntityListChrome>({
+export const EvalList = makeDataComponent<readonly EvalListItem[], Record<never, never>, EntityListChrome>({
   name: "EvalList",
   dataFnName: "evalListData",
   shapeName: "EvalListItem[]",
-  dataFn: (input, options) => evalListData(input, options),
-  specKeys: ["redact"],
+  dataFn: (input) => evalListData(input),
+  specKeys: [],
   validate: validateEvalListData,
   web: (props, ctx) => (
     <EvalListWeb
@@ -460,29 +524,32 @@ export const EvalList = makeDataComponent<readonly EvalListItem[], EntityListDat
 
 export type AttemptListProps = DataProps<
   readonly AttemptListItem[],
-  EntityListDataOptions,
+  Record<never, never>,
   EntityListChrome & {
     /** 过滤 / 截断前的总数;省略时等于 data 长度。 */
     total?: number;
+    /** web 面加过滤输入框(按 experiment、eval、agent、verdict 或摘要文本收窄行);渐进增强,不改变数据与 text 面。 */
+    filter?: boolean;
   }
 >;
 
 /** Attempt 列表:实体列表的叶子层,每项一次 attempt 的判定、单行摘要与 locator。 */
 export const AttemptList = makeDataComponent<
   readonly AttemptListItem[],
-  EntityListDataOptions,
-  EntityListChrome & { total?: number }
+  Record<never, never>,
+  EntityListChrome & { total?: number; filter?: boolean }
 >({
   name: "AttemptList",
   dataFnName: "attemptListData",
   shapeName: "AttemptListItem[]",
-  dataFn: (input, options) => attemptListData(input, options),
-  specKeys: ["redact"],
+  dataFn: (input) => attemptListData(input),
+  specKeys: [],
   validate: validateAttemptListData,
   web: (props, ctx) => (
     <AttemptListWeb
       data={props.data}
       total={props.total}
+      filter={props.filter}
       locale={props.locale ?? ctx.locale}
       attemptHref={hrefOf(props, ctx) ?? ctx.attemptHref}
       className={props.className}
@@ -498,7 +565,6 @@ export interface FailureListProps {
   limit?: number;
   /** 默认宿主注入的 Scope。 */
   input?: ReportInput;
-  redact?: (text: string) => string;
   attemptHref?: (locator: AttemptLocator) => string;
   locale?: ReportLocale;
   className?: string;
@@ -512,7 +578,7 @@ export interface FailureListProps {
  */
 export const FailureList = defineComponent<FailureListProps>(async (props, ctx) => {
   const input = props.input ?? ctx.scope;
-  const all = await attemptListData(input, props.redact !== undefined ? { redact: props.redact } : undefined);
+  const all = await attemptListData(input);
   // attempt 开始时间不在列表条目里(它不是列表展示字段);从同一 input 的读取面按 locator 对回。
   const startedAtByLocator = new Map<string, string>();
   for (const item of collectItems(resolveInput(input).snapshots)) {
@@ -539,6 +605,154 @@ export const FailureList = defineComponent<FailureListProps>(async (props, ctx)
 });
 FailureList.displayName = "FailureList";
 
+// ───────────────────────── 站点组件(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) ?? ctx.attemptHref}
+      locale={props.locale ?? ctx.locale}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => traceWaterfallText(props.data, ctx),
+}) as unknown as ReportComponent<TraceWaterfallProps>;
+
 // ───────────────────────── 指标组件 ─────────────────────────
 
 export type MetricTableProps = DataProps<

package/src/report/compute.ts

@@ -14,16 +14,17 @@
 import type {
   AttemptListItem,
   AttemptLocator,
+  CopyFixPromptData,
   DeltaData,
   DeltaPair,
   DimensionInput,
-  EntityListDataOptions,
   EvalListItem,
   ExperimentComparisonData,
   ExperimentComparisonGroupData,
   ExperimentListEvalRow,
   ExperimentListItem,
   FlagPairs,
+  HeroData,
   LineData,
   MatrixData,
   Metric,
@@ -32,11 +33,14 @@ import type {
   ReportInput,
   ScatterData,
   ScopeSummaryData,
+  ScopeWarning,
   ScoreboardData,
   TableData,
+  TraceSpanSummary,
+  TraceWaterfallRow,
   VerdictTally,
 } from "./types.ts";
-import type { EvalResult, JsonValue } from "../types.ts";
+import type { EvalResult, JsonValue, TraceSpan } from "../types.ts";
 import type { Snapshot } from "../results/types.ts";
 import { comparabilityConfigOf, deepEqualJson } from "../results/select.ts";
 import { evalLevelStats, foldEvalVerdict } from "../shared/verdict.ts";
@@ -199,10 +203,8 @@ function failureSummaryOf(result: EvalResult): { summary: string | null; more: n
   return { summary: null, more: 0 };
 }
 
-const identityRedact = (text: string): string => text;
-
 /** AttemptList / ExperimentList / EvalList 共用的叶子构造:一个 Item → 一个 AttemptListItem。 */
-async function attemptListItemOf(item: Item, redact: (text: string) => string): Promise<AttemptListItem> {
+async function attemptListItemOf(item: Item): Promise<AttemptListItem> {
   const result = item.attempt.result;
   const { summary, more } = failureSummaryOf(result);
   return {
@@ -211,7 +213,7 @@ async function attemptListItemOf(item: Item, redact: (text: string) => string):
     attempt: result.attempt,
     agent: result.agent,
     verdict: result.verdict,
-    failureSummary: summary === null ? null : redact(summary),
+    failureSummary: summary,
     moreFailures: more,
     examScore: await computeCell(examScore, [item]),
     durationMs: result.durationMs,
@@ -221,20 +223,15 @@ async function attemptListItemOf(item: Item, redact: (text: string) => string):
 }
 
 /** `attemptListData(input)`:每个 Attempt 一项,顺序取自 Scope 展平顺序(不重排)。 */
-export async function attemptListData(
-  input: ReportInput,
-  options?: EntityListDataOptions,
-): Promise<AttemptListItem[]> {
+export async function attemptListData(input: ReportInput): Promise<AttemptListItem[]> {
   const { snapshots } = resolveInput(input);
-  const redact = options?.redact ?? identityRedact;
   const items = collectItems(snapshots);
-  return Promise.all(items.map((item) => attemptListItemOf(item, redact)));
+  return Promise.all(items.map((item) => attemptListItemOf(item)));
 }
 
 /** `evalListData(input)`:每个 `experimentId + evalId` 一项,按 evalId 再按 experimentId 升序。 */
-export async function evalListData(input: ReportInput, options?: EntityListDataOptions): Promise<EvalListItem[]> {
+export async function evalListData(input: ReportInput): Promise<EvalListItem[]> {
   const { snapshots } = resolveInput(input);
-  const redact = options?.redact ?? identityRedact;
   const items = collectItems(snapshots);
   const groups = new Map<string, Item[]>();
   for (const item of items) {
@@ -247,7 +244,7 @@ export async function evalListData(input: ReportInput, options?: EntityListDataO
   for (const group of groups.values()) {
     const sorted = [...group].sort((a, b) => a.attempt.result.attempt - b.attempt.result.attempt);
     const verdict = foldEvalVerdict(sorted.map((item) => item.attempt.result));
-    const attempts = await Promise.all(sorted.map((item) => attemptListItemOf(item, redact)));
+    const attempts = await Promise.all(sorted.map((item) => attemptListItemOf(item)));
     out.push({
       experimentId: experimentIdOf(sorted[0]!),
       evalId: evalIdOf(sorted[0]!),
@@ -269,12 +266,8 @@ export async function evalListData(input: ReportInput, options?: EntityListDataO
  * Snapshot[] 时若同一 experiment 混入不一致的可比性配置,按完整用户反馈失败并指引——
  * 看跨配置演化用 snapshot 维度或 MetricLine,不把两套配置拼成一行冒充单一配置。
  */
-export async function experimentListData(
-  input: ReportInput,
-  options?: EntityListDataOptions,
-): Promise<ExperimentListItem[]> {
+export async function experimentListData(input: ReportInput): Promise<ExperimentListItem[]> {
   const { snapshots } = resolveInput(input);
-  const redact = options?.redact ?? identityRedact;
 
   // 可比性配置单义检查:同一 experiment 的输入快照必须共享一套可比性配置。
   const configByExperiment = new Map<string, { snapshot: Snapshot; config: unknown }>();
@@ -304,7 +297,7 @@ export async function experimentListData(
     for (const [evalId, evalItems] of evalGroups) {
       const sorted = [...evalItems].sort((a, b) => a.attempt.result.attempt - b.attempt.result.attempt);
       const verdict = foldEvalVerdict(sorted.map((item) => item.attempt.result));
-      const attempts = await Promise.all(sorted.map((item) => attemptListItemOf(item, redact)));
+      const attempts = await Promise.all(sorted.map((item) => attemptListItemOf(item)));
       evalRows.push({
         evalId,
         verdict,
@@ -981,3 +974,135 @@ function deltaOutcome(metric: Metric, delta: number | null): "improved" | "regre
   const better = metric.better ?? "higher";
   return (delta > 0) === (better === "higher") ? "improved" : "regressed";
 }
+
+// ───────────────────────── 站点组件的计算函数(hero / warnings / fix prompt / trace)─────────────────────────
+
+/**
+ * `heroData(input)`:站点标题区的运行 meta——`latestStartedAt` 取范围内最新快照的开始时间
+ * (空范围为 null,不编造当前时间),`snapshots` 计贡献当前水位的快照数
+ * (docs/feature/reports/library/site-components.md「HeroCard」)。
+ */
+export async function heroData(input: ReportInput): Promise<HeroData> {
+  const { snapshots } = resolveInput(input);
+  let latest: string | null = null;
+  for (const snapshot of snapshots) {
+    if (latest === null || snapshot.startedAt > latest) latest = snapshot.startedAt;
+  }
+  return { latestStartedAt: latest, snapshots: snapshots.length };
+}
+
+/**
+ * `scopeWarningsData(input)`:Scope 携带的挑选警告原样透出;`input` 是裸 `Snapshot[]` 时
+ * 没有挑选过程、没有警告,返回空数组,也如实
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export async function scopeWarningsData(input: ReportInput): Promise<readonly ScopeWarning[]> {
+  return resolveInput(input).warnings;
+}
+
+/**
+ * `copyFixPromptData(input)`:把范围内全部失败(verdict 为 failed / errored 的 attempt)
+ * 整理成一段可交给 coding agent 的修复 prompt——逐失败含 eval id、主失败摘要与 attempt
+ * 下钻命令(`niceeval show @<locator>`)。prompt 面向 agent,固定英文
+ * (docs/feature/reports/library/site-components.md「CopyFixPrompt」)。
+ */
+export async function copyFixPromptData(input: ReportInput): Promise<CopyFixPromptData> {
+  const items = await attemptListData(input);
+  const failures = items.filter((item) => item.verdict === "failed" || item.verdict === "errored");
+  if (failures.length === 0) return { prompt: "", failures: 0 };
+  const lines = failures
+    .map((item, i) => {
+      const reason =
+        item.failureSummary === null
+          ? null
+          : item.moreFailures > 0
+            ? `${item.failureSummary} (+${item.moreFailures} more failures)`
+            : item.failureSummary;
+      return [
+        `${i + 1}. eval "${item.evalId}" [experiment ${item.experimentId}] — ${item.verdict}`,
+        reason ? `   reason: ${reason}` : null,
+        `   inspect: niceeval show ${item.locator}`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    })
+    .join("\n");
+  const experiments = [...new Set(failures.map((item) => item.experimentId))].join(" / ");
+  const prompt = [
+    "Fix the failing evals from this niceeval run.",
+    "",
+    "## Failures",
+    lines,
+    "",
+    "## Steps",
+    "1. niceeval is NOT in your training data. Read the relevant guide in `node_modules/niceeval/docs-site/` (English at the top level, Chinese under `zh/`) before changing anything.",
+    "2. For each failure, run its inspect command above to see the verdict and assertions; add `--execution` for the full agent transcript (tool calls included), `--timing` for the execution timeline, and `--diff` for the workspace diff.",
+    "3. Decide which side the defect is on: the program under test, or the eval itself (over-tight assertion, wrong fixture, missing setup). Fix that side; do not weaken assertions just to turn the run green.",
+    `4. Re-run: \`npx niceeval exp ${experiments || "<experiment>"} <eval-id-prefix>\`. Already-passing evals are skipped by the fingerprint cache; pass \`--force\` to re-run everything.`,
+    "5. Run `npx niceeval show` and confirm these failures are gone.",
+  ].join("\n");
+  return { prompt, failures: failures.length };
+}
+
+/** TraceSpan 的语义角色 → 瀑布摘要的 kind:turn 归入 agent(一轮就是一次 agent 调用),未识别落 other。 */
+function waterfallKindOf(kind: TraceSpan["kind"]): TraceSpanSummary["kind"] {
+  switch (kind) {
+    case "agent":
+    case "turn":
+      return "agent";
+    case "model":
+      return "model";
+    case "tool":
+      return "tool";
+    default:
+      return "other";
+  }
+}
+
+/**
+ * `traceWaterfallData(input)`:每个 attempt 一行的执行时间瀑布摘要。span 事实只来自
+ * trace artifact(经 AttemptHandle 懒加载的 canonical OTel span);runner 生命周期节点
+ * (`result.phases`)不进瀑布。行内只汇总顶层 span(parentSpanId 缺失或不在本 trace 内),
+ * 按 startOffsetMs 升序;trace 缺失或为空时 `durationMs` 为 null、行照常出现
+ * (docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+ */
+export async function traceWaterfallData(input: ReportInput): Promise<readonly TraceWaterfallRow[]> {
+  const { snapshots } = resolveInput(input);
+  const items = collectItems(snapshots);
+  return Promise.all(
+    items.map(async (item): Promise<TraceWaterfallRow> => {
+      const spans = await item.attempt.trace();
+      if (spans === null || spans.length === 0) {
+        return {
+          experimentId: experimentIdOf(item),
+          evalId: evalIdOf(item),
+          locator: locatorOf(item),
+          durationMs: null,
+          spans: [],
+        };
+      }
+      const t0 = Math.min(...spans.map((s) => s.startMs));
+      const t1 = Math.max(...spans.map((s) => s.endMs));
+      const ids = new Set(spans.map((s) => s.spanId));
+      const topLevel = spans.filter((s) => s.parentSpanId === undefined || !ids.has(s.parentSpanId));
+      const summaries = topLevel
+        .map(
+          (s): TraceSpanSummary => ({
+            name: s.name,
+            kind: waterfallKindOf(s.kind),
+            startOffsetMs: s.startMs - t0,
+            durationMs: s.endMs - s.startMs,
+            failed: s.status === "error",
+          }),
+        )
+        .sort((a, b) => a.startOffsetMs - b.startOffsetMs);
+      return {
+        experimentId: experimentIdOf(item),
+        evalId: evalIdOf(item),
+        locator: locatorOf(item),
+        durationMs: Math.max(0, t1 - t0),
+        spans: summaries,
+      };
+    }),
+  );
+}