niceeval 0.6.2 → 0.7.1

package/src/show/index.ts

@@ -1,17 +1,18 @@
-// niceeval show —— 终端宿主(行为规范:docs-site/zh/guides/viewing-results.mdx;
-// 宿主组合语义:docs/feature/reports/architecture.md「Selection 是计算入口」)。
+// niceeval show —— 终端宿主(行为规范:docs/feature/reports/show.md 与分篇;
+// 宿主组合语义:docs/feature/reports/architecture.md「Scope 是计算入口」)。
 //
 // 位置参数 = eval id 前缀,或 `@<locator>`(精确指名单个 attempt,见 results/locator.ts):
-//   裸跑 / 多 eval 前缀  默认 ExperimentComparison 的 text 面(单 eval 前缀仍进入详情)
+//   裸跑 / 多 eval 前缀  内建报告(niceeval/report/built-in 默认导出)的 text 面(单 eval 前缀仍进入详情)
 //   恰好一个 eval     单 eval 详情(attempt / 断言明细,宿主本体)
 //   @<locator>        精确 attempt:无证据 flag → 紧凑全景;带 flag → 对应证据切面
-//   --eval / --execution / --diff[=路径]   证据切面(宿主本体):出现即走证据室,不渲染报告槽
-//   --history        跨 run 时间轴(内置趋势视图),与 --report 互斥
-//   --report <文件>  整槽换成用户报告;位置前缀 / --run / --experiment 先收窄 Selection 再注入
-//   --run <目录>     结果根换成该目录;--experiment Selection 只留该实验
+//   --source / --execution / --diff[=路径]   证据切面(宿主本体):出现即走证据室,不渲染报告槽
+//   --history        执行时间轴(逐 experimentId + evalId 分节),与 --report 互斥
+//   --report <文件>  整槽换成用户报告;位置前缀 / --results / --experiment 先收窄 Scope 再注入
+//   --page <id>      多页报告选页;未命中列出可用页 id 按用法错误退出
+//   --results <目录>  结果根换成该目录;--experiment 让 Scope 只留该实验
 //
-// 数据全部走 niceeval/results 的读取面(openResults + 合成 Selection + loadAttemptEvidence),
-// 不自己爬目录；证据可用性只由 loadAttemptEvidence 在单 Attempt 页面计算。
+// 数据全部走 niceeval/results 的读取面(openResults + 合成 Scope + loadAttemptEvidence),
+// 不自己爬目录;证据可用性只由 loadAttemptEvidence 在单 Attempt 页面计算。
 
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
@@ -23,33 +24,38 @@ import {
   LocatorNotFoundError,
   MalformedLocatorError,
 } from "../results/index.ts";
-// report.ts / load.ts have no JSX of their own, but ReportDefinition / ReportLoadError must
-// come from the SAME module instance ExperimentComparison (built-ins, .tsx) is built
-// against — `unique symbol` branding and `instanceof` are keyed by declaration site, so a raw
-// src copy and the compiled dist copy of "the same" ReportDefinition are, to TypeScript and to
-// `instanceof`, two different types. The package-owned report runtime ships as precompiled
-// ESM (dist/report/**, built by `pnpm run build:report`, immune to a consumer's cwd/tsconfig
-// when niceeval is linked in — see tsconfig.report-build.json); show pulls all of it from
-// there, not just the .tsx-touching pieces.
-import { renderReportToText } from "../../dist/report/report.js";
-import { ExperimentComparison } from "../../dist/report/built-ins/index.js";
-import { ReportLoadError, loadReportFile } from "../../dist/report/load.js";
+// ReportLoadError must come from the SAME module instance the report runtime is built
+// against — `instanceof` is keyed by declaration site, so a raw src copy and the compiled
+// dist copy of "the same" class are two different types. The package-owned report runtime
+// ships as precompiled ESM (dist/report/**, built by `pnpm run build:report`); all report
+// loading/rendering goes through ./report-host.ts (the single contact surface with it).
+import { ReportLoadError } from "../../dist/report/load.js";
 import { detectLocale, t } from "../i18n/index.ts";
 import { foldEvalVerdict } from "../shared/verdict.ts";
 import { selectCurrentResults, filterExperiments } from "../results/select.ts";
-import { evalHistory, experimentHistory } from "./compose.ts";
+import { evalPrefixPredicate } from "../shared/aggregate.ts";
+import { attemptHistory } from "./compose.ts";
+import {
+  HostReportError,
+  loadHostReport,
+  localizeText,
+  reportMetaFor,
+  renderHostPageText,
+  resolveReportTitle,
+  type HostCommandContext,
+} from "./report-host.ts";
 import {
   attemptArtifactsPath,
   attemptEvidenceHeader,
+  attemptHistoryText,
   attemptIndexLine,
   attemptOverviewText,
   attemptsOfEval,
   diffText,
   evalDetailText,
-  evalHistoryText,
   evalSourceText,
   executionText,
-  experimentHistoryText,
+  pageIndexText,
   timingText,
   pickDetailAttempt,
   skippedRunsText,
@@ -57,8 +63,8 @@ import {
 } from "./render.ts";
 
 export interface ShowFlags {
-  /** 该 attempt 运行时保存的 Eval 源码,断言标回源码行(证据切面)。 */
-  eval?: boolean;
+  /** --source:该 attempt 运行时保存的 Eval 源码,断言标回源码行(证据切面)。 */
+  source?: boolean;
   /** 该 attempt 的标准执行事件流 + OTel enrichment(证据切面)。 */
   execution?: boolean;
   /** --timing:默认有界诊断投影；full 逐节点展开。boolean 仅供库调用兼容，等价 summary。 */
@@ -69,8 +75,11 @@ export interface ShowFlags {
   diffPath?: string;
   history?: boolean;
   experiment?: string;
-  run?: string;
+  /** --results:结果根目录(某次快照根或 `copySnapshots` 产物)。 */
+  results?: string;
   report?: string;
+  /** --page:多页报告选页;未命中按用法错误退出并列出可用页 id。 */
+  page?: string;
 }
 
 /** 注入 IO 供测试;默认写 stdout/stderr、宽度取终端列数。 */
@@ -89,8 +98,8 @@ function clampWidth(columns: number | undefined): number {
   return Math.max(40, Math.min(columns as number, 160));
 }
 
-// --report 的装载移到中性模块(两个宿主共用),show 的导出面与错误行为不变。
-export { loadReportFile } from "../../dist/report/load.js";
+// --report 的装载与规范化住在 ./report-host.ts(两个宿主共用的唯一联系面)。
+export { loadHostReport, normalizeHostReport, resolveReportTitle, localizeText } from "./report-host.ts";
 
 export async function runShow(
   cwd: string,
@@ -109,7 +118,7 @@ export async function runShow(
     });
     return 0;
   } catch (e) {
-    if (e instanceof ShowError || e instanceof ReportLoadError) {
+    if (e instanceof ShowError || e instanceof ReportLoadError || e instanceof HostReportError) {
       err(e.message.endsWith("\n") ? e.message : `${e.message}\n`);
       return 1;
     }
@@ -124,7 +133,7 @@ async function show(
   io: { out: (s: string) => void; err: (s: string) => void; width: number; now: number },
 ): Promise<void> {
   const evidence =
-    flags.eval === true ||
+    flags.source === true ||
     flags.execution === true ||
     (flags.timing !== undefined && flags.timing !== false) ||
     flags.diff === true ||
@@ -135,8 +144,15 @@ async function show(
     throw new ShowError(t("cli.show.historyReportConflict"));
   }
 
-  const root = flags.run !== undefined ? resolve(cwd, flags.run) : join(cwd, ".niceeval");
-  if (flags.run !== undefined && !existsSync(root)) {
+  // --page 只在报告槽里有意义:证据切面 / 时间轴与它组合是用法矛盾,先于任何 IO 报出来。
+  if (flags.page !== undefined && (evidence || flags.history)) {
+    throw new ShowError(
+      `--page selects a report page and cannot be combined with ${flags.history ? "--history" : "evidence flags"}.\n`,
+    );
+  }
+
+  const root = flags.results !== undefined ? resolve(cwd, flags.results) : join(cwd, ".niceeval");
+  if (flags.results !== undefined && !existsSync(root)) {
     throw new ShowError(t("cli.show.runDirMissing", { dir: root }));
   }
 
@@ -150,7 +166,7 @@ async function show(
   // (`@` 打头对 eval id 天然无歧义,见 locator.ts),必须在下面的前缀匹配逻辑之前分流掉,
   // 不然 "@1x7f3q" 会被当成一个谁都匹配不到的 eval id 前缀,报「no eval match」这种文不对题的
   // 错误。这一步只解析并渲染出「当前 show 对单个已解析 attempt 能渲染的东西」(单 eval 详情 /
-  // 三个证据切面)——真正的 `--eval`/`--execution`/`--diff` 统一 attempt 全景是后续阶段。
+  // 三个证据切面)——真正的 `--source`/`--execution`/`--diff` 统一 attempt 全景是后续阶段。
   const locatorArg = patterns.find((p) => p.startsWith(ATTEMPT_LOCATOR_PREFIX));
   if (locatorArg !== undefined) {
     if (patterns.length !== 1) {
@@ -171,7 +187,7 @@ async function show(
     const artifactPath = attemptArtifactsPath(attempt, cwd);
     if (evidence) {
       const blocks: string[] = [];
-      if (flags.eval) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
+      if (flags.source) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
       if (flags.execution) blocks.push(executionText(attemptEvidence, { header, artifactPath, width: io.width }));
       if (flags.timing) blocks.push(timingText(attemptEvidence, {
         header,
@@ -240,7 +256,7 @@ async function show(
     const header = attemptEvidenceHeader(attemptEvidence);
     const artifactPath = attemptArtifactsPath(picked, cwd);
     const blocks: string[] = [];
-    if (flags.eval) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
+    if (flags.source) blocks.push(evalSourceText(attemptEvidence, { header, artifactPath, width: io.width }));
     if (flags.execution) blocks.push(executionText(attemptEvidence, { header, artifactPath, width: io.width }));
     if (flags.timing) blocks.push(timingText(attemptEvidence, {
       header,
@@ -255,30 +271,30 @@ async function show(
     return;
   }
 
-  // --history:内置趋势视图。时间轴只列真实执行 —— resume 携带的复印件不占行。
+  // --history:执行时间轴(docs/feature/reports/show.md「--history:一个 eval 的执行时间轴」)。
+  // 对 Scope 中匹配的每个 experimentId + evalId 分节,逐 attempt 而非逐快照;时间轴只列
+  // 真实执行 —— resume 携带的复印件按 attempt 身份键去重后不占行。
   if (flags.history) {
     const experiments = filterExperiments(results.experiments, flags.experiment);
+    // eval 位置参数与 Scope 选择用同一个前缀谓词(单点在 shared/aggregate.ts),不另立口径。
+    const matchesPattern = patterns.length > 0 ? evalPrefixPredicate(patterns) : () => true;
     const blocks: string[] = [];
-    if (patterns.length === 0) {
-      for (const exp of experiments) blocks.push(experimentHistoryText(exp.id, experimentHistory(exp)));
-    } else {
-      const multi = matchedEvalIds.length > 1;
-      for (const evalId of matchedEvalIds) {
-        for (const exp of experiments) {
-          const rows = evalHistory(exp, evalId);
-          if (rows.length === 0) continue;
-          blocks.push(evalHistoryText({ experimentId: exp.id, ...(multi ? { evalId } : {}), rows }));
-        }
+    for (const exp of experiments) {
+      const evalIds = [...exp.evalIds].filter(matchesPattern).sort();
+      for (const evalId of evalIds) {
+        const rows = attemptHistory(exp, evalId);
+        if (rows.length === 0) continue;
+        blocks.push(attemptHistoryText({ experimentId: exp.id, evalId, rows }));
       }
     }
     io.out(blocks.join("\n\n") + "\n");
     return;
   }
 
-  // 单 eval 详情(宿主本体);--report 在场时报告槽优先,前缀只用来收窄 Selection。
+  // 单 eval 详情(宿主本体);--report / --page 在场时报告槽优先,前缀只用来收窄 Scope。
   // 挑哪个 attempt 展开明细不再收数字 --attempt——pickDetailAttempt 的默认启发式
   // (最新一次失败,没有失败挑最新一次)是唯一路径;精确选某一次走 `@<locator>`。
-  if (flags.report === undefined && patterns.length > 0 && matchedEvalIds.length === 1) {
+  if (flags.report === undefined && flags.page === undefined && patterns.length > 0 && matchedEvalIds.length === 1) {
     const evalId = matchedEvalIds[0];
     const attempts = attemptsOfEval(selection.snapshots, evalId);
     const detail = pickDetailAttempt(attempts);
@@ -295,13 +311,48 @@ async function show(
     return;
   }
 
-  // 裸 show 与裸 view 选择同一个普通默认 definition,这里只是渲染 text 面。
-  // --report 替换同一个报告槽。locale = CLI 界面语言(NICEEVAL_LANG / LC_* / LANG 检测):报告 chrome 文案跟随
-  // 终端语言(docs/feature/reports/library.md「locale:渲染面的语言」);Locale 与 ReportLocale 同为
-  // "en" | "zh-CN",直接传递。
-  const definition = flags.report === undefined ? ExperimentComparison : await loadReportFile(cwd, flags.report);
-  // attemptCommand 留给 renderReportToText 的默认值:AttemptLocator 已经是可直接 `niceeval show
-  // @<locator>` 的真实 CLI 语法,不需要再反查 eval id 拼一条近似命令(见 tree.ts 的默认实现)。
-  const text = await renderReportToText(definition, { selection, results }, { width: io.width, locale: detectLocale() });
+  // 报告槽:裸 show 装载 `niceeval/report/built-in` 的默认导出,--report 整槽替换——同一条
+  // 「装载 → 规范化(外壳 + 非空页列表)→ 逐页渲染」管线(docs/feature/reports/library/shell.md)。
+  // locale = CLI 界面语言(NICEEVAL_LANG / LC_* / LANG 检测):报告 chrome 文案跟随终端语言。
+  const report = await loadHostReport(cwd, flags.report);
+  const locale = detectLocale();
+  const commandContext: HostCommandContext = {
+    patterns,
+    ...(flags.results !== undefined ? { results: flags.results } : {}),
+    ...(flags.report !== undefined ? { report: flags.report } : {}),
+    ...(flags.experiment !== undefined ? { experiment: flags.experiment } : {}),
+  };
+  const sourceLabel = flags.report ?? "the built-in report";
+
+  let page = report.pages[0];
+  if (flags.page !== undefined) {
+    const hit = report.pages.find((p) => p.id === flags.page);
+    if (!hit) {
+      // 用法错误:列出可用页 id(docs/feature/reports/show/reports.md Case 1/2 的报错样例)。
+      throw new ShowError(
+        `error: page "${flags.page}" not found in ${sourceLabel}. Available pages: ${report.pages.map((p) => p.id).join(", ")}\n`,
+      );
+    }
+    page = hit;
+  } else if (report.pages.length > 1) {
+    // 多页未选页:只输出页索引与可复制的单页命令,不倾倒页内容(与可比组索引同一模式)。
+    // 标题行走标题回退链(终点是内置文案「Eval 运行结果 / Eval Results」,恒有值)。
+    const title = localizeText(resolveReportTitle(report.title, selection.snapshots), locale) ?? "Eval Results";
+    io.out(pageIndexText({ report, title, command: commandContext, locale }) + "\n");
+    return;
+  }
+
+  // attemptCommand 留给渲染管线的默认值:AttemptLocator 已经是可直接 `niceeval show @<locator>`
+  // 的真实 CLI 语法,不需要再反查 eval id 拼一条近似命令。
+  const meta = reportMetaFor(report, page.id, selection.snapshots);
+  const text = await renderHostPageText(
+    page,
+    { scope: selection, results, report: meta },
+    {
+      width: io.width,
+      locale,
+      commandContext: { ...commandContext, ...(flags.page !== undefined ? { page: flags.page } : {}) },
+    },
+  );
   io.out(text + "\n");
 }

package/src/show/render.ts

@@ -1,5 +1,5 @@
 // show 的文本渲染:单 eval 详情、--history 时间轴、三个证据切面(transcript / trace / diff)。
-// 输出形态照 docs-site/zh/guides/viewing-results.mdx 的示例块;长内容一律截断,
+// 输出形态照 docs-site/zh/how-to/viewing-results.mdx 的示例块;长内容一律截断,
 // 但截断永远如实标注剩余数量和原始 artifact 路径 —— 输出对上下文窗口友好,事实源留在盘上。
 // 全部纯函数(时间经 now 显式传入),证据数据由调用方 await 好了递进来。
 
@@ -15,7 +15,8 @@ import { summaryText } from "../scoring/display.ts";
 import { attemptCostUSD } from "../report/metrics.ts";
 import { formatDurationMs, formatMetricValue, formatPlainNumber, formatUSD } from "../report/format.ts";
 import { indentBlock, padDisplay, renderAlignedRows, wrapDisplay } from "../report/text/layout.ts";
-import type { EvalHistoryRow, ExperimentHistoryRow } from "./compose.ts";
+import type { AttemptHistoryRow } from "./compose.ts";
+import { localizeText, showCommand, type HostCommandContext, type HostReport } from "./report-host.ts";
 
 const MISSING = "—";
 
@@ -72,8 +73,8 @@ export function attemptArtifactsPath(attempt: AttemptHandle, cwd: string): strin
 
 /**
  * 裸 `show` 零可读结果时,skipped 目录的展示文案。niceeval 自己写的、schemaVersion 不兼容的
- * 落盘按 producer 版本分组,一条 `npx niceeval@<version> show --run <结果根>` 覆盖同版本全部
- * 快照——show 没有 view 的单快照直读模式,`--run` 认的是结果根(其下可以有多个 experiment),
+ * 落盘按 producer 版本分组,一条 `npx niceeval@<version> show --results <结果根>` 覆盖同版本全部
+ * 快照——show 没有 view 的单快照直读模式,`--results` 认的是结果根(其下可以有多个 experiment),
  * 不是单个快照目录,所以不对每个目录重复拼一条各自的命令(那条命令用同一个 root 跑起来
  * 结果完全一样,重复只会刷屏)。其余(第三方 harness、版本信息缺失、malformed、incomplete)
  * 没有可执行的统一建议,原样逐条列出。
@@ -86,7 +87,7 @@ export function skippedRunsText(skipped: readonly SkippedDir[], root: string, cw
     const count = g.dirs.length;
     const version = g.producer.version;
     const schema = g.schemaVersion !== undefined ? ` (schemaVersion ${g.schemaVersion})` : "";
-    const cmd = `npx niceeval@${version} show --run ${rootDisplay}`;
+    const cmd = `npx niceeval@${version} show --results ${rootDisplay}`;
     lines.push(
       `  ${count} snapshot${count === 1 ? "" : "s"} written by niceeval ${version}${schema} — run \`${cmd}\` to view`,
     );
@@ -374,8 +375,8 @@ export function evalDetailText(opts: EvalDetailOptions): string {
     if (detail.locator) tail.push(`attempt locator: ${detail.locator}`);
     tail.push(
       detail.locator
-        ? `next: niceeval show ${detail.locator} [--eval|--execution|--diff]`
-        : `next: niceeval show ${evalId} [--eval|--execution|--diff]`,
+        ? `next: niceeval show ${detail.locator} [--source|--execution|--diff]`
+        : `next: niceeval show ${evalId} [--source|--execution|--diff]`,
     );
     blocks.push(tail.join("\n"));
   }
@@ -385,43 +386,58 @@ export function evalDetailText(opts: EvalDetailOptions): string {
 
 // ───────────────────────── --history ─────────────────────────
 
-/** 单 eval 时间轴:`compare/codex-gpt-5.4 · 5 runs · passed 2/5` + 每次真实执行一行。 */
-export function evalHistoryText(opts: {
+/**
+ * 一个 experimentId + evalId 的执行时间轴分节(docs/feature/reports/show.md「--history」):
+ * 节头 `<evalId> · <experimentId> · N attempts · passed x/N`,节内每行
+ * 时间 / verdict / 单行摘要 / 耗时 / 成本 / locator,startedAt 升序(compose 已排好)。
+ */
+export function attemptHistoryText(opts: {
   experimentId: string;
-  /** 多 eval 前缀时块头带上 eval id;单 eval 与 mdx 示例一致不带。 */
-  evalId?: string;
-  rows: EvalHistoryRow[];
+  evalId: string;
+  rows: AttemptHistoryRow[];
 }): string {
   const { experimentId, evalId, rows } = opts;
   const passed = rows.filter((r) => r.verdict === "passed").length;
   const head = [
-    ...(evalId ? [evalId] : []),
+    evalId,
     experimentId,
-    `${rows.length} ${rows.length === 1 ? "run" : "runs"}`,
+    attemptsLabel(rows.length),
     `passed ${passed}/${rows.length}`,
   ].join(" · ");
   if (rows.length === 0) return head;
   const table = renderAlignedRows(
     rows.map((r) => [
-      timelineStamp(r.startedAt),
+      r.startedAt !== undefined ? timelineStamp(r.startedAt) : MISSING,
       `${verdictMark(r.verdict)} ${r.verdict}`,
-      attemptsLabel(r.attempts),
+      r.summary ?? MISSING,
+      formatDurationMs(r.durationMs),
       r.costUSD === null ? MISSING : formatUSD(r.costUSD),
-      r.failedAssertion ?? (r.error ? `error: ${r.error}` : ""),
+      r.locator ?? MISSING,
     ]),
   );
   return `${head}\n\n${indentBlock(table, "  ")}`;
 }
 
-/** 实验级 per-run 通过率序列(裸 `show --history`)。 */
-export function experimentHistoryText(experimentId: string, rows: ExperimentHistoryRow[]): string {
-  const head = `${experimentId} · ${rows.length} ${rows.length === 1 ? "run" : "runs"}`;
-  if (rows.length === 0) return head;
+// ───────────────────────── --report 页索引 ─────────────────────────
+
+/**
+ * 多页报告的页索引(docs/feature/reports/show/reports.md Case 2):标题行 + 每页一行
+ * (id / 本 locale 页名 / 可复制的 `--page` 命令)。索引命令携带完整上下文
+ * (--results / --report / 位置参数),复制即可精确复现下一层视图。
+ */
+export function pageIndexText(opts: {
+  report: HostReport;
+  title: string;
+  command: HostCommandContext;
+  locale: string;
+}): string {
+  const { report, title, command, locale } = opts;
+  const head = `${title} · ${locale === "zh-CN" ? `${report.pages.length} 页` : `${report.pages.length} pages`}`;
   const table = renderAlignedRows(
-    rows.map((r) => [
-      timelineStamp(r.startedAt),
-      `${r.passedEvals}/${r.totalEvals} passed`,
-      r.costUSD === null ? MISSING : formatUSD(r.costUSD),
+    report.pages.map((page) => [
+      page.id,
+      localizeText(page.title, locale) ?? page.id,
+      showCommand({ ...command, page: page.id }),
     ]),
   );
   return `${head}\n\n${indentBlock(table, "  ")}`;
@@ -603,7 +619,7 @@ function execBody(
 /**
  * action / subagent 节点渲染成两行(call + result)——节点模型把 call+result 合并成一个
  * ExecutionNode(按 callId),但分两行读更符合「先看调用、再看结果」的阅读顺序,
- * 与 docs-site/zh/guides/agent-feedback-loop.mdx 的示例一致。
+ * 与 docs-site/zh/how-to/agent-feedback-loop.mdx 的示例一致。
  */
 function executionNodeLines(node: ExecutionNode, originMs: number, timingAvailable: boolean, width: number): string[] {
   const time = node.kind !== "telemetry" && node.span ? relSeconds(node.span.startMs, originMs) : undefined;
@@ -889,7 +905,7 @@ export function attemptOverviewText(
   const tail: string[] = [];
   if (artifactPath) tail.push(`artifacts: ${artifactPath}/`);
   const available = [
-    evidence.capabilities.eval ? `niceeval show ${evidence.locator} --eval` : undefined,
+    evidence.capabilities.source ? `niceeval show ${evidence.locator} --source` : undefined,
     evidence.capabilities.execution ? `niceeval show ${evidence.locator} --execution` : undefined,
     evidence.capabilities.timing ? `niceeval show ${evidence.locator} --timing` : undefined,
     evidence.capabilities.diff ? `niceeval show ${evidence.locator} --diff` : undefined,

package/src/show/report-host.test.ts

@@ -0,0 +1,188 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 「外壳、页面与 Tabs」——宿主装载规范化、页索引命令上下文与标题回退链
+// (契约:docs/feature/reports/library/shell.md)。
+// 页内树的 resolve / render 归报告库测试;这里只测宿主侧的规范化与选择逻辑(纯函数)。
+
+import { describe, expect, it } from "vitest";
+import {
+  BUILT_IN_PAGE_TITLE,
+  BUILT_IN_REPORT_TITLE,
+  HostReportError,
+  localizeText,
+  localizedTextEquals,
+  normalizeHostReport,
+  resolveReportTitle,
+  showCommand,
+} from "./report-host.ts";
+import { pageIndexText } from "./render.ts";
+
+const tree = { kind: "node" }; // 页 content 对宿主是不透明值,规范化不解析树
+
+describe("装载规范化:外壳 + 非空页列表", () => {
+  it("content 缩写展开为唯一页 id `report`,页名是内置页名「报告 / Report」", () => {
+    const report = normalizeHostReport({ kind: "report", content: tree }, "reports/frontier.tsx");
+    expect(report.pages).toHaveLength(1);
+    expect(report.pages[0]).toMatchObject({ id: "report", title: BUILT_IN_PAGE_TITLE, content: tree });
+    expect(report.links).toEqual([]);
+  });
+
+  it("pages 形态按声明序保留页列表与外壳字段", () => {
+    const report = normalizeHostReport(
+      {
+        kind: "report",
+        title: { en: "Memory Evals", "zh-CN": "记忆能力评测" },
+        links: [{ label: "GitHub", href: "https://example.com" }],
+        footer: "Published nightly.",
+        pages: [
+          { id: "overview", title: { en: "Overview", "zh-CN": "总览" }, content: tree },
+          { id: "exam", title: { en: "Exam", "zh-CN": "成绩单" }, content: tree },
+        ],
+      },
+      "reports/site.tsx",
+    );
+    expect(report.pages.map((p) => p.id)).toEqual(["overview", "exam"]);
+    expect(report.title).toEqual({ en: "Memory Evals", "zh-CN": "记忆能力评测" });
+    expect(report.footer).toBe("Published nightly.");
+  });
+
+  it("content 与 pages 恰好声明一个:同给 / 同缺都报错,文案给出 <ExperimentComparison /> 下一步", () => {
+    for (const bad of [
+      { kind: "report", content: tree, pages: [{ id: "a", title: "A", content: tree }] },
+      { kind: "report", title: "T" },
+    ]) {
+      expect(() => normalizeHostReport(bad, "reports/site.tsx")).toThrow(HostReportError);
+      expect(() => normalizeHostReport(bad, "reports/site.tsx")).toThrow(/<ExperimentComparison \/>/);
+    }
+  });
+
+  it("空 pages 列表 / 重复 page id / 非法 page id 在装载期报错", () => {
+    expect(() => normalizeHostReport({ kind: "report", pages: [] }, "r.tsx")).toThrow(/non-empty/);
+    expect(() =>
+      normalizeHostReport(
+        { kind: "report", pages: [{ id: "exam", title: "A", content: tree }, { id: "exam", title: "B", content: tree }] },
+        "r.tsx",
+      ),
+    ).toThrow(/duplicate page id "exam"/);
+    for (const id of ["Exam", "a/b"]) {
+      expect(() =>
+        normalizeHostReport({ kind: "report", pages: [{ id, title: "A", content: tree }] }, "r.tsx"),
+      ).toThrow(/invalid/);
+    }
+  });
+
+  it("默认导出不是 defineReport 产物:完整用户反馈", () => {
+    expect(() => normalizeHostReport({ some: "object" }, "reports/bad.tsx")).toThrow(
+      /does not default-export a report/,
+    );
+  });
+
+  it("ReportLink.icon 是 { svg: string }:合法形状原样透传;无类型 JS 传其它形状装载报错", () => {
+    const svg = '<svg viewBox="0 0 16 16"><path d="M0 0h16v16z"/></svg>';
+    const report = normalizeHostReport(
+      { kind: "report", content: tree, links: [{ label: "GitHub", href: "https://example.com", icon: { svg } }] },
+      "reports/site.tsx",
+    );
+    expect(report.links[0]!.icon).toEqual({ svg });
+
+    // ReactNode / 组件 / 裸字符串都不是 { svg: string },装载期以完整用户反馈拒绝。
+    const reactNode = { $$typeof: Symbol.for("react.transitional.element"), type: "svg", props: {} };
+    for (const icon of [reactNode, "<svg/>", { svg: 42 }, { svg: "" }]) {
+      expect(() =>
+        normalizeHostReport(
+          { kind: "report", content: tree, links: [{ label: "GitHub", href: "https://example.com", icon }] },
+          "reports/site.tsx",
+        ),
+      ).toThrow(/icon" must be \{ svg: string \}/);
+    }
+  });
+
+  it("旧 build 函数形态(集成前桥接)恒为单页 report", () => {
+    const legacy = { build: () => tree };
+    const report = normalizeHostReport(legacy, "the built-in report");
+    expect(report.pages.map((p) => p.id)).toEqual(["report"]);
+    expect(report.pages[0]!.content).toBe(legacy);
+  });
+});
+
+describe("标题回退链:def.title → 唯一且相同的快照 name → 内置文案「Eval 运行结果 / Eval Results」", () => {
+  it("def.title 优先", () => {
+    expect(resolveReportTitle({ en: "T" }, [{ name: "S" }])).toEqual({ en: "T" });
+  });
+
+  it("无 def.title 时取 Scope 中唯一且相同(深相等,键顺序无关)的非空快照 name", () => {
+    expect(resolveReportTitle(undefined, [{ name: { en: "S", "zh-CN": "斯" } }, { name: { "zh-CN": "斯", en: "S" } }]))
+      .toEqual({ en: "S", "zh-CN": "斯" });
+    expect(resolveReportTitle(undefined, [{}, { name: "Only" }])).toBe("Only");
+  });
+
+  it("多个不同 name(en 相同、zh-CN 不同也算不同)不随机挑,落内置文案;全无 name 亦然", () => {
+    expect(
+      resolveReportTitle(undefined, [{ name: { en: "S", "zh-CN": "甲" } }, { name: { en: "S", "zh-CN": "乙" } }]),
+    ).toEqual(BUILT_IN_REPORT_TITLE);
+    expect(resolveReportTitle(undefined, [{}, {}])).toEqual(BUILT_IN_REPORT_TITLE);
+    expect(resolveReportTitle("", [])).toEqual(BUILT_IN_REPORT_TITLE); // 空串标题不算声明
+    // 链终点是内置文案(shell.md),不是产品名——品牌位固定 NiceEval,不吃标题。
+    expect(BUILT_IN_REPORT_TITLE).toEqual({ en: "Eval Results", "zh-CN": "Eval 运行结果" });
+  });
+
+  it("LocalizedText 深相等按字段值,不看键顺序", () => {
+    expect(localizedTextEquals({ a: "1", b: "2" }, { b: "2", a: "1" })).toBe(true);
+    expect(localizedTextEquals({ a: "1" }, { a: "1", b: "2" })).toBe(false);
+  });
+});
+
+describe("LocalizedText 回退:locale → en → 键字典序第一个非空值", () => {
+  it("三级回退各自命中", () => {
+    expect(localizeText({ "zh-CN": "中", en: "E" }, "zh-CN")).toBe("中");
+    expect(localizeText({ "zh-CN": "中", en: "E" }, "fr")).toBe("E");
+    expect(localizeText({ "zh-TW": "繁", ja: "日" }, "en")).toBe("日"); // ja < zh-TW 字典序
+    expect(localizeText("plain", "en")).toBe("plain");
+    expect(localizeText({}, "en")).toBeUndefined();
+  });
+});
+
+describe("页索引与索引命令上下文", () => {
+  const report = normalizeHostReport(
+    {
+      kind: "report",
+      title: { en: "Memory Evals", "zh-CN": "记忆能力评测" },
+      links: [{ label: "GitHub", href: "https://example.com", icon: { svg: "<svg data-mark></svg>" } }],
+      pages: [
+        { id: "overview", title: { en: "Overview", "zh-CN": "总览" }, content: tree },
+        { id: "exam", title: { en: "Exam", "zh-CN": "成绩单" }, content: tree },
+      ],
+    },
+    "reports/site.tsx",
+  );
+
+  it("索引命令保留当前 --results / --report 与位置参数,复制即可复现下一层视图", () => {
+    const text = pageIndexText({
+      report,
+      title: "记忆能力评测",
+      command: { patterns: [], results: "tmp/published-results", report: "reports/site.tsx" },
+      locale: "zh-CN",
+    });
+    expect(text).toContain("记忆能力评测 · 2 页");
+    expect(text).toContain("niceeval show --results tmp/published-results --report reports/site.tsx --page overview");
+    expect(text).toContain("niceeval show --results tmp/published-results --report reports/site.tsx --page exam");
+    expect(text).toContain("总览");
+    expect(text).toContain("成绩单");
+  });
+
+  it("show 不消费 links:页索引不含 icon svg 与 href(icon 是 web 面属性)", () => {
+    const text = pageIndexText({
+      report,
+      title: "Memory Evals",
+      command: { patterns: [] },
+      locale: "en",
+    });
+    expect(text).not.toContain("<svg");
+    expect(text).not.toContain("https://example.com");
+  });
+
+  it("showCommand 按序携带位置参数与 --experiment / --results / --report / --page", () => {
+    expect(
+      showCommand({ patterns: ["memory/swelancer"], experiment: "dev-e2b", report: "reports/site.tsx", page: "exam" }),
+    ).toBe("niceeval show memory/swelancer --experiment dev-e2b --report reports/site.tsx --page exam");
+  });
+});