niceeval 0.13.4-canary.49 → 0.14.0

package/docs-site/zh/reference/cli.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "CLI"
 description: "用固定的 query、show 和 view 读取 canonical SQLite Record。"
 ---
 
-运行评估使用 `niceeval exp`。运行完成后，NiceEval 提供三条读取路径：给 AI、脚本和 CI 的 `niceeval query`，给终端中人读的 `niceeval show`，以及在浏览器中审阅的 `niceeval view`。三者都只读取已封口的 Record。
+运行评估使用 `niceeval exp`。NiceEval 提供三条读取路径：给 AI、脚本和 CI 的 `niceeval query`，给终端中人读的 `niceeval show`，以及在浏览器中审阅的 `niceeval view`。三者都经固定 Inspection operation 读取一个 `PublicationCutoff` 内的已发布事实；origin Run 仍为 `active` 的 Attempt 也可见。
 
 ## `niceeval query`
 
@@ -22,7 +22,7 @@ niceeval query run [--record <file>] --request <file|->
 
 先调用 `discover`，再从返回的 schema 构造 request。不要猜字段，也不要用 SQL、JSON path 或公式拼出另一种查询语言。
 
-continuation token 绑定 operation、canonical request、content identity 和 sealed cutoff。任一绑定变化都会得到 restart correction。
+continuation token 绑定 operation、canonical request、source identity 和 `PublicationCutoff`。任一绑定变化都会得到 restart correction。
 
 ## `niceeval show`
 
@@ -38,7 +38,7 @@ niceeval show @<locator> --usage [--record <file>]
 niceeval show @<locator> --diff [--record <file>]
 ```
 
-`show` 是固定的终端排版入口。省略 selector 时显示默认 overview。`--run <run-id>` 显示一个精确的 sealed Run，可重复传入。`--experiment <experiment-id>` 显示一个精确的 Experiment，也可重复传入。
+`show` 是固定的终端排版入口。省略 selector 时显示默认 overview。`--run <run-id>` 显示一个精确 Run，可重复传入。`--experiment <experiment-id>` 显示一个精确 Experiment，也可重复传入。
 
 `@<locator>` 选择一个 Attempt。它不能与 `--run` 或 `--experiment` 一起使用，后两者也不能一起使用。一个命令最多只能给出一个 Attempt locator。
 
@@ -54,11 +54,11 @@ niceeval show @<locator> --diff [--record <file>]
 niceeval view [--run <run-id>...] [--no-open] [--port <port>] [--json]
 ```
 
-`view` 是固定的第一方本地 Insight。省略 `--run` 时打开默认 overview；重复 `--run` 可选择多个 sealed Run。它不接受位置参数，也不装载项目页面、主题、组件或 renderer。
+`view` 是固定的第一方本地 Insight。省略 `--run` 时打开默认 overview；重复 `--run` 可预选多个 exact Run。它不接受位置参数，也不装载项目页面、主题、组件或 renderer。
 
-`--no-open` 不请求操作系统打开浏览器。`--port` 选择 loopback port。`--json` 输出 `niceeval.view-lifecycle/v1` NDJSON 的 `ready`、`closed` 或 `failed` lifecycle event，而不是结果 JSON。`ready` 中的 URL 含一次性 fragment credential；不要上传原始 stdout。
+`--no-open` 不请求操作系统打开浏览器。`--port` 选择 `127.0.0.1` listener 的端口。SPA assets、本机授权 session 与 generation-bound Inspection endpoint 就绪后，命令向 stdout 写出一次可打开的 loopback URL。传入 `--json` 时改为输出 `niceeval.view/v1` NDJSON 的 `ready` 与 `closed` lifecycle event。启动或运行失败通过退出码与 stderr 反馈。
 
-没有 `--record` 时，View 从项目 canonical `.niceeval/record.sqlite` 读取 cutoff，并可在新发布后提示 refresh。使用 `--record` 时，View 先完整校验外部 SQLite 文件，再固定该 generation；它不会 watch、迁移、修补或部分读取。
+View 只读取项目 canonical `.niceeval/record.sqlite`。新 publication 出现后，页面提示 refresh；用户确认后才切换到新的 cutoff。它不提供 `--record`、SQL、部署、分享、Report、Page、theme、renderer、route 或 operation 参数。
 
 ## 选择读取方式
 
@@ -66,7 +66,7 @@ niceeval view [--run <run-id>...] [--no-open] [--port <port>] [--json]
 | --- | --- |
 | 让脚本、AI 或 CI 发现并取得稳定 JSON | `niceeval query discover`，再用 `explain` / `run` |
 | 在终端审阅 overview、Run、Experiment 或 Attempt 的固定摘要 | `niceeval show` |
-| 在浏览器审阅 overview 或某个 Attempt | `niceeval view` |
+| 在浏览器审阅 overview 或某个 Run | `niceeval view` |
 | 把同一份事实交给另一台兼容 runtime | 复制 `.niceeval/record.sqlite`，再传入 `--record` |
 
 ## CLI flags
@@ -116,6 +116,7 @@ niceeval view [--run <run-id>...] [--no-open] [--port <port>] [--json]
 | `--help` | `niceeval query` | boolean | 打印该命令的帮助。 |
 | `--run` | `niceeval show` | string[] | 显示一个已封口的 Run；可重复传入。 |
 | `--experiment` | `niceeval show` | string[] | 显示一个精确的 Experiment；可重复传入。 |
+| `--all` | `niceeval show` | boolean | 显示紧凑 Results 视图中隐藏的 Attempt。 |
 | `--source` | `niceeval show` | boolean | 显示一个 Attempt 已捕获的 source facts。 |
 | `--execution` | `niceeval show` | boolean | 显示一个 Attempt 的有界 execution outline。 |
 | `--timing` | `niceeval show` | boolean | 显示一个 Attempt 已捕获的 timing activities。 |

package/docs-site/zh/troubleshooting/debug-sandbox.mdx

@@ -4,12 +4,12 @@ sidebarTitle: "保留 Sandbox 现场"
 description: "用 --keep-sandbox 把失败 Attempt 的 Sandbox 保留成可随时唤醒的现场，用 niceeval sandbox enter 进去手动排查，用 sandbox list / stop 查看和清理。"
 ---
 
-Sandbox 默认在每个 Attempt 结束后销毁，排查依据是已封口的 artifact：在 `niceeval view` 中打开 Attempt detail，或通过 `query` 的固定 operation 读取判定、断言、diff 和事件流。完整路线见 [Debug 手册](/zh/troubleshooting/debugging)。
+Sandbox 默认在每个 Attempt 结束后销毁。先在 `niceeval view` 中打开对应 Run 或 Attempt，或通过 `query` 的固定 operation 读取判定、断言、diff、命令和事件流。完整路线见 [Debug 手册](/zh/troubleshooting/debugging)。
 
 但有些问题只能进活的环境里看：
 
 - **环境起不来**——setup 阶段装依赖失败、agent CLI 启动不了。这时 agent 还没开始跑，事件流是空的，最快的办法是进 Sandbox 手动重跑一遍安装命令。
-- **改动落在 `git diff` 之外**——全局装了什么包、`$HOME` 下写了什么配置、`PATH` 实际是什么，artifact 里没有。
+- **改动落在 `git diff` 之外**——全局装了什么包、`$HOME` 下写了什么配置、`PATH` 实际是什么，已发布的 File Changes 不包含这些内容。
 - **重跑太慢**——冷启动加安装要几分钟，想逐条验证猜测时，留着现场比每次重跑快得多。
 
 ## 跑的时候保留现场
@@ -30,13 +30,13 @@ Kept sandboxes (1)
 Stop them with: niceeval sandbox stop --all
 ```
 
-每行给三样东西：Attempt identity、Sandbox 实例 id、进入现场的命令。落盘证据从 `niceeval view @<attempt-locator>` 查看。保留下来的 Sandbox 不会一直跑着烧资源——Docker 容器停在磁盘上，E2B 微 VM 暂停计费，Vercel 保存文件系统。
+每行给三样东西：Attempt identity、Sandbox 实例 id、进入现场的命令。落盘证据从 `niceeval view --run <run-id>` 中选择对应 Attempt 查看。保留下来的 Sandbox 不会一直跑着烧资源——Docker 容器停在磁盘上，E2B 微 VM 暂停计费，Vercel 保存文件系统。
 
 `niceeval sandbox enter` 会先唤醒再进入，在 workdir 打开 shell。退出 shell 后现场自动回到休眠；想让它保持运行，加 `--leave-running`。进去之后就是这次 Attempt 跑完时的环境，可以手动执行命令、翻文件、复现失败。
 
 ## 查看和清理
 
-保留下来的 Sandbox 逐条记录在 `.niceeval/sandboxes/` 里，用 `niceeval sandbox` 管理：
+保留下来的 Sandbox 由项目的留存注册表记录，用 `niceeval sandbox` 管理：
 
 ```bash
 niceeval sandbox list              # 列出保留的沙箱和现场状态
@@ -62,4 +62,4 @@ niceeval sandbox stop --all        # 全部销毁
 
 ## 边界
 
-保留的 Sandbox 只用来排查，不能续跑或重新评分。判定、断言、diff 这些结论仍以 artifact 为准。查看 artifact 的方法见[查看结果](/zh/tutorials/viewing-results)。
+保留的 Sandbox 只用来排查，不能续跑或重新评分。判定、断言和 diff 等结论仍以已发布事实为准。查看结果的方法见[查看结果](/zh/tutorials/viewing-results)。

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

@@ -27,23 +27,23 @@ niceeval show @<attempt-locator> --diff
 
 | 错误 | 下一步 |
 | --- | --- |
-| `record-root-missing` | 检查项目目录或 `--record` 输入。 |
-| `record-schema-migration-required` | 显式运行 `niceeval migrate`。 |
-| `record-schema-unsupported` | 使用支持该 Record 的 NiceEval 版本。 |
-| `record-database-invalid` | 停止普通读取，修复或重新取得有效 Snapshot。 |
+| 找不到项目 Record | 确认在项目目录中运行，并检查唯一的 `.niceeval/record.sqlite` 是否存在。 |
+| `--record` 输入被拒绝 | 重新取得完整的当前 SQLite 文件；外部 Record 会经过完整性和领域不变量校验。 |
+| 旧 schema 或数据库无效 | 在原项目用 current NiceEval 重新运行；读取不会迁移、修补或部分打开 Record。 |
+| Run 仍为 `active`，但原进程已终止 | 先用 `niceeval run show <run-id>` 核对，再运行 `niceeval run recover <run-id> --yes`。 |
 
-已发布事实没有手动编辑的修复路径。需要不同事实时创建新 Run。`niceeval clean` 只处理重新验证后的未完成 rows。
+已发布事实没有手动编辑的修复路径。需要不同事实时创建新的 Run。`niceeval run recover` 只会收口可证明旧 owner 已终止的 Run，并保留已经发布的 Attempt。
 
 ## 结果不完整或无法比较
 
 脚本、AI 或 CI 先运行 `niceeval query discover` 找到正确的固定 operation，再用 `explain` 检查 request，最后运行 `run`。结果会指出 missing、issues、Evidence 与 correction。`query` 只输出机器协议，不用来阅读终端排版。
 
-需要浏览器界面时运行 `niceeval view --run <run-id> --no-open`。不要解析 View 页面，也不要读取私有 `.niceeval/` 文件。
+需要浏览器界面时运行 `niceeval view --run <run-id> --no-open`。不要解析 View 页面，也不要读取或查询私有 SQLite 表。
 
 比较使用 `runs.compare`。它的 `exact` 和 `paired` 模式会拒绝不兼容的 domain 或 pair，不会悄悄缩小分母。
 
-## View 没有刷新
+## View 显示旧结果
 
-operational View 只在用户确认后替换 active sealed cutoff。候选读取失败时，上一份可用 View 仍然可读。Snapshot View 固定 exact Seal，因此不会 watch 或 refresh。
+View 在一次读取开始时固定 PublicationCutoff。页面提示有新发布内容时，确认刷新即可读取新的闭合结果；刷新失败时，上一份可读结果会保留。
 
 正常流程见[查看已封口的运行结果](/zh/tutorials/viewing-results)，命令细节见 [CLI](/zh/reference/cli)。

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

@@ -1,95 +1,75 @@
 ---
 title: "运行被强杀后恢复"
-description: "进程被 kill -9、CI 超时或断电杀掉后，从已发布结果重跑、收回遗留 Sandbox、补齐实验收尾，并显式恢复共享状态租约。"
+description: "进程被 kill -9、CI 超时或断电中断后，保留已发布结果、收口失去 owner 的 Run，并收回遗留 Sandbox。"
 ---
 
-`niceeval exp` 跑到一半被 `kill -9`、CI 时限或断电直接杀掉时，进程没有机会做任何清理。你会碰到三种残留：没跑完的评估、还在 Provider 侧占资源的 Sandbox 实例、实验 `setup` 起过但没关掉的外部服务（隧道、共享服务、license 席位）。三种各有一个恢复入口，都不需要手工翻 Docker 或云控制台。
+`niceeval exp` 被 `kill -9`、CI 时限或断电直接中断时，进程无法执行收尾。已经发布的 Attempt 仍在项目内唯一的 `.niceeval/record.sqlite` 中可读；尚未发布的工作不会变成半条公开事实。
 
-正常的 Ctrl+C 或 SIGTERM 不在本页范围：那些路径 NiceEval 会自己走完全部收尾，不留残留。
+正常的 Ctrl+C 或 SIGTERM 走受控中断：NiceEval 发布已经完成的 Attempt，并把其余 slot 收口为中断原因。本页只处理进程没有机会收尾的情况。
 
-## 从已发布结果重跑
+## 先查看已发布结果
 
-只有成功 seal、完整发布的 Run 里的 Attempt 才是 Record 事实。重跑可以自动沿用其中仍符合资格的结果，不再花一次 Agent 和 Sandbox 的成本。强杀 Invocation 留下的 incomplete Run directory 会被整体忽略：里面的草稿 Attempt 不展示、不引用、也不沿用。
+先列出本次 Invocation 创建过的 Run。若你有 Invocation ID，用它缩小范围：
 
 ```bash
-niceeval exp compare/bub-e2b memory/commit0
+niceeval run list --invocation <invocation-id>
+niceeval run show <run-id>
+niceeval view --run <run-id>
 ```
 
-- 如果另一个完整 Run 已经为 `--attempts 5` 发布 3 个符合资格的 Attempt，就只再跑 2 次。如果那 3 个草稿只存在于强杀 Run、尚未到达 `complete` 发布点，它们一个也不会沿用，5 个位置都可能重跑。
-- 被强杀的实验如果留了没做完的收尾，重跑会先补一次实验级 `teardown` 再开始，泄漏不会越积越多。
-- 判定为 `errored` 的 Attempt 不复用，照常重跑。
-- 想全部重来，加 `--rerun all`。
+`active` Run 仍会显示已经发布的 Attempt，未发布的 expected slot 显示为 `pending`。不要根据运行时间、PID 过期或 heartbeat 停止自行判断它可以被接管。
 
-确认没有活跃 Invocation 占用 Record root 后，运行 `niceeval clean` 删除 incomplete Run 残留。清理不会把草稿 Attempt 变成可复用结果。
+## 收口失去 owner 的 Run
 
-## 收回没清理的 Sandbox 实例
-
-先核对有哪些实例属于已经死掉的运行：
+只有确认原进程已经终止后，才执行恢复：
 
 ```bash
-niceeval sandbox list --orphans
+niceeval run recover <run-id> --yes
 ```
 
-```text
-ID        PROVIDER  OWNER              STARTED            STATE
-f31b9a02  docker    pid 4242@mbp dead  2026-07-20 14:02   orphan
-```
+`run recover` 会验证旧 owner 的精确 process identity。验证通过后，它把 Run 收口为 `interrupted`，并为未发布的 slot 写入 absence reason。它不会删除 Run 或已经发布的 Attempt，也不会让旧 generation 继续写入。
 
-确认后一条命令收回：
+证据不足时命令会拒绝恢复。此时先确认原进程、CI job 和可能的远程 worker 都已停止，再重新检查；不要用超时或“等待太久”代替 owner 证据。
 
-```bash
-niceeval sandbox prune
-```
+需要重新取得结果时，重新运行原来的 Experiment。新的 Invocation 会创建新的 Run；是否沿用已有 Attempt 由当前 Experiment 的 eligibility 和 `--rerun` policy 决定。
 
-- `orphan` 表示属主进程已确认死亡，可以安全销毁。正在跑的运行的实例不会出现在列表里。
-- 多容器题目（Compose）的伴随容器和网络跟随主实例整组列出、整组销毁，不需要再手工 `docker rm` 收尾。
-- 从别的机器创建、无法核对的实例标为 `unverified`，默认不动。确认后用 `niceeval sandbox prune --force`。
-- Vercel Sandbox 无法按元数据核对，到 Provider 的保留期限后自动回收，不需要处理。
-- `--keep-sandbox` 留存的现场不受 `prune` 影响，仍用 `niceeval sandbox stop` 管理。
+## 收回强杀留下的 Sandbox
 
-## 补齐实验收尾
+强杀时正在运行的 Sandbox 不会进入留存注册表。先只读核对孤儿实例：
 
-实验 `setup` 起的外部服务要靠实验 `teardown` 关掉。被强杀的运行如果你暂时不想重跑，单独补一次收尾：
+```bash
+niceeval sandbox list --orphans
+```
+
+确认后再收回：
 
 ```bash
-niceeval exp compare/bub-e2b --teardown
+niceeval sandbox prune
 ```
 
-- 只执行选中实验的 `teardown`，不跑任何评估、不跑 `setup`。
-- 随时可以执行，不依赖上次运行留下的记录。`teardown` 自身要能容忍重复执行。
-- 强杀后原进程的内存已经丢失，`teardown` 里要从容器名、pid 文件或幂等的关停脚本这类持久信息找回要关的资源，不要依赖 `setup` 存在内存里的对象。
+- `orphan` 表示同一主机上的 owner 已被证明终止，可以安全销毁。
+- `unverified` 表示来自另一台主机或无法确认的实例，默认不会删除；确认后才使用 `niceeval sandbox prune --force`。
+- Compose 的伴随容器和网络会作为一组列出和销毁。
+- Vercel Sandbox 没有可检索的孤儿通道，按 Provider 保留期限自行回收。
+- 用 `--keep-sandbox` 留下的现场不受 `prune` 影响，仍用 `niceeval sandbox stop` 管理。
 
 ## 恢复共享状态租约
 
-声明了 `sharedState.key` 的实验会把租约持有到 Sandbox teardown、Provider finalizer 和实验 `teardown` 全部成功。进程被强杀或其中一项 cleanup 失败时，租约会保留；同 key 的新 Invocation 会继续等待，不会根据 PID、超时或 heartbeat 自动接管。
-
-先只检查当前 owner evidence，不带 token 或确认参数：
+声明 `sharedState.key` 的 Experiment 在原 owner 正常释放租约，或操作员完成显式恢复前不会启动相同 key 的新 Invocation。先运行不带 token 的检查命令，读取当前 owner evidence：
 
 ```bash
-niceeval exp compare/bub-e2b --teardown \
-  --recover-shared-state mempal/codex/cohort-a
+niceeval exp <experiment> --teardown \
+  --recover-shared-state <key>
 ```
 
-命令会显示 key、Experiment、owner token、host、PID、process identity 和最新 heartbeat，然后以非零状态退出。先确认原 owner 已终止，再确认它操作的 checkpoint、远端服务和回存流程都已静止。这个恢复入口只补跑实验 `teardown`，不会回滚已经写到一半的业务状态。
-
-核对完后，复制刚显示的完整 owner token，并显式确认两个条件：
+确认原 owner 已终止，并确认它操作的远程服务和 checkpoint 都已静止后，复制命令显示的 token 并显式确认：
 
 ```bash
-niceeval exp compare/bub-e2b --teardown \
-  --recover-shared-state mempal/codex/cohort-a \
+niceeval exp <experiment> --teardown \
+  --recover-shared-state <key> \
   --owner-token <displayed-token> \
   --confirm-owner-terminated \
   --confirm-remote-quiesced
 ```
 
-- 同机的原进程仍然存活时，NiceEval 拒绝恢复；暂停的进程仍算存活。
-- 错误或过期的 token 不会修改租约，也不会释放后来 owner 的租约。
-- 两条恢复命令同时竞争时，只有一条能取得恢复 ownership。
-- 补偿 `teardown` 失败时，租约继续保留。解决 teardown 问题后重新检查，再用当前显示的 token 重试。
-- 成功后，同 key 的等待 Invocation 才能取得租约并开始 Experiment setup 或创建 Sandbox。
-
-## 预防：让下一次强杀无害
-
-- 长任务放在有时限的环境（CI、外部看门狗）里跑时，要为 Run 留出到达 `complete` 发布点的时间。后续运行只能沿用完整 Run 已经发布的结果。
-- 实验 `teardown` 写成幂等的：重复执行不报错、目标已经关掉也算成功。这是补收尾机制正确工作的前提。
-- 使用 `sharedState.key` 时，让 checkpoint 回存具备原子性或可补偿性。显式恢复协调租约不能修复半次业务写入。
+恢复只为该 Experiment 补跑 `teardown`。token 错误、旧 token 或 cleanup 失败都不会释放后来 owner 的租约；修复 teardown 后，用当前显示的 token 再试。

package/docs-site/zh/tutorials/accept-results.mdx

@@ -20,13 +20,13 @@ pnpm exec niceeval exp checkout --dry
 
 ## 核对历史 Attempt
 
-使用完整 locator 查看不可变结果：
+使用完整 locator 在终端查看不可变结果：
 
 ```sh
-pnpm exec niceeval view @1K1P0VJAPVJ12
+pnpm exec niceeval show @1K1P0VJAPVJ12
 ```
 
-核对 Verdict、Assertion、用量、时间和详情页中的证据。需要回看来源 Run 的完整分母时，再使用：
+核对 Verdict、Assertion、用量、时间和证据。需要回看来源 Run 的完整分母时，再使用：
 
 ```sh
 pnpm exec niceeval view --run <source-run-id>
@@ -65,7 +65,7 @@ pnpm exec niceeval view --run <accepted-run-id>
 | 错误 | 下一步 |
 | --- | --- |
 | `malformed-locator` | 从 `--dry` 或固定 query result 复制完整的大写 locator，不使用旧 UUID 或模糊前缀。 |
-| `locator-not-found` | 确认读取的是同一 Record；其它结果根显式传 `--record`。 |
+| `locator-not-found` | 确认读取的是同一份 Record；读取复制出的 SQLite 文件时，为 `show` 显式传 `--record`。 |
 | `accept-ineligible` | 按提示检查 Verdict、timeout、身份或 Observability；不能证明仍成立时重新运行。 |
 | `duplicate-accept-member` | 每个目标 slot 只保留一个 locator，去掉重复或冲突输入。 |
 

package/docs-site/zh/tutorials/agent-onboarding.mdx

@@ -23,7 +23,7 @@ description: "给 Coding Agent 的完整接入流程：探索项目、与用户
 探完之后，向用户**介绍接入等级**并给出推荐（详见[接入等级](/zh/explanation/tier)）：
 
 - **Tier 1（只接 send）**：应用一行不改，全套断言（文本、Judge、多轮、工具、HITL）都在这一档。
-- **Tier 2（send + OTel）**：应用把 OTel span 也发 NiceEval 一份，换 `niceeval view` 的调用瀑布图。已有埋点（第 3 点探到的）就零改动。
+- **Tier 2（send + OTel）**：应用把 OTel span 也发 NiceEval 一份，在 `niceeval view` 中查看调用瀑布图。已有埋点（第 3 点探到的）就零改动。
 - **Tier 3（侵入改造 + flags）**：把应用内部变体暴露成 `flags` 做 feature A/B。已有 A/B 开关（第 4 点探到的）就是现成入口。
 
 **默认推荐先 Tier 1 跑通，再升 Tier 2**——尤其当第 3 点探到应用已有 OTel 时，明确告诉用户「升 Tier 2 只是把 span 多发一份，成本接近零」。Tier 3 只在用户明确要做变体对比时提。
@@ -69,7 +69,7 @@ export default defineConfig({
 按第 1 步选中的方向读完对应文档后，依次写：
 
 1. **Adapter**（`agents/*.ts` 或用户项目里约定的目录）——用 `defineAgent` 实现 `send`，配置走工厂参数，不写死、不读 `process.env`。契约见 [Adapter](/zh/explanation/adapter)，API 签名见 [Adapter 参考](/zh/reference/define-agent)，事件映射见[事件参考](/zh/reference/events)。两个容易踩的点：**端点/模式要选被测系统核心能力的入口，不是最容易跑通的入口**——比如被测平台既有「纯 LLM 聊天」又有「连库执行」两种模式，接前者等于评了个底层模型代理，没评到产品本身。**`evidenceCoverage` 必须按实际映射如实声明**——只把最终文本映射出来就不要用 `completeEvidenceCoverage`，声明会影响断言完整性，虚报比保守更糟。
-2. **Experiment**（`experiments/*.ts`）——引用上面的 Adapter，声明 `model`、`flags`、`attempts` 等。模型对比写两个实验文件，各自钉一个 `model`。`evals: (eval) => boolean` 决定各自本次运行哪些评估用例。路径只负责 id 和批量运行，固定 Inspection operation 消费当前已封口的物理结果与覆盖事实。
+2. **Experiment**（`experiments/*.ts`）——引用上面的 Adapter，声明 `model`、`flags`、`attempts` 等。模型对比写两个实验文件，各自钉一个 `model`。`evals: (eval) => boolean` 决定各自本次运行哪些评估用例。路径只负责 id 和批量运行，固定 Inspection operation 消费当前已发布的物理结果与覆盖事实。
 3. **评估用例**（`evals/*.eval.ts`）——**先探明这个应用是干嘛的，再写一条贴着它真实功能的评估用例**。读它的 README、路由、工具定义或系统提示，找出它的核心用例（客服机器人就问一条真实的客服问题、SQL agent 就给一个真实的查询任务），拿这个用例做第一条评估用例的输入和断言。两类输入都不合格：「你好」这种和应用无关的占位输入，以及「你是什么/你能做什么」这种**问被测系统它自己的元问题**——那不是用户拿它干活的用例。形式上仍从最小写起：一句输入，`t.succeeded()` + 一个针对预期回答的内容断言——但最小形式只是调通的脚手架，不是交付标准，收尾前还要满足两条：
    - **断言在被测系统胡编时要会变红**。不要断言输入里本来就有的词（问「X 是什么」再断言回答含「X」，被测方复读题目就能通过）。断言预期回答独有的实质内容——具体事实、结构（`hasSections()`）、真实链接（`includesUrl()`），或用 `check({ input, output }, closedQA(...))` 做语义判定。
    - **至少一条负例**。喂一个被测系统应该答不了的输入（不存在的表、检索不到的主题），断言它明确说查不到/做不到，而不是编造一个看似合理的结果——对连着真实数据/检索源的 agent，这是最值得先测的失败形态。

package/docs-site/zh/tutorials/authoring.mdx

@@ -168,7 +168,7 @@ export default defineEval({
 <Lifecycle
   title="一条 Attempt 从排队到收尾"
   hint="悬停暂停"
-  note={<>收尾段不计入这条 Attempt 的耗时口径。用 <code>niceeval view @&lt;attempt-locator&gt;</code> 审阅运行信息，或用固定 query operation 读取机器结果。</>}
+  note={<>收尾段不计入这条 Attempt 的耗时口径。用 <code>niceeval show @&lt;attempt-locator&gt;</code> 审阅运行信息，或用固定 query operation 读取机器结果。</>}
   phases={[
     { name: "experiment.setup", what: "起隧道、起共享服务", times: "整场一次" },
     { name: "sandbox.queue", what: "等一个并发位", times: "每 Attempt" },

package/docs-site/zh/tutorials/compare-runs.mdx

@@ -1,7 +1,7 @@
 ---
 title: "比较多个固定 Run"
 sidebarTitle: "比较 Run"
-description: "用 `runs.compare` operation 比较明确 Run 的闭合事实，并在浏览器中审阅相同的结果。"
+description: "用 `runs.compare` operation 比较明确 Run 的已发布事实，并在浏览器中审阅相同的结果。"
 ---
 
 比较模型、提示词或 Agent 版本时，先保留每次运行 receipt 的 `runIds`。不要用最新结果代替明确的比较边界。
@@ -27,6 +27,6 @@ niceeval query run --request compare.json > compare-result.json
 niceeval view --run <baseline-run-id> --run <candidate-run-id>
 ```
 
-View 读取同样已封口的事实，帮助人审阅 overview 与 Attempt detail。它不引入另一套统计、比较或页面组装逻辑。
+View 读取同样已发布的事实，帮助人审阅 Overview 与 Attempt detail。它不引入另一套统计、比较或页面组装逻辑。
 
-当结果来自另一台兼容 runtime 时，复制各自的 canonical `.niceeval/record.sqlite`，然后为 query、show 或 view 指定对应的 `--record` 输入。
+当结果来自另一台兼容 runtime 时，复制 canonical `.niceeval/record.sqlite`。随后为 `show` 或 `query` 指定这份副本的 `--record` 输入；`view` 只读取当前项目的 Record。

package/docs-site/zh/tutorials/concurrency.mdx

@@ -199,23 +199,23 @@ export default defineExperiment({
 });
 ```
 
-## 多开终端时共用 Record
+## 多开终端时共用项目 Record
 
-同一 Record root 允许多个 append writer 并发，但不会让两条 Invocation 自动分工。确认本机、Provider 和 Agent 服务还有余量时，两个终端可以使用同一个 root：
+同一项目的 `.niceeval/record.sqlite` 允许多个 Invocation 发布结果，但不会让两条 Invocation 自动分工。确认本机、Provider 和 Agent 服务还有余量时，两个终端直接在同一项目运行：
 
 ```bash
-niceeval exp compare --record .niceeval/record --max-concurrency 2
-niceeval exp compare --record .niceeval/record --max-concurrency 2
+niceeval exp compare --max-concurrency 2
+niceeval exp compare --max-concurrency 2
 ```
 
-两边各自规划完整选择，可能重复执行相同评估用例，因为双方都不会读取对方尚未发布的 Attempt。完整 Run 会原子发布到共享 Record。只有确实需要隔离 Run 和 sealed facts 时才使用不同 root；NiceEval 不自动合并分开的 root。
+两边各自规划完整选择，可能重复执行相同评估用例，因为双方都不会读取对方尚未发布的 Attempt。每个 Attempt 发布后立刻可供读取，即使来源 Run 仍是 `active`。需要隔离结果时，在另一个项目目录运行；NiceEval 不会合并两份 Record。
 
 三个边界：
 
 - 两边的 CLI 上限会相加，Provider 容量不会。配额紧张时把两边都调低。
 - 实验自己的 `maxConcurrency` 也是每个终端各算各的：两条命令都声明 3 时，合计最多跑六条。
 - 两个终端的 Sandbox 池也各自独立。只有确实共享外部 checkpoint 时才声明 `sharedState.key`；它不会合并 Record。
-- 并发 append writer 可以共用 root。Record maintenance 仍然独占；遇到 `record-maintenance-busy` 时，先停掉 reader 和 writer 再重试。
+- 并发 Invocation 可以共用项目 Record。不要在运行期间复制 `.niceeval/record.sqlite`；等命令成功完成 portable gate 后再复制或归档这一个文件。
 
 ## 边界
 

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

@@ -104,7 +104,7 @@ export default defineEval({
 ```bash
 npx niceeval exp my-agent        # 跑这个 experiment 下的全部 eval
 npx niceeval exp my-agent refund # 只跑 ID 以 refund 开头的
-pnpm exec niceeval view --run <run-id>  # 在本地查看器里查看一个已封口的 Run
+pnpm exec niceeval view --run <run-id>  # 在本地查看器里查看一个 Run
 ```
 
 **验证运行结果**：终端会显示动态 dashboard，完成和排队数量在原位更新。失败、错误和 warning 会保留在输出中。运行结束后会打印摘要和 receipt；用其中的 Run ID 也可以执行 `pnpm exec niceeval view --run <runId>`，查看每条评估用例逐轮的输入、事件和评分明细。
@@ -208,7 +208,7 @@ async send(input, ctx) {
 
 `progress` 是可覆盖的短期状态。`diagnostic` 是运行结束后仍能回顾的有界记录。两者都不能指定 phase 或输出流，也不会自动改变 `Turn.status` 或 Attempt 判定。连接失败、解析无法继续等基础设施错误应抛出异常。正常收到的被测 Agent 失败通过 `Turn.status: "failed"` 表达。
 
-终端只显示错误的一层摘要和 Attempt identity。完整 code、message、cause、stack 与 diagnostics 保存在 Attempt-owned 通道里，使用 `niceeval view @<attempt-locator>` 或固定 `query` operation 查看。OTel trace 只补充调用关系和耗时，不是错误数据的前提。
+终端只显示错误的一层摘要和 Attempt identity。完整 code、message、cause、stack 与 diagnostics 保存在 Attempt-owned 通道里，使用 `niceeval show @<attempt-locator>` 或固定 `query` operation 查看。OTel trace 只补充调用关系和耗时，不是错误数据的前提。
 
 要分别评估本地和生产环境，创建两个 Experiment 文件，并传入不同的工厂参数：
 

package/docs-site/zh/tutorials/docker-in-docker.mdx

@@ -332,7 +332,7 @@ pnpm exec niceeval exp dind-managed --max-concurrency 2
 创建失败后使用终端给出的 Attempt 定位符，不要直接翻运行产物：
 
 ```bash
-pnpm exec niceeval view @1ABC234DEF
+pnpm exec niceeval show @1ABC234DEF
 ```
 
 常见错误与处理方式：

package/docs-site/zh/tutorials/experiments.mdx

@@ -33,7 +33,7 @@ export default defineExperiment({
 npx niceeval exp models
 ```
 
-另一个模型写另一个文件。固定 Inspection operation 在声明的 request 范围内比较合格的 Run；View 打开选中的已封口结果，不接受 Experiment selector。
+另一个模型写另一个文件。固定 Inspection operation 在声明的 request 范围内比较合格的 Run；View 打开选中的 Run，不接受 Experiment selector。
 
 多层目录只负责 id 和批量选择：
 

package/docs-site/zh/tutorials/install-custom-sandbox-agent.mdx

@@ -95,7 +95,7 @@ npx niceeval exp my-agent fixtures/button
 安装或复检失败时，Attempt 会在 `agent.ensure` 阶段变成 `errored`。终端会给出 Attempt 定位符。
 
 ```shell
-pnpm exec niceeval view @<attempt-locator>
+pnpm exec niceeval show @<attempt-locator>
 ```
 
 先检查错误里的包名、版本和目标平台。修正 `identity`、npm 包或安装步骤后，重新运行原命令。

package/docs-site/zh/tutorials/quickstart.mdx

@@ -26,7 +26,7 @@ description: "安装 NiceEval，写三个文件，10 分钟内对你自己的应
   <Step title="查看结果">
     ```bash
     pnpm exec niceeval query discover  # AI、脚本或 CI 先发现读取 operation
-    pnpm exec niceeval view            # 网页审阅已封口的结果
+    pnpm exec niceeval view            # 网页审阅已发布的结果
     ```
   </Step>
 </Steps>
@@ -103,7 +103,7 @@ export default defineEval({
 ```bash
 pnpm exec niceeval exp my-agent   # 跑起来
 pnpm exec niceeval query discover              # 让机器发现可用 operation
-pnpm exec niceeval view                        # 在网页审阅当前已封口的结果
+pnpm exec niceeval view                        # 在网页审阅当前已发布的结果
 ```
 
 到这里第一条评估用例已经跑通。

package/docs-site/zh/tutorials/reporters.mdx

@@ -19,7 +19,7 @@ Reporter 面向当前 Invocation。它可以把当前运行的结果发送到外
 
 ## Reporter 适合什么
 
-把 Reporter 配在需要观察的运行范围，让它处理当前进程可见的结果。外部系统可以接收运行摘要、Attempt 结果或链接，但要读取完整业务事实时，应使用 receipt 的 `runIds` 重新打开停稳 Record。
+把 Reporter 配在需要观察的运行范围，让它处理当前进程可见的结果。外部系统可以接收运行摘要、Attempt 结果或链接，但要读取完整业务事实时，应使用 receipt 的 `runIds` 重新打开已发布事实。
 
 Reporter 不能：
 
@@ -50,7 +50,7 @@ npx niceeval exp checkout --json
 pnpm exec niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
 ```
 
-不要把 progress 或 diagnostic 行当作长期结果格式。它们服务当前 Invocation，完整业务事实属于停稳 Record。
+不要把 progress 或 diagnostic 行当作长期结果格式。它们服务当前 Invocation，完整业务事实属于已发布 Record。
 
 ## 接入外部系统时的原则
 
@@ -58,6 +58,6 @@ pnpm exec niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
 2. 将凭据保留在运行变量中，不写入输出内容。
 3. 用退出状态处理 CI 门禁。
 4. 用 receipt 的 `runIds` 把外部工作流关联到可查看的结果。
-5. 需要审阅已封口事实时，使用 receipt 的 `runIds` 打开 `view`，或用 `query` 交给自动化流程。
+5. 需要审阅已发布事实时，使用 receipt 的 `runIds` 打开 `view`，或用 `query` 交给自动化流程。
 
 有关 CI 命令与 JUnit，请阅读[CI 集成](/zh/tutorials/ci-integration)。

package/docs-site/zh/tutorials/sandbox-agent.mdx

@@ -206,10 +206,10 @@ export default defineSandboxAgent({
 ```text
 ✗ @5TB8167MXJ30SYZCNAVRHPQ4D2 fixtures/button [local] errored · agent setup
     agent-install-failed: npm install my-agent exited with code 1
-    Inspect: niceeval view @5TB8167MXJ30SYZCNAVRHPQ4D2
+    Inspect: niceeval show @5TB8167MXJ30SYZCNAVRHPQ4D2
 ```
 
-运行 `niceeval view @5TB8167MXJ30SYZCNAVRHPQ4D2` 可查看结构化错误、diagnostics 和已完成的生命周期阶段。需要机器读取时，从 `query discover` 的固定 operation 选择 trace。它可直接看出错误或超时发生在哪一层。
+运行 `niceeval show @5TB8167MXJ30SYZCNAVRHPQ4D2` 可查看结构化错误、diagnostics 和已完成的生命周期阶段。需要机器读取时，从 `query discover` 的固定 operation 选择 trace。它可直接看出错误或超时发生在哪一层。
 
 树超过 80 个细节节点时会保留失败、慢点和首尾样本，并提示省略数量。需要逐节点审计时，使用 trace operation 的完整结果。Sandbox 创建失败可能发生在 telemetry 建立前，所以错误回顾不依赖 trace。
 

package/docs-site/zh/tutorials/sandbox-reuse.mdx

@@ -63,9 +63,9 @@ export default defineExperiment({
 
 ## 多开终端时 Sandbox 不共享
 
-Sandbox 复用只发生在一次 Invocation 里。两个终端同时跑一个实验时，两边有各自的 Run 和 Sandbox 池。NiceEval 不把运行中的 Sandbox handle 交给另一个进程；两个 Invocation 可以并发向同一个 Record root 追加已发布结果。
+Sandbox 复用只发生在一次 Invocation 里。两个终端同时跑一个实验时，两边有各自的 Run 和 Sandbox 池。NiceEval 不把运行中的 Sandbox handle 交给另一个进程；两个 Invocation 可以并发向同一项目的 `.niceeval/record.sqlite` 发布结果。
 
-Record maintenance 是独占操作。`clean` 或其它维护命令报告 `record-maintenance-busy` 时，先停止占用该 root 的 reader 和 writer，再重试维护命令。正常并发运行不需要为了避开 writer 冲突而拆成多个 Record root。
+正常并发运行不需要为了避开 writer 冲突而拆成多个 Record。只在 Invocation 成功完成 portable gate 后复制或归档 `.niceeval/record.sqlite`；运行中的 SQLite 文件不是可搬运快照。
 
 如果 Sandbox 只保留自己的临时状态，两边可以同时跑不同评估用例。动态 `.before()` 回调恢复、回存同一个外部 checkpoint 时，为 Experiment 声明稳定且不含秘密的 key：
 
@@ -86,7 +86,7 @@ export default defineExperiment({
 
 NiceEval 会在 Experiment setup 或创建 Sandbox 前取得这个 key，直到 Sandbox cleanup、Provider finalizer 与 Experiment `teardown` 全部完成才释放。等待方不会创建 Sandbox；租约释放后，它继续自己的计划，不读取或采用另一条 Run 的结果。
 
-key 会进入结果的配置身份。更换 key 就是更换状态 cohort，旧结果不会混进来。租约只保护外部 checkpoint，与 Record root 无关；普通 append writer 仍可并发使用同一个 root。不同机器或 working copy 仍需外部分布式锁。
+key 会进入结果的配置身份。更换 key 就是更换状态 cohort，旧结果不会混进来。租约只保护外部 checkpoint，与项目 Record 无关；普通 Invocation 仍可并发发布。不同机器或 working copy 仍需外部分布式锁。
 
 ## 生命周期：谁跑几次
 

package/docs-site/zh/tutorials/viewing-results.mdx

@@ -1,10 +1,10 @@
 ---
-title: "查看已封口的运行结果"
+title: "查看运行结果"
 sidebarTitle: "查看结果"
 description: "在终端用 show 逐层查看结果；在浏览器用 View 审阅，在自动化中用 query 读取 JSON。"
 ---
 
-评估完成后，receipt 中的 `runIds` 是稳定的读取边界。人在终端用 `niceeval show`，在浏览器用 `niceeval view`。AI、脚本和 CI 用 `niceeval query` 读取 JSON。
+每个 Attempt 发布后立即可读，不必等待来源 Run 结束。运行结束后，receipt 中的 `runIds` 也是稳定的读取边界。人在终端用 `niceeval show`，在浏览器用 `niceeval view`。AI、脚本和 CI 用 `niceeval query` 读取 JSON。
 
 ## 先在终端查看 Overview
 
@@ -12,9 +12,9 @@ description: "在终端用 show 逐层查看结果；在浏览器用 View 审阅
 niceeval show
 ```
 
-不带 selector 时，`show` 输出当前 sealed cutoff 的 Overview。它按 Experiment、评估用例和 Attempt 展开汇总，并保留通过率、分数、coverage、缺失项和 issues。先从这里找出需要继续查看的 Experiment、Run 或 Attempt locator。
+不带 selector 时，`show` 输出当前 PublicationCutoff 的 Overview。它按 Experiment、评估用例和 Attempt 展开汇总，并保留通过率、分数、coverage、缺失项和 issues。先从这里找出需要继续查看的 Experiment、Run 或 Attempt locator。
 
-Overview 来自项目 canonical Record 中已封口的结果。即使当前源码或当前安装候选的 identity 已经改变，
+Overview 来自项目唯一的 `.niceeval/record.sqlite` 中已发布的结果。即使当前源码或当前安装候选的 identity 已经改变，
 `show` 也会保留每个逻辑 slot 的最新结果，不会把存在的历史显示为 `Observed 0/0`。这表示结果可查看，
 不表示它已通过当前 target 的复用资格检查。
 
@@ -25,7 +25,7 @@ niceeval show --experiment <experiment-id>
 niceeval show --run <run-id>
 ```
 
-`--experiment` 显示一个 Experiment 的聚合结果和各评估用例。`--run` 显示一个已封口 Run 的成员、判定、分数、coverage 和 usage 摘要。两者都可重复传入多个精确 ID；不能与彼此或 Attempt locator 混用。
+`--experiment` 显示一个 Experiment 的聚合结果和各评估用例。`--run` 显示一个精确 Run 的成员、判定、分数、coverage 和 usage 摘要；`active` Run 已发布的 Attempt 会出现，尚未发布的位置显示 `pending`。两者都可重复传入多个精确 ID；不能与彼此或 Attempt locator 混用。
 
 ## 查看一个 Attempt
 
@@ -49,7 +49,7 @@ niceeval show @<locator> --diff
 niceeval show @<locator> --execution --expand <stable-id>
 ```
 
-`--timing` 显示活动的顺序和耗时，`--usage` 显示 token、请求和成本总计，`--diff` 显示已捕获的文件变更窗口。详情只读取 Record 已封存的事实；`partial`、`not-recorded` 或 `unavailable` 表示实际可用范围，不能当作零值或失败。
+`--timing` 显示活动的顺序和耗时，`--usage` 显示 token、请求和成本总计，`--diff` 显示已捕获的文件变更窗口。详情只读取 Record 已发布的事实；`partial`、`not-recorded` 或 `unavailable` 表示实际可用范围，不能当作零值或失败。
 
 ## 正确解释完成、判定与分数
 
@@ -69,11 +69,11 @@ niceeval view
 niceeval view --run <run-id>
 ```
 
-View 是给人使用的固定第一方浏览器界面。它不读取项目自定义页面、主题或组件。不带 selector 时，View 打开项目当前 sealed cutoff 的 Overview；`--run` 选择一个或多个明确 Run。
+View 是给人使用的固定第一方浏览器界面。它不读取项目自定义页面、主题或组件。不带 selector 时，View 打开项目当前 PublicationCutoff 的 Overview；`--run` 选择一个或多个明确 Run。它同样显示 `active` Run 已发布的 Attempt，以及尚未发布 slot 的 `pending`。
 
 可以使用 `--no-open` 保持浏览器不自动打开，或使用 `--port` 选择 loopback port。`--json` 只输出 lifecycle NDJSON；它不输出运行结果。
 
-新 Run 发布后，项目 View 会提示用户确认 refresh。使用 `--record <file>` 时，View 固定通过完整校验的 SQLite generation，不会 watch 或 refresh。
+新事实发布后，项目 View 会提示用户确认 refresh；确认后才切换到新的 PublicationCutoff。
 
 ## 让机器读取 JSON
 
@@ -87,13 +87,12 @@ niceeval query run --request request.json
 
 常见读取任务由固定 operation 覆盖：列出 Run、取得 Run summary、读取 Attempt detail、trace、diff、sources、artifacts 或比较两个 Run。查看 [CLI](/zh/reference/cli) 获取完整说明。
 
-## 读取另一份封口事实
+## 读取另一份已发布事实
 
 ```sh
 cp .niceeval/record.sqlite ./baseline.record.sqlite
-niceeval view --record ./baseline.record.sqlite
 niceeval show --record ./baseline.record.sqlite
 niceeval query explain --record ./baseline.record.sqlite --request request.json
 ```
 
-`--record` 接受 canonical SQLite Record 的副本，并把它当 hostile input。精确 current schema、SQLite integrity 或领域 invariant 任一校验失败，命令都会拒绝整个文件。
+`show` 和 `query` 的 `--record` 接受 canonical SQLite Record 的副本，并把它当 hostile input。精确 current schema、SQLite integrity 或领域 invariant 任一校验失败，命令都会拒绝整个文件。`view` 只读取当前项目的 `.niceeval/record.sqlite`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.13.4-canary.49",
+  "version": "0.14.0",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",