niceeval 0.12.1 → 0.12.2-canary.31

package/docs-site/zh/troubleshooting/debugging.mdx

@@ -1,248 +1,78 @@
 ---
-title: "排查失败与复盘历史运行"
-sidebarTitle: "Debug 手册"
-description: "一份按场景组织的排查手册：断言失败怎么定位、环境错误怎么进 Sandbox、agent 改了什么怎么看、旧的运行怎么翻出来复盘——每一步都有命令顺序和输出示例。"
+title: "排查 Record 与报告问题"
+sidebarTitle: "排查手册"
+description: "根据可见错误、Sample 状态、Attachment 状态和 rebuild 反馈，定位查看、重跑与导出问题。"
 ---
 
-跑完一次 `niceeval exp`，失败的 Attempt 都带一个 `@` 开头的定位符（如 `@1qrdcfq8`）。它出现在运行摘要、CI 日志和报告里，定位符本身不会过期——只要 `.niceeval/` 里对应的结果快照还在，今天的定位符下周还能用同一条命令打开同一次 Attempt。所有排查都从它开始。
+先用明确 Run 读取问题，不要从目录名或时间猜测目标。
 
-先说一条通用规则：NiceEval 自己的报错和警告都在消息末尾直接给出下一步。能用一条命令解决的，消息里就是替换好实验名的完整命令，复制执行即可（网页里还可以一键复制）；可以不管的警告会写明「什么情况下可以忽略」。所以看到报错先读完最后一句；本手册处理的是消息之外还需要人工判断的场景——判定失败了怎么定位、环境错误怎么进现场。
-
-## 第一步永远是 `niceeval show @<定位符>`
-
-不带任何参数打开 Attempt，第一页就是为排查设计的：判定、失败的断言、耗时分布、改动概览，以及下一步可用的命令。
-
-```text
-$ niceeval show @1qrdcfq8
-@1qrdcfq8 · memory/swelancer-manager-proposals · dev-e2b/codex-e2b · failed
-snapshot 2026-07-12T10:08:29.361Z · attempt 1 · 50.0s · 58.5k tokens · $0.05
-
-assertions: 3 passed · 1 gate failed
-eval source: evals/memory/swelancer-manager-proposals.eval.ts · sha256:ee33b9c4…
-
-✗ 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: 12 events · 0 skill loads · 7 tool calls · 4 AI messages
-timing: sandbox.queue 0.2s · sandbox.create 5.6s · sandbox.setup 3.5s · agent.setup 12.1s ·
-        eval.run 26.3s · workspace.diff 0.3s · assertions.evaluate 1.4s · teardown +0.8s
-
-changes: 2 files changed by agent · M manager_decisions.json · A notes/decision-log.md
-
-available:
-  niceeval show @1qrdcfq8 --source
-  niceeval show @1qrdcfq8 --execution
-  niceeval show @1qrdcfq8 --timing
-  niceeval show @1qrdcfq8 --diff
+```sh
+npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
+npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --page /
 ```
 
-看这一页先回答一个问题：**是 agent 答错了（`failed`），还是环境根本没跑起来（`errored`）？** 两种情况的排查路线完全不同。
+Record reader 只看已经带 `complete` 的 Run。它冻结本次可见的集合；正在写入的目录不会混进 Sample。
 
-## 场景一：断言失败（failed）——agent 跑完了，但结果不对
+## 找不到或无法打开 Record
 
-排查顺序是「哪条断言挂了 → agent 当时做了什么 → 它到底改了什么」。
+| 可见错误 | 含义 | 下一步 |
+| --- | --- | --- |
+| `record-root-missing` | 指定的 Record 根目录不存在。 | 检查项目目录或 `--record` 参数。 |
+| `record-migration-required` | Core 是已知旧 major。 | 运行 `niceeval migrate`。 |
+| `record-format-unsupported` | 当前 NiceEval 不认识该 Core major。 | 安装支持该格式的 NiceEval。 |
+| `core-invalid` | 已完成 Run 的 Core 或引用不能可靠读取。 | 查看具名 issue；不要把它当成缺失结果。 |
 
-**1. 把断言放回源码。** `--source` 显示运行时保存的源码调用树，不读取工作区里的后来版本。入口
-文件是主干；共享 helper 中的失败断言内联在入口调用行下。调用链缺失时，helper 片段按文件列在
-主干之后，不会落进未映射断言。`t.send(...)` 的调用行还会标出对应 Turn 的状态和耗时：
+不要用空值替代这些结果。已发布的 Record 不提供手工编辑修复路径；需要不同事实时创建新的 Run。格式迁移使用 `niceeval migrate`，未完成目录使用 `niceeval clean`。
 
-```text
-$ niceeval show @1qrdcfq8 --source
-21✓     await t.send("Review the proposals and record your decision…");
-    turn1 · completed · 22.4s
-38      for (const [issue, label] of Object.entries(expected)) {
-39        await t.group(`Issue ${issue}: selected proposal matches…`, async () => {
-40✗         t.check(Number(decisions[issue]?.selected_proposal_id), equals(label.selected_proposal_id));
-    gate · Issue 15193 · equals(4) · expected 4 · received 1
-41        });
-42      }
-```
+## Sample 中缺少预期结果
 
-**2. 看 agent 当时做了什么。** `--execution` 把这次 Attempt 的对话按时间线展开——用户消息、assistant 回复、每次工具调用的入参和结果：
+Sample 会保留 Run 的 expected-slot 分母。查看页面上每个 slot 的状态：
 
-```text
-$ niceeval show @1qrdcfq8 --execution
-turn1 · completed · 22.4s · 12.4k tok · $0.02
-  USER
-    Review the proposals and record your decision for each issue…
+| 状态 | 含义 | 下一步 |
+| --- | --- | --- |
+| `included` | Member 和 Attempt 可读。 | 检查需要的 Attachment。 |
+| `not-recorded` | expected slot 没有 Member。 | 检查 Invocation 是否完成，或重新运行该范围。 |
+| `core-invalid` | Member、Attempt 或引用有问题。 | 处理具名 issue，不要把它当成未采集。 |
+| `excluded` | 本次选择排除了该项。 | 检查 `--experiment`、`--eval` 或其他选择条件。 |
 
-  ASSISTANT
-    I'll inspect the task layout and the decision format first…
+需要判断下一次运行会做什么时，先执行：
 
-  TOOL · command_execution  +12.8s · 1.3s
-    input
-      /bin/bash -lc 'cat tasks/15193/proposals.md'
-    result · completed · exit 0
-      Proposal 1: …
+```sh
+npx niceeval exp checkout --dry
 ```
 
-对话按轮分段，每轮头行给出轮标签（`turn1`）、状态、耗时和用量——这个标签和 `--diff`、`--timing` 里的轮次标签是同一套，能互相对照。
+输出会显示每个 slot 会执行还是沿用已有 Attempt，并列出沿用条件不满足的原因。
 
-不想通读全文时，接 `grep` 定向查。列出这次 Attempt 用过哪些工具、各多少次：
+## Attachment 显示不可用
 
-```text
-$ niceeval show @1qrdcfq8 --execution | grep "TOOL ·" | sort | uniq -c
-   5   TOOL · command_execution
-   2   TOOL · file_change
-```
+一个 RecordAttachment 的状态只影响请求它的 Page、PageFamily、Calculation 或 Download：
 
-想确认它有没有跑过某条命令、有没有提到某个文件，直接搜关键词：
+| 状态 | 含义 | 下一步 |
+| --- | --- | --- |
+| `unavailable` | owner 没有这个 Attachment。 | 确认它是否适用于这次运行。 |
+| `migration-required` | 有完整相邻 converter 链。 | 运行 `niceeval migrate`。 |
+| `migration-unavailable` | 不能从历史事实无损形成当前值。 | 使用能读取历史值的功能，或发布新的 Run。 |
+| `unsupported` | 当前功能不认识该 schema。 | 安装 owning plugin，或查看不依赖它的页面。 |
+| `invalid` | envelope、payload 或 blob 无效。 | 阅读具名 issue；其它 Attachment 仍可读取。 |
 
-```bash
-niceeval show @1qrdcfq8 --execution | grep proposals
-```
+未请求的坏 Attachment 不会阻止无关页面。`require-complete` consumer 显示 data-unavailable；`allow-partial` consumer 可显示完整分母与问题。
 
-超长的工具结果只显示前 3 行预览，但截断尾巴自带这张卡片的展开句柄——整行复制就是看全量的下一条命令，不用去翻 `events.json`：
+## view 没有显示新的结果
 
-```text
-  result · completed · exit 0
-    Proposal 1: …
-    (+412 lines · 18553 chars · niceeval show @1qrdcfq8 --execution --expand t1.c17)
+`view` 每次成功 rebuild 才发布一份新的 `ReportExecution`。如果 Report、配置、主题或 Record 的变化导致 rebuild 失败，页面继续显示 last-good execution，并显示本次问题。
 
-$ niceeval show @1qrdcfq8 --execution --expand t1.c17    # 只输出这张卡片，完整不截断
-```
+先修复 rebuild problem，再等待下一次成功 rebuild。页面刷新本身不会绕过这个边界，也不会让旧 execution 重新读取 Record。
 
-**3. 看它到底改了什么。** `--diff` 只显示 **agent 自己改动的文件**——你上传的起始文件、跑完后写入的验证材料不会混在里面，所以列表里的每一行都真的是 agent 干的：
+## JSON 中没有 receipt
 
-```text
-$ niceeval show @1qrdcfq8 --diff
-2 files changed by agent
-  M manager_decisions.json   +6 -2    turn1, turn2
-  A notes/decision-log.md    +18      turn2
+`npx niceeval exp <experiment> --json` 只有在成功建立 Invocation 后，最后才会输出 receipt。命令在建立 Invocation 前就因输入错误退出时，没有 `runIds` 可读取。
 
-single file: niceeval show @1qrdcfq8 --diff=manager_decisions.json
-```
+先修正 Experiment、Eval 选择或命令参数，再重新运行。成功时，使用 receipt 的 `runIds` 运行 `show`、`view` 或 `view --out`。
 
-行尾的 `turn1` 表示这个文件是在第几轮对话里被改的，能和 `--execution` 的轮次对上。要看单个文件的逐行改动，用 `=` 连写文件路径：
+## 静态报告站无法导出
 
-```text
-$ niceeval show @1qrdcfq8 --diff=manager_decisions.json
-M manager_decisions.json · changed in turn1, turn2
-@@ -1,5 +1,7 @@
- {
--  "15193": { "selected_proposal_id": 1 },
-+  "15193": { "selected_proposal_id": 4 },
-```
-
-到这里通常能下结论：是任务描述有歧义、agent 理解错了，还是断言本身写得太死。
-
-**要看文件本身，而不只是改动？** 落盘的证据刻意不保存整个工作区——`--diff` 只有 agent 改过的文件，agent 该写没写的文件、你上传的起始材料、setup 装出来的东西都不在里面。想看它们的实际内容，进活现场：重跑这一条评估用例加 `--keep-sandbox`（`failed` 的 Attempt 同样会保留，不只是环境错误），用下面场景二的方式进 Sandbox，workdir 里就是这次跑完时的完整文件树。
-
-## 场景二：环境错误（errored）——agent 根本没跑起来
-
-`errored` 的第一页不列断言，而是列出错误发生在哪个阶段、什么原因：
-
-```text
-$ niceeval show @12h8m4k1
-@12h8m4k1 · memory/agent-029-use-cache · compare/claude-e2b · errored
-
-error:
-  phase: sandbox.create
-  code: sandbox-rate-limit
-  message: E2B sandbox allocation failed after 5 attempts
-  cause: RateLimitError · too many concurrent sandboxes
-
-execution: unavailable (attempt failed before telemetry was configured)
-timing: sandbox.queue 1.2s · sandbox.create 2m 6s ✗ failed here
-```
-
-`phase` 直接告诉你死在哪一步，而且决定了下一步走哪条路：
-
-**`sandbox.create` 失败——Sandbox 根本没创建出来，没有现场可留。** 这类错误（配额、限流、凭据、镜像 / 模板不存在）在你自己的机器和账号侧排查：核对 API key 和配额、降低 `--max-concurrency`、确认镜像 / 模板名。示例里的 rate-limit 就属于这类，重跑加 `--keep-sandbox` 只会原地再死一次。
-
-**`sandbox.setup` / `agent.setup` / `eval.run` 失败——Sandbox 活过，值得留现场。** 装依赖失败、agent CLI 起不来、跑到一半超时，这类问题事件流往往是空的，落盘证据帮不上忙，最快的办法是留住现场进去手动重跑一遍出错的命令：
-
-```bash
-# 只重跑这一条 eval，失败时保留沙箱
-npx niceeval exp compare memory/agent-029 --keep-sandbox
-```
+`view --out` 只导出一个已经完成的 `ReportExecution`。recorded-data problem 可以进入导出站并保持可见；projector 或作者 callback defect、非法 semantic tree 和 route conflict 会让导出停止。
 
-```text
-Kept sandboxes (1)
-  @18c1m2qx  memory/agent-029-use-cache #1  errored  docker · a3f9c2d1
-             enter: niceeval sandbox enter a3f9c2d1
-Stop them with: niceeval sandbox stop --all
-```
-
-`niceeval sandbox enter a3f9c2d1` 会唤醒现场并在 workdir 打开 shell——手动执行安装命令看真实报错、翻 `$HOME` 下的配置、检查 `PATH`，这些都在 artifact 之外，只有活现场能回答；退出 shell 后现场自动回到休眠，不白烧资源。保留策略、各 provider 的差别见[保留 Sandbox 现场](/zh/troubleshooting/debug-sandbox)。
-
-## 查看和清理留下的 Sandbox
-
-保留下来的 Sandbox 不会一直烧资源：Docker 容器停驻在磁盘上，E2B 微 VM 暂停计费，进入时自动唤醒。用 `niceeval sandbox` 管理：
-
-```text
-$ niceeval sandbox list
-ID        PROVIDER  STATE            FROM
-a3f9c2d1  docker    dormant          memory/agent-029-use-cache #1 · errored · @18c1m2qx · 2026-07-14 15:02
-            enter: niceeval sandbox enter a3f9c2d1
-9f21c07b  vercel    expired          onboarding/tool-first #2 · failed  · @1x7f3q8a · 2026-07-14 14:31
-            expired 2026-07-14 14:36 — remove with: niceeval sandbox stop 9f21c07b
-```
-
-`dormant` 是「睡着但随时能进」，`expired` 是「现场已经没了，只剩记录」。排查完记得清理：
-
-```bash
-niceeval sandbox stop a3f9c2d1     # id 可以只写唯一前缀
-niceeval sandbox stop --all
-```
-
-## 场景三：复盘旧的运行
-
-每次运行都会在 `.niceeval/<实验>/<时间戳>/` 下留一份完整的结果快照，判定、断言、事件流、diff 都在里面，**不会被下一次运行覆盖**。复盘有三个入口：
-
-**用旧定位符直接打开。** 从上周的终端记录、CI 日志或报告里复制 `@` 定位符，`niceeval show @<定位符>` 照常工作，上面的 `--source` / `--execution` / `--diff` 全部可用——包括那份运行时的评估用例源码，哪怕你后来把评估用例改了。
-
-**按实验回看现在的判定。** 不记得定位符时，从实验入手：
-
-```bash
-niceeval show --exp compare/bub        # 这个实验每道题现在的判定
-niceeval show memory/swelancer --exp compare/bub   # 收窄到某道题
-```
-
-列表里每道题、每次 Attempt 都带定位符，接着往深处钻就回到上面的场景一 / 场景二。
-
-**同一个检查刷一批 Attempt。** 从实验列表里复制定位符，套一层循环。比如核对这几次 Attempt 里谁调用过 `file_change`：
-
-```bash
-for loc in @1qrdcfq8 @1x7f3q8a @18c1m2qx; do
-  echo "== $loc"
-  niceeval show $loc --execution | grep "TOOL · file_change"
-done
-```
-
-**在浏览器里翻。** 复盘一批失败、对比多次 Attempt 时，网页比终端顺手：
-
-```bash
-niceeval view
-```
-
-首页是成本 × 通过率总览和实验对比表；每个 Attempt 的详情页有判定、断言、完整时间树、对话、trace 和[按路径排成树的文件改动](/zh/tutorials/viewing-results#attempt-详情里的文件改动)，还有「Copy fix prompt」按钮——把失败整理成一段可以直接交给 coding agent 的修复提示词。报告里的 Attempt 深链和 `show` 用同一套定位符。
-
-**打开归档或别人发来的结果。** 结果目录是自包含的——从 CI 下载的、同事拷给你的、发布到静态站前生成的目录，都能直接指过去：
-
-```bash
-niceeval show --record tmp/ci-artifacts/record
-niceeval view --record site-data/run
-```
+目标目录必须不存在。写入在最后留下 `complete` marker；失败或中断可能留下没有 marker 的目录。删除那个未完成目录后重试。
 
-一个注意点：如果本地清理过旧快照目录，之后的运行里「沿用上次结果」的条目会找不到原始证据（显示为缺失）。要长期归档某次运行，先用 [`publish`](/zh/reference/results-data) 复制出一份再删。
-
-## 速查：症状 → 命令
-
-| 症状 | 命令顺序 |
-|---|---|
-| 断言挂了，不知道为什么 | `show @loc` → `show @loc --source` |
-| 想知道 agent 当时做了什么 | `show @loc --execution` |
-| 想确认有没有调用过某个工具 / 搜对话关键词 | `show @loc --execution \| grep "TOOL ·" \| sort \| uniq -c` / `\| grep <关键词>` |
-| 工具结果被截断，想看完整内容 | 复制截断尾巴里的命令：`show @loc --execution --expand t2.c3` |
-| 想确认 agent 改了哪些文件 | `show @loc --diff` → `--diff=<path>` |
-| 哪一步慢 / 超时死在哪 | `show @loc`（看 `timing:` 行）→ `show @loc --timing` |
-| Sandbox 创建就失败（配额 / 凭据 / 镜像） | `show @loc` 看 error 的 code 与 cause → 查账号配额、核对凭据、降 `--max-concurrency`（没有现场可留） |
-| 装依赖失败、CLI 起不来、跑一半超时 | 重跑该评估用例加 `--keep-sandbox` → `niceeval sandbox enter <id>` |
-| 想看文件实际内容（agent 没改的、起始材料、`$HOME`） | 重跑加 `--keep-sandbox`（failed 也留）→ `sandbox enter` 进 workdir 看 |
-| 留了哪些 Sandbox、清理 | `sandbox list` → `sandbox stop <id>` / `--all` |
-| 复盘上周那次失败 | 翻出旧定位符 → `show @loc`；不记得就 `show --exp <实验>` |
-| 一批失败一起看 | `niceeval view` → Attempt 详情 → Copy fix prompt |
+更多操作步骤见[查看结果](/zh/tutorials/viewing-results)和[发布静态报告](/zh/tutorials/publish-report)。

package/docs-site/zh/troubleshooting/recover-after-kill.mdx

@@ -39,9 +39,9 @@ f31b9a02  docker    pid 4242@mbp dead  2026-07-20 14:02   orphan
 niceeval sandbox prune
 ```
 
-- `orphan` 表示属主进程已确认死亡，可以安全销毁；正在跑的运行的实例不会出现在列表里。
+- `orphan` 表示属主进程已确认死亡，可以安全销毁。正在跑的运行的实例不会出现在列表里。
 - 多容器题目（Compose）的伴随容器和网络跟随主实例整组列出、整组销毁，不需要再手工 `docker rm` 收尾。
-- 从别的机器创建、无法核对的实例标为 `unverified`，默认不动；确认后用 `niceeval sandbox prune --force`。
+- 从别的机器创建、无法核对的实例标为 `unverified`，默认不动。确认后用 `niceeval sandbox prune --force`。
 - Vercel Sandbox 无法按元数据核对，到 Provider 的保留期限后自动回收，不需要处理。
 - `--keep-sandbox` 留存的现场不受 `prune` 影响，仍用 `niceeval sandbox stop` 管理。
 
@@ -54,7 +54,7 @@ niceeval exp compare/bub-e2b --teardown
 ```
 
 - 只执行选中实验的 `teardown`，不跑任何评估、不跑 `setup`。
-- 随时可以执行，不依赖上次运行留下的记录；`teardown` 自身要能容忍重复执行。
+- 随时可以执行，不依赖上次运行留下的记录。`teardown` 自身要能容忍重复执行。
 - 强杀后原进程的内存已经丢失，`teardown` 里要从容器名、pid 文件或幂等的关停脚本这类持久信息找回要关的资源，不要依赖 `setup` 存在内存里的对象。
 
 ## 预防：让下一次强杀无害