niceeval 0.6.1 → 0.7.0

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()`，见 [Sandbox 后端 · 环境钩子](/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

@@ -1,10 +1,10 @@
 ---
 title: "NiceEval 架构：evals、agents 与 sandboxes"
 sidebarTitle: "概览"
-description: "理解 NiceEval、Adapter 和 Sandbox backend 如何配合，用统一 API 评估任意 AI agent。"
+description: "理解 NiceEval、Adapter 和 Sandbox Provider 如何配合，用统一 API 评估任意 AI Agent。"
 ---
 
-[NiceEval](https://niceeval.com/) 的核心设计是把“评测逻辑”与“如何连接被测对象”分开。[NiceEval](https://niceeval.com/) 负责发现、调度、评分和报告；Adapter 负责调用被测系统；Sandbox backend 负责隔离文件系统。
+[NiceEval](https://niceeval.com/) 的核心设计是把“评测逻辑”与“如何连接被测对象”分开。[NiceEval](https://niceeval.com/) 负责发现、调度、评分和报告；Adapter 负责调用被测系统；Sandbox Provider 负责隔离文件系统。
 
 ## 四层架构
 
@@ -15,7 +15,7 @@ NiceEval
         ↓
 Adapter
         ↓
-Subject under test / Sandbox backend
+Subject under test / Sandbox Provider
 ```
 
 ## NiceEval 负责什么
@@ -53,12 +53,12 @@ Subject under test / Sandbox backend
 
 <Tabs>
   <Tab title="Docker">
-    本地容器后端，适合开发和 CI 中的 coding-agent eval。
+    本地容器 Provider，适合开发和 CI 中的 coding-agent eval。
   </Tab>
   <Tab title="Vercel Sandbox">
-    云端 sandbox 后端，适合更强隔离或更大的运行资源。
+    云端 Sandbox Provider，适合更强隔离或更大的运行资源。
   </Tab>
-  <Tab title="第三方后端">
+  <Tab title="第三方 Provider">
     只要实现 `Sandbox` 接口，就可以接入其他沙箱服务。
   </Tab>
 </Tabs>
@@ -102,8 +102,8 @@ Subject under test / Sandbox backend
 
 ## 相关阅读
 
-- [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

@@ -42,10 +42,11 @@ npx niceeval exp local --max-concurrency 8
 ## runs 与 early-exit
 
 ```bash
-npx niceeval exp local fixtures/button --runs 5 --early-exit
+npx niceeval exp local fixtures/button --runs 5
+npx niceeval exp local fixtures/button --runs 5 --no-early-exit
 ```
 
-`runs` 用于测 pass rate。`early-exit` 会在某个 attempt 通过后停止同一 eval 的剩余尝试。
+`runs` 用于测 pass rate。首过即停默认开启：某个 Attempt 通过后，同一 eval 的剩余 Attempt 会被停止。想拿完整的通过率分布时，用 `--no-early-exit` 关闭，让每个 eval 跑满 `runs` 次。
 
 ## 缓存
 
@@ -57,26 +58,35 @@ npx niceeval exp local fixtures/button --runs 5 --early-exit
 npx niceeval exp local --timeout 300000 --budget 5
 ```
 
-超时保护单个 eval，预算保护整次运行成本。
+超时保护单个 eval，预算保护整次运行成本。NiceEval 只有在 Attempt 已经发起 Agent Turn、却连续拿不到成本数据时，才提示预算无法执行。如果 Attempt 在 `sandbox.create` 或 setup 阶段就失败，Agent 尚未运行，CLI 只显示对应的结构化执行错误，不再追加容易误导排查方向的预算警告。
 
 ## Reporter
 
-runner 在 eval 完成后把结果交给 reporters：
+运行中的反馈由 `--output` 选择消费者模型；Reporter 负责把完成后的结果写到其它目的地。两者不是同一层：
+
+```bash
+npx niceeval exp local --output human  # 人：TTY dashboard + 永久错误/诊断
+npx niceeval exp local --output agent  # AI：稳定 envelope + locator handoff
+npx niceeval exp local --output ci     # CI：单一有序 stdout 事件流
+```
+
+省略时使用 `auto`：TTY 选择 Human，CI 环境选择 CI，其它非 TTY 选择 Agent。输出模型只改变反馈，不改变调度、判定或 artifact。
+
+Runner 在 Eval 完成后把结果交给 Reporters：
 
-- console reporter 提供实时反馈。
 - JSON artifacts 用于后续分析。
 - JUnit reporter 适合 CI。
 - Braintrust reporter 把一次运行作为实验上报，跨提交比较。
 
-挂载方式和 Braintrust 配置见 [Reporter 上报](./reporters)。
+挂载方式和 Braintrust 配置见 [Reporter 上报](/zh/how-to/reporters)。
 
 ## 输出目录
 
-每次运行会写入该实验的结果快照目录 `.niceeval/<experiment>/<快照>/`，包括快照级 `snapshot.json`，以及每个 attempt 的 `result.json`（判决与断言）和按需生成的 `events.json`、`sources.json`、`trace.json`、`o11y.json`、`diff.json` 等拆分 artifact。
+每次运行会写入该实验的结果快照目录 `.niceeval/<experiment>/<快照>/`，包括快照级 `snapshot.json`，以及每个 Attempt 的 `result.json`（判定、断言、结构化错误、diagnostics）和按需生成的 `events.json`、`sources.json`、`trace.json`、`o11y.json`、`diff.json` 等拆分 artifact。瞬时 progress 不落盘。
 
 ## 推荐调试流程
 
 1. 先跑 `npx niceeval list` 确认发现结果。
 2. 用 `npx niceeval exp <实验> <ID 前缀>` 缩小到一个 eval。
-3. 失败后运行 `npx niceeval view` 查看 transcript 和 diff。
+3. 失败后复制终端里的 locator，先运行 `npx niceeval show @<locator>` 看错误或断言摘要；需要 Agent 行为时再加 `--execution`，需要文件变化时加 `--diff`。
 4. 再扩大到完整 suite 或 experiment。

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 完成一次反馈闭环
 
@@ -38,7 +38,7 @@ AI 通常按任务选择这些入口：
 <Steps>
   <Step title="运行实验">
     ```bash
-    npx niceeval exp local
+    npx niceeval exp local --output agent
     ```
 
     先读取退出码：`0` 表示所有 Eval 通过；`1` 表示至少一个 Eval 失败或出错；`2` 表示 NiceEval 自身未能完成运行。退出码决定是否继续，控制台文本用于定位原因。
@@ -59,7 +59,7 @@ AI 通常按任务选择这些入口：
 
     `--execution` 合并 AI 输出与 trace：标准事件流提供消息、thinking、tool call/result 和 Skill load；OTel 在能够关联时给同一节点补开始时间、耗时、父子关系和错误状态。没有 OTel 时步骤仍完整，只不显示时间。
 
-    不带证据 flag 时，`show @<id>` 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行与文件变化摘要。AI 应该先读这一页；只有需要回答“为什么产生这个值”时，才继续打开对应证据。
+    不带证据 flag 时，`show @<id>` 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行、生命周期阶段耗时与文件变化摘要。AI 应该先读这一页；只有需要回答“为什么产生这个值”时，才继续打开对应证据。
 
     ```text
     $ niceeval show @1k2m9qtr
@@ -89,20 +89,16 @@ AI 通常按任务选择这些入口：
         source: evals/memory/swelancer-manager-proposals.eval.ts:40:11
 
     execution: 3 events · 0 skill loads · 0 tool calls · 1 AI messages
-    timing: OTel spans recorded for this attempt — see --execution for per-step timing.
-    agent run                     ▕████████████████████▏ 41.2s
-    ├─ inference                  ▕█████░░░░░░░░░░░░░░░▏ 10.1s · "布鲁克林今天大约 24°C，晴。"
-    ├─ inference                  ▕░░░░░█████████░░░░░░▏ 18.3s
-    └─ inference                  ▕░░░░░░░░░░░░░░██████▏ 12.4s
-    no tool calls
+    timing: eval.run 40.4s · scoring.evaluate 0.5s · teardown +0.2s
 
     changes · diff unavailable
     reason: this Attempt did not produce workspace file changes
 
-    full eval source: …/weather/brooklyn/a2/eval-source.ts
+    full eval source: …/weather/brooklyn/a2/sources.json
     available:
       niceeval show @1k2m9qtr --eval
       niceeval show @1k2m9qtr --execution
+      niceeval show @1k2m9qtr --timing
     ```
 
     `--execution` 把 AI 消息、Skill load、工具调用和工具结果排成一棵执行树。它只展示 Agent 可理解的事件；没有关联到这些事件的 SDK / runtime span 不逐行输出，只报告省略数量并保留 `trace.json` 路径。下面的 Attempt 有 OTel，所以能关联的节点同时带相对时间与耗时：
@@ -175,9 +171,10 @@ AI 通常按任务选择这些入口：
 
     | 要回答的问题 | 入口 | 输出必须包含 |
     | --- | --- | --- |
-    | 快速判断一次 Attempt 发生了什么 | `niceeval show @<id>` | Eval 断言、执行步骤、可选 OTel 时间、diff 摘要及各块可用性 |
+    | 快速判断一次 Attempt 发生了什么 | `niceeval show @<id>` | Eval 断言、执行步骤、生命周期阶段耗时摘要、diff 摘要及各块可用性 |
     | Eval 实际检查了什么，哪条 gate / soft 为什么通过或失败 | `niceeval show @<id> --eval` | 运行时 Eval 源码、源码哈希、断言所在行、严重度、分数与原因 |
-    | AI 做了什么、调用了什么、时间花在哪里 | `niceeval show @<id> --execution` | 消息、thinking、Skill load、工具调用与结果；有 OTel 时在同一节点显示时间、父子关系和错误状态 |
+    | AI 做了什么、调用了什么 | `niceeval show @<id> --execution` | 消息、thinking、Skill load、工具调用与结果；有 OTel 时在同一节点附时间、父子关系和错误状态 |
+    | 整个 Attempt 的时间花在哪里 | `niceeval show @<id> --timing` | lifecycle → hook/turn → shell → OTel 的统一时间树；出错的 Attempt 标出已知的最深失败节点 |
     | Sandbox 工作区文件变成什么 | `niceeval show @<id> --diff` | 文件摘要、增删行数、具体补丁和原始 diff 路径；无文件工作区时明确 unavailable |
   </Step>
   <Step title="提出假设并修改">
@@ -195,7 +192,7 @@ AI 通常按任务选择这些入口：
   </Step>
   <Step title="局部重跑并验证假设">
     ```bash
-    npx niceeval exp local weather/brooklyn --force
+    npx niceeval exp local weather/brooklyn --output agent --force
     npx niceeval show weather/brooklyn
     ```
 
@@ -203,7 +200,7 @@ AI 通常按任务选择这些入口：
   </Step>
   <Step title="全量确认没有回归">
     ```bash
-    npx niceeval exp local --force
+    npx niceeval exp local --output agent --force
     npx niceeval show
     ```
 
@@ -213,19 +210,22 @@ AI 通常按任务选择这些入口：
 
 ## AI 应该从输出里读什么
 
-`exp` 运行结束后会给出三类信息：失败摘要、结果统计和结果快照目录。典型输出如下：
+`--output agent` 运行中只向 stderr 追加低频 checkpoint（存活信号，不是结果数据源），结束时向 stdout 打印一个有界 handoff block——这才是 AI 应该解析的部分：
 
 ```text
-Failing:
-  ✗ weather/brooklyn · @1k2m9qtr
-      gate calledTool("get_weather"): tool was never called
-
-Results: 14 passed, 1 failed, 0 errored, 0 skipped
-Structured results: .niceeval/local/2026-07-09T10-00-00-000Z-x1f2/
-  (snapshot.json + 每 attempt 的 result.json / events.json / trace.json / diff.json)
+NICEEVAL RESULT failed
+summary: 14 passed, 1 failed, 0 errored (0 reused)
+snapshots:
+  - .niceeval/local/2026-07-09T10-00-00-000Z-x1f2/
+failures:
+  - @1k2m9qtr weather/brooklyn [local]
+    gate: tool was never called
+next:
+  niceeval show @1k2m9qtr
+  niceeval show @1k2m9qtr --execution
 ```
 
-AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval show @<id>` 或对应证据 flag，不要从头解析运行期间不断刷新的进度行。需要机器读取时，结果快照是事实来源：
+AI 应先从 `failures` 选中 Attempt locator，再按证据位执行 `next` 给出的 `niceeval show @<id>` 或对应证据 flag，不要解析运行期间 stderr 上低频追加的 checkpoint 行——那些只用于判断进程是否存活。失败条数超过上限（默认 5 条）时,handoff 只展开前几条并给出总数,完整清单读结果快照。需要机器读取时，结果快照是事实来源：
 
 ```text
 .niceeval/<experiment>/<快照>/
@@ -238,7 +238,7 @@ AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval sh
 ```
 
 - `snapshot.json` 记录实验身份、运行配置、格式版本和时间。
-- `result.json` 记录该 Attempt 的判定、断言、错误和用量。
+- `result.json` 记录该 Attempt 的判定、断言、结构化错误、diagnostics 和用量；瞬时 progress 不落盘。
 - `events.json` 是对话与工具调用事件，`trace.json` 是调用链，`diff.json` 是 Sandbox 文件变化。
 - 某类证据不存在时，对应文件不会生成。先以 `show` 的提示为准，不要假设每个目录都有全部文件。
 
@@ -268,14 +268,16 @@ AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval sh
 
 ```text
 读取 node_modules/niceeval/INDEX.md，再按索引读取与任务有关的文档。
-运行 npx niceeval exp local，并根据退出码和失败摘要决定下一步。
+运行 npx niceeval exp local --output agent，并根据退出码和失败 locator 决定下一步。
 对每个失败的 Eval，从报告选择一个 Attempt locator；再运行 niceeval show @<id>
-并按问题选择默认 Eval 源码面、--execution 或 --diff。写出失败原因的假设，并判断应该修改被测程序、
+并按问题选择 --eval、--execution、--timing 或 --diff；--timing 从 lifecycle 展开 setup/teardown
+hook、shell 命令、每轮 send 与可关联的 OTel model/tool，回答整个 Attempt 的时间花在哪里。
+写出失败原因的假设，并判断应该修改被测程序、
 Eval，还是实验环境。修改后用 --force 重跑对应 Eval，比较新的判定和证据。
 同一问题连续三轮没有新证据或改善时停止并汇报，不要靠放宽断言碰绿。
-全部局部失败清零后，用 npx niceeval exp local --force 全量验证；退出码 0 才完成。
+全部局部失败清零后，用 npx niceeval exp local --output agent --force 全量验证；退出码 0 才完成。
 ```
 
 真实 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

@@ -18,6 +18,7 @@ export default defineEval({
   reporters?: Reporter[];
   timeoutMs?: number;
   metadata?: Record<string, unknown>;
+  async setup(sandbox, ctx) { /* task fixture + progress/diagnostic */ },
   async test(t) { /* interactions + assertions */ },
 });
 ```
@@ -90,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
 
@@ -109,7 +110,39 @@ export default defineEval({
 });
 ```
 
-详见 [Fixtures](/zh/guides/fixtures)。
+详见 [Fixtures](/zh/how-to/fixtures)。
+
+## 从 Eval 报告长步骤和诊断
+
+`setup` 用于这条 Eval 的任务夹具。第二个参数绑定到 eval setup 阶段；`test(t)` 里的反馈绑定到 eval run 阶段：
+
+```ts
+export default defineEval({
+  async setup(sandbox, ctx) {
+    ctx.progress({ message: "安装 fixture 依赖" });
+    await sandbox.runCommand("npm", ["install"]);
+  },
+
+  async test(t) {
+    t.progress({ message: "上传隐藏测试", current: 1, total: 2 });
+    await t.sandbox.uploadDirectory("../fixtures/project");
+
+    const preflight = await inspectFixture();
+    if (preflight.usedFallback) {
+      t.diagnostic({
+        code: "fixture-check-degraded",
+        level: "warning",
+        message: "Fixture 预检使用了备用检查器",
+        data: { checker: preflight.checker },
+      });
+    }
+
+    await t.send("完成任务");
+  },
+});
+```
+
+`progress` 只更新运行中的短期状态，不进入结果。`diagnostic` 会写进当前 Attempt 的 `result.json`，但不会代替断言或自动改变判定：业务结论仍用 `t.check` / `t.require` / gate；基础设施无法继续时抛出异常。
 
 ## 命名约定