niceeval 0.6.2 → 0.7.1

package/docs-site/zh/reference/cli.mdx

@@ -13,7 +13,7 @@ description: "NiceEval CLI 参考：exp、show、view、init、list 和 clean
     运行命名实验组或配置。可选尾随位置参数按 eval ID 前缀过滤。
   </Card>
   <Card title="npx niceeval init" icon="wand-magic-sparkles">
-    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例 eval 文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/guides/agent-feedback-loop)）。
+    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例 eval 文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/how-to/agent-feedback-loop)）。
   </Card>
   <Card title="npx niceeval list" icon="list">
     发现并打印所有 eval，不运行。
@@ -89,14 +89,16 @@ npx niceeval exp compare-models weather
 | `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
 | `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
 | `--allow-sensitive-artifacts` | boolean | `view --out` 专用:对非发布根(快照没有 publish:&#123;redaction:"applied"&#125; 标记)导出时的显式确认——静态站会原样携带未消毒的证据文件。 |
-| `--eval` | boolean | `show` 命令专用:该 attempt 运行时保存的 Eval 源码,gate/soft 断言标回源码行(证据切面)。 |
+| `--source` | boolean | `show` 命令专用:该 attempt 运行时保存的 Eval 源码,gate/soft 断言标回源码行(证据切面)。 |
 | `--execution` | boolean | `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。 |
 | `--timing` | boolean | `show` 命令专用:整个 Attempt 的统一时间树;裸 `--timing` 给有界诊断投影,`--timing=full` 逐节点展开全部 runner/已关联 OTel 节点。 |
 | `--diff` | boolean | `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 |
-| `--history` | boolean | `show` 命令专用:跨 run 时间轴,只列真实执行;与 `--report` 互斥。 |
+| `--history` | boolean | `show` 命令专用:执行时间轴——对匹配的每个 experiment × eval 分节,逐 attempt 列时间 / verdict / 摘要 / 耗时 / 成本 / locator;与 `--report` 互斥。 |
 | `--experiment` | string | `show` / `view` 命令专用:按路径段前缀收窄 experiment;组名会选中组内全部配置。 |
-| `--run` | string | `show` / `view` 命令专用:钉死看某一个结果目录(某次快照或 `copySnapshots` 产物)。 |
+| `--results` | string | `show` / `view` / `sandbox enter\|list\|stop` 共用:结果根目录(`.niceeval` 之外的另一个根,如 `copySnapshots` 产出的发布根)。 |
+| `--snapshot` | string | `view` 命令专用:只打开这一份快照文件(`snapshot.json`);文件不可读时命令失败(扫描模式只跳过)。 |
 | `--report` | string | `show` / `view` 命令专用:用文件默认导出的 `defineReport(...)` 替换两者共用的默认报告。 |
+| `--page` | string | `show` / `view` 命令专用:选择多页报告的页(页 id 见 `show --report` 的页索引);`view` 里定初始页。 |
 | `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行(按下面 `--output` 选中的 profile 给出预览)。 |
 | `--output` | string | 反馈 profile:`auto`(默认)按环境自动选择,`human` / `agent` / `ci` 强制指定;只改变终端展示,不改变选择、调度、判定、artifact 或退出码。`auto` 依次判定:stderr 是 TTY → human;否则 `CI`(或其它常见 CI 平台环境变量)存在 → ci;否则 → agent。 |
 | `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |
@@ -142,7 +144,7 @@ npx niceeval exp compare --output agent
 npx niceeval exp compare --output ci --strict --json .niceeval/ci-summary.json --junit .niceeval/junit.xml
 ```
 
-三种 profile 的完整对比见[运行器 · Reporter](/zh/guides/runner#reporter)；人在终端里怎么读 dashboard 与结束摘要见上面的[常用 flags](#常用-flags)与本页各命令示例；AI 反馈闭环的完整用法（读输出、按 locator 下钻、局部重跑）见 [AI 反馈闭环](/zh/guides/agent-feedback-loop)；CI 集成（GitHub Actions、退出码、JSON/JUnit）见 [CI 集成](/zh/guides/ci-integration)。
+三种 profile 的完整对比见[运行器 · Reporter](/zh/explanation/runner#reporter)；人在终端里怎么读 dashboard 与结束摘要见上面的[常用 flags](#常用-flags)与本页各命令示例；AI 反馈闭环的完整用法（读输出、按 locator 下钻、局部重跑）见 [AI 反馈闭环](/zh/how-to/agent-feedback-loop)；CI 集成（GitHub Actions、退出码、JSON/JUnit）见 [CI 集成](/zh/how-to/ci-integration)。
 
 ## `view`
 
@@ -150,7 +152,7 @@ npx niceeval exp compare --output ci --strict --json .niceeval/ci-summary.json -
 npx niceeval view
 ```
 
-打开本地结果查看器。它和 `show` 共用同一份默认报告和同一套默认选择——对每个 experiment、每个 eval，取历次运行里最新的那份判定；只补跑部分 eval 时，其余 eval 从更早的运行补齐。默认报告按 experiment id 的父目录分组，只在同组内比较。`show` 输出终端文本，`view` 输出网页并提供可交互的证据浏览；eval ID 前缀、`--experiment`、`--run` 对两者的收窄一致。完整说明见[查看结果](/zh/guides/viewing-results)。
+打开本地结果查看器。它和 `show` 共用同一份默认报告和同一套默认选择——对每个 experiment、每个 eval，取历次运行里最新的那份判定；只补跑部分 eval 时，其余 eval 从更早的运行补齐。默认报告按 experiment id 的父目录分组，只在同组内比较。`show` 输出终端文本，`view` 输出网页并提供可交互的证据浏览；eval ID 前缀、`--experiment`、`--run` 对两者的收窄一致。完整说明见[查看结果](/zh/how-to/viewing-results)。
 
 ## `show [id-prefix...]`
 
@@ -166,7 +168,7 @@ npx niceeval show weather/brooklyn --history
 
 `show` 是终端结果入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。位置参数选「看哪些 eval」（ID 前缀）或直接用 `@<locator>` 精确选一个 attempt；不带位置参数时显示按实验组分区的默认比较报告，指定 eval ID 前缀只收窄报告覆盖的 Eval，不改变组边界。
 
-`@<locator>` 不带证据 flag 时给出该 attempt 的紧凑全景（断言摘要、执行摘要、可选 OTel 时间、diff 摘要）；`--eval`、`--execution`、`--diff` 是同一 attempt 的证据切面，分别展开运行时保存的 Eval 源码、标准执行事件流、工作区文件改动，因此必须搭配 `@<locator>` 精确指名一个 attempt。`--run` 钉住某次结果目录，`--history` 查看跨 run 趋势。完整的阅读顺序、输出示例和 artifact 说明见[查看结果](/zh/guides/viewing-results)。
+`@<locator>` 不带证据 flag 时给出该 attempt 的紧凑全景（断言摘要、执行摘要、可选 OTel 时间、diff 摘要）；`--eval`、`--execution`、`--diff` 是同一 attempt 的证据切面，分别展开运行时保存的 Eval 源码、标准执行事件流、工作区文件改动，因此必须搭配 `@<locator>` 精确指名一个 attempt。`--run` 钉住某次结果目录，`--history` 查看跨 run 趋势。完整的阅读顺序、输出示例和 artifact 说明见[查看结果](/zh/how-to/viewing-results)。
 
 ## `--early-exit` 与 `--strict`
 

package/docs-site/zh/reference/define-agent.mdx

@@ -323,7 +323,7 @@ log(msg: string): void;
 - `hold<T>(state: T): void` / `take<T>(): T | undefined` —— HITL 停轮现场的存取,`take` 取到即清除(一次消费)。
 - `state: Record<string, unknown>` —— 逃生舱,起始 `{}`,框架从不写入。
 
-完整契约见[Adapter 概念](/zh/concepts/adapter#上下文：agentcontext)。
+完整契约见[Adapter 概念](/zh/explanation/adapter#上下文：agentcontext)。
 
 ## Sandbox 接口
 

package/docs-site/zh/reference/events.mdx

@@ -212,7 +212,7 @@ token 用量或 OTel span 反推得到)。存在时优先于按价格表(`define
 } }
 ```
 
-agent 停轮等人时，每个待回答的问题吐一条，同时该 Turn 的 `status` 返回 `"waiting"`。`t.requireInputRequest(filter)` 的 filter 逐字段匹配这个 `request`——**能填的字段尽量填**，否则 eval 侧筛选不到。接法见[接入教程的 HITL 部分](/zh/guides/connect-your-agent)。
+agent 停轮等人时，每个待回答的问题吐一条，同时该 Turn 的 `status` 返回 `"waiting"`。`t.requireInputRequest(filter)` 的 filter 逐字段匹配这个 `request`——**能填的字段尽量填**，否则 eval 侧筛选不到。接法见[接入教程的 HITL 部分](/zh/how-to/connect-your-agent)。
 
 ### `thinking` / `compaction` / `error`
 
@@ -257,6 +257,6 @@ function toStreamEvents(body: MyBotResponse): StreamEvent[] {
 
 ## 相关阅读
 
-- [接入你的 agent](/zh/guides/connect-your-agent) —— 从零跑通的教程。
+- [接入你的 agent](/zh/how-to/connect-your-agent) —— 从零跑通的教程。
 - [能力位](/zh/reference/capabilities) —— 声明"事件流是完整的"意味着什么。
-- [编写 eval](/zh/guides/authoring) —— 消费这条流的断言全集。
+- [编写 eval](/zh/how-to/authoring) —— 消费这条流的断言全集。

package/docs-site/zh/{guides → reference}/official-adapters.mdx

@@ -4,11 +4,11 @@ sidebarTitle: "官方适配器"
 description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么、怎么鉴权，Sandbox 型里怎么装 MCP server、Skill、插件，怎么使用 Agent 官方配置文件。"
 ---
 
-[NiceEval](https://niceeval.com/) 随包带几个官方 Adapter（`niceeval/adapter` 导出的工厂函数），按被测对象要不要隔离工作区分两类：**Sandbox 型**（`claude-code` / `codex` / `bub`）在 Docker 或云端沙箱里跑 coding-agent CLI，能装 MCP server、Skill、Python 插件；**非 Sandbox 型**无侵入连一个已经在跑的 HTTP 服务，或者帮你手写 adapter 时省掉事件流映射。这篇按类型和具体 Adapter 分节，重点是每个 Adapter 的配置项——怎么选、怎么跑通第一条 eval，见[接入你的 Agent](/zh/guides/connect-your-agent)。
+[NiceEval](https://niceeval.com/) 随包带几个官方 Adapter（`niceeval/adapter` 导出的工厂函数），按被测对象要不要隔离工作区分两类：**Sandbox 型**（`claude-code` / `codex` / `bub`）在 Docker 或云端沙箱里跑 coding-agent CLI，能装 MCP server、Skill、Python 插件；**非 Sandbox 型**无侵入连一个已经在跑的 HTTP 服务，或者帮你手写 adapter 时省掉事件流映射。这篇按类型和具体 Adapter 分节，重点是每个 Adapter 的配置项——怎么选、怎么跑通第一条 eval，见[接入你的 Agent](/zh/how-to/connect-your-agent)。
 
 ## Sandbox 适配器
 
-三个内置 Sandbox agent 都用 `defineSandboxAgent` 构造，鉴权走环境变量（可用工厂参数覆盖），并且都支持在沙箱 `setup` 阶段装扩展。怎么运行内置 Sandbox agent、目录结构和自定义 Sandbox adapter，见 [Sandbox Agent](/zh/guides/sandbox-agent)；这里只讲每个 Adapter 能装什么、配置项怎么写。
+三个内置 Sandbox agent 都用 `defineSandboxAgent` 构造，鉴权走环境变量（可用工厂参数覆盖），并且都支持在沙箱 `setup` 阶段装扩展。怎么运行内置 Sandbox agent、目录结构和自定义 Sandbox adapter，见 [Sandbox Agent](/zh/how-to/sandbox-agent)；这里只讲每个 Adapter 能装什么、配置项怎么写。
 
 本页的 `settingsFile` / `configFile` 都相对 NiceEval 项目根解析。项目根是执行 `niceeval` 时的当前工作目录，也就是包含 `niceeval.config.ts` 的目录，不是 Eval 或 Experiment 文件所在目录。例如 Experiment 在 `experiments/web/no-search.ts`、配置在 `configs/codex/no-web.toml` 时，仍写 `configFile: "configs/codex/no-web.toml"`。
 
@@ -19,7 +19,7 @@ description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么
 - **装 Skill**：`skills: SkillSpec[]`——本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进沙箱的 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。
 - **官方配置文件**：`settingsFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径；它指向一份完整的 Claude Code `settings.json`。路径相对项目根，只允许普通相对路径或 `./` 前缀；`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。Adapter 从本地读取后上传文件，原样替换 Sandbox 中原本为空的用户级 `~/.claude/settings.json`；不继承宿主机配置，也不 deep merge 或重新序列化。`model` 和 `env` 归 Experiment 和 Adapter 管，出现在文件里会在 `setup` 阶段报错并点名冲突键。Secret 走环境变量，别写进配置文件。
-- **tracing**：claude CLI 的 beta 原生遥测（`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`），span 只有结构和计时，细节见 [OTel 接入](/zh/guides/connect-otel)。
+- **tracing**：claude CLI 的 beta 原生遥测（`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA`），span 只有结构和计时，细节见 [OTel 接入](/zh/how-to/connect-otel)。
 
 例如，用 `configs/claude-code/no-web.json` 关闭内置联网检索：
 
@@ -107,7 +107,7 @@ 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` 不足以证明兼容。构建入口见 [沙箱 provider · 从官方基线继续构建以提速](/zh/guides/sandbox-providers#从官方基线继续构建以提速)。
+- **预制 Bub**：NiceEval 的 E2B 配方会把 Bub、OTel 插件和 Python 插件集合算成安装指纹。Adapter 只复用指纹完全一致的环境；仅在 PATH 里放一个 `bub` 不足以证明兼容。构建入口见 [沙箱 provider · 从官方基线继续构建以提速](/zh/how-to/sandbox-providers#从官方基线继续构建以提速)。
 - bub 没有 `mcpServers`——MCP 只属于支持它的 Adapter，Config 上压根没有这个字段。
 - **安装方式**：走 `uv tool install`（PyPI 包，不是 npm 包），首次安装会建 checkpoint 缓存加速后续沙箱。
 - **tracing**：内置，通过环境变量注入，协议 `http/protobuf`。
@@ -171,8 +171,8 @@ export default defineExperiment({
 
 ## 相关阅读
 
-- [接入你的 Agent](/zh/guides/connect-your-agent) — 全景：experiment 怎么配、eval 怎么写。
-- [Sandbox Agent](/zh/guides/sandbox-agent) — 怎么运行内置 Sandbox agent，以及怎么写自己的。
+- [接入你的 Agent](/zh/how-to/connect-your-agent) — 全景：experiment 怎么配、eval 怎么写。
+- [Sandbox Agent](/zh/how-to/sandbox-agent) — 怎么运行内置 Sandbox agent，以及怎么写自己的。
 - [内置 Agent 能力参考](/zh/reference/builtin-agents) — 每个适配器逐能力盘点、非 Sandbox 适配器的完整代码示例。
-- [OTel 接入](/zh/guides/connect-otel) — 把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
+- [OTel 接入](/zh/how-to/connect-otel) — 把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
 - [defineAgent 参考](/zh/reference/define-agent) — `defineAgent` / `defineSandboxAgent` 完整参数。

package/docs-site/zh/{guides → reference}/report-components.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "报告组件"
 description: "报告文件里能摆的全部官方双面组件：每个组件回答什么问题、怎么调用、网页面长什么样、终端字符输出长什么样。"
 ---
 
-报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/guides/custom-reports)）。每个组件的数据算法挂在它自己身上，组件名后打个点就找到，算和画永远配对。本页逐个列出官方组件：它展示哪一层数据、在报告里怎么调用、终端输出长什么样。
+报告文件里的每个组件都是双面的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据，走哪扇门由宿主决定（见[自定义报告](/zh/how-to/custom-reports)）。每个组件的数据算法挂在它自己身上，组件名后打个点就找到，算和画永远配对。本页逐个列出官方组件：它展示哪一层数据、在报告里怎么调用、终端输出长什么样。
 
 ## 名称与用途
 
@@ -94,7 +94,7 @@ description: "报告文件里能摆的全部官方双面组件：每个组件回
 
 表比终端宽时先压最宽的左对齐列（按显示宽度折行），右对齐列不折行——数字折行读不了；压到下限仍放不下，就从右侧丢列，并在表下如实报丢了几列，不静默截断。
 
-指标表、指标矩阵、成绩单和成对差异表的终端面就建在 `Table` 上，所以你的表和官方的表用的是同一把尺子。表格之外的形态要自己排字符时，用[自定义报告](/zh/guides/custom-reports)「换形态」一节里那套文本排版函数。
+指标表、指标矩阵、成绩单和成对差异表的终端面就建在 `Table` 上，所以你的表和官方的表用的是同一把尺子。表格之外的形态要自己排字符时，用[自定义报告](/zh/how-to/custom-reports)「换形态」一节里那套文本排版函数。
 
 ## 实验组比较（`ExperimentComparison`）
 
@@ -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/guides/results-data)。要展示哪些 Attempt，过滤返回的 `AttemptListItem[]`。`limit` 也由报告作者在数组上用 `.slice(0, 20)` 表达，截断时把原始数量交给组件的 `total`，组件据此显示“还有 n 项未展示”，不静默截断。
+要在页面显示前遮蔽 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 项未展示”，不静默截断。
 
 ## 指标表（`MetricTable`）
 
@@ -347,7 +347,7 @@ pass ↑                                    （好 → 右上）
 A bub-high   B bub-medium   C codex-high   D codex-low
 ```
 
-网页面点带悬停提示（值与 `samples/total`，禁用 JS 时退化为图内提示）、同系列连线、点击深链下钻。终端面用字母标点、图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。画得出来的点是 0 个（x 或 y 全缺数据）时，两个面都明说这两个指标没有可用数据，不留一片空白；1 个点也照常出图——组件从不因为点不够就整块消失，让你不知道图为什么没了。维度槽也收自定义维度（`{ name, of }`，从 attempt 已有数据算组名）和 `flag()`（experiment 声明的变量），怎么选见[自定义报告](/zh/guides/custom-reports)的「换分组」一节。
+网页面点带悬停提示（值与 `samples/total`，禁用 JS 时退化为图内提示）、同系列连线、点击深链下钻。终端面用字母标点、图例列在图下；x 或 y 缺数据的点两个面都不画，注脚如实报「n 个点缺数据」；点太密排不下时降级为坐标表，不硬挤。画得出来的点是 0 个（x 或 y 全缺数据）时，两个面都明说这两个指标没有可用数据，不留一片空白；1 个点也照常出图——组件从不因为点不够就整块消失，让你不知道图为什么没了。维度槽也收自定义维度（`{ name, of }`，从 attempt 已有数据算组名）和 `flag()`（experiment 声明的变量），怎么选见[自定义报告](/zh/how-to/custom-reports)的「换分组」一节。
 
 ## 指标趋势图（`MetricLine`）
 
@@ -400,4 +400,4 @@ codex   80% → 80%   ±0         $0.51 → —       —
 
 ## 官方组件之外
 
-以上摆法都表达不了时，用 `defineComponent` 写自己的双面组件——网页怎么渲染、终端字符怎么排，两个面你都说了算，写法见[自定义报告](/zh/guides/custom-reports)的「换形态」一节。
+以上摆法都表达不了时，用 `defineComponent` 写自己的双面组件——网页怎么渲染、终端字符怎么排，两个面你都说了算，写法见[自定义报告](/zh/how-to/custom-reports)的「换形态」一节。

package/docs-site/zh/{guides → reference}/results-data.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "结果数据 API"
 description: "报告积木脚下的数据层：openResults 把 .niceeval/ 的落盘 artifact parse 成「实验 → 结果快照 → eval → attempt」的类型化层次，createResultsWriter 把别家结果写成 NiceEval 格式，copySnapshots 负责发布瘦身。"
 ---
 
-[自定义报告](/zh/guides/custom-reports)的积木——指标、计算函数、双面组件——脚下还有一层：`niceeval/results`，落盘 artifact 的 parser。官方两扇门和全部报告积木读的都是这一层，没有私有数据通道；报告表达不了的口径，下到这层直接拿数据算。
+[自定义报告](/zh/how-to/custom-reports)的积木——指标、计算函数、双面组件——脚下还有一层：`niceeval/results`，落盘 artifact 的 parser。官方两扇门和全部报告积木读的都是这一层，没有私有数据通道；报告表达不了的口径，下到这层直接拿数据算。
 
 什么时候下到这层：
 
@@ -160,7 +160,7 @@ latest.warnings[0];
 
 字段供程序判断——CI 里「覆盖缩水就 fail」直接判 `covered < total`，不解析文本；`message` 是渲染好的英文句子，要展示就原样打。渲染与否在你，缺口永远被算出来。警告不止这一种：快照落后于 Selection 中最新的落盘进 `stale-snapshot`、选中的快照没收尾（进程中断）进 `unfinished-snapshot`，每种都带 `kind`、可判断的结构化字段和渲染好的 `message`。
 
-Selection 是[报告积木](/zh/guides/custom-reports)和下文 `copySnapshots` 的通用输入：收 `Selection` 时 warnings 随行（`RunOverview` 之类的组件会如实展示），手工挑的 `Snapshot[]` 数组照收。微调官方口径不用降级成裸数组：`latest.filter((s) => s.experimentId !== "compare/broken")` 返回新 Selection——快照被删减，warnings 修剪到幸存的实验，provenance 不丢。`filter` 只做删减；「换成该实验上一个完整快照」这类**替换式**重挑不是它的事，回到 `exp.snapshots` 自己拿——手工挑的数组没有挑选过程，自然没有 warnings 可带，也如实。
+Selection 是[报告积木](/zh/how-to/custom-reports)和下文 `copySnapshots` 的通用输入：收 `Selection` 时 warnings 随行（`RunOverview` 之类的组件会如实展示），手工挑的 `Snapshot[]` 数组照收。微调官方口径不用降级成裸数组：`latest.filter((s) => s.experimentId !== "compare/broken")` 返回新 Selection——快照被删减，warnings 修剪到幸存的实验，provenance 不丢。`filter` 只做删减；「换成该实验上一个完整快照」这类**替换式**重挑不是它的事，回到 `exp.snapshots` 自己拿——手工挑的数组没有挑选过程，自然没有 warnings 可带，也如实。
 
 ## 一个真实脚本：分布不是折叠
 
@@ -184,7 +184,7 @@ for (const exp of results.experiments) {
 }
 ```
 
-即使在这条最深的路径上也不碰磁盘布局：路径拼接、存在性、版本过滤、快照切分全被库消化。要把这份分布摆进报告页，用 [`defineComponent`](/zh/guides/custom-reports) 包一个双面组件即可。
+即使在这条最深的路径上也不碰磁盘布局：路径拼接、存在性、版本过滤、快照切分全被库消化。要把这份分布摆进报告页，用 [`defineComponent`](/zh/how-to/custom-reports) 包一个双面组件即可。
 
 一条跨快照累计时的义务：NiceEval 默认把上一轮已有确定判定（passed / failed）、且 eval 代码和配置没变的结果携带合入新快照（`--force` 全部重跑），同一个 attempt 因此可能存在于多份落盘。携带条目不是空壳：它带着原快照的 `startedAt`(身份锚)与 `artifactBase`(指向原快照 attempt 目录的相对路径)，懒加载按候选顺序回退——先本快照的 attempt 目录，再 `artifactBase` 指向的原快照目录(原快照被清理后如实返回 `null`)；`ref` 指向条目所在的落盘，即携带入的那份新快照。身份键 `(experimentId, evalId, attempt, startedAt)` 的四个字段都在数据上——前两个是 attempt 的直达字段，序号与 `startedAt` 在 `attempt.result` 上。reader 忠实反映这份重复；跨快照聚合前用 `dedupeAttempts` 按身份键去重，重复保留最新快照里的那份——报告积木的计算函数内置这条，自己写脚本时记得过一遍：
 
@@ -246,14 +246,14 @@ 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/guides/publish-report)。
+大小预检只决定整次复制成功或失败，不会从一个超大文件中间删内容。消毒不是可选项——`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)。
 
 ## 分层速览
 
 | 层 | 入口 | 回答 |
 | --- | --- | --- |
 | 官方两扇门 | `niceeval show` / `niceeval view` | 零代码看官方摆法 |
-| 报告积木 | [自定义报告](/zh/guides/custom-reports)、[报告组件](/zh/guides/report-components) | 自己的口径与摆法 |
+| 报告积木 | [自定义报告](/zh/how-to/custom-reports)、[报告组件](/zh/reference/report-components) | 自己的口径与摆法 |
 | 结果数据 API（本页） | `niceeval/results` | 折叠表达不了的算法、接自己的系统、读写格式本身 |
 
 每层都建立在下一层之上，同一份落盘 artifact 是唯一事实来源——上层的派生物删了随时可重算。

package/docs-site/zh/{guides → troubleshooting}/debug-sandbox.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "保留沙箱现场"
 description: "用 --keep-sandbox 把失败 Attempt 的沙箱保留成可随时唤醒的现场，用 niceeval sandbox enter 进去手动排查，用 sandbox list / stop 查看和清理。"
 ---
 
-沙箱默认在每个 Attempt 结束后销毁，排查依据是落盘的 artifact：`niceeval show` 能看到判定、断言、diff 和事件流。大多数问题到这里就够了——完整的排查路线见 [Debug 手册](/zh/guides/debugging)。
+沙箱默认在每个 Attempt 结束后销毁，排查依据是落盘的 artifact：`niceeval show` 能看到判定、断言、diff 和事件流。大多数问题到这里就够了——完整的排查路线见 [Debug 手册](/zh/troubleshooting/debugging)。
 
 但有些问题只能进活的环境里看：
 
@@ -54,4 +54,4 @@ niceeval sandbox stop --all        # 全部销毁
 
 ## 边界
 
-保留的沙箱只用来排查，不能续跑或重新评分；判定、断言、diff 这些结论仍以 artifact 为准。查看 artifact 的方法见[查看结果](/zh/guides/viewing-results)。
+保留的沙箱只用来排查，不能续跑或重新评分；判定、断言、diff 这些结论仍以 artifact 为准。查看 artifact 的方法见[查看结果](/zh/how-to/viewing-results)。

package/docs-site/zh/{guides → troubleshooting}/debugging.mdx

@@ -6,6 +6,8 @@ description: "一份按场景组织的排查手册：断言失败怎么定位、
 
 跑完一次 `niceeval exp`，失败的 Attempt 都带一个 `@` 开头的定位符（如 `@1qrdcfq8`）。它出现在运行摘要、CI 日志和报告里，定位符本身不会过期——只要 `.niceeval/` 里对应的结果快照还在，今天的定位符下周还能用同一条命令打开同一次 Attempt。所有排查都从它开始。
 
+先说一条通用规则：NiceEval 自己的报错和警告都在消息末尾直接给出下一步。能用一条命令解决的，消息里就是替换好实验名的完整命令，复制执行即可（网页里还可以一键复制）；可以不管的警告会写明「什么情况下可以忽略」。所以看到报错先读完最后一句；本手册处理的是消息之外还需要人工判断的场景——判定失败了怎么定位、环境错误怎么进现场。
+
 ## 第一步永远是 `niceeval show @<定位符>`
 
 不带任何参数打开 Attempt，第一页就是为排查设计的：判定、失败的断言、耗时分布、改动概览，以及下一步可用的命令。
@@ -140,7 +142,7 @@ Kept sandboxes (1)
 Stop them with: niceeval sandbox stop --all
 ```
 
-`niceeval sandbox enter a3f9c2d1` 会唤醒现场并在 workdir 打开 shell——手动执行安装命令看真实报错、翻 `$HOME` 下的配置、检查 `PATH`，这些都在 artifact 之外，只有活现场能回答；退出 shell 后现场自动回到休眠，不白烧资源。保留策略、各 provider 的差别见[保留沙箱现场](/zh/guides/debug-sandbox)。
+`niceeval sandbox enter a3f9c2d1` 会唤醒现场并在 workdir 打开 shell——手动执行安装命令看真实报错、翻 `$HOME` 下的配置、检查 `PATH`，这些都在 artifact 之外，只有活现场能回答；退出 shell 后现场自动回到休眠，不白烧资源。保留策略、各 provider 的差别见[保留沙箱现场](/zh/troubleshooting/debug-sandbox)。
 
 ## 查看和清理留下的沙箱
 
@@ -192,7 +194,7 @@ niceeval show --run tmp/ci-artifacts/results
 niceeval view --run site-data/run
 ```
 
-一个注意点：如果本地清理过旧快照目录，之后的运行里「沿用上次结果」的条目会找不到原始证据（显示为缺失）。要长期归档某次运行，先用 [`copySnapshots`](/zh/guides/results-data) 复制出一份再删。
+一个注意点：如果本地清理过旧快照目录，之后的运行里「沿用上次结果」的条目会找不到原始证据（显示为缺失）。要长期归档某次运行，先用 [`copySnapshots`](/zh/reference/results-data) 复制出一份再删。
 
 ## 速查：症状 → 命令
 

package/docs-site/zh/{quickstart.mdx → tutorials/quickstart.mdx}

@@ -36,7 +36,7 @@ pnpm exec niceeval init
 ```
 
 ### Adapter
-Adapter 是连接 Agent 与 [NiceEval](https://niceeval.com/) 的中间层。有三种不同程序的接入方式，从无侵入式到部分修改你的 Agent 代码，来解锁更有用的评估功能。 见[Tier](/zh/concepts/tier)。
+Adapter 是连接 Agent 与 [NiceEval](https://niceeval.com/) 的中间层。有三种不同程序的接入方式，从无侵入式到部分修改你的 Agent 代码，来解锁更有用的评估功能。 见[Tier](/zh/explanation/tier)。
 
 ```ts
 // agents/my-bot.ts
@@ -101,23 +101,11 @@ pnpm exec niceeval view         # 需要交互浏览时打开本地查看器
 
 到这里第一条 eval 已经跑通。
 
-这个最小 adapter 是**单轮**的——第二轮不会记得第一轮说了什么，因为还没告诉应用怎么接上历史。多轮会话和工具调用事件（解锁 `t.calledTool()`）、HITL、tracing 一样，都是之后给 adapter 加的可选增量：顺着[接入你的 Agent](/zh/guides/connect-your-agent)逐层往下走即可，已写的 eval 不用改。
+这个最小 adapter 是**单轮**的——第二轮不会记得第一轮说了什么，因为还没告诉应用怎么接上历史。多轮会话和工具调用事件（解锁 `t.calledTool()`）、HITL、tracing 一样，都是之后给 adapter 加的可选增量：顺着[接入你的 Agent](/zh/how-to/connect-your-agent)逐层往下走即可，已写的 eval 不用改。
 
-## 按场景走
+## 对照完整项目
 
-已经知道自己要评什么的话，直接从对应场景开始：
-
-<CardGroup cols={3}>
-  <Card title="如果你需要 eval 你的 Claude Code / Codex 插件" icon="plug" href="/zh/example/claude-code-codex-plugin">
-    适合插件、Hook、MCP server 和项目级 coding-agent 扩展。
-  </Card>
-  <Card title="如果你需要 eval 你的 Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
-    适合验证 Skill 是否被触发、是否按流程执行、是否真的提升任务成功率。
-  </Card>
-  <Card title="如果你需要 eval 你的 AI Agent 应用" icon="globe" href="/zh/example/ai-agent-application">
-    适合 AI SDK、LangGraph、Pi 或自研 agent 应用的完整示例。
-  </Card>
-</CardGroup>
+第一条 Eval 跑通后，再到 [Examples](/zh/examples) 按被测对象选择完整项目。那里提供可运行源码；通用操作步骤仍以 How-to Guides 为准。
 
 ## 放进 CI
 
@@ -135,5 +123,5 @@ jobs:
 ```
 
 <Tip>
-  接下来读 [编写 eval](/zh/guides/authoring) 和 [评分指南](/zh/guides/scoring-guide)，把示例替换成你的真实场景。
+  接下来读 [编写 eval](/zh/how-to/authoring) 和 [评分指南](/zh/how-to/scoring-guide)，把示例替换成你的真实场景。
 </Tip>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -60,6 +60,10 @@
       "types": "./dist/report/react/index.d.ts",
       "import": "./dist/report/react/index.js"
     },
+    "./report/built-in": {
+      "types": "./dist/report/built-in/index.d.ts",
+      "import": "./dist/report/built-in/index.js"
+    },
     "./report/react/styles.css": "./src/report/react/styles.css",
     "./report/react/enhance.js": "./src/report/react/enhance.js"
   },
@@ -169,7 +173,7 @@
     "build:report": "tsc -p tsconfig.report-build.json && node scripts/prune-report-dist.mjs",
     "site:dev": "cd site && node scripts/dev.mjs",
     "site:build": "cd site && next build",
-    "docs:dev": "cd docs-site && npx --yes mint@latest dev",
+    "docs:dev": "node scripts/docs-dev.mjs",
     "docs:validate": "cd docs-site && npx --yes mint@latest validate",
     "docs:links": "cd docs-site && npx --yes mint@latest broken-links --check-anchors --check-redirects"
   }

package/src/agents/index.ts

@@ -12,7 +12,7 @@ export type { CoverageStatus, CoverageDeclaration, EvidenceCoverage } from "../t
 // span → canonical GenAI 归一(只服务瀑布图,不喂断言)。私有埋点写自己的 spanMapper 时用:
 // tagSpan 把判定写回 span(原属性只增不改),heuristicTag 是通用兜底判定;mapCodexSpans 是
 // 现成的参考实现(无侵入接 codex 后端时直接声明 `spanMapper: mapCodexSpans`)。
-// 映射目标(什么属性亮起瀑布图的什么)见 docs-site/zh/guides/connect-otel.mdx「瀑布图画得准不准」。
+// 映射目标(什么属性亮起瀑布图的什么)见 docs-site/zh/how-to/connect-otel.mdx「瀑布图画得准不准」。
 export { tagSpan, heuristicTag } from "../o11y/otlp/canonical.ts";
 export type { SpanTag } from "../o11y/otlp/canonical.ts";
 export { mapCodexSpans } from "../o11y/otlp/mappers/codex.ts";
@@ -52,7 +52,7 @@ export type {
 export { fromLangGraphEvents } from "./langgraph.ts";
 export type { LangGraphEventLike, LangGraphContentBlockLike, LangGraphStream } from "./langgraph.ts";
 
-// 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 docs-site/zh/guides/write-send.mdx——
+// 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 docs-site/zh/how-to/write-send.mdx——
 // 这些和任何具体协议无关,自己写 adapter 时优先拿这些拼,只有 transport(怎么发)与
 // 「帧类型 → 操作」这张映射表才是真正要手写的。会话续接与 HITL 停轮现场不再是可选件,
 // 而是 ctx.session(AgentSession)本身自带的存取器(history()/id+capture()、hold()/take())。

package/src/agents/openai-compat.ts

@@ -2,7 +2,7 @@
 // 表格里的 fromChatCompletion(res) / fromResponses(res)。和 fromAiSdk 同一先例:结构化
 // *Like 类型,不依赖 openai 包,兼容任何声明自己走这两种协议形状的服务(不止 OpenAI 官方)。
 //
-// 两种形状对负断言的可信度不同(见 docs-site/zh/guides/write-send.mdx):
+// 两种形状对负断言的可信度不同(见 docs-site/zh/how-to/write-send.mdx):
 //   · Chat Completions 不承诺「响应 = 完整过程」(应用可能在服务端跑完工具循环,只把最终
 //     答案给你),所以 notCalledTool 这类负断言只能当「没看到」,不能当「确实没发生」。
 //   · Responses 的协议契约里 output 数组记录了模型这一轮决定做的全部事(包括每个

package/src/agents/streaming.ts

@@ -1,7 +1,7 @@
 // 官方的「拼装方式」件:把一个手写 send 里反复出现的事收成可复用的小东西,
 // 而不是每接一个新后端就重写一遍循环 + Map + if/else。
 //
-// 背景(见 docs-site/zh/guides/write-send.mdx):一轮交互里真正互不相干的事只有几类——
+// 背景(见 docs-site/zh/how-to/write-send.mdx):一轮交互里真正互不相干的事只有几类——
 //   1. 怎么把输入发出去(transport)——真做不掉,adapter 只写这个;
 //   2. 原始数据怎么变成 StreamEvent[]——按数据到达形状分「整段落地」(sdk-streams.ts 的
 //      fromXxxEvents,已有)和「逐 token / 逐参数增量」(deltaStream,这里新增)两种官方 reducer;
@@ -79,7 +79,7 @@ export async function driveFrameStream<Frame, RFrame = Frame>(
 
 // 会话续接(id/capture、history)与 HITL 停轮现场(hold/take)不再是这里的可选「拼装件」——
 // 它们是 ctx.session(AgentSession)本身的存取器,任何 adapter 直接取用,不需要额外声明什么。
-// 见 docs-site/zh/concepts/adapter.mdx 与 src/context/session.ts 的 createAgentSession。
+// 见 docs-site/zh/explanation/adapter.mdx 与 src/context/session.ts 的 createAgentSession。
 
 // ───────────────────────── deltaStream:逐 token / 逐参数增量累加器 ─────────────────────────
 

package/src/agents/types.ts

@@ -1,5 +1,5 @@
 // agent 域类型:Agent / Adapter 契约、会话与 tracing 导出配置。
-// 「连到哪个被测对象、协议怎么说」的全部契约在这里(见 docs-site/zh/concepts/adapter.mdx)。
+// 「连到哪个被测对象、协议怎么说」的全部契约在这里(见 docs-site/zh/explanation/adapter.mdx)。
 // 能力不再是问卷式声明:t 上解锁什么完全由构造证据决定(见 docs-site 「能力从哪来」一节)。
 
 import type { Cleanup, DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
@@ -126,7 +126,7 @@ export interface InputFile {
 
 /**
  * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析
- * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/concepts/adapter.mdx
+ * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/explanation/adapter.mdx
  * 「不同回答的入参」一节的四种典型形态。
  */
 export interface InputResponse {
@@ -223,7 +223,7 @@ export interface AgentTracing {
  * 新会话线(eval 第一轮 / t.newSession() 之后)拿到一个全新的。**
  * 会话续接(`id`/`capture`、`history`)和 HITL 停轮现场(`hold`/`take`)的存取器都在它上面,
  * "第一轮"是新会话线的自然形态,没有要判断的分支;`state` 是这些存取器之外的逃生舱,
- * 框架从不往里写数据。见 docs-site/zh/concepts/adapter.mdx「AgentContext」一节。
+ * 框架从不往里写数据。见 docs-site/zh/explanation/adapter.mdx「AgentContext」一节。
  */
 export interface AgentSession {
   /** 会话续接:服务端记历史。本线记过的会话 id;新会话线是 undefined。 */