niceeval 0.9.1 → 0.10.0

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

@@ -12,7 +12,7 @@ HITL（human-in-the-loop，人工介入）指 agent 在执行中间停下来，
 - **Codex**：审批模式（suggest / auto-edit 等）决定哪些动作要先经人确认，本质是同一扇门。
 - **AI SDK 应用**：工具不带 `execute` 时，工具调用会浮到前端，由界面上的人确认后把结果交回（`addToolResult`），模型再继续——这是自研应用里最常见的审批门写法。
 
-对被测对象来说，这条"停下来等人"的分支和别的行为一样需要回归：批准后该发生的事发生了吗？拒绝后真的没做吗？问错了人、停错了地方呢？但 eval 是自动跑的，里面没有人。[NiceEval](https://niceeval.com/) 的做法是把"人"折叠成三个可编排的动作：看到 agent 停了（`t.parked()`）、检查它在等什么（`t.requireInputRequest()`）、替人回答（`t.respond()`）。批准、拒绝、补充信息，从此都是能写进 eval 的路径。
+对被测对象来说，这条"停下来等人"的分支和别的行为一样需要回归：批准后该发生的事发生了吗？拒绝后真的没做吗？问错了人、停错了地方呢？但评估用例是自动跑的，里面没有人。[NiceEval](https://niceeval.com/) 的做法是把"人"折叠成三个可编排的动作：看到 agent 停了（`t.parked()`）、检查它在等什么（`t.requireInputRequest()`）、替人回答（`t.respond()`）。批准、拒绝、补充信息，从此都是能写进评估用例的路径。
 
 ## 停轮如何表达：waiting + input.requested
 
@@ -29,9 +29,9 @@ HITL（human-in-the-loop，人工介入）指 agent 在执行中间停下来，
 两个容易想歪的地方：
 
 - **回答轮不是新对话。** 它发生在同一条会话线上，`ctx.session` 还是同一个——Adapter 靠它找回上一轮挂起的现场。
-- **回答不用从文本里猜。** `input.responses` 逐请求带着 `{ requestId, optionId }`（自由文本回答则是 `{ requestId, text }`），命中选项的 `optionId` 在 eval 侧已校验过存在，打错的字直接抛错而不是静默传给应用。每种回答到 Adapter 长什么样，见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)。
+- **回答不用从文本里猜。** `input.responses` 逐请求带着 `{ requestId, optionId }`（自由文本回答则是 `{ requestId, text }`），命中选项的 `optionId` 在评估侧已校验过存在，打错的字直接抛错而不是静默传给应用。每种回答到 Adapter 长什么样，见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)。
 
-## eval 侧：三个动作
+## 评估侧：三个动作
 
 ```ts
 const draft = await t.send("给老板发一封周报邮件。");
@@ -47,37 +47,37 @@ t.calledTool("send_email", { status: "completed" });
 - `t.requireInputRequest(filter)` 从待处理请求里精确取一个（按 `id` / `prompt` / `action` / `optionIds` 等字段匹配），匹配到 0 个或超过 1 个都会抛，多个请求并停时靠它消歧。
 - `t.respond(...)` 回答并发出下一轮；同类请求要给同一个答案时（比如逐个批准一批改动），`t.respondAll(optionId)` 一次处理完。
 
-批准和拒绝是同一扇门的两个分支，各写一条 eval 才算评完：批准后该发生的发生了，拒绝后该发生的没发生。逐个 API 的完整用法见 [Drive](/zh/explanation/drive#人工介入-hitl)。
+批准和拒绝是同一扇门的两个分支，各写一条评估用例才算评完：批准后该发生的发生了，拒绝后该发生的没发生。逐个 API 的完整用法见 [Drive](/zh/explanation/drive#人工介入-hitl)。
 
 ## Adapter 侧：两条义务，一次续跑
 
 HITL 对 Adapter 的全部要求就三件事——前两件发生在停下的那一轮，第三件发生在回答到达的下一轮：
 
 1. **停轮时如实返回 `status: "waiting"`**，不要把挂起报成 `"completed"`，否则 `parked()` 失效、`succeeded()` 假通过；
-2. **每个待回答的问题吐一条 `input.requested`**，`id` 稳定、字段尽量填全——eval 侧的检查和对位全靠它们；
+2. **每个待回答的问题吐一条 `input.requested`**，`id` 稳定、字段尽量填全——评估侧的检查和对位全靠它们；
 3. **下一次 `send` 先交裁决、再续跑**：从 `input.responses` 按 `requestId` 把裁决交回应用（不要按顺序猜），然后接着上一轮挂起的地方继续，而不是重发请求。
 
-"挂起的现场"（比如读了一半的 SSE 流）存在本会话线的 `ctx.session` 上——停轮时 `ctx.session.hold(现场)`，回答轮 `ctx.session.take()` 取回，取到即清除。怎么和流式驱动拼起来，见[写 send](/zh/how-to/write-send#第五步：hitl) 第五步的完整骨架。
+"挂起的现场"（比如读了一半的 SSE 流）存在本会话线的 `ctx.session` 上——停轮时 `ctx.session.hold(现场)`，回答轮 `ctx.session.take()` 取回，取到即清除。怎么和流式驱动拼起来，见[写 send](/zh/tutorials/write-send#第五步：hitl) 第五步的完整骨架。
 
 和 [NiceEval](https://niceeval.com/) 的其它能力一样，HITL 没有布尔声明：**做到了就是有**。send 返回过 `"waiting"` 并吐了 `input.requested`，`t.respond` 就能工作；没做到，eval 会在第一个 `parked()` 或 `requireInputRequest()` 上明确失败，而不是静默假通过。能力如何从构造中来，见 [Adapter](/zh/explanation/adapter#能力从哪来：构造证明，不是问卷)。
 
 ## 拒绝不是故障
 
-人否决和工具报错是两回事，事件流里用不同的 `status` 区分：被人拒绝的调用，`action.result` 的 `status` 是 `"rejected"` 而不是 `"failed"`。这样 `t.noFailedActions()` 不会被一次正当的人工否决误伤，而 `t.calledTool("deploy", { status: "rejected" })` 可以精确断言"发起了调用、被人拦下了"——这正是拒绝分支的 eval 要写的断言。
+人否决和工具报错是两回事，事件流里用不同的 `status` 区分：被人拒绝的调用，`action.result` 的 `status` 是 `"rejected"` 而不是 `"failed"`。这样 `t.noFailedActions()` 不会被一次正当的人工否决误伤，而 `t.calledTool("deploy", { status: "rejected" })` 可以精确断言"发起了调用、被人拦下了"——这正是拒绝分支的评估用例要写的断言。
 
 ## 哪些 agent 用不到 HITL
 
 不是每个 agent 都有这条分支，没有就整个跳过——Adapter 不用管 `waiting`，eval 里也不会出现 `t.respond`：
 
 - **每轮一口气跑完的 agent**：问答、检索、翻译这类单发即回的服务，执行中没有等人的环节。
-- **审批门被关掉的运行形态**：Claude Code、Codex 产品本身是 HITL 的，但作为被测对象在沙箱里通常全自动跑（跳过权限确认）——内置的 `claude-code` / `codex` / `bub` sandbox agent 就是这样，所以它们都不做 HITL。
-- **审批发生在执行循环之外**：比如工单系统里人工复核 agent 的产出。那是另一个系统的流程，不经过 `send`，eval 评不到也不该评。
+- **审批门被关掉的运行形态**：Claude Code、Codex 产品本身是 HITL 的，但作为被测对象在 Sandbox 里通常全自动跑（跳过权限确认）——内置的 `claude-code` / `codex` / `bub` sandbox agent 就是这样，所以它们都不做 HITL。
+- **审批发生在执行循环之外**：比如工单系统里人工复核 agent 的产出。那是另一个系统的流程，不经过 `send`，评估用例评不到也不该评。
 
-判断标准只有一条：**你的 agent 执行循环里存在"停下来等人、拿到回答再继续"的分支，而你想把批准和拒绝写进 eval。**
+判断标准只有一条：**你的 agent 执行循环里存在"停下来等人、拿到回答再继续"的分支，而你想把批准和拒绝写进评估用例。**
 
 ## 相关阅读
 
-- [Drive](/zh/explanation/drive#人工介入-hitl) — eval 侧的完整用法：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`。
+- [Drive](/zh/explanation/drive#人工介入-hitl) — 评估侧的完整用法：`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) — 接入全景：最小接入、参数通道与增量地图。
+- [写 send](/zh/tutorials/write-send) — Adapter 侧实操：`ctx.session.hold` / `take` 与流式 + HITL 的完整骨架。
+- [接入你的 Agent](/zh/tutorials/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。

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

@@ -33,7 +33,7 @@ session.judge.autoevals.closedQA("...")  // (t.newSession() 的返回值)默认
 turn.judge.autoevals.closedQA("...")     // (t.send() 的返回值)默认只评这一轮的 turn.message
 ```
 
-`t.judge` / `session.judge` 是 session 级，适合评整段对话的回答质量或跨轮一致性；`turn.judge` 是 turn 级，只看这一轮的消息——多轮 eval 里不同轮次需要不同评分标准时用它：
+`t.judge` / `session.judge` 是 session 级，适合评整段对话的回答质量或跨轮一致性；`turn.judge` 是 turn 级，只看这一轮的消息——多轮评估用例里不同轮次需要不同评分标准时用它：
 
 ```ts
 const turn1 = await t.send("这张图里有什么?");          // 第一轮:看图
@@ -47,7 +47,7 @@ t.judge.autoevals
 turn3.judge.autoevals.closedQA("这一轮是否回答了形状颜色?").gate();
 ```
 
-要评的不是对话本身——沙箱 diff、文件内容或其它材料——不管挂在哪个接收者上，都用 `{ on }` 显式传：
+要评的不是对话本身——Sandbox diff、文件内容或其它材料——不管挂在哪个接收者上，都用 `{ on }` 显式传：
 
 ```ts
 t.judge.autoevals.closedQA("生成的代码是否是地道的 TypeScript?", {
@@ -127,4 +127,4 @@ t.judge.autoevals.closedQA("语气是否礼貌?").gate();       // 提升为 gat
 
 - [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 类型。
+- [评估](/zh/explanation/evals) — judge 分数如何折进评估用例生命周期和 verdict 类型。

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

@@ -1,5 +1,5 @@
 ---
-title: "NiceEval 架构：evals、agents 与 sandboxes"
+title: "NiceEval 架构：评估用例、agents 与 sandboxes"
 sidebarTitle: "概览"
 description: "理解 NiceEval、Adapter 和 Sandbox Provider 如何配合，用统一 API 评估任意 AI Agent。"
 ---
@@ -21,7 +21,7 @@ Subject under test / Sandbox Provider
 ## NiceEval 负责什么
 
 <CardGroup cols={2}>
-  <Card title="Eval 发现" icon="magnifying-glass">
+  <Card title="评估用例发现" icon="magnifying-glass">
     发现 `*.eval.ts` 文件和 fixture 目录，并从路径推导稳定 ID。
   </Card>
   <Card title="并发调度" icon="timeline">
@@ -53,20 +53,20 @@ Subject under test / Sandbox Provider
 
 <Tabs>
   <Tab title="Docker">
-    本地容器 Provider，适合开发和 CI 中的 coding-agent eval。
+    本地容器 Provider，适合开发和 CI 中的 coding-agent 评估用例。
   </Tab>
   <Tab title="Vercel Sandbox">
     云端 Sandbox Provider，适合更强隔离或更大的运行资源。
   </Tab>
   <Tab title="第三方 Provider">
-    只要实现 `Sandbox` 接口，就可以接入其他沙箱服务。
+    只要实现 `Sandbox` 接口，就可以接入其他 Sandbox 服务。
   </Tab>
 </Tabs>
 
 ## 关键术语
 
 <AccordionGroup>
-  <Accordion title="Eval">
+  <Accordion title="评估用例">
     一个测试用例：描述和 `test(t)` 函数，agent-neutral——用哪个 Agent 由 experiment 决定。
   </Accordion>
   <Accordion title="Agent">
@@ -92,7 +92,7 @@ Subject under test / Sandbox Provider
 ## 端到端流程
 
 <Steps>
-  <Step title="Discovery">发现 eval 文件和 fixture。</Step>
+  <Step title="Discovery">发现评估用例文件和 fixture。</Step>
   <Step title="Scheduling">根据并发、缓存和 attempt 计划运行。</Step>
   <Step title="Agent send">调用 adapter，让被测对象产出 `Turn`。</Step>
   <Step title="Scoring">执行断言、judge 和测试。</Step>
@@ -102,7 +102,7 @@ Subject under test / Sandbox Provider
 
 ## 相关阅读
 
-- [Evals](/zh/explanation/evals) — eval 是什么，以及生命周期细节。
+- [评估](/zh/explanation/evals) — 评估用例是什么，以及生命周期细节。
 - [Adapter](/zh/explanation/adapter) — 如何写 adapter，并在 experiment 中引用它。
 - [Drive](/zh/explanation/drive) — `t.send()`、session 与 HITL：如何产出断言要读的 `Turn` 数据。
 - [Assert](/zh/explanation/assert) — 断言词汇和判定规则。

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

@@ -1,27 +1,27 @@
 ---
-title: "NiceEval runner 如何调度和执行 eval"
+title: "NiceEval runner 如何调度和执行评估用例"
 sidebarTitle: "运行器"
-description: "NiceEval runner 发现 eval，用有界并发调度，缓存结果，重试脆弱基础设施，并执行预算保护。"
+description: "NiceEval runner 发现评估用例，用有界并发调度，缓存结果，重试脆弱基础设施，并执行预算保护。"
 ---
 
-Runner 是把 eval 文件变成一次实际运行的执行引擎。它负责发现、过滤、调度、缓存、attempt、reporters 和 artifact 输出。
+Runner 是把评估用例文件变成一次实际运行的执行引擎。它负责发现、过滤、调度、缓存、attempt、reporters 和 artifact 输出。
 
 ## 发现
 
 runner 会读取 `evals/` 下的：
 
 - `*.eval.ts` 文件
-- 导出 eval 数组的数据集文件
+- 导出评估用例数组的数据集文件
 
 ```bash
 npx niceeval list
 ```
 
-`list` 只发现和打印 ID，不执行 eval。
+`list` 只发现和打印 ID，不执行评估用例。
 
 ## 过滤
 
-`exp` 命令中,实验名之后的位置参数是 eval ID 前缀：
+`exp` 命令中,实验名之后的位置参数是评估用例 ID 前缀：
 
 ```bash
 npx niceeval exp local
@@ -37,7 +37,7 @@ npx niceeval exp local fixtures/button
 npx niceeval exp local --max-concurrency 8
 ```
 
-远程 HTTP agent 可以用更高并发；本地 Docker sandbox 通常需要更低并发，避免 CPU、内存和磁盘竞争。
+远程 HTTP agent 可以用更高并发；本地 Docker Sandbox 通常需要更低并发，避免 CPU、内存和磁盘竞争。
 
 ## runs 与 early-exit
 
@@ -50,7 +50,7 @@ npx niceeval exp local fixtures/button --runs 5 --no-early-exit
 
 ## 缓存
 
-[NiceEval](https://niceeval.com/) 可以根据输入、配置和相关文件 fingerprint 跳过已判定为 `passed` 或 `failed` 的结果——两者都是判定确定的终态。`errored`（超时、沙箱异常等框架/环境层面的不确定失败）永远重试。缓存适合加速迭代，但如果你在调试非确定性行为，应该明确关闭（`--force`）或清理相关缓存。
+[NiceEval](https://niceeval.com/) 可以根据输入、配置和相关文件 fingerprint 跳过已判定为 `passed` 或 `failed` 的结果——两者都是判定确定的终态。`errored`（超时、Sandbox 异常等框架/环境层面的不确定失败）永远重试。缓存适合加速迭代，但如果你在调试非确定性行为，应该明确关闭（`--force`）或清理相关缓存。
 
 ## 超时和预算
 
@@ -58,7 +58,7 @@ npx niceeval exp local fixtures/button --runs 5 --no-early-exit
 npx niceeval exp local --timeout 300000 --budget 5
 ```
 
-超时保护单个 eval，预算保护整次运行成本。NiceEval 只有在 Attempt 已经发起 Agent Turn、却连续拿不到成本数据时，才提示预算无法执行。如果 Attempt 在 `sandbox.create` 或 setup 阶段就失败，Agent 尚未运行，CLI 只显示对应的结构化执行错误，不再追加容易误导排查方向的预算警告。
+超时保护单个评估用例，预算保护整次运行成本。NiceEval 只有在 Attempt 已经发起 Agent Turn、却连续拿不到成本数据时，才提示预算无法执行。如果 Attempt 在 `sandbox.create` 或 setup 阶段就失败，Agent 尚未运行，CLI 只显示对应的结构化执行错误，不再追加容易误导排查方向的预算警告。
 
 ## Reporter
 
@@ -72,13 +72,13 @@ npx niceeval exp local --output ci     # CI：单一有序 stdout 事件流
 
 省略时使用 `auto`：TTY 选择 Human，CI 环境选择 CI，其它非 TTY 选择 Agent。输出模型只改变反馈，不改变调度、判定或 artifact。
 
-Runner 在 Eval 完成后把结果交给 Reporters：
+Runner 在评估用例完成后把结果交给 Reporters：
 
 - JSON artifacts 用于后续分析。
 - JUnit reporter 适合 CI。
 - Braintrust reporter 把一次运行作为实验上报，跨提交比较。
 
-挂载方式和 Braintrust 配置见 [Reporter 上报](/zh/how-to/reporters)。
+挂载方式和 Braintrust 配置见 [Reporter 上报](/zh/tutorials/reporters)。
 
 ## 输出目录
 

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

@@ -4,7 +4,7 @@ sidebarTitle: "接入等级"
 description: "按「Adapter 接到哪里、额外拿到什么观测数据」接入分三级：Tier 1 只接 send，Tier 2 加 OTel，Tier 3 侵入改造暴露 experiment flags。每档买到什么、什么时候升级。"
 ---
 
-接入 [NiceEval](https://niceeval.com/) 不是全有或全无的一次性工程。按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三级——每一级在上一级之上加一种投入、换一组新能力，已写的 eval 全程复用，不用改。
+接入 [NiceEval](https://niceeval.com/) 不是全有或全无的一次性工程。按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三级——每一级在上一级之上加一种投入、换一组新能力，已写的评估用例全程复用，不用改。
 
 ![接入分三个 Tier：Tier 1 只接 send 应用零改动；Tier 2 加 OTel 换 niceeval view 的调用瀑布图；Tier 3 侵入改造把变体暴露成 flags 做 A/B。](/images/adapter-tiers-zh.svg)
 
@@ -18,9 +18,9 @@ description: "按「Adapter 接到哪里、额外拿到什么观测数据」接
 
 ## Tier 2：send + OTel
 
-还是同一个 `send`、同一套事件映射，只是让应用把 OTel span 也发给 [NiceEval](https://niceeval.com/) 一份。应用已埋点（AI SDK telemetry、LangGraph、OpenLLMetry / OpenInference、自埋 gen_ai）就零改动；没埋点补的是一段通用 OTel 初始化——这属于可观测性建设，不是为 eval 定制的改造。
+还是同一个 `send`、同一套事件映射，只是让应用把 OTel span 也发给 [NiceEval](https://niceeval.com/) 一份。应用已埋点（AI SDK telemetry、LangGraph、OpenLLMetry / OpenInference、自埋 gen_ai）就零改动；没埋点补的是一段通用 OTel 初始化——这属于可观测性建设，不是为评估用例定制的改造。
 
-这一档买到的是**观测**：`niceeval view` 的调用瀑布图——应用内部每次模型调用、每次工具执行、各自的耗时与 token，按轮铺成时间线。断言不受影响：span 只进瀑布图，不进事件流、不喂断言。走法见[OTel 接入](/zh/how-to/connect-otel)。
+这一档买到的是**观测**：`niceeval view` 的调用瀑布图——应用内部每次模型调用、每次工具执行、各自的耗时与 token，按轮铺成时间线。断言不受影响：span 只进瀑布图，不进事件流、不喂断言。走法见[OTel 接入](/zh/tutorials/connect-otel)。
 
 ## Tier 3：侵入改造 + experiment flags
 
@@ -30,7 +30,7 @@ description: "按「Adapter 接到哪里、额外拿到什么观测数据」接
 
 ## 无侵入是前两档的底线
 
-前两档都是**无侵入**的：应用由你按它自己的方式启动（`pnpm start`、部署在哪都行），eval 侧不 spawn 应用进程、不另开端口——Adapter 只对着**用户前端本来就在用的那个接口**（HTTP 端点、SSE 流）收发，连不上时报"先起应用"的明确错误。两档的区别只在观测数据：Tier 1 只有 `send` 返回的事件，Tier 2 多一份发给 [NiceEval](https://niceeval.com/) 的 span、瀑布图随之出现。
+前两档都是**无侵入**的：应用由你按它自己的方式启动（`pnpm start`、部署在哪都行），评估侧不 spawn 应用进程、不另开端口——Adapter 只对着**用户前端本来就在用的那个接口**（HTTP 端点、SSE 流）收发，连不上时报"先起应用"的明确错误。两档的区别只在观测数据：Tier 1 只有 `send` 返回的事件，Tier 2 多一份发给 [NiceEval](https://niceeval.com/) 的 span、瀑布图随之出现。
 
 ## 怎么升级
 
@@ -38,7 +38,7 @@ description: "按「Adapter 接到哪里、额外拿到什么观测数据」接
 
 ## 相关阅读
 
-- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入与参数通道。
+- [接入你的 Agent](/zh/tutorials/connect-your-agent) — 接入全景：最小接入与参数通道。
 - [Adapter](/zh/explanation/adapter) — 契约本身：`send` 传入什么返回什么，`ctx.model` / `ctx.telemetry` / `ctx.flags` 按档位出现。
-- [OTel 接入](/zh/how-to/connect-otel) — Tier 2 的完整走法。
+- [OTel 接入](/zh/tutorials/connect-otel) — Tier 2 的完整走法。
 - [实验](/zh/explanation/experiment) — model / flags 对比在 experiment 侧怎么声明。

package/docs-site/zh/index.mdx

@@ -1,22 +1,22 @@
 ---
 title: "NiceEval"
 sidebarTitle: "首页"
-description: "NiceEval 是一个渐进式、全功能、开发体验友好、Agent Native 的 AI agent eval 工具。"
+description: "NiceEval 是框架无关的 Agent-Native 评估框架与 Harness，为你的 AI 应用构建评估提供完整的闭环。"
 ---
 
 <div align="center">
 
 # NiceEval
 
-**渐进式、全功能、开发体验友好、Agent Native 的 AI agent eval 工具**
+**为你的 AI 应用打造的 Agent-Native 评估框架与 Harness**
 
 </div>
 
-[NiceEval](https://niceeval.com/) 是一个受 [eve](https://eve.dev) 启发的 agent-native eval 工具。它首先追求良好的开发体验：一个项目可以在 10 分钟左右接入，eval 文件足够直观，结果也足够容易读。
+[NiceEval](https://niceeval.com/) 是一个受 [eve](https://eve.dev) 启发的 Agent-Native 评估框架与 Harness：`defineEval` 负责写清楚测什么，Harness 负责连被测对象、跑、打分、出报告——两者合在一起，就是从写 Eval 到看结果、优化 Agent 的完整闭环。它首先追求良好的开发体验：一个项目可以在 10 分钟左右接入，评估用例文件足够直观，结果也足够容易读。
 
-它也足够通用：可以用来 eval 给 Claude Code / Codex 写的 coding-agent 插件、Hook 和 Skill，也可以 eval 你自己的 AI Agent 应用。无论你的应用基于 AI SDK、LangGraph、Pi，还是自研 agent loop，都可以通过 adapter 接入。
+它也框架无关、足够通用：可以用来评估给 Claude Code / Codex 写的 coding-agent 插件、Hook 和 Skill，也可以评估你自己的 AI Agent 应用。无论你的应用基于 AI SDK、LangGraph、Pi，还是自研 agent loop，都可以通过 Adapter 接入。
 
-eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告和结构化 artifacts，让你能查看 agent 的行为细节，调试失败原因，并持续优化 pass rate、成本和延迟。
+评估运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告和结构化 artifacts，让你能查看 agent 的行为细节，调试失败原因，并持续优化 pass rate、成本和延迟。
 
 <CardGroup cols={3}>
   <Card title="Agent Framework 接入" icon="code-branch" href="/zh/examples">
@@ -36,7 +36,7 @@ eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告
 
 ### 模式一：Sandbox
 
-跑 Codex、Claude Code 等需要 sandbox 的 coding agent：
+跑 Codex、Claude Code 等需要 Sandbox 的 coding agent：
 
 ```text
    evals/*.eval.ts
@@ -78,25 +78,25 @@ eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告
    └────────────────────────────┘
 ```
 
-- **[NiceEval](https://niceeval.com/) 核心** 负责发现 eval、调度运行、打分、生成报告与 artifacts。
+- **[NiceEval](https://niceeval.com/) 核心** 负责发现评估用例、调度运行、打分、生成报告与 artifacts。
 - **Agent 适配器** 是开放边界：你决定如何调用被测系统，以及如何把输出映射成标准事件流。
-- **Sandbox** 负责文件系统隔离：需要真实 workspace 的 coding agent 使用 Docker 或云端 sandbox；自有 Web Agent 可以直连，无需 Docker。
+- **Sandbox** 负责文件系统隔离：需要真实 workspace 的 coding agent 使用 Docker 或云端 Sandbox；自有 Web Agent 可以直连，无需 Docker。
 
 ## 核心概念一览
 
 | 概念 | 一句话 |
 |---|---|
-| [Eval](/zh/explanation/evals) | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
+| [评估用例](/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 不需要。 |
+| [Sandbox](/zh/tutorials/sandbox-providers) | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | [Tier](/zh/explanation/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
 完整术语表见[架构概览](/zh/explanation/overview)。
 
 ## 示例
 
-跑一条 eval 需要两个文件：eval 本身（测什么）和 experiment（跑哪个 agent）。CLI 不接受裸 eval id——`niceeval exp <experiment> <eval 前缀>` 里的 experiment 才决定「连哪个被测对象」。下面是一个直连 Web Agent 的真实场景（完整项目见仓库 `examples/zh/ai-sdk/`），验证 agent 遇到实时天气问题时会调用工具、并基于工具结果作答，而不是凭空编造：
+跑一条评估用例需要两个文件：评估用例本身（测什么）和 experiment（跑哪个 agent）。CLI 不接受裸评估用例 id——`niceeval exp <experiment> <eval 前缀>` 里的 experiment 才决定「连哪个被测对象」。下面是一个直连 Web Agent 的真实场景（完整项目见仓库 `examples/zh/ai-sdk/`），验证 agent 遇到实时天气问题时会调用工具、并基于工具结果作答，而不是凭空编造：
 
 ```ts
 // evals/weather-tool.eval.ts
@@ -138,7 +138,7 @@ npx niceeval show       # 终端读取结果，失败项可继续下钻
 npx niceeval view       # 网页交互浏览
 ```
 
-如果被测对象是需要隔离工作区的 coding agent（Codex、Claude Code 插件/Skill），evals 里改用 `t.sandbox.uploadDirectory()` 铺工作区、`t.sandbox.fileChanged()` / `t.sandbox.file()` 检查改了什么文件、`t.sandbox.runCommand()` 跑测试——参考独立仓库 [coding-agent-skill](https://github.com/CorrectRoadH/coding-agent-skill)。
+如果被测对象是需要隔离工作区的 coding agent（Codex、Claude Code 插件/Skill），评估用例里改用 `t.sandbox.uploadDirectory()` 铺工作区、`t.sandbox.fileChanged()` / `t.sandbox.file()` 检查改了什么文件、`t.sandbox.runCommand()` 跑测试——参考独立仓库 [coding-agent-skill](https://github.com/CorrectRoadH/coding-agent-skill)。
 
 ## 快速开始
 
@@ -164,13 +164,13 @@ READ https://niceeval.com/INIT.md and install niceeval for this repo.
 
 <AccordionGroup>
   <Accordion title="需要注册账号吗？">
-    不需要。跑 eval 和 `niceeval view` 看报告全在本地完成；只有被测对象本身是需要隔离工作区的 coding agent 时，才会用到 Docker 或 E2B 这类 sandbox provider。
+    不需要。跑评估用例和 `niceeval view` 看报告全在本地完成；只有被测对象本身是需要隔离工作区的 coding agent 时，才会用到 Docker 或 E2B 这类 Sandbox provider。
   </Accordion>
   <Accordion title="我的 Agent 不是用 TypeScript / JavaScript 写的，能接吗？">
     能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发；应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/explanation/adapter)。
   </Accordion>
   <Accordion title="能接到 CI 里吗？">
-    能，见 [CI 集成](/zh/how-to/ci-integration)。
+    能，见 [CI 集成](/zh/tutorials/ci-integration)。
   </Accordion>
 </AccordionGroup>
 

package/docs-site/zh/introduction.mdx

@@ -4,16 +4,13 @@ sidebarTitle: "介绍"
 description: "NiceEval 帮助团队衡量、评估并改进生产环境中的 AI：比较模型、迭代 Agent、发现回归、用真实数据持续改进。"
 ---
 
-[NiceEval](https://niceeval.com/) 是一个 Agent 评估工具，帮助团队衡量、评估并改进生产环境中的 AI。借助 NiceEval，团队可以比较模型、迭代 Agent、发现回归问题，并利用真实用户数据持续改进 AI 应用。它追求低心智负担的 DX：大多数项目都可以在 10 分钟左右接入，写出第一条 eval，并开始稳定地检查 agent 行为。
+[NiceEval](https://niceeval.com/) 是一个 Agent 评估工具，帮助团队衡量、评估并改进生产环境中的 AI。借助 NiceEval，团队可以比较模型、迭代 Agent、发现回归问题，并利用真实用户数据持续改进 AI 应用。
 
-NiceEval 以本地优先为核心：你的评估在你自己的环境中运行，不需要先开账号、连平台才能跑第一条 eval。当团队需要分享评估结果、做回归跟踪时，可以通过 Report 上报到 BrainTrust 等平台，或者自定义报告导出。
+NiceEval 以本地优先为核心：你的评估在你自己的环境中运行。当团队需要分享评估结果、做回归跟踪时，可以通过 Report 上报到 BrainTrust 等平台，或者自定义报告导出。
 
-它既能评估用于 Claude Code / Codex 的 Plugins、Hook 和 Skill，也能直接评你自己的 AI Agent 应用。无论你的 Agent 基于 AI SDK、LangGraph、Pi 还是自研 loop，都可以通过 Adapter 接入同一套评估体系。
-
-## 30 秒看懂 DX
-
-一个 eval 就是一个 TypeScript 文件：给 agent 发消息，断言它做对了什么。
+它既能评估用于 Claude Code / Codex 的 Plugins、Hook 和 Skill，也能直接评你自己的 AI Agent 应用。无论你的 Agent 基于 AI SDK、LangGraph、Pi 还是自研 Agent SDK，都可以通过 Adapter 接入同一套评估体系。
 
+## 构建评估用例
 ```ts
 // evals/eval-tool-call.eval.ts
 import { defineEval } from "niceeval";
@@ -43,14 +40,14 @@ export default defineEval({
 ```sh
 pnpm exec niceeval exp local eval-tool-call  # 用 local experiment 只跑 eval-tool-call
 pnpm exec niceeval show                      # 终端读取结果，适合人和 AI
-pnpm exec niceeval view                      # 在网页中浏览同一批 artifacts
+pnpm exec niceeval view                      # 在网页中浏览
 ```
 
 ## 为什么有了 DeepEval、LangFuse、BrainTrust 还需要 NiceEval
 
 NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「构建 Input 与 Expected Output」的模式，并不适合真实的 Agent 评估——现在的 Agent 要在多轮对话、多 agent 协作、工具调用、Skill 加载等细粒度场景下被检查，NiceEval 就是为这类场景设计的：断言直接落在工具调用、消息内容、结构化输出和用量上，而不是要求你先手工准备一份 golden 数据集。
 
-像 LangFuse、BrainTrust 这类工具更偏 tracing 和监控，对「写 eval、跑 eval、看结果」这条路径来说太重；NiceEval 从一开始就针对这条路径做了友好的开发体验。两者也不冲突：NiceEval 能与 LangFuse、BrainTrust 共存——可以用它们做 tracing，或者把评估结果上传到两者。
+像 LangFuse、BrainTrust 这类工具更偏 tracing 和监控，对「写评估用例、跑评估用例、看结果」这条路径来说太重；NiceEval 从一开始就针对这条路径做了友好的开发体验。两者也不冲突：NiceEval 能与 LangFuse、BrainTrust 共存——可以用它们做 tracing，或者把评估结果上传到两者。
 
 ## 你可以评什么
 
@@ -59,7 +56,7 @@ NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「
     把 Claude Code、Codex、bub 放进 Sandbox，给它任务，再用真实测试和文件断言验证结果。
   </Card>
   <Card title="你自己的 AI Agent 应用" icon="globe">
-    直连你的应用接口，断言回复、工具调用和结构化输出。
+    直连你的应用接口，断言回复、工具调用和结构化输出。通过 Flag 切换测试不同版本的 Prompt
   </Card>
 </CardGroup>
 
@@ -114,7 +111,7 @@ NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「
 
 | 概念 | 一句话 |
 |---|---|
-| Eval | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
+| 评估用例 | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
 | Experiment | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
 | Adapter | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
 | Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
@@ -125,17 +122,17 @@ NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「
 ## 从你的场景开始
 
 <CardGroup cols={3}>
-  <Card title="接入 Agent Framework" icon="code-branch" href="/zh/examples">
-    选择 AI SDK、Claude SDK、Codex SDK、pi-agent-core 或 LangGraph 的可运行接入示例。
+  <Card title="接入 Agent" icon="code-branch" href="/zh/tutorials/connect-your-agent">
+    连接你的 Agent，写一个 Adapter，把消息、工具调用和结构化输出翻译成标准事件流。
   </Card>
   <Card title="评估 Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
     用真实 Workspace 和对照实验衡量 Skill、提示词与 Plugin Benchmark 的效果。
   </Card>
-  <Card title="自写 Adapter" icon="robot" href="/zh/examples/ai-agent-application">
-    查看自定义 HTTP Agent 的工具调用、图片理解、多轮会话和模型对比。
+  <Card title="学习如何写评估用例与实验" icon="robot" href="/zh/tutorials/authoring">
+    了解如何写评估用例、断言、实验配置和报告。
   </Card>
 </CardGroup>
 
 ## 接下来读什么
 
-[快速开始](/zh/tutorials/quickstart) 会带你安装 [NiceEval](https://niceeval.com/)、构建 eval、得到评估报告。
+[快速开始](/zh/tutorials/quickstart) 会带你安装 [NiceEval](https://niceeval.com/)、构建评估用例、得到评估报告。