niceeval 0.7.1 → 0.8.1

package/src/view/data.ts

@@ -7,7 +7,7 @@
 // 见 docs/feature/reports/view.md「打开与收窄」。
 
 import { readFileSync, statSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
 import { dedupeAttempts, openResults } from "../results/index.ts";
 import type { AttemptHandle, Results, Scope, Snapshot, SkippedDir } from "../results/index.ts";
 import {
@@ -15,6 +15,7 @@ import {
   renderHostPageHtml,
   reportMetaFor,
   resolveReportTitle,
+  type HostHeadTag,
   type HostReport,
   type HostReportAsset,
 } from "../show/report-host.ts";
@@ -55,13 +56,7 @@ export interface ViewScan {
    */
   reportPages: ViewReportPageHtml[];
   /** 外壳注入资产(styles / scripts;{src} 已按路径纪律解析成 inline 内容),只进 web 面。 */
-  shellAssets: { styles: string[]; scripts: string[] };
-  /**
-   * --out 的数据等级(见 docs/feature/reports/view.md「静态导出」):全部选中快照带
-   * publish:{redaction:"applied"} 才是 "applied",否则 "sensitive"(含本地事实根与
-   * redaction:"none"——上游声明过原文发布也不豁免导出时的确认)。
-   */
-  publishState: "applied" | "sensitive";
+  shellAssets: { styles: string[]; scripts: string[]; head: ResolvedHeadTag[] };
 }
 
 /** view 宿主输入的组合语义(与 show 对齐,docs/feature/reports/architecture.md「Scope 是计算入口」)。 */
@@ -291,17 +286,12 @@ export async function loadViewScan(input?: string, opts: ViewScanOptions = {}):
     skippedRuns: results.skipped.map(toSkippedNotice),
     report: slot.meta,
   };
-  const publishState =
-    selection.snapshots.length > 0 && selection.snapshots.every((snap) => snap.publish?.redaction === "applied")
-      ? ("applied" as const)
-      : ("sensitive" as const);
   return {
     viewData,
     artifactDirs,
     attemptsByBase,
     reportPages: slot.pages,
     shellAssets: slot.shellAssets,
-    publishState,
   };
 }
 
@@ -331,6 +321,51 @@ function escapeHtml(text: string): string {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
+/**
+ * head 标签的解析形态:attrs 里的本地 `src` / `href` 已解析成宿主机绝对路径,
+ * 由站点管线(site.ts)按内容哈希物化为 `assets/<sha256><ext>` 并回填该属性;
+ * 外链与无资产标签原样透传(shell.md「行为约束」)。
+ */
+export interface ResolvedHeadTag {
+  tag: "meta" | "link" | "script" | "style";
+  attrs: Record<string, string | true>;
+  children?: string;
+  localAsset?: { attr: "src" | "href"; abs: string; ext: string };
+}
+
+/** head 标签 attrs 的 src/href 解析:外链透传,本地路径按 `{src}` 同一路径纪律落成绝对路径并验存在。 */
+function resolveShellHead(tags: HostHeadTag[], baseDir: string | undefined): ResolvedHeadTag[] {
+  const out: ResolvedHeadTag[] = [];
+  for (const entry of tags) {
+    const attrs = { ...(entry.attrs ?? {}) };
+    const resolved: ResolvedHeadTag = {
+      tag: entry.tag,
+      attrs,
+      ...(entry.children !== undefined ? { children: entry.children } : {}),
+    };
+    for (const attr of ["src", "href"] as const) {
+      const value = attrs[attr];
+      if (typeof value !== "string" || /^https?:\/\//i.test(value)) continue;
+      // 形状与 scheme 已在 defineReport 装载期校验;这里只剩本地文件的存在性。
+      if (value.startsWith("/") || value.startsWith("~") || value.split("/").includes("..")) {
+        throw new ViewInputError(
+          `Report head <${entry.tag}> ${attr} "${value}" is not a plain relative path. Assets resolve relative to the report file; ".." segments, absolute paths and "~" are not allowed.`,
+        );
+      }
+      const abs = resolve(baseDir ?? process.cwd(), value);
+      try {
+        statSync(abs);
+      } catch {
+        throw new ViewInputError(`Report head <${entry.tag}> ${attr} asset not found: ${abs} (declared as "${value}").`);
+      }
+      resolved.localAsset = { attr, abs, ext: extname(abs) };
+      break;
+    }
+    out.push(resolved);
+  }
+  return out;
+}
+
 /** 外壳 `{src}` 资产的路径纪律(shell.md「行为约束」):相对报告文件解析;拒绝 `..` 路径段、绝对路径与 `~`。 */
 function resolveShellAssets(assets: HostReportAsset[], baseDir: string | undefined, kind: "styles" | "scripts"): string[] {
   const out: string[] = [];
@@ -371,7 +406,11 @@ async function renderReportSlot(
   results: Results,
   selection: Scope,
   pageFailure: "throw" | "embed" = "throw",
-): Promise<{ meta: ViewReportMeta; pages: ViewReportPageHtml[]; shellAssets: { styles: string[]; scripts: string[] } }> {
+): Promise<{
+  meta: ViewReportMeta;
+  pages: ViewReportPageHtml[];
+  shellAssets: { styles: string[]; scripts: string[]; head: ResolvedHeadTag[] };
+}> {
   // 报告 runtime 走预编译产物(dist/report/**,`pnpm run build:report` 产出),不受 view
   // 消费方 cwd/tsconfig 影响;装载与渲染统一经 ../show/report-host.ts(两个宿主共用的联系面)。
   const hostReport: HostReport = await loadHostReport(report?.cwd ?? process.cwd(), report?.path, {
@@ -389,6 +428,7 @@ async function renderReportSlot(
   const shellAssets = {
     styles: resolveShellAssets(hostReport.styles, reportDir, "styles"),
     scripts: resolveShellAssets(hostReport.scripts, reportDir, "scripts"),
+    head: resolveShellHead(hostReport.head, reportDir),
   };
 
   const pages: ViewReportPageHtml[] = [];

package/src/view/index.ts

@@ -1,14 +1,16 @@
 // 本地结果查看器入口:只做编排与对外导出。
-// 读取(openResults)与统计(官方计算函数)在 data.ts,HTTP 与 HTML 烘焙在 server.ts,
-// server/前端共用的数据契约在 shared/types.ts。
+// 站点管线(planSite/writeSite,server 与 --out 的唯一联系面)在 site.ts,读取(openResults)
+// 与统计(官方计算函数)在 data.ts,HTTP 宿主在 server.ts,server/前端共用的数据契约在
+// shared/types.ts。
 
-import { copyFile, mkdir, writeFile } from "node:fs/promises";
 import { existsSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { ViewInputError, loadViewScan, type ViewScan } from "./data.ts";
-import { renderHtml, type ViewOptions } from "./server.ts";
+import { resolve } from "node:path";
+import { ViewInputError } from "./data.ts";
+import { planSite, writeSite } from "./site.ts";
+import type { ViewOptions } from "./server.ts";
 
 export { startViewServer, type ViewOptions, type ViewServer } from "./server.ts";
+export { planSite, writeSite, renderHtml, type SitePlan, type SiteFile } from "./site.ts";
 export {
   IncompatibleResultsError,
   ViewInputError,
@@ -64,12 +66,12 @@ export function resolveViewInput(
 }
 
 /**
- * 导出静态报告(--out):只有目录式一种形态。写 <dir>/index.html,并把前端会 fetch 的 artifact
- * (sources.json / events.json / trace.json / diff.json)复制到 <dir>/artifact/<base>/——与本地
- * server 的 /artifact/<rel> 路由同一布局,整个目录扔给任何静态托管即是完整体验。
- * 首页即报告槽(裸跑填充内建报告,--report 整槽替换),证据室同站;多页报告仍是单个
- * index.html(页面走 `#/page/<id>` 路由)。单文件(*.html)导出已移除:代码/transcript/trace
- * 视图依赖 artifact 文件,单文件注定残缺(docs/feature/reports/view.md「静态导出」)。
+ * 导出静态报告(--out):只有目录式一种形态。站点管线(site.ts)产出与本地 server 服务的
+ * 同一份产物清单,这里把它写进 <dir>——index.html + `artifact/<base>/` 证据树,整个目录扔给
+ * 任何静态托管即是完整体验。首页即报告槽(裸跑填充内建报告,--report 整槽替换),证据室同站;
+ * 多页报告仍是单个 index.html(页面走 `#/page/<id>` 路由)。单文件(*.html)导出已移除:
+ * 代码/transcript/trace 视图依赖 artifact 文件,单文件注定残缺(docs/feature/reports/view.md
+ * 「静态导出」)。
  */
 export async function buildView(opts: ViewOptions = {}): Promise<string> {
   const out = resolve(opts.out ?? ".niceeval/site");
@@ -86,54 +88,12 @@ export async function buildView(opts: ViewOptions = {}): Promise<string> {
       "--out exports the whole results root and cannot be combined with eval prefixes or --experiment.\n" +
         "To publish a site for one experiment, build a narrower results root and export that:\n" +
         '  const results = await openResults(".niceeval");\n' +
-        '  await copySnapshots(results.latest().filter((s) => s.experimentId.startsWith("<prefix>/")), "<publish-root>", { redact });\n' +
+        '  await copySnapshots(results.latest().filter((s) => s.experimentId.startsWith("<prefix>/")), "<publish-root>");\n' +
         "Then: niceeval view --results <publish-root> --out <site>",
     );
   }
-  const scan = await loadViewScan(opts.input, opts.scan);
-  // --out 按发布防呆二分(见 docs/feature/reports/view.md「静态导出」):目标结果根的全部快照
-  // 带 publish:{redaction:"applied"}(copySnapshots 补记)时直接导出;redaction:"none"、
-  // 无标记结果或本地事实根,都必须显式传 --allow-sensitive-artifacts——静态站原样携带证据文件,
-  // 上游声明过原文发布也不豁免这里的确认。
-  if (!opts.allowSensitiveArtifacts && scan.publishState !== "applied") {
-    throw new ViewInputError(
-      `--out refuses to export unredacted results: not every selected snapshot carries publish: { redaction: "applied" }. ` +
-        `Produce a publish root first with copySnapshots({ redact }) and export that (niceeval view --results <publish-root> --out <site>), ` +
-        `or pass --allow-sensitive-artifacts to explicitly export raw evidence (prompts, tool args, full outputs, sources).`,
-    );
-  }
-  await mkdir(out, { recursive: true });
-  await writeFile(join(out, "index.html"), await renderHtml(scan), "utf-8");
-  await copyFetchedArtifacts(scan, join(out, "artifact"));
+  // 静态导出保持「任一页失败整体失败」(pageFailure 缺省 "throw"),不产出半套站点。
+  const plan = await planSite(opts.input, opts.scan);
+  await writeSite(plan, out);
   return out;
 }
-
-// 导出没有档位(docs/feature/reports/view.md「静态导出」):结果根里存在且前端会读取的证据
-// 文件全部复制——events.json / trace.json / diff.json 原字节复制(diff 有就带,缺时前端在
-// 证据位置如实显示缺失;体积取舍在构建发布根时用 copySnapshots({ artifacts }) 做,不在导出层);
-// 唯一永不复制的是 o11y.json——报告数字在导出时已烘进 HTML,浏览器不读它。
-// sources.json 是格式例外——盘上是去重后的引用(`{path, sha256}[]`),必须先经
-// AttemptHandle.sources() 解引用出完整内容(`{path, content}[]`)再写出,否则浏览器端的
-// isCodeSource 守卫因缺 content 字段判空,代码视图会误判「源码未捕获」(即便源码明明捕获了)。
-const RAW_COPY_ARTIFACTS = ["events.json", "trace.json", "diff.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 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(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");
-    }
-  }
-}

package/src/view/server.ts

@@ -1,21 +1,19 @@
-// HTTP server 与静态资源:起本地 web、按需吐 artifact、把 viewData 烘焙进单个 HTML。
-// 数据读取与统计在 data.ts(openResults + 官方计算函数);这里只管「怎么送到浏览器」。
+// HTTP server:把站点管线(site.ts 的 planSite)产出的同一份产物挂在 127.0.0.1 上按路径服务。
+// 这里不携带任何取数或布局知识——查不到清单条目就是 404,与 `--out` 写盘的文件逐字节一致
+// (docs/feature/reports/view.md 开篇;奇偶由 site-parity 测试守护)。宿主语义只有三条,全部
+// 作用在管线输入端:打开首页整份重建(数据永远是盘上最新)、单页渲染失败折成页内错误块
+// (pageFailure: "embed")、报告槽可被位置参数 / --experiment 收窄。
 
 import { createServer, type Server } from "node:http";
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { loadAttemptIndex, loadViewScan, viewRoot, type ViewScan, type ViewScanOptions } from "./data.ts";
-import type { AttemptHandle } from "../results/index.ts";
-import { localizeText } from "../show/report-host.ts";
+import { type ViewScanOptions } from "./data.ts";
+import { planSite, readSiteFile, type SitePlan } from "./site.ts";
 import { formatThrown } from "../util.ts";
 
 export interface ViewOptions {
   input?: string;
   out?: string;
   port?: number;
-  /** `--out` 对非发布根(无 publish:applied 标记)导出时的显式确认;静态站原样携带证据文件。 */
-  allowSensitiveArtifacts?: boolean;
-  /** 报告槽的组合语义(位置前缀 / --experiment / --report),透传给 loadViewScan。 */
+  /** 报告槽的组合语义(位置前缀 / --experiment / --report),透传给站点管线。 */
   scan?: ViewScanOptions;
 }
 
@@ -24,21 +22,22 @@ export interface ViewServer {
   close(): Promise<void>;
 }
 
-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);
   // 本地 server 的单页失败折成该页的错误块,其它页照常可读(静态导出仍整体失败)。
   const scanOptions = { ...opts.scan, pageFailure: "embed" as const };
-  // 数据装载先跑一遍:--snapshot 指向读不了的快照、--report 装载失败、
-  // 前缀匹配不到,都要在起 server 前就失败并给出提示。
-  await loadViewScan(input, scanOptions);
+
+  // 产物重建的单飞通道:首页请求整份重建;并发请求共享同一次构建,不重复扫描。
+  let current: Promise<SitePlan>;
+  const rebuild = (): Promise<SitePlan> => {
+    current = planSite(input, scanOptions);
+    return current;
+  };
+
+  // 启动前先构建一遍:--snapshot 指向读不了的快照、--report 装载失败、前缀匹配不到,
+  // 都要在起 server 前就失败并给出提示。
+  await rebuild();
+
   const server = createServer(async (req, res) => {
     try {
       const url = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -47,30 +46,42 @@ export async function startViewServer(opts: ViewOptions = {}): Promise<ViewServe
         res.end("ok");
         return;
       }
-      // 按需提供拆分 artifact(trace.json / events.json / …),前端展开时 fetch。
-      // 路径式 /artifact/<rel> 与目录式静态导出的文件布局一致(见 view/index.ts 的 buildView),
-      // 同一份前端产物在本地 server 和静态托管上用同一个相对 URL。
-      if (url.pathname.startsWith("/artifact/")) {
-        await serveArtifact(root, decodeURIComponent(url.pathname.slice("/artifact/".length)), res, () => loadAttemptIndex(input));
-        return;
+
+      // 站点相对路径:`/` 即 index.html;兼容旧的 /artifact?p= query 形式
+      // (0.2.x 前端烘焙的 HTML 可能还开着)。
+      let sitePath: string;
+      if (url.pathname === "/") {
+        // 每次打开首页整份重建,永远是盘上最新数据;--report 的报告文件变更同样在
+        // 下次请求整页重算(装载走 mtime cache-busting,见 report/load.ts)。
+        await rebuild();
+        sitePath = "index.html";
+      } else if (url.pathname === "/artifact") {
+        sitePath = `artifact/${url.searchParams.get("p") ?? ""}`;
+      } else {
+        sitePath = decodeURIComponent(url.pathname.slice(1));
       }
-      // 兼容旧的 query 形式(0.2.x 前端烘焙的 HTML 可能还开着)。
-      if (url.pathname === "/artifact") {
-        await serveArtifact(root, url.searchParams.get("p") ?? "", res, () => loadAttemptIndex(input));
+
+      let plan = await current;
+      let file = plan.files.get(sitePath);
+      if (!file && sitePath.startsWith("artifact/")) {
+        // 未命中最近一次构建的产物清单:管线重建一次再查——server 运行期间
+        // 新落盘的证据(新快照、补跑)不需要重启。
+        plan = await rebuild();
+        file = plan.files.get(sitePath);
+      }
+      if (!file) {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        res.end("not found");
         return;
       }
-      if (url.pathname !== "/") {
+      const body = await readSiteFile(file);
+      if (body === undefined) {
         res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
         res.end("not found");
         return;
       }
-      res.writeHead(200, {
-        "content-type": "text/html; charset=utf-8",
-        "cache-control": "no-store",
-      });
-      // 每次请求现读现算,永远是盘上最新数据;--report 的报告文件变更同样在
-      // 下次请求整页重算(装载走 mtime cache-busting,见 report/load.ts)。
-      res.end(await renderHtml(await loadViewScan(input, scanOptions)));
+      res.writeHead(200, { "content-type": file.contentType, "cache-control": "no-store" });
+      res.end(body);
     } catch (e) {
       res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
       res.end(formatThrown(e));
@@ -87,112 +98,6 @@ export async function startViewServer(opts: ViewOptions = {}): Promise<ViewServe
   };
 }
 
-/**
- * 把 viewData(只含原始值与相对路径,不含宿主机绝对路径)和前端产物烘焙进单个 HTML。
- * 报告槽恒在:每页报告 HTML 作为 <template id="niceeval-report-<pageId>-<locale>"> 静态块
- * 烘在 __NICEEVAL_VIEW_DATA__ 旁(不 hydrate,自定义组件的 <Style> 产物已内联其中),
- * 并恒内联官方组件样式(report/react/styles.css)与渐进增强 runtime(report/react/enhance.js,
- * 内联 <script>:排序 / 过滤 / tooltip,document 级事件委托,报告块被前端搬进槽位也无需重绑;
- * 无 JS 时报告内容依旧完整);外壳声明的 styles 注入在官方样式之后、scripts 注入在官方
- * 增强脚本之后 </body> 前,均按声明顺序(docs/feature/reports/library/shell.md)。
- * 前端只把当前页 / 当前界面语言对应的块摆进报告槽位置,不解析。
- */
-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 [reportStyles, reportEnhance] = await Promise.all([
-    readFile(new URL("../report/react/styles.css", import.meta.url), "utf-8"),
-    readFile(new URL("../report/react/enhance.js", import.meta.url), "utf-8"),
-  ]);
-
-  const shellStyles = scan.shellAssets.styles.map((css) => `\n<style>\n${css}\n</style>`).join("");
-  const shellScripts = scan.shellAssets.scripts.map((js) => `<script>\n${js}\n</script>\n`).join("");
-
-  const pageTemplates = scan.reportPages
-    .flatMap((page) => [
-      `<template id="niceeval-report-${page.id}-en">${page.html.en}</template>`,
-      `<template id="niceeval-report-${page.id}-zh-CN">${page.html["zh-CN"]}</template>`,
-    ])
-    .join("\n");
-
-  // 初始 <title> 与 hero 同源:走完回退链的报告标题(viewData.report.title;终点是内置文案
-  // 「Eval 运行结果 / Eval Results」)。模板 lang="en",初始按 en 解析;前端按界面语言更新。
-  const title = localizeText(scan.viewData.report?.title, "en") ?? "Eval Results";
-
-  return template
-    .replace(
-      /<title>[^<]*<\/title>/,
-      () => `<title>${title.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}</title>`,
-    )
-    .replace(
-      TEMPLATE_PLACEHOLDERS.styles,
-      () =>
-        `<style>\n${styles}\n</style>\n<style>\n${reportStyles}\n</style>\n<script>\n${reportEnhance}\n</script>` +
-        shellStyles,
-    )
-    .replace(TEMPLATE_PLACEHOLDERS.reportSlot, () => pageTemplates)
-    .replace(TEMPLATE_PLACEHOLDERS.viewData, () => JSON.stringify(scan.viewData).replace(/</g, "\\u003c"))
-    .replace(TEMPLATE_PLACEHOLDERS.appCode, () => JSON.stringify(app).replace(/</g, "\\u003c"))
-    .replace("</body>", () => `${shellScripts}</body>`);
-}
-
-/** rel 的末段文件名;base = 去掉末段后剩下的部分(与 artifactUrl 的按段编码/拼接对称)。 */
-function splitArtifactRel(rel: string): { base: string; file: string } {
-  const segments = rel.split("/");
-  const file = segments.pop() ?? "";
-  return { base: segments.join("/"), file };
-}
-
-/**
- * 安全地把 root 下的 artifact 文件吐回去(限定 .json,且解析后必须仍在 root 内)。
- * sources.json 是唯一例外:落盘是去重后的引用(`{path, sha256}[]`),不能直接 piping 原字节——
- * 按 base 反查 AttemptHandle,经它的 `.sources()` 解引用出完整内容(`{path, content}[]`)再回给
- * 浏览器。attemptIndex 懒建(只在真的碰到 sources.json 请求时才付 openResults() 扫描的代价),
- * events.json / trace.json 等其它 artifact 完全不受影响,原样走原文件读取。
- */
-async function serveArtifact(
-  root: string,
-  rel: string,
-  res: import("node:http").ServerResponse,
-  attemptIndex: () => Promise<Map<string, AttemptHandle>>,
-): Promise<void> {
-  const abs = resolve(root, rel);
-  const within = abs === root || abs.startsWith(root + "/");
-  if (!within || !rel.endsWith(".json")) {
-    res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
-    res.end("bad artifact path");
-    return;
-  }
-
-  const { base, file } = splitArtifactRel(rel);
-  if (file === "sources.json") {
-    const attempt = (await attemptIndex()).get(base);
-    if (!attempt) {
-      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
-      res.end("artifact not found");
-      return;
-    }
-    const sources = await attempt.sources();
-    res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
-    res.end(JSON.stringify(sources ?? []));
-    return;
-  }
-
-  try {
-    const body = await readFile(abs, "utf-8");
-    res.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
-    res.end(body);
-  } catch {
-    res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
-    res.end("artifact not found");
-  }
-}
-
-async function readViewAsset(name: string): Promise<string> {
-  return readFile(new URL(name, import.meta.url), "utf-8");
-}
-
 async function listen(server: Server, preferredPort: number): Promise<number> {
   const tryListen = (port: number): Promise<number> =>
     new Promise((resolveListen, reject) => {

package/src/view/site-head.test.ts

@@ -0,0 +1,177 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 覆盖登记行:head 通道注入面——声明序注入 <head>、外链原样透传不进 assets/、
+// 本地 src/href 物化为 assets/<sha256><ext>、attrs 渲染与转义、注入不改初始 HTML
+// 数据节点、head 不进 ctx.report / viewData。
+// 站点管线是 server 与 --out 的唯一联系面,断言全部打在 planSite 产物上。
+
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { loadViewScan } from "./data.ts";
+import { planSite, readSiteFile, writeSite } from "./site.ts";
+import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../types.ts";
+
+const roots: string[] = [];
+async function makeRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "niceeval-sitehead-"));
+  roots.push(root);
+  return root;
+}
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((r) => rm(r, { recursive: true, force: true })));
+});
+
+/** 最小结果根:单实验单快照单 attempt(与 view-report.test.ts 的 writeSnapshot 同一姿势)。 */
+async function seedRoot(): Promise<string> {
+  const root = await makeRoot();
+  const dir = join(root, "compare_bub", "2026-07-08T10-00-00-000Z");
+  await mkdir(dir, { recursive: true });
+  await writeFile(
+    join(dir, "snapshot.json"),
+    JSON.stringify({
+      format: RESULTS_FORMAT,
+      schemaVersion: RESULTS_SCHEMA_VERSION,
+      producer: { name: "niceeval", version: "0.4.6" },
+      experimentId: "compare/bub",
+      agent: "bub",
+      startedAt: "2026-07-08T10:00:00.000Z",
+      completedAt: "2026-07-08T10:00:00.000Z",
+    }),
+    "utf-8",
+  );
+  const attemptDir = join(dir, "weather/brooklyn", "a0");
+  await mkdir(attemptDir, { recursive: true });
+  await writeFile(
+    join(attemptDir, "result.json"),
+    JSON.stringify({ id: "weather/brooklyn", verdict: "passed", attempt: 0, durationMs: 1000, assertions: [] }),
+    "utf-8",
+  );
+  return root;
+}
+
+const FAVICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg"><circle r="4"/></svg>';
+
+const GA_SRC = "https://www.googletagmanager.com/gtag/js?id=G-TEST";
+const OG_IMAGE = 'https://x.example/a"b.png';
+
+/** 不经包入口也合法的最小外壳报告(与 view-report.test.ts 的 shellReportSource 同一姿势)。 */
+function headReportSource(head: string): string {
+  return [
+    'const FACES = Symbol.for("niceeval.report.faces");',
+    'const DEFINITION = Symbol.for("niceeval.report.definition");',
+    "const Block = (props) => Block[FACES].web(props);",
+    "Block[FACES] = {",
+    '  web: () => "HEAD_TEST_BODY",',
+    '  text: () => "HEAD_TEST_BODY",',
+    "};",
+    "const definition = {",
+    '  kind: "report",',
+    '  title: "Head Test",',
+    "  links: [],",
+    `  head: ${head},`,
+    "  scripts: [],",
+    "  styles: [],",
+    '  pages: [{ id: "report", title: "Report", content: { $$typeof: Symbol.for("react.transitional.element"), type: Block, props: {}, key: null } }],',
+    "};",
+    "Object.defineProperty(definition, DEFINITION, { value: true });",
+    "export default definition;",
+    "",
+  ].join("\n");
+}
+
+const HEAD_DECL = JSON.stringify([
+  { tag: "script", attrs: { async: true, src: GA_SRC } },
+  { tag: "script", children: "window.dataLayer = window.dataLayer || [];" },
+  { tag: "meta", attrs: { property: "og:image", content: OG_IMAGE } },
+  { tag: "link", attrs: { rel: "icon", href: "./favicon.svg" } },
+]);
+
+async function seedReport(root: string, head: string): Promise<string> {
+  const path = join(root, "head-report.mjs");
+  await writeFile(path, headReportSource(head), "utf-8");
+  await writeFile(join(root, "favicon.svg"), FAVICON_SVG, "utf-8");
+  return path;
+}
+
+describe("站点管线 · head 通道注入", () => {
+  it("按声明序注入 <head>:外链原样、布尔属性裸渲染、属性值转义、children 原样", async () => {
+    const root = await seedRoot();
+    const path = await seedReport(root, HEAD_DECL);
+    const plan = await planSite(root, { report: { path, cwd: root } });
+    const html = (await readSiteFile(plan.files.get("index.html")!)) as string;
+
+    const gtag = `<script async src="${GA_SRC}"></script>`;
+    const inline = "<script>window.dataLayer = window.dataLayer || [];</script>";
+    const og = '<meta property="og:image" content="https://x.example/a&quot;b.png">';
+    expect(html).toContain(gtag);
+    expect(html).toContain(inline);
+    expect(html).toContain(og);
+    // 全部落在 <head> 内、按声明序。
+    const headEnd = html.indexOf("</head>");
+    const positions = [html.indexOf(gtag), html.indexOf(inline), html.indexOf(og), html.indexOf('rel="icon"')];
+    for (const p of positions) expect(p).toBeGreaterThan(-1);
+    for (const p of positions) expect(p).toBeLessThan(headEnd);
+    expect([...positions].sort((a, b) => a - b)).toEqual(positions);
+  });
+
+  it("本地 href 物化为 assets/<sha256><ext> 并回填标签;外链不进 assets/;写盘与 server 读取同源", async () => {
+    const root = await seedRoot();
+    const path = await seedReport(root, HEAD_DECL);
+    const plan = await planSite(root, { report: { path, cwd: root } });
+
+    const sha256 = createHash("sha256").update(FAVICON_SVG).digest("hex");
+    const assetPath = `assets/${sha256}.svg`;
+    const html = (await readSiteFile(plan.files.get("index.html")!)) as string;
+    expect(html).toContain(`<link rel="icon" href="${assetPath}">`);
+
+    const assetKeys = [...plan.files.keys()].filter((p) => p.startsWith("assets/"));
+    expect(assetKeys).toEqual([assetPath]); // 外链(gtag)不 vendored
+    expect(plan.files.get(assetPath)!.contentType).toBe("image/svg+xml");
+    // server 面:原字节读取(二进制安全)。
+    const served = await readSiteFile(plan.files.get(assetPath)!);
+    expect(Buffer.isBuffer(served)).toBe(true);
+    expect((served as Buffer).toString("utf-8")).toBe(FAVICON_SVG);
+    // 导出面:writeSite 落盘同一份字节。
+    const out = join(root, "out");
+    await writeSite(plan, out);
+    expect(await readFile(join(out, assetPath), "utf-8")).toBe(FAVICON_SVG);
+  });
+
+  it("head 注入不改初始 HTML 的报告数据节点;head 不进 viewData.report", async () => {
+    const root = await seedRoot();
+    const withHead = await seedReport(root, HEAD_DECL);
+    const planWith = await planSite(root, { report: { path: withHead, cwd: root } });
+
+    const bare = join(root, "bare-report.mjs");
+    await writeFile(bare, headReportSource("[]"), "utf-8");
+    const planWithout = await planSite(root, { report: { path: bare, cwd: root } });
+
+    const extractTemplate = (html: string): string => {
+      const match = html.match(/<template id="niceeval-report-report-en">[\s\S]*?<\/template>/);
+      expect(match).not.toBeNull();
+      return match![0];
+    };
+    const htmlWith = (await readSiteFile(planWith.files.get("index.html")!)) as string;
+    const htmlWithout = (await readSiteFile(planWithout.files.get("index.html")!)) as string;
+    expect(extractTemplate(htmlWith)).toBe(extractTemplate(htmlWithout));
+
+    // head 是注入资产,不进序列化声明(viewData.report)。
+    const scan = await loadViewScan(root, { report: { path: withHead, cwd: root } });
+    expect(scan.viewData.report).not.toHaveProperty("head");
+    expect(scan.shellAssets.head).toHaveLength(4);
+  });
+
+  it("本地 href 缺失文件:装载报错并给出解析后的绝对路径", async () => {
+    const root = await seedRoot();
+    const path = join(root, "missing-asset.mjs");
+    await writeFile(
+      path,
+      headReportSource(JSON.stringify([{ tag: "link", attrs: { rel: "icon", href: "./nope.svg" } }])),
+      "utf-8",
+    );
+    await expect(planSite(root, { report: { path, cwd: root } })).rejects.toThrow(/asset not found: .*nope\.svg/);
+  });
+});