niceeval 0.15.1-canary.76 → 0.16.1

package/docs-site/zh/tutorials/custom-application.mdx

@@ -1,14 +1,18 @@
 ---
-title: "评估自定义应用"
-description: "保留应用自己的方法与上下文，用 NiceEval 评估结构化结果和业务操作。"
+title: "评估自定义应用：发帖、生图这类业务操作"
+sidebarTitle: "评估自定义应用"
+description: "被测应用不是对话式 Agent 时，用 defineAdapter 把它的业务方法直接暴露给评估用例，检查结构化结果和业务操作。"
 ---
 
-应用可以提供发帖、生成图片、刷新时间线等方法。用 `defineAdapter` 创建连接，返回对象的顶层操作会成为评估中强类型的 `t` 方法。
-Agent 是实现 `send(input, ctx) → Turn`、Session 和 Turn 的另一种 Adapter；自定义应用不要求实现这个 Agent 协议。
+你在评估一个社交应用里的 AI 功能：用户发帖后，AI 自动生成配图、推荐回复。这里没有“发一条消息、收一条回复”的对话，有的是发帖、回复、生成图片这些业务操作。
+
+硬把它们写成 `t.send("帮我发帖")` 很别扭。更直接的做法是用 `defineAdapter` 把应用自己的方法交给评估用例：返回对象里的每个操作，都会变成评估用例里带类型的 `t.post(...)`、`t.generateImage(...)`。
+
+对话式 Agent 用的 `defineAgent` 是 Adapter 的一种特例，要实现 `send`、多轮会话和 Turn。自定义应用不需要实现这些。
 
 ## 定义应用连接
 
-下面连接一个已有的社交应用。`createSocialApp` 属于你的应用；返回对象明确列出评估需要的操作。
+先告诉 NiceEval 怎么创建你的应用、评估要用到它的哪些操作。下面连接一个已有的社交应用。`createSocialApp` 属于你的应用，返回对象逐个列出评估需要的操作。
 
 ```ts application.ts
 import { defineAdapter } from "niceeval";
@@ -29,16 +33,17 @@ export const social = defineAdapter({
 });
 ```
 
-运行器每个 Attempt 调用一次 `create`，并在结束时执行已登记的 `onCleanup` 回调。实例隔离由你的 factory 实现；运行器不保证返回独立实例，也不会释放未登记 `onCleanup` 的资源。
-取得资源后立即登记 `onCleanup`。
-把 `signal` 传到应用的网络请求和长任务，才能响应取消。
+运行器每个 Attempt 调用一次 `create`，Attempt 结束时执行登记过的 `onCleanup` 回调。
+
+- 每个 Attempt 要不要拿到独立的应用实例，由你的 `create` 决定。运行器不会替你复制实例。
+- 没登记 `onCleanup` 的资源，运行器不会释放。取得资源后立即登记。
+- 把 `signal` 传进应用的网络请求和长任务，超时或取消时它们才会停下。
 
-TypeScript 自动从返回对象推导方法参数和结果，不需要手写 `t` 的类型。
-应用没有提供 `send` 时，`t.send` 会报类型错误。`check` 等 NiceEval 核心名称不能覆盖；已有类实例用上面的闭包方式暴露方法。
+TypeScript 会从返回对象推导出每个方法的参数和结果，不需要手写 `t` 的类型。返回对象里没有 `send` 时，在评估用例里写 `t.send` 会报类型错误。`check` 等 NiceEval 自带的名称不能被覆盖。已有的类实例，用上面的闭包写法逐个暴露方法。
 
 ## 调用应用动作并自定义检查
 
-`test(t)` 同时提供应用操作与评估能力。应用返回的 Post、Reply 等对象可以直接交给 `defineValueMatch` 定义的自定义 Match。
+接下来在评估用例里调用这些操作，再检查结果。`test(t)` 里既有应用的操作，也有 NiceEval 的检查方法。应用返回的 Post、Reply 等对象，可以直接交给 `defineValueMatch` 定义的自定义 Match。
 
 ```ts evals/publish.eval.ts
 import { defineValueMatch } from "niceeval/expect";
@@ -64,13 +69,13 @@ export default social.defineEval({
 });
 ```
 
-这里的动作签名由你的应用决定。`defineValueMatch` 只描述值怎样匹配；`t.check` 登记 Assertion，`.gate()` 显式把 Boolean 条件设为质量门。也可以复用字符串、数值或 Schema 匹配器。
-需要累计分数时使用 `social.defineScoreEval`，再对检查调用 `.score(points)`。
-开放式语气、人物一致性或内容质量可以交给 [Judge](/zh/explanation/judge)。
+操作的参数和返回值由你的应用决定。`defineValueMatch` 只描述一个值怎样算匹配。`t.check` 登记一条断言，`.gate()` 表示这条不通过，整个评估用例就不通过。字符串、数值和 Schema 匹配器也都能直接用。
+
+需要累计分数时，改用 `social.defineScoreEval`，再在检查上调用 `.score(points)`。语气、人物一致性、内容质量这类开放式标准可以交给 [Judge](/zh/explanation/judge)。
 
 ## 在连接处定义断言方法
 
-多个评估需要同一种检查时，在 Adapter 的 `assertions` 中定义便捷方法。它取得当前 Attempt 的 `app` 和统一的 `check`，返回原有断言 handle。
+好几个评估用例都要做同一种检查时，把它写成 Adapter 上的断言方法，评估用例里一行就能调用。在 `assertions` 里定义这些方法，它们拿到当前 Attempt 的 `app` 和 `check`，返回 `check` 的结果。
 
 ```ts application.ts
 import { defineAdapter } from "niceeval";
@@ -113,15 +118,20 @@ export default social.defineScoreEval({
 });
 ```
 
-`hasPublishedText()` 与显式 `check` 共享评分和报告。`defineEval` 的断言方法没有 `.score()`；`defineScoreEval` 的方法提供它。动作方法 `post()` 仍只执行应用操作。
+`hasPublishedText()` 和直接写 `t.check` 的效果一样，计分和报告里的展示也一样。`defineEval` 里的断言方法没有 `.score()`，`defineScoreEval` 里的有。`post()` 这样的操作方法仍然只调用应用。
+
+写断言方法时注意几点：
 
-在断言方法被调用时读取证据。`assertions` 本身只组装方法，不能提前调用 `check`；返回对象不能包含 getter、非函数值或与应用及核心成员重名的方法。
-方法同步返回本次 `check` 的 handle，不返回 Boolean 或 Promise。异步动作、等待和证据封存放在应用方法中，在检查前显式完成。
-证据不完整时应报告明确错误，不能当作空历史来判断“没有发生”。
-便捷方法使用具体参数签名。无法保留类型关联的泛型或重载便捷方法不可调用；这类组合可以使用独立 Match 和显式 `t.check`，应用操作自身的泛型方法仍可使用。
+- 在方法被调用时才读取要检查的数据。`assertions` 只负责组装方法，不能在里面提前调用 `check`。
+- 返回对象里只放函数，不放 getter 或其它值，方法名也不能和应用操作或 NiceEval 自带的名称重名。
+- 方法同步返回 `check` 的结果，不返回 Boolean 或 Promise。异步操作和等待放在应用方法里，在检查前先完成。
+- 数据不完整时报一个明确的错误，不要当成“什么都没发生”来判断。
+- 参数写成具体类型。泛型或重载的断言方法无法调用，这类检查改用独立的 Match 加 `t.check`。应用操作本身可以是泛型方法。
 
 ## 选择实现并运行
 
+写一个 Experiment 选定这个应用，然后运行。
+
 ```ts experiments/local.ts
 import { defineExperiment } from "niceeval";
 import { social } from "../application.ts";
@@ -135,16 +145,17 @@ export default defineExperiment({
 ```bash
 pnpm exec niceeval check
 pnpm exec niceeval exp local
-pnpm exec niceeval view
 ```
 
-实验选择的应用必须满足评估声明的接口。接口不匹配时，NiceEval 会在创建应用前报错。
-具体操作的顺序、参数和重复次数由评估代码决定；应用动作不会自动获得 Agent 的消息重试。
-自定义方法可以命名为 `send`，其参数和返回值仍由应用决定，不需要构造 `Turn`。如果返回对象没有定义 `send`，`t` 也不会自动获得这个方法。
+跑完后用 `pnpm exec niceeval show` 在终端看结果，或用 `pnpm exec niceeval view` 在浏览器里看。
+
+Experiment 选的应用必须提供评估用例用到的操作。缺了操作时，NiceEval 在创建应用之前就报错，先核对 `create` 的返回对象。
+
+操作的顺序、参数和重复次数都由评估代码决定。应用操作失败时不会像 Agent 消息那样自动重试。你也可以把某个操作命名为 `send`，它的参数和返回值仍由应用决定，不需要构造 `Turn`。
 
 ## 用相同评估比较两个实现
 
-需要替换应用实现时，创建共同的类型化契约，再分别提供实现：
+想知道换一套实现后效果是变好还是变差，就让两套实现跑同一批评估用例。先声明它们共同的接口，再分别提供实现：
 
 ```ts
 import { defineAdapterContract } from "niceeval";
@@ -155,10 +166,9 @@ export const baseline = social.implement({ name: "baseline", create: createBasel
 export const candidate = social.implement({ name: "candidate", create: createCandidate });
 ```
 
-评估通过 `social.defineEval` 编写，两个 Experiment 分别选择 `baseline` 与 `candidate`。
-只有共同接口里的方法可在该评估中使用；两个独立创建但同名的契约不能互换。
+评估用例用 `social.defineEval` 编写，两个 Experiment 分别选 `baseline` 和 `candidate`。评估用例里只能用共同接口里的方法。两次分别调用 `defineAdapterContract` 得到的接口即使同名，也不能互换。
 
-需要共享断言方法时，在创建实现前调用 `withAssertions`：
+两套实现要共用断言方法时，在创建实现前调用 `withAssertions`：
 
 ```ts
 const social = defineAdapterContract<SocialContext>({ name: "social/v1" })
@@ -169,15 +179,19 @@ const social = defineAdapterContract<SocialContext>({ name: "social/v1" })
   }));
 ```
 
-从这个返回契约创建实现和评估，各实现就会使用相同检查。`withAssertions` 返回新契约，之前创建的实现不会自动取得这些方法。
+用 `withAssertions` 返回的接口创建实现和评估用例，各实现就会用同一套检查。`withAssertions` 返回的是一个新接口，在它之前创建的实现拿不到这些方法。
+
+### 什么时候沿用上次结果
 
-执行身份同时包含 Adapter identity（`name`、`contract`、`behaviorRevision`）和 experiment 的 `flags`。评估用例静态项目内相对 import/export 闭包变化会自动使候选失效。
-Experiment 单独选择的实现、动态 import、外部包和远端服务不在自动范围内。为这些行为声明非空 `behaviorRevision`，或用显式配置表达变化；未声明版本的自定义 Adapter 不会自动复用。
+再次运行时，NiceEval 会判断能否沿用上次的结果。参与判断的有 Adapter 的 `name`、`contract`、`behaviorRevision`，以及 Experiment 的 `flags`。评估用例文件和它在项目内用相对路径静态 import 的文件一改，这道题就会重跑。
+
+Experiment 单独选择的实现、动态 import、外部包和远端服务，NiceEval 看不到它们的变化。改了这些行为时，提高 `behaviorRevision`，或者用显式配置体现变化。没有声明 `behaviorRevision` 的自定义 Adapter 每次都重跑，不沿用上次结果。用 `pnpm exec niceeval exp local --dry` 可以先看哪些会沿用、哪些会重跑，见[修改后只重跑受影响的评估](/zh/tutorials/rerun-and-cache)。
 
 ## 保存应用执行轨迹
 
-应用结束并取得完整日志后，在 Adapter 内调用 `ctx.recordTrace`。每个事件保留自己的类型、主体、摘要和已知关系。
-应用不用把操作包装成聊天消息。下面的事件只表示请求已接纳；实际完成应记录另一条事件。
+评估失败时，你想知道应用内部到底做了什么。把应用的执行日志交给 NiceEval，之后就能用 `niceeval show` 逐条查看，不必再去应用那边翻日志。
+
+应用结束、拿到完整日志后，在 Adapter 里调用 `ctx.recordTrace`。每个事件保留自己的类型、执行者、摘要和已知的关联，不需要包装成聊天消息。下面的事件只表示发帖请求已被接受，真正发布完成要另记一条事件。
 
 ```ts
 const attachment = await ctx.attach({
@@ -207,23 +221,25 @@ const receipt = await ctx.recordTrace({
 });
 ```
 
-`key` 是这份快照内的关联键，`source.eventId` 只填写应用真实提供的 ID；没有时省略。
-`schema.id` 标识应用的事件格式，不需要填写 `revision`；NiceEval 自行管理记录格式。旧记录仍可读取，旧调用则需删去 `schema.revision`。
-返回的 `receipt.events` 给出可供查看的稳定 `eventId`。同一 `traceId` 重交相同快照返回同一身份，内容冲突会拒绝。
-摘要有界，大输入通过证据引用精确定位到附件中的值，查看时不需要手动扫描整份日志。
+- `key` 用来在这次提交的事件之间互相引用。`source.eventId` 只填应用真实提供的 ID，没有就省略。
+- `schema.id` 标明应用的事件格式，只填 `id`，不填 `revision`。
+- 返回的 `receipt.events` 给出每个事件的 `eventId`，查看时用它展开。同一个 `traceId` 再次提交相同内容，返回同样的 `eventId`；内容不同会被拒绝。
+- 摘要有长度上限。大段输入放进附件，用 `evidence` 的 `pointer` 指向附件里的具体位置，查看时直接定位，不用扫完整份日志。
+
+跑完后查看这个 Attempt 的执行过程，再展开某个事件：
 
 ```sh
-niceeval show @<attempt> --execution
-niceeval show @<attempt> --execution --expand <eventId>
+pnpm exec niceeval show @<attempt> --execution
+pnpm exec niceeval show @<attempt> --execution --expand <eventId>
 ```
 
-清理回调在独立时限内仍可提交轨迹。取消与完整性是两回事：取消后取得完整日志可以是 complete，
-缺少日志时使用 partial 并列出 limitations；不要用空集合表示未知。窗口外事件保留为 excluded 或 unknown，轨迹导入本身不产生评分。
-已保存的轨迹与证据随 Record 搬迁，查看时不调用原应用或模型。
+`collection.state` 描述日志是否完整，和运行有没有被取消无关。取消后仍拿到了完整日志，就写 `complete`。缺日志时写 `partial`，并在 `limitations` 里说明缺了什么，不要用空列表表示“不知道”。超出 `scopes` 采集范围的事件也保留下来，标成 `excluded`，判断不了的标成 `unknown`。提交执行日志本身不影响判分。
+
+`onCleanup` 回调有自己的时限，在里面也能提交执行日志。保存后的执行日志和附件随结果文件 `.niceeval/record.sqlite` 一起保存，查看时不会再调用应用或模型。
 
 ## 归档大附件
 
-应用可把文件、网络响应或生成器作为原始字节流交给 `ctx.attach`。NiceEval 不解析日志格式：
+应用的原始日志、网络响应这类大文件，可以作为附件和结果一起保存，排查时再取出来看。用 `ctx.attach` 把文件、网络响应或生成器作为字节流交给 NiceEval，NiceEval 不解析其中的格式：
 
 ```ts
 import { createReadStream } from "node:fs";
@@ -241,23 +257,27 @@ const receipt = await ctx.attach({
 });
 ```
 
-先关闭本地日志的写入端，再提交归档；读取期间保持源文件稳定。
-成功回执包含 `artifactId`、原始 bytes 的 `sha256` 和 `byteLength`，此后删除或改写源文件不会改变附件。
-回执只表示内容已接管；Attempt 发布后，附件才能随 Record 持久保存。这不表示上传到了远端服务。
+先关掉本地日志的写入，再提交附件，读取期间不要改动源文件。
+
+返回的回执包含 `artifactId`、原始字节的 `sha256` 和 `byteLength`。拿到回执后，NiceEval 已经有了自己的副本，之后删除或改写源文件不影响附件。附件在这个 Attempt 的结果保存时一起写进结果文件，不会上传到任何远端服务。
 
-流每块最多 1 MiB、单件最多 1 GiB，每个 Attempt 的附件总量最多 2 GiB，同时最多归档 4 个流。
-字符串和数组仍是单件 64 MiB、累计 256 MiB。自定义来源必须响应传入的取消信号，释放自己的文件或连接。
-框架逐块复制并写入后才拉取下一块，不收集整件内容。大附件可以分块读取；作为 trace 的 JSON pointer 证据时，单件仍须不超过 64 MiB。
+大小限制：
 
-在 `ctx.onCleanup` 内归档时，使用 cleanup 回调提供的 `signal`，不要使用已取消的 `ctx.signal`。
-归档失败即使被捕获，也会留下采集失败；此前成功接管的附件保留。大文件应在执行期归档，cleanup 总窗口仍是 30 秒。
+- 字节流每块最多 1 MiB，单个附件最多 1 GiB，每个 Attempt 的附件合计最多 2 GiB，同时最多提交 4 个流。
+- 字符串和数组形式的附件单个最多 64 MiB，合计最多 256 MiB。
+- 作为执行日志里 `pointer` 证据的附件，单个不能超过 64 MiB。
+
+NiceEval 写完一块才读下一块，不会把整个文件读进内存。自定义的流必须响应传入的 `signal`，并释放自己的文件或连接。
+
+在 `ctx.onCleanup` 里提交附件时，用 cleanup 回调提供的 `signal`，不要用已经取消的 `ctx.signal`。提交失败时，即使你捕获了错误，这个 Attempt 也会显示采集失败，之前成功提交的附件仍然保留。cleanup 总共只有 30 秒，大文件应在运行过程中提交。
 
 ## 阅读结果
 
-应用结果交给 `t.check` 后，NiceEval 保存有界检查材料和判定。
-没有采集的会话、工具调用和费用保持缺失。没有 Turn 不代表用了零 token，Judge 的费用也不代表整个应用的费用。
-自定义应用不能声明依赖完整应用费用的 `budget`，也不能声明 Agent 专属的 Sandbox 或会话能力。
-当前生命周期 Plugin 依赖 Agent 的执行准备，自定义应用配置它们会在运行前报错。
+用 `pnpm exec niceeval show` 查看这次运行。每条 `t.check` 保存了被检查的值（有长度上限）和判定。
+
+NiceEval 没有采集到的会话、工具调用和费用会显示为缺失，不会填成零。没有 Turn 不代表用了零 token，Judge 的费用也不等于整个应用的费用。
+
+因为拿不到应用的完整费用，自定义应用不能设置 `budget`，也不能声明只有 Agent 才有的 Sandbox 或会话能力。生命周期 Plugin 需要 Agent 的执行准备步骤，在自定义应用上配置它们会在运行前报错。
 
 完整可运行的模拟 X 示例位于 [LLM X 源码](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/llm-x)。
 它由 LLM 生成人物、个人主页、推文、配图和后续社交动态，并使用应用原生方法进行评估。

package/docs-site/zh/tutorials/dataset-fanout.mdx

@@ -1,18 +1,20 @@
 ---
-title: "数据驱动测试（dataset fan-out）：用多份数据运行同一套评估用例"
+title: "数据驱动测试：一份测试集生成多条评估用例"
 sidebarTitle: "数据驱动测试"
-description: "从 .eval.ts 文件导出数组或 keyed record，将一套评估逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部测试集，并获得稳定 ID。"
+description: "几十条评估逻辑相同、只有输入不同时，从一个 .eval.ts 导出数组或对象，一套逻辑生成多条评估用例。也可以用 loadYaml 或 loadJson 读外部测试集，并给每条起稳定的 ID。"
 ---
 
 import { DatasetFanout } from '/snippets/diagram-dataset-fanout.jsx';
 
-数据驱动测试（dataset fan-out）适合大量结构相同、输入不同的测试。例如 SQL 生成、意图分类、检索问答和工具选择。
+你在评估一个 SQL 生成功能，手上有 80 个“问题 + 期望结果”的样例。每条的检查逻辑都一样：发问题、跑 SQL、比结果。给每条写一个文件，改一次检查逻辑就要改 80 处。
+
+数据驱动测试让你只写一份逻辑，用测试集生成多条评估用例。意图分类、检索问答、工具选择这类大量同构的测试都适合这样写。
 
 <DatasetFanout />
 
-## 工作原理
+## 从一个文件导出一组评估用例
 
-没有外部业务 ID 时，一个 `.eval.ts` 文件默认导出数组：
+把样例放进数组，用 `map` 给每一行生成一个 `defineEval`，再把整个数组作为默认导出。检查逻辑只写一次，改它时所有样例一起生效：
 
 ```ts
 import { defineEval } from "niceeval";
@@ -34,18 +36,18 @@ export default rows.map((row) =>
 );
 ```
 
-## 生成 ID
+## 确认每条评估用例的 ID
 
-如果文件是 `evals/sql.eval.ts`，生成的 ID 是：
+导出数组时，NiceEval 按位置给每条编号。如果文件是 `evals/sql.eval.ts`，生成的 ID 是：
 
 ```text
 sql/0000
 sql/0001
 ```
 
-序号零填充，便于稳定引用和过滤。
+序号补零到固定宽度，方便引用和按前缀筛选。注意数组顺序一变，同一个样例的 ID 也会跟着变。
 
-数据源已经带稳定 case、issue 或 benchmark ID 时，默认导出 keyed record：
+数据源已经带有稳定的 case、issue 或 benchmark ID 时，改为导出一个对象，用这些 ID 作 key：
 
 ```ts
 export default Object.fromEntries(
@@ -62,9 +64,13 @@ export default Object.fromEntries(
 );
 ```
 
-文件是 `evals/swelancer.eval.ts`、key 是 `15193` 时，ID 就是 `swelancer/15193`。key 必须是一个非空路径片段：不能是 `.` / `..`，不能含 `/`、`\\` 或控制字符。NiceEval 按 key 字典序发现，数据源返回顺序变化不会改变运行顺序。
+文件是 `evals/swelancer.eval.ts`、key 是 `15193` 时，ID 就是 `swelancer/15193`。key 必须是一个非空的路径片段：不能是 `.` 或 `..`，不能含 `/`、`\\` 或控制字符。NiceEval 按 key 的字典序排列，数据源返回的顺序变了，运行顺序和 ID 都不变。
+
+运行前可以用 `pnpm exec niceeval exp local sql --dry` 确认生成了哪些 ID、一共多少条。
+
+## 从 YAML 或 JSON 读取测试集
 
-## 从 YAML / JSON 加载
+样例多了以后，放进单独的数据文件更好维护。用 `loadYaml` 或 `loadJson` 读取，并传入一个校验函数：
 
 ```ts
 import { loadYaml } from "niceeval/loaders";
@@ -84,32 +90,36 @@ cases:
     sql: SELECT COUNT(*) FROM users;
 ```
 
-`loadYaml` / `loadJson` 必须接 decoder。未验证的动态值只出现在 decoder 入口。验证通过后，返回值就是可以直接使用的强类型数据。
+`loadYaml` 和 `loadJson` 必须传入校验函数（decoder）。文件内容只在校验函数里以未知类型出现；校验通过后，返回值就是带类型的数据，可以直接使用。数据文件格式不对时，校验函数会报错，这个评估文件加载失败。
 
-## 过滤测试集评估用例
+## 只跑测试集里的一部分
+
+在 Experiment 后面写评估用例 ID 前缀，就能只跑其中几条：
 
 ```bash
 # 运行整个测试集
-npx niceeval exp local sql
+pnpm exec niceeval exp local sql
 
-# 只运行第一个数组 case
-npx niceeval exp local sql/0000
+# 只运行数组里的第一条
+pnpm exec niceeval exp local sql/0000
 
-# 运行一个 keyed case
-npx niceeval exp local swelancer/15193
+# 运行对象导出里的一条
+pnpm exec niceeval exp local swelancer/15193
 ```
 
-## 测试集 vs 独立文件
+跑完后用 `pnpm exec niceeval show` 在终端查看结果，或用 `pnpm exec niceeval view` 在浏览器里查看。每条样例都是独立的评估用例，失败的那几条会单独列出。
+
+## 选择测试集还是独立文件
 
 <Tabs>
   <Tab title="使用测试集">
-    case 结构完全一致，主要差异是输入和预期输出。
+    每条样例的流程完全一样，只有输入和预期输出不同。
   </Tab>
   <Tab title="使用独立文件">
-    每个 case 有不同流程、不同断言或需要不同 agent 配置。
+    每条有不同的流程、不同的断言，或需要不同的 Agent 配置。
   </Tab>
 </Tabs>
 
 <Tip>
-  测试集适合”横向覆盖”，独立评估用例文件适合”行为复杂”的场景。
+  测试集适合用大量同类样例覆盖一个功能，独立的评估用例文件适合流程复杂的场景。
 </Tip>

package/docs-site/zh/tutorials/debug-lifecycle-plan.mdx

@@ -1,32 +1,35 @@
 ---
-title: "运行前检查 Sandbox 计划"
+title: "运行前检查 Sandbox 会怎样准备"
 sidebarTitle: "检查 Sandbox 计划"
-description: "用 niceeval debug 查看 Experiment、评估组、评估用例与 Agent 的实际 action 顺序和数值，而不创建运行资源。"
+description: "用 niceeval debug 列出一条评估在 Sandbox 里会按什么顺序准备、安装、执行和收尾，以及每一步的实际参数，不创建任何资源。"
 ---
 
-`exp --dry` 适合确认运行矩阵。需要检查一条评估在 Sandbox 里会按什么顺序准备、安装、执行和收尾时，使用 `niceeval debug`。
+你在 Experiment、评估组和评估用例上都写了 `.before()`，又给 Agent 配了安装步骤。真正跑起来之前，你想确认这些步骤最终按什么顺序执行、每一步的参数是什么，而不是等 Sandbox 建好、装了五分钟依赖之后才发现顺序不对。
 
-## 选择一个精确配对
+`exp --dry` 告诉你会跑哪些评估、多少次。`niceeval debug` 更进一步：它列出某一条评估在 Sandbox 里的完整准备、安装、执行和收尾步骤，不创建任何 Sandbox，也不调用模型。
+
+## 选定一个 Experiment 和一条评估用例
+
+`debug` 一次只看一个 Experiment 下的一条评估用例：
 
 ```sh
 pnpm exec niceeval debug compare/codex memory/commit0
 ```
 
-Experiment 和评估用例 selector 都必须唯一。精确 ID 优先；前缀命中多个候选时，CLI 会列出候选并停止。
+两个参数都必须只命中一个。精确 ID 优先；前缀命中多个时，CLI 会列出候选并停止，你从中复制完整 ID 再运行一次。
 
-评估用例只能从该 Experiment 已选择的范围中匹配。选择一个评估组成员不会把其它成员加入计划，但输出仍会显示评估组贡献的 action。
+评估用例只能从这个 Experiment 已经选中的范围里找。选中评估组里的一条时，计划不会把同组其它评估用例加进来，但仍会显示评估组贡献的准备步骤。
 
-## 按顺序阅读计划
+## 按顺序读计划
 
-Human 输出使用分层框，不把所有步骤压成一段文本。顶层是 Experiment，下面按 lane、slot 和生命周期节点展开。每个 `sandbox.before` action 都显示：
+输出用分层的框展示：最外层是 Experiment，往里依次是每个 Attempt 和它的各个生命周期步骤。每个 `sandbox.before` 步骤会显示：
 
-- owner 与 action ID；
-- 拓扑执行序号和 occurrence 路径；
-- 用户填写的 `changeFrequency` 数值、来源和匹配的 preset；
-- 依赖、排序原因与当前固定的 `attempt` occurrence；
-- Provider 的缓存能力，以及尚未探测的运行时状态；
-- 由已链接 Action、顺序、依赖、state 与 fingerprint 得出的 `prefixIdentity`；
-- `cache.state` 的 `declared`、`cumulative`、`providerCoverage` 和 `barrier`。
+- 这一步由谁声明（`owner`）和它的 ID（`action`）；
+- 它最终的执行序号，以及属于哪条评估用例；
+- 你填写的 `changeFrequency` 数值、它从哪里来、对应哪个 preset；
+- 它依赖哪些步骤、为什么排在这个位置，以及它在哪一层执行（`occurrence`，当前固定为 `attempt`）；
+- Provider 能不能缓存这一步，以及运行时还没有检查的缓存状态；
+- 这一步能否从缓存恢复（`cache.state` 的 `declared`、`cumulative`、`providerCoverage` 和 `barrier`）。
 
 ```text
 ╭─ sandbox.before ───────────────────────────────── EXACT ─╮
@@ -44,33 +47,37 @@ Human 输出使用分层框，不把所有步骤压成一段文本。顶层是 E
 ╰─────────────────────────────────────────────────────────╯
 ```
 
-数字是最终 linked schedule 的数字，不是只显示声明引入顺序。依赖永远优先；两个 ready action 数值相同时，才按 owner 与声明序稳定决定顺序。评估组的低频 action 因此可以排在 Experiment 的高频 action 前面。
+`execution order` 是真实运行时的顺序，不是你在代码里写下的顺序。排序规则是：依赖总是先执行；几个步骤都可以执行时，`changeFrequency` 数值小的先执行；数值也相同时，按声明者和声明先后决定。所以评估组里很少变化的步骤，可以排在 Experiment 里经常变化的步骤前面。
+
+## 判断哪些步骤能从缓存恢复
+
+- `declared` 是这一步自己声明会改变的状态。
+- `cumulative` 包含它和它之前所有准备步骤会改变的状态。
+- `providerCoverage` 说明 Provider 实际能恢复的范围。
+- `barrier` 不是 `none` 时，输出还会给出 `barrierActionId`，指出第一个无法缓存的步骤。原因可能是它的状态声明是默认的 `all`、是 `opaque`，或者 Provider 不支持。这一步和它之后的所有步骤都会真实执行。
+
+## 确认命令和参数
 
-`declared` 是这个 Action 的完整状态承诺，`cumulative` 包含它之前的准备链。`providerCoverage`
-说明 Provider 实际能恢复的范围。`barrier` 不是 `none` 时，输出还会给出 `barrierActionId`；它指出第一个
-默认 `all`、`opaque` 或不受支持的 Action。该 Action 和所有后缀会真实执行。
+写死的命令步骤会显示命令的形状。普通的 callback 标为 `OPAQUE`，因为它只能在运行时执行，`debug` 看不到里面做了什么。
 
-固定 action 会展示安全的命令形状。普通 callback 标为 `OPAQUE`，因为它只能在运行时执行。环境变量只显示 key 和摘要，stdin 只显示摘要与字节数。凭据值、stdin 原文和不安全的远端 locator 不会泄露到 Human 或 JSON 输出。
+环境变量只显示变量名和摘要，stdin 只显示摘要和字节数。凭据值、stdin 原文和不安全的远端地址不会出现在终端或 JSON 输出里。
 
-## 给工具读取结构化计划
+## 让工具读取计划
 
 ```sh
 pnpm exec niceeval debug compare/codex memory/commit0 --json > debug-plan.json
 ```
 
-JSON 保留同一棵结构化计划，不包含终端框线。action 节点带 `declarationOrder`、`executionOrder`、
-`changeFrequency`、`dependencies`、`occurrence` 和 `cache`。
+JSON 和终端输出是同一份计划，只是去掉了框线。每个步骤带 `declarationOrder`、`executionOrder`、`changeFrequency`、`dependencies`、`occurrence` 和 `cache`。
 
-`cache.state` 固定给出 `declared`、`cumulative`、`providerCoverage`、`barrier`，并在有 barrier 时给出
-`barrierActionId`；可确定的 Action 还给出 `cache.prefixIdentity`。`cache.lookup` 与
-`cache.runtime.finalKey` 固定是 `not-probed`，`cache.runtime.status` 是 `pending`，因为 debug 不读取运行时缓存 inventory。
+`cache.state` 总会给出 `declared`、`cumulative`、`providerCoverage`、`barrier`，有 barrier 时再给出 `barrierActionId`；能确定的步骤还会给出 `cache.prefixIdentity`。`debug` 不读取运行时的缓存，所以 `cache.lookup` 与 `cache.runtime.finalKey` 总是 `not-probed`，`cache.runtime.status` 总是 `pending`。
 
-`debug` 只接受 `--json`；预算、重跑、并发等运行 flag 不适用于这个命令。
+`debug` 只接受 `--json`。预算、重跑、并发这些运行参数对它不适用。
 
-## 确认它不会执行资源操作
+## 它不会创建任何资源
 
-`debug` 不运行 before callback、test、after、ensure 或 Provider finalizer，也不创建 Invocation、Run、Record、锁、Sandbox 或构建任务。
+`debug` 不运行 before callback、test、after、ensure 或 Provider 的收尾函数，也不创建 Run、锁、Sandbox 或构建任务，不写入结果文件。
 
-它会加载受信任定义并执行 Experiment 的选择 predicate。Provider planner 也可能读取本地文件、调用只读 CLI 或查询远端控制面，因此仍应只在可信项目中运行。
+它会加载你的 Experiment 定义并执行 `evals` 选择函数。Provider 在规划时也可能读取本地文件、调用只读 CLI 或查询远端服务，所以仍然只在可信项目里运行它。
 
-矩阵和 Attempt 数量先用[选择并预览运行范围](/zh/tutorials/select-and-preview)确认。真实执行失败后需要进入保留现场时，使用[保留 Sandbox 现场排查问题](/zh/troubleshooting/debug-sandbox)。
+要确认跑哪些题、每题跑几次，用[运行前确认跑哪些、跑几次](/zh/tutorials/select-and-preview)。真实运行失败后需要进入现场时，用[保留 Sandbox 现场排查问题](/zh/troubleshooting/debug-sandbox)。