niceeval 0.8.1 → 0.9.0

package/INDEX.md

@@ -2,51 +2,83 @@
 
 这是 coding agent 读取 NiceEval 文档的稳定入口，随 npm 包发布，不属于公开文档站。不要根据训练数据、官网或 GitHub `main` 分支猜测 API。
 
-以下路径都相对于包根 `node_modules/niceeval/`。文档位于 `docs-site/zh/`，与当前安装的 NiceEval 版本一起发布。先按任务读取对应页面；页面再引用其它概念或参考时，继续读取包内文件。
-
-## 开始接入
-
-| 任务 | 读取 |
-| --- | --- |
-| 初始化并跑通第一条 Eval | `docs-site/zh/tutorials/quickstart.mdx` |
-| 理解 Adapter、Experiment、Eval 的分工 | `docs-site/zh/explanation/overview.mdx` |
-| 接入自己的 Agent | `docs-site/zh/how-to/connect-your-agent.mdx` |
-| 选择官方 Adapter | `docs-site/zh/reference/official-adapters.mdx` |
-| 接入 coding agent CLI | `docs-site/zh/how-to/sandbox-agent.mdx` |
-| 选择 Sandbox Provider | `docs-site/zh/how-to/sandbox-providers.mdx` |
-
-## 编写配置与 Eval
-
-| 任务 | 读取 |
-| --- | --- |
-| 编写 Adapter | `docs-site/zh/explanation/adapter.mdx`、`docs-site/zh/reference/define-agent.mdx` |
-| 映射消息、工具调用和事件流 | `docs-site/zh/how-to/write-send.mdx`、`docs-site/zh/reference/events.mdx` |
-| 编写 Experiment | `docs-site/zh/how-to/write-experiment.mdx` |
-| 编写 Eval | `docs-site/zh/explanation/evals.mdx`、`docs-site/zh/reference/define-eval.mdx` |
-| 编写断言和评分 | `docs-site/zh/how-to/authoring.mdx`、`docs-site/zh/how-to/scoring-guide.mdx`、`docs-site/zh/reference/expect.mdx` |
-| 配置 Judge | `docs-site/zh/explanation/judge.mdx`、`docs-site/zh/reference/define-config.mdx` |
-| 配置 OTel | `docs-site/zh/how-to/connect-otel.mdx` |
-| 查 CLI 命令与 flag | `docs-site/zh/reference/cli.mdx` |
-
-## 运行、调试与优化
-
-| 任务 | 读取 |
-| --- | --- |
-| 让 AI 自主运行、观察、修改和重跑 | `docs-site/zh/how-to/agent-feedback-loop.mdx` |
-| 用 `show`、`view` 和 artifact 定位失败 | `docs-site/zh/how-to/viewing-results.mdx` |
-| 组织实验和对比 | `docs-site/zh/how-to/experiments.mdx` |
-| 编写自定义报告 | `docs-site/zh/how-to/custom-reports.mdx`、`docs-site/zh/reference/report-components.mdx` |
-| 读取或转换结构化结果 | `docs-site/zh/reference/results-data.mdx` |
-
-## 专项场景
-
-| 任务 | 读取 |
-| --- | --- |
-| 评估 Claude Code / Codex Skill | `docs-site/zh/examples/coding-agent-extensions.mdx` |
-| 评估 Plugin、Hook 或 MCP server | `docs-site/zh/examples/coding-agent-extensions.mdx` |
-| 编写多轮会话 | `docs-site/zh/explanation/adapter.mdx`、`docs-site/zh/how-to/write-send.mdx` |
-| 编写人工审批流（HITL） | `docs-site/zh/explanation/hitl.mdx` |
-| 做 feature flag A/B 对比 | `docs-site/zh/explanation/tier.mdx`、`docs-site/zh/explanation/experiment.mdx` |
+以下路径都相对于包根 `node_modules/niceeval/`。文档位于 `docs-site/zh/`，与当前安装的 NiceEval 版本一起发布。下面的树列出全部随包页面，每行是「路径 — 标题:一句话自述」。分区含义：
+
+- `tutorials/` 第一次跑通；`explanation/` 概念、边界与原理；`how-to/` 按任务的操作步骤；`reference/` API、CLI 与数据形状的精确事实；`troubleshooting/` 按症状排查失败；`examples/` 真实项目的接入案例。
+
+按当前任务从树里挑 1–3 页读取（通常是一页 how-to 或 explanation 搭一页 reference）；页面再引用其它概念或参考时，继续读取包内文件。
+
+<!-- GENERATED:BEGIN bundled-docs-tree -->
+
+<!-- 本文件是构建产物(pnpm run build:index),勿手改:树区文案改对应页面的 frontmatter title/description,导语改 INDEX.template.md(生成逻辑见 scripts/generate-reference.ts) -->
+
+## `docs-site/zh/tutorials/`
+
+- `docs-site/zh/tutorials/quickstart.mdx` — 为你的 Agent 项目设置评估:安装 NiceEval，写三个文件，10 分钟内对你自己的应用跑通第一条 eval。
+
+## `docs-site/zh/explanation/`
+
+- `docs-site/zh/explanation/adapter.mdx` — Adapter：把 Agent 接入 NiceEval:Adapter 是你写的适配器。本文讲清楚 send 函数传入什么返回什么、被测系统配置怎么传、三个接入等级，以及 t 上的能力从哪来。
+- `docs-site/zh/explanation/assert.mdx` — NiceEval 断言：值、作用域事实、测试与成本:NiceEval 的断言词汇——值断言、作用域断言、test-as-scoring 和效率断言——以及 gate / soft 严重度和判定 verdict 的规则。
+- `docs-site/zh/explanation/drive.mdx` — NiceEval 里怎么驱动 agent：send、session 与 HITL:t.send() 和它返回的 Turn、t.sendFile()、多轮对话、t.newSession()，以及 respond() 处理的人工介入(HITL)。
+- `docs-site/zh/explanation/evals.mdx` — NiceEval 中的 eval：生命周期、verdict 与文件:eval 是一个测试用例：描述和 test 函数，agent-neutral。了解 eval 如何被发现、调度、评分和报告。
+- `docs-site/zh/explanation/experiment.mdx` — 实验（Experiment）：评谁、怎么跑:Experiment 是可签入的运行配置：同一批 eval 对着哪个 agent、哪个模型、开哪些 flags、跑几次。eval 与 experiment 分开的原因——晚绑定，让同一份 eval 换着对象跑。
+- `docs-site/zh/explanation/hitl.mdx` — 人工介入（HITL）：停轮、回答、继续:什么是 Human-in-the-loop，Claude Code / Codex / AI SDK 应用里它长什么样；NiceEval 如何把它变成可评的路径——waiting 停轮、input.requested 说明在等什么、t.respond 替人回答后同一轮继续。
+- `docs-site/zh/explanation/judge.mdx` — NiceEval 里的 LLM-as-judge: 给开放式输出打分:t.judge / session.judge / turn.judge 如何用独立裁判模型评估事实性、闭合式质量和摘要忠实度，以及模型解析优先级和严重度。
+- `docs-site/zh/explanation/overview.mdx` — NiceEval 架构：evals、agents 与 sandboxes:理解 NiceEval、Adapter 和 Sandbox Provider 如何配合，用统一 API 评估任意 AI Agent。
+- `docs-site/zh/explanation/runner.mdx` — NiceEval runner 如何调度和执行 eval:NiceEval runner 发现 eval，用有界并发调度，缓存结果，重试脆弱基础设施，并执行预算保护。
+- `docs-site/zh/explanation/tier.mdx` — 接入等级（Tier）：三级投入，三组能力:按「Adapter 接到哪里、额外拿到什么观测数据」接入分三级：Tier 1 只接 send，Tier 2 加 OTel，Tier 3 侵入改造暴露 experiment flags。每档买到什么、什么时候升级。
+
+## `docs-site/zh/how-to/`
+
+- `docs-site/zh/how-to/agent-feedback-loop.mdx` — 让 AI 写 Eval 并自主优化:让 coding agent 读取随包文档，用 bash 运行实验、下钻结果、定位失败并持续迭代，最后用全量重跑确认收敛。
+- `docs-site/zh/how-to/authoring.mdx` — 编写 eval: 单轮、多轮和数据集模式:学习如何用 defineEval 编写 NiceEval eval，包括单轮断言、多轮对话、数据驱动测试和 sandbox workspace。
+- `docs-site/zh/how-to/ci-integration.mdx` — 在 GitHub Actions 和 CI 中运行 NiceEval:把 NiceEval 接入 GitHub Actions 或任意 CI。eval 失败时非零退出，输出 JUnit XML，并通过缓存加速重复运行。
+- `docs-site/zh/how-to/connect-otel.mdx` — OTel 接入:把应用已经在发的 OTel span 也发给 NiceEval 一份，niceeval view 里就有每轮的调用瀑布图。断言不从这里来——接好 send 那一刻断言就齐了。
+- `docs-site/zh/how-to/connect-your-agent.mdx` — 接入你的 Agent:接入的全景：写一个 adapter、配一个 experiment、跑通第一条 eval；配置和参数怎么在 experiment 里声明、在 Adapter 里消费。事件流、多轮、HITL、tracing 是增量，各有专章。
+- `docs-site/zh/how-to/custom-reports.mdx` — 用报告积木搭自己的口径:一份报告就是一个报告文件：官方宿主打开结果、注入数据，双面组件让同一份自定义报告同时用于 niceeval show 与 niceeval view。
+- `docs-site/zh/how-to/dataset-fanout.mdx` — 数据驱动测试（dataset fan-out）：用多份数据运行同一套 eval:从 .eval.ts 文件导出数组或 keyed record，将一套 eval 逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。
+- `docs-site/zh/how-to/experiments.mdx` — 实验矩阵：用运行矩阵比较 agents 和 models:使用 NiceEval experiments 让同一批 eval 横跨多个 agents、models 和 flags，比较 pass rate、成本和延迟。
+- `docs-site/zh/how-to/fixtures.mdx` — 沙箱 Fixture：用任务评估 coding agents:用 .eval.ts 给 coding agent 准备隔离 workspace、发送真实任务，并用 sandbox 文件、命令、diff 和 judge 验证结果。
+- `docs-site/zh/how-to/publish-report.mdx` — 通过 CI 发布报告:把经过 copySnapshots 大小预检的结果目录提交进仓库,CI 用一行 view --results 导出报告站;超大文件在 commit 前就会得到可执行错误。
+- `docs-site/zh/how-to/reporters.mdx` — 把结果上报到 Braintrust 与其它目的地:用内置 reporters 把 eval 结果送到 Braintrust 实验、JUnit XML 或自定义目的地。
+- `docs-site/zh/how-to/sandbox-agent.mdx` — 沙箱 Agent：评估 Claude Code、Codex 和 bub:使用 NiceEval 内置 agents 或自定义 adapter，在 Docker 或云端 sandbox 中运行 coding-agent CLI。
+- `docs-site/zh/how-to/sandbox-providers.mdx` — Sandbox provider：Docker、Vercel 与第三方:NiceEval 在 Docker 或 Vercel sandbox 中运行 coding agents。了解如何选择 provider、配置权限，并通过 warm pools 改善性能。
+- `docs-site/zh/how-to/scoring-guide.mdx` — 评分指南: 断言、judge 和成本限制:用 NiceEval 的五种评分机制评估任意 eval：值断言、作用域断言、LLM-as-judge、test-as-scoring 和效率检查。
+- `docs-site/zh/how-to/viewing-results.mdx` — 查看 NiceEval 结果并调试 agent 行为:每次运行写入 .niceeval/ 的结构化 artifact 有两扇门：niceeval show 在终端用 @<locator> 精确定位一次 Attempt，逐级下钻 Eval 源码、执行记录与 diff；niceeval view 在网页看同一份证据。
+- `docs-site/zh/how-to/write-experiment.mdx` — 写实验：用 defineExperiment 固定运行配置:学习如何在 experiments/ 里用 defineExperiment 选择 agent、传 model 和 flags、设置 runs、预算、并发与 sandbox。
+- `docs-site/zh/how-to/write-send.mdx` — 如何写好 Send:手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 flags。每一步只在上一步的代码上多几行，每一步解锁一组断言。
+
+## `docs-site/zh/reference/`
+
+- `docs-site/zh/reference/builtin-agents.mdx` — 内置 Agent 能力参考:NiceEval 内置的 claude-code、codex、bub 适配器分别做到了哪些能力，对应哪些断言，以及已知限制。
+- `docs-site/zh/reference/capabilities.mdx` — 能力位参考:NiceEval 怎么知道你的 adapter 做到了什么：没有声明式能力位，全部由构造和实际行为证明。
+- `docs-site/zh/reference/cli.mdx` — NiceEval CLI：命令、flags 和退出码参考:NiceEval CLI 参考：exp、show、view、init、list 和 clean 命令，以及结果下钻、experiment、eval 过滤、并发、预算和 CI 输出。
+- `docs-site/zh/reference/define-agent.mdx` — defineAgent 和 defineSandboxAgent：adapter 参考:defineAgent 和 defineSandboxAgent 参考：AgentContext、AgentSession、Sandbox 接口和共享 sandbox helpers。
+- `docs-site/zh/reference/define-config.mdx` — defineConfig：项目默认配置:defineConfig 参考：judge、reporters、并发、超时和 sandbox 默认值。
+- `docs-site/zh/reference/define-eval.mdx` — defineEval：声明、配置并运行 NiceEval eval:defineEval 参考：选项、test context t、Turn 返回值、sandbox helper，以及数组和 keyed record 数据集导出。
+- `docs-site/zh/reference/events.mdx` — 标准事件流参考:StreamEvent 的十种事件：每种的字段、什么时候吐、哪些断言消费它。adapter 的核心工作就是产出这条流。
+- `docs-site/zh/reference/expect.mdx` — niceeval/expect matchers 与自定义断言参考:niceeval/expect 参考：includes、equals、matches、similarity、satisfies。可链式调用 .gate() 或 .atLeast(0.7)，也可以用 makeAssertion 构建自定义 matcher。
+- `docs-site/zh/reference/official-adapters.mdx` — 官方适配器一览:NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么、怎么鉴权，Sandbox 型里怎么装 MCP server、Skill、插件，怎么使用 Agent 官方配置文件。
+- `docs-site/zh/reference/report-components.mdx` — 报告组件一览:报告文件里能摆的全部官方双面组件：每个组件回答什么问题、怎么调用、网页面长什么样、终端字符输出长什么样。
+- `docs-site/zh/reference/results-data.mdx` — 用 niceeval/results 直接读写结果数据:报告积木脚下的数据层：openResults 把 .niceeval/ 的落盘 artifact parse 成「实验 → 结果快照 → eval → attempt」的类型化层次，createResultsWriter 把别家结果写成 NiceEval 格式，copySnapshots 负责发布瘦身。
+
+## `docs-site/zh/troubleshooting/`
+
+- `docs-site/zh/troubleshooting/debug-sandbox.mdx` — 保留沙箱现场排查问题:用 --keep-sandbox 把失败 Attempt 的沙箱保留成可随时唤醒的现场，用 niceeval sandbox enter 进去手动排查，用 sandbox list / stop 查看和清理。
+- `docs-site/zh/troubleshooting/debugging.mdx` — 排查失败与复盘历史运行:一份按场景组织的排查手册：断言失败怎么定位、环境错误怎么进沙箱、agent 改了什么怎么看、旧的运行怎么翻出来复盘——每一步都有命令顺序和输出示例。
+
+## `docs-site/zh/examples/`
+
+- `docs-site/zh/examples/ai-agent-application.mdx` — 自写 Adapter 评估 AI Agent 应用:一个可运行的 AI SDK v6 Web Agent 评测项目，覆盖自写 Adapter、工具调用、图片理解、多轮会话、模型对比和双路可观测。
+- `docs-site/zh/examples/coding-agent-extensions.mdx` — 评估 Coding Agent 扩展:用真实 Workspace、基线实验和自定义报告，评估 Skill、提示词与 Plugin Benchmark 是否改善 Coding Agent 的任务结果。
+- `docs-site/zh/examples/integrations/ai-sdk-v7.mdx` — AI SDK v7 如何非侵入式接入 NiceEval:一个 AI SDK v7 聊天应用，对着它的 HTTP 接口无侵入接入 NiceEval 前后的完整代码 diff：应用侧一行没改。
+- `docs-site/zh/examples/integrations/claude-sdk.mdx` — Claude Agent SDK 如何非侵入式接入 NiceEval:一个 Claude Agent SDK 助手后端，接入 NiceEval 前后的完整代码 diff：应用侧一行没改，全部新增在 eval 侧。
+- `docs-site/zh/examples/integrations/codex-sdk.mdx` — Codex SDK 如何非侵入式接入 NiceEval:一个 Codex SDK（目录里的编码 agent）后端，接入 NiceEval 前后的完整代码 diff：应用侧一行没改。
+- `docs-site/zh/examples/integrations/langgraph.mdx` — LangGraph 如何非侵入式接入 NiceEval:一个纯 Python LangGraph + LangSmith OTel 导出的应用，接入 NiceEval 前后的完整代码 diff。
+- `docs-site/zh/examples/integrations/pi-sdk.mdx` — pi-agent-core 如何非侵入式接入 NiceEval:一个 pi-agent-core(@earendil-works)助手后端，接入 NiceEval 前后的完整代码 diff：应用侧只加了一个 devDependency。
+
+<!-- GENERATED:END bundled-docs-tree -->
 
 ## 版本规则
 

package/dist/agents/types.d.ts

@@ -2,20 +2,39 @@ import type { Cleanup, DiagnosticInput, ProgressUpdate } from "../shared/types.t
 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 决定。
@@ -69,11 +88,14 @@ export interface AgentSetupManifest {
         /** 安装后 CLI 报告的版本;取不到时省略。 */
         resolvedVersion?: string;
     }>;
-    /** 挂上的 MCP server(不含 env:secret 不进 manifest)。 */
+    /** 挂上的 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 名、

package/dist/i18n/en.d.ts

@@ -22,6 +22,7 @@ export declare const en: {
     "skill.repoAmbiguous": string;
     "skill.repoUnknownSkill": string;
     "skill.copyFailed": string;
+    "mcp.ambiguousTransport": string;
     "plugin.marketplaceFailed": string;
     "plugin.marketplaceVerifyFailed": string;
     "plugin.marketplaceNameMismatch": string;
@@ -91,6 +92,7 @@ export declare const en: {
     "context.turnFailedDefault": string;
     "define.agentNameRequired": string;
     "define.evalIdRejected": string;
+    "define.evalEnvironmentEmpty": string;
     "define.evalTestRequired": string;
     "define.experimentAgentRequired": string;
     "define.experimentFlagNotJson": string;

package/dist/i18n/zh-CN.d.ts

@@ -22,6 +22,7 @@ export declare const zhCN: {
     readonly "skill.repoAmbiguous": "repo skill {{source}} 里有多个 skill,必须用 `skills: [...]` 明确选择要启用哪些。可选:{{available}}。";
     readonly "skill.repoUnknownSkill": "repo skill {{source}}(ref: {{ref}})里没有名为 \"{{skill}}\" 的 skill。可选:{{available}}。";
     readonly "skill.copyFailed": "skill \"{{name}}\" 装进 {{dest}} 失败:\n{{tail}}";
+    readonly "mcp.ambiguousTransport": "MCP server \"{{name}}\" 同时给出了 command 和 url——二选一:本地 stdio 进程写 command,远程 Streamable HTTP 端点写 url。";
     readonly "plugin.marketplaceFailed": "{{agent}} marketplace \"{{name}}\" 连接失败(source: {{source}}, ref: {{ref}}):\n{{tail}}";
     readonly "plugin.marketplaceVerifyFailed": "{{agent}} marketplace \"{{name}}\" add 后回读注册列表失败({{command}}):\n{{tail}}";
     readonly "plugin.marketplaceNameMismatch": string;
@@ -91,6 +92,7 @@ export declare const zhCN: {
     readonly "context.turnFailedDefault": "本轮 send 返回 failed(turn status = failed)";
     readonly "define.agentNameRequired": "defineAgent 需要 name。";
     readonly "define.evalIdRejected": "defineEval 不接受 id —— id 由文件路径推导。";
+    readonly "define.evalEnvironmentEmpty": "defineEval 的 environment 如有提供，必须是非空的 profile id。";
     readonly "define.evalTestRequired": "defineEval 需要一个 async test(t) 函数。";
     readonly "define.experimentAgentRequired": "defineExperiment 需要 agent。";
     readonly "define.experimentFlagNotJson": "experiment.flags.{{key}} 不是可 JSON 序列化的值(函数 / undefined / 循环引用 / bigint 不允许);flags 会原样进入结果快照,必须是纯 JSON。";

package/dist/report/built-in/index.d.ts

@@ -1,2 +1,3 @@
-declare const _default: import("../report.ts").ReportDefinition;
-export default _default;
+import { standard } from "./standard.tsx";
+export { standard };
+export default standard;

package/dist/report/built-in/index.js

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

package/dist/report/built-in/standard.d.ts

@@ -0,0 +1 @@
+export declare const standard: import("../report.ts").ReportDefinition;

package/dist/report/built-in/standard.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// 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.js";
+export const standard = defineReport({
+    pages: [
+        {
+            id: "report",
+            title: { en: "Report", "zh-CN": "报告" },
+            content: (_jsxs(Col, { children: [_jsx(Hero, {}), _jsx(ScopeWarnings, {}), _jsx(CopyFixPrompt, {}), _jsx(ExperimentComparison, {})] })),
+        },
+        {
+            id: "attempts",
+            title: "Attempts",
+            content: (_jsxs(Col, { children: [_jsx(Hero, {}), _jsx(ScopeWarnings, {}), _jsx(AttemptList, { filter: true })] })),
+        },
+        {
+            id: "traces",
+            title: { en: "Traces", "zh-CN": "追踪" },
+            content: (_jsxs(Col, { children: [_jsx(Hero, {}), _jsx(ScopeWarnings, {}), _jsx(TraceWaterfall, {})] })),
+        },
+    ],
+});

package/dist/report/components.d.ts

@@ -1,7 +1,7 @@
 import { type ReportComponent } 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, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentListItem, LineData, MatrixData, ReportInput, ScatterData, ScopeSummaryData, ScoreboardData, TableData } from "./types.ts";
+import type { AttemptListItem, CopyFixPromptData, DeltaData, EvalListItem, ExperimentComparisonData, ExperimentListItem, HeroData, LineData, MatrixData, ReportInput, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, TraceWaterfallRow } from "./types.ts";
 import { type DeltaTableOptions, type MetricLineOptions, type MetricMatrixOptions, type MetricScatterOptions, type MetricTableOptions, type ScoreboardOptions } from "./compute.ts";
 type Never<T> = {
     [K in keyof T]?: never;
@@ -55,6 +55,8 @@ export declare const EvalList: ReportComponent<EvalListProps>;
 export type AttemptListProps = DataProps<readonly AttemptListItem[], Record<never, never>, EntityListChrome & {
     /** 过滤 / 截断前的总数;省略时等于 data 长度。 */
     total?: number;
+    /** web 面加过滤输入框(按 experiment、eval、agent、verdict 或摘要文本收窄行);渐进增强,不改变数据与 text 面。 */
+    filter?: boolean;
 }>;
 /** Attempt 列表:实体列表的叶子层,每项一次 attempt 的判定、单行摘要与 locator。 */
 export declare const AttemptList: ReportComponent<AttemptListProps>;
@@ -74,6 +76,71 @@ export interface FailureListProps {
  * 截断到 limit(默认 20),total 报告截断前总数。
  */
 export declare const FailureList: ReportComponent<FailureListProps>;
+/** `Hero` 的 props:标题缺省取 `ctx.report.title`(回退链后的站点标题)。 */
+export interface HeroProps {
+    /** 覆盖标题;省略时取 ctx.report.title(回退链后的站点标题)。 */
+    title?: LocalizedText;
+    className?: string;
+}
+/**
+ * `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 declare const HeroCard: ReportComponent<HeroCardProps>;
+/** `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 declare const Hero: ReportComponent<HeroProps>;
+/**
+ * `PoweredBy`:唯一的品牌件,无 props 双面组件。web 面渲染指向 niceeval 官网的一行品牌色
+ * 小字(`utm_source=report&utm_medium=powered-by`,`rel` 仅 `noopener` 以保留 Referer);
+ * text 面零输出。没有任何配置——品牌契约是「提供一个组件,不给开关」:不想要品牌就不用
+ * 这些组件、自己写替代组件(docs/feature/reports/library/site-components.md「PoweredBy」)。
+ */
+export declare const PoweredBy: ReportComponent<Record<never, never>>;
+/** `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 declare const ScopeWarnings: 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 declare const CopyFixPrompt: 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 declare const TraceWaterfall: ReportComponent<TraceWaterfallProps>;
 export type MetricTableProps = DataProps<TableData, MetricTableOptions, ChromeProps & {
     /** web 面在表格前渲染过滤输入框(enhance.js 接管);无 JS 时表格内容依旧完整。 */
     filter?: boolean;

package/dist/report/components.js

@@ -1,13 +1,18 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { defineComponent, isHostWebContextActive, memoFetchOf, } from "./tree.js";
-import { attemptListData, deltaTableData, evalListData, experimentComparisonData, experimentListData, metricLineData, metricMatrixData, metricScatterData, metricTableData, scopeSummaryData, scoreboardData, } from "./compute.js";
+import { attemptListData, copyFixPromptData, deltaTableData, evalListData, experimentComparisonData, experimentListData, heroData, metricLineData, metricMatrixData, metricScatterData, metricTableData, scopeSummaryData, scopeWarningsData, scoreboardData, traceWaterfallData, } from "./compute.js";
 import { collectItems, locatorOf, resolveInput } from "./aggregate.js";
-import { attemptListText, deltaText, evalListText, experimentComparisonText, experimentListText, barsText, lineText, matrixText, scatterText, scoreboardText, scopeSummaryText, tableText, } from "./text/faces.js";
+import { attemptListText, deltaText, evalListText, experimentComparisonText, experimentListText, barsText, heroCardText, lineText, matrixText, scatterText, scopeWarningsText, scoreboardText, scopeSummaryText, tableText, traceWaterfallText, } from "./text/faces.js";
 import { ScopeSummary as ScopeSummaryWeb } from "./react/ScopeSummary.js";
 import { ExperimentComparisonView } from "./react/ExperimentComparison.js";
 import { ExperimentList as ExperimentListWeb } from "./react/ExperimentList.js";
 import { EvalList as EvalListWeb } from "./react/EvalList.js";
 import { AttemptList as AttemptListWeb } from "./react/AttemptList.js";
+import { HeroCard as HeroCardWeb } from "./react/HeroCard.js";
+import { PoweredBy as PoweredByWeb } from "./react/PoweredBy.js";
+import { ScopeWarnings as ScopeWarningsWeb } from "./react/ScopeWarnings.js";
+import { CopyFixPrompt as CopyFixPromptWeb } from "./react/CopyFixPrompt.js";
+import { TraceWaterfall as TraceWaterfallWeb } from "./react/TraceWaterfall.js";
 import { MetricTable as MetricTableWeb } from "./react/MetricTable.js";
 import { MetricMatrix as MetricMatrixWeb } from "./react/MetricMatrix.js";
 import { MetricBars as MetricBarsWeb } from "./react/MetricBars.js";
@@ -183,6 +188,56 @@ const validateAttemptListData = (data) => {
     }
     return null;
 };
+const validateHeroData = (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 = (data) => {
+    if (!Array.isArray(data))
+        return "expected an array of ScopeWarning";
+    for (const item of data) {
+        if (!isObject(item) || typeof item.kind !== "string" || typeof item.message !== "string") {
+            return "each warning needs { kind, message, … }";
+        }
+    }
+    return null;
+};
+const validateCopyFixPromptData = (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 = (data) => {
+    if (!Array.isArray(data))
+        return "expected an array of TraceWaterfallRow";
+    for (const row of data) {
+        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) {
+            if (!isObject(span) || typeof span.name !== "string" || typeof span.startOffsetMs !== "number") {
+                return "each span needs { name, kind, startOffsetMs, durationMs, failed }";
+            }
+        }
+    }
+    return null;
+};
 function makeDataComponent(def) {
     const assertData = (data) => {
         const problem = def.validate(data);
@@ -286,7 +341,7 @@ export const AttemptList = makeDataComponent({
     dataFn: (input) => attemptListData(input),
     specKeys: [],
     validate: validateAttemptListData,
-    web: (props, ctx) => (_jsx(AttemptListWeb, { data: props.data, total: props.total, locale: props.locale ?? ctx.locale, attemptHref: hrefOf(props, ctx) ?? ctx.attemptHref, className: props.className })),
+    web: (props, ctx) => (_jsx(AttemptListWeb, { data: props.data, total: props.total, filter: props.filter, locale: props.locale ?? ctx.locale, attemptHref: hrefOf(props, ctx) ?? ctx.attemptHref, className: props.className })),
     text: (props, ctx) => attemptListText(props.data, props.total, ctx),
 });
 /**
@@ -316,6 +371,100 @@ export const FailureList = defineComponent(async (props, ctx) => {
     return (_jsx(AttemptList, { data: failures.slice(0, limit), total: failures.length, attemptHref: props.attemptHref, locale: props.locale, className: props.className }));
 });
 FailureList.displayName = "FailureList";
+/** HeroCard 的 data 校验入口(它不经 makeDataComponent,数据形态是唯一形态)。 */
+const assertHeroData = (data) => {
+    const problem = validateHeroData(data);
+    if (problem !== null)
+        throw dataShapeError("HeroCard", "heroData", "HeroData", problem);
+    return data;
+};
+/**
+ * `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({
+    web: (props, ctx) => {
+        assertHeroData(props.data);
+        return _jsx(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";
+/**
+ * `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(async ({ title, className }, ctx) => (_jsx(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({
+    web: () => _jsx(PoweredByWeb, {}),
+    text: () => "",
+});
+PoweredBy.displayName = "PoweredBy";
+/**
+ * `ScopeWarnings`:选择警告区,警告的唯一呈现组件。把 Scope 携带的 `ScopeWarning[]`
+ * 按「下一步动作」聚合渲染(带 experimentId 的按实验聚合、非实验作用域按 kind 聚合;
+ * integrity 组在前);web 面组头带去重后的可复制命令、明细收原生 `<details>`(总条数 ≤ 3
+ * 默认展开),text 面同构但不折叠。空警告集与裸 `Snapshot[]` 输入两面零输出
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export const ScopeWarnings = makeDataComponent({
+    name: "ScopeWarnings",
+    dataFnName: "scopeWarningsData",
+    shapeName: "ScopeWarning[]",
+    dataFn: (input) => scopeWarningsData(input),
+    specKeys: [],
+    validate: validateScopeWarningsData,
+    web: (props, ctx) => props.data.length === 0 ? null : (_jsx(ScopeWarningsWeb, { data: props.data, locale: props.locale ?? ctx.locale, className: props.className })),
+    text: (props, ctx) => scopeWarningsText(props.data, ctx),
+});
+/**
+ * `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({
+    name: "CopyFixPrompt",
+    dataFnName: "copyFixPromptData",
+    shapeName: "CopyFixPromptData",
+    dataFn: (input) => copyFixPromptData(input),
+    specKeys: [],
+    validate: validateCopyFixPromptData,
+    web: (props, ctx) => props.data.failures === 0 ? null : (_jsx(CopyFixPromptWeb, { data: props.data, locale: props.locale ?? ctx.locale, className: props.className })),
+    text: () => "",
+});
+/**
+ * `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({
+    name: "TraceWaterfall",
+    dataFnName: "traceWaterfallData",
+    shapeName: "TraceWaterfallRow[]",
+    dataFn: (input) => traceWaterfallData(input),
+    specKeys: [],
+    validate: validateTraceWaterfallData,
+    web: (props, ctx) => (_jsx(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),
+});
 /** 榜单:一行一个维度值、一列一个指标,回答「谁整体更好」。 */
 export const MetricTable = makeDataComponent({
     name: "MetricTable",

package/dist/report/compute.d.ts

@@ -1,4 +1,4 @@
-import type { AttemptListItem, DeltaData, DeltaPair, DimensionInput, EvalListItem, ExperimentComparisonData, ExperimentListItem, FlagPairs, LineData, MatrixData, Metric, NumericAxis, ReportInput, ScatterData, ScopeSummaryData, ScoreboardData, TableData } from "./types.ts";
+import type { AttemptListItem, CopyFixPromptData, DeltaData, DeltaPair, DimensionInput, EvalListItem, ExperimentComparisonData, ExperimentListItem, FlagPairs, HeroData, LineData, MatrixData, Metric, NumericAxis, ReportInput, ScatterData, ScopeSummaryData, ScopeWarning, ScoreboardData, TableData, TraceWaterfallRow } from "./types.ts";
 import type { JsonValue } from "../types.ts";
 export interface MetricTableOptions {
     /** 行维度(内置 / 自定义 / flag() / runConfig())。 */
@@ -110,3 +110,30 @@ export interface DeltaTableOptions {
     evals?: string | readonly string[];
 }
 export declare function deltaTableData(input: ReportInput, options: DeltaTableOptions): Promise<DeltaData>;
+/**
+ * `heroData(input)`:站点标题区的运行 meta——`latestStartedAt` 取范围内最新快照的开始时间
+ * (空范围为 null,不编造当前时间),`snapshots` 计贡献当前水位的快照数
+ * (docs/feature/reports/library/site-components.md「HeroCard」)。
+ */
+export declare function heroData(input: ReportInput): Promise<HeroData>;
+/**
+ * `scopeWarningsData(input)`:Scope 携带的挑选警告原样透出;`input` 是裸 `Snapshot[]` 时
+ * 没有挑选过程、没有警告,返回空数组,也如实
+ * (docs/feature/reports/library/site-components.md「ScopeWarnings」)。
+ */
+export declare function scopeWarningsData(input: ReportInput): Promise<readonly ScopeWarning[]>;
+/**
+ * `copyFixPromptData(input)`:把范围内全部失败(verdict 为 failed / errored 的 attempt)
+ * 整理成一段可交给 coding agent 的修复 prompt——逐失败含 eval id、主失败摘要与 attempt
+ * 下钻命令(`niceeval show @<locator>`)。prompt 面向 agent,固定英文
+ * (docs/feature/reports/library/site-components.md「CopyFixPrompt」)。
+ */
+export declare function copyFixPromptData(input: ReportInput): Promise<CopyFixPromptData>;
+/**
+ * `traceWaterfallData(input)`:每个 attempt 一行的执行时间瀑布摘要。span 事实只来自
+ * trace artifact(经 AttemptHandle 懒加载的 canonical OTel span);runner 生命周期节点
+ * (`result.phases`)不进瀑布。行内只汇总顶层 span(parentSpanId 缺失或不在本 trace 内),
+ * 按 startOffsetMs 升序;trace 缺失或为空时 `durationMs` 为 null、行照常出现
+ * (docs/feature/reports/library/site-components.md「TraceWaterfall」)。
+ */
+export declare function traceWaterfallData(input: ReportInput): Promise<readonly TraceWaterfallRow[]>;