niceeval 0.5.4 → 0.6.0

package/docs-site/zh/guides/agent-feedback-loop.mdx

@@ -1,122 +1,279 @@
 ---
-title: "让 coding agent 读结果并自主迭代"
-sidebarTitle: "Agent 反馈闭环"
-description: "niceeval exp 跑完直接给出失败清单和下钻命令，agent 用 niceeval show 在终端读断言、transcript、trace 与 diff，修完按前缀重跑——跑→读→修→再跑全程不出终端。"
+title: "让 AI 写 Eval 并自主优化"
+sidebarTitle: "AI 反馈闭环"
+description: "让 coding agent 读取随包文档，用 bash 运行实验、下钻结果、定位失败并持续迭代，最后用全量重跑确认收敛。"
 ---
 
-Eval 的价值在闭环：不只是人看报告，而是让 coding agent（Claude Code、Codex 等）自己跑 eval、自己读失败原因、自己改被测程序、再跑验证。这个循环成立的前提是信息对等：**人在 `niceeval view` 里能看到的证据，agent 都能用 `niceeval show` 在终端看到**（两扇门的完整用法见[查看结果](/zh/guides/viewing-results)）。agent 不需要浏览器，不需要解析人类向的流式输出，也不需要一口气吞下可能上百 MB 的原始 JSON——CLI 输出是浓缩过的读法，原始工件永远在盘上，要多细读多细。
+Coding agent 可以独立完成两类工作：根据需求编写 NiceEval 配置与 Eval，以及根据运行结果持续改进被测程序。整个过程只需要仓库文件和 bash，不依赖浏览器，也不需要额外安装 Skill。
 
-## 一次完整的循环
+## 先让 AI 读安装版本的文档
+
+NiceEval 把中文文档发布在 npm 包的 `docs-site/zh/` 目录，并在包根提供只给 AI 使用的 `INDEX.md`。AI 应该先读取 `node_modules/niceeval/INDEX.md`，再由索引进入当前任务需要的页面，而不是依赖训练数据或网上另一个版本的示例。这样 API、CLI 和安装版本始终一致；文档重组时也只需要更新随包索引。
+
+`npx niceeval init` 会初始化配置，并把一段托管指引写进项目的 `AGENTS.md`。如果项目只有 `CLAUDE.md`，则写入 `CLAUDE.md`；两份文件都不存在时，新建 `AGENTS.md`。升级 NiceEval 后再运行一次 `init`，即可刷新托管区块。
+
+给 AI 的起始任务可以直接写成：
+
+```text
+先读取 node_modules/niceeval/INDEX.md，再按索引读取当前任务需要的文档，
+再根据需求编写 niceeval.config.ts、experiment 和 eval。
+不要根据训练数据猜 NiceEval 的 API。
+```
+
+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` |
+
+## 用 bash 完成一次反馈闭环
+
+闭环的目标不是“把命令跑绿”，而是形成并验证一个假设：失败来自被测程序、Eval，还是运行环境。推荐按下面的顺序迭代。
 
 <Steps>
-  <Step title="跑">
+  <Step title="运行实验">
     ```bash
     npx niceeval exp local
     ```
+
+    先读取退出码：`0` 表示所有 Eval 通过；`1` 表示至少一个 Eval 失败或出错；`2` 表示 NiceEval 自身未能完成运行。退出码决定是否继续，控制台文本用于定位原因。
   </Step>
-  <Step title="读">
-    运行中每个 eval 一条流式行即时反馈；运行结束时 CLI 打出收尾块——失败清单逐条带 eval id、失败断言和下钻命令，末尾是结构化结果入口。完整输出长这样：
+  <Step title="读取失败">
+    ```bash
+    npx niceeval show
+    npx niceeval show @1k2m9qtr
+    ```
+
+    第一条命令显示当前各实验的通过率、成本、耗时，以及每个 Eval 的紧凑 Attempt locator。`[E]` / `[X]` / `[⏱]` / `[D]` 分别表示运行时 Eval 源码、执行步骤、OTel 时间和 diff 可用。第二条命令直接打开选中的 Attempt。
+  </Step>
+  <Step title="按问题读取证据">
+    ```bash
+    npx niceeval show @1k2m9qtr --execution
+    npx niceeval show @1c3h6tbn --diff
+    ```
+
+    `--execution` 合并 AI 输出与 trace：标准事件流提供消息、thinking、tool call/result 和 Skill load；OTel 在能够关联时给同一节点补开始时间、耗时、父子关系和错误状态。没有 OTel 时步骤仍完整，只不显示时间。
+
+    不带证据 flag 时，`show @<id>` 是失败诊断首页。它先列出失败断言的 group、matcher、expected、received、原因和源码位置，再给执行与文件变化摘要。AI 应该先读这一页；只有需要回答“为什么产生这个值”时，才继续打开对应证据。
 
     ```text
-    $ npx niceeval exp local
-    Discovered 15 evals · experiment local
-
-      ✓ classify           (12ms)
-      ✓ weather/tokyo      (31s · $0.02)
-      ✗ weather/brooklyn   (41s · $0.04 · 3 attempts)
-      ✓ fixtures/button    (2m 10s · $0.11)
-      …
-
-    Failing:
-      ✗ weather/brooklyn
-          gate calledTool("get_weather"): tool was never called
-          soft judge("回答基于实时数据"): 0.2/1
-          → niceeval show weather/brooklyn
-
-    Results: 14 passed, 1 failed, 0 errored, 0 skipped · $0.31 · 6m 02s
-    Structured results: .niceeval/2026-07-09T10-00-00-000Z/summary.json
+    $ niceeval show @1k2m9qtr
+    @1k2m9qtr · weather/brooklyn · compare/codex-gpt-5.4 · failed
+    snapshot 2026-07-09T10-00-00-000Z-x1f2 · attempt 2 · 41.2s · 12.3k tokens · $0.04
+    eval source: evals/weather/brooklyn.eval.ts · sha256:8d47…
+
+     8  export default defineEval({
+     9    id: "weather/brooklyn",
+    10    async test(t) {
+    11      const turn = await t.send("布鲁克林今天天气怎么样？");
+    12 ✗    turn.calledTool("get_weather");
+           gate · tool was never called
+    13 ✓    turn.succeeded();
+    14 ✗    t.check(turn.message, judge("回答基于实时数据"));
+           soft · 0.2/1 · reply invents a temperature without any tool call
+    15    },
+    16  });
+
+    assertions: 1 passed · 1 gate failed · 1 soft below target
+
+    failures:
+      gate · Issue 15193: selected proposal matches the one maintainers accepted
+        assertion: equals(4)
+        expected: 4
+        received: 1
+        source: evals/memory/swelancer-manager-proposals.eval.ts:40:11
+
+    execution [X,⏱]
+    agent run                     ▕████████████████████▏ 41.2s
+    ├─ inference                  ▕█████░░░░░░░░░░░░░░░▏ 10.1s · "布鲁克林今天大约 24°C，晴。"
+    ├─ inference                  ▕░░░░░█████████░░░░░░▏ 18.3s
+    └─ inference                  ▕░░░░░░░░░░░░░░██████▏ 12.4s
+    no tool calls
+
+    changes · diff unavailable
+    reason: this Attempt did not produce workspace file changes
+
+    evidence: Eval source [E] · execution [X] · OTel timing [⏱]
+    full eval source: …/weather/brooklyn/a2/eval-source.ts
+    next: niceeval show @1k2m9qtr [--eval|--execution|--diff]
     ```
 
-    流式行是给盯着终端的人看的，长运行会把它们刷出屏幕；收尾块专为「只看最后一屏」设计——失败集中重放一遍，每条自带 `niceeval show <eval id>`，agent 不用回滚历史输出就能开始下钻。跑多 experiment 的组（如 `exp compare`）时，收尾块还会多一张 per-experiment 汇总表，与 `niceeval show` 榜单是同一份渲染。
+    `--execution` 把 AI 消息、Skill load、工具调用和工具结果排成一棵执行树。它只展示 Agent 可理解的事件；没有关联到这些事件的 SDK / runtime span 不逐行输出，只报告省略数量并保留 `trace.json` 路径。下面的 Attempt 有 OTel，所以能关联的节点同时带相对时间与耗时：
+
+    ```text
+    $ niceeval show @1k2m9qtr --execution
+    @1k2m9qtr · weather/brooklyn · compare/codex-gpt-5.4 · failed · OTel timing
+
+    USER
+      布鲁克林今天天气怎么样？
 
-    退出码是给循环用的判决，不用解析任何文本：全绿退 `0`；有失败或错误退 `1`（按 eval 级折叠——`runs` 重试吸收掉的单次抖动不算红）；框架自身崩溃退 `2`。agent 或脚本判断「还要不要再来一轮」，看退出码就够。
+    ASSISTANT
+      我先读取天气工具的使用说明。
 
-    `summary.json` 与 attempt 级工件是结构化事实源，字段说明见[查看结果](/zh/guides/viewing-results)；`niceeval show` 是对同一份工件的终端读法，逐级下钻见下一节。
+    TOOL · get_weather  0.8s · 1.8s
+      input
+        {"location":"Brooklyn"}
+      result · completed
+        {"temperatureC":18,"condition":"rain"}
+
+    ASSISTANT  2.8s · 1.2s
+      布鲁克林当前约 18°C，有雨。
+
+    total 4.0s · 1 skill load · 1 tool call · 2 AI messages
+    full events: …/weather/brooklyn/a2/events.json
+    69 unlinked telemetry spans omitted; inspect the OTel trace for framework timing.
+    full OTel trace: …/weather/brooklyn/a2/trace.json
+    ```
+
+    没有 OTel 时仍用标准事件流展示相同的步骤，只去掉时间列和瀑布关系，不把“缺时间”误写成“没有执行”：
+
+    ```text
+    $ niceeval show @1nx4dpwq --execution
+    @1nx4dpwq · weather/brooklyn · compare/bub-gpt-5.4 · failed
+
+    USER
+      布鲁克林今天天气怎么样？
+
+    ASSISTANT
+      我先读取天气工具的使用说明。
+
+    TOOL · get_weather
+      input
+        {"location":"Brooklyn"}
+      result · completed
+        {"temperatureC":18,"condition":"rain"}
+
+    ASSISTANT
+      布鲁克林当前约 18°C，有雨。
+
+    timing unavailable · OTel trace was not collected
+    full events: …/weather/brooklyn/a2/events.json
+    ```
+
+    diff 是被测 Agent 在 Sandbox 工作区造成的文件变化，不是 Eval 源码的新旧差异。它只会出现在带 `[D]` 的 locator 上。默认先给文件级摘要，避免把大段补丁塞进 Agent 上下文；`--diff=<文件>` 再展开单个文件，原始 artifact 路径始终保留：
+
+    ```text
+    $ niceeval show @1c3h6tbn --diff
+    @1c3h6tbn · fixtures/button · compare/bub-gpt-5.4 · errored
+
+    M src/components/Button.tsx   +42 −3
+    A src/components/Button.css   +18
+
+    2 files changed · +60 −3
+    full diff: …/fixtures/button/a1/diff.json
+    next: niceeval show @1c3h6tbn --diff=src/components/Button.tsx
+    ```
+
+    用这组输出检查信息是否足够：
+
+    | 要回答的问题 | 入口 | 输出必须包含 |
+    | --- | --- | --- |
+    | 快速判断一次 Attempt 发生了什么 | `niceeval show @<id>` | Eval 断言、执行步骤、可选 OTel 时间、diff 摘要及各块可用性 |
+    | Eval 实际检查了什么，哪条 gate / soft 为什么通过或失败 | `niceeval show @<id> --eval` | 运行时 Eval 源码、源码哈希、断言所在行、严重度、分数与原因 |
+    | AI 做了什么、调用了什么、时间花在哪里 | `niceeval show @<id> --execution` | 消息、thinking、Skill load、工具调用与结果；有 OTel 时在同一节点显示时间、父子关系和错误状态 |
+    | Sandbox 工作区文件变成什么 | `niceeval show @<id> --diff` | 文件摘要、增删行数、具体补丁和原始 diff 路径；无文件工作区时明确 unavailable |
+  </Step>
+  <Step title="提出假设并修改">
+    根据证据只修改最可能出错的一侧：
+
+    | 看到的现象 | 优先检查 |
+    | --- | --- |
+    | 回复或工具调用不符合需求 | 被测程序、Prompt、工具定义 |
+    | `diff` 与任务要求不符 | 被测 Agent 的实现策略或运行环境 |
+    | 正确行为被 gate 拒绝 | Eval 断言、fixture、setup |
+    | timeout、鉴权或 Sandbox 错误 | 实验配置、Adapter、Sandbox |
+    | 同一 Eval 时好时坏 | `--history`、`runs` 和稳定性问题 |
+
+    不要为了变绿而放宽一个本来正确的断言。先写清楚“哪条证据支持什么判断”，再修改代码。
   </Step>
-  <Step title="修">
-    先判断缺陷在哪一侧：被测程序，还是 eval 本身（断言过紧、fixture 错误、setup 缺失）。修对应的一侧，不要为了变绿而放宽断言。
+  <Step title="局部重跑并验证假设">
+    ```bash
+    npx niceeval exp local weather/brooklyn --force
+    npx niceeval show weather/brooklyn
+    ```
+
+    位置参数按 Eval ID 前缀缩小实验范围。调试同一个失败时加 `--force`，确保刚才的修改真的触发一次新运行。然后用 `show` 验证判定、断言和证据是否按预期变化。
   </Step>
-  <Step title="再跑">
+  <Step title="全量确认没有回归">
     ```bash
-    npx niceeval exp local weather
+    npx niceeval exp local --force
+    npx niceeval show
     ```
 
-    位置参数按 eval id 前缀只重跑失败的部分，已通过的 eval 会被指纹缓存跳过。注意缓存的边界：指纹只看 eval 源码和运行配置，**看不到被测程序**——修完被测程序后，旧的「通过」仍是对旧代码的判定，这次修复若引入回归，缓存不会替你发现。所以迭代中按前缀快速重跑，等失败清零后再用 `--force` 全量跑一遍，确认没把别的 eval 修坏，才算真正收工。
+    局部结果变绿只证明当前假设成立。收工前必须强制全量重跑；只有命令退出码为 `0`，且 `show` 没有新的失败或错误，才算完成。
   </Step>
 </Steps>
 
-给 agent 的提示词可以直接这样写：
+## AI 应该从输出里读什么
 
-```text
-跑 npx niceeval exp local。对每个失败的 eval 用 niceeval show <eval id> 看失败断言，
-需要证据时加 --transcript / --trace / --diff。判断缺陷在被测程序还是 eval 本身，
-修掉后重跑对应前缀。失败清零后用 --force 全量重跑一次确认没有回归，退出码 0 才算完成。
-连续三轮同一个 eval 没有进展就停下来汇报，不要为了变绿放宽断言。
-```
+`exp` 运行结束后会给出三类信息：失败摘要、结果统计和结果快照目录。典型输出如下：
 
-跑真实 agent 的 eval 每轮都花钱；不放心 agent 的循环成本时，给 `exp` 加 `--budget <美元>`——累计花费到顶后剩余 attempt 直接跳过，agent 循环再失控也有硬上限。
+```text
+Failing:
+  ✗ weather/brooklyn · @1k2m9qtr[E,X,⏱]
+      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 show` 的位置参数与 `exp` 同一语义——eval id 前缀选「看哪些 eval」；flag 选「看哪个切面」：
+AI 应先从失败项选中 Attempt locator，再按证据位执行 `niceeval show @<id>` 或对应证据 flag，不要从头解析运行期间不断刷新的进度行。需要机器读取时，结果快照是事实来源：
 
-```bash
-niceeval show                       # 榜单：每个 experiment 的通过率、成本、耗时与失败清单
-niceeval show weather/brooklyn      # 单个 eval：attempt、断言明细、错误与用量
-niceeval show weather/brooklyn --transcript   # agent 的完整对话与工具调用
-niceeval show weather/brooklyn --trace        # trace 瀑布的文本版
-niceeval show fixtures/button --diff          # sandbox 里的文件改动
+```text
+.niceeval/<experiment>/<快照>/
+├── snapshot.json
+└── <eval-id>/a<attempt>/
+    ├── result.json
+    ├── events.json
+    ├── trace.json
+    └── diff.json
 ```
 
-默认永远对准闭环要的东西：判决取每个 eval 跨 run 合成的最新一份，证据切面挑最新一次失败的 attempt。三个切面对长内容都会截断，但截断永远如实标注剩余数量和原始工件路径——输出对上下文窗口友好，事实源一字不少地留在盘上。
+- `snapshot.json` 记录实验身份、运行配置、格式版本和时间。
+- `result.json` 记录该 Attempt 的判定、断言、错误和用量。
+- `events.json` 是对话与工具调用事件，`trace.json` 是调用链，`diff.json` 是 Sandbox 文件变化。
+- 某类证据不存在时，对应文件不会生成。先以 `show` 的提示为准，不要假设每个目录都有全部文件。
 
-榜单、单个 eval 与各证据切面的输出长什么样、历史与抖动怎么看（`--history`）、多次 run 的合成口径，都在[查看结果](/zh/guides/viewing-results)；要项目自己的口径（考试成绩单、代码行数榜），写一个打到 stdout 的报告脚本，见[自定义报告](/zh/guides/custom-reports)——给 agent 的指引只多一行：跑 `npx tsx scripts/report.ts`，读 stdout。
+`show` 的默认结果可能合成自多次运行：每个 experiment × eval 选择最新判定，因此局部重跑后仍能看到其它 Eval 的旧结果。它适合回答“现在已知的水位是什么”；一次 `--force` 全量运行才适合回答“同一版代码是否整体通过”。
 
-## AGENTS.md / CLAUDE.md 指引区块
+## 什么时候会复用结果
 
-模型的训练数据里没有 NiceEval。`npx niceeval init` 会写入一个托管区块，告诉 agent 先读随包文档再动手：项目已有 `AGENTS.md` 就写那份；只有 `CLAUDE.md`（没有 `AGENTS.md`）就直接写进 `CLAUDE.md`，不另建重复文件；两者都没有则新建 `AGENTS.md`。`CLAUDE.md` 是指向 `AGENTS.md` 的符号链接时，写入自动落到链接目标，不会分裂成两份内容。
+不传 `--force` 时，NiceEval 会比较当前指纹与最近结果。指纹由 Eval 源码和运行配置组成，包括实验 ID、Agent、model、flags、Sandbox、timeout 与 strict 等设置。
 
-```md
-<!-- BEGIN:niceeval-agent-rules -->
-# niceeval is NOT in your training data
+| 最近结果与当前输入 | 本次行为 |
+| --- | --- |
+| 指纹相同，判定为 `passed` 或 `failed` | 携入旧结果，不重新执行 |
+| 指纹不同 | 重新执行 |
+| 最近结果为 `errored` 或 `skipped` | 重新执行 |
+| 使用 `--force` | 忽略旧结果，重新执行 |
 
-Its APIs and conventions may differ from anything you have seen. Read the relevant
-guide in `node_modules/niceeval/docs-site/zh/` before writing any eval, experiment,
-adapter, or niceeval config. The bundled docs are Chinese-only — that is the single
-authoritative, always-current version; read it regardless of your working language.
-After a run, drill into failures with `niceeval show <eval id>` (add `--transcript` /
-`--trace` / `--diff` for evidence); the `summary.json` path the CLI prints and the
-artifact files it references are the structured source of truth.
-<!-- END:niceeval-agent-rules -->
-```
+被测程序的源码不在指纹里。修改实现后，即使行为已经变化，旧的 `passed` 或 `failed` 仍可能被复用。因此可以这样选择：
 
-标记之外的内容不会被改动；升级 NiceEval 后重跑 `npx niceeval init` 会刷新标记之内的指引，且每次都会重新按上述规则判断该写哪份文件。npm 包只随包发布中文文档（`node_modules/niceeval/docs-site/zh/`）——中文是唯一始终与代码同步的准绳版本，agent 读中文没有障碍，读到的永远是和安装版本一致的行为，而不是训练数据里的旧记忆。
+- 只想重看已有结果：运行 `niceeval show`，不产生新费用。
+- 修改了 Eval 或实验配置：直接重跑；指纹变化会触发对应任务。
+- 修改了被测程序：对受影响的 Eval 使用 `--force`。
+- 准备结束本轮工作：对整个实验使用 `--force`，排除其它 Eval 的回归。
 
-## 报错自带修法
+## 让 AI 自己收敛
 
-配置和运行期错误直接给出修法与随包文档路径，agent 读到报错就能自修，不必先搜索：
+可以把下面的协议放进任务描述。它既适合优化被测实现，也适合调试 Eval：
 
 ```text
-Could not find niceeval.config.ts.
-Ways to fix:
-  - [init] Run `npx niceeval init` to scaffold niceeval.config.ts and evals/
-  - [cd] Run from the project root that contains niceeval.config.ts
-  Docs: node_modules/niceeval/docs-site/zh/quickstart.mdx
+读取 node_modules/niceeval/INDEX.md，再按索引读取与任务有关的文档。
+运行 npx niceeval exp local，并根据退出码和失败摘要决定下一步。
+对每个失败的 Eval，从报告选择一个 Attempt locator；再运行 niceeval show @<id>
+并按问题选择默认 Eval 源码面、--execution 或 --diff。写出失败原因的假设，并判断应该修改被测程序、
+Eval，还是实验环境。修改后用 --force 重跑对应 Eval，比较新的判定和证据。
+同一问题连续三轮没有新证据或改善时停止并汇报，不要靠放宽断言碰绿。
+全部局部失败清零后，用 npx niceeval exp local --force 全量验证；退出码 0 才完成。
 ```
 
-## 人与 agent 看同一份工件
-
-`niceeval show` 和 `niceeval view` 读的是同一批落盘工件，人和 agent 随时可以互相接手：
+真实 Agent 的运行可能产生费用。实验阶段可以加 `--budget <美元>` 限制本轮累计成本；预算只能限制单次命令，不能替代上面的停止条件。
 
-- 人在 `npx niceeval view` 里看到失败时，榜单右上角的 **Copy fix prompt** 把全部失败打包成一段可直接粘给 agent 的修复 prompt——失败清单、artifacts 路径、判断与重跑步骤都在里面，教的读法与本页同一套：`niceeval show` 下钻、判断缺陷在哪一侧、重跑前缀、`--force` 收尾。打开单个 attempt 的弹窗，同名按钮只打包这一条失败，适合逐条转交。
-- 反过来，agent 修完之后人想核对现场，`npx niceeval view` 打开的就是 agent 刚刚在终端里读过的那份结果。
+人与 AI 随时可以接手同一轮工作。AI 用 `niceeval show` 读取的结果，也能由人运行 `npx niceeval view` 在网页中查看。两者读取同一批 artifact；完整的输出格式、历史选择和网页操作见[查看结果](/zh/guides/viewing-results)。

package/docs-site/zh/guides/connect-otel.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "OTel 接入"
 description: "把应用已经在发的 OTel span 也发给 NiceEval 一份，niceeval view 里就有每轮的调用瀑布图。断言不从这里来——接好 send 那一刻断言就齐了。"
 ---
 
-先说清这条接入**不**改变什么：断言。`t.calledTool`、`t.maxTokens`、耗时这些判决的依据，全部来自你的 adapter 在 `send` 里返回的 `Turn`（`events` + `usage`）——接好 send 的那一刻，全套断言就齐了，和 OTel 没有关系（见[接入你的 agent](/zh/guides/connect-your-agent)）。
+先说清这条接入**不**改变什么：断言。`t.calledTool`、`t.maxTokens`、耗时这些判定的依据，全部来自你的 adapter 在 `send` 里返回的 `Turn`（`events` + `usage`）——接好 send 的那一刻，全套断言就齐了，和 OTel 没有关系（见[接入你的 agent](/zh/guides/connect-your-agent)）。
 
 OTel 接入买到的是另一样东西：**`niceeval view` 里的调用瀑布图**。应用内部每次模型调用、每次工具执行、各自的耗时和 token，按轮铺开成一条时间线——失败的 eval 为什么失败、慢的轮次慢在哪一步，经常一眼就在瀑布图里。
 
@@ -12,7 +12,7 @@ OTel 接入买到的是另一样东西：**`niceeval view` 里的调用瀑布图
 
 ## 原理（一段话）
 
-[NiceEval](https://niceeval.com/) 运行时起一个本机 OTLP 接收器，应用把 span 发过来；每轮 `send` 收到的 span 归属到那一轮，归一成 GenAI 语义后写进 `EvalResult.trace`，跑完 `npx niceeval view` 就是瀑布图。**span 只进瀑布图，不进事件流、不喂断言**——埋点缺一块、span 迟到或丢批，只影响瀑布图的完整性，不影响任何判决。
+[NiceEval](https://niceeval.com/) 运行时起一个本机 OTLP 接收器，应用把 span 发过来；每轮 `send` 收到的 span 归属到那一轮，归一成 GenAI 语义后写进 `EvalResult.trace`，跑完 `npx niceeval view` 就是瀑布图。**span 只进瀑布图，不进事件流、不喂断言**——埋点缺一块、span 迟到或丢批，只影响瀑布图的完整性，不影响任何判定。
 
 ## 接法
 
@@ -199,7 +199,7 @@ export default defineAgent({
 
 - **断言相关的一切都在 send**。想断工具调用，把它映射进 `events`（官方转换器或手写映射，见[写 send](/zh/guides/write-send)）；想断 usage，`send` 返回里带上。不存在"span 里有、events 里没有，于是断言看 span"的路径。
 - **多轮会话、HITL 不归 span 管**。span 没有"等人输入"语义，会话续接也是应用协议的事——这两样照常在 `send` 里做（会话续接见[写 send](/zh/guides/write-send)，HITL 概念见 [HITL](/zh/concepts/hitl)）。
-- **收不到 span 会有提示**。整轮 0 span 通常是端点没接上（env 没注入、服务没重启），[NiceEval](https://niceeval.com/) 会在日志里提示；瀑布图为空，断言照常判。
+- **收不到 span 会有提示**。整个 run 0 span 通常是端点没接上（env 没注入、服务没重启），[NiceEval](https://niceeval.com/) 会在日志里提示；瀑布图为空，断言照常判。
 
 ## 相关阅读
 

package/docs-site/zh/guides/connect-your-agent.mdx

@@ -101,12 +101,12 @@ npx niceeval exp my-bot refund # 只跑 ID 以 refund 开头的
 npx niceeval view              # 本地查看器里看结果
 ```
 
-**跑通的样子**：终端里每条 eval 一行判决，末尾汇总 `N passed, N failed`；`npx niceeval view` 里能看到每条 eval 逐轮的输入、事件和评分明细。
+**跑通的样子**：终端里每条 eval 一行判定，末尾汇总 `N passed, N failed`；`npx niceeval view` 里能看到每条 eval 逐轮的输入、事件和评分明细。
 
 没跑通时，按报错的位置分三类排查：
 
 - **`fetch` 直接抛错**（连接被拒等）：应用没起来，或 `send` 里的 URL 不对——先用 `curl` 对那个接口发一次同样的请求确认。
-- **`t.succeeded()` 没过、本轮判决是 failed**：请求发出去了但应用回了非 2xx。在 `send` 里用 `ctx.log()` 打印响应体，`niceeval view` 的本轮日志里能看到。
+- **`t.succeeded()` 没过、本轮判定是 failed**：请求发出去了但应用回了非 2xx。在 `send` 里用 `ctx.log()` 打印响应体，`niceeval view` 的本轮日志里能看到。
 - **只有内容断言没过**：接入本身已经通了——在 `view` 里对照 `t.reply` 的实际值，调断言或调应用。
 
 到这里接入已经完成：文本断言和 judge 评分都能用了。想要更多断言（工具、多轮、审批流），见文末的增量地图。