niceeval 0.13.3 → 0.13.4-canary.39

package/docs-site/zh/README.md

@@ -42,4 +42,4 @@ Technical Reference 不等于整页都由生成器拼出来。页面仍可手写
 - `troubleshooting/debugging.mdx` 与 `troubleshooting/debug-sandbox.mdx` 从失败症状出发，目录独立，在导航中归入 `Tutorials` 标签下的“问题排查”。
 - `tutorials/sandbox-providers.mdx` 按 How-to 写，因为主任务是选择并配置 Provider。若以后字段表继续增长，再拆出独立 Provider Reference。
 
-新增或移动页面时，同时更新 `docs-site/docs.json` 和旧路径 redirect。校验命令以 [`../AGENTS.md`](../AGENTS.md) 为准。
+新增或移动页面时，同时更新 `apps/docs-site/docs.json` 和旧路径 redirect。校验命令以 [`../AGENTS.md`](../AGENTS.md) 为准。

package/docs-site/zh/explanation/assert.mdx

@@ -30,6 +30,10 @@ t.check(turn.data, matches(OrderSchema));
 t.check(turn.message.length, satisfies("回复不是空文本", (length) => length > 0));
 ```
 
+`matched` 和 `mismatched` 只说明候选值是否满足当前 Match。它们不能单独证明这条规则刚好覆盖任务允许的全部正确结果。
+
+`equals(expected)` 比较值的深相等；候选值是字符串时，它要求完全相同的字符串。如果任务接受多种等价表示，先把产物解析或归一化为任务关心的值，再选择能覆盖这些结果的 Match。只有字面表示本身属于任务要求时，才用精确字符串比较。
+
 ## 作用域 Assertion
 
 作用域方法在调用时直接登记 Boolean Assertion。接收者决定证据范围：`turn.*` 只看该不可变 Turn，`session.*` 看该 Session 调用点之前的前缀，根 `t.*` 看调用点时所有已启动 Session 的 vector cut。

package/docs-site/zh/explanation/judge.mdx

@@ -5,7 +5,8 @@ description: "用 t.judge 和 turn.judge 直接登记 Judge Assertion，再在
 ---
 
 Judge 用独立裁判模型评估难以用精确 Match 表达的质量，例如事实一致性、摘要忠实度和说明是否清楚。
-它的三个 recipe 都直接登记 measurement Assertion，分数是 `[0, 1]` 内的有限数字。调用即登记；handle 只配置同一条 Assertion。
+它的三个 recipe 都直接登记 measurement Assertion，measurement 是 `[0, 1]` 内的有限数字。这个区间是统一的数据格式，不表示每个 recipe 都会给任意连续分数。
+调用即登记；handle 只配置同一条 Assertion。
 
 ```ts
 const turn = await t.send("用两句话说明这项变更的风险。");
@@ -16,11 +17,13 @@ turn.judge.autoevals.closedQA("回答是否清楚说明了风险？")
 
 ## 三个 recipe
 
-| Recipe | 用途 |
-|---|---|
-| `closedQA(question, material)` | 判断输出是否满足一条开放式标准 |
-| `factuality(reference, material)` | 判断输出是否与参考文本一致 |
-| `summarizes(source, material)` | 判断输出是否忠实总结原文 |
+| Recipe | 用途 | 当前可能的 measurement |
+|---|---|---|
+| `closedQA(question, material)` | 判断输出是否满足一条开放式标准 | `0` 或 `1` |
+| `factuality(reference, material)` | 判断输出是否与参考文本一致 | `0`、`0.4`、`0.6` 或 `1` |
+| `summarizes(source, material)` | 判断输出是否忠实总结原文 | `0` 或 `1` |
+
+`factuality` 的中间档位有固定含义：提交内容是参考答案的一致子集时为 `0.4`，是一致超集时为 `0.6`。它不是按事实条数计算覆盖率。只回答一个事实和回答两个事实，都可能落在同一个 `0.4` 档位。
 
 `turn.judge.autoevals.*` 已经绑定该 Turn 的原始用户输入和助手输出，因此只传标准：
 
@@ -42,6 +45,25 @@ t.judge.autoevals.closedQA("文档是否说明了安装和回滚？", {
 
 文件先经公开 Sandbox API 读取成字符串。Judge API 不接收路径、`{ on }`、隐式最后一条输入或单次模型覆盖。`session.judge` 也不是公开 API；跨 session 的材料由作者显式组合。
 
+## 一条标准对应一个 Judge
+
+先判断评分标准能否独立成立。可以独立判断、独立计权或需要单独显示失败原因的要求，分别登记 Judge Assertion。
+
+```ts
+turn.judge.autoevals.closedQA("回答是否说明了兼容性风险？")
+  .gate(1)
+  .label("兼容性风险");
+turn.judge.autoevals.closedQA("回答是否给出了回滚方法？")
+  .gate(1)
+  .label("回滚方法");
+```
+
+不要把独立要求合成“回答是否准确、完整、清楚，并说明风险和回滚？”。一个 `closedQA` 只会给这组要求一个 `0` 或 `1`，报告无法指出是哪一项失败，也无法给各项不同权重。
+
+只有标准描述同一个不可分割的整体质量时，才使用一个 Judge。例如“风险说明整体是否清楚”是一个维度；它的 measurement 可以作为这一项的结果。标准中出现“并且”不一定要拆，但如果其中一半可以成立、可以单独给分或失败后需要单独修复，就应该拆。
+
+能用确定性证据验证的条件不交给 Judge。命令是否成功、文件是否存在和工具是否调用，分别使用对应的 Match 或 scoped Assertion；Judge 只评价传入文本中的开放式语义。
+
 ## 声明 capability 和配置
 
 只有评估用例声明了 `judge` 才能创建 Judge Assertion：
@@ -77,7 +99,7 @@ export default defineConfig({
 
 ## 阈值与分数
 
-通过制评估用 `.gate(n)` 把 Judge measurement 纳入 failed；`.atLeast(n)` 只记录局部 condition。
+通过制评估用 `.gate(n)` 把 Judge measurement 纳入 failed；`.atLeast(n)` 只记录局部 condition。每个必须成立的开放式要求使用一条独立 Judge，并分别设置 gate。这样任何一项失败都会使 Attempt 失败，报告也会保留各自的理由。
 
 ```ts
 const quality = turn.judge.autoevals.closedQA("回答是否准确且完整？")
@@ -88,12 +110,21 @@ await quality.orStop();
 
 `.orStop()` 是同一 handle 的 async barrier。低于阈值时它停止当前 continuation；正常 stop 后 Attempt 仍得到 `failed` Verdict。
 
-计分制评估直接调用 `.score(n)`：measurement `m` 贡献 `m * n`。`.atLeast(n)` 只增加局部 condition，可以单独配置，也可以与 `.score(n)` 同一条 Assertion 共存。
+计分制评估直接调用 `.score(n)`：measurement `m` 贡献 `m * n`。这里的 `n` 是这一评分项的权重，不是评估的固定总分。多个独立要求分别调用 `.score(n)`，各项 contribution 再累加。
 
 ```ts
-turn.judge.autoevals.closedQA("回答质量如何？").score(20).atLeast(0.5);
+turn.judge.autoevals.closedQA("回答是否说明了兼容性风险？")
+  .score(8)
+  .label("兼容性风险");
+turn.judge.autoevals.closedQA("回答是否给出了回滚方法？")
+  .score(12)
+  .label("回滚方法");
 ```
 
+上例两项各自得到 `0` 或 `1`，因此分别贡献 `0/8` 和 `0/12`。如果评价的是一个整体维度，也可以只登记一条 Judge，再用 `.score(n)` 乘这一项的 measurement。例如 `factuality` 得到 `0.4` 且该项 `.score(20)` 时贡献 `8` 分。这个 `0.4` 表示固定的“一致子集”档位，不表示完成了 40% 的独立要求。
+
+`.atLeast(n)` 只增加局部 condition，可以单独配置，也可以与 `.score(n)` 同一条 Assertion 共存。它不会改变 contribution，也不会让计分制评估产生 failed Verdict。
+
 两种配置都只运行一次 Judge evaluator，写一条 AssertionResult。没有配置 `.score()` 的 Judge Assertion 默认只保存 evaluation。
 
 ## 配置、预检与失败

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

@@ -126,7 +126,7 @@ Human 输出在每条 lane 内固定依次显示 Group before-slot、physical en
 
 Sandbox materialize 节点会显示 template owner、provider、kind 和安全的 configured locator。`Exact` 只代表原样显示作者配置，不代表 image tag、远端内容或最终实例已经冻结。远端 URL 的凭据、query 与 fragment 会脱敏。Docker image 只有保守的 credential-safe reference（可带标准 `sha256` digest）才显示 `Exact`；URL、非 digest userinfo 或其它不安全语法整项显示 `Opaque`，且不输出原字符串。
 
-作者提供的本地 path、`file:` URL、Dockerfile file 或 local dir 整项显示 `Opaque`，原路径不会进入输出。只有未配置 `localSandbox.dir` 时的固定 `author-base-dir` 标签可以显示 `Exact`。env value、credential、stdin、build arg value 和 custom identity 不输出。
+作者提供的本地 path、`file:` URL 或 Dockerfile file 整项显示 `Opaque`，原路径不会进入输出。env value、credential、stdin、build arg value 和 custom identity 不输出。
 
 E2B template name 与 Vercel snapshot ID 是 Provider 管理的任意字符串，因此完整 locator 同样显示 `Opaque`。Human 命令计划在统一终端出口把 C0、C1、ESC、tab 与 carriage return 显示成转义文本，覆盖 template metadata 与 Shell 行。JSON 保留结构化值，并依靠 JSON string escaping。
 
@@ -136,59 +136,83 @@ E2B template name 与 Vercel snapshot ID 是 Provider 管理的任意字符串
 
 ## 常用 flags
 
-下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 Sandbox provider 的 CLI flag，也没有项目级默认 provider。请在评估用例或 Experiment 上声明 template-bearing `SandboxLayer`，并从 `niceeval/sandbox` 导入下列工厂之一：
+下表静态读取各命令自有的 option schema 生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 Sandbox provider 的 CLI flag，也没有项目级默认 provider。请在评估用例或 Experiment 上声明 template-bearing `SandboxLayer`，并从 `niceeval/sandbox` 导入下列工厂之一：
 
 - `dockerSandbox({ source: { type: "image", image } })`
 - `dockerComposeSandbox({ file, workspaceService })`
 - `dockerSandbox({ source: { type: "dockerfile", context } })`
 - `vercelSandbox({ snapshotId })`
 - `e2bSandbox({ template })`
-- `localSandbox()`
 
 {/* GENERATED:BEGIN cli-flags */}
 
 {/* 本区块由 pnpm docs:reference 从源码注释生成,勿手改;要改文案,改对应源码的 TSDoc/JSDoc(映射见 scripts/generate-reference.ts) */}
 
-| Flag | 类型 | 说明 |
-|---|---|---|
-| `--agent` | string | experiment 运行不支持该 flag。要换 agent,请在 `experiments/` 下新增或复制一个配置文件。 |
-| `--model` | string | experiment 运行不支持该 flag。要换模型,请新增或复制一个 experiment 文件并修改 `model`。 |
-| `--attempts` | number | 每个 eval 运行多少次,常用于 pass@N。 |
-| `--max-concurrency` | number | 设置同时运行的 eval 数量。 |
-| `--max-build-concurrency` | number | 设置同时进行的 Sandbox 镜像 lookup/build 数量；与 eval 并发独立，默认 2。 |
-| `--timeout` | number | 单个 attempt 的超时时间,单位毫秒。解析链:`--timeout` > experiment > eval(`defineEval({ timeoutMs })`)> `niceeval.config.ts`,默认无上限(四层都没声明就不设 deadline);config 是缺省底而不是覆盖层,写了 config 不会让 eval 自己声明的上限失效。 |
-| `--budget` | number | 整次运行的预算上限(美元)。 |
-| `--keep-sandbox` | boolean | `exp` 命令专用:跑完留下 failed/errored attempt 的 Sandbox 现场(= `--keep-sandbox=failed`);`--keep-sandbox=all` 连 passed 也留。事后用 `niceeval sandbox list/enter/stop` 查看与销毁。 |
-| `--all` | boolean | `sandbox stop` 专用:销毁全部留存 Sandbox。 |
-| `--window` | string | `sandbox diff` 专用:只看某个 send 窗口(如 `--window turn2` 或 `--window session2/turn1`);省略输出全部窗口的串联视图。 |
-| `--path` | string | `sandbox diff` 专用:只看某个文件的 patch;省略输出该窗口的全部文件。 |
-| `--leave-running` | boolean | `sandbox enter` 专用:shell 退出后让现场保持运行,不送回休眠。 |
-| `--orphans` | boolean | `sandbox list` 专用:核对强杀(`SIGKILL` / 断电)路径留下的无主沙箱实例(docker + e2b;vercel 无按元数据检索实例的通道,不参与)。只读,不清理;销毁走 `niceeval sandbox prune`。 |
-| `--tag` | string | 只运行带有该 tag 的 eval(见 `defineEval` 的 `tags`)。 |
-| `--junit` | string | 额外写一份 JUnit XML 报告到指定路径,供 CI 消费。 |
-| `--json` | boolean | `exp` 运行在 stdout 输出单一有序的 NDJSON 事件流；`exp --dry` 与 `debug` 输出各自的单个 JSON 计划文档。`show` 输出 Host 拥有的内建或自定义单目标机器文档，不形成完整站点或打开第二条取数路径。 |
-| `--smoke` | boolean | `docker profile doctor` 专用：启动受限 DinD 容器并运行内层容器。 |
-| `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
-| `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
-| `--host` | string | `view` 命令专用:指定监听地址；省略时为 127.0.0.1，只写 `--host` 时为 0.0.0.0。非 loopback 监听无认证或 TLS，会向所有可达客户端暴露报告数据。 |
-| `--experiment` | string[] | `show` / `view` 命令专用：按完整 ExperimentId 收窄当前项目结果；可重复，不接受前缀或逗号列表。 |
-| `--record` | string | `show` / `view` / `accept` / `sandbox enter\|list\|stop` 共用:指定实际 Record root;CLI 不补接 `.niceeval/record` 或其它后缀。 |
-| `--run` | string[] | `show` / `view` 可重复传入 `--run`;每次按完整 RunId 增加一个显式 Run,重复 identity 去重。 |
-| `--report` | string | `show` / `view` 命令专用：内建 `standard` 或受信任的 Report module 路径。 |
-| `--page` | string | `show` / `view` 命令专用:选择报告的初始页;`show` 渲染该页并在尾部附其余页索引,`view` 以它作初始路由。未命中的页 id 按用法错误退出并列出可用页 id。 |
-| `--teardown` | boolean | `exp` 命令专用:补齐被强杀打断的实验级 teardown——只对选中的实验各执行一次 teardown(新进程语义),不派发 attempt、不跑 setup;没有遗留登记也照常执行。与 eval 前缀位置参数组合是用法错误。 |
-| `--recover-shared-state` | string | `exp --teardown` 专用:显式恢复一个永不自动接管的 sharedState lease；必须同时提供 --owner-token、--confirm-owner-terminated 和 --confirm-remote-quiesced。 |
-| `--owner-token` | string | `--recover-shared-state` 专用:要恢复的不可变 owner token；错误或过期 token 不会修改 lease。 |
-| `--confirm-owner-terminated` | boolean | `--recover-shared-state` 专用:确认原 owner 已终止。 |
-| `--confirm-remote-quiesced` | boolean | `--recover-shared-state` 专用:确认远端外部状态已静止。 |
-| `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行(人读文本或 `--json` 单文档,见「机器怎么读:--json」)。 |
-| `--force` | boolean | `sandbox prune` 专用:除 orphan 外也销毁 unverified 实例;`exp` 明确拒绝此 flag,重跑失败项或全部项请用 `--rerun` / `--rerun all`。 |
-| `--rerun` | boolean | `exp` 命令专用:重新运行失败项(裸写/failed)或全部项(all),不改变长期指纹。 |
-| `--early-exit` / `--no-early-exit` | boolean | 某个 eval 的一次 attempt 通过后,停止该 eval 剩余的 attempts;省略默认关(`attempts` 默认跑满、测完整通过率)。 |
-| `--open` / `--no-open` | boolean | `view` 命令专用:启动后自动打开浏览器(默认行为)。 |
-| `--yes` | boolean | `clean` / `migrate` 专用：确认不可逆 maintenance 动作或在 clean Git restore point 下执行 migration。 |
-| `--help` | boolean | 打印用法说明并退出。 |
-| `--version` | boolean | 打印 niceeval 的版本号并退出。 |
+| Flag | 命令 | 类型 | 说明 |
+|---|---|---|---|
+| `--help` | `niceeval` | boolean | 打印根命令索引。 |
+| `--version` | `niceeval` | boolean | 打印当前安装的 NiceEval 版本。 |
+| `--tag` | `niceeval check`、`niceeval exp`、`niceeval exp list` | string | 只选择带有该 tag 的评估用例。 |
+| `--help` | `niceeval check`、`niceeval exp`、`niceeval exp list`、`niceeval exp rename`、`niceeval exp --teardown`、`niceeval debug`、`niceeval accept`、`niceeval session` | boolean | 打印该命令的帮助。 |
+| `--attempts` | `niceeval exp` | number | 让每个选中的评估用例运行指定次数。 |
+| `--max-concurrency` | `niceeval exp` | number | 限制同时执行的 Attempt 数量。 |
+| `--max-build-concurrency` | `niceeval exp` | number | 限制同时准备 Sandbox build 的数量。 |
+| `--timeout` | `niceeval exp` | number | 以毫秒设置每个 Attempt 的超时时间。 |
+| `--budget` | `niceeval exp` | number | 以美元设置本次 Invocation 的预算。 |
+| `--junit` | `niceeval exp` | string | 写出必需的 JUnit 报告。 |
+| `--json` | `niceeval exp` | boolean | 写出该命令的机器文档或事件流。 |
+| `--dry` | `niceeval exp` | boolean | 规划但不创建 Invocation。 |
+| `--rerun`（单独使用为 `failed`） / `--rerun=failed\|all` / `--rerun failed\|all` | `niceeval exp` | `failed` \| `all` | 要求重新运行失败目标或全部目标。 |
+| `--keep-sandbox`（单独使用为 `failed`） / `--keep-sandbox=failed\|all` | `niceeval exp` | `failed` \| `all` | 保留 failed 或全部已结束 Attempt 的 Sandbox。 |
+| `--early-exit` / `--no-early-exit` | `niceeval exp` | boolean | 某次结果通过后停止该评估用例余下的 Attempt。 |
+| `--record` | `niceeval exp`、`niceeval accept` | string | 使用指定的 NiceEval Record root。 |
+| `--json` | `niceeval exp list` | boolean | 写出该命令的机器文档或事件流。 |
+| `--dry` | `niceeval exp rename` | boolean | 预览显式 Experiment 重命名。 |
+| `--json` | `niceeval exp rename` | boolean | 写出该命令的机器文档或事件流。 |
+| `--teardown` | `niceeval exp --teardown` | boolean | 运行显式的 Experiment teardown 恢复。 |
+| `--json` | `niceeval exp --teardown` | boolean | 写出该命令的机器文档或事件流。 |
+| `--recover-shared-state` | `niceeval exp --teardown` | string | 指定要显式恢复的共享状态 key。 |
+| `--owner-token` | `niceeval exp --teardown` | string | 提供准确的共享状态 owner token。 |
+| `--confirm-owner-terminated` | `niceeval exp --teardown` | boolean | 确认记录的 owner 已终止。 |
+| `--confirm-remote-quiesced` | `niceeval exp --teardown` | boolean | 确认远端共享状态已静止。 |
+| `--json` | `niceeval debug` | boolean | 写出该命令的机器文档或事件流。 |
+| `--all` | `niceeval session` | boolean | 包含已经完成的 Invocation 状态条目。 |
+| `--json` | `niceeval session` | boolean | 写出该命令的机器文档或事件流。 |
+| `--record` | `niceeval show`、`niceeval view` | string | 使用指定的 NiceEval Record root。 |
+| `--run` | `niceeval show`、`niceeval view` | string[] | 选择一个已发布的精确 Run；可重复传入以选择多个 Run。 |
+| `--experiment` | `niceeval show`、`niceeval view` | string[] | 按 Experiment selector 缩小当前项目的结果。 |
+| `--report` | `niceeval show`、`niceeval view` | string | 使用标准 Report 或可信的 Report module 路径。 |
+| `--theme` | `niceeval show`、`niceeval view` | string | 使用 basalt、chalk 或可信的 Theme module 路径。 |
+| `--page` | `niceeval show`、`niceeval view` | string | 选择 show 的目标或 view 的初始路由。 |
+| `--json` | `niceeval show` | boolean | 写出该命令的机器文档或事件流。 |
+| `--source` / `--source=<value>` | `niceeval show` | true \| string | 显示一个 Attempt 的源快照；可选地只显示一个文件。 |
+| `--execution` | `niceeval show` | boolean | 显示一个 Attempt 保留的执行证据。 |
+| `--timing`（单独使用为 `summary`） / `--timing=summary\|full` | `niceeval show` | `summary` \| `full` | 显示摘要或完整的时序证据。 |
+| `--grep` | `niceeval show` | string | 用 JavaScript 正则表达式过滤执行证据。 |
+| `--diff` / `--diff=<value>` | `niceeval show` | true \| string | 显示选中 Attempt 的文件改动；可选地只显示一个内联路径。 |
+| `--out` | `niceeval view` | string | 导出完整的静态 Report 站点。 |
+| `--host`（单独使用为 `0.0.0.0`） / `--host=<value>` / `--host <value>` | `niceeval view` | string | 监听指定地址；裸写 `--host` 会监听 0.0.0.0。 |
+| `--port` | `niceeval view` | string | 监听指定端口；默认选择可用端口。 |
+| `--open` / `--no-open` | `niceeval view` | boolean | 在浏览器中打开实时 Report。 |
+| `--help` | `niceeval show`、`niceeval view` | boolean | 打印该命令的帮助。 |
+| `--record` | `niceeval clean`、`niceeval migrate`、`niceeval sandbox list`、`niceeval sandbox enter`、`niceeval sandbox history`、`niceeval sandbox diff`、`niceeval sandbox stop`、`niceeval sandbox prune` | string | 使用指定的 NiceEval Record root。 |
+| `--yes` | `niceeval clean`、`niceeval migrate` | boolean | 确认计划中的 Record maintenance 操作。 |
+| `--help` | `niceeval clean`、`niceeval migrate` | boolean | 打印该命令的帮助。 |
+| `--help` | `niceeval init` | boolean | 打印该命令的帮助。 |
+| `--json` | `niceeval docker profile list`、`niceeval docker profile doctor`、`niceeval docker cache inventory`、`niceeval docker cache gc` | boolean | 写出该命令的机器文档或事件流。 |
+| `--smoke` | `niceeval docker profile doctor` | boolean | 运行 Docker profile 的探测诊断。 |
+| `--domain` | `niceeval docker cache inventory`、`niceeval docker cache gc` | string | 选择一个由 NiceEval 管理的 Docker 缓存域。 |
+| `--apply` | `niceeval docker cache gc` | string | 应用先前签发的 Docker 缓存回收计划。 |
+| `--help` | `niceeval docker` | boolean | 打印该命令的帮助。 |
+| `--all` | `niceeval sandbox stop` | boolean | 销毁全部留存 Sandbox。 |
+| `--window` | `niceeval sandbox diff` | string | 选择一个已记录的改动窗口。 |
+| `--path` | `niceeval sandbox diff` | string | 选择 Sandbox diff 中的一个路径。 |
+| `--leave-running` | `niceeval sandbox enter` | boolean | 离开 shell 后继续保留 Sandbox。 |
+| `--orphans` | `niceeval sandbox list` | boolean | 检查已终止运行遗留的未登记 Sandbox 实例。 |
+| `--force` | `niceeval sandbox prune` | boolean | 同时清理未验证的孤儿候选项。 |
+| `--help` | `niceeval sandbox` | boolean | 打印该命令的帮助。 |
+| `--tag` | `niceeval list` | string | 只选择带有该 tag 的评估用例。 |
+| `--help` | `niceeval list` | boolean | 打印该命令的帮助。 |
 
 {/* GENERATED:END cli-flags */}
 

package/docs-site/zh/reference/define-agent.mdx

@@ -628,11 +628,11 @@ readonly user?: string;
 ```
 
 覆盖本条命令的执行身份;省略 = Sandbox 默认身份(沿用环境自己声明的身份——Docker 镜像 `USER`、
-Compose service `user:`、E2B template 默认用户、宿主当前用户,见
+Compose service `user:`、E2B template 默认用户,见
 docs/feature/sandbox/library.md「执行身份」)。
 
 语义跨 provider 一致,各 provider 映射到自己的原生机制(docker:`exec --user`;E2B:
-`{ user }`;Vercel:只认 `"root"`,映射 `{ sudo: true }`,其它值报错;local:任何值都报错)。
+`{ user }`;Vercel:只认 `"root"`,映射 `{ sudo: true }`,其它值报错)。
 本就全程 root 的 provider 视作 no-op；完全无法换身份的 provider 可不支持（抛错）——但**省略与
 显式值的语义保持一致**,不因 provider 而变。
 

package/docs-site/zh/reference/report-components.mdx

@@ -54,6 +54,7 @@ export default defineReport({
     id: "overview",
     path: "/",
     title: { en: "Overview", "zh-CN": "概览" },
+    presentation: "page",
     render: () => <Overview />,
   }],
 });
@@ -96,20 +97,20 @@ const MetricCard = defineComponent<
 
 ## Page、参数和页面选择
 
-普通 Page 的 `render` 可以直接接收固定 Sample，或先用 `load(sample, params, context)` 关闭输入。参数 Page 还要声明 `navigation: false` 与 `params`：
+普通 Page 的 `render` 可以直接接收固定 Sample，或先用 `load(sample, params, context)` 关闭输入。普通业务 Page 的 `presentation` 是 `"page"`。参数 Page 还要声明 `navigation: false`、`presentation` 与 `params`：
 
 - `encode(params)` 产生 canonical key；
 - `decode(key)` 必须能把同一种 key 还原；
 - `enumerate(sample)` 只为完整站点列出实例；
 - `context.evidence(locator)` 只返回当前 Sample 内的关闭证据视图。
 
-`pages` 是 Report 唯一的页面集合，详情必须作为 Page 或参数 Page 显式声明；Host 不补建任何 route。`niceeval show --page <route>` 只 decode、load 和 render 这个目标 Page。它不会调用 `enumerate()` 或执行其它 Page。`niceeval view` 与 `niceeval view --out` 才会枚举全部普通 Page 和参数实例，并在所有路径、链接、资源和预算通过校验后形成完整站点。
+`presentation: "overlay"` 用于叠加在当前业务 Page 上的 Attempt、Source 和 Diff 详情。其它业务页面使用 `"page"`。`pages` 是 Report 唯一的页面集合，Host 不补建任何详情或 route。`niceeval show --page <route>` 只 decode、load 和 render 这个目标 Page。它不会调用 `enumerate()` 或执行其它 Page。`niceeval view` 与 `niceeval view --out` 才会枚举全部普通 Page 和参数实例，并在所有路径、链接、资源和预算通过校验后形成完整站点。
 
 ## JSON、网页和静态站
 
 `show --json` 固定输出英语 JSON。内建 Report 输出 Host 拥有的具名领域文档；自定义 Report 输出一个 Page 的 route、标题、80-column rendered text、下载摘要和问题表。两种 v1 JSON 都在顶层以相同的 `projections` 对象携带该目标 Page 的闭合成本数据；它们不包含作者树、HTML、全站路由或站点 identity。
 
-view 与静态导出使用同一份完整站点版本。同一路由的 HTTP body 与导出目录页面 body 逐字节相同。两者都携带同一个 Host runtime；静态目录找不到 view 的端点时，实时刷新会安静停用。目录不需要网络、源 Record 或 NiceEval 安装，但浏览器必须启用随包交付的 JavaScript。禁用时页面显示可操作的错误，不维护第二套阅读路径。
+view 与静态导出使用同一份完整站点版本。两者只交付一个根 app shell，并通过 hash 打开已经关闭的 Page 或 overlay。它们都携带同一个 Host runtime；静态目录不会探测 view 的实时刷新端点。目录不需要网络、源 Record 或 NiceEval 安装，但必须通过 HTTP(S) 托管，且浏览器必须启用随包交付的 JavaScript。禁用时页面显示可操作的错误，不维护第二套阅读路径。
 
 ## 样式和资源边界
 

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

@@ -45,6 +45,12 @@ niceeval sandbox stop a3f9c2d1     # 销毁指定沙箱（id 可以只写唯一
 niceeval sandbox stop --all        # 全部销毁
 ```
 
+这些管理命令不读取 `niceeval.config.ts`。即使配置文件暂时无法执行，你仍可以查看或销毁现场。命令会读取
+`.env` 来准备 Provider 凭据；`.env` 不可读时先修复它，再重试。
+
+`sandbox` 没有 `--json` 输出。`niceeval sandbox list --json` 会直接提示 `Unknown option '--json'`，不会继续
+打印人读文本。机器输出参数只属于明确声明它的命令。
+
 `stop` 是幂等的：Sandbox 已经不在了（手动删过、云端过期）不算错误，只会把记录移掉并说明。如果 provider 销毁失败，命令会保留记录并返回错误，方便稍后重试，不会把仍活着的资源从列表里藏掉。忘了清也有提醒——下次运行开始时，如果还有上次保留的 Sandbox，会打一行提示。
 
 ## 各 Provider 的差别

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

@@ -1,7 +1,7 @@
 ---
 title: "排查结果与报告问题"
 sidebarTitle: "排查手册"
-description: "根据可见错误、Sample 状态和 rebuild 反馈，定位查看、重跑与导出问题。"
+description: "根据可见错误、判定和 Sample 状态定位问题，区分被测失败、证据错误与评估用例误判。"
 ---
 
 先用明确 Run 读取问题，不要从目录名或时间猜测目标。
@@ -13,6 +13,33 @@ pnpm exec niceeval view --run <run-id> --no-open
 
 这两条命令从同一范围形成 Sample，并执行同一份 Report。先确定选择是否正确，再检查页面中的度量和问题。
 
+## Attempt 判定为 `failed`
+
+`failed` 只说明至少一个影响 Verdict 的断言未满足。它不会自动说明被测结果违背任务，也不会指定要修 Agent 还是评估用例。
+
+先从 Run 页面给出的 Attempt locator 下钻：
+
+```sh
+pnpm exec niceeval show @<attempt-locator>
+```
+
+然后分别核对三件事：
+
+1. **任务允许什么。** 阅读评估输入、Fixture 和验收说明，确定必须满足的含义，以及是否真的要求固定表示形式。不要只用断言反推任务。
+2. **实际发生了什么。** 阅读产物、回复和断言证据，先独立判断它们是否满足任务。报告没有暴露必要证据时，记录 NiceEval 的呈现缺口，不要扫描 `.niceeval/` 私有文件补结论。
+3. **断言接受什么。** 阅读断言条件、`expected` / `received` 和断言源码，检查判据是否覆盖任务允许的正确结果。
+
+| 比较结果 | 归因与下一步 |
+| --- | --- |
+| 产物违背任务 | 修正被测应用或 Agent。 |
+| 产物满足任务，断言却拒绝了任务允许的结果 | 这是评估用例的 False Negative。修正过窄的判据，再重跑相同范围。 |
+| 产物正确，断言证据却没有如实表示它 | 修正 Adapter 映射或证据呈现。 |
+| 任务含糊或证据不足 | 先澄清任务或补足公开证据，不要强行归因。 |
+
+结构化文本可能有多种有效序列化。如果任务要求的是解析后的数据，先解析或归一化，再断言结构和值。只有字面表示本身属于任务要求时，才使用精确文本匹配。
+
+不要因为结果是红色就放宽断言。正确的修复会让判据与任务允许的结果保持一致。
+
 ## 找不到或无法打开结果
 
 | 可见错误 | 含义 | 下一步 |

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

@@ -1,7 +1,7 @@
 ---
 title: "让 Coding Agent 根据结果迭代"
 sidebarTitle: "Coding Agent 反馈闭环"
-description: "让 Coding Agent 读取 receipt 的 runIds，再用 show 或 view 查看已发布 Record 中的结果。"
+description: "让 Coding Agent 读取 receipt 的 runIds，查看结果，再区分被测失败、证据错误与评估用例误判。"
 ---
 
 Coding Agent 可以用命令行完成一次清楚的反馈闭环：阅读安装版本的文档，运行 Experiment，读取最后的 receipt，用 receipt 的 `runIds` 查看结果，再修改程序或评估用例并重新运行。
@@ -57,7 +57,7 @@ pnpm exec niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
 
 | 看到的状态 | 下一步 |
 | --- | --- |
-| `failed` | 检查任务结果与断言，修正被测程序或评估逻辑。 |
+| Attempt `failed` | 比较任务允许的结果、实际产物及证据和断言条件，再决定修被测对象、Adapter 还是评估用例。 |
 | `errored` | 检查诊断、Adapter、Sandbox 或凭据。 |
 | `not-recorded` | 检查该 expected slot 为什么没有 Member。 |
 | `core-invalid` | 阅读具名 Core issue，不要把它当成未采集。 |
@@ -65,6 +65,8 @@ pnpm exec niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
 | `migration-required` | 运行 `niceeval migrate`。 |
 | `unsupported` 或 `failed` | 只处理依赖该分析输入的查看内容，并阅读具名问题。 |
 
+处理 Attempt `failed` 时，不要为了通过一个过窄的 Match 而修改本来符合任务的产物。产物满足任务、断言却拒绝任务允许的结果时，这是评估用例的 False Negative。完整归因流程见[排查手册](/zh/troubleshooting/debugging#attempt-判定为-failed)。
+
 ## 修改后再次运行
 
 让 Agent 每次只处理一个可验证假设：修改程序或评估用例，运行相同范围，再读取新的 receipt 和 Run。需要确认所有 slot 真实执行时使用：

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

@@ -67,7 +67,7 @@ import { Picker, Schedule } from '/snippets/widgets.jsx';
 | 实验并发上限 | 实验文件的 `maxConcurrency` | 这一个实验同时跑几条 | 各算各的，两个终端的值相加 |
 | 共享状态租约 | 实验文件的 `sharedState.key` | 同一 checkpoint 的完整恢复、执行与回存区间 | 同 key 的区间串行 |
 
-全局值的解析顺序是 `--max-concurrency` → 配置里的 `maxConcurrency` → 当前 Sandbox Provider 的推荐默认值（`docker` 10、`e2b` 20、`vercel` 1、`local` 1）。推荐值反映的是 Provider 侧的约束。你自己 Agent 接口的限速用 `--max-concurrency` 压。
+全局值的解析顺序是 `--max-concurrency` → 配置里的 `maxConcurrency` → 当前 Sandbox Provider 的推荐默认值（`docker` 10、`e2b` 20、`vercel` 1）。推荐值反映的是 Provider 侧的约束。你自己 Agent 接口的限速用 `--max-concurrency` 压。
 
 ```bash
 npx niceeval exp compare --max-concurrency 19
@@ -217,7 +217,7 @@ niceeval exp compare --record .niceeval/record --max-concurrency 2
 ## 边界
 
 - 并发上限管的是资源占用，不是花钱。封顶花费用 `--budget`。
-- `local` 这类声明独占串行的 Provider 有一道 Provider 级串行限制，`--max-concurrency` 不解除它——那是正确性约束，不是调度参数。
+- 声明独占串行的 Provider 有一道 Provider 级串行限制，`--max-concurrency` 不解除它——那是正确性约束，不是调度参数。
 - 按「同时在跑的 run 数」计费或限额的 Agent 服务，贴着限额值配全局上限压不稳：退避让出的位立刻被新 Attempt 顶上，服务侧并发恒在上限。单个终端可以用实验级 `maxConcurrency` 留余量。多开时各边的值会相加，账户级配额仍要分别调低或交给外部编排。
 - 声明 `sandboxReuse: true` 的实验，每个 Sandbox 内部串行、Sandbox 之间并行，见[复用 Sandbox](/zh/tutorials/sandbox-reuse)。
 - 评估组内部稳定串行，不同组仍可并行，见[评估组](/zh/tutorials/eval-groups)。