niceeval 0.6.2 → 0.7.0

package/docs-site/zh/{guides → how-to}/connect-your-agent.mdx

@@ -14,11 +14,11 @@ description: "接入的全景：写一个 adapter、配一个 experiment、跑
   <Card title="AI SDK 应用" icon="bolt" href="/zh/reference/builtin-agents">
     用 Vercel AI SDK（`useChat` 后端）写的应用：内置 `uiMessageStreamAgent` 无侵入接它的 HTTP 接口，零映射、含 HITL，有完整的 before/after 示例。不用读本文。
   </Card>
-  <Card title="Coding agent CLI" icon="terminal" href="/zh/guides/sandbox-agent">
+  <Card title="Coding agent CLI" icon="terminal" href="/zh/how-to/sandbox-agent">
     评 claude-code / codex / bub 这类改文件的 coding agent：用内置 sandbox agent。
   </Card>
   <Card title="其它 AI Agent" icon="plug">
-    自研 agent loop、LangGraph / OpenAI Agents SDK 应用、已部署 agent：手写 send（本文 + [写 send](/zh/guides/write-send)）。应用已埋 OTel 的话顺手接上，`niceeval view` 多一张调用瀑布图（[OTel 接入](/zh/guides/connect-otel)）。
+    自研 agent loop、LangGraph / OpenAI Agents SDK 应用、已部署 agent：手写 send（本文 + [写 send](/zh/how-to/write-send)）。应用已埋 OTel 的话顺手接上，`niceeval view` 多一张调用瀑布图（[OTel 接入](/zh/how-to/connect-otel)）。
   </Card>
 </CardGroup>
 
@@ -51,7 +51,7 @@ export default defineAgent({
 });
 ```
 
-URL 先写死没关系——怎么把它从 experiment 传进来，见下文[「参数怎么进」](#参数怎么进：experiment-声明，adapter-消费)。`send` 的完整契约（`TurnInput` / `AgentContext` / `Turn` 各字段）见 [Adapter](/zh/concepts/adapter)。
+URL 先写死没关系——怎么把它从 experiment 传进来，见下文[「参数怎么进」](#参数怎么进：experiment-声明，adapter-消费)。`send` 的完整契约（`TurnInput` / `AgentContext` / `Turn` 各字段）见 [Adapter](/zh/explanation/adapter)。
 
 就算 agent runtime 和 eval 在同一个代码库里，也照样走 HTTP，不要把 `fetch` 换成进程内的函数直调：
 
@@ -171,8 +171,8 @@ export default defineExperiment({
 | `signal` | 运行器（超时与取消） | 挂到发出的每个请求上 |
 | `model` | experiment 的 `model` | 应用接口收模型选择就随请求转发；不收就忽略 |
 | `flags` | experiment 的 `flags` | 原样转发（请求体、header 都行），应用按参数切换变体 |
-| `telemetry` | 配置了 OTel 接入时出现 | 只碰 `headers`：每轮新的 W3C `traceparent`，spread 进请求头。接收端点每次运行都一样，在 `defineConfig` 里固定、应用启动时指向它，不从 send 传——见 [OTel 接入](/zh/guides/connect-otel) |
-| `session` | 运行器（每条会话线一份） | 会话续接与 HITL 停轮现场的存取器都在它上面：`history()`、`id` / `capture()`、`hold()` / `take()`，见[写 send](/zh/guides/write-send) |
+| `telemetry` | 配置了 OTel 接入时出现 | 只碰 `headers`：每轮新的 W3C `traceparent`，spread 进请求头。接收端点每次运行都一样，在 `defineConfig` 里固定、应用启动时指向它，不从 send 传——见 [OTel 接入](/zh/how-to/connect-otel) |
+| `session` | 运行器（每条会话线一份） | 会话续接与 HITL 停轮现场的存取器都在它上面：`history()`、`id` / `capture()`、`hold()` / `take()`，见[写 send](/zh/how-to/write-send) |
 | `progress(update)` | 运行器（绑定当前 `agent.run`） | 报告 Turn/tool 的短期状态；Human dashboard 可显示，结果不保存 |
 | `diagnostic(input)` | 运行器（绑定当前 `agent.run`） | 保存协议退化、响应不完整等 warning/error；可由 locator 下钻回顾 |
 
@@ -222,7 +222,7 @@ npx niceeval exp local
 npx niceeval exp prod
 ```
 
-不要把 URL 放进 CLI 位置参数——experiment 名之后的位置参数只用于过滤 eval ID。experiment 的完整字段（`runs`、`budget`、并发、`sandbox`）见[写实验](/zh/guides/write-experiment)。
+不要把 URL 放进 CLI 位置参数——experiment 名之后的位置参数只用于过滤 eval ID。experiment 的完整字段（`runs`、`budget`、并发、`sandbox`）见[写实验](/zh/how-to/write-experiment)。
 
 ## 之后的增量：一张地图
 
@@ -230,13 +230,13 @@ npx niceeval exp prod
 
 | 想解锁什么 | 给 adapter 加什么 | 去哪看 |
 |---|---|---|
-| 工具断言（`calledTool` / `toolOrder` / 负断言） | 把应用返回映射成标准事件流 | [写 send](/zh/guides/write-send)、[事件流参考](/zh/reference/events) |
-| 多轮对话、`t.newSession()` 隔离 | 接上 `ctx.session`：`history()` 或 `id` + `capture()` | [写 send](/zh/guides/write-send) |
-| 审批流（HITL，人工介入） | 停轮返回 `waiting` + `input.requested`，回答轮续跑 | [HITL](/zh/concepts/hitl) |
-| `niceeval view` 的调用瀑布图 | 应用把 OTel span 发给 NiceEval（不影响断言） | [OTel 接入](/zh/guides/connect-otel) |
-| feature A/B 对比 | 应用把变体暴露成 `flags` 可切换的配置 | [Tier](/zh/concepts/tier)、[写实验](/zh/guides/write-experiment) |
+| 工具断言（`calledTool` / `toolOrder` / 负断言） | 把应用返回映射成标准事件流 | [写 send](/zh/how-to/write-send)、[事件流参考](/zh/reference/events) |
+| 多轮对话、`t.newSession()` 隔离 | 接上 `ctx.session`：`history()` 或 `id` + `capture()` | [写 send](/zh/how-to/write-send) |
+| 审批流（HITL，人工介入） | 停轮返回 `waiting` + `input.requested`，回答轮续跑 | [HITL](/zh/explanation/hitl) |
+| `niceeval view` 的调用瀑布图 | 应用把 OTel span 发给 NiceEval（不影响断言） | [OTel 接入](/zh/how-to/connect-otel) |
+| feature A/B 对比 | 应用把变体暴露成 `flags` 可切换的配置 | [Tier](/zh/explanation/tier)、[写实验](/zh/how-to/write-experiment) |
 
-这些增量落在哪一档、各档买到什么，见 [Tier](/zh/concepts/tier)。
+这些增量落在哪一档、各档买到什么，见 [Tier](/zh/explanation/tier)。
 
 ## 参考实现
 
@@ -244,9 +244,9 @@ npx niceeval exp prod
 
 ## 相关阅读
 
-- [官方适配器一览](/zh/guides/official-adapters) —— 被测对象能直接用官方 Adapter 时，Sandbox / 非 Sandbox 各有哪些、配置项怎么写。
-- [写 send](/zh/guides/write-send) —— 手写 Adapter 的完整教程：七步递进，从发一条消息到 HITL、OTel、flags。
-- [Adapter](/zh/concepts/adapter) —— `send` 的契约：`TurnInput` / `AgentContext` / `Turn` 逐字段。
-- [OTel 接入](/zh/guides/connect-otel) —— 把应用的 span 也发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
-- [Tier](/zh/concepts/tier) —— 三档接入各投入什么、买到什么。
-- [写实验](/zh/guides/write-experiment) —— `defineExperiment` 的完整字段。
+- [官方适配器一览](/zh/reference/official-adapters) —— 被测对象能直接用官方 Adapter 时，Sandbox / 非 Sandbox 各有哪些、配置项怎么写。
+- [写 send](/zh/how-to/write-send) —— 手写 Adapter 的完整教程：七步递进，从发一条消息到 HITL、OTel、flags。
+- [Adapter](/zh/explanation/adapter) —— `send` 的契约：`TurnInput` / `AgentContext` / `Turn` 逐字段。
+- [OTel 接入](/zh/how-to/connect-otel) —— 把应用的 span 也发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图。
+- [Tier](/zh/explanation/tier) —— 三档接入各投入什么、买到什么。
+- [写实验](/zh/how-to/write-experiment) —— `defineExperiment` 的完整字段。

package/docs-site/zh/{guides → how-to}/custom-reports.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "自定义报告"
 description: "一份报告就是一个报告文件：官方宿主打开结果、注入数据，双面组件让同一份自定义报告同时用于 niceeval show 与 niceeval view。"
 ---
 
-[查看结果](/zh/guides/viewing-results)讲「用」：官方两扇门 `niceeval show`（终端）和 `niceeval view`（网页）怎么看。本页讲「写」：官方摆法不够时，怎么写一份自己的报告——考试成绩单、代码行数榜、质量 × 成本 frontier。
+[查看结果](/zh/how-to/viewing-results)讲「用」：官方两扇门 `niceeval show`（终端）和 `niceeval view`（网页）怎么看。本页讲「写」：官方摆法不够时，怎么写一份自己的报告——考试成绩单、代码行数榜、质量 × 成本 frontier。
 
 一份报告就是一个报告文件。你不用打开结果目录、不用写渲染代码、不用起自己的应用：`niceeval show` / `niceeval view` 本体就是宿主——替你打开结果、把数据注入进来，你用官方组件和 `Row` / `Col` 摆版面，写完把文件路径递给 `--report`，终端和网页两扇门就都认它——官方的证据室深链、`--run` 历史切换、静态导出，自定义报告全部原样享有。
 
@@ -59,7 +59,7 @@ niceeval show --report reports/exam.tsx    # 终端：同一棵树走文本面
 niceeval view --report reports/exam.tsx    # 网页：同一棵树走网页面，attempt 深链直达证据室
 ```
 
-注入的上下文只有两样，全部是[结果数据 API](/zh/guides/results-data) 的原语，宿主没有私有通道：`results` 就是 `openResults(".niceeval")` 的返回（实验、历次快照、attempt 级 `diff()`、`trace()` 都在上面）；`selection` 是宿主替你挑好的那份结果。挑选规则是：对每个实验、每道 eval，取该实验历史运行里最新的那次判定——只按前缀重跑了一部分 eval，其余 eval 的判定从更早的运行补齐，不会因为一次局部重跑就整体退回某一份残缺快照。默认报告吃的就是这份 `selection`，快照在 `selection.snapshots`，挑选提醒在 `selection.warnings`。默认挑法不合口径时，拿 `results` 自己挑，手工挑的 `Snapshot[]` 数组同样能喂给每个组件。
+注入的上下文只有两样，全部是[结果数据 API](/zh/reference/results-data) 的原语，宿主没有私有通道：`results` 就是 `openResults(".niceeval")` 的返回（实验、历次快照、attempt 级 `diff()`、`trace()` 都在上面）；`selection` 是宿主替你挑好的那份结果。挑选规则是：对每个实验、每道 eval，取该实验历史运行里最新的那次判定——只按前缀重跑了一部分 eval，其余 eval 的判定从更早的运行补齐，不会因为一次局部重跑就整体退回某一份残缺快照。默认报告吃的就是这份 `selection`，快照在 `selection.snapshots`，挑选提醒在 `selection.warnings`。默认挑法不合口径时，拿 `results` 自己挑，手工挑的 `Snapshot[]` 数组同样能喂给每个组件。
 
 报告文件里有两种数据形态。实体列表的 `.data(selection)` 返回普通数组：`ExperimentListItem[]`、`EvalListItem[]`、`AttemptListItem[]`。报告作者用 JavaScript `.filter()` / `.slice()` 决定展示哪些实体，再把数组作为 `items` 传给列表；组件不藏另一套过滤 DSL。指标图形和汇总组件收算好的 `data`；其中 `MetricScatter` 也提供 `selection` 简写，由宿主在渲染前计算。计算后的组件只渲染传入数据，不碰结果目录。
 
@@ -67,7 +67,7 @@ niceeval view --report reports/exam.tsx    # 网页：同一棵树走网页面
 
 命令行的范围先作用在挑选上，报告拿到的就是收窄到这个范围后的 `selection`：位置参数的 eval id 前缀收窄 Selection 覆盖的 eval（覆盖提醒的分母同样收窄到范围内），`--run` 把结果根换成指定目录，`--experiment` 让 Selection 只留该实验。`--history` 与 `--report` 互斥——趋势在报告里用 `exp.snapshots` 自己摆；证据切面（`--eval` / `--execution` / `--diff`）只看证据，不渲染报告。
 
-页面里的每个组件都是**双面**的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据。实体列表按 experiment → Eval → Attempt 展示事实；指标表、矩阵、条形图、成绩单、散点图、趋势图和差异表展示聚合值。完整清单见[报告组件](/zh/guides/report-components)。网页面的实体、格子和点深链到 Attempt 详情，终端面印出对应的 `niceeval show <eval id>` 下钻命令。
+页面里的每个组件都是**双面**的：网页面是 React 渲染，终端面是字符渲染，两面吃同一份算好的数据。实体列表按 experiment → Eval → Attempt 展示事实；指标表、矩阵、条形图、成绩单、散点图、趋势图和差异表展示聚合值。完整清单见[报告组件](/zh/reference/report-components)。网页面的实体、格子和点深链到 Attempt 详情，终端面印出对应的 `niceeval show <eval id>` 下钻命令。
 
 默认报告没有特权：它就是上面导出的 `ExperimentComparison`。你的报告和它同级；需要同样的“按目录分组、组内比较”摆法就直接引用它，不需要就不摆。自己直接组合 `MetricScatter` / `ExperimentList` 时，通用组件只消费你传入的数据，不会自动分组；把跨组 Selection 传进去就表示你明确要做跨组分析。
 
@@ -190,7 +190,7 @@ codex   80%         355 lines    $0.51
 
 `label` 可以是一份文案，也可以按语言给：`label: { en: "Code lines", "zh-CN": "代码行数" }`——查看器界面切语言时，按语言给的 label 跟着切；只给一份就两种语言都用它。指标算出来的数字本身不分语言。
 
-内置指标里 `endToEndPassRate` / `taskPassRate` / `executionReliability` / `costUSD` / `durationMs` / `tokens` 只读 Attempt 自带的判定、用量这些字段，任何一份结果目录都算得出。没有限定词的“成功率”使用 `endToEndPassRate`：passed 记 1，failed 和 errored 都记 0。`taskPassRate` 只在形成可信判定的样本上衡量答题质量，errored 不参与；展示它时应明确写“可判定任务通过率”，不能简称成功率。要区分答题质量和执行问题，把 `endToEndPassRate`、`taskPassRate`、`executionReliability` 三列并排。`turns`（Agent 的总轮次）不一样，它读 `attempt.o11y()`——这份数据 `copySnapshots` 缺省会随行，但如果发布脚本显式给了 `artifacts` 列表又没把 `"o11y"` 写进去，它就不在发布根里（见[结果数据 API](/zh/guides/results-data)的「发布」一节），指标渲染成 `—`，不是 0。自己写的指标只要读了 `o11y()` / `diff()` 这类 artifact（就像上面 `codeLines` 读 `attempt.diff()`），发布前都要过一遍同样的检查。
+内置指标里 `endToEndPassRate` / `taskPassRate` / `executionReliability` / `costUSD` / `durationMs` / `tokens` 只读 Attempt 自带的判定、用量这些字段，任何一份结果目录都算得出。没有限定词的“成功率”使用 `endToEndPassRate`：passed 记 1，failed 和 errored 都记 0。`taskPassRate` 只在形成可信判定的样本上衡量答题质量，errored 不参与；展示它时应明确写“可判定任务通过率”，不能简称成功率。要区分答题质量和执行问题，把 `endToEndPassRate`、`taskPassRate`、`executionReliability` 三列并排。`turns`（Agent 的总轮次）不一样，它读 `attempt.o11y()`——这份数据 `copySnapshots` 缺省会随行，但如果发布脚本显式给了 `artifacts` 列表又没把 `"o11y"` 写进去，它就不在发布根里（见[结果数据 API](/zh/reference/results-data)的「发布」一节），指标渲染成 `—`，不是 0。自己写的指标只要读了 `o11y()` / `diff()` 这类 artifact（就像上面 `codeLines` 读 `attempt.diff()`），发布前都要过一遍同样的检查。
 
 ## 换分组：三种维度
 
@@ -297,7 +297,7 @@ codex       80%   $0.51
 克劳德        —       —
 ```
 
-列宽按**终端显示宽度**算：一个汉字占 2 列，所以中文 agent 名、中文题目名都不会把表撕歪。`align: "right"` 让数字列右对齐。格子给 `null` 就渲染 `—`，不补 0。行上带 `locator` 就多出一列 attempt，网页面点进证据室、终端面把 locator 交给 `niceeval show`。完整字段见[报告组件](/zh/guides/report-components)的「表格」一节。
+列宽按**终端显示宽度**算：一个汉字占 2 列，所以中文 agent 名、中文题目名都不会把表撕歪。`align: "right"` 让数字列右对齐。格子给 `null` 就渲染 `—`，不补 0。行上带 `locator` 就多出一列 attempt，网页面点进证据室、终端面把 locator 交给 `niceeval show`。完整字段见[报告组件](/zh/reference/report-components)的「表格」一节。
 
 ### 不是表：`defineComponent` 加文本排版函数
 
@@ -389,7 +389,7 @@ codex   ████████████████░░░░  80%
 niceeval view --report reports/exam.tsx --out site
 ```
 
-产物是纯静态文件：你的报告页是首页，证据室（transcript、trace、代码视图）在同一站内，报告里的每个数字点进去就是证据。组件不 hydrate；页面内联一小段官方脚本，提供表头排序、行过滤、图表悬停这些浏览操作，浏览器禁用 JS 时页面仍完整可读。交给任何静态托管即可。CI 上没有 `.niceeval/` 时，先用 `copySnapshots` 把快照瘦身进仓库再导出，流程见[查看结果](/zh/guides/viewing-results#导出与静态托管)。
+产物是纯静态文件：你的报告页是首页，证据室（transcript、trace、代码视图）在同一站内，报告里的每个数字点进去就是证据。组件不 hydrate；页面内联一小段官方脚本，提供表头排序、行过滤、图表悬停这些浏览操作，浏览器禁用 JS 时页面仍完整可读。交给任何静态托管即可。CI 上没有 `.niceeval/` 时，先用 `copySnapshots` 把快照瘦身进仓库再导出，流程见[查看结果](/zh/how-to/viewing-results#导出与静态托管)。
 
 双面组件的网页面就是普通 React 组件，`data` 函数就是普通 TS 函数——想把某一块指标表嵌进已有的内部面板，import 组件喂数据就行。那是零件的复用，不是另一套报告系统：报告的家在官方宿主。算数据与渲染分离部署时（CI 落 JSON、另一个应用 fetch），两侧锁同一个 niceeval 版本是硬要求——组件数据不带版本戳，兼容性跟随包版本。
 

package/docs-site/zh/{guides → how-to}/experiments.mdx

@@ -43,7 +43,7 @@ npx niceeval exp compare-models   # 把同组各 model 并排出报告
 npx niceeval exp compare-models/gpt-5.4
 ```
 
-`defineExperiment` 的字段怎么写、`flags` 怎么透传到 adapter，见[写实验](/zh/guides/write-experiment)。
+`defineExperiment` 的字段怎么写、`flags` 怎么透传到 adapter，见[写实验](/zh/how-to/write-experiment)。
 
 ## 适合比较什么
 
@@ -51,10 +51,10 @@ npx niceeval exp compare-models/gpt-5.4
 - 不同模型（Tier 1 接入即可：应用接口暴露模型选择，`model` 经 `ctx.model` 透传）。
 - 不同 prompts 或 feature flags（要求 Tier 3 接入：变体在应用内部，需要应用把它暴露成 experiment 可选的 flag，经 `flags` → `ctx.flags` 透传）。
 - 不同 sandbox provider。
-- 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` 钩子里，一个变体一个 experiment 文件，见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+- 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` 钩子里，一个变体一个 experiment 文件，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 - 同一任务的 pass@N。
 
-Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/concepts/tier)。
+Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/explanation/tier)。
 
 ## 查看结果
 

package/docs-site/zh/{guides → how-to}/publish-report.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "CI 发布报告"
 description: "把经过 copySnapshots 大小预检的结果目录提交进仓库,CI 用一行 view --run 导出报告站;超大文件在 commit 前就会得到可执行错误。"
 ---
 
-`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、结果快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/guides/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里，但不要直接提交本地事实根 `.niceeval/`：逐字符串截断能防一条失控输出膨胀，不能保证整个文件小于 Git host 的限制。先用 `copySnapshots` 生成经过 50 MiB 单文件预检的发布结果根，再提交这个目录。
+`niceeval view --out <目录>` 把查看器导出成一个纯静态目录:报告、结果快照列表、transcript、trace 瀑布,和本地 `niceeval view` 看到的完全一样(导出行为见[查看结果 · 导出与静态托管](/zh/how-to/viewing-results#导出与静态托管))。CI 发布只需要让结果数据到构建机手里，但不要直接提交本地事实根 `.niceeval/`：逐字符串截断能防一条失控输出膨胀，不能保证整个文件小于 Git host 的限制。先用 `copySnapshots` 生成经过 50 MiB 单文件预检的发布结果根，再提交这个目录。
 
 ## 生成可提交的结果目录
 
@@ -38,7 +38,7 @@ npx niceeval view --run report-data --out site
 
 ## 发布自定义报告
 
-不传 `--report` 时,发布出来的首页是默认报告。想让首页换成自己的报告,把 [`defineReport` 报告文件](/zh/guides/custom-reports)传给 `--report` 就行——attempt 证据页(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
+不传 `--report` 时,发布出来的首页是默认报告。想让首页换成自己的报告,把 [`defineReport` 报告文件](/zh/how-to/custom-reports)传给 `--report` 就行——attempt 证据页(transcript、trace、代码视图)仍在同一个站里,报告里的每个数字点进去就是对应证据,和本地 `view --report` 看到的一模一样:
 
 ```bash
 npx niceeval view --run report-data --report reports/exam.tsx --out site

package/docs-site/zh/{guides → how-to}/sandbox-agent.mdx

@@ -63,7 +63,7 @@ export default defineExperiment({
 });
 ```
 
-Claude Code 使用 `correctroads-default-team/niceeval-claude-code:v0.6.1`，Bub 使用 `correctroads-default-team/niceeval-bub:v0.6.1`。版本 tag 适合 CI；省略 tag 会跟随当前稳定构建。如何继续增加系统包、二进制或模型缓存，见 [沙箱 provider · 从官方基线继续构建以提速](/zh/guides/sandbox-providers#从官方基线继续构建以提速)。
+Claude Code 使用 `correctroads-default-team/niceeval-claude-code:v0.6.1`，Bub 使用 `correctroads-default-team/niceeval-bub:v0.6.1`。版本 tag 适合 CI；省略 tag 会跟随当前稳定构建。如何继续增加系统包、二进制或模型缓存，见 [沙箱 provider · 从官方基线继续构建以提速](/zh/how-to/sandbox-providers#从官方基线继续构建以提速)。
 
 内置 agent 从 `niceeval/adapter` 导出的是工厂函数。需要配置鉴权、代理、MCP 或 GitHub skill 时，把这些写进工厂参数；模型仍然写在 experiment 的 `model` 字段，sandbox provider 仍然写在 `sandbox` 字段：
 
@@ -120,7 +120,7 @@ createSandbox
 
 `t.sandbox.diff` 与 `t.sandbox.fileChanged()` 只包含 **agent 在 `t.send()` 期间改动的文件**：NiceEval 在每次 `t.send()` 前后记录一次工作区状态，把中间的变化记在 agent 名下。你上传的起始文件、`t.send()` 之后写入的验证材料都不会混进来，所以 `fileChanged("src/app.ts")` 只在 agent 真的动过这个文件时通过。
 
-环境钩子（`.setup()` / `.teardown()`）挂在 experiment `sandbox` 字段的 spec 上，用来做"按实验变化的环境准备"——装某个实验专属的二进制、预热、跨 attempt 载入和回存状态。它写下的文件属于环境，不会被算进 agent 产出的 diff。写法和规则见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+环境钩子（`.setup()` / `.teardown()`）挂在 experiment `sandbox` 字段的 spec 上，用来做"按实验变化的环境准备"——装某个实验专属的二进制、预热、跨 attempt 载入和回存状态。它写下的文件属于环境，不会被算进 agent 产出的 diff。写法和规则见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 
 ## 自定义 sandbox agent
 

package/docs-site/zh/{guides → how-to}/sandbox-providers.mdx

@@ -347,4 +347,4 @@ export default defineSandbox({
 - 控制 `maxConcurrency`（experiment 字段或 `--max-concurrency`），避免本地 Docker 资源耗尽。
 - 把慢测试拆成必要的 gate 和可选的 soft 检查。
 
-Warm pools 和复用属于 runner / scheduler 层面的能力，详见 [Runner](/zh/guides/runner)。
+Warm pools 和复用属于 runner / scheduler 层面的能力，详见 [Runner](/zh/explanation/runner)。

package/docs-site/zh/{guides → how-to}/viewing-results.mdx

@@ -23,7 +23,7 @@ ACTIVE
 … 17 more active
 ```
 
-Human profile 只原位更新当前总数和 active slots，不把历史帧推入 scrollback。失败、错误和去重后的 diagnostic 永久追加，并带 locator。结束块只保留摘要、失败 locator、下钻命令和结果路径。这段输出怎么进「跑→读→修→再跑」的循环，见 [Agent 反馈闭环](/zh/guides/agent-feedback-loop)。
+Human profile 只原位更新当前总数和 active slots，不把历史帧推入 scrollback。失败、错误和去重后的 diagnostic 永久追加，并带 locator。结束块只保留摘要、失败 locator、下钻命令和结果路径。这段输出怎么进「跑→读→修→再跑」的循环，见 [Agent 反馈闭环](/zh/how-to/agent-feedback-loop)。
 
 ## `.niceeval/<experiment>/<快照>/`
 
@@ -321,7 +321,7 @@ compare/codex-gpt-5.4 · 5 runs · passed 2/5
 
 ✓✗ 交替说明这个 eval 在抖，该修的是稳定性（被测程序或断言），反复重跑碰运气只会烧钱；连续绿转红的拐点就是回归引入的位置，用 `--run <目录>` 钉住拐点前后两次细看。时间轴只列真实执行——缓存携带的旧结果是判定的复印件，不占行，否则趋势会被复印件灌满假数据。不带 eval id 的 `niceeval show --history` 给每个 experiment 的 per-run 通过率序列，同一份趋势的榜单视角。
 
-两次 run 的精确对比（这次修复具体翻转了哪些 eval）不做成 flag：用 `DeltaTable` 积木写一份报告递给 `--report`，几行就是一份自定义对比报告，终端和网页两扇门都认——内置命令只管固定摆法，自定义口径见[自定义报告](/zh/guides/custom-reports)。
+两次 run 的精确对比（这次修复具体翻转了哪些 eval）不做成 flag：用 `DeltaTable` 积木写一份报告递给 `--report`，几行就是一份自定义对比报告，终端和网页两扇门都认——内置命令只管固定摆法，自定义口径见[自定义报告](/zh/how-to/custom-reports)。
 
 ## `niceeval view`：网页证据室
 
@@ -335,13 +335,13 @@ npx niceeval view
   失败后立刻运行 `npx niceeval view`，可以直接打开刚刚那次运行的 artifacts。
 </Tip>
 
-`view` 的首页是一份报告：不传 `--report` 时完整加载当前结果并显示全部可比组索引，选中一组后只显示该组的成本 × 端到端成功率散点图与实验表。切组只改变页面状态，不重新读取或计算；不同组不会混进同一张图或榜单。浏览器禁用 JS 时，每组作为独立的 `<details>` 完整可读；启用 JS 后一次聚焦一组。传了 `--report` 就换成你自己的报告（与 `show --report` 吃同一个文件），见[自定义报告](/zh/guides/custom-reports)。证据部分（Attempt 弹窗、transcript、trace 瀑布、run 列表）始终保留。
+`view` 的首页是一份报告：不传 `--report` 时完整加载当前结果并显示全部可比组索引，选中一组后只显示该组的成本 × 端到端成功率散点图与实验表。切组只改变页面状态，不重新读取或计算；不同组不会混进同一张图或榜单。浏览器禁用 JS 时，每组作为独立的 `<details>` 完整可读；启用 JS 后一次聚焦一组。传了 `--report` 就换成你自己的报告（与 `show --report` 吃同一个文件），见[自定义报告](/zh/how-to/custom-reports)。证据部分（Attempt 弹窗、transcript、trace 瀑布、run 列表）始终保留。
 
 网页版多几样浏览操作：切换可比组、点表头就地排序、在当前组的过滤框里筛行、点开一个 experiment 行看它每道题的判定与原因、悬停散点看数值——这些只影响眼前的视图，不改判定口径，刷新即恢复。Attempt 弹窗里有与 `show --timing` 同源的统一时间树：Sandbox 启动、setup hook 及其 shell、agent 安装命令、每轮 send 与可关联的 OTel model/tool、评分与收尾都能逐层展开。报告上方有 **Copy fix prompt** 按钮，把全部失败打包成可直接粘给 coding agent 的修复 prompt（attempt 弹窗里有单条版）。报告文案有中英两份，随界面语言切换。
 
 ## 导出与静态托管
 
-发布结果只有一种导出：`--out <目录>` 整站导出，完整带上能查看的一切。想要自己的页面形态，用报告积木自建（见[自定义报告](/zh/guides/custom-reports)）。
+发布结果只有一种导出：`--out <目录>` 整站导出，完整带上能查看的一切。想要自己的页面形态，用报告积木自建（见[自定义报告](/zh/how-to/custom-reports)）。
 
 ### 内置查看器整站：静态托管
 
@@ -360,7 +360,7 @@ NiceEval 写入 `<dir>/index.html`，并把查看器要读取的 artifact（`sou
 - `diff.json` 和 `o11y.json` 不会被复制。查看器不读取它们，且 diff 可能达到上百 MB。
 - 用 `file://` 直接打开 `index.html` 时浏览器不允许 fetch artifact，代码视图会提示源码不可用。本地预览用 http 服务打开。
 
-最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。要让站点随 push 自动更新，先用 `copySnapshots` 生成经过单文件预算检查的发布结果根，把它提交进仓库，再让 CI 对这个目录运行 `view --run <目录> --out`——workflow 与平台接线见[通过 CI 发布报告](/zh/guides/publish-report)。
+最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。要让站点随 push 自动更新，先用 `copySnapshots` 生成经过单文件预算检查的发布结果根，把它提交进仓库，再让 CI 对这个目录运行 `view --run <目录> --out`——workflow 与平台接线见[通过 CI 发布报告](/zh/how-to/publish-report)。
 
 ## Artifact 说明
 
@@ -410,4 +410,4 @@ Soft 断言的分数记录在 `assertions[].score` 里；非 `--strict` 模式
 - 想知道 agent 做了什么、调用了什么，看 `--execution`；关联成功的 OTel 时间会贴在同一事件旁。
 - coding-agent 失败时看 `--diff` 和 `--execution` 里的工具调用；两者结合能看出「改错了文件」还是「压根没调用该调用的工具」。
 - Sandbox eval 跑得慢或超时，先看 `--timing`：排队、Sandbox 启动、setup hook 里的每条 shell、agent 安装命令、每轮 send 与可关联的 OTel model/tool 各花多久，一眼可判；收尾卡住也在这里单独列出。
-- 判断缺陷在被测程序还是 eval 本身、修完怎么重跑，流程见 [Agent 反馈闭环](/zh/guides/agent-feedback-loop)。
+- 判断缺陷在被测程序还是 eval 本身、修完怎么重跑，流程见 [Agent 反馈闭环](/zh/how-to/agent-feedback-loop)。

package/docs-site/zh/{guides → how-to}/write-experiment.mdx

@@ -118,8 +118,8 @@ export default defineExperiment({
 });
 ```
 
-固定的 Agent CLI、系统包和大模型缓存应先做进 image/template/snapshot；`.setup()` 不应在每个 Attempt 重建同一套环境。如何从官方 Docker 镜像、E2B 模板或 Vercel runtime 继续派生来提速，见 [沙箱 provider · 从官方基线继续构建以提速](/zh/guides/sandbox-providers#从官方基线继续构建以提速)。
+固定的 Agent CLI、系统包和大模型缓存应先做进 image/template/snapshot；`.setup()` 不应在每个 Attempt 重建同一套环境。如何从官方 Docker 镜像、E2B 模板或 Vercel runtime 继续派生来提速，见 [沙箱 provider · 从官方基线继续构建以提速](/zh/how-to/sandbox-providers#从官方基线继续构建以提速)。
 
-钩子的执行时机、多钩子顺序和失败语义见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+钩子的执行时机、多钩子顺序和失败语义见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 
-跨配置比较的设计建议见[实验矩阵](/zh/guides/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/concepts/adapter)。
+跨配置比较的设计建议见[实验矩阵](/zh/how-to/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/explanation/adapter)。

package/docs-site/zh/{guides → how-to}/write-send.mdx

@@ -4,11 +4,11 @@ sidebarTitle: "如何写好 Send"
 description: "手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 flags。每一步只在上一步的代码上多几行，每一步解锁一组断言。"
 ---
 
-[Adapter](/zh/concepts/adapter) 讲了契约：`send` 传入 `TurnInput` 和 `AgentContext`，返回 `Turn`。这一页讲怎么写它——从"发一条消息拿到回复"的最小形态起步，一步一步加到完整接入。每一步只在上一步的代码上多几行，前面已有的部分在代码里用 `// ……省略` 标出；每一步末尾说明这几行解锁了哪些断言。改完任何一步都能立刻验证：把新解锁的断言写进一条 eval 重跑 `npx niceeval exp`，`niceeval view` 里能看到这一步新增的数据——多轮轨迹、用量、工具事件、待回答请求。
+[Adapter](/zh/explanation/adapter) 讲了契约：`send` 传入 `TurnInput` 和 `AgentContext`，返回 `Turn`。这一页讲怎么写它——从"发一条消息拿到回复"的最小形态起步，一步一步加到完整接入。每一步只在上一步的代码上多几行，前面已有的部分在代码里用 `// ……省略` 标出；每一步末尾说明这几行解锁了哪些断言。改完任何一步都能立刻验证：把新解锁的断言写进一条 eval 重跑 `npx niceeval exp`，`niceeval view` 里能看到这一步新增的数据——多轮轨迹、用量、工具事件、待回答请求。
 
 三个贯穿全文的原则：
 
-- **接的位置永远是用户前端本来就在用的那个接口。** 页面调哪个端点、收什么格式，Adapter 就调哪个端点、收什么格式——不为 eval 开新接口，也不 import 应用内部代码直调函数（为什么，见[接入你的 Agent](/zh/guides/connect-your-agent)）。
+- **接的位置永远是用户前端本来就在用的那个接口。** 页面调哪个端点、收什么格式，Adapter 就调哪个端点、收什么格式——不为 eval 开新接口，也不 import 应用内部代码直调函数（为什么，见[接入你的 Agent](/zh/how-to/connect-your-agent)）。
 - **你唯一真正手写的是 transport**——URL、鉴权、请求体每家本来就不一样。解析（原始返回 → 标准事件流）有官方转换器，从 `niceeval/adapter` 导出；编排（会话续接、HITL 暂停恢复）的状态槽就挂在 `ctx.session` 上，取用即可，不需要额外声明什么。
 - **运行反馈走 `ctx`，不直接写终端。** 长步骤用 `ctx.progress(...)`；需要在运行后回顾的退化或异常上下文用 `ctx.diagnostic(...)`；无法继续时抛错。不要从 Adapter 调用 `console.log/error` 或写 `process.stdout/stderr`。
 
@@ -72,7 +72,7 @@ if (!res.requestId) {
 
 `progress` 不落盘；diagnostic 会随 Attempt 保存并可通过 locator 回顾。HTTP 连接失败或响应无法解析时直接抛错，runner 会记录错误发生在 `agent.run`，并把 Attempt 标为 `errored`。
 
-**这一步解锁**：`t.reply`、`t.messageIncludes()`、judge 的全部对话材料，以及 experiment 侧的**模型对比**（`ctx.model` 就是 experiment 声明的 `model`，运行器原样递给你、Adapter 不解释含义，只转发——不需要等到后面的步骤，也不需要应用配合做任何改造，分档见 [Tier](/zh/concepts/tier)）。
+**这一步解锁**：`t.reply`、`t.messageIncludes()`、judge 的全部对话材料，以及 experiment 侧的**模型对比**（`ctx.model` 就是 experiment 声明的 `model`，运行器原样递给你、Adapter 不解释含义，只转发——不需要等到后面的步骤，也不需要应用配合做任何改造，分档见 [Tier](/zh/explanation/tier)）。
 
 它有两个明显的局限：每轮都是一场全新对话（第二次 `t.send` 接不上第一次），工具调用完全看不见。后面两步各解决一个。
 
@@ -153,7 +153,7 @@ export default defineAgent({
 
 ## 第四步：把工具解析成事件
 
-应用的返回里不只有回复文本——Chat Completions 形返回的 `tool_calls` 记录了这轮调过什么工具。Adapter 最重要的工作就是**把接口的返回归一成标准事件流**：本轮发生的每件事一个对象，按真实发生顺序排进 `Turn.events`，对象是下面十种类型之一（各字段的实际值，[契约页有一轮的完整示例](/zh/concepts/adapter)）：
+应用的返回里不只有回复文本——Chat Completions 形返回的 `tool_calls` 记录了这轮调过什么工具。Adapter 最重要的工作就是**把接口的返回归一成标准事件流**：本轮发生的每件事一个对象，按真实发生顺序排进 `Turn.events`，对象是下面十种类型之一（各字段的实际值，[契约页有一轮的完整示例](/zh/explanation/adapter)）：
 
 ```ts
 type StreamEvent =
@@ -226,7 +226,7 @@ type StreamEvent =
 应用中途停下来等人（工具审批、等补充信息）时，`send` 两侧各有义务：
 
 - **停轮**：返回 `status: "waiting"`，并且每个待回答的问题吐一条带稳定 `id` 的 `input.requested` 事件——`t.parked()`、`t.requireInputRequest()` 读它，回答靠这个 `id` 对位。
-- **回答轮**：eval 里的 `t.respond(...)` 到 Adapter 是**又一次普通的 `send`**（还是同一条会话线、同一份状态），人的裁决以结构化形式随 `input.responses` 到达，每条带 `requestId`、`optionId` 或 `text`（形态见[不同回答的入参](/zh/concepts/adapter#不同回答的入参)）。Adapter 先把裁决交回应用，再接着取结果。被人拒绝的调用，`action.result` 的 `status` 置 `"rejected"` 而不是 `"failed"`——拒绝是人的决定、不是工具故障，`noFailedActions()` 不误伤。
+- **回答轮**：eval 里的 `t.respond(...)` 到 Adapter 是**又一次普通的 `send`**（还是同一条会话线、同一份状态），人的裁决以结构化形式随 `input.responses` 到达，每条带 `requestId`、`optionId` 或 `text`（形态见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)）。Adapter 先把裁决交回应用，再接着取结果。被人拒绝的调用，`action.result` 的 `status` 置 `"rejected"` 而不是 `"failed"`——拒绝是人的决定、不是工具故障，`noFailedActions()` 不误伤。
 
 "停轮时读了一半的现场"（比如一条读到一半的 SSE 流）也存在 `ctx.session` 上：停轮时 `ctx.session.hold(现场)`，回答轮开头 `ctx.session.take()` 取回——取到即清除，一次消费。
 
@@ -284,7 +284,7 @@ export default defineAgent({
 });
 ```
 
-不需要 HITL 的接口，删掉停轮现场相关的三处（`Pending`、`hold`、开头的 `take` 分支）即可，其余不变。停轮 / 回答 / 续跑的完整心智模型见 [HITL](/zh/concepts/hitl)。
+不需要 HITL 的接口，删掉停轮现场相关的三处（`Pending`、`hold`、开头的 `take` 分支）即可，其余不变。停轮 / 回答 / 续跑的完整心智模型见 [HITL](/zh/explanation/hitl)。
 
 **这一步解锁**：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`，以及 `calledTool(..., { status: "rejected" })` 的精确断言。
 
@@ -318,7 +318,7 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces node server.js
 
 `ctx.telemetry` 只在配置了 OTel 接入时出现，没配时 spread 一个 `undefined` 也安全，这行可以常驻。不带这个头 span 也能收到，但归属退化成时间窗口、该 agent 的轮次会降为串行——带上它是并发下归属准确的来源。
 
-**这一步解锁**：`niceeval view` 里的调用瀑布图——应用内部每次模型调用、每次工具执行的耗时与 token，按轮铺成时间线。断言不变：判定依据在前几步的事件映射里已经齐了，span 只进瀑布图、不喂断言。接收器怎么起、span 怎么归属到轮，见 [OTel 接入](/zh/guides/connect-otel)。
+**这一步解锁**：`niceeval view` 里的调用瀑布图——应用内部每次模型调用、每次工具执行的耗时与 token，按轮铺成时间线。断言不变：判定依据在前几步的事件映射里已经齐了，span 只进瀑布图、不喂断言。接收器怎么起、span 怎么归属到轮，见 [OTel 接入](/zh/how-to/connect-otel)。
 
 ## 第七步：透传 experiment 的 flags（A/B 对比）
 
@@ -345,7 +345,7 @@ export default defineExperiment({
 });
 ```
 
-两个 experiment 文件各声明一份 `flags`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/concepts/tier)；`flags` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/guides/write-experiment)。
+两个 experiment 文件各声明一份 `flags`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/explanation/tier)；`flags` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/how-to/write-experiment)。
 
 **这一步解锁**：同一批 eval 跨变体的成绩对比。
 
@@ -363,8 +363,8 @@ export default defineExperiment({
 
 ## 相关阅读
 
-- [Adapter](/zh/concepts/adapter) — 契约本身：`send` 传入什么返回什么、三个接入等级、能力从哪来。
-- [接入你的 Agent](/zh/guides/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
-- [HITL](/zh/concepts/hitl) — 停轮等人的完整概念：握手时序与两侧义务。
-- [Drive](/zh/concepts/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
-- [Assert](/zh/concepts/assert) — 标准事件流驱动的完整断言词汇。
+- [Adapter](/zh/explanation/adapter) — 契约本身：`send` 传入什么返回什么、三个接入等级、能力从哪来。
+- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
+- [HITL](/zh/explanation/hitl) — 停轮等人的完整概念：握手时序与两侧义务。
+- [Drive](/zh/explanation/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
+- [Assert](/zh/explanation/assert) — 标准事件流驱动的完整断言词汇。

package/docs-site/zh/index.mdx

@@ -19,14 +19,14 @@ description: "NiceEval 是一个渐进式、全功能、开发体验友好、Age
 eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告和结构化 artifacts，让你能查看 agent 的行为细节，调试失败原因，并持续优化 pass rate、成本和延迟。
 
 <CardGroup cols={3}>
-  <Card title="Claude Code / Codex 插件" icon="plug" href="/zh/example/claude-code-codex-plugin">
-    用 sandbox workspace 让 coding agent 跑真实任务，再用测试、diff 和工具调用记录验证插件行为。
+  <Card title="Agent Framework 接入" icon="code-branch" href="/zh/examples">
+    对照 AI SDK、Claude SDK、Codex SDK、pi-agent-core 和 LangGraph 的可运行接入项目。
   </Card>
-  <Card title="Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
-    用 experiment setup 注入 Skill，再与无 Skill baseline 批量比较通过率、成本和行为差异。
+  <Card title="Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    用真实 Workspace 和对照实验衡量 Skill、提示词与 Plugin Benchmark 的实际收益。
   </Card>
-  <Card title="AI Agent 应用" icon="globe" href="/zh/example/ai-agent-application">
-    用 `defineAgent` 包装你的 AI Agent，把回复、工具调用和结构化输出纳入同一套 eval。
+  <Card title="自写 Adapter" icon="globe" href="/zh/examples/ai-agent-application">
+    查看一个覆盖工具、图片、多轮、模型对比和 OTel 的完整 AI Agent 项目。
   </Card>
 </CardGroup>
 
@@ -86,13 +86,13 @@ eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告
 
 | 概念 | 一句话 |
 |---|---|
-| [Eval](/zh/concepts/evals) | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
-| [Experiment](/zh/concepts/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
-| [Adapter](/zh/concepts/adapter) | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
-| [Sandbox](/zh/guides/sandbox-providers) | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
-| [Tier](/zh/concepts/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
+| [Eval](/zh/explanation/evals) | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
+| [Experiment](/zh/explanation/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
+| [Adapter](/zh/explanation/adapter) | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
+| [Sandbox](/zh/how-to/sandbox-providers) | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
+| [Tier](/zh/explanation/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
-完整术语表见[架构概览](/zh/concepts/overview)。
+完整术语表见[架构概览](/zh/explanation/overview)。
 
 ## 示例
 
@@ -142,23 +142,21 @@ npx niceeval view       # 网页交互浏览
 
 ## 快速开始
 
-如果你想让 coding agent 直接帮项目接入 [NiceEval](https://niceeval.com/)，可以把对应场景页交给它读：
+如果你想让 Coding Agent 直接帮项目接入 [NiceEval](https://niceeval.com/)，让它先读安装入口：
 
 ```text
-READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/claude-code-codex-plugin.mdx and install niceeval for this repo.
-READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/claude-code-codex-skill.mdx and install niceeval for this repo.
-READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/ai-agent-application.mdx and install niceeval for this repo.
+READ https://niceeval.com/INIT.md and install niceeval for this repo.
 ```
 
 <CardGroup cols={3}>
-  <Card title="如果你需要 eval 你的 Claude Code / Codex 插件" icon="plug" href="/zh/example/claude-code-codex-plugin">
-    从真实插件任务出发，上传 workspace、注入插件，并用 pass rate 看插件是否稳定工作。
+  <Card title="浏览所有可运行示例" icon="grid-2" href="/zh/examples">
+    按被测对象选择接入前后源码和完整项目。
   </Card>
-  <Card title="如果你需要 eval 你的 Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
-    验证 Skill 是否被加载、是否按约定使用工具、是否产出可测试结果。
+  <Card title="评估 Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    复用真实 Workspace、Baseline 和多 Arm 实验设计。
   </Card>
-  <Card title="如果你需要 eval 你的 AI Agent 应用" icon="globe" href="/zh/example/ai-agent-application">
-    包装你的 agent 接口，写对话、工具调用、结构化输出和成本断言。
+  <Card title="自写 Adapter" icon="globe" href="/zh/examples/ai-agent-application">
+    查看自定义 HTTP 协议和事件映射的完整项目。
   </Card>
 </CardGroup>
 
@@ -169,13 +167,13 @@ READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/doc
     不需要。跑 eval 和 `niceeval view` 看报告全在本地完成；只有被测对象本身是需要隔离工作区的 coding agent 时，才会用到 Docker 或 E2B 这类 sandbox provider。
   </Accordion>
   <Accordion title="我的 Agent 不是用 TypeScript / JavaScript 写的，能接吗？">
-    能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发；应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/concepts/adapter)。
+    能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发；应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/explanation/adapter)。
   </Accordion>
   <Accordion title="能接到 CI 里吗？">
-    能，见 [CI 集成](/zh/guides/ci-integration)。
+    能，见 [CI 集成](/zh/how-to/ci-integration)。
   </Accordion>
 </AccordionGroup>
 
 <Tip>
-  想先走最小路径，读 [快速开始](/zh/quickstart)。想理解边界，读 [架构概览](/zh/concepts/overview)。
+  想先走最小路径，读 [快速开始](/zh/tutorials/quickstart)。想理解边界，读 [架构概览](/zh/explanation/overview)。
 </Tip>

package/docs-site/zh/introduction.mdx

@@ -120,22 +120,22 @@ NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「
 | Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
-完整术语表见[架构概览](/zh/concepts/overview)。
+完整术语表见[架构概览](/zh/explanation/overview)。
 
 ## 从你的场景开始
 
 <CardGroup cols={3}>
-  <Card title="评估 Claude Code / Codex 插件" icon="puzzle-piece" href="/zh/example/claude-code-codex-plugin">
-    把插件放进真实 workspace，比较有插件和无插件时的通过率、成本、耗时和行为差异。
+  <Card title="接入 Agent Framework" icon="code-branch" href="/zh/examples">
+    选择 AI SDK、Claude SDK、Codex SDK、pi-agent-core 或 LangGraph 的可运行接入示例。
   </Card>
-  <Card title="评估 Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
-    对比有 Skill 和无 Skill 的 coding-agent 任务，衡量 Skill 是否真的提升结果。
+  <Card title="评估 Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    用真实 Workspace 和对照实验衡量 Skill、提示词与 Plugin Benchmark 的效果。
   </Card>
-  <Card title="评估你的 AI Agent 应用" icon="robot" href="/zh/example/ai-agent-application">
-    直连你自己的应用接口，断言工具调用、图片理解和多轮会话。
+  <Card title="自写 Adapter" icon="robot" href="/zh/examples/ai-agent-application">
+    查看自定义 HTTP Agent 的工具调用、图片理解、多轮会话和模型对比。
   </Card>
 </CardGroup>
 
 ## 接下来读什么
 
-[快速开始](/zh/quickstart) 会带你安装 [NiceEval](https://niceeval.com/)、构建 eval、得到评估报告。
+[快速开始](/zh/tutorials/quickstart) 会带你安装 [NiceEval](https://niceeval.com/)、构建 eval、得到评估报告。

package/docs-site/zh/reference/builtin-agents.mdx

@@ -242,7 +242,7 @@ export default uiMessageStreamAgent({
 - **收发 + 事件流**：SSE 帧经 `ai` 包官方的框架无关 reducer `readUIMessageStream`（`useChat` 内部同款）归约，工具调用/结果/消息文本从消息 parts 直构——**不要求应用接 OTel**。
 - **会话续接**：协议是服务端零状态、「客户端带全量历史」——工厂用 `ctx.session.history()` 存整份 `UIMessage[]`，每轮原样重放；新会话线（`t.newSession()` 之后）拿到的是空历史。
 - **HITL**：AI SDK v7 tool approval（工具带 `needsApproval: true`）原生映射——part 停在 `approval-requested` 时该 Turn 的 `status: "waiting"` + `input.requested`；`t.respond("approve" / "deny")` 翻译成 `approval-responded` 原地改写该 part、原样重发 `messages` 触发服务端续跑（和真实前端 `addToolApprovalResponse()` + `sendMessage()` 的协议行为一致，没有单独的 approve 端点）。拒绝的调用以 `rejected` 落进事件流，且默认带「不要重试」的 reason（`denyReason` 可覆盖）——不带的话模型经常原样重发同一个调用。
-- **usage / 瀑布图**：UI Message Stream 协议帧里没有 usage，所以 `t.maxTokens` 这类用量断言在这个内置件上默认没有数据（应用把 usage 放进 message metadata 属于应用自己的协议扩展）。瀑布图是另一回事：应用有 OTel 埋点（如官方 `@ai-sdk/otel`）时，按 [OTel 接入](/zh/guides/connect-otel)把 span 发给 [NiceEval](https://niceeval.com/)，`niceeval view` 就有完整瀑布图——span 只进瀑布图，不喂断言。
+- **usage / 瀑布图**：UI Message Stream 协议帧里没有 usage，所以 `t.maxTokens` 这类用量断言在这个内置件上默认没有数据（应用把 usage 放进 message metadata 属于应用自己的协议扩展）。瀑布图是另一回事：应用有 OTel 埋点（如官方 `@ai-sdk/otel`）时，按 [OTel 接入](/zh/how-to/connect-otel)把 span 发给 [NiceEval](https://niceeval.com/)，`niceeval view` 就有完整瀑布图——span 只进瀑布图，不喂断言。
 
 需要在 eval 项目里安装 `ai`（可选 peer 依赖，协议 reducer 来自它）。完整可跑示例：[`examples/zh/tier1/ai-sdk-v7`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/ai-sdk-v7)。
 
@@ -357,7 +357,7 @@ return driveFrameStream(frames, stream, ctx);         // 逐帧喂 stream.add()
 
 ## 通用「拼装方式」件：`driveFrameStream` / `deltaStream` + `ctx.session`
 
-一个手写 send 里真正互不相干的只有三段：transport（怎么发）、reduce（原始数据 → 事件，上一节的转换器管这个）、编排（会话续接 + HITL 暂停恢复）。第三段和任何具体协议无关，纯粹是控制流模式——会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器直接挂在 `ctx.session` 上（`AgentSession`，见 [Adapter 概念](/zh/concepts/adapter#上下文：agentcontext)），不需要单独导入什么件、也不需要声明；剩下真正跨协议复用的只有两个官方件：
+一个手写 send 里真正互不相干的只有三段：transport（怎么发）、reduce（原始数据 → 事件，上一节的转换器管这个）、编排（会话续接 + HITL 暂停恢复）。第三段和任何具体协议无关，纯粹是控制流模式——会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器直接挂在 `ctx.session` 上（`AgentSession`，见 [Adapter 概念](/zh/explanation/adapter#上下文：agentcontext)），不需要单独导入什么件、也不需要声明；剩下真正跨协议复用的只有两个官方件：
 
 | 件 | 解决什么 |
 |---|---|
@@ -414,7 +414,7 @@ export default defineAgent({
 
 ## 相关阅读
 
-- [接入你的 agent](/zh/guides/connect-your-agent) — 自己写 adapter 时每个能力怎么做、对应什么断言。
-- [Sandbox Agent](/zh/guides/sandbox-agent) — 怎么运行内置 sandbox agent，以及怎么写自己的。
+- [接入你的 agent](/zh/how-to/connect-your-agent) — 自己写 adapter 时每个能力怎么做、对应什么断言。
+- [Sandbox Agent](/zh/how-to/sandbox-agent) — 怎么运行内置 sandbox agent，以及怎么写自己的。
 - [defineAgent 参考](/zh/reference/define-agent) — `defineAgent` / `defineSandboxAgent` 完整参数。
-- [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` 的调用瀑布图。

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

@@ -49,15 +49,15 @@ export default defineAgent({
 
 ### 工具/动作事件完整性
 
-含义：这一轮的每次工具调用是否都以 `action.called` + `action.result` 出现在 events 里（[事件流参考](/zh/reference/events)）。来源只有两个：官方转换器按被测协议的契约保证；手工映射由你的代码决定。OTel span 不是来源——span 只进瀑布图，不进事件流（见 [OTel 接入](/zh/guides/connect-otel)）。
+含义：这一轮的每次工具调用是否都以 `action.called` + `action.result` 出现在 events 里（[事件流参考](/zh/reference/events)）。来源只有两个：官方转换器按被测协议的契约保证；手工映射由你的代码决定。OTel span 不是来源——span 只进瀑布图，不进事件流（见 [OTel 接入](/zh/how-to/connect-otel)）。
 
 ### 会话续接
 
-含义：用 `ctx.session.id` / `capture` 或 `ctx.session.history` 把请求连到同一个后端会话/累计历史上。有它，跨轮记忆断言、`t.newSession()` 隔离断言才有意义。两种实现写法见[写 send](/zh/guides/write-send)。
+含义：用 `ctx.session.id` / `capture` 或 `ctx.session.history` 把请求连到同一个后端会话/累计历史上。有它，跨轮记忆断言、`t.newSession()` 隔离断言才有意义。两种实现写法见[写 send](/zh/how-to/write-send)。
 
 ### `tracing` —— 发 OTLP trace
 
-runner 消费：运行时起一个本机 OTLP 接收器，把本轮 trace context 经 `ctx.telemetry.headers` 交给你；span 归一后在 `niceeval view` 画瀑布图——只画图，不喂断言。来源：CLI 型写 `tracing` 字段（env / configure 把端点交给被测进程）；长驻应用在 `niceeval.config.ts` 配 `telemetry: { port }` 固定端口（见 [OTel 接入](/zh/guides/connect-otel)）。
+runner 消费：运行时起一个本机 OTLP 接收器，把本轮 trace context 经 `ctx.telemetry.headers` 交给你；span 归一后在 `niceeval view` 画瀑布图——只画图，不喂断言。来源：CLI 型写 `tracing` 字段（env / configure 把端点交给被测进程）；长驻应用在 `niceeval.config.ts` 配 `telemetry: { port }` 固定端口（见 [OTel 接入](/zh/how-to/connect-otel)）。
 
 ### `kind: "sandbox"` —— 沙箱与改文件
 
@@ -70,7 +70,7 @@ runner 消费：为每次 attempt 准备沙箱（Docker / Vercel / E2B），经
 ## 相关阅读
 
 - [事件流参考](/zh/reference/events) —— 事件流承诺的具体内容。
-- [Adapter 概念](/zh/concepts/adapter) —— `ctx`/`Turn` 的完整契约、能力从哪来。
-- [接入你的 agent](/zh/guides/connect-your-agent) —— 每种接入路径怎么做。
-- [OTel 接入](/zh/guides/connect-otel) —— span 只进瀑布图、不喂断言的完整走法。
+- [Adapter 概念](/zh/explanation/adapter) —— `ctx`/`Turn` 的完整契约、能力从哪来。
+- [接入你的 agent](/zh/how-to/connect-your-agent) —— 每种接入路径怎么做。
+- [OTel 接入](/zh/how-to/connect-otel) —— span 只进瀑布图、不喂断言的完整走法。
 - [内置 Agent 能力](/zh/reference/builtin-agents) —— 内置 adapter 各自做到什么。