niceeval 0.9.0 → 0.10.0

package/docs-site/images/logo-dark.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 64" role="img" aria-label="NiceEval">
+  <rect x="6" y="9" width="52" height="9" fill="#f5f5f1"/>
+  <rect x="6" y="26" width="30" height="9" fill="#f5f5f1"/>
+  <rect x="6" y="43" width="16" height="9" fill="#f5f5f1"/>
+  <polyline points="33 43, 42 52, 57 29" fill="none" stroke="#b9ff3d" stroke-width="9" stroke-linecap="square" stroke-linejoin="miter"/>
+  <text x="76" y="41" fill="#f5f5f1" font-family="Avenir Next, Segoe UI, Arial, sans-serif" font-size="30" font-weight="700">NiceEval</text>
+</svg>

package/docs-site/images/logo.svg

@@ -1,6 +1,7 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 56" role="img" aria-label="niceeval">
-  <rect width="56" height="56" rx="12" fill="#11161e"/>
-  <path d="M15 14h28v7H25v7h15v7H25v13H15z" fill="#f8fafc"/>
-  <path d="M31 35h14v7H31z" fill="#848c8e"/>
-  <text x="72" y="37" fill="#11161e" font-family="Inter, Arial, sans-serif" font-size="28" font-weight="700">niceeval</text>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 64" role="img" aria-label="NiceEval">
+  <rect x="6" y="9" width="52" height="9" fill="#11161e"/>
+  <rect x="6" y="26" width="30" height="9" fill="#11161e"/>
+  <rect x="6" y="43" width="16" height="9" fill="#11161e"/>
+  <polyline points="33 43, 42 52, 57 29" fill="none" stroke="#b9ff3d" stroke-width="9" stroke-linecap="square" stroke-linejoin="miter"/>
+  <text x="76" y="41" fill="#11161e" font-family="Avenir Next, Segoe UI, Arial, sans-serif" font-size="30" font-weight="700">NiceEval</text>
 </svg>

package/docs-site/zh/README.md

@@ -2,26 +2,27 @@
 
 `zh/` 按读者此刻的需求组织，不按 NiceEval 的内部模块组织。判断一页放在哪里时，先问读者是在学习、完成任务、查事实、理解原理，还是修复问题。
 
-## 五个正文分区
+## 五种正文类型
 
 | 目录 | 页面类型 | 读者要什么 | 本站边界 |
 | --- | --- | --- | --- |
-| `tutorials/` | Tutorial | 跟着一条安全路径拿到第一次成功 | 当前只有 `quickstart.mdx`。不为凑齐目录增加第二条入门路径 |
-| `how-to/` | How-to | 完成一个现实任务 | 标题用任务表述；步骤、验证方式和失败后的下一步要清楚 |
+| `tutorials/` | Tutorial / How-to | 拿到第一次成功，或完成一个现实任务 | `quickstart.mdx` 负责最短成功路径；其余页面按具体任务组织，步骤、验证方式和失败后的下一步要清楚 |
 | `explanation/` | Explanation | 理解概念、边界和运行原理 | 不承担完整操作步骤或字段罗列 |
 | `reference/` | Technical Reference | 快速查准确、完整的事实 | API 签名、字段、类型和 CLI flags 以源码为权威来源 |
 | `troubleshooting/` | Troubleshooting | 从可见症状定位并修复问题 | 按症状组织，不按内部模块组织 |
 
 `index.mdx` 和 `introduction.mdx` 是站点入口，不硬归入正文类型。`examples/` 是独立资源入口，不属于 Diátaxis 的四种正文类型。
 
+Tutorial 和 How-to 都属于用户完成任务时阅读的教程，因此统一放进 `tutorials/`，并在导航中合并到 `Tutorials` 标签。`quickstart.mdx` 负责第一次成功，其余页面负责已有基础后的具体任务。目录合并不改变两种页面的写作边界，也不把 Reference 或 Explanation 内容混进教程。
+
 ## Examples 的收录标准
 
-`examples/` 只收录有真实可运行源码的项目。一个案例页只回答四件事：被测对象是什么、这个项目证明什么、源码在哪里、怎么运行。操作步骤的通用版本链接 How-to，字段和配置全集链接 Reference，不在案例页复制。
+`examples/` 只收录有真实可运行源码的项目。一个案例页只说明被测对象、验证目标、源码位置和运行方式。操作步骤的通用版本链接对应任务教程，字段和配置全集链接 Reference，不在案例页复制。
 
 - 接入前后能从仓库源码计算时，由生成器产出 diff 页面，不手抄代码。
 - 同一个可运行项目只保留一张案例页。Skill、Plugin 等相邻主题共享实验设计时合并，不复制两份近似正文。
 - 只有一个条目的 Showcase 不单独成页，真实项目直接列在 `examples/index.mdx`。
-- 没有可运行源码、只有片段或设想的内容不进 Examples。片段进入对应 How-to，未实现方向留在 Roadmap。
+- 没有可运行源码、只有片段或设想的内容不进 Examples。片段进入对应任务教程，未实现方向留在 Roadmap。
 
 ## Reference 的生成边界
 
@@ -38,7 +39,7 @@ Technical Reference 不等于整页都由生成器拼出来。页面仍可手写
 
 - `explanation/runner.mdx` 解释执行引擎如何发现、调度、缓存和产出结果，不是一步一任务的操作指南。
 - `reference/official-adapters.mdx`、`reference/report-components.mdx` 和 `reference/results-data.mdx` 用于查能力、组件或数据 API，不能留在 How-to。
-- `troubleshooting/debugging.mdx` 与 `troubleshooting/debug-sandbox.mdx` 从失败症状出发，目录独立，在导航中归入 How-to Guides。
-- `how-to/sandbox-providers.mdx` 目前保留在 How-to，因为主问题是选择并配置 Provider；若以后字段表继续增长，再拆出独立 Provider Reference。
+- `troubleshooting/debugging.mdx` 与 `troubleshooting/debug-sandbox.mdx` 从失败症状出发，目录独立，在导航中归入 `Tutorials` 标签下的“问题排查”。
+- `tutorials/sandbox-providers.mdx` 按 How-to 写，因为主任务是选择并配置 Provider；若以后字段表继续增长，再拆出独立 Provider Reference。
 
 新增或移动页面时，同时更新 `docs-site/docs.json` 和旧路径 redirect。校验命令以 [`../AGENTS.md`](../AGENTS.md) 为准。

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

@@ -19,11 +19,11 @@ description: "一个可运行的 AI SDK v6 Web Agent 评测项目，覆盖自写
 | --- | --- |
 | 被测应用 | 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 可以复用到不同模型和部署实例。
+Adapter 只负责连接和翻译。URL 与模型属于 Experiment；评估用例只描述交互与好结果。这个分层让同一批评估用例可以复用到不同模型和部署实例。
 
 ## 目录
 
@@ -58,6 +58,6 @@ pnpm exec niceeval view
 
 ## 继续阅读
 
-- [接入你的 Agent](/zh/how-to/connect-your-agent)：从最小 Adapter 开始接入自己的协议。
-- [如何写好 Send](/zh/how-to/write-send)：逐步补齐会话、工具、HITL 和 OTel。
-- [实验矩阵](/zh/how-to/experiments)：组织模型和配置对比。
+- [接入你的 Agent](/zh/tutorials/connect-your-agent)：从最小 Adapter 开始接入自己的协议。
+- [编写 Send](/zh/tutorials/write-send)：逐步补齐会话、工具、HITL 和 OTel。
+- [实验矩阵](/zh/tutorials/experiments)：组织模型和配置对比。

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

@@ -7,7 +7,7 @@ description: "用真实 Workspace、基线实验和自定义报告，评估 Skil
 这个案例把扩展内容作为 Experiment 变量，让同一个 Coding Agent 在同一批真实开发任务上运行，再比较任务成功率、成本、耗时和行为差异。
 
 - [查看完整源码](https://github.com/CorrectRoadH/coding-agent-skill)
-- [查看 Fixtures 指南](/zh/how-to/fixtures)
+- [查看 Fixtures 指南](/zh/tutorials/fixtures)
 
 ## 两组实验
 
@@ -20,7 +20,7 @@ Ponytail 这一组迁移自第三方 Plugin 的 Agentic Benchmark，但这个仓
 
 ## 实验设计
 
-每个 Arm 固定相同的模型、Sandbox、任务集、Runs 和预算，只改变注入内容。Eval 不读取“当前是哪个 Arm”，也不为实验组降低验收标准。
+每个 Arm 固定相同的模型、Sandbox、任务集、Runs 和预算，只改变注入内容。评估用例不读取“当前是哪个 Arm”，也不为某个对照配置降低验收标准。
 
 ```text
 coding-agent-skill/
@@ -51,7 +51,7 @@ pnpm exec niceeval view --report reports/benchmark.tsx
 
 ## 从这个案例复用什么
 
-- 用 Experiment 表达有扩展和无扩展的对照，不让 Eval 知道实验条件。
+- 用 Experiment 表达有扩展和无扩展的对照，不让评估用例知道实验条件。
 - Prompt 不泄露答案；验证阶段再检查测试、源码、Diff 和行为证据。
 - 把任务成功率作为主指标，把 Token、成本、耗时和行为作为解释指标。
-- [评分指南](/zh/how-to/scoring-guide) 负责选择 Gate、Soft 和 Judge；本页不复制评分 API。
+- [评分指南](/zh/tutorials/scoring-guide) 负责选择 Gate、Soft 和 Judge；本页不复制评分 API。

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

@@ -6,7 +6,7 @@ description: "按被测对象选择可运行的 NiceEval 示例：Agent Framewor
 
 这里的每个示例都有真实可运行源码。先按被测对象选择，不必从头依次阅读。
 
-如果你还没有跑通过第一条 Eval，先读 [Quickstart](/zh/tutorials/quickstart)。如果你已经知道要完成什么，直接进入对应的 [How-to Guides](/zh/how-to/connect-your-agent)。
+如果你还没有跑通过第一条评估用例，先读 [Quickstart](/zh/tutorials/quickstart)。已经明确任务时，直接进入对应的 [Tutorials](/zh/tutorials/connect-your-agent) 页面。
 
 ## 接入已有 Agent Framework
 
@@ -42,9 +42,9 @@ description: "按被测对象选择可运行的 NiceEval 示例：Agent Framewor
 - [查看在线报告](https://niceeval.com/showcase/memory)
 - [查看项目源码](https://github.com/CorrectRoadH/coding-agent-memory-evals)
 
-## 什么不放在 Examples
+## Examples 的收录边界
 
-- 单段 API 用法放进 How-to 或 Reference。
+- 单段 API 用法放进任务教程或 Reference。
 - 没有可运行源码的伪项目不收录。
 - Roadmap 和尚未实现的接入不收录。
 - 同一个项目不为 Skill、Plugin、Hook 等相邻叫法复制多张案例页。

package/docs-site/zh/examples/integrations/ai-sdk-v7.mdx

@@ -8,7 +8,7 @@ description: "一个 AI SDK v7 聊天应用，对着它的 HTTP 接口无侵入
 
 对比对象：
 
-- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/ai-sdk-v7](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/ai-sdk-v7) —— 普通的 AI SDK v7 聊天应用（HTTP 服务器 + React 聊天 UI），还没接任何 eval。
+- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/ai-sdk-v7](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/ai-sdk-v7) —— 普通的 AI SDK v7 聊天应用（HTTP 服务器 + React 聊天 UI），还没接任何评估用例。
 - **after**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/ai-sdk-v7](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/ai-sdk-v7) —— 同一个应用接入 NiceEval 之后的样子。
 
 **接入方式**：内置 **`uiMessageStreamAgent`**——AI SDK UI Message Stream 协议（`useChat`

package/docs-site/zh/examples/integrations/claude-sdk.mdx

@@ -1,20 +1,20 @@
 ---
 title: "Claude Agent SDK 如何非侵入式接入 NiceEval"
 sidebarTitle: "Claude Agent SDK 如何接入"
-description: "一个 Claude Agent SDK 助手后端，接入 NiceEval 前后的完整代码 diff：应用侧一行没改，全部新增在 eval 侧。"
+description: "一个 Claude Agent SDK 助手后端，接入 NiceEval 前后的完整代码 diff：应用侧一行没改，全部新增在评估用例侧。"
 ---
 
 {/* 本文件由 scripts/gen-diff-code.ts 生成（pnpm run gen:diff-code），不要手工编辑 */}
 
 对比对象：
 
-- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/claude-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/claude-sdk) —— 独立的 `@anthropic-ai/claude-agent-sdk` HTTP 服务，还没接任何 eval。
+- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/claude-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/claude-sdk) —— 独立的 `@anthropic-ai/claude-agent-sdk` HTTP 服务，还没接任何评估用例。
 - **after**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/claude-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/claude-sdk) —— 同一个应用接入 NiceEval 之后的样子。
 
 **接入方式**：官方转换器——Claude Agent SDK 原生 `SDKMessage` → 标准事件的映射是
 `fromClaudeSdkMessages`（`"niceeval/adapter"` 导出）的事，adapter 只剩传输粘合与
 HITL 停轮判定（`calculate` 经官方 `canUseTool` 回调门控）。应用由你自己按它的方式启动
-（`pnpm start`），eval 不代管进程。应用侧 `src/backend/*` 逐字节未变。
+（`pnpm start`），评估用例不代管进程。应用侧 `src/backend/*` 逐字节未变。
 
 接入的全部代码变更（生成时从两个目录实测统计）：
 

package/docs-site/zh/examples/integrations/codex-sdk.mdx

@@ -8,15 +8,15 @@ description: "一个 Codex SDK（目录里的编码 agent）后端，接入 Nice
 
 对比对象：
 
-- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/codex-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/codex-sdk) —— 独立的 `@openai/codex-sdk` HTTP 服务，还没接任何 eval。
+- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/codex-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/codex-sdk) —— 独立的 `@openai/codex-sdk` HTTP 服务，还没接任何评估用例。
 - **after**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/codex-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/codex-sdk) —— 同一个应用接入 NiceEval 之后的样子。
 
 **接入方式**：官方转换器——codex 原生 `ThreadEvent` → 标准事件的映射是
 `fromCodexThreadEvents`（`"niceeval/adapter"` 导出）的事：消息文本、工具项
 （`command_execution` / `mcp_tool_call` / `file_change` → 配对的 `action.*`）和
 `turn.completed` 的 usage 全部来自这条流，adapter 只剩传输粘合。没有 HITL
-（Codex SDK 不支持）。eval 测的是真实编码任务（在工作目录里写文件、跑命令），断言
-直接读磁盘验证。应用由你自己启动（`pnpm start`），eval 不代管进程。应用侧
+（Codex SDK 不支持）。评估用例测的是真实编码任务（在工作目录里写文件、跑命令），断言
+直接读磁盘验证。应用由你自己启动（`pnpm start`），评估用例不代管进程。应用侧
 `src/backend/*` 逐字节未变。要 OTel 瀑布图见 `tier2/`，feature A/B 见 `tier3/`。
 
 接入的全部代码变更（生成时从两个目录实测统计）：

package/docs-site/zh/examples/integrations/langgraph.mdx

@@ -8,18 +8,18 @@ description: "一个纯 Python LangGraph + LangSmith OTel 导出的应用，接
 
 对比对象：
 
-- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/langgraph](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/langgraph) —— 纯 Python 的 `create_agent`（LangChain 1.x / LangGraph）HTTP 服务，还没接任何 eval。
+- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/langgraph](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/langgraph) —— 纯 Python 的 `create_agent`（LangChain 1.x / LangGraph）HTTP 服务，还没接任何评估用例。
 - **after**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/langgraph](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/langgraph) —— 同一个应用接入 NiceEval 之后的样子。
 
 **接入方式**：手写帧映射——server.py 的自定义 JSON 帧逐帧翻成标准事件（`tool-input` →
 `action.called`、`tool-output` → `action.result`、`text-delta` 累积成 `message`、
 `tool-approval-request` → 停轮 + `input.requested`），HITL 停轮现场的存取走 `ctx.session`。
-被测应用是 Python，eval 侧是另起的独立 TS 项目，应用侧 `src/backend/*.py` 逐字节未变。
+被测应用是 Python，评估用例侧是另起的独立 TS 项目，应用侧 `src/backend/*.py` 逐字节未变。
 要 OTel 瀑布图见 `tier2/`，feature A/B 见 `tier3/`。
 
 接入的全部代码变更（生成时从两个目录实测统计）：
 
-<table className="gd-summary"><tbody><tr><th>{"类别"}</th><th>{"文件数"}</th><th>{"行数"}</th></tr><tr><td>{"eval 侧 TS 项目脚手架（必要：被测应用是 Python，全新文件）"}</td><td>{"3"}</td><td>{"+42"}</td></tr><tr><td>{"adapter（必要：传输粘合，协议映射在官方包里）"}</td><td>{"2"}</td><td>{"+182"}</td></tr><tr><td>{"evals 与 experiments（评测内容，按需增长）"}</td><td>{"6"}</td><td>{"+118"}</td></tr><tr className="gd-total"><td>{"合计"}</td><td>{"11"}</td><td>{"+342"}</td></tr></tbody></table>
+<table className="gd-summary"><tbody><tr><th>{"类别"}</th><th>{"文件数"}</th><th>{"行数"}</th></tr><tr><td>{"评估用例侧 TS 项目脚手架（必要：被测应用是 Python，全新文件）"}</td><td>{"3"}</td><td>{"+42"}</td></tr><tr><td>{"adapter（必要：传输粘合，协议映射在官方包里）"}</td><td>{"2"}</td><td>{"+182"}</td></tr><tr><td>{"evals 与 experiments（评测内容，按需增长）"}</td><td>{"6"}</td><td>{"+118"}</td></tr><tr className="gd-total"><td>{"合计"}</td><td>{"11"}</td><td>{"+342"}</td></tr></tbody></table>
 
 ## 文件清单
 

package/docs-site/zh/examples/integrations/pi-sdk.mdx

@@ -8,13 +8,13 @@ description: "一个 pi-agent-core(@earendil-works)助手后端，接入 NiceEva
 
 对比对象：
 
-- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/pi-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/pi-sdk) —— 独立的 `@earendil-works/pi-agent-core` HTTP 服务，还没接任何 eval。
+- **before**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/pi-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/pi-sdk) —— 独立的 `@earendil-works/pi-agent-core` HTTP 服务，还没接任何评估用例。
 - **after**：[https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/pi-sdk](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/pi-sdk) —— 同一个应用接入 NiceEval 之后的样子。
 
 **接入方式**：官方转换器——pi 原生 `AgentEvent` → 标准事件的映射是
 `fromPiAgentEvents`（`"niceeval/adapter"` 导出）的事，adapter 只剩传输粘合：
 应用在哪个 URL、审批打哪个端点（`calculate` 工具走 HITL 审批）。应用由你自己按它的
-方式启动（`pnpm start`），eval 不代管进程。应用侧 `src/backend/*` 逐字节未变。
+方式启动（`pnpm start`），评估用例不代管进程。应用侧 `src/backend/*` 逐字节未变。
 
 接入的全部代码变更（生成时从两个目录实测统计）：
 

package/docs-site/zh/explanation/adapter.mdx

@@ -4,18 +4,18 @@ sidebarTitle: "Adapter"
 description: "Adapter 是你写的适配器。本文讲清楚 send 函数传入什么返回什么、被测系统配置怎么传、三个接入等级，以及 t 上的能力从哪来。"
 ---
 
-在 [NiceEval](https://niceeval.com/) 里，`Adapter` 是连接运行器和被测系统的适配层。Adapter 需要实现 `send` 函数：把 `t.send()` 等 eval 侧动作发给你的应用，再把应用返回翻译成 [NiceEval](https://niceeval.com/) 的标准 `Turn`。
+在 [NiceEval](https://niceeval.com/) 里，`Adapter` 是连接运行器和被测系统的适配层。Adapter 需要实现 `send` 函数：把 `t.send()` 等评估侧动作发给你的应用，再把应用返回翻译成 [NiceEval](https://niceeval.com/) 的标准 `Turn`。
 
-后续阅读[写 send](/zh/how-to/write-send)
+后续阅读[写 send](/zh/tutorials/write-send)
 
 ## 适配器
 如果被测系统使用标准的 OpenAI Chat Completions 或 Responses 协议，可以直接用官方适配器。自己实现的前后端协议（HTTP、gRPC、WebSocket 都行）则写一个 Adapter：它知道怎么鉴权、怎么调用你的应用、怎么把返回翻译成标准事件流。
 
 一次 `t.send()` 的完整往返，穿过这条边界两次：
 
-![一次 t.send 的完整往返：eval 调用 t.send，运行器组装 TurnInput 与 ctx，adapter 调用你的应用并返回标准事件流 Turn。](/images/agent-turn-roundtrip-zh.svg)
+![一次 t.send 的完整往返：评估用例调用 t.send，运行器组装 TurnInput 与 ctx，adapter 调用你的应用并返回标准事件流 Turn。](/images/agent-turn-roundtrip-zh.svg)
 
-去程：eval 里的驱动动词（`t.send` / `t.sendFile` / `t.respond`）组装 `TurnInput` 和本会话线的 `ctx`，调一次 Adapter 的 `send`。
+去程：评估用例里的驱动动词（`t.send` / `t.sendFile` / `t.respond`）组装 `TurnInput` 和本会话线的 `ctx`，调一次 Adapter 的 `send`。
 
 回程：Adapter 把应用的原始返回翻译成 `Turn`——其中 `events` 是一个按发生顺序排列的事件对象数组（下文有实际值）
 
@@ -96,14 +96,14 @@ 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/explanation/tier)。
 
-eval 侧的驱动 API——`t.send()`、`t.sendFile()`、`t.newSession()`、HITL 的 `t.respond()` / `t.respondAll()`
+评估侧的驱动 API——`t.send()`、`t.sendFile()`、`t.newSession()`、HITL 的 `t.respond()` / `t.respondAll()`
 统一都是调用 Adapter 的 `send`。
 
-怎么收敛、send 里怎么接，见[写 send](/zh/how-to/write-send)。
+怎么收敛、send 里怎么接，见[写 send](/zh/tutorials/write-send)。
 
 ## send 函数
 
-不管 Adapter 连的是 HTTP 服务还是沙箱里的 CLI，暴露给运行器的接口完全一致：
+不管 Adapter 连的是 HTTP 服务还是 Sandbox 里的 CLI，暴露给运行器的接口完全一致：
 
 ```ts
 interface Agent {
@@ -119,7 +119,7 @@ interface Agent {
 `send` 是唯一要实现的函数。它的签名里只有三个类型，分开看。
 
 <Note>
-  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
+  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [Sandbox provider · 生命周期](/zh/tutorials/sandbox-providers#生命周期)。
 </Note>
 
 ### 传入：`TurnInput`
@@ -145,11 +145,11 @@ interface InputResponse {
 }
 ```
 
-eval 侧不管调的是 `t.send()`、`t.sendFile()` 还是 `t.respond()`，到 Adapter 时都是一次普通的 `send`，差别全在字段上：
+评估侧不管调的是 `t.send()`、`t.sendFile()` 还是 `t.respond()`，到 Adapter 时都是一次普通的 `send`，差别全在字段上：
 
 如果你的应用接口不收文件就忽略 `files`。
 
-| eval 侧 | `text` | `files` | `responses` | `outputSchema` |
+| 评估侧 | `text` | `files` | `responses` | `outputSchema` |
 |---|---|---|---|---|
 | `t.send(text)` | 发送文本 | — | — | 声明了 `output` 才有 |
 | `t.sendFile(path, text?)` | 附言（可为空串） | 有 | — | 同上 |
@@ -160,7 +160,7 @@ eval 侧不管调的是 `t.send()`、`t.sendFile()` 还是 `t.respond()`，到 A
 
 #### 不同回答的入参
 
-HITL 回答轮里，人的裁决以结构化形式随 `input.responses` 到达——Adapter 不需要解析 `text` 去猜哪句回答对应哪个请求、算不算批准。每条回答必带 `requestId`；`optionId` 和 `text` 二选一：回答命中请求 `options` 里的某个 id 就是 `optionId`（eval 侧已校验过存在，不会有打错的字静默传进来），否则整句作为自由文本落在 `text`。四种典型形态：
+HITL 回答轮里，人的裁决以结构化形式随 `input.responses` 到达——Adapter 不需要解析 `text` 去猜哪句回答对应哪个请求、算不算批准。每条回答必带 `requestId`；`optionId` 和 `text` 二选一：回答命中请求 `options` 里的某个 id 就是 `optionId`（评估侧已校验过存在，不会有打错的字静默传进来），否则整句作为自由文本落在 `text`。四种典型形态：
 
 ```ts
 // ① 单个待处理请求，回答命中选项（approve / deny 同理，只是 optionId 不同）
@@ -232,9 +232,9 @@ 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/how-to/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、沙箱快照 tag 按它分区），见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
+`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/tutorials/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的生命周期里按实验隔离跨 attempt 的状态（缓存目录名、Sandbox 快照 tag 按它分区），见 [Sandbox provider · 生命周期](/zh/tutorials/sandbox-providers#生命周期)。
 
-`session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（eval 的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器都在它上面，"第一轮"就是新会话线的自然形态——`id` 是 `undefined`、`history.get()` 是空数组，没有要判断的分支；`state` 是这些存取器之外的逃生舱，框架从不往里写数据。
+`session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（评估用例的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器都在它上面，"第一轮"就是新会话线的自然形态——`id` 是 `undefined`、`history.get()` 是空数组，没有要判断的分支；`state` 是这些存取器之外的逃生舱，框架从不往里写数据。
 
 ### 返回：`Turn`
 
@@ -257,9 +257,9 @@ 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/how-to/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/tutorials/write-send)。
 
-`data` 不是"随便放点什么"的口袋，它只有一条规则：**要什么，由 eval 在 send 上用 schema 声明；声明了才有 data，拿到手就是声明的类型。**
+`data` 不是"随便放点什么"的口袋，它只有一条规则：**要什么，由评估用例在 send 上用 schema 声明；声明了才有 data，拿到手就是声明的类型。**
 
 ```ts
 // eval 侧：output 声明既是给应用的要求，也是 turn.data 的类型来源
@@ -275,7 +275,7 @@ turn.data.amount;   // 类型是 number——不是 unknown，不用手动收窄
 
 `send` 一 return，Adapter 的工作就结束了——剩下全是运行器的事。四个字段各有明确去向：
 
-| Turn 字段 | 运行器拿它做什么 | eval 作者在哪感知到 |
+| Turn 字段 | 运行器拿它做什么 | 评估用例作者在哪感知到 |
 |---|---|---|
 | `events` | 追加进本会话线的事件流，`deriveRunFacts` 折叠成事实（`toolCalls`、`parked`、`messageCount`…）；最后一条 assistant `message` 同时更新 `t.reply` | 全部作用域断言：`t.calledTool()`、`t.messageIncludes()`…；`t.events` 可直接查 |
 | `status` | 记录本轮终态；`"waiting"` 时把本轮的 `input.requested` 收进待答列表 | `t.succeeded()` / `t.parked()`；`"waiting"` 之后用 `t.respond()` 接 |
@@ -302,8 +302,8 @@ turn.data.amount;   // 类型是 number——不是 unknown，不用手动收窄
 
 ## 相关阅读
 
-- [写 send](/zh/how-to/write-send) — 实操教程：从发一条消息到完整接入，七步递进，每步解锁一组断言。
-- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
-- [Drive](/zh/explanation/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
+- [写 send](/zh/tutorials/write-send) — 实操教程：从发一条消息到完整接入，七步递进，每步解锁一组断言。
+- [接入你的 Agent](/zh/tutorials/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
+- [Drive](/zh/explanation/drive) — 评估侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
 - [Assert](/zh/explanation/assert) — 标准事件流驱动的完整断言词汇。
 - [架构概览](/zh/explanation/overview) — 四层架构和边界。

package/docs-site/zh/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/explanation/judge)。
+断言把 agent 在一次评估用例里做的一切——每条消息、每次工具调用、每处文件改动、每一分 token——折叠成一个可解释的结果。[NiceEval](https://niceeval.com/) 提供四种互补的断言机制：有的立即检查一个值，有的在整轮跑完后评估整次运行，有的在 Sandbox 里跑测试，有的衡量效率。四种都产出同一种 `Assertion` 类型，都进同一套判定规则。第五种机制——让语言模型评判开放式质量——见 [Judge](/zh/explanation/judge)。
 
 ## 四种断言机制
 
@@ -16,7 +16,7 @@ description: "NiceEval 的断言词汇——值断言、作用域断言、test-a
     `t.succeeded()`、`t.calledTool()`、`t.messageIncludes()` 等在 `test(t)` 里注册，但在函数返回**之后**才对完整轮次数据统一评估，适合整次运行的事实。
   </Card>
   <Card title="3. Test-as-scoring" icon="flask">
-    在 sandbox eval 里，从 `test(t)` 跑项目测试、构建脚本或临时探针命令——适合代码任务，文件内容和构建结果就是事实标准。
+    在 Sandbox 型评估用例里，从 `test(t)` 跑项目测试、构建脚本或临时探针命令——适合代码任务，文件内容和构建结果就是事实标准。
   </Card>
   <Card title="4. 效率断言" icon="gauge">
     `t.maxTokens()` 和 `t.maxCost()` 把 token 用量和估算成本变成可评分的维度。答对了但烧掉十倍 token 的 agent，不该跟省着用的拿一样的分。
@@ -29,12 +29,12 @@ description: "NiceEval 的断言词汇——值断言、作用域断言、test-a
 
 <Tabs>
   <Tab title="gate">
-    gate 是硬性要求。一旦失败，整个 eval 立刻判为 `failed`——不管其它断言表现如何。适合必须为真的事实：“调用了正确的工具”“输出解析为合法 JSON”“没有 shell 命令报错”。
+    gate 是硬性要求。一旦失败，整个评估用例立刻判为 `failed`——不管其它断言表现如何。适合必须为真的事实：“调用了正确的工具”“输出解析为合法 JSON”“没有 shell 命令报错”。
 
     `niceeval/expect` 里大多数匹配器（`includes`、`equals`、`matches`、`satisfies`）默认 gate；`t.succeeded()`、`t.calledTool()` 这类作用域断言也默认 gate。
   </Tab>
   <Tab title="soft">
-    soft 是带数值阈值的质量分。分数低于阈值时，eval 变成 `passed` 而不是 `failed`——是质量回归的信号，但不算硬性破坏。soft 失败只在 `--strict` 下才算数。
+    soft 是带数值阈值的质量分。分数低于阈值时，评估用例变成 `passed` 而不是 `failed`——是质量回归的信号，但不算硬性破坏。soft 失败只在 `--strict` 下才算数。
 
     适合“好不好”而不是“对不对”的连续判断：相似度打分、LLM-as-judge 的事实性评分、想跟踪但不想拦 CI 的成本预算。
 
@@ -183,9 +183,9 @@ t.sandbox.noFailedShellCommands();
 
 作用域断言到处遵守同一条规则：**接收者决定作用域，不是断言名字决定作用域。** `t.*` 聚合这次 eval run 的全部轮次（含 `t.newSession()` 开的额外 session）；`session.*`（`t.newSession()` 的返回值）只看这一条 session；`turn.*`（`t.send()` 的返回值）只看这一轮自己。同一套词汇，不同接收者——各接收者是什么见 [Drive](/zh/explanation/drive)。
 
-## 3. Test-as-scoring（沙箱型 eval）
+## 3. Test-as-scoring（Sandbox 型评估用例）
 
-沙箱型代码 eval 里，在 `test(t)` 内跑验证命令，把结果记成断言：
+Sandbox 型代码评估用例里，在 `test(t)` 内跑验证命令，把结果记成断言：
 
 ```ts
 import { commandSucceeded, includes } from "niceeval/expect";
@@ -210,7 +210,7 @@ t.maxTokens(80_000).atLeast(0.7);     // soft 变体——照样跟踪，只有
 t.check(t.usage.outputTokens, satisfies((n) => n < 10_000, "not verbose"));
 ```
 
-`t.usage` 在 `test(t)` 里随处可用，暴露 `{ inputTokens, outputTokens, cacheReadTokens?, … }`。沙箱型 agent 的 token 数由 adapter 从 transcript 里抠出；远程 agent 直接在 `Turn.usage` 里返回。
+`t.usage` 在 `test(t)` 里随处可用，暴露 `{ inputTokens, outputTokens, cacheReadTokens?, … }`。Sandbox 型 agent 的 token 数由 adapter 从 transcript 里抠出；远程 agent 直接在 `Turn.usage` 里返回。
 
 ## 自定义评分器
 
@@ -240,5 +240,5 @@ t.check(t.reply, jsonValid());
 
 - [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 类型。
+- [写 send](/zh/tutorials/write-send) — 标准事件流如何产出，作用域断言依赖它什么。
+- [评估](/zh/explanation/evals) — 断言如何折进评估用例生命周期和 verdict 类型。

package/docs-site/zh/explanation/drive.mdx

@@ -40,7 +40,7 @@ adapter 返回后运行器立刻按声明校验：`data` 不匹配，本轮直
 
 ## 带文件的一轮 —— `t.sendFile()`
 
-`t.sendFile(path, text?)` 读一个本地文件(相对 eval 所在目录),按扩展名推断 MIME 类型,把它作为 data URL 附加到这一轮的输入里：
+`t.sendFile(path, text?)` 读一个本地文件(相对评估用例所在目录),按扩展名推断 MIME 类型,把它作为 data URL 附加到这一轮的输入里：
 
 ```ts
 const turn = await t.sendFile("fixtures/invoice.png", "这张发票的总额是多少?");
@@ -61,7 +61,7 @@ await t.send("好,发出去。");
 t.calledTool("send_email");
 ```
 
-多轮 `t.send()` 能不能真的续上上文，取决于 Adapter 的 `send` 是否接了 `ctx.session` 的会话续接存取器（`history()` 或 `id` + `capture()`）——没接时每轮各是一场新对话。怎么接见 [Adapter](/zh/explanation/adapter) 与[写 send](/zh/how-to/write-send)。
+多轮 `t.send()` 能不能真的续上上文，取决于 Adapter 的 `send` 是否接了 `ctx.session` 的会话续接存取器（`history()` 或 `id` + `capture()`）——没接时每轮各是一场新对话。怎么接见 [Adapter](/zh/explanation/adapter) 与[写 send](/zh/tutorials/write-send)。
 
 ## 独立会话 —— `t.newSession()`
 
@@ -78,12 +78,12 @@ t.check(fresh.reply, satisfies((r) => !r.includes("小明"), "没有记忆泄漏
 ```
 
 <Warning>
-常见错误是想当然认为 `t.newSession()` 天然保证隔离。运行器保证的只是新会话线的状态是空的——真正对应用开一条新对话是 adapter 的事。一个不看自己的会话状态、永远续接同一个底层上下文的 adapter,会让 `t.newSession()` 悄悄共享状态,且不会报错。写 adapter 时,先用上面这条 eval 验一下隔离,再信任它。
+常见错误是想当然认为 `t.newSession()` 天然保证隔离。运行器保证的只是新会话线的状态是空的——真正对应用开一条新对话是 adapter 的事。一个不看自己的会话状态、永远续接同一个底层上下文的 adapter,会让 `t.newSession()` 悄悄共享状态,且不会报错。写 adapter 时,先用上面这条评估用例验一下隔离,再信任它。
 </Warning>
 
 ## 人工介入(HITL)
 
-有些 agent 会在一轮执行中间停下来,等审批或缺失信息,而不是直接跑完。这时这一轮以 `status: "waiting"` 结束,并带一条或多条 `input.requested` 事件说明在等什么。完整的心智模型(握手时序、Adapter 侧义务、rejected 语义)见 [HITL](/zh/explanation/hitl),这里讲 eval 侧怎么用。
+有些 agent 会在一轮执行中间停下来,等审批或缺失信息,而不是直接跑完。这时这一轮以 `status: "waiting"` 结束,并带一条或多条 `input.requested` 事件说明在等什么。完整的心智模型(握手时序、Adapter 侧义务、rejected 语义)见 [HITL](/zh/explanation/hitl),这里讲评估侧怎么用。
 
 ```ts
 const draft = await t.send("拟一封跟进邮件,但先别发,等我确认。");

package/docs-site/zh/explanation/evals.mdx

@@ -1,12 +1,12 @@
 ---
-title: "NiceEval 中的 eval：生命周期、verdict 与文件"
+title: "NiceEval 中的评估用例：生命周期、verdict 与文件"
 sidebarTitle: "评估"
-description: "eval 是一个测试用例：描述和 test 函数，agent-neutral。了解 eval 如何被发现、调度、评分和报告。"
+description: "评估用例是一个测试用例：描述和 test 函数，agent-neutral。了解评估用例如何被发现、调度、评分和报告。"
 ---
 
 一个 eval 是一个可运行的测试用例。它通常由一个 `*.eval.ts` 文件导出，通过 `defineEval` 声明。
 
-## eval 的组成
+## 评估用例的组成
 
 ```ts
 import { defineEval } from "niceeval";
@@ -31,7 +31,7 @@ export default defineEval({
 | `environment` | 可选的环境需求 profile，由 sandbox spec 的 `environments` 表映射到具体预制环境 |
 | `test(t)` | 交互和断言逻辑 |
 
-eval 本身不声明用哪个 Agent——它默认保持 agent-neutral，同一个 eval 可以在不同 experiment 下跑不同 Agent。选哪个 Agent 是 experiment 的字段，不由 CLI 临时覆盖。
+评估用例本身不声明用哪个 Agent——它默认保持 agent-neutral，同一个评估用例可以在不同 experiment 下跑不同 Agent。选哪个 Agent 是 experiment 的字段，不由 CLI 临时覆盖。
 
 <Note>
   不要手写 `id` 或 `name`。[NiceEval](https://niceeval.com/) 从文件路径推导 ID。
@@ -84,7 +84,7 @@ npx niceeval exp local weather/brooklyn
     执行异常、超时或作者错误，本次执行无法形成可信结论。
   </Card>
   <Card title="skipped" icon="forward" color="#6b7280">
-    eval 主动跳过，通常通过 `t.skip(reason)`。
+    评估用例主动跳过，通常通过 `t.skip(reason)`。
   </Card>
 </CardGroup>
 
@@ -94,7 +94,7 @@ npx niceeval exp local weather/brooklyn
 
 ## `*.eval.ts` 约定
 
-只有以 `.eval.ts` 结尾的文件会被发现。用目录表达分组：
+只有以 `.eval.ts` 结尾的文件会被发现。目录只形成 ID 前缀：
 
 ```text
 evals/
@@ -118,9 +118,9 @@ export default rows.map((row) =>
 );
 ```
 
-生成 ID 类似 `sql/0000`、`sql/0001`。详见 [数据驱动测试](/zh/how-to/dataset-fanout)。
+生成 ID 类似 `sql/0000`、`sql/0001`。详见 [数据驱动测试](/zh/tutorials/dataset-fanout)。
 
 ## 相关阅读
 
-- [实验](/zh/explanation/experiment) — 另一半：评谁、怎么跑；为什么和 eval 分开（晚绑定）。
+- [实验](/zh/explanation/experiment) — 另一半：评谁、怎么跑；为什么和评估用例分开（晚绑定）。
 - [Assert](/zh/explanation/assert) — gate 与 soft 的完整判定规则。

package/docs-site/zh/explanation/experiment.mdx

@@ -1,7 +1,7 @@
 ---
 title: "实验（Experiment）：评谁、怎么跑"
 sidebarTitle: "实验"
-description: "Experiment 是可签入的运行配置：同一批 eval 对着哪个 agent、哪个模型、开哪些 flags、跑几次。eval 与 experiment 分开的原因——晚绑定，让同一份 eval 换着对象跑。"
+description: "Experiment 是可签入的运行配置：同一批评估用例对着哪个 agent、哪个模型、开哪些 flags、跑几次。评估用例与 experiment 分开的原因——晚绑定，让同一份评估用例换着对象跑。"
 ---
 
 **experiment** 对着哪个 agent、用哪个模型、开哪些 flags、跑几次。用于做 AB 测试、模型对比、feature 对比——`flags` 就是 A/B 测试里的 feature flag，一个 experiment 是一组 flag 取值。
@@ -23,19 +23,19 @@ export default defineExperiment({
 
 - `agent`：评谁。放的是已经配置好的实例——被测系统的 URL、鉴权传给 Adapter 工厂，不进 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)。
+- `runs`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[写实验](/zh/tutorials/write-experiment)。
 
-Experiment 是纯配置数据，没有 `setup` / `teardown` 这类生命周期字段。要按实验准备环境（装二进制、预热、跨 attempt 存取状态），挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
+Experiment 还有一对实验级 Hook `setup` / `teardown`：整个实验只跑一次，在你自己的机器上执行，用来起停所有 Attempt 共享的服务（比如一条到内网服务的隧道、一个实验专用的 mock server）——`setup` 在本实验第一个 Attempt 派发前执行，`teardown` 在全部 Attempt 收尾后执行（中断也执行），当且仅当 `setup` 的时点已经走到才触发。要按实验在 Sandbox 里准备环境（装二进制、预热、跨 attempt 存取状态），则挂在 `sandbox` 字段的 spec 上——`dockerSandbox()` 等工厂返回的对象可以链 `.setup()` / `.teardown()`。两者的边界与写法见[写实验 · 启动 Experiment 共享服务](/zh/tutorials/write-experiment#启动-experiment-共享服务)与[Sandbox provider · 生命周期](/zh/tutorials/sandbox-providers#生命周期)。
 
-同一实验里的 eval 需要不同预制环境时，eval 只声明 provider-neutral 的 `environment` profile；sandbox spec 的 `environments` 表再把 profile 映射到 Docker image、E2B template 或 Vercel sandbox snapshot。这样任务需求留在 eval，provider 产物留在 spec，一个实验仍覆盖全部 eval、对比不拆分。写法见[写实验 · 让不同 eval 使用不同预制环境](/zh/how-to/write-experiment#让不同-eval-使用不同预制环境)。
+同一实验里的评估用例需要不同预制环境时，评估用例只声明 provider-neutral 的 `environment` profile；sandbox spec 的 `environments` 表再把 profile 映射到 Docker image、E2B template 或 Vercel Sandbox snapshot。这样任务需求留在评估用例，provider 产物留在 spec，一个实验仍覆盖全部评估用例、对比不拆分。写法见[写实验 · 让不同评估用例使用不同预制环境](/zh/tutorials/write-experiment#让不同评估用例使用不同预制环境)。
 
 ## 矩阵对比
 
-要比较的每个变体写一个 experiment 文件：两个模型就是两个文件，只差 `model` 一行；prompt A/B 就是只差一个参数。同一批 eval 在多个 experiment 下各跑一遍，pass rate、成本、延迟就有了可比的横截面——`niceeval view` 里叠着看。适合比什么、结果怎么读，见[实验矩阵](/zh/how-to/experiments)。
+要比较的每个变体写一个 experiment 文件：两个模型就是两个文件，只差 `model` 一行；prompt A/B 就是只差一个参数。同一批 eval 在多个 experiment 下各跑一遍，pass rate、成本、延迟就有了可比的横截面——`niceeval view` 里叠着看。适合比什么、结果怎么读，见[实验矩阵](/zh/tutorials/experiments)。
 
 ## 相关阅读
 
-- [写实验](/zh/how-to/write-experiment) — `defineExperiment` 的完整字段：runs、预算、并发与 sandbox。
-- [实验矩阵](/zh/how-to/experiments) — 跨 agent / model / flags 的对比怎么组织、怎么读结果。
-- [评估](/zh/explanation/evals) — 另一半：eval 是什么、生命周期与 verdict。
+- [写实验](/zh/tutorials/write-experiment) — `defineExperiment` 的完整字段：runs、预算、并发与 sandbox。
+- [实验矩阵](/zh/tutorials/experiments) — 跨 agent / model / flags 的对比怎么组织、怎么读结果。
+- [评估](/zh/explanation/evals) — 另一半：评估用例是什么、生命周期与 verdict。
 - [Tier](/zh/explanation/tier) — `model` / `flags` 各在哪一档生效。