niceeval 0.6.1 → 0.7.0

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

@@ -4,29 +4,26 @@ sidebarTitle: "查看结果"
 description: "每次运行写入 .niceeval/ 的结构化 artifact 有两扇门：niceeval show 在终端用 @<locator> 精确定位一次 Attempt，逐级下钻 Eval 源码、执行记录与 diff；niceeval view 在网页看同一份证据。"
 ---
 
-每次运行后，[NiceEval](https://niceeval.com/) 都会把结构化结果写入该实验的**结果快照**目录 `.niceeval/<experiment>/<快照>/`。看结果有两扇门，读的是同一批 artifact：`niceeval show` 是终端读法，人和 coding agent 都能用；`niceeval view` 是网页读法，适合人浏览证据。两扇门共用判定公式与选结果规则：对每个 experiment 的每道 eval，取时间上最新的那份判定，同一个 experiment 跨多次运行拼出来。默认首页针对媒介不同：`show` 先给可下钻的 Attempt 表，`view` 先给图表分析；传入同一个 `--report` 文件时则共用报告组件与数据口径。
+每次运行后，[NiceEval](https://niceeval.com/) 都会把结构化结果写入该实验的**结果快照**目录 `.niceeval/<experiment>/<快照>/`。看结果有两扇门，读的是同一批 artifact：`niceeval show` 是终端读法，人和 coding agent 都能用；`niceeval view` 是网页读法，适合人浏览证据。两扇门共用判定公式、选结果规则和默认报告：对每个 experiment 的每道 eval，取时间上最新的那份判定，同一个 experiment 跨多次运行拼出来；再按 experiment id 的父目录分组，只在同组内比较。`show` 输出文本面，`view` 输出网页面。
 
 ## 控制台输出
 
 ```text
-Discovered 3 evals
-
-  ✓ classify (12ms)
-  ✓ weather/brooklyn (456ms)
-  ✗ api-validation (38s)
-    - gate: expected src/routes/users.ts to include .safeParse() [FAILED]
-
-Failing:
-  ✗ api-validation
-      gate fileIncludes("src/routes/users.ts", ".safeParse()")
-      → niceeval show api-validation
-
-Results: 2 passed, 1 failed, 0 errored, 0 skipped
-Structured results: .niceeval/compare_web-agent/2026-07-09T10-00-00-000Z-x1f2/
-  (snapshot.json + 每 attempt 的 result.json / events.json / trace.json / diff.json)
+Plan: 45 attempts · 9 evals × 5 configs · concurrency 19
+✗ @12h8m4k1 fixtures/button [compare/claude-e2b] errored · sandbox.create
+    sandbox-rate-limit: E2B sandbox allocation failed after 5 attempts
+    Inspect: niceeval show @12h8m4k1
+
+niceeval exp compare                                      2m 14s
+45 total · 6 reused · 19 running · 12 queued · 8 completed  $0.84
+
+ACTIVE
+● memory/agent-029-use-cache  compare/bub-e2b      1m 42s  running tests
+● memory/agent-030-app-route compare/codex        1m 18s  editing src/app.ts
+… 17 more active
 ```
 
-运行中每个 eval 一条流式行，失败断言内联展开；运行结束的收尾块把失败集中重放一遍，每条自带下钻命令，末尾是本次实验的快照目录。这段输出怎么进「跑→读→修→再跑」的循环，见 [Agent 反馈闭环](/zh/guides/agent-feedback-loop)。
+Human profile 只原位更新当前总数和 active slots，不把历史帧推入 scrollback。失败、错误和去重后的 diagnostic 永久追加，并带 locator。结束块只保留摘要、失败 locator、下钻命令和结果路径。这段输出怎么进「跑→读→修→再跑」的循环，见 [Agent 反馈闭环](/zh/how-to/agent-feedback-loop)。
 
 ## `.niceeval/<experiment>/<快照>/`
 
@@ -38,7 +35,7 @@ Structured results: .niceeval/compare_web-agent/2026-07-09T10-00-00-000Z-x1f2/
    └─ 2026-07-09T10-00-00-000Z-x1f2/      # 快照目录:时间戳 + 随机后缀
       ├─ snapshot.json                    # 快照元数据(开始时写,收尾补 completedAt)
       └─ weather-tool/a0/                 # 单个 eval attempt 的目录
-         ├─ result.json                   # 判决、断言、用量 —— attempt 完成时一次写成
+         ├─ result.json                   # 判定、断言、结构化错误/diagnostics、用量
          ├─ events.json
          ├─ sources.json
          ├─ trace.json
@@ -51,39 +48,44 @@ Structured results: .niceeval/compare_web-agent/2026-07-09T10-00-00-000Z-x1f2/
 `niceeval show` 的位置参数有两种形态：eval id 前缀选「看哪些 eval」，`@<locator>` 精确指名「看哪一次 Attempt」。flag 选「看哪个切面」：
 
 ```bash
-niceeval show                       # 榜单：每个 Attempt 的判定、eval、locator、短原因、耗时与成本
+niceeval show                       # 默认报告：按实验组分区，组内比较配置并下钻到 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 --execution # 该 Attempt 的消息、thinking、Skill 加载、工具调用,有 OTel 时补时间
+niceeval show @1c3h6twx --timing    # 有界诊断时间树:phase、hook、operation、shell、turn、OTel 与收尾
+niceeval show @1c3h6twx --timing=full # 同一棵时间树逐节点完整展开
 niceeval show @1c3h6twx --diff      # sandbox 里的文件改动
 niceeval show weather/brooklyn --history      # 跨 run 时间轴：抖动与回归拐点
 ```
 
-`@<locator>` 是一次 Attempt 的持久、不透明身份，形如 `@1k2m9qrs`：由 `{experimentId, 快照时刻, evalId, attempt 序号}` 这个身份元组确定性派生，同一份落盘结果反复解析恒得到同一个值。它出现在 `niceeval show` 的紧凑索引里，直接复制粘贴就能定位到那一次运行。裸 `show` 的 locator 列只打印 `@<id>`，不追加判定或证据能力缩写；打开 Attempt 首页后，`available` 会列出实际可用的证据命令。
+`@<locator>` 是一次 Attempt 的持久、不透明身份，形如 `@1k2m9qrs`：由 `{experimentId, 快照时刻, evalId, attempt 序号}` 这个身份元组确定性派生，同一份落盘结果反复解析恒得到同一个值。它出现在 `niceeval show` 的分组明细里，直接复制粘贴就能定位到那一次运行。列表里的 locator 只打印 `@<id>`，不追加判定或证据能力缩写；打开 Attempt 首页后，`available` 会列出实际可用的证据命令。
+
+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` 负责快、收尾的全量跑负责真。
 
-单个 eval 视图里，多 experiment、多 Attempt 时的断言明细块默认挑最新一次失败的 Attempt 展开；没有失败就挑最新一次。这只是一个默认展开的启发式，不是精确选择——需要精确看某一次 Attempt，复制那一行的 `@<locator>` 直接 `show` 它即可。`--experiment` 把 Selection 收窄到一个实验，`--run <目录>` 钉死看某一次历史 run，`--history` 看跨 run 趋势。不带 `--report` 时 `show` 渲染专用 Attempt 索引；`--report <文件>` 换成你自己的报告，同一个文件也能喂给 `view`。位置前缀、`--run`、`--experiment` 对 `--report` 同样生效；`--history` 与 `--report` 互斥。
+单个 eval 视图里，多 experiment、多 Attempt 时的断言明细块默认挑最新一次失败的 Attempt 展开；没有失败就挑最新一次。这只是一个默认展开的启发式，不是精确选择——需要精确看某一次 Attempt，复制那一行的 `@<locator>` 直接 `show` 它即可。`--experiment compare` 按路径段前缀把 Selection 收窄到整个 `compare` 组，`--experiment compare/bub` 只留一个 experiment；`--run <目录>` 钉死看某一次历史 run，`--history` 看跨 run 趋势。`--report <文件>` 同时替换 `show` / `view` 的默认报告。位置前缀、`--run`、`--experiment` 对自定义报告同样生效；`--history` 与 `--report` 互斥。
 
 `niceeval view` 的每个视图都有 CLI 对应物：
 
 | `niceeval view` 里的视图 | 终端对应 |
 | --- | --- |
-| 当前结果的同构 Attempt 表 | `niceeval show` |
+| 当前结果的分组比较报告 | `niceeval show` |
 | 该 eval 各 experiment 的判定行 + 默认 attempt 的断言明细 | `niceeval show <eval id>` |
 | 单次 Attempt 的紧凑全景（断言、执行、diff 摘要与证据可用性） | `niceeval show @<locator>` |
 | Eval 源码标注（断言标回源码行） | `niceeval show @<locator> --eval` |
 | AI 对话、thinking、Skill 加载与工具调用（有 OTel 时补时间） | `niceeval show @<locator> --execution` |
+| 单次 Attempt 的阶段耗时分解 | `niceeval show @<locator> --timing`；逐节点审计用 `--timing=full` |
 | 文件改动 | `niceeval show @<locator> --diff` |
 | 历史 run 列表 | `niceeval show <eval id> --history`；钉死某一次用 `--run <目录>` |
 
-### 默认 Attempt 索引
+### 默认分组比较报告
 
-不带 flag 的 `niceeval show` 先按 experiment 打印摘要，再用同构表列出每个 Attempt。列固定为 `STATUS / EVAL / ATTEMPT / RESULT / DURATION / COST`：四态判定同时给图标与完整单词，locator 只保留 `@<id>`，失败原因优先显示期望值/实际值或命令退出码。完整断言和 evidence 留在 `niceeval show @<locator>`。
+不带 flag 的 `niceeval show` 如果命中多个可比组，只列组索引和可直接执行的 `niceeval show --experiment <group>` 命令；Selection 只剩一个组时才输出该组的成本 × 端到端成功率图和实验列表。组的边界来自 experiment id 的完整父目录：`compare/*` 与 `dev-e2b/*` 不共享坐标系、连线、排序或汇总数字；顶层 experiment 各自形成单例组。
 
-只有一个 experiment 时直接显示它的表，不出现“至少两个实验才能比较”的无关空态。有两个及以上 experiment 时，前面增加紧凑比较表；成本 × 通过率散点留给 `niceeval view`。快照未完成、过旧或覆盖不全的 warning 位于索引前；自定义报告摆了 `RunOverview` 时，同一条 warning 也只显示一次。
+组内实验列表先给固定列汇总，再按 experiment → Eval → Attempt 展开。locator 只保留 `@<id>`，失败原因优先显示期望值/实际值或命令退出码；完整断言和 evidence 留在 `niceeval show @<locator>`。某组只有一个 experiment 时散点仍显示单点，不出现“至少两个实验才能比较”的空态。快照未完成、过旧或覆盖不全的 warning 位于组索引前，同一条 warning 只显示一次。
 
 ### 单个 eval
 
@@ -126,7 +128,7 @@ failures:
     source: evals/memory/swelancer-manager-proposals.eval.ts:40:11
 
 execution: 2 events · 0 skill loads · 0 tool calls · 1 AI messages
-timing: OTel spans recorded for this attempt — see --execution for per-step timing.
+timing: eval.run 40.8s · scoring.evaluate 0.3s
 
 changes: diff unavailable · no workspace diff was recorded for this attempt
 
@@ -134,13 +136,14 @@ artifacts: .niceeval/compare_codex-gpt-5.4/2026-07-09T10-00-00-000Z-x1f2/weather
 available:
   niceeval show @1k2m9qrs --eval
   niceeval show @1k2m9qrs --execution
+  niceeval show @1k2m9qrs --timing
 ```
 
 这份全景只给摘要，不复现某个切面的完整内容——完整源码、完整事件流或完整文件列表分别要对应的证据 flag 才给。`changes` 一行永远说明 diff 不可用的具体原因：这里是「这次 Attempt 从未收集过 diff」（`weather/brooklyn` 不是 sandbox eval，压根不会有工作区改动可收集）；如果是 sandbox eval 但 agent 确实没碰任何文件，会是另一句「没有产生工作区文件改动」；两种「不可用」原因不同，不共用一句含糊的提示。
 
-### `--eval`、`--execution`、`--diff`：三个证据切面
+### `--eval`、`--execution`、`--timing`、`--diff`：四个证据切面
 
-三个证据 flag 既可以加在 `@<locator>` 后面（精确到一次 Attempt），也可以加在能唯一收窄到一个 eval 的前缀后面（挑同一套默认启发式选中的 attempt——最新一次失败，没有失败就挑最新一次，与单 eval 详情块展开的是同一次）；前缀撞到不止一个 eval 时会报错，报错正文直接给出每个候选 eval 的 `@<locator>`，照抄一个继续即可。可以同时传多个证据 flag，一次输出全部要看的切面。
+四个证据 flag 既可以加在 `@<locator>` 后面（精确到一次 Attempt），也可以加在能唯一收窄到一个 eval 的前缀后面（挑同一套默认启发式选中的 attempt——最新一次失败，没有失败就挑最新一次，与单 eval 详情块展开的是同一次）；前缀撞到不止一个 eval 时会报错，报错正文直接给出每个候选 eval 的 `@<locator>`，照抄一个继续即可。可以同时传多个证据 flag，一次输出全部要看的切面。
 
 `--eval` 是运行时保存的 Eval 源码，按行标注每条断言、gate 失败与 soft 分数直接排在对应源码行下面，源码里没能对应到具体行的断言（没有位置信息，或位置指向另一个文件）单独成一段，永不丢弃：
 
@@ -231,6 +234,45 @@ 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 在已知的最深节点用 `✗` 标出死在哪里：
+
+```text
+$ niceeval show @1c3h6twx --timing
+@1c3h6twx · fixtures/button · compare/bub-gpt-5.4 · errored
+total 2m 4s
+
+sandbox.queue         0.3s
+sandbox.create        8.2s
+sandbox.setup        21.6s
+  ├─ restoreCache        18.9s
+  │  └─ shell · tar xzf … 18.8s
+  └─ setup#2              2.7s
+     └─ shell · pnpm config set … 2.7s
+workspace.baseline    0.2s
+  └─ shell · git init && git commit … 0.2s
+agent.setup          41.5s
+  ├─ shell · npm install -g @openai/codex… 39.8s
+  └─ shell · write ~/.codex/config.toml      1.7s
+eval.run             50.9s
+  └─ turn s1/t1      50.9s ✗ agent-runtime-error
+     └─ shell · codex exec … 50.7s
+        ├─ agent · codex.exec 50.5s  OTel
+        └─ model · chat       44.2s  OTel
+
+teardown (not counted in total):
+agent.teardown       0.4s
+sandbox.teardown     3.1s
+  └─ persistCache       3.1s
+     └─ shell · tar czf … 3.0s
+sandbox.stop         1.2s
+```
+
+收尾阶段不计入 Attempt 总耗时，单独分组列出——「判定早就出了、进程还在等收尾」这类问题看这一组。缩进表示包含关系，不表示子项可以相加：命令、turn 和 OTel span 都可能嵌套或并发。
+
+裸 `--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`。
+
 `--diff` 默认给文件级摘要（落盘的 diff 只有改动后的全文，没有基线可比对增删行数，所以每个改动过的文件都标 `M`、后面跟它现在的行数，不区分新建与修改）；看单个文件的完整内容用 `--diff=<文件路径>`——路径必须用 `=` 连写，位置参数永远留给 eval id 前缀 / `@<locator>`：
 
 ```text
@@ -255,12 +297,12 @@ $ niceeval show @1c3h6twx --diff=src/components/Button.tsx
 2. 运行 niceeval show <eval-id>，读取该题各 experiment 的判定、默认 attempt 的断言明细,
    以及每行末尾的 @<locator>。
 3. 运行 niceeval show @<locator>，看紧凑全景确认这次 Attempt 实际捕获到了哪些证据。
-4. 按问题选择 --eval、--execution 或 --diff；可以同时传多个证据 flag。
+4. 按问题选择 --eval、--execution、--timing 或 --diff；可以同时传多个证据 flag。
 5. 输出被截断时，读取末尾标出的 sources.json、events.json、trace.json 或 diff.json 原始路径。
 6. 修复后重跑该 eval，再用 niceeval show <eval-id> 验证新的 @<locator>；收工前用 --force 全量重跑确认整体结果。
 ```
 
-`--eval` 回答“这道题实际检查了什么、哪条断言为什么过或没过”，`--execution` 回答“agent 做了什么、调用了什么、时间花在哪里”，`--diff` 回答“沙箱里的文件实际改成了什么”。先按问题选证据，不需要每次把三份都读完。
+`--eval` 回答“这道题实际检查了什么、哪条断言为什么过或没过”，`--execution` 回答“agent 做了什么、调用了什么”（可关联时附 OTel 时间），`--timing` 回答“整个 Attempt 的时间花在哪里”，`--diff` 回答“沙箱里的文件实际改成了什么”。先按问题选证据，不需要每次把四份都读完。
 
 ### 历史与抖动：`--history`
 
@@ -279,7 +321,7 @@ compare/codex-gpt-5.4 · 5 runs · passed 2/5
 
 ✓✗ 交替说明这个 eval 在抖，该修的是稳定性（被测程序或断言），反复重跑碰运气只会烧钱；连续绿转红的拐点就是回归引入的位置，用 `--run <目录>` 钉住拐点前后两次细看。时间轴只列真实执行——缓存携带的旧结果是判定的复印件，不占行，否则趋势会被复印件灌满假数据。不带 eval id 的 `niceeval show --history` 给每个 experiment 的 per-run 通过率序列，同一份趋势的榜单视角。
 
-两次 run 的精确对比（这次修复具体翻转了哪些 eval）不做成 flag：用 `DeltaTable` 积木写一份报告递给 `--report`，几行就是一份自定义对比报告，终端和网页两扇门都认——内置命令只管固定摆法，自定义口径见[自定义报告](/zh/guides/custom-reports)。
+两次 run 的精确对比（这次修复具体翻转了哪些 eval）不做成 flag：用 `DeltaTable` 积木写一份报告递给 `--report`，几行就是一份自定义对比报告，终端和网页两扇门都认——内置命令只管固定摆法，自定义口径见[自定义报告](/zh/how-to/custom-reports)。
 
 ## `niceeval view`：网页证据室
 
@@ -293,13 +335,13 @@ npx niceeval view
   失败后立刻运行 `npx niceeval view`，可以直接打开刚刚那次运行的 artifacts。
 </Tip>
 
-`view` 的首页是一份报告：不传 `--report` 时是成本 × 通过率散点图与逐实验表，适合人在网页比较；传了 `--report` 就换成你自己的报告（与 `show --report` 吃同一个文件），见[自定义报告](/zh/guides/custom-reports)。裸 `show` 则使用更适合终端 agent 循环的 Attempt 索引。证据部分（Attempt 弹窗、transcript、trace 瀑布、run 列表）始终保留。
+`view` 的首页是一份报告：不传 `--report` 时完整加载当前结果并显示全部可比组索引，选中一组后只显示该组的成本 × 端到端成功率散点图与实验表。切组只改变页面状态，不重新读取或计算；不同组不会混进同一张图或榜单。浏览器禁用 JS 时，每组作为独立的 `<details>` 完整可读；启用 JS 后一次聚焦一组。传了 `--report` 就换成你自己的报告（与 `show --report` 吃同一个文件），见[自定义报告](/zh/how-to/custom-reports)。证据部分（Attempt 弹窗、transcript、trace 瀑布、run 列表）始终保留。
 
-网页版多几样浏览操作：点表头就地排序、在榜单的过滤框里筛行、点开一个 experiment 行看它每道题的判定与原因、悬停散点看数值——这些只影响眼前的视图，不改判定口径，刷新即恢复。报告上方有 **Copy fix prompt** 按钮，把全部失败打包成可直接粘给 coding agent 的修复 prompt（attempt 弹窗里有单条版）。报告文案有中英两份，随界面语言切换。
+网页版多几样浏览操作：切换可比组、点表头就地排序、在当前组的过滤框里筛行、点开一个 experiment 行看它每道题的判定与原因、悬停散点看数值——这些只影响眼前的视图，不改判定口径，刷新即恢复。Attempt 弹窗里有与 `show --timing` 同源的统一时间树：Sandbox 启动、setup hook 及其 shell、agent 安装命令、每轮 send 与可关联的 OTel model/tool、评分与收尾都能逐层展开。报告上方有 **Copy fix prompt** 按钮，把全部失败打包成可直接粘给 coding agent 的修复 prompt（attempt 弹窗里有单条版）。报告文案有中英两份，随界面语言切换。
 
 ## 导出与静态托管
 
-发布结果只有一种导出：`--out <目录>` 整站导出，完整带上能查看的一切。想要自己的页面形态，用报告积木自建（见[自定义报告](/zh/guides/custom-reports)）。
+发布结果只有一种导出：`--out <目录>` 整站导出，完整带上能查看的一切。想要自己的页面形态，用报告积木自建（见[自定义报告](/zh/how-to/custom-reports)）。
 
 ### 内置查看器整站：静态托管
 
@@ -318,7 +360,7 @@ NiceEval 写入 `<dir>/index.html`，并把查看器要读取的 artifact（`sou
 - `diff.json` 和 `o11y.json` 不会被复制。查看器不读取它们，且 diff 可能达到上百 MB。
 - 用 `file://` 直接打开 `index.html` 时浏览器不允许 fetch artifact，代码视图会提示源码不可用。本地预览用 http 服务打开。
 
-最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。要让站点随 push 自动更新，把 `.niceeval/` 提交进仓库、CI 上一行 `view --out` 导出——workflow 与平台接线见[通过 CI 发布报告](/zh/guides/publish-report)。
+最简单的流程是在跑过 eval 的机器上导出，把产物目录直接部署，不需要额外步骤。要让站点随 push 自动更新，先用 `copySnapshots` 生成经过单文件预算检查的发布结果根，把它提交进仓库，再让 CI 对这个目录运行 `view --run <目录> --out`——workflow 与平台接线见[通过 CI 发布报告](/zh/how-to/publish-report)。
 
 ## Artifact 说明
 
@@ -328,7 +370,7 @@ NiceEval 写入 `<dir>/index.html`，并把查看器要读取的 artifact（`sou
 
 ### `result.json`
 
-单个 attempt 的权威记录：判定、断言、耗时、用量、成本。attempt 完成时一次写成，之后不再改写。
+单个 Attempt 的权威记录：判定、断言、正式阶段耗时、结构化 error、去重后的 diagnostics、用量和成本。cleanup、teardown 与 Sandbox stop 完成后一次写成，之后不再改写。`progress` 的短期 message/current/total 不落盘。
 
 ### `events.json`
 
@@ -344,7 +386,7 @@ eval 源码位置和断言位置，用于查看器把失败断言对应回代码
 
 ### `trace.json`
 
-OTLP trace 或标准化后的 span 数据。
+OTLP trace 或标准化后的 span 数据。它是可选的执行关系和耗时证据，不是错误存储：沙箱创建（`sandbox.create`）可能早于 telemetry，teardown 可能晚于 trace collect。
 
 ### `o11y.json`
 
@@ -365,6 +407,7 @@ Soft 断言的分数记录在 `assertions[].score` 里；非 `--strict` 模式
 
 - 榜单里失败/错误的题每条自带下钻命令：`niceeval show <eval id>` 先看断言明细，行尾的 `@<locator>` 可以直接精确下钻到某一次 Attempt。
 - 想知道 eval 实际检查了什么、断言为什么过或没过，看 `--eval`（标回源码行的断言标注）。
-- 想知道 agent 做了什么、调用了什么、时间花在哪里，看 `--execution`（或 view 的证据面板）。
+- 想知道 agent 做了什么、调用了什么，看 `--execution`；关联成功的 OTel 时间会贴在同一事件旁。
 - coding-agent 失败时看 `--diff` 和 `--execution` 里的工具调用；两者结合能看出「改错了文件」还是「压根没调用该调用的工具」。
-- 判断缺陷在被测程序还是 eval 本身、修完怎么重跑，流程见 [Agent 反馈闭环](/zh/guides/agent-feedback-loop)。
+- Sandbox eval 跑得慢或超时，先看 `--timing`：排队、Sandbox 启动、setup hook 里的每条 shell、agent 安装命令、每轮 send 与可关联的 OTel model/tool 各花多久，一眼可判；收尾卡住也在这里单独列出。
+- 判断缺陷在被测程序还是 eval 本身、修完怎么重跑，流程见 [Agent 反馈闭环](/zh/how-to/agent-feedback-loop)。

package/docs-site/zh/{guides → how-to}/write-experiment.mdx

@@ -104,7 +104,7 @@ npx niceeval exp prompt-variants/concise
 | `timeoutMs` | 单个 attempt 的超时 |
 | `budget` | 这一格配置的预算上限 |
 | `maxConcurrency` | 这一格配置的并发上限 |
-| `sandbox` | sandbox agent 使用的后端，如 `dockerSandbox()` / `e2bSandbox()`；spec 上可以链 `.setup()` / `.teardown()` 挂按实验变化的环境钩子 |
+| `sandbox` | sandbox agent 使用的 provider，如 `dockerSandbox()` / `e2bSandbox()`；spec 上可以链 `.setup()` / `.teardown()` 挂按实验变化的环境钩子 |
 
 Experiment 本身是纯配置数据，没有 `setup` / `teardown` 这类字段。要在跑 agent 前按实验准备环境（装二进制、预热、跨 attempt 载入和回存状态），挂在 `sandbox` 字段的 spec 上：
 
@@ -112,12 +112,14 @@ Experiment 本身是纯配置数据，没有 `setup` / `teardown` 这类字段
 export default defineExperiment({
   agent: codexAgent({ mcpServers: [mempalMcp] }),
   sandbox: e2bSandbox({ template: "fasteval-agents" })
-    .setup(mempalSetup("codex"))        // 装二进制、预热、写 hook、载入状态
+    .setup(mempalSetup("codex"))        // 预检、写动态配置、预热、载入状态
     .teardown(mempalTeardown("codex")), // 回存状态
   maxConcurrency: 1,                    // 载入和回存之间不能并发，声明串行
 });
 ```
 
-钩子的执行时机、多钩子顺序和失败语义见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
+固定的 Agent CLI、系统包和大模型缓存应先做进 image/template/snapshot；`.setup()` 不应在每个 Attempt 重建同一套环境。如何从官方 Docker 镜像、E2B 模板或 Vercel runtime 继续派生来提速，见 [沙箱 provider · 从官方基线继续构建以提速](/zh/how-to/sandbox-providers#从官方基线继续构建以提速)。
 
-跨配置比较的设计建议见[实验矩阵](/zh/guides/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/concepts/adapter)。
+钩子的执行时机、多钩子顺序和失败语义见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
+
+跨配置比较的设计建议见[实验矩阵](/zh/how-to/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/explanation/adapter)。

package/docs-site/zh/{guides → how-to}/write-send.mdx

@@ -4,12 +4,13 @@ sidebarTitle: "如何写好 Send"
 description: "手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 flags。每一步只在上一步的代码上多几行，每一步解锁一组断言。"
 ---
 
-[Adapter](/zh/concepts/adapter) 讲了契约：`send` 传入 `TurnInput` 和 `AgentContext`，返回 `Turn`。这一页讲怎么写它——从"发一条消息拿到回复"的最小形态起步，一步一步加到完整接入。每一步只在上一步的代码上多几行，前面已有的部分在代码里用 `// ……省略` 标出；每一步末尾说明这几行解锁了哪些断言。改完任何一步都能立刻验证：把新解锁的断言写进一条 eval 重跑 `npx niceeval exp`，`niceeval view` 里能看到这一步新增的数据——多轮轨迹、用量、工具事件、待回答请求。
+[Adapter](/zh/explanation/adapter) 讲了契约：`send` 传入 `TurnInput` 和 `AgentContext`，返回 `Turn`。这一页讲怎么写它——从"发一条消息拿到回复"的最小形态起步，一步一步加到完整接入。每一步只在上一步的代码上多几行，前面已有的部分在代码里用 `// ……省略` 标出；每一步末尾说明这几行解锁了哪些断言。改完任何一步都能立刻验证：把新解锁的断言写进一条 eval 重跑 `npx niceeval exp`，`niceeval view` 里能看到这一步新增的数据——多轮轨迹、用量、工具事件、待回答请求。
 
-两个贯穿全文的原则：
+三个贯穿全文的原则：
 
-- **接的位置永远是用户前端本来就在用的那个接口。** 页面调哪个端点、收什么格式，Adapter 就调哪个端点、收什么格式——不为 eval 开新接口，也不 import 应用内部代码直调函数（为什么，见[接入你的 Agent](/zh/guides/connect-your-agent)）。
+- **接的位置永远是用户前端本来就在用的那个接口。** 页面调哪个端点、收什么格式，Adapter 就调哪个端点、收什么格式——不为 eval 开新接口，也不 import 应用内部代码直调函数（为什么，见[接入你的 Agent](/zh/how-to/connect-your-agent)）。
 - **你唯一真正手写的是 transport**——URL、鉴权、请求体每家本来就不一样。解析（原始返回 → 标准事件流）有官方转换器，从 `niceeval/adapter` 导出；编排（会话续接、HITL 暂停恢复）的状态槽就挂在 `ctx.session` 上，取用即可，不需要额外声明什么。
+- **运行反馈走 `ctx`，不直接写终端。** 长步骤用 `ctx.progress(...)`；需要在运行后回顾的退化或异常上下文用 `ctx.diagnostic(...)`；无法继续时抛错。不要从 Adapter 调用 `console.log/error` 或写 `process.stdout/stderr`。
 
 ![一次 t.send 的完整往返：eval 调用 t.send，运行器组装 TurnInput 与 ctx，adapter 调用你的应用并返回标准事件流 Turn。](/images/agent-turn-roundtrip-zh.svg)
 
@@ -38,6 +39,7 @@ const BASE_URL = "http://localhost:8080";   // 要按 experiment 切换地址，
 export default defineAgent({
   name: "chat-app",
   async send(input, ctx) {
+    ctx.progress({ message: "等待 Chat API" });
     const res = await fetch(`${BASE_URL}/v1/chat/completions`, {  // ← 前端本来就在用的接口
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -56,7 +58,21 @@ export default defineAgent({
 });
 ```
 
-**这一步解锁**：`t.reply`、`t.messageIncludes()`、judge 的全部对话材料，以及 experiment 侧的**模型对比**（`ctx.model` 就是 experiment 声明的 `model`，运行器原样递给你、Adapter 不解释含义，只转发——不需要等到后面的步骤，也不需要应用配合做任何改造，分档见 [Tier](/zh/concepts/tier)）。
+如果接口返回了可继续处理、但证据不完整的响应，报告 diagnostic 而不是把原始响应全部打印出来：
+
+```ts
+if (!res.requestId) {
+  ctx.diagnostic({
+    code: "missing-request-id",
+    level: "warning",
+    message: "响应没有 request id，无法与服务端日志关联",
+  });
+}
+```
+
+`progress` 不落盘；diagnostic 会随 Attempt 保存并可通过 locator 回顾。HTTP 连接失败或响应无法解析时直接抛错，runner 会记录错误发生在 `agent.run`，并把 Attempt 标为 `errored`。
+
+**这一步解锁**：`t.reply`、`t.messageIncludes()`、judge 的全部对话材料，以及 experiment 侧的**模型对比**（`ctx.model` 就是 experiment 声明的 `model`，运行器原样递给你、Adapter 不解释含义，只转发——不需要等到后面的步骤，也不需要应用配合做任何改造，分档见 [Tier](/zh/explanation/tier)）。
 
 它有两个明显的局限：每轮都是一场全新对话（第二次 `t.send` 接不上第一次），工具调用完全看不见。后面两步各解决一个。
 
@@ -137,7 +153,7 @@ export default defineAgent({
 
 ## 第四步：把工具解析成事件
 
-应用的返回里不只有回复文本——Chat Completions 形返回的 `tool_calls` 记录了这轮调过什么工具。Adapter 最重要的工作就是**把接口的返回归一成标准事件流**：本轮发生的每件事一个对象，按真实发生顺序排进 `Turn.events`，对象是下面十种类型之一（各字段的实际值，[契约页有一轮的完整示例](/zh/concepts/adapter)）：
+应用的返回里不只有回复文本——Chat Completions 形返回的 `tool_calls` 记录了这轮调过什么工具。Adapter 最重要的工作就是**把接口的返回归一成标准事件流**：本轮发生的每件事一个对象，按真实发生顺序排进 `Turn.events`，对象是下面十种类型之一（各字段的实际值，[契约页有一轮的完整示例](/zh/explanation/adapter)）：
 
 ```ts
 type StreamEvent =
@@ -210,7 +226,7 @@ type StreamEvent =
 应用中途停下来等人（工具审批、等补充信息）时，`send` 两侧各有义务：
 
 - **停轮**：返回 `status: "waiting"`，并且每个待回答的问题吐一条带稳定 `id` 的 `input.requested` 事件——`t.parked()`、`t.requireInputRequest()` 读它，回答靠这个 `id` 对位。
-- **回答轮**：eval 里的 `t.respond(...)` 到 Adapter 是**又一次普通的 `send`**（还是同一条会话线、同一份状态），人的裁决以结构化形式随 `input.responses` 到达，每条带 `requestId`、`optionId` 或 `text`（形态见[不同回答的入参](/zh/concepts/adapter#不同回答的入参)）。Adapter 先把裁决交回应用，再接着取结果。被人拒绝的调用，`action.result` 的 `status` 置 `"rejected"` 而不是 `"failed"`——拒绝是人的决定、不是工具故障，`noFailedActions()` 不误伤。
+- **回答轮**：eval 里的 `t.respond(...)` 到 Adapter 是**又一次普通的 `send`**（还是同一条会话线、同一份状态），人的裁决以结构化形式随 `input.responses` 到达，每条带 `requestId`、`optionId` 或 `text`（形态见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)）。Adapter 先把裁决交回应用，再接着取结果。被人拒绝的调用，`action.result` 的 `status` 置 `"rejected"` 而不是 `"failed"`——拒绝是人的决定、不是工具故障，`noFailedActions()` 不误伤。
 
 "停轮时读了一半的现场"（比如一条读到一半的 SSE 流）也存在 `ctx.session` 上：停轮时 `ctx.session.hold(现场)`，回答轮开头 `ctx.session.take()` 取回——取到即清除，一次消费。
 
@@ -268,7 +284,7 @@ export default defineAgent({
 });
 ```
 
-不需要 HITL 的接口，删掉停轮现场相关的三处（`Pending`、`hold`、开头的 `take` 分支）即可，其余不变。停轮 / 回答 / 续跑的完整心智模型见 [HITL](/zh/concepts/hitl)。
+不需要 HITL 的接口，删掉停轮现场相关的三处（`Pending`、`hold`、开头的 `take` 分支）即可，其余不变。停轮 / 回答 / 续跑的完整心智模型见 [HITL](/zh/explanation/hitl)。
 
 **这一步解锁**：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`，以及 `calledTool(..., { status: "rejected" })` 的精确断言。
 
@@ -302,7 +318,7 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces node server.js
 
 `ctx.telemetry` 只在配置了 OTel 接入时出现，没配时 spread 一个 `undefined` 也安全，这行可以常驻。不带这个头 span 也能收到，但归属退化成时间窗口、该 agent 的轮次会降为串行——带上它是并发下归属准确的来源。
 
-**这一步解锁**：`niceeval view` 里的调用瀑布图——应用内部每次模型调用、每次工具执行的耗时与 token，按轮铺成时间线。断言不变：判定依据在前几步的事件映射里已经齐了，span 只进瀑布图、不喂断言。接收器怎么起、span 怎么归属到轮，见 [OTel 接入](/zh/guides/connect-otel)。
+**这一步解锁**：`niceeval view` 里的调用瀑布图——应用内部每次模型调用、每次工具执行的耗时与 token，按轮铺成时间线。断言不变：判定依据在前几步的事件映射里已经齐了，span 只进瀑布图、不喂断言。接收器怎么起、span 怎么归属到轮，见 [OTel 接入](/zh/how-to/connect-otel)。
 
 ## 第七步：透传 experiment 的 flags（A/B 对比）
 
@@ -329,7 +345,7 @@ export default defineExperiment({
 });
 ```
 
-两个 experiment 文件各声明一份 `flags`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/concepts/tier)；`flags` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/guides/write-experiment)。
+两个 experiment 文件各声明一份 `flags`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/explanation/tier)；`flags` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/how-to/write-experiment)。
 
 **这一步解锁**：同一批 eval 跨变体的成绩对比。
 
@@ -347,8 +363,8 @@ export default defineExperiment({
 
 ## 相关阅读
 
-- [Adapter](/zh/concepts/adapter) — 契约本身：`send` 传入什么返回什么、三个接入等级、能力从哪来。
-- [接入你的 Agent](/zh/guides/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
-- [HITL](/zh/concepts/hitl) — 停轮等人的完整概念：握手时序与两侧义务。
-- [Drive](/zh/concepts/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
-- [Assert](/zh/concepts/assert) — 标准事件流驱动的完整断言词汇。
+- [Adapter](/zh/explanation/adapter) — 契约本身：`send` 传入什么返回什么、三个接入等级、能力从哪来。
+- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
+- [HITL](/zh/explanation/hitl) — 停轮等人的完整概念：握手时序与两侧义务。
+- [Drive](/zh/explanation/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
+- [Assert](/zh/explanation/assert) — 标准事件流驱动的完整断言词汇。

package/docs-site/zh/index.mdx

@@ -19,14 +19,14 @@ description: "NiceEval 是一个渐进式、全功能、开发体验友好、Age
 eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告和结构化 artifacts，让你能查看 agent 的行为细节，调试失败原因，并持续优化 pass rate、成本和延迟。
 
 <CardGroup cols={3}>
-  <Card title="Claude Code / Codex 插件" icon="plug" href="/zh/example/claude-code-codex-plugin">
-    用 sandbox workspace 让 coding agent 跑真实任务，再用测试、diff 和工具调用记录验证插件行为。
+  <Card title="Agent Framework 接入" icon="code-branch" href="/zh/examples">
+    对照 AI SDK、Claude SDK、Codex SDK、pi-agent-core 和 LangGraph 的可运行接入项目。
   </Card>
-  <Card title="Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
-    用 experiment setup 注入 Skill，再与无 Skill baseline 批量比较通过率、成本和行为差异。
+  <Card title="Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    用真实 Workspace 和对照实验衡量 Skill、提示词与 Plugin Benchmark 的实际收益。
   </Card>
-  <Card title="AI Agent 应用" icon="globe" href="/zh/example/ai-agent-application">
-    用 `defineAgent` 包装你的 AI Agent，把回复、工具调用和结构化输出纳入同一套 eval。
+  <Card title="自写 Adapter" icon="globe" href="/zh/examples/ai-agent-application">
+    查看一个覆盖工具、图片、多轮、模型对比和 OTel 的完整 AI Agent 项目。
   </Card>
 </CardGroup>
 
@@ -86,13 +86,13 @@ eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告
 
 | 概念 | 一句话 |
 |---|---|
-| [Eval](/zh/concepts/evals) | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
-| [Experiment](/zh/concepts/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
-| [Adapter](/zh/concepts/adapter) | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
-| [Sandbox](/zh/guides/sandbox-providers) | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
-| [Tier](/zh/concepts/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
+| [Eval](/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 不需要。 |
+| [Tier](/zh/explanation/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
-完整术语表见[架构概览](/zh/concepts/overview)。
+完整术语表见[架构概览](/zh/explanation/overview)。
 
 ## 示例
 
@@ -142,23 +142,21 @@ npx niceeval view       # 网页交互浏览
 
 ## 快速开始
 
-如果你想让 coding agent 直接帮项目接入 [NiceEval](https://niceeval.com/)，可以把对应场景页交给它读：
+如果你想让 Coding Agent 直接帮项目接入 [NiceEval](https://niceeval.com/)，让它先读安装入口：
 
 ```text
-READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/claude-code-codex-plugin.mdx and install niceeval for this repo.
-READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/claude-code-codex-skill.mdx and install niceeval for this repo.
-READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/ai-agent-application.mdx and install niceeval for this repo.
+READ https://niceeval.com/INIT.md and install niceeval for this repo.
 ```
 
 <CardGroup cols={3}>
-  <Card title="如果你需要 eval 你的 Claude Code / Codex 插件" icon="plug" href="/zh/example/claude-code-codex-plugin">
-    从真实插件任务出发，上传 workspace、注入插件，并用 pass rate 看插件是否稳定工作。
+  <Card title="浏览所有可运行示例" icon="grid-2" href="/zh/examples">
+    按被测对象选择接入前后源码和完整项目。
   </Card>
-  <Card title="如果你需要 eval 你的 Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
-    验证 Skill 是否被加载、是否按约定使用工具、是否产出可测试结果。
+  <Card title="评估 Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    复用真实 Workspace、Baseline 和多 Arm 实验设计。
   </Card>
-  <Card title="如果你需要 eval 你的 AI Agent 应用" icon="globe" href="/zh/example/ai-agent-application">
-    包装你的 agent 接口，写对话、工具调用、结构化输出和成本断言。
+  <Card title="自写 Adapter" icon="globe" href="/zh/examples/ai-agent-application">
+    查看自定义 HTTP 协议和事件映射的完整项目。
   </Card>
 </CardGroup>
 
@@ -166,16 +164,16 @@ READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/doc
 
 <AccordionGroup>
   <Accordion title="需要注册账号吗？">
-    不需要。跑 eval 和 `niceeval view` 看报告全在本地完成；只有被测对象本身是需要隔离工作区的 coding agent 时，才会用到 Docker 或 E2B 这类 sandbox 后端。
+    不需要。跑 eval 和 `niceeval view` 看报告全在本地完成；只有被测对象本身是需要隔离工作区的 coding agent 时，才会用到 Docker 或 E2B 这类 sandbox provider。
   </Accordion>
   <Accordion title="我的 Agent 不是用 TypeScript / JavaScript 写的，能接吗？">
-    能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发；应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/concepts/adapter)。
+    能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发；应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/explanation/adapter)。
   </Accordion>
   <Accordion title="能接到 CI 里吗？">
-    能，见 [CI 集成](/zh/guides/ci-integration)。
+    能，见 [CI 集成](/zh/how-to/ci-integration)。
   </Accordion>
 </AccordionGroup>
 
 <Tip>
-  想先走最小路径，读 [快速开始](/zh/quickstart)。想理解边界，读 [架构概览](/zh/concepts/overview)。
+  想先走最小路径，读 [快速开始](/zh/tutorials/quickstart)。想理解边界，读 [架构概览](/zh/explanation/overview)。
 </Tip>

package/docs-site/zh/introduction.mdx

@@ -120,22 +120,22 @@ NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「
 | Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
 | Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
-完整术语表见[架构概览](/zh/concepts/overview)。
+完整术语表见[架构概览](/zh/explanation/overview)。
 
 ## 从你的场景开始
 
 <CardGroup cols={3}>
-  <Card title="评估 Claude Code / Codex 插件" icon="puzzle-piece" href="/zh/example/claude-code-codex-plugin">
-    把插件放进真实 workspace，比较有插件和无插件时的通过率、成本、耗时和行为差异。
+  <Card title="接入 Agent Framework" icon="code-branch" href="/zh/examples">
+    选择 AI SDK、Claude SDK、Codex SDK、pi-agent-core 或 LangGraph 的可运行接入示例。
   </Card>
-  <Card title="评估 Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
-    对比有 Skill 和无 Skill 的 coding-agent 任务，衡量 Skill 是否真的提升结果。
+  <Card title="评估 Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    用真实 Workspace 和对照实验衡量 Skill、提示词与 Plugin Benchmark 的效果。
   </Card>
-  <Card title="评估你的 AI Agent 应用" icon="robot" href="/zh/example/ai-agent-application">
-    直连你自己的应用接口，断言工具调用、图片理解和多轮会话。
+  <Card title="自写 Adapter" icon="robot" href="/zh/examples/ai-agent-application">
+    查看自定义 HTTP Agent 的工具调用、图片理解、多轮会话和模型对比。
   </Card>
 </CardGroup>
 
 ## 接下来读什么
 
-[快速开始](/zh/quickstart) 会带你安装 [NiceEval](https://niceeval.com/)、构建 eval、得到评估报告。
+[快速开始](/zh/tutorials/quickstart) 会带你安装 [NiceEval](https://niceeval.com/)、构建 eval、得到评估报告。