niceeval 0.5.4 → 0.6.0

package/src/view/data.ts

@@ -1,30 +1,25 @@
-// view 的数据层:读取经 niceeval/results 的 openResults(布局/版本知识只住在那),
-// 统计经 niceeval/report 的官方计算函数(RunOverview.data / MetricTable.data 的实现,
-// 从 compute.ts 直接引用 —— 调用侧适配,不经 components.tsx,避免把 react 拉进 CLI 路径)。
-// 这里只做编排:挑选(results.latest();位置前缀 / --experiment / --report 在场时经
-// composeShowSelection 与 show 同口径合成)、快照明细注入(attemptRef / artifactBase)、
-// skipped / warnings 透传、--report 的报告槽渲染(renderReportSlot)。旧 loader
-// (readSummary / loadSummaries / 目录扫描 / 版本判定)与旧聚合(aggregateRows)已删,
-// 见 docs/view.md「用 Reports 积木重建 view」迁移顺序 1–2。
+// view 的数据层:读取经 niceeval/results 的 openResults(布局/版本知识只住在那)。
+// 这里只做编排:报告槽 Selection 恒经 selectCurrentResults(现刻水位;与 show 调同一个函数,
+// 两扇门判定不分叉)、快照明细注入(locator / artifactBase)、skipped 透传、报告槽渲染
+// (renderReportSlot:裸跑填充 CostPassRateComparison,--report 整槽替换,en / zh-CN 双语各渲染一遍)。
+// --report 只换报告定义,注入的 Selection 与裸跑同一份。统计口径整体住在报告槽里
+// (报告组件的官方计算函数),viewData 不再携带 overview / 榜单这类统计产物,
+// 见 docs/feature/reports/view.md「打开与收窄」。
 
 import { statSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { dedupeAttempts, openResults } from "../results/index.ts";
-import type { AttemptHandle, Results, RunDir, Selection, SkippedRun } from "../results/index.ts";
-import { overviewData, tableData } from "../report/compute.ts";
-import { costUSD, durationMs, passRate, tokens } from "../report/metrics.ts";
-import { loadReportFile } from "../report/load.ts";
-import { composeShowSelection, filterExperiments } from "../show/compose.ts";
-import type { EvalResult, RunSummary } from "../types.ts";
-import type { SkippedRunNotice, ViewData, ViewEvalResult, ViewSnapshot } from "./shared/types.ts";
+import type { AttemptHandle, Results, Selection, Snapshot, SkippedDir } from "../results/index.ts";
+// dist-sourced: ReportDefinition/ReportLoadError identity must match the built-ins/web.ts
+// module instance renderReportSlot() dynamically imports below (see its comment).
+import { loadReportFile } from "../../dist/report/load.js";
+import { selectCurrentResults, filterExperiments } from "../results/select.ts";
+import type { EvalResult } from "../types.ts";
+import type { ReportSlotHtml, SkippedRunNotice, ViewData, ViewEvalResult, ViewSnapshot } from "./shared/types.ts";
 import { t } from "../i18n/index.ts";
 import { RESULTS_SCHEMA_VERSION } from "../types.ts";
 
-/** 榜单列:官方内置指标,与 `niceeval show` 榜单同一批口径(通过率 / 耗时 / tokens / 成本)。 */
-const BOARD_COLUMNS = [passRate, durationMs, tokens, costUSD] as const;
-
-/** hero 整体通过率的常量维度:全部选中 attempt 一组,走同一台两级聚合引擎。 */
-const OVERALL_DIMENSION = { name: "overall", of: () => "all" } as const;
+export type { ReportSlotHtml } from "./shared/types.ts";
 
 export interface ViewScan {
   viewData: ViewData;
@@ -34,18 +29,26 @@ export interface ViewScan {
    */
   artifactDirs: Map<string, string>;
   /**
-   * --report:报告树经 renderReportToStaticHtml 渲染出的静态 HTML,整槽替换查看器的
-   * 报告槽。作为独立静态块烘进页面(与 __NICEEVAL_VIEW_DATA__ 相邻),不进 viewData ——
-   * 证据室沿用官方数据契约不动,前端只负责把这块 HTML 摆进报告槽位置,不解析。
+   * artifactBase → AttemptHandle。sources.json 在盘上是去重后的引用(`{path, sha256}[]`),
+   * 不能像其它 artifact 那样直接 copyFile / piping 原字节——必须经 `AttemptHandle.sources()`
+   * 解引用出完整内容(`{path, content}[]`)才能给浏览器用。这份索引专为那一种 artifact 的特判
+   * 准备(`copyFetchedArtifacts`),events.json / trace.json 仍走 `artifactDirs` 的原文件路径。
+   */
+  attemptsByBase: Map<string, AttemptHandle>;
+  /**
+   * 报告槽:报告树经 renderReportToStaticHtml 渲染出的静态 HTML(en / zh-CN 各一份),
+   * 裸跑填充内置默认报告 CostPassRateComparison,--report 整槽替换。作为两个 <template> 静态块
+   * 烘进页面(与 __NICEEVAL_VIEW_DATA__ 相邻),不进 viewData —— 前端只负责把当前
+   * 界面语言对应的那块 HTML 摆进报告槽位置,不解析。
    */
-  reportHtml?: string;
+  reportHtml: ReportSlotHtml;
 }
 
-/** view 宿主输入的组合语义(与 show 对齐,docs/reports.md「宿主输入的组合语义」)。 */
+/** view 宿主输入的组合语义(与 show 对齐,docs/feature/reports/architecture.md「Selection 是计算入口」)。 */
 export interface ViewScanOptions {
-  /** eval id 前缀(位置参数):收窄报告槽选集;证据室(快照明细)不收窄,深链恒可达。 */
+  /** eval id 前缀(位置参数):收窄报告槽 Selection;证据室(快照明细)不收窄,深链恒可达。 */
   patterns?: string[];
-  /** experiment id 前缀(--experiment):选集只留该实验。 */
+  /** experiment id 前缀(--experiment):Selection 只留该实验。 */
   experiment?: string;
   /** --report 报告文件:相对 cwd 的路径。装载失败抛 ReportLoadError(CLI 打印后退出)。 */
   report?: { path: string; cwd: string };
@@ -54,12 +57,12 @@ export interface ViewScanOptions {
 /** 可预期的用户输入错误:CLI 打一句英文直说问题与下一步,退出码 1,不抛堆栈。 */
 export class ViewInputError extends Error {}
 
-/** 版本不同、按设计直接不兼容的 run;只占位提示,不解析内容。 */
+/** 版本不同、按设计直接不兼容的落盘;只占位提示,不解析内容。 */
 export interface IncompatibleRun {
-  /** run 目录,相对 cwd;直接可拼进 npx 命令。 */
+  /** 快照目录,相对 cwd;直接可拼进 npx 命令。 */
   dir: string;
   schemaVersion: number;
-  producer?: RunSummary["producer"];
+  producer?: Snapshot["producer"];
 }
 
 /** 用能读这份报告的 niceeval 版本查看的命令;第三方 harness 的落盘拼不出 npx,返回 undefined。 */
@@ -72,7 +75,7 @@ export function incompatibleViewCommand(run: IncompatibleRun): string | undefine
 export function incompatibleHint(run: IncompatibleRun): string {
   const command = incompatibleViewCommand(run);
   if (command === undefined) {
-    // 第三方 harness:如实报名字和版本,不拼 npx(docs/results-lib.md 的裁决)。
+    // 第三方 harness:如实报名字和版本,不拼 npx(docs/feature/results/library.md 的裁决)。
     return t("cli.view.incompatibleForeign", {
       dir: run.dir,
       name: run.producer?.name ?? "?",
@@ -90,7 +93,7 @@ export function incompatibleHint(run: IncompatibleRun): string {
   });
 }
 
-/** 单文件模式读到版本不同的 summary 时抛出;CLI 捕获后打印提示退出,不当成普通错误堆栈。 */
+/** 单文件模式读到版本不同的 snapshot 时抛出;CLI 捕获后打印提示退出,不当成普通错误堆栈。 */
 export class IncompatibleResultsError extends Error {
   constructor(readonly run: IncompatibleRun) {
     super(incompatibleHint(run));
@@ -98,48 +101,61 @@ export class IncompatibleResultsError extends Error {
   }
 }
 
-/** 服务/解析工件的根目录:输入是目录就用它,是文件就用其所在目录。 */
+/**
+ * 服务/解析 artifact 的根目录:输入是目录就用它,是文件就上跳两层(snapshot.json 恒在
+ * `<root>/<experiment-dir>/<snapshot-dir>/snapshot.json`,root 是 AttemptRef.snapshot
+ * 两段路径的锚点)。
+ */
 export function viewRoot(input?: string): string {
   const target = resolve(input ?? ".niceeval");
   try {
-    return statSync(target).isFile() ? dirname(target) : target;
+    return statSync(target).isFile() ? dirname(dirname(target)) : target;
   } catch {
     return target;
   }
 }
 
+/** 携带条目 / 新算的 artifactBase:`result.artifactBase ?? `${ref.snapshot}/${ref.attempt}``(posix 拼接)。 */
+function withArtifactBase(attempt: AttemptHandle): EvalResult {
+  const r = attempt.result;
+  if (r.artifactBase !== undefined) return r;
+  return { ...r, artifactBase: `${attempt.ref.snapshot}/${attempt.ref.attempt}` };
+}
+
 /**
  * 读跨历史「每 (experimentId, evalId) 最新一份」的 EvalResult,供续跑携带已通过结果。
- * 只看最近一个 run 不行:部分补跑(位置参数只跑几道题)会把携带基线换成那个部分 run,
+ * 只看最近一个快照不行:部分补跑(位置参数只跑几道题)会把携带基线换成那个部分快照,
  * 之后重跑任何实验都携带不到东西,`exp <组>` 的「补齐缺失」语义随之失效。
- * 同一 (experimentId, evalId) 的多个 attempt 整批取自含它的最新 run,不跨 run 混装。
- * 携带条目要能被 view 找回工件,这里同时把 artifactBase(相对结果根)拼好(runner 依赖它)。
+ * 同一 (experimentId, evalId) 的多个 attempt 整批取自含它的最新快照,不跨快照混装。
+ * 携带条目要能被 view 找回 artifact,这里同时把 artifactBase(相对结果根)拼好(runner 依赖它)。
  */
 export async function loadLatestResultsPerEval(root = ".niceeval"): Promise<EvalResult[]> {
   const results = await openResults(root);
-  const rootAbs = resolve(root);
-  const claimed = new Set<string>();
   const out: EvalResult[] = [];
-  for (const run of results.runDirs) {
-    // runDirs 已按新→旧排序;同一 run 内先收本轮的 key,收完再整体入 claimed,
-    // 保证同 (experiment, eval) 的多 attempt 整批取自同一个 run。
-    const takenThisRun = new Set<string>();
-    for (const attempt of run.attempts) {
-      const key = `${attempt.experimentId}|${attempt.evalId}`;
-      if (claimed.has(key)) continue;
-      takenThisRun.add(key);
-      out.push(annotateResult(attempt, run, rootAbs).annotated);
+  for (const exp of results.experiments) {
+    // exp.snapshots 已按新→旧排序;同一快照内先收本轮的 eval id,收完再整体入 claimed,
+    // 保证同 (experiment, eval) 的多 attempt 整批取自同一个快照。
+    const claimed = new Set<string>();
+    for (const snapshot of exp.snapshots) {
+      const takenThisSnapshot = new Set<string>();
+      for (const ev of snapshot.evals) {
+        if (claimed.has(ev.id)) continue;
+        takenThisSnapshot.add(ev.id);
+        for (const attempt of ev.attempts) out.push(withArtifactBase(attempt));
+      }
+      for (const id of takenThisSnapshot) claimed.add(id);
     }
-    for (const key of takenThisRun) claimed.add(key);
   }
   return out;
 }
 
 /**
  * `niceeval view` 的数据装载入口:server 每次请求现读现算,`--out` 导出用同一份。
- * 位置前缀 / --experiment / --report 在场时,报告槽选集经 composeShowSelection 合成
- * (与 `niceeval show` 同一口径,两扇门判决不分叉);全部缺省时维持 results.latest(),
- * 默认行为不变。证据室数据(快照明细 / skipped)恒为全量,深链在任何收窄下都可达。
+ * 报告槽 Selection 恒经 selectCurrentResults 合成(现刻水位;与 `niceeval show` 调同一个
+ * 函数,裸跑与局部收窄不分叉),位置前缀 / --experiment 只作为 scope 传入,不切换选择口径。
+ * --report 本身不改挑选——它只换报告槽的填充,注入的 Selection 与裸跑同一份,
+ * 「裸跑 ≡ --report <CostPassRateComparison>」靠这条成立(docs/feature/reports/architecture.md「Selection 是计算入口」)。
+ * 证据室数据(快照明细 / skipped)恒为全量,深链在任何收窄下都可达。
  * 零可读结果一律抛 ViewInputError,不渲染/导出空页面(server 起不来,--out 非零退出)。
  */
 export async function loadViewScan(input?: string, opts: ViewScanOptions = {}): Promise<ViewScan> {
@@ -149,7 +165,6 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
   assertSingleFileReadable(results, target);
 
   const patterns = opts.patterns ?? [];
-  const narrowed = patterns.length > 0 || opts.experiment !== undefined || opts.report !== undefined;
 
   // 零可读结果直说,不渲染/导出一张空页面(与 show 的「匹配不到直说」同一原则;
   // CI 静态发布还靠这个非零退出保住上一次部署,空报告不顶上线)。零可读最常见的
@@ -170,10 +185,11 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
     );
   }
 
-  const baseSelection = results.latest();
-  const selection = narrowed
-    ? composeShowSelection(results, { experiment: opts.experiment, patterns })
-    : baseSelection;
+  // 报告槽 Selection:恒经现刻水位选择器合成,与 show 裸跑同口径(两扇门判定不分叉)。
+  const selection = selectCurrentResults(results, { experiment: opts.experiment, patterns });
+  // latestPerExperiment 只服务证据室 UI 的 latest 标记(ViewSnapshot.latest / viewData.snapshots),
+  // 与报告槽 Selection 完全无关,绝不复用为报告 Selection。
+  const latestPerExperiment = results.latest();
 
   if (patterns.length > 0 && selection.snapshots.every((s) => s.evals.length === 0)) {
     const known = [
@@ -184,23 +200,17 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
     );
   }
 
-  const [overview, table, overall] = [
-    await overviewData(selection),
-    await tableData(selection, { rows: "experiment", columns: BOARD_COLUMNS, sort: passRate }),
-    await tableData(selection, { rows: OVERALL_DIMENSION, columns: [passRate] }),
-  ];
+  // 报告槽:裸跑填充 CostPassRateComparison,--report 整槽替换。报告吃同一份注入 Selection,
+  // web 面在计算侧静态渲染成 HTML(en / zh-CN 各一遍,切界面语言不重算数据)。
+  const reportHtml = await renderReportSlot(opts.report, results, selection);
 
-  // --report:整槽替换。报告吃同一份注入选集,web 面在计算侧静态渲染成 HTML。
-  const reportHtml = opts.report
-    ? await renderReportSlot(opts.report, results, selection)
-    : undefined;
-
-  // 跨快照按身份键去重:--resume 携带的条目在多份落盘里重复,只保留最新 run 里的那份
+  // 跨快照按身份键去重:--resume 携带的条目在多份落盘里重复,只保留最新快照里的那份
   // (与官方计算函数的聚合口径一致,Runs / Traces 的计数因此不被复印件灌票)。
   const artifactDirs = new Map<string, string>();
+  const attemptsByBase = new Map<string, AttemptHandle>();
   // latest 标记恒按 results.latest() 口径打(ViewSnapshot.latest 的声明语义),
-  // 不随收窄后的合成选集漂移 —— 榜单行与快照的关联靠它成立。
-  const latestSet = new Set(baseSelection.snapshots);
+  // 与报告槽 Selection(现刻水位,可能合成自更早快照)是两个独立概念,不混用。
+  const latestSet = new Set(latestPerExperiment.snapshots);
   const allAttempts: AttemptHandle[] = [];
   for (const exp of results.experiments) {
     for (const snap of exp.snapshots) allAttempts.push(...snap.attempts);
@@ -216,59 +226,100 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
       if (kept.length === 0 && !latest) continue;
       snapshots.push({
         experimentId: snap.experimentId,
-        ...(snap.synthetic ? { synthetic: true } : {}),
         agent: snap.agent,
         ...(snap.model !== undefined ? { model: snap.model } : {}),
         startedAt: snap.startedAt,
-        run: basename(snap.runDir.dir),
+        // 与 reader 的 AttemptRef.snapshot 同一公式(祖父目录名/自身目录名),不依赖 root——
+        // 单文件模式的 root 是从目标文件上跳算出的,两条计算各自独立更不容易踩偏差。
+        run: `${basename(dirname(snap.dir))}/${basename(snap.dir)}`,
         latest,
         results: kept.map((a) => {
-          const { annotated, base, abs } = annotateResult(a, snap.runDir, root);
-          if (base && abs) artifactDirs.set(base, abs);
+          const { annotated, base, abs } = annotateResult(a, root);
+          artifactDirs.set(base, abs);
+          attemptsByBase.set(base, a);
           return annotated;
         }),
       });
     }
   }
 
-  const latestRun = results.runDirs[0];
+  // 全局最新快照(跨全部实验):hero 的项目名 / 最近一次运行时刻从这里取。
+  let latestSnapshot: Snapshot | undefined;
+  for (const exp of results.experiments) {
+    const candidate = exp.snapshots[0];
+    if (!candidate) continue;
+    if (!latestSnapshot || candidate.startedAt > latestSnapshot.startedAt) latestSnapshot = candidate;
+  }
+
   const viewData: ViewData = {
-    ...(latestRun?.summary.name !== undefined ? { name: latestRun.summary.name } : {}),
-    ...(latestRun ? { lastRunAt: latestRun.summary.startedAt } : {}),
-    // 合成选集的快照是跨 run 拼出来的,来源 run 数从 attempt 的 runDir 数;
-    // 默认选集(latest 口径)保持原表达式,行为不变。
-    composedRuns: narrowed
-      ? new Set(selection.snapshots.flatMap((s) => s.attempts.map((a) => a.runDir.dir))).size
-      : new Set(selection.snapshots.map((s) => s.runDir.dir)).size,
-    overview,
-    table,
-    overall,
+    ...(latestSnapshot?.name !== undefined ? { name: latestSnapshot.name } : {}),
+    ...(latestSnapshot ? { lastRunAt: latestSnapshot.startedAt } : {}),
+    // 合成 Selection 的快照是跨快照拼出来的,来源物理 run 数从 attempt 自己的 snapshot
+    // 反向引用取——每个 attempt 的 .snapshot 恒指向它真实所在的贡献快照(无论 Selection
+    // 是否合成),所以这条对裸跑与收窄一律成立,不需要分支。
+    composedRuns: new Set(selection.snapshots.flatMap((s) => s.attempts.map((a) => a.snapshot.dir))).size,
     snapshots,
     skippedRuns: results.skipped.map(toSkippedNotice),
   };
-  return { viewData, artifactDirs, ...(reportHtml !== undefined ? { reportHtml } : {}) };
+  return { viewData, artifactDirs, attemptsByBase, reportHtml };
 }
 
 /**
- * 报告槽渲染:装载报告文件(dev server 语义 —— 文件变更下次请求整页重算,经 mtime
- * cache-busting)→ 注入与默认报告同口径的选集 → web 面 renderToStaticMarkup 成静态 HTML。
- * react-dom 只在 --report 在场时动态加载,默认 CLI 路径不背 react。
- * attemptHref 缺省即 `#/attempt/<run>/<result>`(view 的 attempt 深链路由)。
+ * base(withArtifactBase 同一公式)→ AttemptHandle 的轻量索引,供 server.ts 的 artifact 路由
+ * 按 URL 反查 attempt——只有 sources.json 请求需要这份索引(其余 artifact 直接读盘文件更便宜),
+ * 所以特意不跑 loadViewScan 的全套 Selection 合成 + 报告双语渲染,只做一次 openResults() 扫描。
+ * 不做去重收窄:遍历全部落盘 attempt,同一 base 只可能来自同一份物理落盘,历史快照里被去重
+ * 吸走的重复条目 base 天然不同,不会冲突;不会被 UI 引用的 base 混进来也无害(纯查表,
+ * 从不主动枚举 key)。
+ */
+export async function loadAttemptIndex(input?: string): Promise<Map<string, AttemptHandle>> {
+  const target = resolve(input ?? ".niceeval");
+  const results = await openResults(target);
+  const index = new Map<string, AttemptHandle>();
+  for (const exp of results.experiments) {
+    for (const snap of exp.snapshots) {
+      for (const attempt of snap.attempts) {
+        index.set(withArtifactBase(attempt).artifactBase!, attempt);
+      }
+    }
+  }
+  return index;
+}
+
+/**
+ * 报告槽渲染:装载报告文件(--report;dev server 语义 —— 文件变更下次请求整页重算,
+ * 经 mtime cache-busting),缺省用内置默认报告 CostPassRateComparison → 注入 Selection →
+ * web 面 renderToStaticMarkup 成静态 HTML,en / zh-CN 各渲染一遍(chrome 文案按 locale)。
+ * react / react-dom 动态加载:data.ts 还被 runner 的续跑携带(loadLatestResultsPerEval)
+ * 消费,渲染依赖不进那条路径。attemptHref 缺省即 `#/attempt/@<locator>` 深链路由(web.ts 的默认值),
+ * 单段、不透明——证据室(`src/view/app/`)的 attempt 路由消费同一个格式(attempt-route.ts),
+ * 报告槽深链与证据室深链是同一条路由的两个来源。
  */
 async function renderReportSlot(
-  report: { path: string; cwd: string },
+  report: { path: string; cwd: string } | undefined,
   results: Results,
   selection: Selection,
-): Promise<string> {
-  const definition = await loadReportFile(report.cwd, report.path, { freshImport: true });
-  const { renderReportToStaticHtml } = await import("../report/web.ts");
-  return renderReportToStaticHtml(definition, { selection, results });
+): Promise<ReportSlotHtml> {
+  // built-ins/index.ts 和 web.ts 都碰 JSX(.tsx / import react-dom);package-owned 的报告
+  // runtime 走预编译产物(dist/report/**,`pnpm run build:report` 产出),不受 view 消费方
+  // cwd/tsconfig 影响 —— 见 tsconfig.report-build.json。两个动态 import 必须落在同一份编译
+  // 产物图里(dist/report/tree.js 的 WebContext 模块级状态不能跨实例),不能一个走 dist
+  // 一个走 src。
+  const definition = report
+    ? await loadReportFile(report.cwd, report.path, { freshImport: true })
+    : (await import("../../dist/report/built-ins/index.js")).CostPassRateComparison;
+  const { renderReportToStaticHtml } = await import("../../dist/report/web.js");
+  const ctx = { selection, results };
+  return {
+    en: await renderReportToStaticHtml(definition, ctx, { locale: "en" }),
+    "zh-CN": await renderReportToStaticHtml(definition, ctx, { locale: "zh-CN" }),
+  };
 }
 
 /**
- * 单文件模式(`niceeval view path/to/summary.json`)是用户明确指定的目标:
+ * 单文件模式(`niceeval view path/to/snapshot.json`)是用户明确指定的目标:
  * 读不了就让命令失败并给可执行的下一步,不打开一个空页面。目录模式不走这里
- * (读不了的进 skipped,页面顶部横幅展示,单个坏 run 不拖垮整页)。
+ * (读不了的进 skipped,页面顶部横幅展示,单个坏快照不拖垮整页)。
  */
 function assertSingleFileReadable(results: Results, target: string): void {
   let isFile = false;
@@ -277,7 +328,8 @@ function assertSingleFileReadable(results: Results, target: string): void {
   } catch {
     return; // 目标不存在:按空结果渲染(还没跑过 eval 不是错误)。
   }
-  if (!isFile || results.runDirs.length > 0) return;
+  const hasSnapshots = results.experiments.some((e) => e.snapshots.length > 0);
+  if (!isFile || hasSnapshots) return;
   const skip = results.skipped[0];
   if (skip?.reason === "incompatible-version") {
     throw new IncompatibleResultsError({
@@ -288,37 +340,31 @@ function assertSingleFileReadable(results: Results, target: string): void {
   }
   if (skip?.reason === "malformed") {
     throw new Error(
-      `${target}: ${skip.detail ?? "unreadable report"}. The report may be corrupted; re-run the eval or delete this run directory.`,
+      `${target}: ${skip.detail ?? "unreadable report"}. The report may be corrupted; re-run the eval or delete this snapshot directory.`,
     );
   }
-  throw new Error(`${target} is not a niceeval summary`);
+  throw new Error(`${target} is not a niceeval snapshot`);
 }
 
 /**
  * 给单条 attempt 注入 view 侧标注:
- * - attemptRef:直接用 niceeval/results 的证据引用(与 Reports 的 MetricCell.refs 同一身份)。
- * - artifactBase:相对 view 根的工件目录(前端据此 fetch trace.json 等)。--resume 携带的
- *   条目 artifactsDir 为空、artifactBase 指向原 run,原样沿用(同一套候选顺序)。
- * 返回新对象,不 mutate 读入的 summary;宿主机绝对路径只回给调用方写进 artifactDirs
+ * - locator:不透明的 AttemptLocator(与 Reports 的 MetricCell.refs / `ctx.attemptHref` 同一身份),
+ *   `#/attempt/@<locator>` 深链路由的参数——证据室按它在 viewData.snapshots 里定位回同一条 attempt。
+ * - artifactBase:相对 view 根的 artifact 目录(前端据此 fetch trace.json 等)。本快照跑出的
+ *   条目落盘没有这个字段,按 `${ref.snapshot}/${ref.attempt}` 现算;携带条目(--resume 合入)
+ *   落盘自带 artifactBase,指向原快照,原样沿用。
+ * 返回新对象,不 mutate 读入的结果;宿主机绝对路径只回给调用方写进 artifactDirs
  * (server 端内存),不挂到 result 上,避免随 viewData 进静态 HTML。
  */
 function annotateResult(
   attempt: AttemptHandle,
-  run: RunDir,
   root: string,
-): { annotated: ViewEvalResult; base?: string; abs?: string } {
+): { annotated: ViewEvalResult; base: string; abs: string } {
   const r = attempt.result;
-  const annotated: ViewEvalResult = { ...r, attemptRef: attempt.ref };
-  if (r.artifactsDir) {
-    const abs = join(run.dir, r.artifactsDir);
-    const base = relative(root, abs).split(/[\\/]/).join("/");
-    return { annotated: { ...annotated, artifactBase: base }, base, abs };
-  }
-  if (r.artifactBase) {
-    // 已是相对结果根的路径(携带条目),工件留在原 run 目录里。
-    return { annotated, base: r.artifactBase, abs: join(root, r.artifactBase) };
-  }
-  return { annotated };
+  const base = r.artifactBase ?? `${attempt.ref.snapshot}/${attempt.ref.attempt}`;
+  const abs = join(root, base);
+  const annotated: ViewEvalResult = { ...r, locator: attempt.locator, artifactBase: base };
+  return { annotated, base, abs };
 }
 
 /**
@@ -326,7 +372,7 @@ function annotateResult(
  * 有 skipped 时逐条列目录与原因——schemaVersion 不兼容的 niceeval 落盘给出可跑的
  * npx 命令,让「全被跳过」和「真没跑过」在错误里就能分清,不用进查看器排查。
  */
-function noReadableResults(target: string, skipped: SkippedRun[]): string {
+function noReadableResults(target: string, skipped: SkippedDir[]): string {
   if (skipped.length === 0) return t("cli.view.noResults", { root: target }).trimEnd();
   const lines = skipped.map((skip) => {
     const notice = toSkippedNotice(skip);
@@ -334,7 +380,7 @@ function noReadableResults(target: string, skipped: SkippedRun[]): string {
     const hint = notice.command ? ` — view it with \`${notice.command.trim()}\`` : "";
     return `  ${notice.dir}: ${notice.reason}${version}${hint}`;
   });
-  const runs = skipped.length === 1 ? "1 run directory was" : `${skipped.length} run directories were`;
+  const runs = skipped.length === 1 ? "1 snapshot directory was" : `${skipped.length} snapshot directories were`;
   return [
     `No readable results under ${target} — ${runs} skipped:`,
     ...lines,
@@ -342,7 +388,7 @@ function noReadableResults(target: string, skipped: SkippedRun[]): string {
   ].join("\n");
 }
 
-function toSkippedNotice(skip: SkippedRun): SkippedRunNotice {
+function toSkippedNotice(skip: SkippedDir): SkippedRunNotice {
   const dir = relative(process.cwd(), skip.dir) || ".";
   const command =
     skip.reason === "incompatible-version" && skip.producer?.name === "niceeval" && skip.producer.version

package/src/view/index.ts

@@ -26,7 +26,7 @@ export {
  * - 恰好一个位置参数且指向存在的文件 → 单文件模式(`niceeval view <summary.json>`),
  *   不与 --run 或其它位置参数混用;
  * - 指向存在的目录 → 报错直说:目录经 `--run <dir>` 递入,位置参数留给 eval id 前缀;
- * - 其余 → eval id 前缀,收窄报告槽选集(经 show 同一套选集合成)。
+ * - 其余 → eval id 前缀,收窄报告槽 Selection(经 show 同一套 Selection 合成)。
  */
 export function resolveViewInput(
   cwd: string,
@@ -74,12 +74,12 @@ export function resolveViewInput(
 }
 
 /**
- * 导出静态报告(--out):只有目录式一种形态。写 <dir>/index.html,并把前端会 fetch 的工件
+ * 导出静态报告(--out):只有目录式一种形态。写 <dir>/index.html,并把前端会 fetch 的 artifact
  * (sources.json / events.json / trace.json)复制到 <dir>/artifact/<base>/——与本地
  * server 的 /artifact/<rel> 路由同一布局,整个目录扔给任何静态托管即是完整体验。
- * 带 --report(opts.scan.report)时,报告页即首页的报告槽,证据室同站。
- * 单文件(*.html)导出已移除:代码/transcript/trace 视图依赖工件文件,单文件注定残缺,
- * 存在本身就在诱导用户导出一份看不了证据的报告(docs/view.md「静态导出」)。
+ * 首页即报告槽(裸跑填充 CostPassRateComparison,--report 整槽替换),证据室同站。
+ * 单文件(*.html)导出已移除:代码/transcript/trace 视图依赖 artifact 文件,单文件注定残缺,
+ * 存在本身就在诱导用户导出一份看不了证据的报告(docs/feature/reports/view.md「静态导出」)。
  */
 export async function buildView(opts: ViewOptions = {}): Promise<string> {
   const out = resolve(opts.out ?? ".niceeval/site");
@@ -95,18 +95,30 @@ export async function buildView(opts: ViewOptions = {}): Promise<string> {
   return out;
 }
 
-// 只复制前端会 fetch 的三类工件。diff.json / o11y.json 是运行侧产物,查看器从不读取,
-// 且 diff 可达上百 MB,带进静态导出只会拖垮部署体积。
-const FETCHED_ARTIFACTS = ["sources.json", "events.json", "trace.json"];
+// 只导出前端会 fetch 的三类 artifact。diff.json / o11y.json 是运行侧产物,查看器从不读取,
+// 且 diff 可达上百 MB,带进静态导出只会拖垮部署体积。events.json / trace.json 原字节复制;
+// sources.json 是例外——盘上是去重后的引用(`{path, sha256}[]`),必须先经
+// AttemptHandle.sources() 解引用出完整内容(`{path, content}[]`)再写出,否则浏览器端的
+// isCodeSource 守卫因缺 content 字段判空,代码视图会误判「源码未捕获」(即便源码明明捕获了)。
+const RAW_COPY_ARTIFACTS = ["events.json", "trace.json"];
 
 async function copyFetchedArtifacts(scan: ViewScan, artifactRoot: string): Promise<void> {
   for (const [base, srcDir] of scan.artifactDirs) {
     const destDir = join(artifactRoot, base);
     // 输入本身已经是导出布局(比如对着上次导出的目录重新生成 index.html)时不自拷。
     if (resolve(srcDir) === resolve(destDir)) continue;
-    const files = FETCHED_ARTIFACTS.filter((name) => existsSync(join(srcDir, name)));
-    if (!files.length) continue;
+
+    const rawFiles = RAW_COPY_ARTIFACTS.filter((name) => existsSync(join(srcDir, name)));
+    const hasSourcesRef = existsSync(join(srcDir, "sources.json"));
+    if (!rawFiles.length && !hasSourcesRef) continue;
+
     await mkdir(destDir, { recursive: true });
-    await Promise.all(files.map((name) => copyFile(join(srcDir, name), join(destDir, name))));
+    await Promise.all(rawFiles.map((name) => copyFile(join(srcDir, name), join(destDir, name))));
+
+    if (hasSourcesRef) {
+      const attempt = scan.attemptsByBase.get(base);
+      const sources = attempt ? await attempt.sources() : null;
+      await writeFile(join(destDir, "sources.json"), JSON.stringify(sources ?? []), "utf-8");
+    }
   }
 }