niceeval 0.4.5 → 0.5.0

package/src/view/index.ts

@@ -1,29 +1,83 @@
 // 本地结果查看器入口:只做编排与对外导出。
-// 读取/版本判定在 loader.ts,聚合在 aggregate.ts,HTTP 与 HTML 烘焙在 server.ts,
-// server/前端共用的折叠口径、格式化与数据形状在 shared/。
+// 读取(openResults)与统计(官方计算函数)在 data.ts,HTTP 与 HTML 烘焙在 server.ts,
+// server/前端共用的数据契约在 shared/types.ts。
 
 import { copyFile, mkdir, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { loadSummaries, type ScanResult } from "./loader.ts";
+import { ViewInputError, loadViewScan, type ViewScan } from "./data.ts";
 import { renderHtml, type ViewOptions } from "./server.ts";
 
 export { startViewServer, type ViewOptions, type ViewServer } from "./server.ts";
 export {
   IncompatibleResultsError,
+  ViewInputError,
   incompatibleHint,
   incompatibleViewCommand,
   loadLatestResultsPerEval,
-  loadSummaries,
+  loadViewScan,
   type IncompatibleRun,
-  type ScanResult,
-  type SkippedRun,
-} from "./loader.ts";
+  type ViewScan,
+  type ViewScanOptions,
+} from "./data.ts";
+
+/**
+ * view 的位置参数语义(与 CLI 模型一致:位置参数选「看哪些 eval」):
+ * - 恰好一个位置参数且指向存在的文件 → 单文件模式(`niceeval view <summary.json>`),
+ *   不与 --run 或其它位置参数混用;
+ * - 指向存在的目录 → 报错直说:目录经 `--run <dir>` 递入,位置参数留给 eval id 前缀;
+ * - 其余 → eval id 前缀,收窄报告槽选集(经 show 同一套选集合成)。
+ */
+export function resolveViewInput(
+  cwd: string,
+  positionals: string[],
+  run?: string,
+): { input?: string; patterns: string[] } {
+  if (run !== undefined) {
+    const dir = resolve(cwd, run);
+    if (!existsSync(dir)) {
+      throw new ViewInputError(`Results directory not found: ${dir}`);
+    }
+  }
+  const kindOf = (p: string): "file" | "dir" | "pattern" => {
+    try {
+      const stat = statSync(resolve(cwd, p));
+      return stat.isFile() ? "file" : stat.isDirectory() ? "dir" : "pattern";
+    } catch {
+      return "pattern";
+    }
+  };
+  for (const p of positionals) {
+    const kind = kindOf(p);
+    if (kind === "dir") {
+      throw new ViewInputError(
+        `"${p}" is a directory. Pass results directories with --run (niceeval view --run ${p}); positional arguments select evals by id prefix.`,
+      );
+    }
+    if (kind !== "file") continue;
+    if (positionals.length > 1) {
+      throw new ViewInputError(
+        `"${p}" is a summary file, but more positional arguments were given. Single-file mode takes exactly one path: niceeval view ${p}`,
+      );
+    }
+    if (run !== undefined) {
+      throw new ViewInputError(
+        `"${p}" is a summary file and cannot be combined with --run. Pass either the file (niceeval view ${p}) or the results dir (niceeval view --run <dir>).`,
+      );
+    }
+    return { input: resolve(cwd, p), patterns: [] };
+  }
+  return {
+    ...(run !== undefined ? { input: resolve(cwd, run) } : {}),
+    patterns: positionals,
+  };
+}
 
 /**
  * 导出静态报告(--out):只有目录式一种形态。写 <dir>/index.html,并把前端会 fetch 的工件
  * (sources.json / events.json / trace.json)复制到 <dir>/artifact/<base>/——与本地
  * server 的 /artifact/<rel> 路由同一布局,整个目录扔给任何静态托管即是完整体验。
+ * 带 --report(opts.scan.report)时,报告页即首页的报告槽,证据室同站。
  * 单文件(*.html)导出已移除:代码/transcript/trace 视图依赖工件文件,单文件注定残缺,
  * 存在本身就在诱导用户导出一份看不了证据的报告(docs/view.md「静态导出」)。
  */
@@ -34,7 +88,7 @@ export async function buildView(opts: ViewOptions = {}): Promise<string> {
       `--out expects a directory, got "${opts.out}". Single-file HTML export was removed: code, transcript and trace views need artifact files next to the page. Export a directory instead (e.g. --out site) and serve it with any static host.`,
     );
   }
-  const scan = await loadSummaries(opts.input);
+  const scan = await loadViewScan(opts.input, opts.scan);
   await mkdir(out, { recursive: true });
   await writeFile(join(out, "index.html"), await renderHtml(scan), "utf-8");
   await copyFetchedArtifacts(scan, join(out, "artifact"));
@@ -45,7 +99,7 @@ export async function buildView(opts: ViewOptions = {}): Promise<string> {
 // 且 diff 可达上百 MB,带进静态导出只会拖垮部署体积。
 const FETCHED_ARTIFACTS = ["sources.json", "events.json", "trace.json"];
 
-async function copyFetchedArtifacts(scan: ScanResult, artifactRoot: string): Promise<void> {
+async function copyFetchedArtifacts(scan: ViewScan, artifactRoot: string): Promise<void> {
   for (const [base, srcDir] of scan.artifactDirs) {
     const destDir = join(artifactRoot, base);
     // 输入本身已经是导出布局(比如对着上次导出的目录重新生成 index.html)时不自拷。

package/src/view/server.ts

@@ -1,17 +1,18 @@
 // HTTP server 与静态资源:起本地 web、按需吐工件、把 viewData 烘焙进单个 HTML。
-// 数据读取在 loader.ts,聚合在 aggregate.ts;这里只管「怎么送到浏览器」。
+// 数据读取与统计在 data.ts(openResults + 官方计算函数);这里只管「怎么送到浏览器」。
 
 import { createServer, type Server } from "node:http";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { loadSummaries, viewRoot, type ScanResult } from "./loader.ts";
-import { buildViewData } from "./aggregate.ts";
+import { loadViewScan, viewRoot, type ViewScan, type ViewScanOptions } from "./data.ts";
 import { formatThrown } from "../util.ts";
 
 export interface ViewOptions {
   input?: string;
   out?: string;
   port?: number;
+  /** 报告槽的组合语义(位置前缀 / --experiment / --report),透传给 loadViewScan。 */
+  scan?: ViewScanOptions;
 }
 
 export interface ViewServer {
@@ -23,11 +24,15 @@ const TEMPLATE_PLACEHOLDERS = {
   styles: "<!-- __NICEEVAL_STYLES__ -->",
   appCode: "__NICEEVAL_APP_CODE__",
   viewData: "__NICEEVAL_VIEW_DATA_JSON__",
+  reportSlot: "<!-- __NICEEVAL_REPORT_SLOT__ -->",
 } as const;
 
 export async function startViewServer(opts: ViewOptions = {}): Promise<ViewServer> {
   const input = opts.input;
   const root = viewRoot(input);
+  // 数据装载先跑一遍:单文件模式指向读不了的报告、--report 装载失败、
+  // 前缀匹配不到,都要在起 server 前就失败并给出提示。
+  await loadViewScan(input, opts.scan);
   const server = createServer(async (req, res) => {
     try {
       const url = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -57,7 +62,9 @@ export async function startViewServer(opts: ViewOptions = {}): Promise<ViewServe
         "content-type": "text/html; charset=utf-8",
         "cache-control": "no-store",
       });
-      res.end(await renderHtml(await loadSummaries(input)));
+      // 每次请求现读现算,永远是盘上最新数据;--report 的报告文件变更同样在
+      // 下次请求整页重算(装载走 mtime cache-busting,见 report/load.ts)。
+      res.end(await renderHtml(await loadViewScan(input, opts.scan)));
     } catch (e) {
       res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
       res.end(formatThrown(e));
@@ -74,16 +81,31 @@ export async function startViewServer(opts: ViewOptions = {}): Promise<ViewServe
   };
 }
 
-/** 把 viewData(只含原始值与相对路径,不含宿主机绝对路径)和前端产物烘焙进单个 HTML。 */
-export async function renderHtml(scan: ScanResult): Promise<string> {
+/**
+ * 把 viewData(只含原始值与相对路径,不含宿主机绝对路径)和前端产物烘焙进单个 HTML。
+ * --report 在场时,报告 HTML 作为 <template id="niceeval-report"> 静态块烘在
+ * __NICEEVAL_VIEW_DATA__ 旁(零客户端 JS、不 hydrate,自定义组件的 <Style> 产物
+ * 已内联其中),并附官方组件样式(report/react/styles.css);前端只把这块摆进
+ * 报告槽位置,不解析。
+ */
+export async function renderHtml(scan: ViewScan): Promise<string> {
   const template = await readViewAsset("template.html");
   const styles = await readViewAsset("client-dist/app.css");
   const app = await readViewAsset("client-dist/app.js");
-  const viewData = buildViewData(scan);
+  const reportStyles =
+    scan.reportHtml !== undefined
+      ? await readFile(new URL("../report/react/styles.css", import.meta.url), "utf-8")
+      : undefined;
 
   return template
-    .replace(TEMPLATE_PLACEHOLDERS.styles, () => `<style>\n${styles}\n</style>`)
-    .replace(TEMPLATE_PLACEHOLDERS.viewData, () => JSON.stringify(viewData).replace(/</g, "\\u003c"))
+    .replace(
+      TEMPLATE_PLACEHOLDERS.styles,
+      () => `<style>\n${styles}\n</style>${reportStyles !== undefined ? `\n<style>\n${reportStyles}\n</style>` : ""}`,
+    )
+    .replace(TEMPLATE_PLACEHOLDERS.reportSlot, () =>
+      scan.reportHtml !== undefined ? `<template id="niceeval-report">${scan.reportHtml}</template>` : "",
+    )
+    .replace(TEMPLATE_PLACEHOLDERS.viewData, () => JSON.stringify(scan.viewData).replace(/</g, "\\u003c"))
     .replace(TEMPLATE_PLACEHOLDERS.appCode, () => JSON.stringify(app).replace(/</g, "\\u003c"));
 }
 

package/src/view/shared/types.ts

@@ -1,56 +1,59 @@
-// server(aggregate/loader)与前端(app/)共用的 view 数据形状。
+// server(data.ts)与前端(app/)共用的 view 数据形状。
 // viewData 会被序列化进静态 HTML,两边必须对同一份声明编程;只允许 type import。
+//
+// 统计层收编后(docs/view.md「用 Reports 积木重建 view」迁移顺序 2),烘进 HTML 的不再是
+// 私有 rows,而是官方数据契约:OverviewData / TableData(niceeval/report 的计算函数产物)
+// + 快照元信息(证据室数据)+ skipped / warnings。前端只做渲染与展示态交互,不再聚合。
 
-import type { EvalResult, LocalizedText, Usage } from "../../types.ts";
+import type { EvalResult, LocalizedText } from "../../types.ts";
+import type { OverviewData, TableData } from "../../report/types.ts";
+
+// 官方契约的类型再导出(全部 type-only,前端打包时被擦除)。
+export type { MetricCell, MetricColumn, OverviewData, SelectionWarning, TableData } from "../../report/types.ts";
 
 /**
- * attempt 的深链身份:run 目录(相对 view 输入根,通常就是 `.niceeval/` 下的时间戳目录名)
- * + 该 attempt 在 summary.results 里的下标。`#/attempt/<run>/<result>` 路由的参数——
- * 报告页(前门)与 view(证据室)靠这份契约指向同一个 attempt,见 docs/view.md「用 Reports 积木重建 view」。
+ * attempt 的深链身份:run 目录名 + 该 attempt 在 summary.results 里的下标。
+ * `#/attempt/<run>/<result>` 路由的参数——与 niceeval/results 的 AttemptRef、Reports 的
+ * MetricCell.refs 同一身份契约,报告页(前门)与 view(证据室)靠它指向同一个 attempt。
  */
 export interface AttemptRef {
   run: string;
   result: number;
 }
 
-/** view 侧的 attempt 结果 = 瘦身后的 EvalResult + loadSummaries 注入的深链身份。 */
+/** view 侧的 attempt 结果 = 瘦身后的 EvalResult + loader 注入的深链身份与工件基址。 */
 export type ViewEvalResult = EvalResult & { attemptRef?: AttemptRef };
 
-/** 榜单一行 = 一个实验(或 legacy 的 agent×model 组合),跨全部历史 run 聚合。 */
-export interface ViewRow {
-  key: string;
-  experimentId?: string;
-  experiment?: EvalResult["experiment"];
-  group?: string;
-  label: string;
+/**
+ * 快照 = 单次跑的实验(experiment × run 切片),与 niceeval/results 的 Snapshot 同口径。
+ * 携带 attempt 明细供证据室(钻取 / AttemptModal / Runs / Traces)渲染;
+ * 榜单统计不从这里算,吃 ViewData.table / overview 的官方产物。
+ */
+export interface ViewSnapshot {
+  /** 落盘缺 experimentId 时是 "<agent>/<model>" 合成键(synthetic: true 同源)。 */
+  experimentId: string;
+  synthetic?: boolean;
   agent: string;
   model?: string;
-  /** 总 attempt 数(详情里作次要信息)。 */
-  runs: number;
-  /** 去重后的 eval 数(成功率分母的口径)。 */
-  evals: number;
-  passed: number;
-  failed: number;
-  errored: number;
-  skipped: number;
-  scored?: number;
-  passRate: number;
-  avgDurationMs: number;
-  usage: Usage;
-  estimatedCostUSD?: number;
-  /** 该实验组里最新一次 run 的 startedAt(ISO);详情展示「运行时间」。 */
-  lastRunAt?: string;
+  startedAt: string;
+  /** 物理 run 目录名(= AttemptRef.run)。 */
+  run: string;
+  /** 是否该实验最新一次快照 —— 榜单(results.latest() 口径)的成员。 */
+  latest: boolean;
+  /** 该快照的 attempt 明细(跨快照去重后的幸存条目;attemptRef / artifactBase 已注入)。 */
   results: ViewEvalResult[];
 }
 
-/** 目录扫描里被跳过的 run 在页面顶部的提示条目。 */
+/** 目录扫描里被跳过的 run 在页面顶部的提示条目;三种原因与 niceeval/results 的 skipped 一致。 */
 export interface SkippedRunNotice {
-  /** run 目录(summary.json 所在目录),相对 cwd。 */
+  /** run 目录,相对 cwd。 */
   dir: string;
-  reason: "incompatible-version" | "malformed";
+  reason: "incompatible-version" | "malformed" | "incomplete";
   schemaVersion?: number;
+  /** 完整 producer:只有 name === "niceeval" 才配得出 npx 命令,第三方 harness 如实报名字。 */
+  producerName?: string;
   producerVersion?: string;
-  /** incompatible-version:服务端拼好的查看命令(npx niceeval@<version> view <dir>)。 */
+  /** incompatible-version 且 producer 是 niceeval:服务端拼好的查看命令。 */
   command?: string;
   /** malformed:一句诊断(invalid JSON / results 不是数组 …)。 */
   detail?: string;
@@ -58,20 +61,23 @@ export interface SkippedRunNotice {
 
 /**
  * 烘焙进 HTML 的页面数据。时间/比率/成本一律传原始值(ISO 字符串、number),
- * 格式化统一由前端按当前界面 locale 做,server 不预格式化。
+ * 格式化统一由前端按当前界面 locale 做;官方 MetricCell 自带 display,前端直接渲染。
  */
 export interface ViewData {
-  rows?: ViewRow[];
   /** 项目名(来自 config.name);hero 标题,可按 locale 多语言。 */
   name?: LocalizedText;
   /** 最近一次 run 的 startedAt(ISO);没有历史 run 时缺省。 */
   lastRunAt?: string;
-  /** 0–1 的通过率。 */
-  passRate: number;
-  /** 去重后的 eval 结果数。 */
-  resultCount: number;
-  durationMs: number;
-  estimatedCostUSD?: number;
-  /** 读不了 / 版本不同而被跳过的 run;前端顶部横幅展示。 */
+  /** 榜单合成自几个物理 run(latest 选集覆盖的 run 数);表头「合成来源」标注。 */
+  composedRuns: number;
+  /** 官方 KPI(RunOverview.data 产物):totals + 选中快照元信息 + 选集 warnings 随行。 */
+  overview: OverviewData;
+  /** 官方榜单(MetricTable.data,rows: "experiment"):每个实验最新一次快照的口径。 */
+  table: TableData;
+  /** 整体单行(MetricTable.data,常量维度):hero 的官方通过率,同一台聚合引擎。 */
+  overall: TableData;
+  /** 全部历史快照(跨快照按身份键去重后);Experiments 钻取吃 latest,Runs / Traces 吃全部。 */
+  snapshots: ViewSnapshot[];
+  /** 读不了的落盘(三种原因);前端顶部横幅展示,不静默。 */
   skippedRuns?: SkippedRunNotice[];
 }

package/src/view/styles.css

@@ -146,6 +146,11 @@ h1 {
   font-size: 14px;
 }
 .meta b { color: var(--text); font-weight: 570; }
+/* --report 报告槽:server 侧渲染好的静态报告 HTML(nre-* 类的样式随包 styles.css 注入),
+   这里只给槽位留呼吸空间,不覆盖报告自己的样式。 */
+.report-slot {
+  margin: 0 auto 36px;
+}
 .summary {
   display: grid;
   grid-template-columns: repeat(4, minmax(0, 1fr));

package/src/view/template.html

@@ -9,6 +9,7 @@
 </head>
 <body>
   <div id="root"></div>
+  <!-- __NICEEVAL_REPORT_SLOT__ -->
   <script>new Function(__NICEEVAL_APP_CODE__)();</script>
 </body>
 </html>

package/src/view/view-report.test.ts

@@ -0,0 +1,308 @@
+// niceeval view 的 --report 报告槽与宿主组合语义(docs/reports.md「宿主输入的组合语义」
+// 与裁决记录 6;公开行为准绳 docs-site/zh/guides/viewing-results.mdx / custom-reports.mdx)。
+// 覆盖:
+// - 组合语义与 show 对齐:位置前缀收窄报告槽选集、--experiment 过滤、匹配不到直说;
+// - 单文件模式共存:存在的文件路径 → 单文件模式,目录报错直说走 --run,其余按 eval 前缀;
+// - 报告槽整槽替换:报告 HTML(含 <Style> 产物与证据室深链)烘进静态块,证据室数据原样保留;
+// - --out 静态导出:index.html 含报告块与官方样式,报告 HTML 零 <script>;
+// - dev server 装载语义:报告文件变更 → 下次装载整页重算(mtime cache-busting)。
+
+import { mkdir, mkdtemp, readFile, rm, utimes, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ReportLoadError } from "../report/load.ts";
+import { ViewInputError, loadViewScan } from "./data.ts";
+import { buildView, resolveViewInput } from "./index.ts";
+import { runShow } from "../show/index.ts";
+import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type RunSummary } from "../types.ts";
+
+const EXAM_REPORT = resolve(__dirname, "../../test/fixtures/report/exam-report.tsx");
+
+const roots: string[] = [];
+async function makeRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "niceeval-viewreport-"));
+  roots.push(root);
+  return root;
+}
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((r) => rm(r, { recursive: true, force: true })));
+});
+
+function res(over: Partial<EvalResult> & Pick<EvalResult, "id">): EvalResult {
+  return { agent: "bub", outcome: "passed", attempt: 0, durationMs: 1000, assertions: [], ...over };
+}
+
+function summaryOf(results: EvalResult[], over: Partial<RunSummary> = {}): RunSummary {
+  const count = (o: EvalResult["outcome"]) => results.filter((r) => r.outcome === o).length;
+  return {
+    format: RESULTS_FORMAT,
+    schemaVersion: RESULTS_SCHEMA_VERSION,
+    producer: { name: "niceeval", version: "0.4.6" },
+    agent: results[0]?.agent ?? "bub",
+    startedAt: "2026-07-08T10:00:00.000Z",
+    completedAt: "2026-07-08T10:10:00.000Z",
+    passed: count("passed"),
+    failed: count("failed"),
+    skipped: count("skipped"),
+    errored: count("errored"),
+    durationMs: 60_000,
+    results,
+    ...over,
+  };
+}
+
+async function writeRun(root: string, dirName: string, summary: RunSummary): Promise<string> {
+  const dir = join(root, dirName);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
+  return dir;
+}
+
+/** 两个实验、weather 通过 + button 失败:报告槽/证据室/深链断言都要用到失败案例。 */
+async function seedRoot(): Promise<string> {
+  const root = await makeRoot();
+  await writeRun(
+    root,
+    "2026-07-08T10-00-00-000Z",
+    summaryOf(
+      [
+        res({ id: "weather/brooklyn", experimentId: "compare/bub", startedAt: "2026-07-08T10:00:01.000Z" }),
+        res({
+          id: "fixtures/button",
+          experimentId: "compare/bub",
+          outcome: "failed",
+          startedAt: "2026-07-08T10:00:02.000Z",
+          assertions: [
+            { name: 'fileChanged("Button.tsx")', severity: "gate", score: 0, passed: false },
+          ],
+        }),
+      ],
+      { startedAt: "2026-07-08T10:00:00.000Z" },
+    ),
+  );
+  await writeRun(
+    root,
+    "2026-07-09T10-00-00-000Z",
+    summaryOf(
+      [res({ id: "weather/brooklyn", experimentId: "compare/codex", agent: "codex", startedAt: "2026-07-09T10:00:01.000Z" })],
+      { agent: "codex", startedAt: "2026-07-09T10:00:00.000Z" },
+    ),
+  );
+  return root;
+}
+
+// ───────────────────────── 位置参数语义(单文件模式共存) ─────────────────────────
+
+describe("resolveViewInput · 位置参数语义", () => {
+  it("存在的文件路径 → 单文件模式;其余位置参数按 eval id 前缀", async () => {
+    const root = await seedRoot();
+    const file = join(root, "2026-07-08T10-00-00-000Z", "summary.json");
+    expect(resolveViewInput(root, [file])).toEqual({ input: file, patterns: [] });
+    expect(resolveViewInput(root, ["weather", "fixtures/button"])).toEqual({
+      patterns: ["weather", "fixtures/button"],
+    });
+    expect(resolveViewInput(root, [])).toEqual({ patterns: [] });
+  });
+
+  it("目录位置参数:报错直说走 --run(位置参数留给 eval id 前缀)", async () => {
+    const root = await seedRoot();
+    expect(() => resolveViewInput(root, ["2026-07-08T10-00-00-000Z"])).toThrow(ViewInputError);
+    expect(() => resolveViewInput(root, ["2026-07-08T10-00-00-000Z"])).toThrow(/--run/);
+  });
+
+  it("单文件模式不与其它位置参数或 --run 混用,歧义报错直说", async () => {
+    const root = await seedRoot();
+    const file = join(root, "2026-07-08T10-00-00-000Z", "summary.json");
+    expect(() => resolveViewInput(root, [file, "weather"])).toThrow(/exactly one path/);
+    expect(() => resolveViewInput(root, [file], root)).toThrow(/--run/);
+  });
+
+  it("--run 指向不存在的目录:直说", async () => {
+    const root = await seedRoot();
+    expect(() => resolveViewInput(root, [], join(root, "nope"))).toThrow(/Results directory not found/);
+  });
+
+  it("--run 换结果根,位置参数仍是前缀", async () => {
+    const root = await seedRoot();
+    expect(resolveViewInput("/elsewhere", ["weather"], root)).toEqual({ input: root, patterns: ["weather"] });
+  });
+});
+
+// ───────────────────────── 组合语义(与 show 对齐) ─────────────────────────
+
+describe("loadViewScan · 组合语义", () => {
+  it("位置前缀收窄报告槽选集(榜单/overview);证据室快照不收窄,深链恒可达", async () => {
+    const root = await seedRoot();
+    const { viewData } = await loadViewScan(root, { patterns: ["weather"] });
+    // 报告槽:两实验都只剩 weather/brooklyn 一题,全过。
+    expect(viewData.overview.totals.evals).toBe(1);
+    expect(viewData.overview.totals.attempts).toBe(2); // 2 个实验各 1 attempt
+    for (const row of viewData.table.rows) {
+      expect(row.cells["pass-rate"]!.value).toBe(1);
+    }
+    // 证据室:快照明细仍含 fixtures/button(attempt 深链在收窄下也能解析)。
+    const allIds = viewData.snapshots.flatMap((s) => s.results.map((r) => r.id));
+    expect(allIds).toContain("fixtures/button");
+  });
+
+  it("--experiment 过滤:选集只留该实验", async () => {
+    const root = await seedRoot();
+    const { viewData } = await loadViewScan(root, { experiment: "compare/codex" });
+    expect(viewData.table.rows.map((r) => r.key)).toEqual(["compare/codex"]);
+  });
+
+  it("前缀/实验匹配不到:直说,不渲染空页面", async () => {
+    const root = await seedRoot();
+    await expect(loadViewScan(root, { patterns: ["nosuch"] })).rejects.toBeInstanceOf(ViewInputError);
+    await expect(loadViewScan(root, { patterns: ["nosuch"] })).rejects.toThrow(/weather\/brooklyn/);
+    await expect(loadViewScan(root, { experiment: "nosuch" })).rejects.toBeInstanceOf(ViewInputError);
+  });
+
+  it("全部缺省:默认行为不变(results.latest() 口径,不走合成)", async () => {
+    const root = await seedRoot();
+    const { viewData, reportHtml } = await loadViewScan(root);
+    expect(reportHtml).toBeUndefined();
+    expect(viewData.table.rows.map((r) => r.key).sort()).toEqual(["compare/bub", "compare/codex"]);
+  });
+});
+
+// ───────────────────────── 报告槽整槽替换 ─────────────────────────
+
+describe("loadViewScan · --report 报告槽", () => {
+  it("报告树渲染为静态 HTML:官方水位 + 自定义摆法 + <Style> 产物 + 证据室深链,零 <script>", async () => {
+    const root = await seedRoot();
+    const scan = await loadViewScan(root, { report: { path: EXAM_REPORT, cwd: root } });
+    const html = scan.reportHtml!;
+    expect(html).toContain("考试成绩单"); // 自定义 Section
+    expect(html).toContain("nre-"); // 官方组件的稳定类名
+    expect(html).toContain("<style>.exam-note { color: #4a7; }</style>"); // <Style> 随树带走
+    expect(html).toContain("#/attempt/2026-07-08T10-00-00-000Z/"); // 失败案例深链进证据室
+    expect(html).not.toContain("<script"); // 报告槽产物零客户端 JS,不 hydrate
+    // 证据室数据契约(__NICEEVAL_VIEW_DATA__)原样保留:快照、attemptRef、skipped 不动。
+    expect(scan.viewData.snapshots.length).toBeGreaterThan(0);
+    expect(scan.viewData.snapshots.flatMap((s) => s.results).every((r) => r.attemptRef)).toBe(true);
+    expect(JSON.stringify(scan.viewData)).not.toContain("考试成绩单"); // 报告块不进 viewData
+  });
+
+  it("位置前缀对 --report 生效:收窄注入选集,报告只见范围内的 eval", async () => {
+    const root = await seedRoot();
+    const scan = await loadViewScan(root, {
+      patterns: ["weather"],
+      report: { path: EXAM_REPORT, cwd: root },
+    });
+    // 范围外的失败(fixtures/button)不再出现在报告里;范围内的实验行都在。
+    expect(scan.reportHtml).not.toContain("fixtures/button");
+    expect(scan.reportHtml).toContain("compare/bub");
+    expect(scan.reportHtml).toContain("compare/codex");
+  });
+
+  it("show --report 与 view --report 吃同一个报告文件,判决口径一致", async () => {
+    const root = await seedRoot();
+    let text = "";
+    const code = await runShow(root, [], { run: root, report: EXAM_REPORT }, {
+      out: (s) => (text += s),
+      err: () => {},
+      width: 120,
+    });
+    expect(code).toBe(0);
+    const scan = await loadViewScan(root, { report: { path: EXAM_REPORT, cwd: root } });
+    // 同一棵树的两个面:同一份失败清单与同一个自定义 Section。
+    for (const needle of ["考试成绩单", "compare/bub", "compare/codex", "fixtures/button"]) {
+      expect(text).toContain(needle);
+      expect(scan.reportHtml).toContain(needle);
+    }
+  });
+
+  it("报告文件缺失 / 默认导出不是 defineReport 产物:ReportLoadError 直说", async () => {
+    const root = await seedRoot();
+    await expect(
+      loadViewScan(root, { report: { path: join(root, "missing.tsx"), cwd: root } }),
+    ).rejects.toBeInstanceOf(ReportLoadError);
+    const bad = join(root, "bad.mjs");
+    await writeFile(bad, "export default {};\n", "utf-8");
+    await expect(loadViewScan(root, { report: { path: bad, cwd: root } })).rejects.toThrow(
+      /does not default-export a report/,
+    );
+  });
+});
+
+// ───────────────────────── dev server 装载语义:整页重算 ─────────────────────────
+
+describe("loadViewScan · 报告文件变更整页重算", () => {
+  /** 不经包入口也合法的最小报告(与 show.test.ts 同一姿势):写 tmp .mjs 才能改内容重载。 */
+  function reportSource(marker: string): string {
+    return [
+      'const FACES = Symbol.for("niceeval.report.faces");',
+      "const Block = (props) => Block[FACES].web(props);",
+      "Block[FACES] = {",
+      `  web: () => "${marker}",`,
+      `  text: () => "${marker}",`,
+      "};",
+      "export default {",
+      '  [Symbol.for("niceeval.report.definition")]: true,',
+      "  build: () => ({",
+      '    $$typeof: Symbol.for("react.transitional.element"),',
+      "    type: Block,",
+      "    props: {},",
+      "    key: null,",
+      "  }),",
+      "};",
+      "",
+    ].join("\n");
+  }
+
+  it("重写报告文件后,下一次装载渲染新内容(mtime cache-busting)", async () => {
+    const root = await seedRoot();
+    const path = join(root, "report.mjs");
+    await writeFile(path, reportSource("FIRST_RENDER"), "utf-8");
+    const first = await loadViewScan(root, { report: { path, cwd: root } });
+    expect(first.reportHtml).toContain("FIRST_RENDER");
+
+    await writeFile(path, reportSource("SECOND_RENDER"), "utf-8");
+    // mtime 精度兜底:显式把 mtime 拨到未来,确保与首次装载可区分。
+    const future = new Date(Date.now() + 5000);
+    await utimes(path, future, future);
+    const second = await loadViewScan(root, { report: { path, cwd: root } });
+    expect(second.reportHtml).toContain("SECOND_RENDER");
+    expect(second.reportHtml).not.toContain("FIRST_RENDER");
+  });
+});
+
+// ───────────────────────── --out 静态导出 ─────────────────────────
+
+describe("buildView · --out 与 --report", () => {
+  it("报告页为首页报告槽,证据室同站:index.html 含报告块与官方样式,工件照常复制", async () => {
+    const root = await seedRoot();
+    // 给 weather attempt 一份 events 工件,验证证据室工件照常进导出。
+    const artifactDir = join(root, "2026-07-09T10-00-00-000Z", "artifacts", "weather");
+    await mkdir(artifactDir, { recursive: true });
+    await writeFile(join(artifactDir, "events.json"), "[]", "utf-8");
+    const summaryPath = join(root, "2026-07-09T10-00-00-000Z", "summary.json");
+    const summary = JSON.parse(await readFile(summaryPath, "utf-8")) as RunSummary;
+    summary.results[0]!.artifactsDir = "artifacts/weather";
+    await writeFile(summaryPath, JSON.stringify(summary), "utf-8");
+
+    const out = join(root, "site");
+    await buildView({ input: root, out, scan: { report: { path: EXAM_REPORT, cwd: root } } });
+
+    const html = await readFile(join(out, "index.html"), "utf-8");
+    expect(html).toContain('<template id="niceeval-report">');
+    expect(html).toContain("考试成绩单");
+    expect(html).toContain("nre-"); // 官方组件样式(report/react/styles.css)随页注入
+    // 报告块本体零 <script>:静态块起于 <template>,内部只有标记与 <style>。
+    const block = html.split('<template id="niceeval-report">')[1]!.split("</template>")[0]!;
+    expect(block).not.toContain("<script");
+    // 证据室同站:工件按 /artifact/<base>/ 布局复制。
+    expect(existsSync(join(out, "artifact", "2026-07-09T10-00-00-000Z/artifacts/weather", "events.json"))).toBe(true);
+  });
+
+  it("默认导出(无 --report)不含报告块,行为不变", async () => {
+    const root = await seedRoot();
+    const out = join(root, "site");
+    await buildView({ input: root, out });
+    const html = await readFile(join(out, "index.html"), "utf-8");
+    expect(html).not.toContain('<template id="niceeval-report">');
+  });
+});