niceeval 0.7.1 → 0.8.1

package/docs-site/zh/reference/report-components.mdx

@@ -211,7 +211,7 @@ inspect: niceeval show @<id> [--eval|--execution|--diff]
 每项固定代表一个 Attempt，显示 experiment、Eval、Attempt 序号、判定、耗时、成本、失败断言、结构化 error 的一层摘要、Judge 评语和证据链接。diagnostics、cause 和 stack 留给 locator 下钻详情，避免比较列表被基础设施日志撑开。它既能列失败证据，也能列通过样本，不把 verdict 过滤写死在组件名里。
 
 ```tsx
-const attempts = await AttemptList.data(selection, { redact });
+const attempts = await AttemptList.data(selection);
 
 <AttemptList
   items={attempts.filter((item) => item.verdict === "failed" || item.verdict === "errored")}
@@ -234,7 +234,7 @@ inspect: niceeval show @<id> [--eval|--execution|--diff]
 (3 more not shown · showing 20 of 23)
 ```
 
-要在页面显示前遮蔽 error message/cause/stack、diagnostic message/data、断言 detail 或 Judge 评语，把 `redact` 交给 `.data()`；稳定 code、lifecycle operation、experiment、Eval 和 locator 不改。它只影响这份组件数据，管不到发布目录里的 artifact 文件——发布数据集的消毒用 [`copySnapshots` 的 `redact` 选项](/zh/reference/results-data)。要展示哪些 Attempt，过滤返回的 `AttemptListItem[]`。`limit` 也由报告作者在数组上用 `.slice(0, 20)` 表达，截断时把原始数量交给组件的 `total`，组件据此显示“还有 n 项未展示”，不静默截断。
+要展示哪些 Attempt，过滤返回的 `AttemptListItem[]`。`limit` 也由报告作者在数组上用 `.slice(0, 20)` 表达，截断时把原始数量交给组件的 `total`，组件据此显示“还有 n 项未展示”，不静默截断。
 
 ## 指标表（`MetricTable`）
 

package/docs-site/zh/reference/results-data.mdx

@@ -235,9 +235,7 @@ import { openResults, copySnapshots } from "niceeval/results";
 const results = await openResults(".niceeval");
 await copySnapshots(results.latest(), "site-data/run", {
   artifacts: ["sources", "events", "trace", "o11y"],   // diff 不截断,缺省也不带;
-  redact: (text) => text.replaceAll(/sk-[A-Za-z0-9]+/g, "[redacted]"),
-});                                                     // redact 必填:函数消毒,或 false 显式声明原文发布;
-                                                        // 每个待发布文件还会经过 50 MiB 预检;
+});                                                     // 每个待发布文件还会经过 50 MiB 预检;
                                                         // o11y 只有几 KB,报告用到 turns 这类
                                                         // 读 o11y 的指标就把它带上,不然渲染成「—」
 ```
@@ -246,7 +244,7 @@ await copySnapshots(results.latest(), "site-data/run", {
 
 复制开始前，NiceEval 会规划全部目标文件并检查序列化后的大小。任一文件超过固定的 50 MiB，整次复制在创建目标目录前失败，错误会列出路径、实际大小和处理建议。你可以从 `artifacts` 排除那类证据；如果是旧版本留下的超大 events / trace，用当前版本重跑后再发布。这个检查既覆盖没有逐值截断的源码 / diff，也覆盖单值都正常但累计过大的 JSON，避免直到 `git push` 才撞上 Git host 的单文件限制。
 
-大小预检只决定整次复制成功或失败，不会从一个超大文件中间删内容。消毒不是可选项——`copySnapshots` 要求显式传 `redact`：给一个函数就改写复制出来的所有文件里的自由文本（events、trace、源码、diff、运行摘要都在内；id、事件类型这类标识字段不动），确定这批数据可以原文公开就传 `redact: false`，两个都不传会直接报错。注意报告积木 `AttemptList.data` 的 `redact` 只影响页面上显示的数据，管不到发布目录里的 artifact 文件；发布场景一律在 `copySnapshots` 这一步消毒。唯一随行补记的是挑选时的**覆盖事实**：`partial-coverage` 警告的分母是实验的历史并集，而发布目录没有历史——所以每个复制出的快照带上 `knownEvalIds`（复制时刻该实验已知的 eval 并集），reader 端把它并进 `exp.evalIds` 的计算（取本地历史与快照携带值的并集）。发布目录上重新 `openResults().latest()`，残缺警告被同一套机制重新算出来，不靠发布者转述。复制出的目录就是标准结果目录，`niceeval view --run <目录>` 直接能看；要让报告站随 push 自动更新，workflow 见[通过 CI 发布报告](/zh/how-to/publish-report)。
+大小预检只决定整次复制成功或失败，不会从一个超大文件中间删内容。复制忠实于源：artifact 按原字节复制，不重新序列化、不改写。唯一随行补记的是挑选时的**覆盖事实**：`partial-coverage` 警告的分母是实验的历史并集，而发布目录没有历史——所以每个复制出的快照带上 `knownEvalIds`（复制时刻该实验已知的 eval 并集），reader 端把它并进 `exp.evalIds` 的计算（取本地历史与快照携带值的并集）。发布目录上重新 `openResults().latest()`，残缺警告被同一套机制重新算出来，不靠发布者转述。复制出的目录就是标准结果目录，`niceeval view --results <目录>` 直接能看；要让报告站随 push 自动更新，workflow 见[通过 CI 发布报告](/zh/how-to/publish-report)。
 
 ## 分层速览
 

package/docs-site/zh/troubleshooting/debugging.mdx

@@ -190,8 +190,8 @@ niceeval view
 **打开归档或别人发来的结果。** 结果目录是自包含的——从 CI 下载的、同事拷给你的、发布到静态站前生成的目录，都能直接指过去：
 
 ```bash
-niceeval show --run tmp/ci-artifacts/results
-niceeval view --run site-data/run
+niceeval show --results tmp/ci-artifacts/results
+niceeval view --results site-data/run
 ```
 
 一个注意点：如果本地清理过旧快照目录，之后的运行里「沿用上次结果」的条目会找不到原始证据（显示为缺失）。要长期归档某次运行，先用 [`copySnapshots`](/zh/reference/results-data) 复制出一份再删。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -83,10 +83,6 @@
   },
   "devDependencies": {
     "@ai-sdk/otel": "^1.0.9",
-    "@vercel/sandbox": "^2.2.1",
-    "braintrust": "^3.20.0",
-    "dockerode": "^4.0.2",
-    "e2b": "^2.31.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
     "@opentelemetry/sdk-trace-node": "^2.8.0",
     "@radix-ui/react-collapsible": "^1.1.14",
@@ -98,9 +94,15 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@types/tar-stream": "^3.1.3",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "@vercel/sandbox": "^2.2.1",
     "@vitejs/plugin-react": "^6.0.3",
+    "braintrust": "^3.20.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "dockerode": "^4.0.2",
+    "e2b": "^2.31.0",
+    "jsdom": "^29.1.1",
     "lucide-react": "^1.21.0",
     "mixpanel-browser": "^2.80.0",
     "next": "16.2.10",
@@ -112,7 +114,6 @@
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "@typescript/native": "npm:typescript@^7.0.2",
     "vite": "^8.1.0",
     "vitest": "^4.1.9"
   },

package/src/cli.ts

@@ -105,7 +105,6 @@ interface Flags {
   timing?: "summary" | "full";
   keepSandbox?: "failed" | "all";
   all: boolean;
-  allowSensitiveArtifacts: boolean;
   window?: string;
   sandboxPath?: string;
   leaveRunning: boolean;
@@ -156,8 +155,6 @@ const FLAG_OPTIONS = {
   out: { type: "string" },
   /** `view` 命令专用:指定本地服务器监听端口。 */
   port: { type: "string" },
-  /** `view --out` 专用:对非发布根(快照没有 publish:{redaction:"applied"} 标记)导出时的显式确认——静态站会原样携带未消毒的证据文件。 */
-  "allow-sensitive-artifacts": { type: "boolean" },
   // show 的证据切面 / 时间轴 / 报告装载(docs-site/zh/how-to/viewing-results.mdx)。
   // 证据切面只认 `@<locator>`(或收窄到单个 eval 的前缀)选出的那一个 attempt——不再有
   // 数字 `--attempt`,选哪个 attempt 由 locator 精确指名,不是「先选 eval 再挑第几次」。
@@ -307,7 +304,6 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     timing: values.timing === true ? (timingMode ?? "summary") : undefined,
     keepSandbox: values["keep-sandbox"] === true ? (keepSandboxTier ?? "failed") : undefined,
     all: values.all === true,
-    allowSensitiveArtifacts: values["allow-sensitive-artifacts"] === true,
     window: values.window as string | undefined,
     sandboxPath: values.path as string | undefined,
     leaveRunning: values["leave-running"] === true,
@@ -591,7 +587,7 @@ async function main(): Promise<void> {
       ...(flags.page !== undefined ? { page: flags.page } : {}),
     };
     if (flags.out) {
-      const out = await buildView({ input: viewInput.input, out: flags.out, allowSensitiveArtifacts: flags.allowSensitiveArtifacts, scan }).catch(exitOnViewUserError);
+      const out = await buildView({ input: viewInput.input, out: flags.out, scan }).catch(exitOnViewUserError);
       process.stdout.write(t("cli.view.exportedDir", { out }));
       process.exit(0);
     }

package/src/context/context.ts

@@ -165,7 +165,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     return brief(value, 4000);
   }
 
-  /** 失败断言的 evidence:被检查值自带命令摘要(CommandResult.command)时就是「命令行本身」。 */
+  /** evidence 不区分 pass/fail(与 judge 同口径):被检查值自带命令摘要(CommandResult.command)时就是「命令行本身」。 */
   function checkedValueEvidence(value: unknown): string | undefined {
     const command = asCommandResult(value)?.command;
     return typeof command === "string" && command.length > 0 ? command : undefined;
@@ -378,12 +378,15 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
         evaluate: async (sc) => {
           const resolved = await resolveValue(value, sc);
           const score = await assertion.score(resolved);
-          if (computePassed(spec.severity, spec.threshold, score)) return score;
+          const evidence = checkedValueEvidence(resolved);
+          if (computePassed(spec.severity, spec.threshold, score)) {
+            return evidence !== undefined ? { score, evidence } : score;
+          }
           return {
             score,
             expected: assertion.expected,
             received: previewCheckedValue(resolved),
-            ...(checkedValueEvidence(resolved) !== undefined ? { evidence: checkedValueEvidence(resolved) } : {}),
+            ...(evidence !== undefined ? { evidence } : {}),
           };
         },
       };
@@ -395,18 +398,21 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
       const score = await assertion.score(v);
       // require 恒为硬门槛(不过即中止 eval),判定口径与 finalize 同一份 computePassed。
       const passed = computePassed("gate", assertion.threshold, score);
+      const evidence = checkedValueEvidence(v);
       collector.record({
         name: assertion.name,
         severity: "gate",
         threshold: assertion.threshold,
         evaluate: () =>
           passed
-            ? score
+            ? evidence !== undefined
+              ? { score, evidence }
+              : score
             : {
                 score,
                 expected: assertion.expected,
                 received: previewCheckedValue(v),
-                ...(checkedValueEvidence(v) !== undefined ? { evidence: checkedValueEvidence(v) } : {}),
+                ...(evidence !== undefined ? { evidence } : {}),
               },
       });
       if (!passed) throw new EvalRequirementFailed(assertion.name);

package/src/report/components.tsx

@@ -26,7 +26,6 @@ import type { AttemptLocator } from "../results/locator.ts";
 import type {
   AttemptListItem,
   DeltaData,
-  EntityListDataOptions,
   EvalListItem,
   ExperimentComparisonData,
   ExperimentListItem,
@@ -400,7 +399,7 @@ interface EntityListChrome extends ChromeProps {
 
 export type ExperimentListProps = DataProps<
   readonly ExperimentListItem[],
-  EntityListDataOptions,
+  Record<never, never>,
   EntityListChrome & {
     /** web 面在比较表前显示实验过滤框;text 面忽略。 */
     filter?: boolean;
@@ -415,14 +414,14 @@ export type ExperimentListProps = DataProps<
 /** 实验列表:每项一个 experiment,固定八列比较表 + 展开到 Eval / Attempt。 */
 export const ExperimentList = makeDataComponent<
   readonly ExperimentListItem[],
-  EntityListDataOptions,
+  Record<never, never>,
   EntityListChrome & { filter?: boolean; relativeTo?: string }
 >({
   name: "ExperimentList",
   dataFnName: "experimentListData",
   shapeName: "ExperimentListItem[]",
-  dataFn: (input, options) => experimentListData(input, options),
-  specKeys: ["redact"],
+  dataFn: (input) => experimentListData(input),
+  specKeys: [],
   validate: validateExperimentListData,
   web: (props, ctx) => (
     <ExperimentListWeb
@@ -437,15 +436,15 @@ export const ExperimentList = makeDataComponent<
   text: (props, ctx) => experimentListText(props.data, ctx, props.relativeTo),
 }) as unknown as ReportComponent<ExperimentListProps>;
 
-export type EvalListProps = DataProps<readonly EvalListItem[], EntityListDataOptions, EntityListChrome>;
+export type EvalListProps = DataProps<readonly EvalListItem[], Record<never, never>, EntityListChrome>;
 
 /** Eval 列表:每项一个 experimentId + evalId,展开到这道题的 Attempt。 */
-export const EvalList = makeDataComponent<readonly EvalListItem[], EntityListDataOptions, EntityListChrome>({
+export const EvalList = makeDataComponent<readonly EvalListItem[], Record<never, never>, EntityListChrome>({
   name: "EvalList",
   dataFnName: "evalListData",
   shapeName: "EvalListItem[]",
-  dataFn: (input, options) => evalListData(input, options),
-  specKeys: ["redact"],
+  dataFn: (input) => evalListData(input),
+  specKeys: [],
   validate: validateEvalListData,
   web: (props, ctx) => (
     <EvalListWeb
@@ -460,7 +459,7 @@ export const EvalList = makeDataComponent<readonly EvalListItem[], EntityListDat
 
 export type AttemptListProps = DataProps<
   readonly AttemptListItem[],
-  EntityListDataOptions,
+  Record<never, never>,
   EntityListChrome & {
     /** 过滤 / 截断前的总数;省略时等于 data 长度。 */
     total?: number;
@@ -470,14 +469,14 @@ export type AttemptListProps = DataProps<
 /** Attempt 列表:实体列表的叶子层,每项一次 attempt 的判定、单行摘要与 locator。 */
 export const AttemptList = makeDataComponent<
   readonly AttemptListItem[],
-  EntityListDataOptions,
+  Record<never, never>,
   EntityListChrome & { total?: number }
 >({
   name: "AttemptList",
   dataFnName: "attemptListData",
   shapeName: "AttemptListItem[]",
-  dataFn: (input, options) => attemptListData(input, options),
-  specKeys: ["redact"],
+  dataFn: (input) => attemptListData(input),
+  specKeys: [],
   validate: validateAttemptListData,
   web: (props, ctx) => (
     <AttemptListWeb
@@ -498,7 +497,6 @@ export interface FailureListProps {
   limit?: number;
   /** 默认宿主注入的 Scope。 */
   input?: ReportInput;
-  redact?: (text: string) => string;
   attemptHref?: (locator: AttemptLocator) => string;
   locale?: ReportLocale;
   className?: string;
@@ -512,7 +510,7 @@ export interface FailureListProps {
  */
 export const FailureList = defineComponent<FailureListProps>(async (props, ctx) => {
   const input = props.input ?? ctx.scope;
-  const all = await attemptListData(input, props.redact !== undefined ? { redact: props.redact } : undefined);
+  const all = await attemptListData(input);
   // attempt 开始时间不在列表条目里(它不是列表展示字段);从同一 input 的读取面按 locator 对回。
   const startedAtByLocator = new Map<string, string>();
   for (const item of collectItems(resolveInput(input).snapshots)) {

package/src/report/compute.ts

@@ -17,7 +17,6 @@ import type {
   DeltaData,
   DeltaPair,
   DimensionInput,
-  EntityListDataOptions,
   EvalListItem,
   ExperimentComparisonData,
   ExperimentComparisonGroupData,
@@ -199,10 +198,8 @@ function failureSummaryOf(result: EvalResult): { summary: string | null; more: n
   return { summary: null, more: 0 };
 }
 
-const identityRedact = (text: string): string => text;
-
 /** AttemptList / ExperimentList / EvalList 共用的叶子构造:一个 Item → 一个 AttemptListItem。 */
-async function attemptListItemOf(item: Item, redact: (text: string) => string): Promise<AttemptListItem> {
+async function attemptListItemOf(item: Item): Promise<AttemptListItem> {
   const result = item.attempt.result;
   const { summary, more } = failureSummaryOf(result);
   return {
@@ -211,7 +208,7 @@ async function attemptListItemOf(item: Item, redact: (text: string) => string):
     attempt: result.attempt,
     agent: result.agent,
     verdict: result.verdict,
-    failureSummary: summary === null ? null : redact(summary),
+    failureSummary: summary,
     moreFailures: more,
     examScore: await computeCell(examScore, [item]),
     durationMs: result.durationMs,
@@ -221,20 +218,15 @@ async function attemptListItemOf(item: Item, redact: (text: string) => string):
 }
 
 /** `attemptListData(input)`:每个 Attempt 一项,顺序取自 Scope 展平顺序(不重排)。 */
-export async function attemptListData(
-  input: ReportInput,
-  options?: EntityListDataOptions,
-): Promise<AttemptListItem[]> {
+export async function attemptListData(input: ReportInput): Promise<AttemptListItem[]> {
   const { snapshots } = resolveInput(input);
-  const redact = options?.redact ?? identityRedact;
   const items = collectItems(snapshots);
-  return Promise.all(items.map((item) => attemptListItemOf(item, redact)));
+  return Promise.all(items.map((item) => attemptListItemOf(item)));
 }
 
 /** `evalListData(input)`:每个 `experimentId + evalId` 一项,按 evalId 再按 experimentId 升序。 */
-export async function evalListData(input: ReportInput, options?: EntityListDataOptions): Promise<EvalListItem[]> {
+export async function evalListData(input: ReportInput): Promise<EvalListItem[]> {
   const { snapshots } = resolveInput(input);
-  const redact = options?.redact ?? identityRedact;
   const items = collectItems(snapshots);
   const groups = new Map<string, Item[]>();
   for (const item of items) {
@@ -247,7 +239,7 @@ export async function evalListData(input: ReportInput, options?: EntityListDataO
   for (const group of groups.values()) {
     const sorted = [...group].sort((a, b) => a.attempt.result.attempt - b.attempt.result.attempt);
     const verdict = foldEvalVerdict(sorted.map((item) => item.attempt.result));
-    const attempts = await Promise.all(sorted.map((item) => attemptListItemOf(item, redact)));
+    const attempts = await Promise.all(sorted.map((item) => attemptListItemOf(item)));
     out.push({
       experimentId: experimentIdOf(sorted[0]!),
       evalId: evalIdOf(sorted[0]!),
@@ -269,12 +261,8 @@ export async function evalListData(input: ReportInput, options?: EntityListDataO
  * Snapshot[] 时若同一 experiment 混入不一致的可比性配置,按完整用户反馈失败并指引——
  * 看跨配置演化用 snapshot 维度或 MetricLine,不把两套配置拼成一行冒充单一配置。
  */
-export async function experimentListData(
-  input: ReportInput,
-  options?: EntityListDataOptions,
-): Promise<ExperimentListItem[]> {
+export async function experimentListData(input: ReportInput): Promise<ExperimentListItem[]> {
   const { snapshots } = resolveInput(input);
-  const redact = options?.redact ?? identityRedact;
 
   // 可比性配置单义检查:同一 experiment 的输入快照必须共享一套可比性配置。
   const configByExperiment = new Map<string, { snapshot: Snapshot; config: unknown }>();
@@ -304,7 +292,7 @@ export async function experimentListData(
     for (const [evalId, evalItems] of evalGroups) {
       const sorted = [...evalItems].sort((a, b) => a.attempt.result.attempt - b.attempt.result.attempt);
       const verdict = foldEvalVerdict(sorted.map((item) => item.attempt.result));
-      const attempts = await Promise.all(sorted.map((item) => attemptListItemOf(item, redact)));
+      const attempts = await Promise.all(sorted.map((item) => attemptListItemOf(item)));
       evalRows.push({
         evalId,
         verdict,

package/src/report/index.ts

@@ -40,6 +40,7 @@ export type {
   RenderReportTextOptions,
   RenderTreeTextOptions,
   ReportTreeHostContext,
+  HeadTag,
   ReportAsset,
   ReportDef,
   ReportDefinition,
@@ -167,7 +168,6 @@ export type {
   DimensionInput,
   DimensionOptions,
   DimensionRef,
-  EntityListDataOptions,
   EvalListItem,
   ExperimentComparisonData,
   ExperimentComparisonGroupData,

package/src/report/report.test.ts

@@ -3,8 +3,8 @@
 // niceeval/results 的读取契约手工构造)。覆盖登记行:两级聚合 vs 平铺、errored=0 口径、
 // skipped=null、null≠0、Scoreboard 固定分母(notRun/unscorable 分开)、权重最长前缀、
 // 身份键去重、现刻水位、自定义指标 where/aggregate、evalGroup 完整父路径、verdict 权威、
-// MetricCell 诚实、缺 artifact 指标、repeatedFailedCommands、实体列表 failureSummary /
-// redact、scopeSummaryData 两级计票、experimentComparisonData 分区、pairsByFlag、
+// MetricCell 诚实、缺 artifact 指标、repeatedFailedCommands、实体列表 failureSummary、
+// scopeSummaryData 两级计票、experimentComparisonData 分区、pairsByFlag、
 // MetricLine 点身份、空数组反馈、metricTableData sort。
 
 import { describe, expect, it } from "vitest";
@@ -595,24 +595,6 @@ describe("实体列表 data", () => {
     expect(byEval.get("list/errored")!.costUSD).toBeNull();
   });
 
-  it("redact 只改写 failureSummary(含嵌套 attempt 条目);身份字段、locator 与数值指标原样", async () => {
-    const redact = (text: string) => text.replaceAll("41", "[redacted]");
-    const attempts = await attemptListData([listSnap()], { redact });
-    const failedItem = attempts.find((item) => item.evalId === "list/failed")!;
-    expect(failedItem.failureSummary).toContain("[redacted]");
-    expect(failedItem.evalId).toBe("list/failed");
-    expect(failedItem.experimentId).toBe("exp/list");
-    expect(failedItem.costUSD).toBe(0.1);
-
-    const evals = await evalListData([listSnap()], { redact });
-    const nested = evals.find((item) => item.evalId === "list/failed")!.attempts[0]!;
-    expect(nested.failureSummary).toContain("[redacted]");
-
-    const experiments = await experimentListData([listSnap()], { redact });
-    const nestedInExp = experiments[0]!.evalRows.find((row) => row.evalId === "list/failed")!.attempts[0]!;
-    expect(nestedInExp.failureSummary).toContain("[redacted]");
-  });
-
   it("experimentListData:evalVerdicts / endToEndPassRate / costUSD / durationMs / tokens 齐全,默认按端到端成功率降序", async () => {
     const winner = snap({ experimentId: "exp/win", results: [res("a", "passed"), res("b", "passed")] });
     const loser = snap({ experimentId: "exp/lose", results: [res("a", "failed"), res("b", "passed")] });

package/src/report/report.ts

@@ -1,4 +1,4 @@
-// defineReport:唯一可被宿主装载的产物 —— 一层外壳(标题、外链、页脚、脚本、样式)加
+// defineReport:唯一可被宿主装载的产物 —— 一层外壳(标题、外链、页脚、head 标签、脚本、样式)加
 // 非空页列表;单页与多页不是两种机制,页数只是列表长度(docs/feature/reports/library/shell.md)。
 // 入参有两级缩写,各有精确展开:树入参 ≡ { content: 树 } ≡ pages: [{ id: "report",
 // title: 内置页名, content: 树 }]。`content` 与 `pages` 恰好声明一个,没有隐式默认。
@@ -40,6 +40,16 @@ export interface ReportLink {
 /** src 是相对顶层报告文件的路径;两种形态不可同时出现。 */
 export type ReportAsset = { src: string; inline?: never } | { inline: string; src?: never };
 
+/**
+ * 结构化 head 标签。tag 是白名单闭集——head 是元数据与第三方脚本的注入口,不是 HTML 后门。
+ * attrs 值为 true 渲染裸布尔属性(async、defer),字符串渲染 `key="value"`(值转义后落 HTML);
+ * 属性语义与脚本内容同一约定——作者义务,宿主不校验。
+ * meta / link 无子内容由类型表达;script / style 的 children 是原样文本,不转义。
+ */
+export type HeadTag =
+  | { tag: "meta" | "link"; attrs: Record<string, string | true>; children?: never }
+  | { tag: "script" | "style"; attrs?: Record<string, string | true>; children?: string };
+
 export interface ReportShell {
   /** 标题:首页 hero 与浏览器标题。页头左端是恒定的 NiceEval 品牌字标,不由 title 覆盖;回退链 def.title → 唯一快照 name → 内置文案「Eval 运行结果 / Eval Results」。 */
   title?: LocalizedText;
@@ -47,6 +57,12 @@ export interface ReportShell {
   links?: ReportLink[];
   /** 每页页脚的一段文字;省略时不渲染页脚(品牌行恒在 hero 下方,不占页脚)。 */
   footer?: LocalizedText;
+  /**
+   * 注入每页 `<head>` 的结构化标签,在官方与外壳样式之后按声明顺序渲染。
+   * 第三方 snippet(分析、埋点、评论)、SEO meta、favicon、字体、JSON-LD 的家:
+   * 声明什么标签就渲染什么标签,宿主只做结构校验,新的第三方接入不需要契约变更。
+   */
+  head?: HeadTag[];
   /** 注入每个页面的脚本,在官方增强脚本之后、按声明顺序于 </body> 前加载。 */
   scripts?: ReportAsset[];
   /** 注入每个页面的样式表,在官方样式之后按声明顺序加载。 */
@@ -76,13 +92,14 @@ const REPORT_DEFINITION: unique symbol = Symbol.for("niceeval.report.definition"
 /**
  * defineReport 的唯一产物:只作 --report 文件的默认导出,交给宿主装载。
  * 它不是 ReportNode——不能放进任何 content 或报告树,外壳因此不可嵌套。
- * 字段是装载规范化后的形态:pages 恒非空,links / scripts / styles 恒为数组。
+ * 字段是装载规范化后的形态:pages 恒非空,links / head / scripts / styles 恒为数组。
  */
 export interface ReportDefinition {
   readonly kind: "report";
   readonly title?: LocalizedText;
   readonly links: readonly ReportLink[];
   readonly footer?: LocalizedText;
+  readonly head: readonly HeadTag[];
   readonly scripts: readonly ReportAsset[];
   readonly styles: readonly ReportAsset[];
   readonly pages: NonEmptyArray<ReportPage>;
@@ -161,6 +178,16 @@ function assertLocalizedText(value: unknown, where: string): asserts value is Lo
 
 const PAGE_ID_PATTERN = /^[a-z0-9-]+$/;
 
+/** 本地资产路径纪律(shell.md「行为约束」):相对报告文件的普通相对路径,拒绝 `..` 段、绝对路径与 `~`。 */
+function assertLocalAssetPath(src: string, where: string): void {
+  const segments = src.split(/[\\/]+/);
+  if (src.startsWith("/") || /^[A-Za-z]:/.test(src) || src.startsWith("~") || segments.includes("..")) {
+    throw new Error(
+      `defineReport ${where} "${src}" is not allowed: only plain relative paths (optionally with a ./ prefix) resolve against the report file — no ".." segments, absolute paths, or "~". Move the asset next to the report file and reference it relatively.`,
+    );
+  }
+}
+
 function assertAssets(assets: unknown, field: "scripts" | "styles"): ReportAsset[] {
   if (assets === undefined) return [];
   if (!Array.isArray(assets)) {
@@ -176,17 +203,111 @@ function assertAssets(assets: unknown, field: "scripts" | "styles"): ReportAsset
     }
     if (hasSrc) {
       const src = asset.src as string;
-      const segments = src.split(/[\\/]+/);
-      if (src.startsWith("/") || /^[A-Za-z]:/.test(src) || src.startsWith("~") || segments.includes("..")) {
+      // 外链不属于增强层资产:第三方外链标签的家是 head 通道。
+      if (/^https?:\/\//i.test(src) || src.startsWith("//")) {
         throw new Error(
-          `defineReport ${field} src "${src}" is not allowed: only plain relative paths (optionally with a ./ prefix) resolve against the report file — no ".." segments, absolute paths, or "~". Move the asset next to the report file and reference it relatively.`,
+          `defineReport ${field} src "${src}" is an external URL — ${field} take local files and inline content (the host pipeline vendors them). Declare third-party external tags in "head" instead, e.g. head: [{ tag: "script", attrs: { async: true, src: "…" } }].`,
         );
       }
+      assertLocalAssetPath(src, `${field} src`);
     }
   }
   return assets as ReportAsset[];
 }
 
+const HEAD_TAG_NAMES = new Set(["meta", "link", "script", "style"]);
+const HEAD_ATTR_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_.:-]*$/;
+
+function assertHeadTags(tags: unknown): HeadTag[] {
+  if (tags === undefined) return [];
+  if (!Array.isArray(tags)) {
+    throw new Error(
+      'defineReport head must be an array of { tag, attrs?, children? } entries (tag: "meta" | "link" | "script" | "style").',
+    );
+  }
+  for (const entry of tags as Array<Record<string, unknown>>) {
+    const tag = entry?.tag;
+    // 白名单闭集:head 是元数据与第三方脚本的注入口,不是 HTML 后门;标题走 title 字段回退链。
+    if (typeof tag !== "string" || !HEAD_TAG_NAMES.has(tag)) {
+      throw new Error(
+        `defineReport head tag ${JSON.stringify(tag)} is not allowed — head injects metadata and third-party tags, and the allowed tags are "meta", "link", "script", "style". For the document title, use the shell "title" field instead.`,
+      );
+    }
+    const attrs = entry.attrs;
+    if (attrs !== undefined && (typeof attrs !== "object" || attrs === null || Array.isArray(attrs))) {
+      throw new Error(
+        `defineReport head <${tag}> attrs must be a { name: string | true } record (true renders a bare boolean attribute like async).`,
+      );
+    }
+    if ((tag === "meta" || tag === "link") && attrs === undefined) {
+      throw new Error(
+        `defineReport head <${tag}> needs attrs — a bare <${tag}> renders nothing. Declare e.g. { tag: "${tag}", attrs: { ${tag === "meta" ? 'name: "…", content: "…"' : 'rel: "…", href: "…"'} } }.`,
+      );
+    }
+    const attrRecord = (attrs ?? {}) as Record<string, unknown>;
+    for (const [name, value] of Object.entries(attrRecord)) {
+      if (!HEAD_ATTR_NAME_PATTERN.test(name)) {
+        throw new Error(
+          `defineReport head <${tag}> attribute name ${JSON.stringify(name)} is not a valid HTML attribute name. Use letters, digits, "-", "_", ":" or ".".`,
+        );
+      }
+      if (value !== true && typeof value !== "string") {
+        throw new Error(
+          `defineReport head <${tag}> attribute "${name}" must be a string or true (true renders a bare boolean attribute like async); got ${typeof value}.`,
+        );
+      }
+    }
+    // 宿主自有的文档单例:charset / viewport 由宿主外壳拥有,声明它们装载报错。
+    if (tag === "meta" && attrRecord.charset !== undefined) {
+      throw new Error(
+        "defineReport head must not declare <meta charset> — the document charset is owned by the host shell. Remove the entry.",
+      );
+    }
+    if (tag === "meta" && typeof attrRecord.name === "string" && attrRecord.name.toLowerCase() === "viewport") {
+      throw new Error(
+        'defineReport head must not declare <meta name="viewport"> — the viewport is owned by the host shell. Remove the entry.',
+      );
+    }
+    const children = entry.children;
+    if (children !== undefined) {
+      if (tag === "meta" || tag === "link") {
+        throw new Error(
+          `defineReport head <${tag}> does not take children — <${tag}> is a void element; put the content in attrs.`,
+        );
+      }
+      if (typeof children !== "string") {
+        throw new Error(
+          `defineReport head <${tag}> children must be a string of literal ${tag === "script" ? "JavaScript" : "CSS"}; got ${typeof children}.`,
+        );
+      }
+      // children 原样落进标签,闭合序列在该上下文无法转义,会提前截断标签。
+      if (children.toLowerCase().includes(`</${tag}`)) {
+        throw new Error(
+          `defineReport head <${tag}> children contain "</${tag}>" — that sequence cannot be escaped inside a <${tag}> and would close the tag early. Split the content into two entries or move it into a local file asset.`,
+        );
+      }
+    }
+    // src / href 按 scheme 分流:http(s) 外链原样透传;其余按本地路径纪律解析。
+    for (const name of ["src", "href"]) {
+      const value = attrRecord[name];
+      if (typeof value !== "string") continue;
+      if (/^https?:\/\//i.test(value)) continue;
+      if (value.startsWith("//")) {
+        throw new Error(
+          `defineReport head <${tag}> ${name} "${value}" is protocol-relative — declare the scheme explicitly, e.g. "https:${value}".`,
+        );
+      }
+      if (/^[a-z][a-z0-9+.-]*:/i.test(value)) {
+        throw new Error(
+          `defineReport head <${tag}> ${name} "${value}" uses a scheme other than http(s) — external head assets must be http(s) URLs. Anything else, ship as a local file next to the report and reference it relatively.`,
+        );
+      }
+      assertLocalAssetPath(value, `head <${tag}> ${name}`);
+    }
+  }
+  return tags as HeadTag[];
+}
+
 export function defineReport(content: ReportNode): ReportDefinition;
 export function defineReport(def: ReportDef): ReportDefinition;
 export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
@@ -196,7 +317,7 @@ export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
     : (input as ReportDef);
   if (typeof def !== "object" || def === null) {
     throw new Error(
-      "defineReport expects a report tree or a config object ({ title?, links?, footer?, scripts?, styles?, content | pages }). " +
+      "defineReport expects a report tree or a config object ({ title?, links?, footer?, head?, scripts?, styles?, content | pages }). " +
         CONTENT_NEXT_STEP,
     );
   }
@@ -273,6 +394,7 @@ export function defineReport(input: ReportNode | ReportDef): ReportDefinition {
     ...(def.title !== undefined ? { title: def.title } : {}),
     links: [...links],
     ...(def.footer !== undefined ? { footer: def.footer } : {}),
+    head: assertHeadTags(def.head),
     scripts: assertAssets(def.scripts, "scripts"),
     styles: assertAssets(def.styles, "styles"),
     pages: pages as unknown as NonEmptyArray<ReportPage>,