niceeval 0.12.1 → 0.12.2-canary.31

package/docs-site/zh/reference/official-adapters.mdx

@@ -4,21 +4,25 @@ sidebarTitle: "官方适配器"
 description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么、怎么鉴权，Sandbox 型里怎么装 MCP server、Skill、插件，怎么使用 Agent 官方配置文件。"
 ---
 
-[NiceEval](https://niceeval.com/) 随包带几个官方 Adapter（`niceeval/adapter` 导出的工厂函数），按被测对象要不要隔离工作区分两类：**Sandbox 型**（`claude-code` / `codex` / `bub`）在 Docker 或云端 Sandbox 里跑 coding-agent CLI，能装 MCP server、Skill、Python 插件；**非 Sandbox 型**无侵入连一个已经在跑的 HTTP 服务，或者帮你手写 adapter 时省掉事件流映射。这篇按类型和具体 Adapter 分节，重点是每个 Adapter 的配置项——怎么选、怎么跑通第一条评估用例，见[接入你的 Agent](/zh/tutorials/connect-your-agent)。
+[NiceEval](https://niceeval.com/) 随包带几个官方 Adapter（`niceeval/adapter` 导出的工厂函数），按被测对象要不要隔离工作区分两类。**Sandbox 型**（`claude-code` / `codex` / `bub`）在 Docker 或云端 Sandbox 里跑 coding-agent CLI，能装 MCP server、Skill、Python 插件。**非 Sandbox 型**无侵入连一个已经在跑的 HTTP 服务，或者帮你手写 adapter 时省掉事件流映射。这篇按类型和具体 Adapter 分节，重点是每个 Adapter 的配置项——怎么选、怎么跑通第一条评估用例，见[接入你的 Agent](/zh/tutorials/connect-your-agent)。
 
 ## Sandbox 适配器
 
-三个内置 Sandbox agent 都用 `defineSandboxAgent` 构造，鉴权走环境变量（可用工厂参数覆盖），并且都支持在 Sandbox `setup` 阶段装扩展。怎么运行内置 Sandbox agent、目录结构和自定义 Sandbox adapter，见 [Sandbox Agent](/zh/tutorials/sandbox-agent)；这里只讲每个 Adapter 能装什么、配置项怎么写。
+三个内置 Sandbox agent 都用 `defineSandboxAgent` 构造，鉴权走环境变量（可用工厂参数覆盖），并且都支持在 Sandbox `setup` 阶段装扩展。怎么运行内置 Sandbox agent、目录结构和自定义 Sandbox adapter，见 [Sandbox Agent](/zh/tutorials/sandbox-agent)。这里只讲每个 Adapter 能装什么、配置项怎么写。
 
 本页的 `settingsFile` / `configFile` 都相对 NiceEval 项目根解析。项目根是执行 `niceeval` 时的当前工作目录，也就是包含 `niceeval.config.ts` 的目录，不是评估用例或 Experiment 文件所在目录。例如 Experiment 在 `experiments/web/no-search.ts`、配置在 `configs/codex/no-web.toml` 时，仍写 `configFile: "configs/codex/no-web.toml"`。
 
 ### claude-code
 
 - **鉴权**：`ANTHROPIC_API_KEY`（工厂参数 `apiKey` 可覆盖），可选 `ANTHROPIC_BASE_URL`（工厂参数 `baseUrl`）。
-- **装 MCP server**：`mcpServers` 配置项，`setup` 阶段写进 Sandbox 里用户级的 `~/.claude.json`（顶层 `mcpServers` 字段）。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）；远程 Streamable HTTP 端点写 `url`（可带 `headers`，逐字进请求头，常用于 `Authorization`），写成 `{ "type": "http", "url": …, "headers": … }` 条目。`url` 要 Sandbox 内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
-- **装 Skill**：`skills: SkillSpec[]`——本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进 Sandbox 的 project 级 `.claude/skills/<name>/`，claude CLI 原生发现（原生 `Skill` 工具调用被 adapter 归一为 `skill.loaded` 事件，不重复记成工具调用；用 `t.loadedSkill()` 断言，不是 `t.calledTool("Skill", ...)`）。
+- **装 MCP server**：`mcpServers` 配置项，`setup` 阶段写进 Sandbox 里用户级的 `~/.claude.json`（顶层 `mcpServers` 字段）。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）。远程 Streamable HTTP 端点写 `url`（可带 `headers`，逐字进请求头，常用于 `Authorization`），写成 `{ "type": "http", "url": …, "headers": … }` 条目。`url` 要 Sandbox 内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
+- **装 Skill**：`skills: SkillSpec[]`。本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进 Sandbox 的 project 级 `.claude/skills/<name>/`，claude CLI 原生发现（原生 `Skill` 工具调用被 adapter 归一为 `skill.loaded` 事件，不重复记成工具调用。用 `t.loadedSkill()` 断言，不是 `t.calledTool("Skill", ...)`）。
 - **装原生 Plugin**：`plugins: ClaudeCodePluginSpec[]`，每一项声明 Marketplace 连接（`name` / `source` / 可选 `ref`）和其中的 Plugin 名。这个类型只属于 claude-code，传不进 codex。复用 Sandbox 的 Experiment 不用额外处理残留：每条 Attempt 开始前，同名 marketplace 注册与已装 Plugin 都会按声明的 `source` / `ref` 重新安装。
-- **官方配置文件**：`settingsFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径；它指向一份完整的 Claude Code `settings.json`。路径相对项目根，只允许普通相对路径或 `./` 前缀；`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.claude/settings.json`；不继承宿主机配置，也不 deep merge 或重新序列化。`model` 和 `env` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。Secret 走环境变量，别写进配置文件。
+- **官方配置文件**：`settingsFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径。它指向一份完整的 Claude Code `settings.json`。路径相对项目根，只允许普通相对路径或 `./` 前缀。`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。
+
+  Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.claude/settings.json`。不继承宿主机配置，也不 deep merge 或重新序列化。`model` 和 `env` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。
+
+  Secret 走环境变量，别写进配置文件。
 - **安装后脚本**：`postSetup: SandboxHook[]`，在写 settings、挂 MCP、装 Skill 与 Plugin 全部完成后，按数组顺序在 Sandbox 里跑你的 Hook 函数。典型用途是运行插件自带的 setup 脚本（比如它要往全局配置里登记 hook）——这类脚本必须等安装产物就位才能跑。与它成对的收尾是 `preTeardown: SandboxHook[]`：按逆序、在 agent 自己的 teardown 步骤之前执行，当且仅当 `postSetup` 的时点已经走到才触发。Hook 抛错算基础设施错误（Attempt 记 errored），不算 agent 答题失败。
 - **tracing**：claude CLI 的 beta 原生遥测（`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`），span 只有结构和计时，细节见 [OTel 接入](/zh/tutorials/connect-otel)。
 
@@ -34,7 +38,7 @@ description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么
 ```ts
 import { defineExperiment } from "niceeval";
 import { claudeCodeAgent } from "niceeval/adapter";
-import { dockerImageSandbox } from "niceeval/sandbox";
+import { dockerSandbox } from "niceeval/sandbox";
 
 export default defineExperiment({
   agent: claudeCodeAgent({
@@ -54,7 +58,7 @@ export default defineExperiment({
     settingsFile: "configs/claude-code/no-web.json",
   }),
   model: "claude-sonnet-4-6",
-  sandbox: dockerImageSandbox({ image: "node:24-slim" }),
+  sandbox: dockerSandbox({ source: { type: "image", image: "node:24-slim" } }),
 });
 ```
 
@@ -62,16 +66,20 @@ export default defineExperiment({
 
 - **鉴权**：`CODEX_API_KEY`（工厂参数 `apiKey` 可覆盖，不是 `OPENAI_API_KEY`），可选 `CODEX_BASE_URL`（工厂参数 `baseUrl`）接 OpenAI 兼容代理。
 - **Agent 进程环境**：`env` 会注入每次 `codex exec` 与 `codex exec resume`。Codex 启动的 Session 生命周期 Hook、MCP 动态请求头和命令子进程都会继承。值不会拼进 shell 文本或写入安装清单，并按潜在敏感值从 timing、execution 与错误证据中脱敏。`CODEX_API_KEY` 仍由 `apiKey` 或宿主环境提供，并覆盖 `env` 里的同名键。`PATH` 是 Sandbox 受管变量，不接受经 `env` 声明——出现即在 `codexAgent()` 调用时报错，改用 Sandbox 的 `pathPrepend`（见 [Sandbox provider](/zh/tutorials/sandbox-providers)）。
-- **装 MCP server**：`mcpServers` 配置项，`setup` 阶段追加进 `~/.codex/config.toml` 的 `[mcp_servers.<name>]` 段。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）；远程 Streamable HTTP 端点写 `url`（可带 `headers`，写成 `[mcp_servers.<name>.http_headers]` 子表）。`url` 要 Sandbox 内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
+- **装 MCP server**：`mcpServers` 配置项，`setup` 阶段追加进 `~/.codex/config.toml` 的 `[mcp_servers.<name>]` 段。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）。远程 Streamable HTTP 端点写 `url`（可带 `headers`，写成 `[mcp_servers.<name>.http_headers]` 子表）。`url` 要 Sandbox 内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
 
   <Warning>
     是复数 `mcp_servers`：单数 `[mcp_server.x]` 会被 codex CLI 静默忽略，MCP 压根挂不上，且不会报错——自查用 `codex mcp list`。
   </Warning>
 
-- **装 Skill**：`skills: SkillSpec[]`，与 claude-code 同一个类型。装进 `.agents/skills/<name>/`，并把发现指引写进 AGENTS.md——codex 没有 claude-code 那种原生 Skill 工具，只把文件装进去它不会主动去读；断言"用没用到"看它是否真的执行过读那个文件的 shell 命令，没有工具调用可以直接认。
+- **装 Skill**：`skills: SkillSpec[]`，与 claude-code 同一个类型。装进 `.agents/skills/<name>/`，并把发现指引写进 AGENTS.md——codex 没有 claude-code 那种原生 Skill 工具，只把文件装进去它不会主动去读。断言"用没用到"看它是否真的执行过读那个文件的 shell 命令，没有工具调用可以直接认。
 - **装原生 Plugin**：`plugins: CodexPluginSpec[]`，声明 Marketplace 连接（`name` / `source` / 可选 `ref` / 可选 `sparse`）和其中的 Plugin 名。`sparse` 是路径数组（如 `[".agents", "plugins/repo-map"]`），每项让 `codex plugin marketplace add` 带一个 `--sparse <path>`，大仓库只拉插件所需路径，装出来的内容不变。这个类型只属于 codex，传不进 claude-code。复用 Sandbox 的 Experiment 不用额外处理残留：每条 Attempt 开始前，同名 marketplace 注册与已装 Plugin 都会按声明的 `source` / `ref` 重新安装。
-- **官方配置文件**：`configFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径；它指向一份完整的 Codex `config.toml`。路径相对项目根，只允许普通相对路径或 `./` 前缀；`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.codex/config.toml`；不继承宿主机配置，也不拼接、deep merge 或解析后重写。`model`、`model_provider`、`model_providers`、`model_reasoning_effort`、`mcp_servers`、`otel` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。Secret 走环境变量，别写进配置文件。
-- **安装后脚本**：`postSetup: SandboxHook[]`，语义与 claude-code 相同：全部安装步骤完成后按序在 Sandbox 里跑你的 Hook 函数，适合运行插件自带的 setup 脚本；成对的 `preTeardown: SandboxHook[]` 按逆序在 agent teardown 之前收尾，当且仅当 `postSetup` 的时点已经走到才触发。脚本往 codex 全局配置登记的 hook 不需要交互式信任确认——运行时 `codex exec` 已绕过 hook 信任门槛，hook 直接生效。
+- **官方配置文件**：`configFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径。它指向一份完整的 Codex `config.toml`。路径相对项目根，只允许普通相对路径或 `./` 前缀。`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。
+
+  Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.codex/config.toml`。不继承宿主机配置，也不拼接、deep merge 或解析后重写。`model`、`model_provider`、`model_providers`、`model_reasoning_effort`、`mcp_servers`、`otel` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。
+
+  Secret 走环境变量，别写进配置文件。
+- **安装后脚本**：`postSetup: SandboxHook[]`，语义与 claude-code 相同：全部安装步骤完成后按序在 Sandbox 里跑你的 Hook 函数，适合运行插件自带的 setup 脚本。成对的 `preTeardown: SandboxHook[]` 按逆序在 agent teardown 之前收尾，当且仅当 `postSetup` 的时点已经走到才触发。脚本往 codex 全局配置登记的 hook 不需要交互式信任确认——运行时 `codex exec` 已绕过 hook 信任门槛，hook 直接生效。
 - **tracing**：内置，通过 `config.toml` 的 `[otel.trace_exporter.otlp-http]` 段配置，协议 `http/json`。
 
 例如，用 `configs/codex/no-web.toml` 关闭内置联网检索：
@@ -84,11 +92,13 @@ web_search = "disabled"
 ```ts
 import { defineExperiment } from "niceeval";
 import { codexAgent } from "niceeval/adapter";
-import { dockerImageSandbox } from "niceeval/sandbox";
+import { dockerSandbox } from "niceeval/sandbox";
+
+const memorySpace = "memorybench-nowledge";
 
 export default defineExperiment({
   agent: codexAgent({
-    env: { NMEM_SPACE: "memorybench-nowledge" },
+    env: { NMEM_SPACE: memorySpace },
     mcpServers: [
       { name: "browser", command: "npx", args: ["-y", "@anthropic/mcp-browser"] },
       { name: "team-memory", url: "https://mem.example.com/mcp/", headers: { Authorization: `Bearer ${process.env.MEM_API_KEY}` } },
@@ -102,8 +112,9 @@ export default defineExperiment({
     ],
     configFile: "configs/codex/no-web.toml",
   }),
+  flags: { memorySpace },
   model: "gpt-5.4",
-  sandbox: dockerImageSandbox({ image: "node:24-slim" }),
+  sandbox: dockerSandbox({ source: { type: "image", image: "node:24-slim" } }),
 });
 ```
 
@@ -111,17 +122,17 @@ export default defineExperiment({
 
 - **鉴权**：`BUB_API_KEY` + `BUB_API_BASE`（OpenAI 兼容代理），工厂参数 `apiKey` / `apiBase` 可覆盖。
 - **装 Skill**：`skills: SkillSpec[]`，与另外两个 Adapter 同一个类型。装进 `.agents/skills/<name>/`，发现指引写进 AGENTS.md。
-- **装插件**：`pythonPlugins: PythonPluginSpec[]`（`{ package }`：PyPI 包、版本约束或 git URL），`setup` 阶段进 `uv tool install … --with <package>`。这个类型只属于 bub；package 集合进安装 checkpoint key，插件不同的两个变体不会复用同一份安装缓存。
-- **预制 Bub**：NiceEval 的 E2B 配方会把 Bub、OTel 插件和 Python 插件集合算成安装指纹。Adapter 只复用指纹完全一致的环境；仅在 PATH 里放一个 `bub` 不足以证明兼容。构建入口见 [Sandbox provider · 从官方基线继续构建以提速](/zh/tutorials/sandbox-providers#从官方基线继续构建以提速)。
+- **装插件**：`pythonPlugins: PythonPluginSpec[]`（`{ package }`：PyPI 包、版本约束或 git URL），`setup` 阶段进 `uv tool install … --with <package>`。这个类型只属于 bub。package 集合进安装 checkpoint key，插件不同的两个变体不会复用同一份安装缓存。
+- **预制 Bub**：NiceEval 的 E2B 配方会把 Bub、OTel 插件和 Python 插件集合算成安装指纹。Adapter 只复用指纹完全一致的环境。仅在 PATH 里放一个 `bub` 不足以证明兼容。构建入口见 [Sandbox provider · 从官方基线继续构建以提速](/zh/tutorials/sandbox-providers#从官方基线继续构建以提速)。
 - bub 没有 `mcpServers`——MCP 只属于支持它的 Adapter，Config 上压根没有这个字段。
-- **安装后脚本**：`postSetup: SandboxHook[]`，语义与另外两个 Adapter 相同：全部安装步骤完成后按序在 Sandbox 里跑你的 Hook 函数；成对的 `preTeardown: SandboxHook[]` 按逆序在 agent teardown 之前收尾，当且仅当 `postSetup` 的时点已经走到才触发。
+- **安装后脚本**：`postSetup: SandboxHook[]`，语义与另外两个 Adapter 相同：全部安装步骤完成后按序在 Sandbox 里跑你的 Hook 函数。成对的 `preTeardown: SandboxHook[]` 按逆序在 agent teardown 之前收尾，当且仅当 `postSetup` 的时点已经走到才触发。
 - **安装方式**：走 `uv tool install`（PyPI 包，不是 npm 包），首次安装会建 checkpoint 缓存加速后续 Sandbox。
 - **tracing**：内置，通过环境变量注入，协议 `http/protobuf`。
 
 ```ts
 import { defineExperiment } from "niceeval";
 import { bubAgent } from "niceeval/adapter";
-import { dockerImageSandbox } from "niceeval/sandbox";
+import { dockerSandbox } from "niceeval/sandbox";
 
 export default defineExperiment({
   agent: bubAgent({
@@ -129,7 +140,7 @@ export default defineExperiment({
     pythonPlugins: [{ package: "bub-plugin-memory==1.3.0" }],
   }),
   model: "gpt-5.4",
-  sandbox: dockerImageSandbox({ image: "node:24-slim" }),
+  sandbox: dockerSandbox({ source: { type: "image", image: "node:24-slim" } }),
 });
 ```
 
@@ -148,7 +159,7 @@ export default defineExperiment({
 | tracing | ✅（beta，仅结构与计时） | ✅ | ✅ |
 | 安装方式 | npm 全局包（需镜像自带 Node） | 自带运行时的原生包（解压即用，镜像无需 Node） | `uv tool install`（PyPI） |
 
-装了什么有据可查：Adapter 在 `setup` 收尾把安装清单交给运行器，存成 Attempt Artifact `agent-setup.json`（库里读 `attempt.agentSetup()`；清单不落沙箱磁盘，agent 看不到它）。清单只记来源、ref、Skill/Plugin 名、解析出的版本，以及官方配置文件的项目相对路径和 SHA-256；不保存配置正文、API Key 或环境变量值。MCP server 同理只记非敏感字段：stdio 形态记 `name` / `command` / `args` 不记 `env`，HTTP 形态记 `name` / `url` 不记 `headers`。
+装了什么有据可查：Adapter 在 `setup` 收尾把安装清单交给运行器，存成 Attempt Artifact `agent-setup.json`（库里读 `attempt.agentSetup()`。清单不落沙箱磁盘，agent 看不到它）。清单只记来源、ref、Skill/Plugin 名、解析出的版本，以及官方配置文件的项目相对路径和 SHA-256。不保存配置正文、API Key 或环境变量值。MCP server 同理只记非敏感字段：stdio 形态记 `name` / `command` / `args` 不记 `env`，HTTP 形态记 `name` / `url` 不记 `headers`。
 
 ## 非 Sandbox 适配器
 
@@ -166,7 +177,7 @@ export default defineExperiment({
   });
   ```
 
-- **SDK 事件流转换器**（`createClaudeSdkEventStream` / `createPiAgentEventStream` / `createCodexThreadEventStream`）：手写 adapter 连一个跑着 Claude Agent SDK / pi-agent-core / Codex SDK 的服务时，原生帧到标准事件的映射官方已经做好，只需要补传输粘合，配合 `driveFrameStream` 逐帧驱动。
+- **SDK 事件流转换器**（`createClaudeSdkEventStream` / `createPiAgentEventStream` / `createCodexThreadEventStream`）：适合手写 SDK Adapter。官方已经做好原生帧到标准事件的映射。你只需补上请求应用接口的代码，再用 `driveFrameStream` 逐帧读取结果。
 - **`turnFromAiSdk`**：AI SDK `generateText` / `streamText` 结果到标准事件流的转换器，写自己的 HTTP web agent adapter 时用。
 
 这几个适配器的完整参数、能力表和示例代码，见[内置 Agent 能力参考](/zh/reference/builtin-agents)。
@@ -183,4 +194,4 @@ export default defineExperiment({
 - [Sandbox Agent](/zh/tutorials/sandbox-agent) — 怎么运行内置 Sandbox agent，以及怎么写自己的。
 - [内置 Agent 能力参考](/zh/reference/builtin-agents) — 每个适配器逐能力盘点、非 Sandbox 适配器的完整代码示例。
 - [OTel 接入](/zh/tutorials/connect-otel) — 把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
-- [Adapter 参考](/zh/reference/define-agent) — `defineDirectAgent` / `defineSandboxAgent` 完整参数。
+- [Adapter 参考](/zh/reference/define-agent) — `defineAgent` / `defineSandboxAgent` 完整参数。

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

@@ -1,405 +1,121 @@
 ---
-title: "报告组件 API"
-description: "niceeval/report 的 page、计算函数、结果值与双面组件参考。"
+title: "报告 API"
+description: "RecordProjection、Calculation、Page、ReportExecution 与静态导出的公开边界。"
 ---
 
-报告作者使用一条普通 TypeScript 数据流：
+Report 作者只从 `niceeval/report` 声明需要哪些 `RecordProjection`，再把投影结果和计算结果包装成页面或下载。作者不接收 reader、路径、raw Attachment 或磁盘字段。
 
 ```text
-Sample 或 AttemptEvidence
-  → 普通函数
-  → 可序列化结果值
-  → 组件
-  → text / web
+AnalysisSample
+        ↓  opaque RecordProjection declarations
+ProjectedSample
+        ↓  Calculation / Page / PageFamily / Download
+immutable ReportExecution
+        ├─ show
+        ├─ view revision
+        └─ static export
 ```
 
-公开 API 没有统一的惰性查询对象。
-异步读取和计算在 page render 中完成，组件只显示已经算好的值。
+## 声明 RecordProjection
 
-## 定义报告
+NiceEval 提供的 opaque projector 固定形成一种 typed view。Report 用三个 constructor 声明逻辑访问；作者不能定义 raw family/projector：
 
-单页报告直接传 render 函数：
+| constructor | 对齐方式 |
+| --- | --- |
+| `attemptSlotProjection(projector)` | 对 Sample 的每个 slot 形成 entry，并读取它精确引用的 Attempt Attachment。 |
+| `attemptOriginRunProjection(projector)` | 对每个 slot 形成 entry，并读取该 Attempt 的 origin Run Attachment。 |
+| `selectedRunProjection(projector)` | 对每个 selected Run 形成 entry，并读取该 Run Attachment。 |
 
-```tsx
-export default defineReport(async (sample) => {
-  const rows = toExperimentRows(sample);
-
-  return (
-    <Col>
-      <Table rows={rows} />
-    </Col>
-  );
-});
-```
-
-多页报告静态声明 `pages`：
-
-```ts
-interface PageDefinition<P = void, I = Sample> {
-  id: string;
-  title: LocalizedText;
-  navigation?: boolean;
-  params?: PageParams<P>;
-  load?: (
-    base: Sample,
-    params: P,
-    ctx: PageLoadContext,
-  ) => I | Promise<I>;
-  render: PageRender<I>;
-}
-```
-
-`pages` 是非空有序数组。`id` 必须唯一。
-`load` 决定这页的输入从哪来，省略时输入就是当前 Sample。
-声明 `params` 的页按参数产生多个实例（Attempt 详情、Experiment 详情都是这种页），必须同时声明 `load` 并写 `navigation: false`。
-宿主只执行当前请求的 page render。
-
-外壳字段只有 `title`、`theme`、`dimensionPins`、`head` 与 `pages`。
-页脚和页头链接用普通组件组合；组件脚本样式随自定义 renderer 声明。
-
-## Calculation
-
-Calculation 由 `rollup()` 产生：
+前两种访问不会丢掉 `excluded`、`not-recorded` 或 `core-invalid` slot。相同 Attempt 被多个 slot 引用时，公开结果仍按 slot 对齐。
 
 ```ts
-const changedLines = rollup(
-  async (attempt) => {
-    const diff = await attempt.diff();
-    return diff ? countChangedLines(diff) : null;
-  },
-  {
-    withinEval: min,
-    acrossEvals: mean,
-    unit: "lines",
-    better: "lower",
-  },
-);
-```
-
-Reducer 是函数值。内建入口提供：
+const verdicts = attemptSlotProjection(verdictProjector);
+const evaluations = selectedRunProjection(evaluationsProjector);
 
-```ts
-mean;
-sum;
-min;
-max;
-percentile(0.95);
+const inputs = reportInputs({ verdicts, evaluations });
 ```
 
-省略题内或跨题 reducer 时使用 `mean`。
-`null` 不参与 reducer；空集合保持 `null`。
-
-官方 Calculation 和用户 Calculation 使用相同的 `rollup()`。
-常用官方值包括 `passRate`、`costUSD` 与 `durationMs`。
+`reportInputs` 固定输入 key 与其 projection 的类型。host 在执行任何 Record I/O 前闭合这组依赖，并让每个 projection 至多执行一次。
 
-## `aggregate()`
+## 定义 Calculation 和页面
 
-`aggregate()` 按分组函数执行多个 Calculation：
+Calculation 只从静态声明的 projection 派生业务值。它自己返回业务 `observed` 与 `denominator`；host 不会从 coverage 或 entry 数量猜测统计口径。
 
-```tsx
-const performance = await aggregate(sample, {
-  by: {
-    agent,
-    experiment,
-  },
-  values: {
-    passRate,
-    costUSD,
-  },
+```ts
+const passRate = defineCalculation({
+  id: Either.getOrThrow(reportComponentId("pass-rate")),
+  inputs,
+  completeness: "allow-partial",
+  calculate: ({ sample, inputs }) =>
+    calculatePassRate(sample, inputs.verdicts, inputs.evaluations),
 });
 ```
 
-结果是普通只读数组：
+直接消费 projection 的 Calculation、Page、PageFamily 和 Download 必须选择完整度：
 
-```ts
-readonly {
-  agent: string;
-  experiment: string;
-  passRate: MetricValue;
-  costUSD: MetricValue;
-  refs: readonly AttemptLocator[];
-}[];
-```
+| 选择 | 行为 |
+| --- | --- |
+| `allow-partial` | callback 收到完整的 `ProjectedSample`、coverage 与 issues，可以显示部分结果。 |
+| `require-complete` | 必需数据不完整时不调用 callback，result 是 `data-unavailable`。 |
 
-`by` 和 `values` 的键不能重名，也不能使用保留键 `refs`。
-自定义分组可以是返回字符串的普通同步函数。
+`unavailable`、`migration-required`、`migration-unavailable`、`unsupported`、`invalid` 与 partial collection 都是 recorded-data problem。callback 的意外 throw 属于 execution problem，两者不能互相替代。
 
-## `MetricValue`
+Page 返回闭合的 `ReportDocument` 语义树。它不是 HTML、React element 或另一套文本输出。PageFamily 只能根据已投影或已计算的内存值展开 route，不能在展开时追加 Attachment I/O。
 
-```ts
-interface MetricValue {
-  value: number | null;
-  unit?: string;
-  format?: MetricFormat;
-  better?: "higher" | "lower";
-  bounds?: {
-    min?: number;
-    max?: number;
-  };
-  samples: number;
-  total: number;
-  basis: "attempt" | "eval" | "run" | "pair";
-  refs: readonly AttemptLocator[];
-}
-```
-
-`value: null` 表示缺数据或不适用，不等于零。
-`samples`、`total` 与 `basis` 解释分母。
-`refs` 让表格、图表和 Agent 下钻到原始 Attempt。
-
-复杂算法使用 `metricValue()` 和 `evidenceRow()` 构造带证据结果：
+## 组合一个 Report
 
 ```ts
-const point = evidenceRow({
-  eval: evalId,
-  delta: metricValue({
-    value,
-    samples,
-    total,
-    basis: "pair",
-    evidence,
-    unit: "%",
-  }),
+const overview = definePage({
+  id: Either.getOrThrow(reportComponentId("overview")),
+  route: Either.getOrThrow(reportRoute("/")),
+  calculations: { passRate },
+  render: ({ calculations }) =>
+    reportDocument({
+      title: "Summary",
+      children: [
+        reportMetric({
+          label: "Pass rate",
+          value:
+            calculations.passRate.state === "available"
+              ? calculations.passRate.value.rate
+              : null,
+        }),
+      ],
+    }),
 });
-```
-
-成对差异、稳定性、固定题集成绩单和历史趋势保留在对应报告旁。
-它们不共享一个没有稳定公式的公共函数。
-
-## 实体转换
-
-实体投影立即执行：
-
-```ts
-toAttemptRows(attempts);
-toExperimentRows(sample);
-toEvalRows(sample);
-await toTraceNodes(sample);
-toSampleNotices(sample);
-```
-
-函数返回精确结果形状，不返回统一包装。
-普通数组可以继续 `filter()`、`toSorted()`、`slice()` 或 join。
-
-高频实体提供薄组件：
-
-```tsx
-<AttemptList attempts={attempts} />
-<ExperimentTable input={sample} />
-```
-
-`ExperimentTable` 按 Experiment → Eval → Attempt 展开；
-网页面点击 Attempt 会打开现有详情 modal。
-
-默认实验比较直接使用：
-
-```tsx
-<ExperimentScatter input={sample} />
-```
-
-它画成本与主读数的散点：通过制使用通过率，计分制使用总分。
-
-## 组件属性
-
-| 组件 | 主要属性 |
-|---|---|
-| `Table` | `rows` |
-| `Scatter` | `points`、`x`、`y`、`point` |
-| `Line`、`Bars`、`Area` | `points`、`x`、`y` |
-| `Stat` | `value` |
-| `Grid` | `items` |
-| `Callouts` | `items` |
-| `Conversation` | `turns` |
-| `Waterfall` | `nodes` |
-| `SourceView` | `source` |
-| `DiffView` | `files` |
-| `AttemptDetails` | `attempt` |
-| `ExperimentDetails` | `input` |
-| `Hero` | `logo`、`description`、`links` |
-| `ExperimentScatter` | `input`、`series`、`connect`、`pointTarget` |
-| `ExperimentTable` | `input`、`sort`、`searchable` |
-
-`SourceView` 的 `source` 表示待显示的源码值。
-它不是惰性查询对象。
-
-## 品牌标题区
-
-`Hero` 可以直接显示产品 Logo、介绍和主要外链。
-间距、响应式布局、链接体裁与深浅色适配由 NiceEval 提供：
-
-```tsx
-<Hero
-  logo={{ src: memoryBenchLogo, alt: "MemoryBench" }}
-  description={{
-    en: "Does memory help coding agents ship better code?",
-    "zh-CN": "记忆能否帮助 coding agent 交付更好的代码？",
-  }}
-  links={[
-    {
-      label: "GitHub",
-      href: "https://github.com/acme/memorybench",
-    },
-  ]}
-/>
-```
-
-`logo.src` 使用浏览器可读取的图片 URL。
-`description` 与 `links[].label` 支持 `LocalizedText`。
-`show` 输出介绍与链接文字，但省略纯视觉 Logo；`view` 显示完整品牌标题区。
-
-## 表格
-
-```tsx
-<Table
-  rows={performance}
-  columns={[
-    "agent",
-    { field: "costUSD", label: "Spend" },
-    "passRate",
-  ]}
-/>
-```
-
-省略 `columns` 时按稳定字段顺序推导。
-排序、过滤和 limit 只改变显示行，不重新聚合。
-
-## 图表
-
-```tsx
-<Scatter
-  points={performance}
-  x="costUSD"
-  y="passRate"
-  point="agent"
-/>
-```
-
-从 Sample 派生的 points 必须带行级 `refs`，
-读数字段必须是 MetricValue。
-纯外部数值序列要显式声明 `external`，并且不提供 Attempt 下钻。
-
-一个点点开去哪由 `pointTarget` 决定，返回值是「页 id + 参数」：
-
-```tsx
-<Scatter
-  points={performance}
-  x="costUSD"
-  y="passRate"
-  point="experiment"
-  pointTarget={(row) => ({
-    page: "experiment",
-    params: { experiment: row.experiment },
-  })}
-/>
-```
-
-省略 `pointTarget` 时，行级 `refs` 恰好一个的点链到该 Attempt 详情；多个 `refs` 的点不带链接。
-报告里没有目标页时点也不带链接，不会出现假链接。
-
-`Line` 用于时间或有序数值，`Bars` 用于排行和堆叠，
-`Area` 用于累计量或区间。
-需要混合 mark 时使用 `ComposedChart`，每条 series 显式绑定字段和轴。
-
-横向排行榜直接使用官方 `Bars`：
-
-```tsx
-<Bars
-  points={ranking}
-  x="agent"
-  y="passRate"
-  sort={{ field: "passRate", direction: "desc" }}
-  limit={10}
-  layout="horizontal"
-/>
-```
-
-`sort` 与 `limit` 只改变显示顺序和可见行，不重新聚合。
-`layout="horizontal"` 在网页面使用横向排行条；
-text 面恒用横向条，保留分类标签、格式化终值与覆盖率。
-
-## Attempt 与 Experiment 详情
-
-两种详情都是参数化 page。
-官方导出 `standardAttemptPage` 与 `standardExperimentPage`，放进自己的 `pages` 数组即可复用完整详情：
-
-```tsx
-import {
-  standardAttemptPage,
-  standardExperimentPage,
-} from "niceeval/report/built-in";
 
 export default defineReport({
-  pages: [
-    { id: "overview", title: "Overview", render: overview },
-    standardAttemptPage,
-    standardExperimentPage,
-  ],
+  id: Either.getOrThrow(reportId("summary")),
+  calculations: { passRate },
+  pages: [overview],
 });
 ```
 
-自定义 Attempt 详情时复用官方页的 `params` 与 `load`，只换 `render`：
+`defineReport` 验证 ID 与组件引用。Page、PageFamily 和 Download 只能引用同一个 Report 已注册的 Calculation。页面 route 与下载路径必须通过对应 constructor 创建，避免输出冲突。
 
-```tsx
-{
-  ...standardAttemptPage,
-  render: (attempt) => (
-    <AttemptDetails attempt={attempt} />
-  ),
-}
-```
+## 由 show / view 执行 Report
 
-`render` 里可以显式调用：
+应用代码不调用 Report host。`niceeval show`、`niceeval view` 与 `view --out` 的内部 host
+选择 Run、执行 projection 与作者 graph，并形成不可变、自包含的 `ReportExecution`。
+包不导出 `niceeval/report/host`、`niceeval/report/host/node` 或 `executeReport()`。
 
-```ts
-toConversationTurns(attempt);
-toDiffFiles(attempt);
-toTimelineNodes(attempt);
-toAttemptSource(attempt);
-```
+`ReportExecution` 包含 Sample、projection 摘要、Calculation、family、页面、下载项与 problem table，但不包含 reader、路径、Scope、callback 或 projector token。
 
-`ExperimentDetails` 显示单个实验的完整读面：身份、读数摘要、判定构成、题目清单、覆盖缺口与实验级提示。
-默认散点的实验点点开就是这一页。
+每个 projection、Calculation、PageFamily、页面实例与 Download 在同一 execution 中最多执行一次。`show`、`view` 与 `exportStaticReport` 只消费完成后的 execution。
 
-## 自定义 renderer
+| 情况 | `show` / `view` | 静态导出 |
+| --- | --- | --- |
+| recorded-data problem | 显示问题，并保留其它成功内容。 | 可以导出，问题必须可见。 |
+| execution problem | 保留其它成功页面，并显示问题。 | 不导出。 |
 
-只有新增显示形状时才使用扩展入口：
+## view 与静态导出
 
-```tsx
-import { defineRenderer } from "niceeval/report/extension";
+`view` 每次 rebuild 构造新的固定 `ReportExecution`。完整成功后才替换当前 revision；失败保留 last-good execution，并显示 bounded rebuild problem。
 
-const ConfusionMatrix = defineRenderer({
-  text(value, options, context) {
-    return renderTextMatrix(value, options, context);
-  },
-  web(value, options, context) {
-    return <WebMatrix value={value} options={options} />;
-  },
-});
-```
-
-`text` 与 `web` 都是必填项。
-renderer 只接已经计算好的普通值，不读取 Sample、Record、artifact 或网络。
-
-脚本和样式放在 `assets`。
-初始 HTML 在没有 JavaScript 时仍必须完整可读。
-
-## React 入口
+静态导出只写一份已经完成的 execution。它先验证 semantic tree、route、下载项与 execution problems，再写出页面、host-data、downloads、manifest 和内建 runtime。所有内容写完后，最后写入 `complete` marker。
 
-`niceeval/report/react` 只导出纯 Web 组件与结果类型：
-
-```tsx
-const points = await aggregate(sample, {
-  by: { agent },
-  values: { passRate, costUSD },
-});
-
-<Scatter
-  points={points}
-  x="costUSD"
-  y="passRate"
-  point="agent"
-/>
-```
+## 相关页面
 
-服务端或构建进程负责打开 Record、选择 Sample 和计算结果。
-浏览器只接收序列化后的值。
+- [结果数据 API](/zh/reference/results-data)：在 Report callback 中消费 Sample 与 `ProjectedSample`。
+- [编写自定义报告](/zh/tutorials/custom-reports)：从投影写出一个实际 Report。
+- [发布静态报告](/zh/tutorials/publish-report)：导出并分享固定 execution。