niceeval 0.7.1 → 0.8.0

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

@@ -0,0 +1,117 @@
+// cases: docs/engineering/unit-tests/reports/cases.md
+// 「show/view 宿主等价与选择」分区——
+// 本地 server 与 --out 消费同一份站点产物:同一路径两宿主逐字节一致;server 不提供产物清单
+// 之外的路径。server 打开首页触发产物整份重建(盘上新数据无需重启),artifact 未命中重建一次。
+// 契约:docs/feature/reports/view.md 开篇「同一条站点管线」。
+
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createResultsWriter } from "../results/index.ts";
+import { buildView } from "./index.ts";
+import { planSite } from "./site.ts";
+import { startViewServer, type ViewServer } from "./server.ts";
+
+const roots: string[] = [];
+async function makeDir(prefix: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), prefix));
+  roots.push(dir);
+  return dir;
+}
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((r) => rm(r, { recursive: true, force: true })));
+});
+
+/** 真实 writer 落一份含 events / trace / diff / 去重 sources 的快照(不手写落盘格式)。 */
+async function seedSnapshot(root: string, experimentId: string, evalId: string): Promise<void> {
+  const writer = createResultsWriter(root, { producer: { name: "niceeval", version: "1.0.0" } });
+  const snap = await writer.snapshot({ experimentId, agent: "bub", startedAt: "2026-07-01T08:00:00.000Z" });
+  await snap.writeAttempt(
+    { id: evalId, verdict: "passed", attempt: 0, durationMs: 1, assertions: [] },
+    {
+      sources: [{ path: "evals/a.eval.ts", content: "export default 1;\n" }],
+      events: [
+        { type: "message", role: "user", text: "hi", loc: { file: "evals/a.eval.ts", line: 3 } },
+        { type: "message", role: "assistant", text: "hello there" },
+      ],
+      trace: [{ name: "turn", kind: "turn" } as never],
+      diff: [{ window: "s1/t1", changes: { "a.txt": { status: "added", after: "1" } } }] as never,
+    },
+  );
+  await writer.finish();
+}
+
+describe("站点管线奇偶:server 与 --out 是同一份产物", () => {
+  let server: ViewServer | undefined;
+  afterEach(async () => {
+    await server?.close();
+    server = undefined;
+  });
+
+  it("导出目录的每个文件与 server 对同路径的响应逐字节一致;server 不提供清单之外的路径", async () => {
+    const root = await makeDir("niceeval-parity-root-");
+    await seedSnapshot(root, "exp", "q1");
+
+    const out = await makeDir("niceeval-parity-out-");
+    await buildView({ input: root, out, allowSensitiveArtifacts: true });
+    server = await startViewServer({ input: root });
+
+    // 清单驱动遍历:计划里的每一个路径,写盘字节 ≡ 服务字节。
+    const plan = await planSite(root);
+    expect(plan.files.size).toBeGreaterThanOrEqual(5); // index.html + sources/events/trace/diff
+    for (const file of plan.files.values()) {
+      const written = await readFile(join(out, file.path), "utf-8");
+      const res = await fetch(new URL(file.path === "index.html" ? "/" : `/${file.path}`, server.url));
+      expect(res.status, file.path).toBe(200);
+      expect(await res.text(), file.path).toBe(written);
+    }
+
+    // 产物清单之外的路径不存在旁路取数:即便文件真实在结果根里(o11y.json),也不服务。
+    const base = [...plan.files.keys()].find((p) => p.endsWith("/events.json"))!.replace(/\/events\.json$/, "");
+    for (const path of [`${base}/o11y.json`, `${base}/result.json`, "artifact/../package.json", "no-such-file"]) {
+      const res = await fetch(new URL(`/${path}`, server.url));
+      expect(res.status, path).toBe(404);
+    }
+  });
+
+  it("首页请求触发整份重建:server 启动后新落盘的快照,刷新即可见、其证据无需重启可 fetch", async () => {
+    const root = await makeDir("niceeval-parity-fresh-");
+    await seedSnapshot(root, "exp-a", "q1");
+    server = await startViewServer({ input: root });
+
+    const before = await (await fetch(server.url)).text();
+    expect(before).toContain("exp-a");
+    expect(before).not.toContain("exp-b");
+
+    await seedSnapshot(root, "exp-b", "q2");
+
+    // 刷新首页:整份产物重建,新实验进入 viewData。
+    const after = await (await fetch(server.url)).text();
+    expect(after).toContain("exp-b");
+
+    // 新快照的证据文件不重启 server 就能取到(artifact 未命中时管线重建一次再查)。
+    const plan = await planSite(root);
+    const eventsPath = [...plan.files.keys()].find((p) => p.includes("exp-b") && p.endsWith("/events.json"))!;
+    const res = await fetch(new URL(`/${eventsPath}`, server.url));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual([
+      { type: "message", role: "user", text: "hi", loc: { file: "evals/a.eval.ts", line: 3 } },
+      { type: "message", role: "assistant", text: "hello there" },
+    ]);
+  });
+
+  it("legacy /artifact?p= query 形式仍服务同一份产物", async () => {
+    const root = await makeDir("niceeval-parity-legacy-");
+    await seedSnapshot(root, "exp", "q1");
+    server = await startViewServer({ input: root });
+
+    const plan = await planSite(root);
+    const eventsPath = [...plan.files.keys()].find((p) => p.endsWith("/events.json"))!;
+    const rel = eventsPath.replace(/^artifact\//, "");
+    const res = await fetch(new URL(`/artifact?p=${encodeURIComponent(rel)}`, server.url));
+    expect(res.status).toBe(200);
+    const direct = await (await fetch(new URL(`/${eventsPath}`, server.url))).text();
+    expect(await res.text()).toBe(direct);
+  });
+});

package/src/view/site.ts

@@ -0,0 +1,209 @@
+// 站点管线:本地 server 与 `--out` 的唯一联系面(docs/feature/reports/view.md 开篇)。
+// planSite 把结果根物化成一份站点产物清单(index.html + artifact 证据树),writeSite 把清单
+// 写盘,server 按路径服务同一份清单——布局与取数知识(artifact 相对路径、sources.json 解引用)
+// 只住在这里,两个宿主都是哑消费者,同一路径两边逐字节一致(site-parity 测试守护)。
+
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { loadViewScan, type ResolvedHeadTag, type ViewScan, type ViewScanOptions } from "./data.ts";
+import { localizeText } from "../show/report-host.ts";
+
+/** 站点产物清单里的一个文件:现算内容,或指向结果根内的原文件。 */
+export interface SiteFile {
+  /** 站点相对路径(posix),如 `index.html`、`artifact/<base>/events.json`。 */
+  path: string;
+  contentType: string;
+  source: { kind: "content"; body: string } | { kind: "file"; abs: string };
+}
+
+export interface SitePlan {
+  /** path → SiteFile;写盘按它遍历,server 按它查表(查不到即 404,不存在旁路取数)。 */
+  files: Map<string, SiteFile>;
+  /** 构建这份产物用的扫描结果(publishState 等宿主前置校验用;不进产物)。 */
+  scan: ViewScan;
+}
+
+const JSON_TYPE = "application/json; charset=utf-8";
+const HTML_TYPE = "text/html; charset=utf-8";
+
+// 前端会 fetch 的原字节证据文件(docs/feature/reports/view.md「静态导出」:有就带,缺时前端
+// 在证据位置如实显示缺失;o11y.json 永不进产物——报告数字已烘进 HTML,浏览器不读它)。
+const RAW_COPY_ARTIFACTS = ["events.json", "trace.json", "diff.json"];
+
+/**
+ * 把结果根物化成站点产物清单。sources.json 是唯一的格式例外——盘上是去重后的引用
+ * (`{path, sha256}[]`),必须经 `AttemptHandle.sources()` 解引用出完整内容(`{path, content}[]`)
+ * 才能给浏览器用,解引用只发生在这里这一处。
+ */
+export async function planSite(input?: string, opts: ViewScanOptions = {}): Promise<SitePlan> {
+  const scan = await loadViewScan(input, opts);
+  const files = new Map<string, SiteFile>();
+  // head 标签的本地 src/href 资产按内容哈希物化进 assets/(同内容同扩展名去重,
+  // 同名文件不冲突;shell.md「行为约束」),回填后的标签渲染进 <head>。
+  const headHtml = await materializeHeadAssets(scan.shellAssets.head, files);
+  files.set("index.html", {
+    path: "index.html",
+    contentType: HTML_TYPE,
+    source: { kind: "content", body: await renderHtml(scan, headHtml) },
+  });
+
+  for (const [base, srcDir] of scan.artifactDirs) {
+    for (const name of RAW_COPY_ARTIFACTS) {
+      const abs = join(srcDir, name);
+      if (!existsSync(abs)) continue;
+      const path = `artifact/${base}/${name}`;
+      files.set(path, { path, contentType: JSON_TYPE, source: { kind: "file", abs } });
+    }
+    if (existsSync(join(srcDir, "sources.json"))) {
+      const attempt = scan.attemptsByBase.get(base);
+      const sources = attempt ? await attempt.sources() : null;
+      const path = `artifact/${base}/sources.json`;
+      files.set(path, { path, contentType: JSON_TYPE, source: { kind: "content", body: JSON.stringify(sources ?? []) } });
+    }
+  }
+  return { files, scan };
+}
+
+/** 把站点产物清单写盘(`--out`)。输入本身已是导出布局(对上次导出的目录重新生成)时原文件不自拷。 */
+export async function writeSite(plan: SitePlan, outDir: string): Promise<void> {
+  for (const file of plan.files.values()) {
+    const dest = join(outDir, file.path);
+    await mkdir(dirname(dest), { recursive: true });
+    if (file.source.kind === "content") {
+      await writeFile(dest, file.source.body, "utf-8");
+    } else if (resolve(file.source.abs) !== resolve(dest)) {
+      await copyFile(file.source.abs, dest);
+    }
+  }
+}
+
+/** 取清单中一个文件的字节(server 响应体与写盘内容同源;file 类缺失时返回 undefined,由宿主 404)。 */
+export async function readSiteFile(file: SiteFile): Promise<string | Buffer | undefined> {
+  if (file.source.kind === "content") return file.source.body;
+  try {
+    // 原字节读取:assets/ 里的 head 资产可以是二进制(favicon、字体),不能按 utf-8 解码。
+    return await readFile(file.source.abs);
+  } catch {
+    return undefined;
+  }
+}
+
+/** head 资产的响应 content-type;命不中的按二进制下发(写盘路径不受影响)。 */
+const ASSET_CONTENT_TYPES: Record<string, string> = {
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".json": JSON_TYPE,
+};
+
+function escapeAttrValue(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+/** 单个 head 标签 → HTML:attrs 值 true 渲染裸布尔属性,字符串转义后渲染 `key="value"`;script/style 的 children 原样落进标签(闭合序列已在装载期拒绝)。 */
+function renderHeadTagHtml(tag: ResolvedHeadTag, attrs: Record<string, string | true>): string {
+  const attrHtml = Object.entries(attrs)
+    .map(([name, value]) => (value === true ? ` ${name}` : ` ${name}="${escapeAttrValue(value)}"`))
+    .join("");
+  if (tag.tag === "meta" || tag.tag === "link") return `<${tag.tag}${attrHtml}>`;
+  return `<${tag.tag}${attrHtml}>${tag.children ?? ""}</${tag.tag}>`;
+}
+
+/**
+ * head 标签落成 HTML,本地 src/href 资产进站点清单:`assets/<sha256><ext>`,
+ * source 指向原文件(写盘 copyFile、server 原字节下发都二进制安全),标签属性回填该相对路径。
+ * 外链(http(s)://)原样透传,不进 assets/。
+ */
+async function materializeHeadAssets(head: ResolvedHeadTag[], files: Map<string, SiteFile>): Promise<string> {
+  const rendered: string[] = [];
+  for (const tag of head) {
+    const attrs = { ...tag.attrs };
+    if (tag.localAsset) {
+      const bytes = await readFile(tag.localAsset.abs);
+      const sha256 = createHash("sha256").update(bytes).digest("hex");
+      const path = `assets/${sha256}${tag.localAsset.ext}`;
+      files.set(path, {
+        path,
+        contentType: ASSET_CONTENT_TYPES[tag.localAsset.ext.toLowerCase()] ?? "application/octet-stream",
+        source: { kind: "file", abs: tag.localAsset.abs },
+      });
+      attrs[tag.localAsset.attr] = path;
+    }
+    rendered.push(renderHeadTagHtml(tag, attrs));
+  }
+  return rendered.join("\n");
+}
+
+const TEMPLATE_PLACEHOLDERS = {
+  styles: "<!-- __NICEEVAL_STYLES__ -->",
+  appCode: "__NICEEVAL_APP_CODE__",
+  viewData: "__NICEEVAL_VIEW_DATA_JSON__",
+  reportSlot: "<!-- __NICEEVAL_REPORT_SLOT__ -->",
+} as const;
+
+/**
+ * 把 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 注入在官方样式之后、head 标签(headHtml,
+ * 由站点管线物化本地资产后渲染)在外壳 styles 之后、scripts 注入在官方增强脚本之后
+ * </body> 前,均按声明顺序(docs/feature/reports/library/shell.md)。
+ * 前端只把当前页 / 当前界面语言对应的块摆进报告槽位置,不解析。
+ */
+export async function renderHtml(scan: ViewScan, headHtml = ""): 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 +
+        (headHtml ? `\n${headHtml}` : ""),
+    )
+    .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>`);
+}
+
+async function readViewAsset(name: string): Promise<string> {
+  return readFile(new URL(name, import.meta.url), "utf-8");
+}

package/src/view/styles.css

@@ -673,6 +673,14 @@ details.span-d > summary.trace-row:hover { background: color-mix(in oklch, var(-
   color: var(--bad);
   font-size: 12.5px;
 }
+.ts-skill {
+  font-size: 12px;
+}
+.ts-raw .ts-tool { color: var(--soft); }
+.ts-skill .ts-text {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: var(--muted);
+}
 .ts-compaction {
   text-align: center;
   font-size: 11px;
@@ -925,6 +933,8 @@ a.brand:hover { opacity: 0.75; }
 .reply-tool-name { color: var(--warn); }
 .reply-tool-out { color: var(--muted); }
 .reply-err { color: var(--bad); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.reply-skill { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; color: var(--muted); }
+.reply-user .reply-text { color: var(--muted); white-space: pre-wrap; word-break: break-word; }
 .reply-empty { color: var(--soft); }
 
 .assert-detail { display: flex; flex-direction: column; gap: 9px; }

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

@@ -23,7 +23,7 @@ import { afterEach, describe, expect, it } from "vitest";
 // `instanceof`-incompatible class.
 import { ReportLoadError } from "../../dist/report/load.js";
 import { ViewInputError, loadViewScan, type ViewScan } from "./data.ts";
-import { renderHtml } from "./server.ts";
+import { renderHtml } from "./site.ts";
 import { buildView, resolveViewInput } from "./index.ts";
 import { runShow } from "../show/index.ts";
 import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION, type EvalResult, type Verdict } from "../types.ts";