niceeval 0.6.2 → 0.7.1

package/docs-site/zh/examples/ai-agent-application.mdx

@@ -0,0 +1,63 @@
+---
+title: "自写 Adapter 评估 AI Agent 应用"
+sidebarTitle: "AI Agent 应用"
+description: "一个可运行的 AI SDK v6 Web Agent 评测项目，覆盖自写 Adapter、工具调用、图片理解、多轮会话、模型对比和双路可观测。"
+---
+
+这个项目演示如何用 `defineAgent` 把已有 HTTP Agent 接入 NiceEval。它适合需要控制自有协议和事件映射的应用。
+
+- [查看完整源码](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/ai-sdk)
+- 本地目录：`examples/zh/ai-sdk/`
+
+<Note>
+  如果应用使用 AI SDK v7 的 UI Message Stream，优先使用内置 `uiMessageStreamAgent`。对应的无侵入示例见 [AI SDK v7](/zh/examples/integrations/ai-sdk-v7)。
+</Note>
+
+## 这个项目证明什么
+
+| 部分 | 实现 |
+| --- | --- |
+| 被测应用 | AI SDK v6 Web Agent，HTTP `POST /api/turn` |
+| Adapter | `defineAgent` + 自定义 `AgentEvent` → `StreamEvent` 映射 |
+| Eval | 天气工具、图片理解、多轮文本、多轮图片上下文 |
+| Experiment | 每个文件固定一个模型，同组比较 DeepSeek 与 GPT |
+| 可观测 | 应用继续上报 Langfuse，同时把本轮 OTLP 数据发给 NiceEval |
+
+Adapter 只负责连接和翻译。URL 与模型属于 Experiment；Eval 只描述交互与好结果。这个分层让同一批 Eval 可以复用到不同模型和部署实例。
+
+## 目录
+
+```text
+examples/zh/ai-sdk/
+├── src/                     # 被测 Web Agent
+├── adapter/adapter.ts       # 自写 NiceEval Adapter
+├── evals/                   # 工具、图片和多轮 Eval
+├── experiments/             # 模型对比
+└── niceeval.config.ts
+```
+
+## 跑起来
+
+这个示例调用真实模型，没有 Mock 模式。先复制环境变量并填入 OpenAI 兼容服务的凭据：
+
+```bash
+cd examples/zh/ai-sdk
+pnpm install
+cp .env.example .env
+pnpm dev
+```
+
+另开一个终端运行：
+
+```bash
+cd examples/zh/ai-sdk
+pnpm exec niceeval list
+pnpm exec niceeval exp compare-models weather-tool
+pnpm exec niceeval view
+```
+
+## 继续阅读
+
+- [接入你的 Agent](/zh/how-to/connect-your-agent)：从最小 Adapter 开始接入自己的协议。
+- [如何写好 Send](/zh/how-to/write-send)：逐步补齐会话、工具、HITL 和 OTel。
+- [实验矩阵](/zh/how-to/experiments)：组织模型和配置对比。

package/docs-site/zh/examples/coding-agent-extensions.mdx

@@ -0,0 +1,57 @@
+---
+title: "评估 Coding Agent 扩展"
+sidebarTitle: "Coding Agent 扩展"
+description: "用真实 Workspace、基线实验和自定义报告，评估 Skill、提示词与 Plugin Benchmark 是否改善 Coding Agent 的任务结果。"
+---
+
+这个案例把扩展内容作为 Experiment 变量，让同一个 Coding Agent 在同一批真实开发任务上运行，再比较任务成功率、成本、耗时和行为差异。
+
+- [查看完整源码](https://github.com/CorrectRoadH/coding-agent-skill)
+- [查看 Fixtures 指南](/zh/how-to/fixtures)
+
+## 两组实验
+
+| 实验 | 对照 | 测什么 |
+| --- | --- | --- |
+| Zod Skill | `with-skill` vs `baseline` | Skill 是否让 Agent 稳定使用 `z.object().safeParse()`，而不是退回手写校验 |
+| Ponytail Benchmark | Baseline / Caveman / Ponytail / YAGNI One-liner | 完整决策 Skill 是否比裸 Agent、简短风格 Skill 或一句提示更有效 |
+
+Ponytail 这一组迁移自第三方 Plugin 的 Agentic Benchmark，但这个仓库实际比较的是注入给 Agent 的内容与提示。它不用于证明某个原生 Plugin 包装或安装协议是否正确。原生 Skill / Plugin 的安装配置见 [官方适配器](/zh/reference/official-adapters)。
+
+## 实验设计
+
+每个 Arm 固定相同的模型、Sandbox、任务集、Runs 和预算，只改变注入内容。Eval 不读取“当前是哪个 Arm”，也不为实验组降低验收标准。
+
+```text
+coding-agent-skill/
+├── skills/                  # 各 Arm 注入的内容
+├── workspaces/ts-starter/   # 每个 Eval 的初始项目
+├── evals/                   # 真实开发任务与验证
+├── experiments/             # Baseline 和实验 Arm
+└── reports/benchmark.tsx    # Arm × Metric 自定义报告
+```
+
+验证优先看最终产物：项目测试、隐藏探针、源码和 Diff。只有事件稳定且完整时，才把 Skill Load 或工具调用作为 Gate。
+
+## 跑起来
+
+```bash
+git clone https://github.com/CorrectRoadH/coding-agent-skill.git
+cd coding-agent-skill
+pnpm install
+cp .env.example .env
+docker info
+
+pnpm exec niceeval exp ponytail-baseline
+pnpm exec niceeval exp caveman
+pnpm exec niceeval exp ponytail
+pnpm exec niceeval exp yagni-oneliner
+pnpm exec niceeval view --report reports/benchmark.tsx
+```
+
+## 从这个案例复用什么
+
+- 用 Experiment 表达有扩展和无扩展的对照，不让 Eval 知道实验条件。
+- Prompt 不泄露答案；验证阶段再检查测试、源码、Diff 和行为证据。
+- 把任务成功率作为主指标，把 Token、成本、耗时和行为作为解释指标。
+- [评分指南](/zh/how-to/scoring-guide) 负责选择 Gate、Soft 和 Judge；本页不复制评分 API。

package/docs-site/zh/examples/index.mdx

@@ -0,0 +1,50 @@
+---
+title: "NiceEval Examples"
+sidebarTitle: "选择示例"
+description: "按被测对象选择可运行的 NiceEval 示例：Agent Framework 接入、完整 AI Agent 评测、Coding Agent 扩展 benchmark 和真实项目。"
+---
+
+这里的每个示例都有真实可运行源码。先按被测对象选择，不必从头依次阅读。
+
+如果你还没有跑通过第一条 Eval，先读 [Quickstart](/zh/tutorials/quickstart)。如果你已经知道要完成什么，直接进入对应的 [How-to Guides](/zh/how-to/connect-your-agent)。
+
+## 接入已有 Agent Framework
+
+下面五组示例都保留接入前的普通应用和接入 NiceEval 后的完整项目。页面中的代码 diff 从这两份源码生成。
+
+| 被测对象 | 接入方式 | 示例覆盖 |
+| --- | --- | --- |
+| [AI SDK v7](/zh/examples/integrations/ai-sdk-v7) | 内置 `uiMessageStreamAgent` | UI Message Stream、多轮、工具、HITL |
+| [Claude Agent SDK](/zh/examples/integrations/claude-sdk) | `fromClaudeSdkMessages` | 原生事件流、多轮、工具、HITL |
+| [Codex SDK](/zh/examples/integrations/codex-sdk) | `fromCodexThreadEvents` | 编码任务、文件和命令、usage；SDK 不支持 HITL |
+| [pi-agent-core](/zh/examples/integrations/pi-sdk) | `fromPiAgentEvents` | 原生事件流、多轮、工具、HITL；SDK 没有 OTel |
+| [LangGraph](/zh/examples/integrations/langgraph) | 手写自定义 SSE 帧映射 | Python 应用、多轮、工具、HITL |
+
+每组源码都位于 [`examples/zh/origin/`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin) 和 [`examples/zh/tier1/`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1)。需要 OTel 或 Experiment Flags 时，再沿相同项目进入 `tier2/` 和 `tier3/`。
+
+## 完整评测项目
+
+<CardGroup cols={2}>
+  <Card title="自写 Adapter 评估 AI Agent 应用" icon="robot" href="/zh/examples/ai-agent-application">
+    一个 AI SDK v6 Web Agent，覆盖工具调用、图片理解、多轮会话、模型对比和双路可观测。
+  </Card>
+  <Card title="评估 Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    用真实 Workspace 和对照实验衡量 Skill、提示词与 Plugin Benchmark 对任务结果的影响。
+  </Card>
+</CardGroup>
+
+## 真实项目
+
+### Coding Agent Memory Evals
+
+[coding-agent-memory-evals](https://github.com/CorrectRoadH/coding-agent-memory-evals) 用同一批开发任务和同一个模型，对比 Coding Agent 是否带持久记忆时的任务成功率、成本、耗时和行为差异。
+
+- [查看在线报告](https://niceeval.com/showcase/memory)
+- [查看项目源码](https://github.com/CorrectRoadH/coding-agent-memory-evals)
+
+## 什么不放在 Examples
+
+- 单段 API 用法放进 How-to 或 Reference。
+- 没有可运行源码的伪项目不收录。
+- Roadmap 和尚未实现的接入不收录。
+- 同一个项目不为 Skill、Plugin、Hook 等相邻叫法复制多张案例页。

package/docs-site/zh/{concepts → explanation}/adapter.mdx

@@ -6,7 +6,7 @@ description: "Adapter 是你写的适配器。本文讲清楚 send 函数传入
 
 在 [NiceEval](https://niceeval.com/) 里，`Adapter` 是连接运行器和被测系统的适配层。Adapter 需要实现 `send` 函数：把 `t.send()` 等 eval 侧动作发给你的应用，再把应用返回翻译成 [NiceEval](https://niceeval.com/) 的标准 `Turn`。
 
-后续阅读[写 send](/zh/guides/write-send)
+后续阅读[写 send](/zh/how-to/write-send)
 
 ## 适配器
 如果被测系统使用标准的 OpenAI Chat Completions 或 Responses 协议，可以直接用官方适配器。自己实现的前后端协议（HTTP、gRPC、WebSocket 都行）则写一个 Adapter：它知道怎么鉴权、怎么调用你的应用、怎么把返回翻译成标准事件流。
@@ -94,12 +94,12 @@ export default defineExperiment({
 
 ## 接入等级
 
-按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三级：**Tier 1 只接 send**（应用代码一行不改，全套断言在这一级就齐了）、**Tier 2 send + OTel**（应用把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图）、**Tier 3 侵入改造 + experiment flags**（feature A/B）。每档投入什么、买到什么、什么时候升级，见 [Tier](/zh/concepts/tier)。
+按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三级：**Tier 1 只接 send**（应用代码一行不改，全套断言在这一级就齐了）、**Tier 2 send + OTel**（应用把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图）、**Tier 3 侵入改造 + experiment flags**（feature A/B）。每档投入什么、买到什么、什么时候升级，见 [Tier](/zh/explanation/tier)。
 
 eval 侧的驱动 API——`t.send()`、`t.sendFile()`、`t.newSession()`、HITL 的 `t.respond()` / `t.respondAll()`
 统一都是调用 Adapter 的 `send`。
 
-怎么收敛、send 里怎么接，见[写 send](/zh/guides/write-send)。
+怎么收敛、send 里怎么接，见[写 send](/zh/how-to/write-send)。
 
 ## send 函数
 
@@ -119,7 +119,7 @@ interface Agent {
 `send` 是唯一要实现的函数。它的签名里只有三个类型，分开看。
 
 <Note>
-  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 </Note>
 
 ### 传入：`TurnInput`
@@ -232,7 +232,7 @@ interface AgentSession {
 
 Runner 为 Agent 的 `setup`、每次 `send` 和 `teardown` 分别绑定 lifecycle scope。Adapter 只报告当前回调内部的 progress/diagnostic，不能传 phase、颜色或输出流。`progress` 不落盘；diagnostic 会进入 Attempt 的 `result.json`。无法继续时抛错，由 runner 保存结构化 error 并把 Attempt 标为 `errored`。
 
-`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、沙箱快照 tag 按它分区），见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/how-to/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、沙箱快照 tag 按它分区），见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 
 `session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（eval 的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器都在它上面，"第一轮"就是新会话线的自然形态——`id` 是 `undefined`、`history.get()` 是空数组，没有要判断的分支；`state` 是这些存取器之外的逃生舱，框架从不往里写数据。
 
@@ -257,7 +257,7 @@ interface Turn {
 ]
 ```
 
-对象统共十种类型（`message`、`action.*`、`input.requested`……完整清单见[事件流参考](/zh/reference/events)）。断言读的就是这个数组：`t.calledTool("get_weather")` 数 `action.called`，`t.reply` 取最后一条 assistant `message`。注意 `send` 每次只返回**本轮**的数组——跨轮拼成整条会话线是运行器的事，见下一节。多数情况下你也不手写这些对象：官方转换器的返回值就是一个填好 `events`、`usage`、`status` 的完整 `Turn`，怎么选转换器见[写 send](/zh/guides/write-send)。
+对象统共十种类型（`message`、`action.*`、`input.requested`……完整清单见[事件流参考](/zh/reference/events)）。断言读的就是这个数组：`t.calledTool("get_weather")` 数 `action.called`，`t.reply` 取最后一条 assistant `message`。注意 `send` 每次只返回**本轮**的数组——跨轮拼成整条会话线是运行器的事，见下一节。多数情况下你也不手写这些对象：官方转换器的返回值就是一个填好 `events`、`usage`、`status` 的完整 `Turn`，怎么选转换器见[写 send](/zh/how-to/write-send)。
 
 `data` 不是"随便放点什么"的口袋，它只有一条规则：**要什么，由 eval 在 send 上用 schema 声明；声明了才有 data，拿到手就是声明的类型。**
 
@@ -302,8 +302,8 @@ turn.data.amount;   // 类型是 number——不是 unknown，不用手动收窄
 
 ## 相关阅读
 
-- [写 send](/zh/guides/write-send) — 实操教程：从发一条消息到完整接入，七步递进，每步解锁一组断言。
-- [接入你的 Agent](/zh/guides/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
-- [Drive](/zh/concepts/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
-- [Assert](/zh/concepts/assert) — 标准事件流驱动的完整断言词汇。
-- [架构概览](/zh/concepts/overview) — 四层架构和边界。
+- [写 send](/zh/how-to/write-send) — 实操教程：从发一条消息到完整接入，七步递进，每步解锁一组断言。
+- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
+- [Drive](/zh/explanation/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
+- [Assert](/zh/explanation/assert) — 标准事件流驱动的完整断言词汇。
+- [架构概览](/zh/explanation/overview) — 四层架构和边界。

package/docs-site/zh/{concepts → explanation}/assert.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "断言"
 description: "NiceEval 的断言词汇——值断言、作用域断言、test-as-scoring 和效率断言——以及 gate / soft 严重度和判定 verdict 的规则。"
 ---
 
-断言把 agent 在一次 eval 里做的一切——每条消息、每次工具调用、每处文件改动、每一分 token——折叠成一个可解释的结果。[NiceEval](https://niceeval.com/) 提供四种互补的断言机制：有的立即检查一个值，有的在整轮跑完后评估整次运行，有的在沙箱里跑测试，有的衡量效率。四种都产出同一种 `Assertion` 类型，都进同一套判定规则。第五种机制——让语言模型评判开放式质量——见 [Judge](/zh/concepts/judge)。
+断言把 agent 在一次 eval 里做的一切——每条消息、每次工具调用、每处文件改动、每一分 token——折叠成一个可解释的结果。[NiceEval](https://niceeval.com/) 提供四种互补的断言机制：有的立即检查一个值，有的在整轮跑完后评估整次运行，有的在沙箱里跑测试，有的衡量效率。四种都产出同一种 `Assertion` 类型，都进同一套判定规则。第五种机制——让语言模型评判开放式质量——见 [Judge](/zh/explanation/judge)。
 
 ## 四种断言机制
 
@@ -119,7 +119,7 @@ t.check(turn.data, satisfies((d) => d.total > 0, "total is positive"));
 
 ## 2. 作用域断言
 
-作用域断言在 `test(t)` 里注册，但在函数返回**之后**才对累积完的完整轮次数据评估。它们读的是 `t.send()` 产出的标准事件流（见 [Drive](/zh/concepts/drive)）及其派生事实——所以只要你的 adapter 产出正确的事件，这些断言对任何 agent 都一样好用。
+作用域断言在 `test(t)` 里注册，但在函数返回**之后**才对累积完的完整轮次数据评估。它们读的是 `t.send()` 产出的标准事件流（见 [Drive](/zh/explanation/drive)）及其派生事实——所以只要你的 adapter 产出正确的事件，这些断言对任何 agent 都一样好用。
 
 <Warning>
 作用域断言只有在 agent 声明了对应能力时才出现在 `t` 上。agent 没声明 `toolObservability: true` 时调用 `t.calledTool()` 是编译期报错。
@@ -181,7 +181,7 @@ t.sandbox.noFailedShellCommands();
 
 `t.sandbox.diff` 是可查询对象：`t.sandbox.diff.get("src/Button.tsx")` 返回文件改动后的内容；`t.sandbox.diff.isEmpty()` 检查有没有文件变化；`t.sandbox.diff.matches(re)` 和 `t.sandbox.notInDiff(re)` 对完整 diff 文本跑正则。
 
-作用域断言到处遵守同一条规则：**接收者决定作用域，不是断言名字决定作用域。** `t.*` 聚合这次 eval run 的全部轮次（含 `t.newSession()` 开的额外 session）；`session.*`（`t.newSession()` 的返回值）只看这一条 session；`turn.*`（`t.send()` 的返回值）只看这一轮自己。同一套词汇，不同接收者——各接收者是什么见 [Drive](/zh/concepts/drive)。
+作用域断言到处遵守同一条规则：**接收者决定作用域，不是断言名字决定作用域。** `t.*` 聚合这次 eval run 的全部轮次（含 `t.newSession()` 开的额外 session）；`session.*`（`t.newSession()` 的返回值）只看这一条 session；`turn.*`（`t.send()` 的返回值）只看这一轮自己。同一套词汇，不同接收者——各接收者是什么见 [Drive](/zh/explanation/drive)。
 
 ## 3. Test-as-scoring（沙箱型 eval）
 
@@ -238,7 +238,7 @@ t.check(t.reply, jsonValid());
 
 ## 相关阅读
 
-- [Drive](/zh/concepts/drive) — `t.send()`、`t.newSession()` 和 HITL：这些断言读的 Turn 数据是怎么产出的。
-- [Judge](/zh/concepts/judge) — 第五种评分机制，评无法写成固定规则的开放式质量。
-- [写 send](/zh/guides/write-send) — 标准事件流如何产出，作用域断言依赖它什么。
-- [Evals](/zh/concepts/evals) — 断言如何折进 eval 生命周期和 verdict 类型。
+- [Drive](/zh/explanation/drive) — `t.send()`、`t.newSession()` 和 HITL：这些断言读的 Turn 数据是怎么产出的。
+- [Judge](/zh/explanation/judge) — 第五种评分机制，评无法写成固定规则的开放式质量。
+- [写 send](/zh/how-to/write-send) — 标准事件流如何产出，作用域断言依赖它什么。
+- [Evals](/zh/explanation/evals) — 断言如何折进 eval 生命周期和 verdict 类型。

package/docs-site/zh/{concepts → explanation}/drive.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "驱动"
 description: "t.send() 和它返回的 Turn、t.sendFile()、多轮对话、t.newSession()，以及 respond() 处理的人工介入(HITL)。"
 ---
 
-在断言或 judge 之前，先要让 agent 动起来。**Drive** 是 `test(t)` 里发送输入、拿到结果的那部分——`t.send()`、`t.sendFile()`、`t.newSession()`，以及 HITL 的 `t.respond()` / `t.respondAll()`。驱动产出的都是一个 **Turn**，[NiceEval](https://niceeval.com/) 里的所有断言和 judge 都从 Turn 的数据上读，具体看 [Assert](/zh/concepts/assert) 和 [Judge](/zh/concepts/judge)。
+在断言或 judge 之前，先要让 agent 动起来。**Drive** 是 `test(t)` 里发送输入、拿到结果的那部分——`t.send()`、`t.sendFile()`、`t.newSession()`，以及 HITL 的 `t.respond()` / `t.respondAll()`。驱动产出的都是一个 **Turn**，[NiceEval](https://niceeval.com/) 里的所有断言和 judge 都从 Turn 的数据上读，具体看 [Assert](/zh/explanation/assert) 和 [Judge](/zh/explanation/judge)。
 
 ## `t.send()` 和它返回的 `Turn`
 
@@ -61,7 +61,7 @@ await t.send("好,发出去。");
 t.calledTool("send_email");
 ```
 
-多轮 `t.send()` 能不能真的续上上文，取决于 Adapter 的 `send` 是否接了 `ctx.session` 的会话续接存取器（`history()` 或 `id` + `capture()`）——没接时每轮各是一场新对话。怎么接见 [Adapter](/zh/concepts/adapter) 与[写 send](/zh/guides/write-send)。
+多轮 `t.send()` 能不能真的续上上文，取决于 Adapter 的 `send` 是否接了 `ctx.session` 的会话续接存取器（`history()` 或 `id` + `capture()`）——没接时每轮各是一场新对话。怎么接见 [Adapter](/zh/explanation/adapter) 与[写 send](/zh/how-to/write-send)。
 
 ## 独立会话 —— `t.newSession()`
 
@@ -83,7 +83,7 @@ t.check(fresh.reply, satisfies((r) => !r.includes("小明"), "没有记忆泄漏
 
 ## 人工介入(HITL)
 
-有些 agent 会在一轮执行中间停下来,等审批或缺失信息,而不是直接跑完。这时这一轮以 `status: "waiting"` 结束,并带一条或多条 `input.requested` 事件说明在等什么。完整的心智模型(握手时序、Adapter 侧义务、rejected 语义)见 [HITL](/zh/concepts/hitl),这里讲 eval 侧怎么用。
+有些 agent 会在一轮执行中间停下来,等审批或缺失信息,而不是直接跑完。这时这一轮以 `status: "waiting"` 结束,并带一条或多条 `input.requested` 事件说明在等什么。完整的心智模型(握手时序、Adapter 侧义务、rejected 语义)见 [HITL](/zh/explanation/hitl),这里讲 eval 侧怎么用。
 
 ```ts
 const draft = await t.send("拟一封跟进邮件,但先别发,等我确认。");
@@ -98,7 +98,7 @@ await t.respond({ request, optionId: "approve" });
 t.calledTool("send_email");
 ```
 
-`t.requireInputRequest(filter)` 把一个待处理的 HITL 请求变成可检查、可回应的具体值——如果匹配到 0 个或超过 1 个待处理请求就会抛出,所以尽量把能填的 filter 字段都填上(`id` / `prompt` / `display` / `action` / `optionIds` / `input`)来消歧。`t.respond(...)` 回答它并发出下一轮;每个参数是一条回答:字符串按待处理请求的顺序对位,`{ request, optionId }` 对象形式显式指名(多个请求并停时用它)。在底层它只是又一次普通的 `send`:回答文本进 `input.text`,同时以结构化形式逐条进 `input.responses`——命中请求选项的回答带 `{ requestId, optionId }`,自由文本回答带 `{ requestId, text }`,adapter 不用解析文本,按 `requestId` 就能对上"哪个回答给哪个请求"。每种回答到 adapter 长什么样,见[不同回答的入参](/zh/concepts/adapter#不同回答的入参)。
+`t.requireInputRequest(filter)` 把一个待处理的 HITL 请求变成可检查、可回应的具体值——如果匹配到 0 个或超过 1 个待处理请求就会抛出,所以尽量把能填的 filter 字段都填上(`id` / `prompt` / `display` / `action` / `optionIds` / `input`)来消歧。`t.respond(...)` 回答它并发出下一轮;每个参数是一条回答:字符串按待处理请求的顺序对位,`{ request, optionId }` 对象形式显式指名(多个请求并停时用它)。在底层它只是又一次普通的 `send`:回答文本进 `input.text`,同时以结构化形式逐条进 `input.responses`——命中请求选项的回答带 `{ requestId, optionId }`,自由文本回答带 `{ requestId, text }`,adapter 不用解析文本,按 `requestId` 就能对上"哪个回答给哪个请求"。每种回答到 adapter 长什么样,见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)。
 
 如果当前轮有多个同类待处理请求、都该给同一个答案(比如逐个批准一批文件改动),用 `t.respondAll(optionId)` 一次性处理,不用挨个解。`optionId` 会先对每条待处理请求校验——不在请求的 `options` 里就直接抛错,打错的字不会被静默当成别的答案发出去：
 
@@ -112,7 +112,7 @@ t.succeeded();
 
 ## 相关阅读
 
-- [HITL](/zh/concepts/hitl) — 停轮等人的完整概念：握手时序与两侧义务。
-- [Assert](/zh/concepts/assert) — 从 `Turn.events` 和 `Turn.data` 上读的断言词汇。
-- [Judge](/zh/concepts/judge) — `t.judge` / `session.judge` / `turn.judge` 各自默认评什么材料。
-- [Adapter](/zh/concepts/adapter) — 能力从哪来:什么解锁 `t.newSession()`、HITL 和工具相关断言。
+- [HITL](/zh/explanation/hitl) — 停轮等人的完整概念：握手时序与两侧义务。
+- [Assert](/zh/explanation/assert) — 从 `Turn.events` 和 `Turn.data` 上读的断言词汇。
+- [Judge](/zh/explanation/judge) — `t.judge` / `session.judge` / `turn.judge` 各自默认评什么材料。
+- [Adapter](/zh/explanation/adapter) — 能力从哪来:什么解锁 `t.newSession()`、HITL 和工具相关断言。

package/docs-site/zh/{concepts → explanation}/evals.mdx

@@ -89,7 +89,7 @@ npx niceeval exp local weather/brooklyn
 
 ## gate 与 soft
 
-`gate` 是硬门槛，失败会让 eval 失败；`soft` 参与打分，但不一定让 eval 失败。完整规则见 [Assert](/zh/concepts/assert)。
+`gate` 是硬门槛，失败会让 eval 失败；`soft` 参与打分，但不一定让 eval 失败。完整规则见 [Assert](/zh/explanation/assert)。
 
 ## `*.eval.ts` 约定
 
@@ -117,9 +117,9 @@ export default rows.map((row) =>
 );
 ```
 
-生成 ID 类似 `sql/0000`、`sql/0001`。详见 [数据驱动测试](/zh/guides/dataset-fanout)。
+生成 ID 类似 `sql/0000`、`sql/0001`。详见 [数据驱动测试](/zh/how-to/dataset-fanout)。
 
 ## 相关阅读
 
-- [实验](/zh/concepts/experiment) — 另一半：评谁、怎么跑；为什么和 eval 分开（晚绑定）。
-- [Assert](/zh/concepts/assert) — gate 与 soft 的完整判定规则。
+- [实验](/zh/explanation/experiment) — 另一半：评谁、怎么跑；为什么和 eval 分开（晚绑定）。
+- [Assert](/zh/explanation/assert) — gate 与 soft 的完整判定规则。

package/docs-site/zh/{concepts → explanation}/experiment.mdx

@@ -22,18 +22,18 @@ export default defineExperiment({
 ```
 
 - `agent`：评谁。放的是已经配置好的实例——被测系统的 URL、鉴权传给 Adapter 工厂，不进 experiment 的其它字段。
-- `model` / `flags`：透传语义。[NiceEval](https://niceeval.com/) 不解释它们的含义，原样经 `ctx` 递给 Adapter，由 Adapter 随请求转发、应用按需切换——这正是 [Tier](/zh/concepts/tier) 里模型对比（Tier 1）和 feature A/B（Tier 3）的通道。
-- `runs`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[写实验](/zh/guides/write-experiment)。
+- `model` / `flags`：透传语义。[NiceEval](https://niceeval.com/) 不解释它们的含义，原样经 `ctx` 递给 Adapter，由 Adapter 随请求转发、应用按需切换——这正是 [Tier](/zh/explanation/tier) 里模型对比（Tier 1）和 feature A/B（Tier 3）的通道。
+- `runs`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[写实验](/zh/how-to/write-experiment)。
 
-Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [沙箱 provider · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
 
 ## 矩阵对比
 
-要比较的每个变体写一个 experiment 文件：两个模型就是两个文件，只差 `model` 一行；prompt A/B 就是只差一个参数。同一批 eval 在多个 experiment 下各跑一遍，pass rate、成本、延迟就有了可比的横截面——`niceeval view` 里叠着看。适合比什么、结果怎么读，见[实验矩阵](/zh/guides/experiments)。
+要比较的每个变体写一个 experiment 文件：两个模型就是两个文件，只差 `model` 一行；prompt A/B 就是只差一个参数。同一批 eval 在多个 experiment 下各跑一遍，pass rate、成本、延迟就有了可比的横截面——`niceeval view` 里叠着看。适合比什么、结果怎么读，见[实验矩阵](/zh/how-to/experiments)。
 
 ## 相关阅读
 
-- [写实验](/zh/guides/write-experiment) — `defineExperiment` 的完整字段：runs、预算、并发与 sandbox。
-- [实验矩阵](/zh/guides/experiments) — 跨 agent / model / flags 的对比怎么组织、怎么读结果。
-- [评估](/zh/concepts/evals) — 另一半：eval 是什么、生命周期与 verdict。
-- [Tier](/zh/concepts/tier) — `model` / `flags` 各在哪一档生效。
+- [写实验](/zh/how-to/write-experiment) — `defineExperiment` 的完整字段：runs、预算、并发与 sandbox。
+- [实验矩阵](/zh/how-to/experiments) — 跨 agent / model / flags 的对比怎么组织、怎么读结果。
+- [评估](/zh/explanation/evals) — 另一半：eval 是什么、生命周期与 verdict。
+- [Tier](/zh/explanation/tier) — `model` / `flags` 各在哪一档生效。

package/docs-site/zh/{concepts → explanation}/hitl.mdx

@@ -29,7 +29,7 @@ HITL（human-in-the-loop，人工介入）指 agent 在执行中间停下来，
 两个容易想歪的地方：
 
 - **回答轮不是新对话。** 它发生在同一条会话线上，`ctx.session` 还是同一个——Adapter 靠它找回上一轮挂起的现场。
-- **回答不用从文本里猜。** `input.responses` 逐请求带着 `{ requestId, optionId }`（自由文本回答则是 `{ requestId, text }`），命中选项的 `optionId` 在 eval 侧已校验过存在，打错的字直接抛错而不是静默传给应用。每种回答到 Adapter 长什么样，见[不同回答的入参](/zh/concepts/adapter#不同回答的入参)。
+- **回答不用从文本里猜。** `input.responses` 逐请求带着 `{ requestId, optionId }`（自由文本回答则是 `{ requestId, text }`），命中选项的 `optionId` 在 eval 侧已校验过存在，打错的字直接抛错而不是静默传给应用。每种回答到 Adapter 长什么样，见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)。
 
 ## eval 侧：三个动作
 
@@ -47,7 +47,7 @@ t.calledTool("send_email", { status: "completed" });
 - `t.requireInputRequest(filter)` 从待处理请求里精确取一个（按 `id` / `prompt` / `action` / `optionIds` 等字段匹配），匹配到 0 个或超过 1 个都会抛，多个请求并停时靠它消歧。
 - `t.respond(...)` 回答并发出下一轮；同类请求要给同一个答案时（比如逐个批准一批改动），`t.respondAll(optionId)` 一次处理完。
 
-批准和拒绝是同一扇门的两个分支，各写一条 eval 才算评完：批准后该发生的发生了，拒绝后该发生的没发生。逐个 API 的完整用法见 [Drive](/zh/concepts/drive#人工介入-hitl)。
+批准和拒绝是同一扇门的两个分支，各写一条 eval 才算评完：批准后该发生的发生了，拒绝后该发生的没发生。逐个 API 的完整用法见 [Drive](/zh/explanation/drive#人工介入-hitl)。
 
 ## Adapter 侧：两条义务，一次续跑
 
@@ -57,9 +57,9 @@ HITL 对 Adapter 的全部要求就三件事——前两件发生在停下的那
 2. **每个待回答的问题吐一条 `input.requested`**，`id` 稳定、字段尽量填全——eval 侧的检查和对位全靠它们；
 3. **下一次 `send` 先交裁决、再续跑**：从 `input.responses` 按 `requestId` 把裁决交回应用（不要按顺序猜），然后接着上一轮挂起的地方继续，而不是重发请求。
 
-"挂起的现场"（比如读了一半的 SSE 流）存在本会话线的 `ctx.session` 上——停轮时 `ctx.session.hold(现场)`，回答轮 `ctx.session.take()` 取回，取到即清除。怎么和流式驱动拼起来，见[写 send](/zh/guides/write-send#第五步：hitl) 第五步的完整骨架。
+"挂起的现场"（比如读了一半的 SSE 流）存在本会话线的 `ctx.session` 上——停轮时 `ctx.session.hold(现场)`，回答轮 `ctx.session.take()` 取回，取到即清除。怎么和流式驱动拼起来，见[写 send](/zh/how-to/write-send#第五步：hitl) 第五步的完整骨架。
 
-和 [NiceEval](https://niceeval.com/) 的其它能力一样，HITL 没有布尔声明：**做到了就是有**。send 返回过 `"waiting"` 并吐了 `input.requested`，`t.respond` 就能工作；没做到，eval 会在第一个 `parked()` 或 `requireInputRequest()` 上明确失败，而不是静默假通过。能力如何从构造中来，见 [Adapter](/zh/concepts/adapter#能力从哪来：构造证明，不是问卷)。
+和 [NiceEval](https://niceeval.com/) 的其它能力一样，HITL 没有布尔声明：**做到了就是有**。send 返回过 `"waiting"` 并吐了 `input.requested`，`t.respond` 就能工作；没做到，eval 会在第一个 `parked()` 或 `requireInputRequest()` 上明确失败，而不是静默假通过。能力如何从构造中来，见 [Adapter](/zh/explanation/adapter#能力从哪来：构造证明，不是问卷)。
 
 ## 拒绝不是故障
 
@@ -77,7 +77,7 @@ HITL 对 Adapter 的全部要求就三件事——前两件发生在停下的那
 
 ## 相关阅读
 
-- [Drive](/zh/concepts/drive#人工介入-hitl) — eval 侧的完整用法：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`。
-- [Adapter](/zh/concepts/adapter#不同回答的入参) — 回答到 Adapter 的结构化入参，四种典型形态。
-- [写 send](/zh/guides/write-send) — Adapter 侧实操：`ctx.session.hold` / `take` 与流式 + HITL 的完整骨架。
-- [接入你的 Agent](/zh/guides/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
+- [Drive](/zh/explanation/drive#人工介入-hitl) — eval 侧的完整用法：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`。
+- [Adapter](/zh/explanation/adapter#不同回答的入参) — 回答到 Adapter 的结构化入参，四种典型形态。
+- [写 send](/zh/how-to/write-send) — Adapter 侧实操：`ctx.session.hold` / `take` 与流式 + HITL 的完整骨架。
+- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。

package/docs-site/zh/{concepts → explanation}/judge.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "评判"
 description: "t.judge / session.judge / turn.judge 如何用独立裁判模型评估事实性、闭合式质量和摘要忠实度，以及模型解析优先级和严重度。"
 ---
 
-judge 断言是第五种评分机制，和 [Assert](/zh/concepts/assert) 里的四种并列。用在“对不对靠规则说不清”的地方——开放式行文、语气、事实一致性、摘要质量。裁判模型和被测 agent **完全分离**，避免自评：同一个模型给自己的输出打分，天然会打得偏高。
+judge 断言是第五种评分机制，和 [Assert](/zh/explanation/assert) 里的四种并列。用在“对不对靠规则说不清”的地方——开放式行文、语气、事实一致性、摘要质量。裁判模型和被测 agent **完全分离**，避免自评：同一个模型给自己的输出打分，天然会打得偏高。
 
 ```ts
 t.judge.autoevals.factuality(reference).atLeast(0.8);   // 与参考文本的事实一致性
@@ -113,7 +113,7 @@ defineConfig({
 
 ## 严重度：judge 默认 soft
 
-judge 调用和其它断言一样是评分函数，遵守 [Assert · gate 与 soft 严重度](/zh/concepts/assert#gate-与-soft-严重度) 同一套机制——只是**默认值**和大多数值匹配器不同：
+judge 调用和其它断言一样是评分函数，遵守 [Assert · gate 与 soft 严重度](/zh/explanation/assert#gate-与-soft-严重度) 同一套机制——只是**默认值**和大多数值匹配器不同：
 
 ```ts
 t.judge.autoevals.closedQA("语气是否礼貌?");              // 不带阈值 → soft，纯记分，永不让 eval 失败
@@ -125,6 +125,6 @@ t.judge.autoevals.closedQA("语气是否礼貌?").gate();       // 提升为 gat
 
 ## 相关阅读
 
-- [Assert](/zh/concepts/assert) — gate / soft 严重度的完整规则，以及 judge 分数最终折进的判定规则。
-- [Drive](/zh/concepts/drive) — `t.send()`、`t.newSession()`，以及 `t.judge` / `session.judge` / `turn.judge` 各自挂在哪个 handle 上。
-- [Evals](/zh/concepts/evals) — judge 分数如何折进 eval 生命周期和 verdict 类型。
+- [Assert](/zh/explanation/assert) — gate / soft 严重度的完整规则，以及 judge 分数最终折进的判定规则。
+- [Drive](/zh/explanation/drive) — `t.send()`、`t.newSession()`，以及 `t.judge` / `session.judge` / `turn.judge` 各自挂在哪个 handle 上。
+- [Evals](/zh/explanation/evals) — judge 分数如何折进 eval 生命周期和 verdict 类型。

package/docs-site/zh/{concepts → explanation}/overview.mdx

@@ -102,8 +102,8 @@ Subject under test / Sandbox Provider
 
 ## 相关阅读
 
-- [Evals](/zh/concepts/evals) — eval 是什么，以及生命周期细节。
-- [Adapter](/zh/concepts/adapter) — 如何写 adapter，并在 experiment 中引用它。
-- [Drive](/zh/concepts/drive) — `t.send()`、session 与 HITL：如何产出断言要读的 `Turn` 数据。
-- [Assert](/zh/concepts/assert) — 断言词汇和判定规则。
-- [Judge](/zh/concepts/judge) — LLM-as-judge，评开放式质量。
+- [Evals](/zh/explanation/evals) — eval 是什么，以及生命周期细节。
+- [Adapter](/zh/explanation/adapter) — 如何写 adapter，并在 experiment 中引用它。
+- [Drive](/zh/explanation/drive) — `t.send()`、session 与 HITL：如何产出断言要读的 `Turn` 数据。
+- [Assert](/zh/explanation/assert) — 断言词汇和判定规则。
+- [Judge](/zh/explanation/judge) — LLM-as-judge，评开放式质量。

package/docs-site/zh/{guides → explanation}/runner.mdx

@@ -78,7 +78,7 @@ Runner 在 Eval 完成后把结果交给 Reporters：
 - JUnit reporter 适合 CI。
 - Braintrust reporter 把一次运行作为实验上报，跨提交比较。
 
-挂载方式和 Braintrust 配置见 [Reporter 上报](./reporters)。
+挂载方式和 Braintrust 配置见 [Reporter 上报](/zh/how-to/reporters)。
 
 ## 输出目录
 

package/docs-site/zh/{concepts → explanation}/tier.mdx

@@ -20,7 +20,7 @@ description: "按「Adapter 接到哪里、额外拿到什么观测数据」接
 
 还是同一个 `send`、同一套事件映射，只是让应用把 OTel span 也发给 [NiceEval](https://niceeval.com/) 一份。应用已埋点（AI SDK telemetry、LangGraph、OpenLLMetry / OpenInference、自埋 gen_ai）就零改动；没埋点补的是一段通用 OTel 初始化——这属于可观测性建设，不是为 eval 定制的改造。
 
-这一档买到的是**观测**：`niceeval view` 的调用瀑布图——应用内部每次模型调用、每次工具执行、各自的耗时与 token，按轮铺成时间线。断言不受影响：span 只进瀑布图，不进事件流、不喂断言。走法见[OTel 接入](/zh/guides/connect-otel)。
+这一档买到的是**观测**：`niceeval view` 的调用瀑布图——应用内部每次模型调用、每次工具执行、各自的耗时与 token，按轮铺成时间线。断言不受影响：span 只进瀑布图，不进事件流、不喂断言。走法见[OTel 接入](/zh/how-to/connect-otel)。
 
 ## Tier 3：侵入改造 + experiment flags
 
@@ -34,11 +34,11 @@ description: "按「Adapter 接到哪里、额外拿到什么观测数据」接
 
 ## 怎么升级
 
-三级递进不互斥：先用 Tier 1 跑通基线和模型对比；要调用瀑布图，升 Tier 2；要对照应用内部变体，再升 Tier 3。每次升级都只是给 Adapter 或应用加东西，experiment 侧怎么组织对比见[实验](/zh/concepts/experiment)。
+三级递进不互斥：先用 Tier 1 跑通基线和模型对比；要调用瀑布图，升 Tier 2；要对照应用内部变体，再升 Tier 3。每次升级都只是给 Adapter 或应用加东西，experiment 侧怎么组织对比见[实验](/zh/explanation/experiment)。
 
 ## 相关阅读
 
-- [接入你的 Agent](/zh/guides/connect-your-agent) — 接入全景：最小接入与参数通道。
-- [Adapter](/zh/concepts/adapter) — 契约本身：`send` 传入什么返回什么，`ctx.model` / `ctx.telemetry` / `ctx.flags` 按档位出现。
-- [OTel 接入](/zh/guides/connect-otel) — Tier 2 的完整走法。
-- [实验](/zh/concepts/experiment) — model / flags 对比在 experiment 侧怎么声明。
+- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入与参数通道。
+- [Adapter](/zh/explanation/adapter) — 契约本身：`send` 传入什么返回什么，`ctx.model` / `ctx.telemetry` / `ctx.flags` 按档位出现。
+- [OTel 接入](/zh/how-to/connect-otel) — Tier 2 的完整走法。
+- [实验](/zh/explanation/experiment) — model / flags 对比在 experiment 侧怎么声明。

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

@@ -24,12 +24,12 @@ AI 通常按任务选择这些入口：
 
 | 任务 | 随包文档 |
 | --- | --- |
-| 初始化项目 | `docs-site/zh/quickstart.mdx` |
-| 编写 Eval | `docs-site/zh/concepts/evals.mdx` |
-| 定义实验 | `docs-site/zh/guides/write-experiment.mdx` |
-| 连接被测 Agent | `docs-site/zh/concepts/adapter.mdx` |
-| 配置 Sandbox | `docs-site/zh/guides/sandbox-agent.mdx` |
-| 解释运行结果 | `docs-site/zh/guides/viewing-results.mdx` |
+| 初始化项目 | `docs-site/zh/tutorials/quickstart.mdx` |
+| 编写 Eval | `docs-site/zh/explanation/evals.mdx` |
+| 定义实验 | `docs-site/zh/how-to/write-experiment.mdx` |
+| 连接被测 Agent | `docs-site/zh/explanation/adapter.mdx` |
+| 配置 Sandbox | `docs-site/zh/how-to/sandbox-agent.mdx` |
+| 解释运行结果 | `docs-site/zh/how-to/viewing-results.mdx` |
 
 ## 用 bash 完成一次反馈闭环
 
@@ -280,4 +280,4 @@ Eval，还是实验环境。修改后用 --force 重跑对应 Eval，比较新
 
 真实 Agent 的运行可能产生费用。实验阶段可以加 `--budget <美元>` 限制本轮累计成本；预算只能限制单次命令，不能替代上面的停止条件。
 
-人与 AI 随时可以接手同一轮工作。AI 用 `niceeval show` 读取的结果，也能由人运行 `npx niceeval view` 在网页中查看。两者读取同一批 artifact；完整的输出格式、历史选择和网页操作见[查看结果](/zh/guides/viewing-results)。
+人与 AI 随时可以接手同一轮工作。AI 用 `niceeval show` 读取的结果，也能由人运行 `npx niceeval view` 在网页中查看。两者读取同一批 artifact；完整的输出格式、历史选择和网页操作见[查看结果](/zh/how-to/viewing-results)。

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

@@ -91,7 +91,7 @@ export default rows.map((row) =>
 );
 ```
 
-生成 ID 为 `sql/0000`、`sql/0001` 等。详见 [数据驱动测试](/zh/guides/dataset-fanout)。
+生成 ID 为 `sql/0000`、`sql/0001` 等。详见 [数据驱动测试](/zh/how-to/dataset-fanout)。
 
 ## Sandbox workspace
 
@@ -110,7 +110,7 @@ export default defineEval({
 });
 ```
 
-详见 [Fixtures](/zh/guides/fixtures)。
+详见 [Fixtures](/zh/how-to/fixtures)。
 
 ## 从 Eval 报告长步骤和诊断
 

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

@@ -4,11 +4,11 @@ sidebarTitle: "OTel 接入"
 description: "把应用已经在发的 OTel span 也发给 NiceEval 一份，niceeval view 里就有每轮的调用瀑布图。断言不从这里来——接好 send 那一刻断言就齐了。"
 ---
 
-先说清这条接入**不**改变什么：断言。`t.calledTool`、`t.maxTokens`、耗时这些判定的依据，全部来自你的 adapter 在 `send` 里返回的 `Turn`（`events` + `usage`）——接好 send 的那一刻，全套断言就齐了，和 OTel 没有关系（见[接入你的 agent](/zh/guides/connect-your-agent)）。
+先说清这条接入**不**改变什么：断言。`t.calledTool`、`t.maxTokens`、耗时这些判定的依据，全部来自你的 adapter 在 `send` 里返回的 `Turn`（`events` + `usage`）——接好 send 的那一刻，全套断言就齐了，和 OTel 没有关系（见[接入你的 agent](/zh/how-to/connect-your-agent)）。
 
 OTel 接入买到的是另一样东西：**`niceeval view` 里的调用瀑布图**。应用内部每次模型调用、每次工具执行、各自的耗时和 token，按轮铺开成一条时间线——失败的 eval 为什么失败、慢的轮次慢在哪一步，经常一眼就在瀑布图里。
 
-如果你的应用已经在发 OTel trace——AI SDK 的 telemetry、LangGraph 的 LangSmith 导出、OpenLLMetry / OpenInference 自动埋点，或自己按 GenAI 语义埋的点——那瀑布图的数据你已经在生产了：让应用把 span 也发给 [NiceEval](https://niceeval.com/) 一份即可，应用代码一行不改，仍是无侵入（见 [Tier](/zh/concepts/tier)）。
+如果你的应用已经在发 OTel trace——AI SDK 的 telemetry、LangGraph 的 LangSmith 导出、OpenLLMetry / OpenInference 自动埋点，或自己按 GenAI 语义埋的点——那瀑布图的数据你已经在生产了：让应用把 span 也发给 [NiceEval](https://niceeval.com/) 一份即可，应用代码一行不改，仍是无侵入（见 [Tier](/zh/explanation/tier)）。
 
 ## 原理（一段话）
 
@@ -197,12 +197,12 @@ export default defineAgent({
 
 ## 边界
 
-- **断言相关的一切都在 send**。想断工具调用，把它映射进 `events`（官方转换器或手写映射，见[写 send](/zh/guides/write-send)）；想断 usage，`send` 返回里带上。不存在"span 里有、events 里没有，于是断言看 span"的路径。
-- **多轮会话、HITL 不归 span 管**。span 没有"等人输入"语义，会话续接也是应用协议的事——这两样照常在 `send` 里做（会话续接见[写 send](/zh/guides/write-send)，HITL 概念见 [HITL](/zh/concepts/hitl)）。
+- **断言相关的一切都在 send**。想断工具调用，把它映射进 `events`（官方转换器或手写映射，见[写 send](/zh/how-to/write-send)）；想断 usage，`send` 返回里带上。不存在"span 里有、events 里没有，于是断言看 span"的路径。
+- **多轮会话、HITL 不归 span 管**。span 没有"等人输入"语义，会话续接也是应用协议的事——这两样照常在 `send` 里做（会话续接见[写 send](/zh/how-to/write-send)，HITL 概念见 [HITL](/zh/explanation/hitl)）。
 - **收不到 span 会有提示**。整个 run 0 span 通常是端点没接上（env 没注入、服务没重启），[NiceEval](https://niceeval.com/) 会在日志里提示；瀑布图为空，断言照常判。
 
 ## 相关阅读
 
-- [接入你的 agent](/zh/guides/connect-your-agent) —— 断言从哪来：send 的事件映射。
-- [写 send](/zh/guides/write-send) —— 手写 adapter 的完整教程，第六步就是本页的 adapter 侧接法。
+- [接入你的 agent](/zh/how-to/connect-your-agent) —— 断言从哪来：send 的事件映射。
+- [写 send](/zh/how-to/write-send) —— 手写 adapter 的完整教程，第六步就是本页的 adapter 侧接法。
 - [事件流参考](/zh/reference/events) —— 断言消费的事件长什么样。