niceeval 0.9.0 → 0.10.0

package/docs-site/zh/{how-to → tutorials}/viewing-results.mdx

@@ -1,10 +1,10 @@
 ---
 title: "查看 NiceEval 结果并调试 agent 行为"
 sidebarTitle: "查看结果"
-description: "每次运行写入 .niceeval/ 的结构化 artifact 有两扇门：niceeval show 在终端用 @<locator> 精确定位一次 Attempt，逐级下钻 Eval 源码、执行记录与 diff；niceeval view 在网页看同一份证据。"
+description: "用 niceeval show 在终端按 @<locator> 查看 Attempt 的评估用例源码、执行记录与 diff，或用 niceeval view 在网页中查看同一份证据。"
 ---
 
-每次运行后，[NiceEval](https://niceeval.com/) 都会把结构化结果写入该实验的**结果快照**目录 `.niceeval/<experiment>/<快照>/`。看结果有两扇门，读的是同一批 artifact：`niceeval show` 是终端读法，人和 coding agent 都能用；`niceeval view` 是网页读法，适合人浏览证据。两扇门共用判定公式、选结果规则和默认报告：对每个 experiment 的每道 eval，取时间上最新的那份判定，同一个 experiment 跨多次运行拼出来；再按 experiment id 的父目录分组，只在同组内比较。`show` 输出文本面，`view` 输出网页面。
+每次运行后，[NiceEval](https://niceeval.com/) 都会把结构化结果写入该实验的**结果快照**目录 `.niceeval/<experiment>/<快照>/`。快照记录本次运行实际选择的 `selectedEvalIds`；`show` / `view` 直接比较当前 Scope 中的 experiments。
 
 ## 控制台输出
 
@@ -23,7 +23,7 @@ ACTIVE
 … 17 more active
 ```
 
-Human profile 只原位更新当前总数和 active slots，不把历史帧推入 scrollback。失败、错误和去重后的 diagnostic 永久追加，并带 locator。结束块只保留摘要、失败 locator、下钻命令和结果路径。这段输出怎么进「跑→读→修→再跑」的循环，见 [Agent 反馈闭环](/zh/how-to/agent-feedback-loop)。
+Human profile 只原位更新当前总数和 active slots，不把历史帧推入 scrollback。失败、错误和去重后的 diagnostic 会保留并带 locator。结束块只包含摘要、失败 locator、查看命令和结果路径。完整的运行、读取、修复与重跑流程见 [Coding Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)。
 
 ## `.niceeval/<experiment>/<快照>/`
 
@@ -45,14 +45,14 @@ Human profile 只原位更新当前总数和 active slots，不把历史帧推
 
 ## `niceeval show`：终端下钻
 
-`niceeval show` 的位置参数有两种形态：eval id 前缀选「看哪些 eval」，`@<locator>` 精确指名「看哪一次 Attempt」。flag 选「看哪个切面」：
+`niceeval show` 的位置参数有两种形态：评估用例 ID 前缀选择评估用例范围，`@<locator>` 精确指定一次 Attempt。Flag 选择证据类型：
 
 ```bash
-niceeval show                       # 默认报告：按实验组分区，组内比较配置并下钻到 Attempt
+niceeval show                       # 默认报告：比较当前 Scope 并下钻到 Attempt
 niceeval show weather               # 前缀过滤：weather/* 下每个 eval 的判定
 niceeval show weather/brooklyn      # 单个 eval：各 experiment 的 attempt 行(含 @<locator>)、默认 attempt 的断言明细
-niceeval show @1k2m9qrs             # 精确到一次 Attempt:紧凑全景(断言/执行/diff 摘要 + 可用证据一览)
-niceeval show @1k2m9qrs --eval      # 该 Attempt 运行时保存的 Eval 源码,断言标回源码行
+niceeval show @1k2m9qrs             # 精确到一次 Attempt：断言、执行、diff 与可用证据摘要
+niceeval show @1k2m9qrs --source      # 该 Attempt 运行时保存的 Eval 源码,断言标回源码行
 niceeval show @1k2m9qrs --execution # 该 Attempt 的消息、thinking、Skill 加载、工具调用,有 OTel 时补时间
 niceeval show @1c3h6twx --timing    # 有界诊断时间树:phase、hook、operation、shell、turn、OTel 与收尾
 niceeval show @1c3h6twx --timing=full # 同一棵时间树逐节点完整展开
@@ -64,18 +64,18 @@ niceeval show weather/brooklyn --history      # 跨 run 时间轴：抖动与回
 
 Sandbox 创建、setup 或 teardown 错误不依赖 trace。`result.json` 保存错误的 `code`、`message`、生命周期阶段（`phase`）、有限 cause/stack 和 diagnostics；trace 只在存在时补调用关系与耗时。Attempt 在 cleanup、teardown 和 sandbox stop 结束后才封口写入，因此收尾 diagnostic 也能回顾。
 
-同一个实验多次跑会留下多份结果，不带 `@<locator>` 的默认视图只回答一个问题——「现在整体怎样」：每个 experiment × eval 取时间上最新的那份判定，同一个 experiment 跨多次运行拼出来。按前缀只重跑了部分 eval 时，其余 eval 的判定从更早的运行补齐，报告永远是全局最新，不会因为一次局部重跑变残缺。合成是有标注的：每份判定都带上它产生的时间，能看出报告是从哪几次运行拼出来的。合成结果可能混着不同版本的被测代码——所以收工判定以 `--force` 全量重跑为准，迭代途中的 `show` 负责快、收尾的全量跑负责真。
+同一个 Experiment 多次运行会留下多份结果。不带 `@<locator>` 的默认视图显示每个 Experiment × 评估用例最新的判定，并可能从同一个 Experiment 的多次运行中组合结果。按前缀只重跑部分评估用例时，其余评估用例的判定从更早的运行补齐。每份判定都带有生成时间，因此可以识别组合结果的来源。组合结果可能包含不同版本的被测代码，最终判定应以 `--force` 全量重跑为准。
 
-单个 eval 视图里，多 experiment、多 Attempt 时的断言明细块默认挑最新一次失败的 Attempt 展开；没有失败就挑最新一次。这只是一个默认展开的启发式，不是精确选择——需要精确看某一次 Attempt，复制那一行的 `@<locator>` 直接 `show` 它即可。`--experiment compare` 按路径段前缀把 Selection 收窄到整个 `compare` 组，`--experiment compare/bub` 只留一个 experiment；`--results <目录>` 换结果根，`--snapshot <snapshot.json>` 只看某一次落盘的快照，`--history` 看跨 run 趋势。`--report <文件>` 同时替换 `show` / `view` 的默认报告。位置前缀、`--results`、`--experiment` 对自定义报告同样生效；`--history` 与 `--report` 互斥。
+单个评估用例视图里，多 experiment、多 Attempt 时默认展开最新一次失败的 Attempt；需要精确查看就复制该行的 `@<locator>`。`--exp agents/codex` 按 experiment id 路径收窄；`--results` 换结果根，`--snapshot` 只看某一次快照。
 
 `niceeval view` 的每个视图都有 CLI 对应物：
 
 | `niceeval view` 里的视图 | 终端对应 |
 | --- | --- |
 | 当前结果的分组比较报告 | `niceeval show` |
-| 该 eval 各 experiment 的判定行 + 默认 attempt 的断言明细 | `niceeval show <eval id>` |
-| 单次 Attempt 的紧凑全景（断言、执行、diff 摘要与证据可用性） | `niceeval show @<locator>` |
-| Eval 源码标注（断言标回源码行） | `niceeval show @<locator> --eval` |
+| 该评估用例各 experiment 的判定行 + 默认 attempt 的断言明细 | `niceeval show <eval id>` |
+| 单次 Attempt 摘要（断言、执行、diff 与证据可用性） | `niceeval show @<locator>` |
+| 评估用例源码标注（断言标回源码行） | `niceeval show @<locator> --source` |
 | AI 对话、thinking、Skill 加载与工具调用（有 OTel 时补时间） | `niceeval show @<locator> --execution` |
 | 单次 Attempt 的阶段耗时分解 | `niceeval show @<locator> --timing`；逐节点审计用 `--timing=full` |
 | 文件改动 | `niceeval show @<locator> --diff` |
@@ -83,11 +83,11 @@ Sandbox 创建、setup 或 teardown 错误不依赖 trace。`result.json` 保存
 
 ### 默认分组比较报告
 
-不带 flag 的 `niceeval show` 如果命中多个可比组，只列组索引和可直接执行的 `niceeval show --experiment <group>` 命令；Selection 只剩一个组时才输出该组的成本 × 端到端成功率图和实验列表。组的边界来自 experiment id 的完整父目录：`compare/*` 与 `dev-e2b/*` 不共享坐标系、连线、排序或汇总数字；顶层 experiment 各自形成单例组。
+不带 flag 的 `niceeval show` 直接输出当前 Scope 的成本 × 端到端成功率图和实验列表。每个 experiment 的 eval 数与指标分母读取其快照 `selectedEvalIds`；未选择的评估用例不补成失败。
 
-组内实验列表先给固定列汇总，再按 experiment → Eval → Attempt 展开。locator 只保留 `@<id>`，失败原因优先显示期望值/实际值或命令退出码；完整断言和 evidence 留在 `niceeval show @<locator>`。某组只有一个 experiment 时散点仍显示单点，不出现“至少两个实验才能比较”的空态。快照未完成、过旧或覆盖不全的 warning 位于组索引前，同一条 warning 只显示一次。
+实验列表先给固定列汇总，再按 experiment → 评估用例 → Attempt 展开。locator 只保留 `@<id>`；完整断言和 evidence 留在 `niceeval show @<locator>`。只有一个 experiment 时散点仍显示单点。
 
-### 单个 eval
+### 单个评估用例
 
 ```text
 $ niceeval show weather/brooklyn
@@ -103,14 +103,14 @@ attempt 3 · compare/codex-gpt-5.4 · failed · 41.2s · 12.3k tokens · $0.04
 
 artifacts: .niceeval/compare_codex-gpt-5.4/2026-07-09T10-00-00-000Z-x1f2/weather/brooklyn/a2/
 attempt locator: @1k2m9qrs
-next: niceeval show @1k2m9qrs [--eval|--execution]
+next: niceeval show @1k2m9qrs [--source|--execution]
 ```
 
 每个 experiment 一行的紧凑索引末尾就带着代表 attempt 的 `@<locator>`（`compare/bub-gpt-5.4` 只有一次 attempt 就代表它自己，`compare/codex-gpt-5.4` 代表的是默认展开的那一次失败）；展开的明细块结尾再重复一次精确的 `attempt locator:`，两处给的是同一个值。想看别的 attempt（比如 `compare/codex-gpt-5.4` 更早失败的那次），去 `--history` 或 artifact 目录里找到它的 locator，`niceeval show @<locator>` 直接跳过去，不需要先回到这张列表。
 
-### `@<locator>`：一次 Attempt 的全景
+### `@<locator>`：一次 Attempt 的摘要
 
-不带证据 flag 的 `niceeval show @<locator>` 是失败诊断首页：除断言计票外，失败项直接列 group、matcher、expected、received、原因和源码位置；随后给 Eval 源码是否可用、Agent 事件计数、OTel 计时可用性与工作区 diff 摘要。通常这一页已经能回答“为什么失败”，需要解释 Agent 为什么产生该结果时再打开证据切面：
+不带证据 flag 的 `niceeval show @<locator>` 是失败诊断首页：除断言计票外，失败项直接列 group、matcher、expected、received、原因和源码位置；随后给出评估用例源码可用性、Agent 事件计数、OTel 计时可用性与工作区 diff 摘要。该页用于定位失败原因；需要追查 Agent 结果的来源时，再打开对应证据视图：
 
 ```text
 $ niceeval show @1k2m9qrs
@@ -134,21 +134,21 @@ changes: diff unavailable · no workspace diff was recorded for this attempt
 
 artifacts: .niceeval/compare_codex-gpt-5.4/2026-07-09T10-00-00-000Z-x1f2/weather/brooklyn/a2/
 available:
-  niceeval show @1k2m9qrs --eval
+  niceeval show @1k2m9qrs --source
   niceeval show @1k2m9qrs --execution
   niceeval show @1k2m9qrs --timing
 ```
 
-这份全景只给摘要，不复现某个切面的完整内容——完整源码、完整事件流或完整文件列表分别要对应的证据 flag 才给。`changes` 一行永远说明 diff 不可用的具体原因：这里是「这次 Attempt 从未收集过 diff」（`weather/brooklyn` 不是 sandbox eval，压根不会有工作区改动可收集）；如果是 sandbox eval 但 agent 确实没碰任何文件，会是另一句「没有产生工作区文件改动」；两种「不可用」原因不同，不共用一句含糊的提示。
+该视图只给摘要，不复现完整证据。完整源码、事件流和文件列表分别由对应的证据 flag 展开。`changes` 行会说明 diff 不可用的具体原因：此处的 `weather/brooklyn` 不是 Sandbox 评估用例，因此从未收集工作区改动；Sandbox 评估用例未修改文件时则显示「没有产生工作区文件改动」。
 
-### `--eval`、`--execution`、`--timing`、`--diff`：四个证据切面
+### `--source`、`--execution`、`--timing`、`--diff`：四个证据切面
 
-四个证据 flag 既可以加在 `@<locator>` 后面（精确到一次 Attempt），也可以加在能唯一收窄到一个 eval 的前缀后面（挑同一套默认启发式选中的 attempt——最新一次失败，没有失败就挑最新一次，与单 eval 详情块展开的是同一次）；前缀撞到不止一个 eval 时会报错，报错正文直接给出每个候选 eval 的 `@<locator>`，照抄一个继续即可。可以同时传多个证据 flag，一次输出全部要看的切面。
+四个证据 flag 既可以加在 `@<locator>` 后面（精确到一次 Attempt），也可以加在能唯一收窄到一个评估用例的前缀后面（挑同一套默认启发式选中的 attempt——最新一次失败，没有失败就挑最新一次，与单个评估用例详情块展开的是同一次）；前缀撞到不止一个评估用例时会报错，报错正文直接给出每个候选评估用例的 `@<locator>`，照抄一个继续即可。可以同时传多个证据 flag，一次输出全部要看的切面。
 
-`--eval` 是运行时保存的 Eval 源码，按行标注每条断言、gate 失败与 soft 分数直接排在对应源码行下面，源码里没能对应到具体行的断言（没有位置信息，或位置指向另一个文件）单独成一段，永不丢弃：
+`--source` 是运行时保存的评估用例源码，按行标注每条断言、gate 失败与 soft 分数直接排在对应源码行下面，源码里没能对应到具体行的断言（没有位置信息，或位置指向另一个文件）单独成一段，永不丢弃：
 
 ```text
-$ niceeval show @1k2m9qrs --eval
+$ niceeval show @1k2m9qrs --source
 @1k2m9qrs · weather/brooklyn · compare/codex-gpt-5.4 · failed
 
 eval source: evals/weather/brooklyn.eval.ts · sha256:a3fa4555…
@@ -170,7 +170,7 @@ assertions: 1 passed · 1 gate failed · 1 soft below target
 full eval source: .niceeval/compare_codex-gpt-5.4/2026-07-09T10-00-00-000Z-x1f2/weather/brooklyn/a2/sources.json
 ```
 
-它展示的是**这次 Attempt 运行当时保存的源码**，不是当前工作区里同名文件的最新内容——eval 改过之后再看旧 Attempt，看到的仍是它跑的那一版。没有捕获到源码时如实说明「eval source unavailable for this attempt」，不伪造一份空文档。
+它展示的是**这次 Attempt 运行当时保存的源码**，不是当前工作区里同名文件的最新内容——评估用例改过之后再看旧 Attempt，看到的仍是它跑的那一版。没有捕获到源码时如实说明「eval source unavailable for this attempt」，不伪造一份空文档。
 
 `--execution` 把标准事件流（消息、thinking、Skill 加载、工具调用/结果、subagent、错误）排成一棵执行树；这次 Attempt 接入过 OTel 时，同一节点能关联到的 span 会补上相对时间与耗时。无法关联到 Agent 事件的 SDK / runtime span 不逐行混入执行记录，只在结尾报告省略数量并指向完整 `trace.json`。没接入 OTel 时骨架、顺序和内容不变，只去掉时间列并标 `timing unavailable`：
 
@@ -189,7 +189,7 @@ full events: .niceeval/compare_codex-gpt-5.4/2026-07-09T10-00-00-000Z-x1f2/weath
 full OTel trace: .niceeval/compare_codex-gpt-5.4/2026-07-09T10-00-00-000Z-x1f2/weather/brooklyn/a2/trace.json
 ```
 
-这次 Attempt 只有两条消息、没有任何工具调用节点——这正是上面 `calledTool("get_weather")` 这条 gate 断言失败的原因，`--execution` 在这里直接印证了 `--eval` 那份断言标注。有 Skill 加载和工具调用时,`--execution` 把它们按发生顺序一起排进同一棵树,工具调用拆成「调用」与「结果」两行读:
+这次 Attempt 只有两条消息、没有任何工具调用节点——这正是上面 `calledTool("get_weather")` 这条 gate 断言失败的原因，`--execution` 在这里直接印证了 `--source` 那份断言标注。有 Skill 加载和工具调用时,`--execution` 把它们按发生顺序一起排进同一棵树,工具调用拆成「调用」与「结果」两行读:
 
 ```text
 $ niceeval show @1c3h6twx --execution
@@ -234,7 +234,7 @@ timing unavailable · OTel trace was not collected
 full events: .niceeval/compare_codex-gpt-5.4/2026-07-09T10-00-00-000Z-x1f2/weather/brooklyn/a2/events.json
 ```
 
-`--timing` 回答「整个 Attempt 的时间花在哪里」。runner 把 lifecycle、setup/teardown hook、批量工作的 operation、所有经 Sandbox API 发出的 shell 命令，以及每个 session/turn 的 send 墙钟包络记进 `result.json`；某轮有 OTel 时，再按 `traceId` 把 agent/model/tool span 挂到该轮下面。没有 OTel 时，phase、hook、operation、shell 与 turn 时间仍完整，只缺轮内细分。出错或超时的 Attempt 在已知的最深节点用 `✗` 标出死在哪里：
+`--timing` 显示整个 Attempt 的阶段耗时。Runner 把 lifecycle、setup/teardown hook、批量工作的 operation、所有经 Sandbox API 发出的 shell 命令，以及每个 session/turn 的 `send` 墙钟时间记入 `result.json`。某轮有 OTel 时，再按 `traceId` 把 Agent、model 和 tool span 挂到该轮下面。没有 OTel 时，phase、hook、operation、shell 与 Turn 时间仍完整，只缺轮内细分。出错或超时的 Attempt 会在已知的最深节点用 `✗` 标出：
 
 ```text
 $ niceeval show @1c3h6twx --timing
@@ -271,9 +271,9 @@ sandbox.stop         1.2s
 
 裸 `--timing` 会完整列出 phase，并把 phase 下的细节控制在 80 个节点内。超过上限时，它优先保留失败路径、最慢节点与首尾时序，在省略位置显示节点数、未展示的失败数，并给出 `--timing=full`。小树中两种模式输出相同；`--timing=full` 不设节点上限，适合审计旧结果或把完整树重定向到文件。NiceEval 不自动启动 pager，因此管道、CI 和 coding agent 不会等待键盘输入。命令可能并发，省略行不会把子节点耗时相加。
 
-operation 的名称由执行这段工作的组件在采集时写入。例如一次 workspace diff 导出可以显示成 `export workspace diff · 1 window · 3,302 files`，下面只有一条真实的批量 shell。展示层不会解析 `git show` 等命令文本、猜出一个 `git show ×N` 分组；如果旧 artifact 确实记录了几千次调用，默认模式有界摘要，`--timing=full` 仍能逐条核对。一次超时到底是 Sandbox 创建慢、某条安装命令慢，还是一轮里的模型/工具慢，`--timing` 一眼可判。旧结果或第三方写入的结果没有阶段数据时，两种模式都如实提示 `phase timing unavailable`。
+Operation 名称由执行工作的组件在采集时写入。例如一次 Workspace diff 导出可以显示为 `export workspace diff · 1 window · 3,302 files`，并包含一条真实的批量 shell。展示层不会解析 `git show` 等命令文本来推测 `git show ×N` 分组。旧 artifact 记录大量调用时，默认模式提供有界摘要，`--timing=full` 可以逐条核对。`--timing` 会分别显示 Sandbox 创建、安装命令和轮内模型或工具耗时。旧结果或第三方结果没有阶段数据时，两种模式都会提示 `phase timing unavailable`。
 
-`--diff` 默认给文件级摘要（落盘的 diff 只有改动后的全文，没有基线可比对增删行数，所以每个改动过的文件都标 `M`、后面跟它现在的行数，不区分新建与修改）；看单个文件的完整内容用 `--diff=<文件路径>`——路径必须用 `=` 连写，位置参数永远留给 eval id 前缀 / `@<locator>`：
+`--diff` 默认给文件级摘要（落盘的 diff 只有改动后的全文，没有基线可比对增删行数，所以每个改动过的文件都标 `M`、后面跟它现在的行数，不区分新建与修改）；看单个文件的完整内容用 `--diff=<文件路径>`——路径必须用 `=` 连写，位置参数永远留给评估用例 id 前缀 / `@<locator>`：
 
 ```text
 $ niceeval show @1c3h6twx --diff
@@ -296,17 +296,17 @@ $ niceeval show @1c3h6twx --diff=src/components/Button.tsx
 1. 运行 niceeval show，找到失败或出错的 eval，从紧凑索引里摘一个 @<locator>。
 2. 运行 niceeval show <eval-id>，读取该题各 experiment 的判定、默认 attempt 的断言明细,
    以及每行末尾的 @<locator>。
-3. 运行 niceeval show @<locator>，看紧凑全景确认这次 Attempt 实际捕获到了哪些证据。
-4. 按问题选择 --eval、--execution、--timing 或 --diff；可以同时传多个证据 flag。
+3. 运行 niceeval show @<locator>，从摘要确认这次 Attempt 捕获的证据类型。
+4. 按问题选择 --source、--execution、--timing 或 --diff；可以同时传多个证据 flag。
 5. 输出被截断时，读取末尾标出的 sources.json、events.json、trace.json 或 diff.json 原始路径。
 6. 修复后重跑该 eval，再用 niceeval show <eval-id> 验证新的 @<locator>；收工前用 --force 全量重跑确认整体结果。
 ```
 
-`--eval` 回答“这道题实际检查了什么、哪条断言为什么过或没过”，`--execution` 回答“agent 做了什么、调用了什么”（可关联时附 OTel 时间），`--timing` 回答“整个 Attempt 的时间花在哪里”，`--diff` 回答“沙箱里的文件实际改成了什么”。先按问题选证据，不需要每次把四份都读完。
+`--source` 显示评估用例检查内容和断言结果，`--execution` 显示 Agent 消息与调用（可关联时附 OTel 时间），`--timing` 显示 Attempt 各阶段耗时，`--diff` 显示 Sandbox 文件改动。按诊断目标选择证据，不需要每次读取全部四种视图。
 
 ### 历史与抖动：`--history`
 
-榜单和单个 eval 视图回答「现在」；「这个 eval 稳不稳」「什么时候开始坏的」问的是趋势。`--history` 给跨 run 时间轴，每次真实执行一行：
+默认报告和单个评估用例视图显示最新判定。`--history` 用跨 run 时间轴显示稳定性和回归起点，每次真实执行一行：
 
 ```text
 $ niceeval show weather/brooklyn --history
@@ -319,9 +319,9 @@ compare/codex-gpt-5.4 · 5 runs · passed 2/5
   2026-07-07T16-40   ✗ failed   3 attempts   $0.05   gate calledTool("get_weather")
 ```
 
-✓✗ 交替说明这个 eval 在抖，该修的是稳定性（被测程序或断言），反复重跑碰运气只会烧钱；连续绿转红的拐点就是回归引入的位置，用 `view --snapshot <snapshot.json>` 钉住拐点前后两次细看。时间轴只列真实执行——缓存携带的旧结果是判定的复印件，不占行，否则趋势会被复印件灌满假数据。不带 eval id 的 `niceeval show --history` 给每个 experiment 的 per-run 通过率序列，同一份趋势的榜单视角。
+✓✗ 交替说明这个评估用例在抖，该修的是稳定性（被测程序或断言），反复重跑碰运气只会烧钱；连续绿转红的拐点就是回归引入的位置，用 `view --snapshot <snapshot.json>` 钉住拐点前后两次细看。时间轴只列真实执行——缓存携带的旧结果是判定的复印件，不占行，否则趋势会被复印件灌满假数据。不带评估用例 id 的 `niceeval show --history` 给每个 experiment 的 per-run 通过率序列，同一份趋势的榜单视角。
 
-两次 run 的精确对比（这次修复具体翻转了哪些 eval）不做成 flag：用 `DeltaTable` 积木写一份报告递给 `--report`，几行就是一份自定义对比报告，终端和网页两扇门都认——内置命令只管固定摆法，自定义口径见[自定义报告](/zh/how-to/custom-reports)。
+两次 run 的精确对比不提供专用 flag。使用 `DeltaTable` 组件编写自定义对比报告，再把文件传给 `--report`；终端和网页会渲染同一份报告。具体写法见[自定义报告](/zh/tutorials/custom-reports)。
 
 ## `niceeval view`：在网页看证据
 
@@ -329,19 +329,19 @@ compare/codex-gpt-5.4 · 5 runs · passed 2/5
 npx niceeval view
 ```
 
-这会打开本地结果查看器。它的首页报告和 `niceeval show` 选结果的规则一模一样：对每个 experiment 的每道 eval，取时间上最新的那份判定，同一个 experiment 跨多次运行拼出来；收窄范围（eval ID 前缀、`--experiment`）时按同一条规则收窄。你可以浏览 eval、查看 agent 的对话与工具调用、读 diff、检查断言结果。数据不会上传到外部服务。
+这会打开本地结果查看器。它的首页报告和 `niceeval show` 选结果的规则一模一样：对每个 experiment 的每道评估用例，取时间上最新的那份判定，同一个 experiment 跨多次运行拼出来；收窄范围（评估用例 ID 前缀、`--exp`）时按同一条规则收窄。你可以浏览评估用例、查看 agent 的对话与工具调用、读 diff、检查断言结果。数据不会上传到外部服务。
 
 <Tip>
   失败后立刻运行 `npx niceeval view`，可以直接打开刚刚那次运行的 artifacts。
 </Tip>
 
-`view` 的首页是一份报告：不传 `--report` 时完整加载当前结果并显示全部可比组索引，选中一组后只显示该组的成本 × 端到端成功率散点图与实验表。切组只改变页面状态，不重新读取或计算；不同组不会混进同一张图或榜单。浏览器禁用 JS 时，每组作为独立的 `<details>` 完整可读；启用 JS 后一次聚焦一组。传了 `--report` 就换成你自己的报告（与 `show --report` 吃同一个文件），页面与导航完全由报告文件决定，见[自定义报告](/zh/how-to/custom-reports)。Attempt 详情（弹窗里的 transcript、时间树、trace、diff）始终可用——它是查看器自身的能力，报告里的每个数字点进去都是对应证据；默认报告另有 Attempts 列表页和追踪瀑布页，自己的报告要同款页面就摆同名组件。
+`view` 的首页直接显示当前 Scope 的摘要、成本 × 端到端成功率散点图与实验表。传 `--report` 就换成自己的报告。Attempt 详情里的 transcript、时间树、trace 与 diff 始终可用。
 
-网页版多几样浏览操作：切换可比组、点表头就地排序、在当前组的过滤框里筛行、点开一个 experiment 行看它每道题的判定与原因、悬停散点看数值——这些只影响眼前的视图，不改判定口径，刷新即恢复。Attempt 弹窗里有与 `show --timing` 同源的统一时间树：Sandbox 启动、setup hook 及其 shell、agent 安装命令、每轮 send 与可关联的 OTel model/tool、评分与收尾都能逐层展开。默认报告页里有 **Copy fix prompt** 按钮（`CopyFixPrompt` 组件，自己的报告可以直接摆同款），把全部失败打包成可直接粘给 coding agent 的修复 prompt（attempt 弹窗里有单条版）。报告文案有中英两份，随界面语言切换。
+网页版可以排序实验表、筛行、展开 experiment、悬停散点看数值；这些操作不改判定口径。
 
 ## 导出与静态托管
 
-发布结果只有一种导出：`--out <目录>` 整站导出，完整带上能查看的一切。想要自己的页面形态，用报告积木自建（见[自定义报告](/zh/how-to/custom-reports)）。
+发布结果使用 `--out <目录>` 导出完整静态站。需要自定义页面时，使用报告组件编写报告，见[自定义报告](/zh/tutorials/custom-reports)。
 
 ### 内置查看器整站：静态托管
 
@@ -349,7 +349,16 @@ npx niceeval view
 npx niceeval view --out site
 ```
 
-NiceEval 写入 `<dir>/index.html`，并把查看器要读取的 artifact（`sources.json`、`events.json`、`trace.json`）复制到 `<dir>/artifact/` 下。把整个目录交给任何静态托管（Vercel、GitHub Pages 或 `python3 -m http.server`），代码视图、transcript 和 trace 瀑布图都和本地 `niceeval view` 一致；表格排序、过滤和图表悬停也照常可用——所需脚本已内联进页面，浏览器禁用 JS 时页面仍完整可读，只是少这些浏览操作。
+NiceEval 写入 `<dir>/index.html`，并把查看器要读取的 artifact（`sources.json`、`events.json`、`trace.json`，有 `diff.json` 也带上）复制到 `<dir>/artifact/` 下。把整个目录交给任何静态托管（Vercel、GitHub Pages 或 `python3 -m http.server`），代码视图、transcript 和 trace 瀑布图都和本地 `niceeval view` 一致；表格排序、过滤和图表悬停也照常可用——所需脚本已内联进页面，浏览器禁用 JS 时页面仍完整可读，只是少这些浏览操作。
+
+只想发布一部分结果时，把本地查看用的收窄直接交给导出：
+
+```bash
+npx niceeval view --exp agents/codex --out site       # 只发布一个 experiment 路径范围
+npx niceeval view weather --out site                # 只发布 weather 开头的 eval
+```
+
+出站的就是收窄到的：页面和 `artifact/` 证据都只含收窄后的范围，被滤掉实验的 transcript、源码和 trace 不会跟着出站。不收窄就是整站导出完整结果。
 
 `--out` 只接受目录。没有单文件导出：代码视图、transcript 和 trace 依赖 artifact 文件，单个 HTML 装不下完整证据。要把结果发给别人，托管整站发链接即可。
 
@@ -357,10 +366,10 @@ NiceEval 写入 `<dir>/index.html`，并把查看器要读取的 artifact（`sou
 
 两点限制：
 
-- `diff.json` 和 `o11y.json` 不会被复制。查看器不读取它们，且 diff 可能达到上百 MB。
+- `o11y.json` 不会被复制——报告数字已经算进页面，查看器不读取它。
 - 用 `file://` 直接打开 `index.html` 时浏览器不允许 fetch artifact，代码视图会提示源码不可用。本地预览用 http 服务打开。
 
-最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。要让站点随 push 自动更新，先用 `copySnapshots` 生成经过单文件预算检查的发布结果根，把它提交进仓库，再让 CI 对这个目录运行 `view --results <目录> --out`——workflow 与平台接线见[通过 CI 发布报告](/zh/how-to/publish-report)。
+最短流程是在运行评估用例的机器上导出并直接部署产物目录。要让站点随 push 自动更新，先用 `copySnapshots` 生成经过单文件预算检查的发布结果根并提交到仓库，再让 CI 对该目录运行 `view --results <目录> --out`。Workflow 与托管平台配置见[通过 CI 发布报告](/zh/tutorials/publish-report)。
 
 ## Artifact 说明
 
@@ -378,15 +387,15 @@ NiceEval 写入 `<dir>/index.html`，并把查看器要读取的 artifact（`sou
 
 ### `diff.json`
 
-Sandbox eval 中 agent 改动的文件 diff。
+Sandbox 评估用例中 agent 改动的文件 diff。
 
 ### `sources.json`
 
-eval 源码位置和断言位置，用于查看器把失败断言对应回代码。
+评估用例源码位置和断言位置，用于查看器把失败断言对应回代码。
 
 ### `trace.json`
 
-OTLP trace 或标准化后的 span 数据。它是可选的执行关系和耗时证据，不是错误存储：沙箱创建（`sandbox.create`）可能早于 telemetry，teardown 可能晚于 trace collect。
+OTLP trace 或标准化后的 span 数据。它是可选的执行关系和耗时证据，不是错误存储：Sandbox 创建（`sandbox.create`）可能早于 telemetry，teardown 可能晚于 trace collect。
 
 ### `o11y.json`
 
@@ -398,7 +407,7 @@ OTLP trace 或标准化后的 span 数据。它是可选的执行关系和耗时
   <Tab title="passed">所有 gate 通过。</Tab>
   <Tab title="failed">至少一个 gate 失败，或 `--strict` 下 soft 断言低于阈值。</Tab>
   <Tab title="errored">环境、超时、adapter 或 agent runtime 出错。</Tab>
-  <Tab title="skipped">eval 被主动跳过。</Tab>
+  <Tab title="skipped">评估用例被主动跳过。</Tab>
 </Tabs>
 
 Soft 断言的分数记录在 `assertions[].score` 里；非 `--strict` 模式下，它们不会产生额外的 verdict。
@@ -406,8 +415,8 @@ Soft 断言的分数记录在 `assertions[].score` 里；非 `--strict` 模式
 ## 调试建议
 
 - 榜单里失败/错误的题每条自带下钻命令：`niceeval show <eval id>` 先看断言明细，行尾的 `@<locator>` 可以直接精确下钻到某一次 Attempt。
-- 想知道 eval 实际检查了什么、断言为什么过或没过，看 `--eval`（标回源码行的断言标注）。
-- 想知道 agent 做了什么、调用了什么，看 `--execution`；关联成功的 OTel 时间会贴在同一事件旁。
+- 检查评估用例内容和断言结果时使用 `--source`，断言标注会对应到源码行。
+- 检查 Agent 消息和调用时使用 `--execution`；关联成功的 OTel 时间会显示在同一事件旁。
 - coding-agent 失败时看 `--diff` 和 `--execution` 里的工具调用；两者结合能看出「改错了文件」还是「压根没调用该调用的工具」。
-- Sandbox eval 跑得慢或超时，先看 `--timing`：排队、Sandbox 启动、setup hook 里的每条 shell、agent 安装命令、每轮 send 与可关联的 OTel model/tool 各花多久，一眼可判；收尾卡住也在这里单独列出。
-- 判断缺陷在被测程序还是 eval 本身、修完怎么重跑，流程见 [Agent 反馈闭环](/zh/how-to/agent-feedback-loop)。
+- Sandbox 评估用例运行缓慢或超时时，先看 `--timing`。该视图分别列出排队、Sandbox 启动、setup hook 中的 shell、Agent 安装命令、每轮 `send`、可关联的 OTel model/tool 以及收尾阶段耗时。
+- 定位被测程序或评估用例缺陷并完成重跑的流程见 [Coding Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)。