niceeval 0.9.1 → 0.10.0

package/src/report/components/entity-lists/compute.ts

@@ -0,0 +1,196 @@
+// 计算函数(*Data):ReportInput → 一份组件数据。实体列表族(ExperimentList / EvalList /
+// AttemptList / FailureList)的 *Data 都住在这里(docs/feature/reports/library/entity-lists.md)。
+//
+// 共同约定(docs/feature/reports/architecture.md「指标聚合不变量」):
+// - 第一参收 ReportInput = Scope | readonly Snapshot[];warnings 不进组件数据(宿主统一显示);
+// - 聚合前按身份键去重(dedupeAttempts;missing-startedAt 不去重、如实保留、不透出警告);
+// - null ≠ 0:缺数据不编数,覆盖率经 samples/total 如实暴露;
+// - core 中立:只认 Metric / Dimension 接口,不出现具体 agent 名的分支。
+
+import type {
+  AttemptListItem,
+  EvalListItem,
+  ExperimentListEvalRow,
+  ExperimentListItem,
+  ReportInput,
+} from "../../model/types.ts";
+import type { EvalResult } from "../../../types.ts";
+import type { Snapshot } from "../../../results/types.ts";
+import { comparabilityConfigOf, deepEqualJson } from "../../../results/select.ts";
+import { foldEvalVerdict } from "../../../shared/verdict.ts";
+import {
+  collectItems,
+  computeCell,
+  evalIdOf,
+  experimentIdOf,
+  fullEvalKey,
+  groupItems,
+  locatorOf,
+  resolveInput,
+  type Item,
+} from "../../model/aggregate.ts";
+import { attemptCostUSD, costUSD, durationMs, endToEndPassRate, examScore, tokens } from "../../model/metrics.ts";
+import { compactAssertionSummary, primaryAssertionSummary, summaryText } from "../../../scoring/display.ts";
+import { selectedEvalsOnly, summarizeItems } from "../shared-compute.ts";
+
+/**
+ * 一次 attempt 的单行结果摘要(Scoring display 契约):failed 取主失败断言摘要(不含
+ * "+N more",N 单独进 moreFailures),errored 取结构化 error 的一层摘要
+ * (phase · code · message),passed / skipped 为 null。
+ */
+export function failureSummaryOf(result: EvalResult): { summary: string | null; more: number } {
+  if (result.verdict === "errored" && result.error !== undefined) {
+    const parts = [result.error.phase, result.error.code, result.error.message].filter(
+      (part): part is string => typeof part === "string" && part.length > 0,
+    );
+    return { summary: summaryText(parts.join(" · ")), more: 0 };
+  }
+  if (result.verdict === "failed" || result.verdict === "errored") {
+    const primary = primaryAssertionSummary(result.assertions, result.verdict);
+    if (primary !== undefined) {
+      return {
+        summary: compactAssertionSummary({ ...primary, additionalFailures: 0 }),
+        more: primary.additionalFailures,
+      };
+    }
+    if (result.verdict === "errored" && result.skipReason !== undefined) {
+      return { summary: summaryText(result.skipReason), more: 0 };
+    }
+    return { summary: null, more: 0 };
+  }
+  return { summary: null, more: 0 };
+}
+
+/** AttemptList / ExperimentList / EvalList 共用的叶子构造:一个 Item → 一个 AttemptListItem。 */
+async function attemptListItemOf(item: Item): Promise<AttemptListItem> {
+  const result = item.attempt.result;
+  const { summary, more } = failureSummaryOf(result);
+  return {
+    experimentId: experimentIdOf(item),
+    evalId: evalIdOf(item),
+    attempt: result.attempt,
+    agent: result.agent,
+    verdict: result.verdict,
+    failureSummary: summary,
+    moreFailures: more,
+    examScore: await computeCell(examScore, [item]),
+    durationMs: result.durationMs,
+    costUSD: attemptCostUSD(result),
+    locator: locatorOf(item),
+  };
+}
+
+/** `attemptListData(input)`:每个 Attempt 一项,顺序取自 Scope 展平顺序(不重排)。 */
+export async function attemptListData(input: ReportInput): Promise<AttemptListItem[]> {
+  const { snapshots } = resolveInput(input);
+  const items = collectItems(snapshots);
+  return Promise.all(items.map((item) => attemptListItemOf(item)));
+}
+
+/** `evalListData(input)`:每个 `experimentId + evalId` 一项,按 evalId 再按 experimentId 升序。 */
+export async function evalListData(input: ReportInput): Promise<EvalListItem[]> {
+  const { snapshots } = resolveInput(input);
+  const items = collectItems(snapshots);
+  const groups = new Map<string, Item[]>();
+  for (const item of items) {
+    const key = fullEvalKey(item);
+    const list = groups.get(key);
+    if (list) list.push(item);
+    else groups.set(key, [item]);
+  }
+  const out: EvalListItem[] = [];
+  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)));
+    out.push({
+      experimentId: experimentIdOf(sorted[0]!),
+      evalId: evalIdOf(sorted[0]!),
+      verdict,
+      examScore: await computeCell(examScore, sorted),
+      durationMs: await computeCell(durationMs, sorted),
+      costUSD: await computeCell(costUSD, sorted),
+      attempts,
+    });
+  }
+  out.sort((a, b) => a.evalId.localeCompare(b.evalId) || a.experimentId.localeCompare(b.experimentId));
+  return out;
+}
+
+/**
+ * `experimentListData(input)`:每个 experiment 一项,展开到每道 Eval;初始按端到端通过率
+ * 从高到低(缺数据沉底,同分按 id)。一行只有一套 agent / model / flags 是输入约束:
+ * 宿主注入的 current() Scope 保证每个 experiment 只由可比性配置一致的快照拼成;作者自选
+ * Snapshot[] 时若同一 experiment 混入不一致的可比性配置,按完整用户反馈失败并指引——
+ * 看跨配置演化用 snapshot 维度或 MetricLine,不把两套配置拼成一行冒充单一配置。
+ */
+export async function experimentListData(input: ReportInput): Promise<ExperimentListItem[]> {
+  const { snapshots: rawSnapshots } = resolveInput(input);
+  const snapshots = selectedEvalsOnly(rawSnapshots);
+
+  // 可比性配置单义检查:同一 experiment 的输入快照必须共享一套可比性配置。
+  const configByExperiment = new Map<string, { snapshot: Snapshot; config: unknown }>();
+  for (const snapshot of snapshots) {
+    const config = comparabilityConfigOf(snapshot);
+    const existing = configByExperiment.get(snapshot.experimentId);
+    if (existing === undefined) {
+      configByExperiment.set(snapshot.experimentId, { snapshot, config });
+    } else if (!deepEqualJson(existing.config, config)) {
+      throw new Error(
+        `experimentListData got inconsistent comparability configs for experiment "${snapshot.experimentId}" ` +
+          `(snapshots ${existing.snapshot.startedAt} and ${snapshot.startedAt} differ in agent/model/reasoningEffort/flags/budget/timeoutMs/sandbox). ` +
+          "One row shows one configuration — it cannot honestly merge two. To chart evolution across configs, " +
+          'use the "snapshot" dimension or MetricLine; to show the current level, pass results.current() which selects a single config per experiment.',
+      );
+    }
+  }
+
+  const items = collectItems(snapshots);
+  const groups = groupItems(items, "experiment");
+  const out: ExperimentListItem[] = [];
+  for (const [experimentId, group] of groups) {
+    const stats = summarizeItems(group);
+    const newest = [...group].sort((a, b) => b.snapshot.startedAt.localeCompare(a.snapshot.startedAt))[0]!;
+    const evalGroups = groupItems(group, "eval");
+    const evalRows: ExperimentListEvalRow[] = [];
+    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)));
+      evalRows.push({
+        evalId,
+        verdict,
+        durationMs: await computeCell(durationMs, sorted),
+        costUSD: await computeCell(costUSD, sorted),
+        attempts,
+      });
+    }
+    const experiment = newest.snapshot.experiment ?? newest.attempt.result.experiment;
+    const model = newest.attempt.result.model ?? newest.snapshot.model;
+    out.push({
+      experimentId,
+      agent: newest.snapshot.agent || newest.attempt.result.agent,
+      ...(model !== undefined ? { model } : {}),
+      ...(experiment?.flags ? { flags: experiment.flags } : {}),
+      evalVerdicts: stats.verdicts,
+      endToEndPassRate: await computeCell(endToEndPassRate, group),
+      costUSD: await computeCell(costUSD, group),
+      durationMs: await computeCell(durationMs, group),
+      tokens: await computeCell(tokens, group),
+      evals: stats.evals,
+      attempts: stats.attempts,
+      lastRunAt: stats.lastRunAt!,
+      evalRows,
+    });
+  }
+  // 初始态按端到端通过率(endToEndPassRate)从高到低,缺数据沉底;同分按 experiment id 稳定排序。
+  out.sort((a, b) => {
+    const va = a.endToEndPassRate.value;
+    const vb = b.endToEndPassRate.value;
+    if (va === null && vb === null) return a.experimentId.localeCompare(b.experimentId);
+    if (va === null) return 1;
+    if (vb === null) return -1;
+    return vb - va || a.experimentId.localeCompare(b.experimentId);
+  });
+  return out;
+}

package/src/report/components/entity-lists/faces.ts

@@ -0,0 +1,207 @@
+// 实体列表族(ExperimentList / EvalList / AttemptList)的 text 面:同一份算好的数据,
+// 渲染成终端字符(niceeval show 的形态)。三面共用的紧凑标记:`locator✓`(判定符紧跟
+// locator,中间不留空格)。ExperimentList / EvalList 逐 attempt 只列这一个标记 + 各自的
+// 摘要,不重复整段 niceeval show 命令;要看某个 attempt 的完整证据,agent 自己拼
+// `niceeval show <locator>`。零 react、零 IO、纯同步。
+
+import type { AttemptListItem, EvalListItem, ExperimentListItem } from "../../model/types.ts";
+import type { TextContext } from "../../definition/tree.ts";
+import type { TableColumn, TableRow } from "../../definition/primitives.tsx";
+import {
+  experimentDisplayName,
+  fitFailureSummary,
+  formatDurationMs,
+  formatUSD,
+  verdictMark,
+} from "../../model/format.ts";
+import { countText, localeText, type ReportLocale } from "../../model/locale.ts";
+import { stringWidth, wrapDisplay } from "../../model/text-layout.ts";
+import { renderTableText } from "../../definition/table-text.ts";
+import { cellText, missingText, verdictTallyText, MISSING_MARK } from "../shared-faces.ts";
+
+// ───────────────────────── 实体列表(ExperimentList / EvalList / AttemptList)─────────────────────────
+//
+// 三面共用的紧凑标记:`locator✓`(判定符紧跟 locator,中间不留空格)。
+// ExperimentList / EvalList 逐 attempt 只列这一个标记 + 各自的摘要,不重复整段
+// niceeval show 命令;要看某个 attempt 的完整证据,agent 自己拼 `niceeval show <locator>`。
+
+function locatorBadge(item: { locator: string; verdict: AttemptListItem["verdict"] }): string {
+  return `${item.locator}${verdictMark(item.verdict)}`;
+}
+
+/**
+ * failureSummary + moreFailures 的展示形态:摘要在计算侧已按 Scoring display 契约折好,
+ * 这里只加 "+N more failures" 计数与宽度收口,不重算摘要。
+ */
+function attemptReasonText(item: AttemptListItem, locale: ReportLocale, maxChars: number): string | undefined {
+  if (item.failureSummary === null) return undefined;
+  const withMore =
+    item.moreFailures > 0
+      ? `${item.failureSummary} · ${countText(locale, "entityList.moreFailures", item.moreFailures)}`
+      : item.failureSummary;
+  return fitFailureSummary(withMore, Math.max(24, maxChars));
+}
+
+// ── ExperimentList ──
+
+function experimentSummaryTable(
+  items: readonly ExperimentListItem[],
+  ctx: TextContext,
+  relativeTo?: string,
+): string {
+  const locale = ctx.locale;
+  const compact = ctx.width < 100;
+  const columns: TableColumn[] = [
+    { key: "experiment", header: compact && locale === "en" ? "Exp." : localeText(locale, "experimentList.experiment") },
+    { key: "model", header: localeText(locale, "table.model") },
+    { key: "agent", header: localeText(locale, "table.agent") },
+    { key: "duration", header: compact && locale === "en" ? "Avg" : localeText(locale, "experimentList.avgDuration"), align: "right" },
+    { key: "passRate", header: compact && locale === "en" ? "Pass" : localeText(locale, "experimentList.passRate"), align: "right" },
+    { key: "result", header: localeText(locale, "experimentList.result") },
+    { key: "tokens", header: localeText(locale, "experimentList.tokens"), align: "right" },
+    { key: "cost", header: localeText(locale, "experimentList.cost"), align: "right" },
+  ];
+  const rows: TableRow[] = items.map((item) => ({
+    key: item.experimentId,
+    cells: {
+      experiment: experimentDisplayName(item.experimentId, relativeTo),
+      model: item.model ?? localeText(locale, "experimentList.defaultModel"),
+      agent: item.agent,
+      duration: cellText(item.durationMs, locale),
+      passRate: cellText(item.endToEndPassRate, locale),
+      result: verdictTallyText(item.evalVerdicts, locale),
+      tokens: cellText(item.tokens, locale),
+      cost: cellText(item.costUSD, locale),
+    },
+  }));
+  const metadata = items.flatMap((item) =>
+    wrapDisplay(
+      `${experimentDisplayName(item.experimentId, relativeTo)}: ${localeText(locale, "overview.evalsCount", { n: item.evals })} · ${localeText(locale, "overview.attemptsCount", { n: item.attempts })} · ${item.lastRunAt}`,
+      Math.max(8, ctx.width - 2),
+    ).map((line) => `  ${line}`),
+  );
+  return [renderTableText({ columns: columns as unknown as [TableColumn, ...TableColumn[]], rows, locale }, ctx), metadata.join("\n")].join("\n");
+}
+
+function experimentDetailTable(item: ExperimentListItem, ctx: TextContext, relativeTo?: string): string {
+  const locale = ctx.locale;
+  const columns: TableColumn[] = [
+    { key: "status", header: localeText(locale, "experimentList.status") },
+    { key: "entity", header: localeText(locale, "experimentList.evalAttempt") },
+    // Result 是可扫读的失败预览,不是证据面:两行放不下的以 … 收口,完整值走 locator 下钻。
+    { key: "result", header: localeText(locale, "experimentList.result"), maxLines: 2 },
+    { key: "duration", header: localeText(locale, "experimentList.duration"), align: "right" },
+    { key: "cost", header: localeText(locale, "experimentList.cost"), align: "right" },
+  ];
+  // Result 的字符预算 ≈ 两行 × 它能分到的列宽(总宽减其它列的自然宽与列距)。这里只做
+  // 粗预算;精确的按宽度收口由列的 maxLines 兜底。
+  const statusWidth = Math.max(
+    stringWidth(localeText(locale, "experimentList.status")),
+    ...item.evalRows.map((row) => stringWidth(`${verdictMark(row.verdict)} ${localeText(locale, `verdict.${row.verdict}`)}`)),
+  );
+  const entityWidth = Math.max(
+    stringWidth(localeText(locale, "experimentList.evalAttempt")),
+    ...item.evalRows.flatMap((row) => [stringWidth(row.evalId), ...row.attempts.map((a) => stringWidth(a.locator) + 3)]),
+  );
+  const fixedWidth = statusWidth + entityWidth + 8 /* duration */ + 6 /* cost */ + 3 * 4; /* 4 段列距 */
+  const resultBudget = Math.max(24, (ctx.width - fixedWidth) * 2);
+  const rows: TableRow[] = item.evalRows.flatMap((row) => {
+    // Eval 父行只承载折叠判定与题级聚合;失败摘要只在 Attempt 子行出现。
+    const parent: TableRow = {
+      key: row.evalId,
+      cells: {
+        status: `${verdictMark(row.verdict)} ${localeText(locale, `verdict.${row.verdict}`)}`,
+        entity: row.evalId,
+        result: "",
+        duration: localeText(locale, "entityList.average", { value: cellText(row.durationMs, locale) }),
+        cost: localeText(locale, "entityList.average", { value: cellText(row.costUSD, locale) }),
+      },
+    };
+    const attempts: TableRow[] = row.attempts.map((attempt, index) => ({
+      key: attempt.locator,
+      cells: {
+        status: `  ${verdictMark(attempt.verdict)}`,
+        entity: `${index === row.attempts.length - 1 ? "└─" : "├─"} ${attempt.locator}`,
+        result: attemptReasonText(attempt, locale, resultBudget) ?? MISSING_MARK,
+        duration: attempt.verdict === "skipped" && attempt.durationMs === 0 ? null : formatDurationMs(attempt.durationMs),
+        cost: attempt.costUSD === null ? null : formatUSD(attempt.costUSD),
+      },
+    }));
+    return [parent, ...attempts];
+  });
+  const flags = item.flags && Object.keys(item.flags).length > 0
+    ? `${localeText(locale, "experimentList.flags")} ${Object.entries(item.flags)
+        .map(([key, value]) => `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`)
+        .join(" · ")}`
+    : undefined;
+  return [
+    experimentDisplayName(item.experimentId, relativeTo),
+    flags,
+    renderTableText({ columns: columns as unknown as [TableColumn, ...TableColumn[]], rows, locale }, ctx),
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function experimentListText(items: readonly ExperimentListItem[], ctx: TextContext, relativeTo?: string): string {
+  if (items.length === 0) return localeText(ctx.locale, "attemptList.empty");
+  return [
+    experimentSummaryTable(items, ctx, relativeTo),
+    ...items.map((item) => experimentDetailTable(item, ctx, relativeTo)),
+  ].join("\n\n");
+}
+
+// ── EvalList ──
+
+function evalListAttemptLine(item: AttemptListItem, ctx: TextContext): string {
+  // 行式列表同守「Result 最多两行」:预算 = 两行终端宽,超出按尾截收口。
+  const reason = attemptReasonText(item, ctx.locale, ctx.width * 2 - stringWidth(locatorBadge(item)) - 6);
+  return `  ${locatorBadge(item)}${reason ? ` · ${reason}` : ""}`;
+}
+
+export function evalListText(items: readonly EvalListItem[], ctx: TextContext): string {
+  const locale = ctx.locale;
+  if (items.length === 0) return localeText(locale, "attemptList.empty");
+  const blocks = items.map((item) => {
+    const identity = `${item.evalId} · ${item.experimentId} · ${localeText(locale, `verdict.${item.verdict}`)}`;
+    const summary = [
+      localeText(locale, "attemptList.score", { score: cellText(item.examScore, locale) }),
+      localeText(locale, "overview.attemptsCount", { n: item.attempts.length }),
+      localeText(locale, "entityList.average", {
+        value: item.durationMs.value === null ? missingText(locale) : formatDurationMs(item.durationMs.value),
+      }),
+      localeText(locale, "entityList.average", {
+        value: item.costUSD.value === null ? missingText(locale) : formatUSD(item.costUSD.value),
+      }),
+    ].join(" · ");
+    const attemptLines = item.attempts.map((attempt) => evalListAttemptLine(attempt, ctx));
+    return [identity, `  ${summary}`, ...attemptLines].join("\n");
+  });
+  return blocks.join("\n\n");
+}
+
+// ── AttemptList ──
+
+/** Attempt 比较卡片:只显示一条主失败摘要(至多两行终端宽);完整 assertions 走 locator 下钻。 */
+function attemptListItemText(item: AttemptListItem, ctx: TextContext): string {
+  const head = [
+    `${verdictMark(item.verdict)} ${item.locator}`,
+    item.evalId,
+    item.experimentId,
+    formatDurationMs(item.durationMs),
+    ...(item.costUSD !== null ? [formatUSD(item.costUSD)] : []),
+  ].join(" · ");
+  const lines = [head];
+  const reason = attemptReasonText(item, ctx.locale, ctx.width * 2 - 4);
+  if (reason) lines.push(`  ${reason}`);
+  return lines.join("\n");
+}
+
+export function attemptListText(items: readonly AttemptListItem[], total: number | undefined, ctx: TextContext): string {
+  const locale = ctx.locale;
+  if (items.length === 0) return localeText(locale, "attemptList.empty");
+  const blocks = items.map((item) => attemptListItemText(item, ctx));
+  const remaining = (total ?? items.length) - items.length;
+  if (remaining > 0) blocks.push(localeText(locale, "attemptList.truncatedText", { n: remaining }));
+  return blocks.join("\n\n");
+}

package/src/report/components/entity-lists/index.tsx

@@ -0,0 +1,241 @@
+// 官方双面组件的装配点:web 面(./ExperimentList.tsx / EvalList.tsx / AttemptList.tsx 的纯
+// React 组件)+ text 面(./faces.ts)+ resolve 解析面(spec 形态由管线代调配套 ./compute.ts)。
+// FailureList 是组合组件,内部就是 attemptListData → 过滤 → AttemptList data 形态,不产生
+// 自己的 data。
+
+import { defineComponent, type ReportComponent } from "../../definition/tree.ts";
+import type { AttemptListItem, EvalListItem, ExperimentListItem, ReportInput } from "../../model/types.ts";
+import type { AttemptLocator } from "../../../results/locator.ts";
+import { collectItems, locatorOf, resolveInput } from "../../model/aggregate.ts";
+import type { ReportLocale } from "../../model/locale.ts";
+import {
+  arrayProblem,
+  cellProblem,
+  isObject,
+  makeDataComponent,
+  hrefOf,
+  tallyProblem,
+  type ChromeProps,
+  type DataProps,
+  type Validator,
+} from "../shared.ts";
+import { attemptListData, evalListData, experimentListData } from "./compute.ts";
+import { attemptListText, evalListText, experimentListText } from "./faces.ts";
+import { AttemptList as AttemptListWeb } from "./AttemptList.tsx";
+import { EvalList as EvalListWeb } from "./EvalList.tsx";
+import { ExperimentList as ExperimentListWeb } from "./ExperimentList.tsx";
+
+/** AttemptListItem(src/report/model/types.ts):三个组件族共用的叶子形状(独立 data 或嵌套在 evalRows/attempts 里)。 */
+function attemptListItemProblem(value: unknown, path: string): string | null {
+  if (!isObject(value)) return `"${path}" must be an object`;
+  if (typeof value.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+  if (typeof value.evalId !== "string") return `"${path}.evalId" must be a string`;
+  if (typeof value.attempt !== "number") return `"${path}.attempt" must be a number`;
+  if (typeof value.agent !== "string") return `"${path}.agent" must be a string`;
+  if (typeof value.verdict !== "string") return `"${path}.verdict" must be a string`;
+  if (!(value.failureSummary === null || typeof value.failureSummary === "string")) {
+    return `"${path}.failureSummary" must be a string or null`;
+  }
+  if (typeof value.moreFailures !== "number") return `"${path}.moreFailures" must be a number`;
+  const examScoreProblem = cellProblem(value.examScore, `${path}.examScore`);
+  if (examScoreProblem !== null) return examScoreProblem;
+  if (typeof value.durationMs !== "number") return `"${path}.durationMs" must be a number`;
+  if (!(value.costUSD === null || typeof value.costUSD === "number")) return `"${path}.costUSD" must be a number or null`;
+  if (typeof value.locator !== "string") return `"${path}.locator" must be a string`;
+  return null;
+}
+
+export const validateExperimentListData: Validator = (data) =>
+  arrayProblem(data, "data", (item, path) => {
+    if (!isObject(item)) return `"${path}" must be an object`;
+    if (typeof item.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+    if (typeof item.agent !== "string") return `"${path}.agent" must be a string`;
+    const verdictsProblem = tallyProblem(item.evalVerdicts, `${path}.evalVerdicts`);
+    if (verdictsProblem !== null) return verdictsProblem;
+    const passRateProblem = cellProblem(item.endToEndPassRate, `${path}.endToEndPassRate`);
+    if (passRateProblem !== null) return passRateProblem;
+    const costProblem = cellProblem(item.costUSD, `${path}.costUSD`);
+    if (costProblem !== null) return costProblem;
+    const durationProblem = cellProblem(item.durationMs, `${path}.durationMs`);
+    if (durationProblem !== null) return durationProblem;
+    const tokensProblem = cellProblem(item.tokens, `${path}.tokens`);
+    if (tokensProblem !== null) return tokensProblem;
+    if (typeof item.evals !== "number") return `"${path}.evals" must be a number`;
+    if (typeof item.attempts !== "number") return `"${path}.attempts" must be a number`;
+    if (typeof item.lastRunAt !== "string") return `"${path}.lastRunAt" must be a string`;
+    return arrayProblem(item.evalRows, `${path}.evalRows`, (row, rowPath) => {
+      if (!isObject(row) || typeof row.evalId !== "string") {
+        return `"${rowPath}" must be an object with a string "evalId"`;
+      }
+      const rowDurationProblem = cellProblem(row.durationMs, `${rowPath}.durationMs`);
+      if (rowDurationProblem !== null) return rowDurationProblem;
+      const rowCostProblem = cellProblem(row.costUSD, `${rowPath}.costUSD`);
+      if (rowCostProblem !== null) return rowCostProblem;
+      return arrayProblem(row.attempts, `${rowPath}.attempts`, attemptListItemProblem);
+    });
+  });
+export const validateEvalListData: Validator = (data) =>
+  arrayProblem(data, "data", (item, path) => {
+    if (!isObject(item)) return `"${path}" must be an object`;
+    if (typeof item.experimentId !== "string") return `"${path}.experimentId" must be a string`;
+    if (typeof item.evalId !== "string") return `"${path}.evalId" must be a string`;
+    if (typeof item.verdict !== "string") return `"${path}.verdict" must be a string`;
+    const examScoreProblem = cellProblem(item.examScore, `${path}.examScore`);
+    if (examScoreProblem !== null) return examScoreProblem;
+    const durationProblem = cellProblem(item.durationMs, `${path}.durationMs`);
+    if (durationProblem !== null) return durationProblem;
+    const costProblem = cellProblem(item.costUSD, `${path}.costUSD`);
+    if (costProblem !== null) return costProblem;
+    return arrayProblem(item.attempts, `${path}.attempts`, attemptListItemProblem);
+  });
+export const validateAttemptListData: Validator = (data) => arrayProblem(data, "data", attemptListItemProblem);
+
+// ───────────────────────── 实体列表 ─────────────────────────
+
+interface EntityListChrome extends ChromeProps {
+  attemptHref?: (locator: AttemptLocator) => string;
+}
+
+export type ExperimentListProps = DataProps<
+  readonly ExperimentListItem[],
+  Record<never, never>,
+  EntityListChrome & {
+    /** web 面在比较表前显示实验过滤框;text 面忽略。 */
+    filter?: boolean;
+    /**
+     * 可选父路径:两面的行标签去掉与它相同的前缀,只显示 experiment id 末段。自定义报告
+     * 显式传入使用;默认 `ExperimentComparison` 不传,完整 id 始终可见。完整 id 仍是
+     * 排序 / 着色 / 过滤 / 折叠的键。
+     */
+    relativeTo?: string;
+  }
+>;
+
+/** 实验列表:每项一个 experiment,固定八列比较表 + 展开到 Eval / Attempt。 */
+export const ExperimentList = makeDataComponent<
+  readonly ExperimentListItem[],
+  Record<never, never>,
+  EntityListChrome & { filter?: boolean; relativeTo?: string }
+>({
+  name: "ExperimentList",
+  dataFnName: "experimentListData",
+  shapeName: "ExperimentListItem[]",
+  dataFn: (input) => experimentListData(input),
+  specKeys: [],
+  validate: validateExperimentListData,
+  web: (props, ctx) => (
+    <ExperimentListWeb
+      data={props.data}
+      filter={props.filter}
+      relativeTo={props.relativeTo}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx)}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => experimentListText(props.data, ctx, props.relativeTo),
+}) as unknown as ReportComponent<ExperimentListProps>;
+
+export type EvalListProps = DataProps<readonly EvalListItem[], Record<never, never>, EntityListChrome>;
+
+/** Eval 列表:每项一个 experimentId + evalId,展开到这道题的 Attempt。 */
+export const EvalList = makeDataComponent<readonly EvalListItem[], Record<never, never>, EntityListChrome>({
+  name: "EvalList",
+  dataFnName: "evalListData",
+  shapeName: "EvalListItem[]",
+  dataFn: (input) => evalListData(input),
+  specKeys: [],
+  validate: validateEvalListData,
+  web: (props, ctx) => (
+    <EvalListWeb
+      data={props.data}
+      locale={props.locale ?? ctx.locale}
+      attemptHref={hrefOf(props, ctx)}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => evalListText(props.data, ctx),
+}) as unknown as ReportComponent<EvalListProps>;
+
+export type AttemptListProps = DataProps<
+  readonly AttemptListItem[],
+  Record<never, never>,
+  EntityListChrome & {
+    /** 过滤 / 截断前的总数;省略时等于 data 长度。 */
+    total?: number;
+    /** web 面加过滤输入框(按 experiment、eval、agent、verdict 或摘要文本收窄行);渐进增强,不改变数据与 text 面。 */
+    filter?: boolean;
+  }
+>;
+
+/** Attempt 列表:实体列表的叶子层,每项一次 attempt 的判定、单行摘要与 locator。 */
+export const AttemptList = makeDataComponent<
+  readonly AttemptListItem[],
+  Record<never, never>,
+  EntityListChrome & { total?: number; filter?: boolean }
+>({
+  name: "AttemptList",
+  dataFnName: "attemptListData",
+  shapeName: "AttemptListItem[]",
+  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)}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => attemptListText(props.data, props.total, ctx),
+}) as unknown as ReportComponent<AttemptListProps>;
+
+// ───────────────────────── FailureList(官方组合件)─────────────────────────
+
+export interface FailureListProps {
+  /** 显示的最大条数;默认 20。 */
+  limit?: number;
+  /** 默认宿主注入的 Scope。 */
+  input?: ReportInput;
+  attemptHref?: (locator: AttemptLocator) => string;
+  locale?: ReportLocale;
+  className?: string;
+}
+
+/**
+ * 「现在有哪些失败要处理」的成品组合件:内部就是 attemptListData → 过滤 → AttemptList
+ * data 形态,与手写组合严格等价、没有私有能力(docs/feature/reports/library/entity-lists.md)。
+ * verdict ∈ failed / errored,按 attempt 开始时间降序(同刻按 locator 字典序),
+ * 截断到 limit(默认 20),total 报告截断前总数。
+ */
+export const FailureList = defineComponent<FailureListProps>(async (props, ctx) => {
+  const input = props.input ?? ctx.scope;
+  const all = await attemptListData(input);
+  // attempt 开始时间不在列表条目里(它不是列表展示字段);从同一 input 的读取面按 locator 对回。
+  const startedAtByLocator = new Map<string, string>();
+  for (const item of collectItems(resolveInput(input).snapshots)) {
+    startedAtByLocator.set(locatorOf(item), item.attempt.result.startedAt ?? "");
+  }
+  const failures = all
+    .filter((item) => item.verdict === "failed" || item.verdict === "errored")
+    .sort((a, b) => {
+      const ta = startedAtByLocator.get(a.locator) ?? "";
+      const tb = startedAtByLocator.get(b.locator) ?? "";
+      if (ta !== tb) return ta < tb ? 1 : -1; // 最近的失败在前
+      return a.locator < b.locator ? -1 : a.locator > b.locator ? 1 : 0;
+    });
+  const limit = props.limit ?? 20;
+  return (
+    <AttemptList
+      data={failures.slice(0, limit)}
+      total={failures.length}
+      attemptHref={props.attemptHref}
+      locale={props.locale}
+      className={props.className}
+    />
+  );
+});
+FailureList.displayName = "FailureList";