niceeval 0.8.1 → 0.9.0

package/src/agents/post-setup.ts

@@ -0,0 +1,33 @@
+// factory 的 postSetup 钩子执行器 —— Claude Code / Codex / Bub 共用。
+// 契约见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」:
+// 在 adapter 全部安装步骤(含 manifest)之后按数组顺序执行;复用 SandboxHook 的窄上下文;
+// 返回的 cleanup 合成一个 LIFO 闭包,由 runner 与 agent teardown 一起收尾;钩子抛错
+// 直接传播(attempt errored)。
+
+import type { Cleanup } from "../shared/types.ts";
+import type { Sandbox, SandboxHook, SandboxHookContext } from "../sandbox/types.ts";
+import type { AgentContext } from "./types.ts";
+
+export async function runPostSetupHooks(
+  sb: Sandbox,
+  ctx: AgentContext,
+  hooks: readonly SandboxHook[] | undefined,
+): Promise<Cleanup | void> {
+  if (!hooks?.length) return;
+  // 窄上下文与沙箱钩子同款:不把 session / model / telemetry 借给过程钩子。
+  const hookCtx: SandboxHookContext = {
+    experimentId: ctx.experimentId,
+    signal: ctx.signal,
+    progress: (update) => ctx.progress(update),
+    diagnostic: (input) => ctx.diagnostic(input),
+  };
+  const cleanups: Cleanup[] = [];
+  for (const hook of hooks) {
+    const cleanup = await hook(sb, hookCtx);
+    if (typeof cleanup === "function") cleanups.push(cleanup);
+  }
+  if (!cleanups.length) return;
+  return async () => {
+    for (const cleanup of [...cleanups].reverse()) await cleanup();
+  };
+}

package/src/agents/types.ts

@@ -7,21 +7,42 @@ import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
 
 /**
- * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,
- * 不是 native plugin 的一种。在 agent factory config 里声明,setup 阶段写进各自的配置文件。
- * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ * 本地 stdio 形态的 MCP server:沙箱内起子进程,按 stdio 说 MCP 协议。
+ * 与 {@link McpHttpServer} 按形状判别(有 `command` 的是 stdio,有 `url` 的是 HTTP)。
  */
-export interface McpServer {
+export interface McpStdioServer {
   /** 服务器唯一名(config key)。 */
   name: string;
   /** 启动命令(如 "npx"、"node"、"uvx")。 */
   command: string;
   /** 传给命令的参数。 */
   args?: string[];
-  /** 注入服务器进程的环境变量。 */
+  /** 注入服务器进程的环境变量(可能含 secret,不进 manifest)。 */
   env?: Record<string, string>;
 }
 
+/**
+ * 远程 Streamable HTTP 形态的 MCP server:沙箱直接连一个 HTTP 端点。
+ * `url` 必须沙箱内可达——宿主机上的服务先经隧道(cloudflared / tailscale 等)暴露。
+ */
+export interface McpHttpServer {
+  /** 服务器唯一名(config key)。 */
+  name: string;
+  /** Streamable HTTP 端点(如 https://mem.example.com/mcp/)。 */
+  url: string;
+  /** 逐字写进每个请求的 HTTP 头(常用于 Authorization;可能含 secret,不进 manifest)。 */
+  headers?: Record<string, string>;
+}
+
+/**
+ * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,
+ * 不是 native plugin 的一种。stdio 与 Streamable HTTP 两种形态按形状判别,不设 kind 标签
+ * (两种形态各有唯一必填判别字段);同时给出 `command` 与 `url` 属配置错误,setup 报错点名。
+ * 在 agent factory config 里声明,setup 阶段写进各自的配置文件。
+ * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ */
+export type McpServer = McpStdioServer | McpHttpServer;
+
 /**
  * Skill 的来源描述 —— Claude Code / Codex / Bub 共用的**数据类型**:只统一「从哪里取得
  * 哪份 Skill」,安装位置、发现机制、要不要额外写 project instruction 由各 Adapter 决定。
@@ -67,8 +88,8 @@ export interface AgentSetupManifest {
     /** 安装后 CLI 报告的版本;取不到时省略。 */
     resolvedVersion?: string;
   }>;
-  /** 挂上的 MCP server(不含 env:secret 不进 manifest)。 */
-  mcpServers?: Array<{ name: string; command: string; args?: string[] }>;
+  /** 挂上的 MCP server(只记非 secret 字段:stdio 不含 env,HTTP 不含 headers)。 */
+  mcpServers?: Array<{ name: string; command: string; args?: string[] } | { name: string; url: string }>;
   /**
    * 官方原生配置文件(Claude Code `settings.json` / Codex `config.toml`):只记 Agent 名、
    * 项目相对来源路径与原始字节的 SHA-256,不落正文 —— 任意官方配置都可能携带敏感字符串,

package/src/cli.ts

@@ -17,7 +17,7 @@ import { planCarry } from "./runner/fingerprint.ts";
 import { failureDetailFromResult } from "./runner/feedback/failure.ts";
 import { stopAllSandboxes, liveSandboxCount } from "./sandbox/registry.ts";
 import { evalLevelStats } from "./shared/verdict.ts";
-import { sandboxRecommendedConcurrency } from "./sandbox/resolve.ts";
+import { prepareRunSandboxes, resolvedSandboxRecommendedConcurrency } from "./runner/sandbox-selection.ts";
 import { Json, JUnit } from "./runner/reporters/json.ts";
 import { Artifacts as ArtifactsReporter } from "./runner/reporters/artifacts.ts";
 import {
@@ -178,7 +178,7 @@ const FLAG_OPTIONS = {
   snapshot: { type: "string" },
   /** `show` / `view` 命令专用:用文件默认导出的 `defineReport(...)` 替换两者共用的默认报告。 */
   report: { type: "string" },
-  /** `show` / `view` 命令专用:选择多页报告的页(页 id 见 `show --report` 的页索引);`view` 里定初始页。 */
+  /** `show` / `view` 命令专用:选择报告的初始页;`show` 渲染该页并在尾部附其余页索引,`view` 以它作初始路由。未命中的页 id 按用法错误退出并列出可用页 id。 */
   page: { type: "string" },
   /** 只打印本次会匹配到的 eval × 运行配置,不实际执行(按下面 `--output` 选中的 profile 给出预览)。 */
   dry: { type: "boolean" },
@@ -468,7 +468,7 @@ function evalsFilterFromExperiment(
 ): (id: string) => boolean {
   const patternFilter = makeFilter(patterns);
   let expFilter: (id: string) => boolean = () => true;
-  if (Array.isArray(evals)) expFilter = (id) => evals.includes(id) || evals.some((e) => id.startsWith(e + "/"));
+  if (Array.isArray(evals)) expFilter = makeFilter(evals);
   else if (typeof evals === "function") expFilter = evals;
   return (id) => expFilter(id) && patternFilter(id);
 }
@@ -771,6 +771,9 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
+  // environments 查表在 dry-run 与真实运行共用的规划边界完成；缺表项在任何沙箱/agent 花费前穷举失败。
+  prepareRunSandboxes(evals, agentRuns, config.sandbox);
+
   if (flags.dry) {
     // --dry 只按所选 profile 打印计划,不运行、不落盘 —— 三种 profile 各自的展示逻辑
     // 都在 runner/feedback/{human,agent,ci}.ts 里,这里只负责拼数据、选函数、写流、退出。
@@ -826,7 +829,7 @@ async function main(): Promise<void> {
   // envelope 展示的"携入"就会和 run.ts 真实调度的"携入"对不上(见 memory 的
   // live-carry-row-shows-waiting-forever)。
   const priorResults = flags.force ? undefined : await loadLatestResultsPerEval(join(cwd, ".niceeval"));
-  const carryPlan = priorResults?.length ? await planCarry(evals, agentRuns, priorResults) : undefined;
+  const carryPlan = priorResults?.length ? await planCarry(evals, agentRuns, priorResults, config.sandbox) : undefined;
   const reusedFailures = (carryPlan?.carriedResults ?? [])
     .map(failureDetailFromResult)
     .filter((failure) => failure !== undefined);
@@ -834,8 +837,7 @@ async function main(): Promise<void> {
   // 无全局默认:并发上限由 sandbox provider 的推荐值决定(多个 agentRun 各有 sandbox 时取
   // 最小值,最保守的 provider 决定上限)。同一个值既进 RunFeedbackPlan.shape,也传给 runEvals——
   // 两处必须是同一个数字,dashboard 展示的并发上限不能和真实调度的并发上限对不上。
-  const sandboxRecs = agentRuns.map((r) => sandboxRecommendedConcurrency(r.sandbox));
-  const sandboxDefaultConcurrency = sandboxRecs.length > 0 ? Math.min(...sandboxRecs) : 10;
+  const sandboxDefaultConcurrency = resolvedSandboxRecommendedConcurrency(evals, agentRuns, config.sandbox);
   const maxConcurrency =
     flags.maxConcurrency ??
     envNumber("NICEEVAL_MAX_CONCURRENCY") ??

package/src/define.ts

@@ -55,6 +55,9 @@ export function defineEval(def: EvalDef): EvalDef {
   if (typeof def.test !== "function") {
     throw new Error(t("define.evalTestRequired"));
   }
+  if (def.environment !== undefined && def.environment.trim().length === 0) {
+    throw new Error(t("define.evalEnvironmentEmpty"));
+  }
   return def;
 }
 

package/src/i18n/en.ts

@@ -24,6 +24,8 @@ export const en = {
   "skill.repoAmbiguous": "Repo skill {{source}} contains multiple skills; select which ones to enable with `skills: [...]`. Available: {{available}}.",
   "skill.repoUnknownSkill": "Repo skill {{source}} (ref: {{ref}}) has no skill named \"{{skill}}\". Available: {{available}}.",
   "skill.copyFailed": "Could not install skill \"{{name}}\" into {{dest}}:\n{{tail}}",
+  "mcp.ambiguousTransport":
+    "MCP server \"{{name}}\" specifies both \"command\" and \"url\" — pick one transport: \"command\" for a local stdio server, \"url\" for a remote Streamable HTTP endpoint.",
   "plugin.marketplaceFailed": "Could not connect {{agent}} marketplace \"{{name}}\" (source: {{source}}, ref: {{ref}}):\n{{tail}}",
   "plugin.marketplaceVerifyFailed": "Could not read back the registered marketplace list after adding {{agent}} marketplace \"{{name}}\" ({{command}}):\n{{tail}}",
   "plugin.marketplaceNameMismatch":
@@ -83,8 +85,8 @@ export const en = {
     "      --diff[=file] sandbox workspace file-change summary; =file expands one file\n" +
     "      --history   per experiment × eval execution timeline (mutually exclusive with --report)\n" +
     "      --results <dir>   pin a results root    --experiment <id>   one experiment\n" +
-    "      --report <file>   custom report    --page <id>   pick a page (multi-page\n" +
-    "        reports print a page index with copyable commands)\n" +
+    "      --report <file>   custom report    --page <id>   pick the initial page (multi-page\n" +
+    "        reports render it, then list the rest as a page index with copyable commands)\n" +
     "  niceeval list                                       list discovered evals\n" +
     "  niceeval view [eval-id-prefix…] [--out dir] [--port n] [--no-open]\n" +
     "      report pages + evidence rooms; --report <file> swaps in your report\n" +
@@ -151,6 +153,7 @@ export const en = {
   "context.turnFailedDefault": "This send returned failed (turn status = failed)",
   "define.agentNameRequired": "defineAgent requires name.",
   "define.evalIdRejected": "defineEval does not accept id; ids are derived from file paths.",
+  "define.evalEnvironmentEmpty": "defineEval environment must be a non-empty profile id when provided.",
   "define.evalTestRequired": "defineEval requires an async test(t) function.",
   "define.experimentAgentRequired": "defineExperiment requires agent.",
   "define.experimentFlagNotJson": "experiment.flags.{{key}} is not JSON-serializable (functions / undefined / cycles / bigint are not allowed); flags are persisted verbatim into result snapshots and must be plain JSON.",

package/src/i18n/zh-CN.ts

@@ -22,6 +22,8 @@ export const zhCN = {
   "skill.repoAmbiguous": "repo skill {{source}} 里有多个 skill,必须用 `skills: [...]` 明确选择要启用哪些。可选:{{available}}。",
   "skill.repoUnknownSkill": "repo skill {{source}}(ref: {{ref}})里没有名为 \"{{skill}}\" 的 skill。可选:{{available}}。",
   "skill.copyFailed": "skill \"{{name}}\" 装进 {{dest}} 失败:\n{{tail}}",
+  "mcp.ambiguousTransport":
+    "MCP server \"{{name}}\" 同时给出了 command 和 url——二选一:本地 stdio 进程写 command,远程 Streamable HTTP 端点写 url。",
   "plugin.marketplaceFailed": "{{agent}} marketplace \"{{name}}\" 连接失败(source: {{source}}, ref: {{ref}}):\n{{tail}}",
   "plugin.marketplaceVerifyFailed": "{{agent}} marketplace \"{{name}}\" add 后回读注册列表失败({{command}}):\n{{tail}}",
   "plugin.marketplaceNameMismatch":
@@ -79,7 +81,8 @@ export const zhCN = {
     "      --diff[=文件] agent 归因的文件改动摘要;=文件 按窗口展开单个文件\n" +
     "      --history   逐 experiment × eval 的执行时间轴(与 --report 互斥)\n" +
     "      --results <目录> 钉死结果根   --experiment <id> 只看该实验\n" +
-    "      --report <文件> 自定义报告   --page <id> 选页(多页报告先输出页索引)\n" +
+    "      --report <文件> 自定义报告   --page <id> 定初始页(多页报告渲染该页,\n" +
+    "        尾部再附其余页索引)\n" +
     "  niceeval list                            列出发现到的 eval\n" +
     "  niceeval view [eval-id 前缀…] [--out 目录] [--port n] [--no-open]\n" +
     "      报告页 + 证据室;--report <文件> 整槽换成自定义报告(与 show 同一文件)\n" +
@@ -145,6 +148,7 @@ export const zhCN = {
   "context.turnFailedDefault": "本轮 send 返回 failed(turn status = failed)",
   "define.agentNameRequired": "defineAgent 需要 name。",
   "define.evalIdRejected": "defineEval 不接受 id —— id 由文件路径推导。",
+  "define.evalEnvironmentEmpty": "defineEval 的 environment 如有提供，必须是非空的 profile id。",
   "define.evalTestRequired": "defineEval 需要一个 async test(t) 函数。",
   "define.experimentAgentRequired": "defineExperiment 需要 agent。",
   "define.experimentFlagNotJson": "experiment.flags.{{key}} 不是可 JSON 序列化的值(函数 / undefined / 循环引用 / bigint 不允许);flags 会原样进入结果快照,必须是纯 JSON。",

package/src/index.ts

@@ -35,6 +35,7 @@ export type {
   RunShape,
   AssertionResult,
   ExperimentRunInfo,
+  SandboxRunInfo,
   DiffData,
   DiffView,
   ScriptResult,

package/src/report/built-in/index.tsx

@@ -1,9 +1,10 @@
-// niceeval/report/built-in —— 包里自带的一个报告文件,没有任何私有钩子
-// (docs/feature/reports/library/built-in.md)。裸 `niceeval show` 与 `niceeval view`
-// 装载的就是这份默认导出:一份普通 defineReport,与用户的 --report 文件同层、
-// 走同一条 装载 → resolve → validate → render 管线。「builtin」不是装载逻辑里的类别,
-// 只是宿主默认拿哪个值的事实。
+// niceeval/report/built-in —— 内建视图的家:每个内建视图是一份普通 defineReport 成品,
+// 有自己的名字、一个源文件,按名字具名导出;默认导出恒等于 standard——裸宿主装载的那份
+// (docs/feature/reports/library/built-in.md)。新增内建视图 = 新文件 + 新具名导出,
+// 不需要注册表,也不改变装载管线。
 
-import { ExperimentComparison, defineReport } from "../index.ts";
+import { standard } from "./standard.tsx";
 
-export default defineReport(<ExperimentComparison />);
+export { standard };
+
+export default standard;

package/src/report/built-in/standard.tsx

@@ -0,0 +1,59 @@
+// standard —— 内建视图之一:报告 / Attempts / 追踪三页的通用结果站,没有任何私有钩子
+// (docs/feature/reports/library/built-in.md)。裸 `niceeval show` 与 `niceeval view`
+// 装载的就是它:一份普通 defineReport,与用户的 --report 文件同层、走同一条
+// 装载 → resolve → validate → render 管线。「builtin」不是装载逻辑里的类别,
+// 只是宿主默认拿哪个值的事实;用户报告经 defineReport({ extends: standard, … }) 整站复用。
+//
+// 三页站点:report(Hero + 警告 + 批量修复 prompt + 实验对比)、attempts(带过滤的
+// attempt 全列表)、traces(执行瀑布)。裸宿主导航上能看到的一切内容都在这份定义里;
+// 宿主保留的只有机器(docs/feature/reports/architecture.md「宿主保留的只有机器」)。
+
+import {
+  AttemptList,
+  Col,
+  CopyFixPrompt,
+  ExperimentComparison,
+  Hero,
+  ScopeWarnings,
+  TraceWaterfall,
+  defineReport,
+} from "../index.ts";
+
+export const standard = defineReport({
+  pages: [
+    {
+      id: "report",
+      title: { en: "Report", "zh-CN": "报告" },
+      content: (
+        <Col>
+          <Hero />
+          <ScopeWarnings />
+          <CopyFixPrompt />
+          <ExperimentComparison />
+        </Col>
+      ),
+    },
+    {
+      id: "attempts",
+      title: "Attempts",
+      content: (
+        <Col>
+          <Hero />
+          <ScopeWarnings />
+          <AttemptList filter />
+        </Col>
+      ),
+    },
+    {
+      id: "traces",
+      title: { en: "Traces", "zh-CN": "追踪" },
+      content: (
+        <Col>
+          <Hero />
+          <ScopeWarnings />
+          <TraceWaterfall />
+        </Col>
+      ),
+    },
+  ],
+});

package/src/report/components.tsx

@@ -21,34 +21,42 @@ import {
   type TextContext,
   type WebContext,
 } from "./tree.ts";
-import type { ReportLocale } from "./locale.ts";
+import type { LocalizedText, ReportLocale } from "./locale.ts";
 import type { AttemptLocator } from "../results/locator.ts";
 import type {
   AttemptListItem,
+  CopyFixPromptData,
   DeltaData,
   EvalListItem,
   ExperimentComparisonData,
   ExperimentListItem,
+  HeroData,
   LineData,
   MatrixData,
   ReportInput,
   ScatterData,
   ScopeSummaryData,
+  ScopeWarning,
   ScoreboardData,
   TableData,
+  TraceWaterfallRow,
 } from "./types.ts";
 import {
   attemptListData,
+  copyFixPromptData,
   deltaTableData,
   evalListData,
   experimentComparisonData,
   experimentListData,
+  heroData,
   metricLineData,
   metricMatrixData,
   metricScatterData,
   metricTableData,
   scopeSummaryData,
+  scopeWarningsData,
   scoreboardData,
+  traceWaterfallData,
   type DeltaTableOptions,
   type MetricLineOptions,
   type MetricMatrixOptions,
@@ -64,18 +72,26 @@ import {
   experimentComparisonText,
   experimentListText,
   barsText,
+  heroCardText,
   lineText,
   matrixText,
   scatterText,
+  scopeWarningsText,
   scoreboardText,
   scopeSummaryText,
   tableText,
+  traceWaterfallText,
 } from "./text/faces.ts";
 import { ScopeSummary as ScopeSummaryWeb } from "./react/ScopeSummary.tsx";
 import { ExperimentComparisonView } from "./react/ExperimentComparison.tsx";
 import { ExperimentList as ExperimentListWeb } from "./react/ExperimentList.tsx";
 import { EvalList as EvalListWeb } from "./react/EvalList.tsx";
 import { AttemptList as AttemptListWeb } from "./react/AttemptList.tsx";
+import { HeroCard as HeroCardWeb } from "./react/HeroCard.tsx";
+import { PoweredBy as PoweredByWeb } from "./react/PoweredBy.tsx";
+import { ScopeWarnings as ScopeWarningsWeb } from "./react/ScopeWarnings.tsx";
+import { CopyFixPrompt as CopyFixPromptWeb } from "./react/CopyFixPrompt.tsx";
+import { TraceWaterfall as TraceWaterfallWeb } from "./react/TraceWaterfall.tsx";
 import { MetricTable as MetricTableWeb } from "./react/MetricTable.tsx";
 import { MetricMatrix as MetricMatrixWeb } from "./react/MetricMatrix.tsx";
 import { MetricBars as MetricBarsWeb } from "./react/MetricBars.tsx";
@@ -257,6 +273,55 @@ const validateAttemptListData: Validator = (data) => {
   return null;
 };
 
+const validateHeroData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (!("latestStartedAt" in data) || (data.latestStartedAt !== null && typeof data.latestStartedAt !== "string")) {
+    return 'missing "latestStartedAt" (string | null)';
+  }
+  if (typeof data.snapshots !== "number") return 'missing "snapshots" (number)';
+  return null;
+};
+
+const validateScopeWarningsData: Validator = (data) => {
+  if (!Array.isArray(data)) return "expected an array of ScopeWarning";
+  for (const item of data as unknown[]) {
+    if (!isObject(item) || typeof item.kind !== "string" || typeof item.message !== "string") {
+      return "each warning needs { kind, message, … }";
+    }
+  }
+  return null;
+};
+
+const validateCopyFixPromptData: Validator = (data) => {
+  if (!isObject(data)) return "expected an object";
+  if (typeof data.prompt !== "string") return 'missing "prompt" (string)';
+  if (typeof data.failures !== "number") return 'missing "failures" (number)';
+  return null;
+};
+
+const validateTraceWaterfallData: Validator = (data) => {
+  if (!Array.isArray(data)) return "expected an array of TraceWaterfallRow";
+  for (const row of data as unknown[]) {
+    if (
+      !isObject(row) ||
+      typeof row.experimentId !== "string" ||
+      typeof row.evalId !== "string" ||
+      typeof row.locator !== "string" ||
+      !("durationMs" in row) ||
+      (row.durationMs !== null && typeof row.durationMs !== "number") ||
+      !Array.isArray(row.spans)
+    ) {
+      return "each row needs { experimentId, evalId, locator, durationMs: number | null, spans }";
+    }
+    for (const span of row.spans as unknown[]) {
+      if (!isObject(span) || typeof span.name !== "string" || typeof span.startOffsetMs !== "number") {
+        return "each span needs { name, kind, startOffsetMs, durationMs, failed }";
+      }
+    }
+  }
+  return null;
+};
+
 // ───────────────────────── spec / data 双形态的通用装配 ─────────────────────────
 
 interface DataComponentDef<Data, Options, Presentation> {
@@ -463,6 +528,8 @@ export type AttemptListProps = DataProps<
   EntityListChrome & {
     /** 过滤 / 截断前的总数;省略时等于 data 长度。 */
     total?: number;
+    /** web 面加过滤输入框(按 experiment、eval、agent、verdict 或摘要文本收窄行);渐进增强,不改变数据与 text 面。 */
+    filter?: boolean;
   }
 >;
 
@@ -470,7 +537,7 @@ export type AttemptListProps = DataProps<
 export const AttemptList = makeDataComponent<
   readonly AttemptListItem[],
   Record<never, never>,
-  EntityListChrome & { total?: number }
+  EntityListChrome & { total?: number; filter?: boolean }
 >({
   name: "AttemptList",
   dataFnName: "attemptListData",
@@ -482,6 +549,7 @@ export const AttemptList = makeDataComponent<
     <AttemptListWeb
       data={props.data}
       total={props.total}
+      filter={props.filter}
       locale={props.locale ?? ctx.locale}
       attemptHref={hrefOf(props, ctx) ?? ctx.attemptHref}
       className={props.className}
@@ -537,6 +605,154 @@ export const FailureList = defineComponent<FailureListProps>(async (props, ctx)
 });
 FailureList.displayName = "FailureList";
 
+// ───────────────────────── 站点组件(Hero / PoweredBy / ScopeWarnings / CopyFixPrompt / TraceWaterfall)─────────────────────────
+
+/** `Hero` 的 props:标题缺省取 `ctx.report.title`(回退链后的站点标题)。 */
+export interface HeroProps {
+  /** 覆盖标题;省略时取 ctx.report.title(回退链后的站点标题)。 */
+  title?: LocalizedText;
+  className?: string;
+}
+
+/** HeroCard 的 data 校验入口(它不经 makeDataComponent,数据形态是唯一形态)。 */
+const assertHeroData = (data: unknown): HeroData => {
+  const problem = validateHeroData(data);
+  if (problem !== null) throw dataShapeError("HeroCard", "heroData", "HeroData", problem);
+  return data as HeroData;
+};
+
+/**
+ * `HeroCard`:Hero 的渲染件,双面组件,只收 data 形态——标题输入是站点声明与 Scope 的
+ * 合成物,没有单独的 spec 等价形。web 面渲染 hero 标题(h1)、按渲染 locale 格式化的运行
+ * meta(latestStartedAt 为 null 时内置「暂无运行」文案)与品牌行(等同 PoweredBy,恒含、
+ * 无拆除 prop);text 面输出标题行与 meta 行,不含品牌行
+ * (docs/feature/reports/library/site-components.md「HeroCard」)。
+ */
+export const HeroCard = defineComponent<HeroCardProps>({
+  web: (props, ctx) => {
+    assertHeroData(props.data);
+    return <HeroCardWeb title={props.title} data={props.data} className={props.className} locale={ctx.locale} />;
+  },
+  text: (props, ctx) => {
+    assertHeroData(props.data);
+    return heroCardText(props.title, props.data, ctx);
+  },
+});
+HeroCard.displayName = "HeroCard";
+
+/** `HeroCard` 的 props:标题 + `heroData()` 的产物,只有 data 形态。 */
+export interface HeroCardProps {
+  title: LocalizedText;
+  data: HeroData;
+  className?: string;
+}
+
+/**
+ * `Hero`:页首的站点标题区——标题、最后运行时间、快照合成来源,恒含品牌行。官方组合组件,
+ * 与手写 `<HeroCard title={title ?? ctx.report.title} data={await heroData(ctx.scope)} />`
+ * 严格等价、没有私有能力;读 `ctx.report` 意味着输出跟随站点,要站点无关的标题区直接用
+ * `HeroCard` 显式传值(docs/feature/reports/library/site-components.md「Hero」)。
+ */
+export const Hero = defineComponent<HeroProps>(async ({ title, className }, ctx) => (
+  <HeroCard title={title ?? ctx.report.title} data={await heroData(ctx.scope)} className={className} />
+));
+Hero.displayName = "Hero";
+
+/**
+ * `PoweredBy`:唯一的品牌件,无 props 双面组件。web 面渲染指向 niceeval 官网的一行品牌色
+ * 小字(`utm_source=report&utm_medium=powered-by`,`rel` 仅 `noopener` 以保留 Referer);
+ * text 面零输出。没有任何配置——品牌契约是「提供一个组件,不给开关」:不想要品牌就不用
+ * 这些组件、自己写替代组件(docs/feature/reports/library/site-components.md「PoweredBy」)。
+ */
+export const PoweredBy = defineComponent<Record<never, never>>({
+  web: () => <PoweredByWeb />,
+  text: () => "",
+});
+PoweredBy.displayName = "PoweredBy";
+
+/** `ScopeWarnings` 的 props:spec 形态取宿主 Scope 的 warnings,data 形态收 `ScopeWarning[]`。 */
+export type ScopeWarningsProps = DataProps<readonly ScopeWarning[], Record<never, never>, ChromeProps>;
+
+/**
+ * `ScopeWarnings`:选择警告区,警告的唯一呈现组件。把 Scope 携带的 `ScopeWarning[]`
+ * 按「下一步动作」聚合渲染(带 experimentId 的按实验聚合、非实验作用域按 kind 聚合;
+ * integrity 组在前);web 面组头带去重后的可复制命令、明细收原生 `<details>`(总条数 ≤ 3
+ * 默认展开),text 面同构但不折叠。空警告集与裸 `Snapshot[]` 输入两面零输出
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export const ScopeWarnings = makeDataComponent<readonly ScopeWarning[], Record<never, never>, ChromeProps>({
+  name: "ScopeWarnings",
+  dataFnName: "scopeWarningsData",
+  shapeName: "ScopeWarning[]",
+  dataFn: (input) => scopeWarningsData(input),
+  specKeys: [],
+  validate: validateScopeWarningsData,
+  web: (props, ctx) =>
+    props.data.length === 0 ? null : (
+      <ScopeWarningsWeb data={props.data} locale={props.locale ?? ctx.locale} className={props.className} />
+    ),
+  text: (props, ctx) => scopeWarningsText(props.data, ctx),
+}) as unknown as ReportComponent<ScopeWarningsProps>;
+
+/** `CopyFixPrompt` 的 props:spec 形态无选项,data 形态收 `copyFixPromptData()` 的产物。 */
+export type CopyFixPromptProps = DataProps<CopyFixPromptData, Record<never, never>, ChromeProps>;
+
+/**
+ * `CopyFixPrompt`:把当前范围的全部失败整理成一段可交给 coding agent 的修复 prompt。
+ * prompt 在 resolve 阶段算好、烘进静态 HTML,无 JS 时在折叠块里完整可读,「复制」是增强层
+ * 行为;`failures` 为 0 时两面零输出;text 面恒零输出——终端里的等价能力是 `show` 的
+ * attempt 下钻命令本身(docs/feature/reports/library/site-components.md「CopyFixPrompt」)。
+ */
+export const CopyFixPrompt = makeDataComponent<CopyFixPromptData, Record<never, never>, ChromeProps>({
+  name: "CopyFixPrompt",
+  dataFnName: "copyFixPromptData",
+  shapeName: "CopyFixPromptData",
+  dataFn: (input) => copyFixPromptData(input),
+  specKeys: [],
+  validate: validateCopyFixPromptData,
+  web: (props, ctx) =>
+    props.data.failures === 0 ? null : (
+      <CopyFixPromptWeb data={props.data} locale={props.locale ?? ctx.locale} className={props.className} />
+    ),
+  text: () => "",
+}) as unknown as ReportComponent<CopyFixPromptProps>;
+
+/** `TraceWaterfall` 的 props:spec 形态无选项,data 形态收 `traceWaterfallData()` 的产物。 */
+export type TraceWaterfallProps = DataProps<
+  readonly TraceWaterfallRow[],
+  Record<never, never>,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>;
+
+/**
+ * `TraceWaterfall`:每个 attempt 一行的执行时间瀑布,用 canonical OTel 字段显示被测 agent
+ * 的原始 span(agent / model / tool)。web 面静态渲染顶层 span 分解条(失败 span 带失败
+ * 标记),行链接 attempt 详情;text 面每 attempt 一行(locator、总耗时、span 计数与失败
+ * 标记)+ 可复制的 `--timing` 下钻命令。trace 缺失的行照常出现并如实显示缺失;runner
+ * 生命周期节点不进瀑布(docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+ */
+export const TraceWaterfall = makeDataComponent<
+  readonly TraceWaterfallRow[],
+  Record<never, never>,
+  ChromeProps & { attemptHref?: (locator: AttemptLocator) => string }
+>({
+  name: "TraceWaterfall",
+  dataFnName: "traceWaterfallData",
+  shapeName: "TraceWaterfallRow[]",
+  dataFn: (input) => traceWaterfallData(input),
+  specKeys: [],
+  validate: validateTraceWaterfallData,
+  web: (props, ctx) => (
+    <TraceWaterfallWeb
+      data={props.data}
+      attemptHref={hrefOf(props, ctx) ?? ctx.attemptHref}
+      locale={props.locale ?? ctx.locale}
+      className={props.className}
+    />
+  ),
+  text: (props, ctx) => traceWaterfallText(props.data, ctx),
+}) as unknown as ReportComponent<TraceWaterfallProps>;
+
 // ───────────────────────── 指标组件 ─────────────────────────
 
 export type MetricTableProps = DataProps<