niceeval 0.12.1 → 0.12.2-canary.31

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

@@ -1,7 +1,7 @@
 ---
 title: "NiceEval CLI：命令、flags 和退出码参考"
 sidebarTitle: "命令行"
-description: "NiceEval CLI 参考：exp、show、view、init、list 和 clean 命令，以及结果下钻、experiment、评估用例过滤、并发、预算和 CI 输出。"
+description: "NiceEval CLI 参考：exp、debug、show、view、init、list 和 clean 命令，以及结果下钻、experiment、评估用例过滤、并发、预算和 CI 输出。"
 ---
 
 [NiceEval](https://niceeval.com/) CLI 是发现、运行和查看评估用例的入口。实际执行评估用例时采用 experiment-first 模型：**`exp` 选择可签入的运行配置**，experiment 后的位置参数才按评估用例 ID 前缀过滤。agent、model 和 flags 写在 `experiments/`，不靠临时 CLI 参数。
@@ -10,38 +10,31 @@ description: "NiceEval CLI 参考：exp、show、view、init、list 和 clean
 
 <CardGroup cols={2}>
   <Card title="npx niceeval exp [path] [id-prefix]" icon="flask">
-    按 experiment id 路径运行；每个配置的 `evals` 决定覆盖哪些评估用例。
+    按 experiment id 路径运行。每个配置的 `evals` 决定覆盖哪些评估用例。
+  </Card>
+  <Card title="npx niceeval debug <experiment> <eval>" icon="bug">
+    显示一个配对的 Sandbox 与 Plugin 生命周期命令计划，不运行评估。
   </Card>
   <Card title="npx niceeval init" icon="wand-magic-sparkles">
-    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`；不生成示例评估用例文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)）。
+    创建空的 `evals/` 目录和最小的 `niceeval.config.ts`。不生成示例评估用例文件。同时写入/刷新 niceeval 指引区块——项目已有 `AGENTS.md` 就写那份，只有 `CLAUDE.md` 就写进 `CLAUDE.md`，都没有则新建 `AGENTS.md`（见[Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)）。
   </Card>
   <Card title="npx niceeval list" icon="list">
     发现并打印所有评估用例，不运行。
   </Card>
   <Card title="npx niceeval clean" icon="trash">
-    删除 `.niceeval/` 下历史快照 artifacts。
+    删除明确 writer 留下的 Record 临时目录，不删除正式 Run 或 Attempt。
   </Card>
-  <Card title="npx niceeval show [id-prefix | @locator]" icon="terminal">
-    在终端读取结果；用 `@<locator>` 或评估用例 ID 前缀下钻断言、评估用例源码、执行事件流、diff 和历史。
+  <Card title="npx niceeval show [--run]" icon="terminal">
+    在终端执行报告。不带 locator 或 `--run` 的命令读取当前项目结果；精确 Attempt 定位符或 Run ID 用于审计历史。
   </Card>
   <Card title="npx niceeval view" icon="eye">
-    打开网页结果查看器，读默认报告并交互浏览评估用例源码、执行事件流与 diff；默认范围与 `show` 相同。跨 run 时间轴（`--history`）是 `show` 专用的终端能力。
+    打开固定 ReportExecution 的网页结果。选择与 `show` 相同；要看编辑后的 Record，结束后重新运行。
   </Card>
 </CardGroup>
 
 ## 输出语言
 
-[NiceEval](https://niceeval.com/) 的 CLI 和运行时文案支持本地化。要固定输出语言（CI 日志尤其需要），写在 `niceeval.config.ts` 里：
-
-```ts
-import { defineConfig } from "niceeval";
-
-export default defineConfig({
-  locale: "en",
-});
-```
-
-没写 `locale` 时按系统 locale 判定，依次看 `LC_ALL`、`LC_MESSAGES`、`LANG`。以 `zh` 开头的值使用 `zh-CN`,其它语言使用 `en`;都没有时默认 `zh-CN`。这只影响终端/runtime 文案,不改变结果 JSON 里的机器字段,也不翻译 LLM judge prompt。
+CLI 与运行时文案是英语。这只影响终端/runtime 文案，不改变结果 JSON 里的机器字段，也不翻译 LLM Judge prompt。浏览器 `niceeval view` 自己提供中英切换。
 
 ## `npx niceeval exp [path|config] [id-prefix...]`
 
@@ -63,10 +56,10 @@ npx niceeval exp models weather
 ```
 
 <Note>
-  评估用例过滤参数只出现在 experiment 选择之后。裸 `npx niceeval weather` 不会运行；请使用 `npx niceeval exp local weather` 或 `npx niceeval exp compare weather`。
+  评估用例过滤参数只出现在 experiment 选择之后。只写 `npx niceeval weather` 不会运行。请使用 `npx niceeval exp local weather` 或 `npx niceeval exp compare weather`。
 </Note>
 
-第一个位置参数只解释为 experiment id、目录路径或文件名前缀；尾随位置参数按评估用例 id 前缀继续收窄。
+第一个位置参数只解释为 experiment id、目录路径或文件名前缀。尾随位置参数按评估用例 id 前缀继续收窄。
 
 ### `npx niceeval exp list [experiment-prefix]`
 
@@ -78,11 +71,79 @@ npx niceeval exp list compare/codex
 npx niceeval exp list --json
 ```
 
-默认输出每个配置的 `experimentId`、描述、agent、model、attempts、选中的 eval 数和 labels；`--json` 输出单个 `niceeval.experiments` 文档，并在每项附上完整的 `selectedEvalIds`。
+默认输出每个配置的 `experimentId`、描述、agent、model、attempts、选中的 eval 数和 labels。`--json` 输出单个 `niceeval.experiments` 文档，并在每项附上完整的 `selectedEvalIds`。
+
+### 查看一个配对的完整 Shell 与 lifecycle
+
+```bash
+npx niceeval debug compare/codex memory/commit0
+npx niceeval debug compare/codex memory/commit0 --json
+```
+
+两个 selector 都必须唯一。精确 ID 优先，否则可以使用唯一前缀。Eval 只能从 Experiment 自己选中的范围里匹配；零命中或多命中会列出精确候选。
+
+计划包含 Plugin lifecycle、author prepare、Agent ensure/setup/teardown、test、cleanup 与 Provider finalizer。能静态声明的 `shell()` / `command()` 展开为实际命令，普通 callback 标为 `opaque`。
+
+评估在 Group 内时，只选择这个成员不会把同组其它成员加回计划，但输出仍保留一次 Group lifecycle 包裹。人读输出只显示 `COMMAND PLAN`；`--json` 输出单个 `niceeval.debug-plan/v1` 文档。
+
+TTY 中，总览、Experiment、lane、slot 和每个 lifecycle step 都分别使用与 `show` 相同的圆角区域框，不会把整棵树放入一个总框。每条 Shell、每个 Plugin occurrence 和每个没有命令或只能运行期确定的阶段都有自己的框：
+
+```text
+╭─ sandbox.materialize ─────────────────────────────────────── OPAQUE ─╮
+│ position: lane eval-group:group · physical lifecycle template enter  │
+│ owner: provider:docker                                               │
+│ template: docker:image                                               │
+│ template owner: experiment:suite/one                                 │
+│ configured locator: exact · image="node@sha256:cd849..."             │
+│ reason: provider materialization is a runtime operation              │
+╰──────────────────────────────────────────────────────────────────────╯
+
+╭─ sandbox.prepare ──────────────────────────────────────────── EXACT ─╮
+│ position: lane eval-group:group · slot group/first #0                │
+│ owner: eval:group/first                                              │
+│ command: shell "printf fixture-ready"                                │
+╰──────────────────────────────────────────────────────────────────────╯
+```
+
+多行 Shell 会在自己的框内显示成带 gutter 的代码区，而不是压成带 `\n` 的单行字符串。缩进、空行、末尾换行和长行续行都会保留；终端控制字符显示为转义文本：
+
+```text
+╭─ sandbox.prepare ──────────────────────────────────────────────────── EXACT ─╮
+│ position: lane eval:group/first · slot group/first #0                        │
+│ owner: eval:group/first                                                      │
+│ command: shell · 5 lines                                                     │
+│   │ set -eu                                                                  │
+│   │   pnpm install                                                           │
+│   │                                                                          │
+│   │   pnpm test                                                              │
+│   │                                                                          │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+管道、`NO_COLOR` 或过窄终端逐框降级成无框标题与正文，内容和顺序不变。`--json` 不包含框线。
+
+Human 输出在每条 lane 内固定依次显示 Group before-slot、physical enter、slots、physical exit 与 Group after-slot。Physical teardown 和 Provider finalizer 因而位于使用该实例的全部 slot 之后。
+
+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 不输出。
+
+E2B template name 与 Vercel snapshot ID 是 Provider 管理的任意字符串，因此完整 locator 同样显示 `Opaque`。Human 命令计划在统一终端出口把 C0、C1、ESC、tab 与 carriage return 显示成转义文本，覆盖 template metadata 与 Shell 行。JSON 保留结构化值，并依靠 JSON string escaping。
+
+`debug` 不执行运行期 setup、test、teardown、ensure、materialize 或 finalizer，也不创建 Invocation、Run、Record、锁、Sandbox 或 build。它会加载 `.env` 和受信任定义，并执行 Experiment 的选择 predicate。Provider planner 也可能读取文件、调用只读 CLI，或查询 Docker control plane 和远端 API。
+
+计划把 Experiment 配置的全部 Attempt 列作候选 dispatch。正常运行仍可能因 carry、首过即停或预算而不执行某个 slot。`debug` 只接受可选的 `--json`；其它运行 flag 会按用法错误退出。
 
 ## 常用 flags
 
-下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 Sandbox provider 的 CLI flag，也没有项目级 provider 兜底：请在 Eval 或 Experiment 上声明 template-bearing `SandboxLayer`，使用 `niceeval/sandbox` 的 `dockerImageSandbox({ image })`、`dockerComposeSandbox({ file, workspaceService })`、`dockerfileSandbox({ context })`、`vercelSandbox({ snapshotId })`、`e2bSandbox({ template })` 或 `localSandbox()`。
+下表由 CLI 的 flag 解析表生成，表外的 flag 一律按未知 flag 报错并以非零状态退出。**没有**用于选择 Sandbox provider 的 CLI flag，也没有项目级默认 provider。请在 Eval 或 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 */}
 
@@ -105,33 +166,23 @@ npx niceeval exp list --json
 | `--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 事件流(一行一个 JSON 对象),供 coding agent、CI annotation adapter 或脚本消费;`--dry --json` 输出单个 JSON 计划文档而不是流。省略即人读文本(TTY live 面板 / 非 TTY 追加流)。`show` 命令专用:任何切片的结构化形态——同一范围、同一切片选出的同一批实体,输出成一个 JSON 文档到 stdout;与 `--report`、`--expand` 互斥,多个证据 flag(`--source`/`--execution`/`--timing`/`--diff`)只能选一个。 |
+| `--json` | boolean | `exp` 运行在 stdout 输出单一有序的 NDJSON 事件流；`exp --dry` 与 `debug` 输出各自的单个 JSON 计划文档。`show` 输出同一 ReportExecution 的宿主数据与状态，不打开第二条取数路径。 |
+| `--smoke` | boolean | `docker profile doctor` 专用：启动受限 DinD 容器并运行内层容器。 |
 | `--out` | string | `view` 命令专用:把结果查看器静态导出到指定目录。 |
 | `--port` | number | `view` 命令专用:指定本地服务器监听端口。 |
-| `--host` | string | `view` 命令专用:指定监听地址；可裸写，此时监听全部网络地址并打印可打开的本机与局域网 URL。省略时同样监听全部网络地址。 |
-| `--source` | boolean | `show` 命令专用:该 attempt 运行时保存的 Eval 源码调用树。裸写为有界默认投影；`--source=full` 展开全部调用路径；`--source=<path>` 按捕获路径后缀唯一匹配并显示该文件全文。 |
-| `--execution` | boolean | `show` 命令专用:该 attempt 的标准执行事件流(消息、thinking、Skill load、工具调用/结果);有 OTel 时同一节点补时间(证据切面)。每个内容段最多预览前 3 行,截断尾巴自带 `--expand` 展开句柄。 |
-| `--timing` | boolean | `show` 命令专用:整个 Attempt 的统一时间树;裸 `--timing` 给有界诊断投影,`--timing=full` 逐节点展开全部 runner/已关联 OTel 节点。 |
-| `--grep` | string | `show` 命令专用:只与 `--execution` 组合;JS 正则,只输出命中的执行卡片(角色文本、工具名、input、result,失败命令再加 display/stdout/stderr),末尾报跨 attempt 汇总 `N matches in M attempts`。与 `--expand` 互斥。 |
-| `--expand` | string | `show` 命令专用:只与 `--execution` 组合,要求范围恰好命中一个 attempt;展开一张卡片的完整落盘内容(不截断)。句柄语法 `t<轮次>.c<卡片>`(agent 事件)或 `cmd<n>`(失败 Sandbox 命令),来自截断卡片自带的提示。与 `--grep` 互斥。 |
-| `--diff` | boolean | `show` 命令专用:sandbox 里的文件改动摘要;`--diff=<文件路径>` 看单个文件的完整改动(路径必须 `=` 连写)。 |
-| `--history` | boolean | `show` 命令专用:执行时间轴——对匹配的每个 experiment × eval 分节,逐 attempt 列时间 / verdict / 摘要 / 耗时 / 成本 / locator;与 `--report` 互斥。 |
-| `--usage` | boolean | `show` 命令专用:范围内逐 attempt 的用量表(`UsageTable` 装配)——判定、轮数、工具调用数、token 拆分与成本;多个 experiment 时逐 experiment 分节、节尾各自合计,缺失字段显示 `—` 且不计入合计。`@<locator>` 范围下退化成该 attempt 的单行表。 |
-| `--stats` | boolean | `show` 命令专用:eval × experiment 的稳定性矩阵(`StabilityMatrix` 装配)——每格是该组合全部历史执行(跨快照去重、不设可比性门槛)的判定计数,回答「哪些题从来没通过过」;与 `@<locator>`、`--report` 互斥。 |
-| `--exp` | string | `show` / `view` 命令专用:按路径段前缀收窄 experiment(与 `niceeval exp` 位置参数同一套匹配);目录路径会选中其下全部配置。可重复;出现两次以上进入对照语义——每次出现必须恰好解析到一个 experiment,顺序即对照条件顺序、首个是基准,`@<locator>` 与重复 `--exp` 互斥。`view --out` 时同一收窄决定出站内容。 |
-| `--record` | string | `show` / `view` / `accept` / `sandbox enter\|list\|stop` 共用:记录根目录(`.niceeval` 之外的另一个根,如 `publish` 产出的发布根)。 |
-| `--run` | string | `view` 命令专用:只打开这一份快照文件(`run.json`);文件不可读时命令失败(扫描模式只跳过)。 |
-| `--report` | string | `show` / `view` 命令专用:用文件默认导出的 `defineReport(...)` 替换两者共用的默认报告。 |
-| `--theme` | string | `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` 命令专用：内建 `overview` 或受信任的 Report module 路径。 |
 | `--page` | string | `show` / `view` 命令专用:选择报告的初始页;`show` 渲染该页并在尾部附其余页索引,`view` 以它作初始路由。未命中的页 id 按用法错误退出并列出可用页 id。 |
-| `--fresh` | boolean | `show` / `view` 命令专用:只统计新执行的 attempt(排除携带条目与跨快照拼入的历史执行);被排除的题按覆盖事实转为覆盖占位行,不静默消失。 |
 | `--teardown` | boolean | `exp` 命令专用:补齐被强杀打断的实验级 teardown——只对选中的实验各执行一次 teardown(新进程语义),不派发 attempt、不跑 setup;没有遗留登记也照常执行。与 eval 前缀位置参数组合是用法错误。 |
 | `--dry` | boolean | 只打印本次会匹配到的 eval × 运行配置,不实际执行(人读文本或 `--json` 单文档,见「机器怎么读:--json」)。 |
-| `--force` | boolean | 忽略上次运行结果,不跳过已通过的 (experiment, eval) 组合,强制全部重跑。 |
+| `--force` | boolean | `sandbox prune` 专用:除 orphan 外也销毁 unverified 实例;`exp` 明确拒绝此 flag,重跑失败项或全部项请用 `--rerun` / `--rerun all`。 |
 | `--rerun` | boolean | `exp` 命令专用:重新运行失败项(裸写/failed)或全部项(all),不改变长期指纹。 |
-| `--strict` | boolean | CI 中推荐使用:让软阈值(`soft`)失败也计入整条 eval 的 verdict。 |
 | `--early-exit` / `--no-early-exit` | boolean | 某个 eval 的一次 attempt 通过后,停止该 eval 剩余的 attempts;省略默认关(`attempts` 默认跑满、测完整通过率)。 |
 | `--open` / `--no-open` | boolean | `view` 命令专用:启动后自动打开浏览器(默认行为)。 |
+| `--yes` | boolean | `clean` / `migrate` 专用：确认不可逆 maintenance 动作或没有 Git restore point 的 migration。 |
 | `--help` | boolean | 打印用法说明并退出。 |
 | `--version` | boolean | 打印 niceeval 的版本号并退出。 |
 
@@ -154,11 +205,11 @@ npx niceeval exp compare-models weather-tool
 
 运行命名 experiment，用矩阵比较 agents、models 或 flags。第二个参数开始是评估用例 ID 前缀过滤。
 
-`show` 与 `view` 是顶层命令，应写成 `npx niceeval show`、`npx niceeval view`。误写成 `npx niceeval exp show` / `exp view` 且没有同名 experiment 时，CLI 会在“不存在的实验”错误后提示正确命令；仓库确实存在同名 experiment 时仍按合法 id 执行。
+`show` 与 `view` 是顶层命令，应写成 `npx niceeval show`、`npx niceeval view`。误写成 `npx niceeval exp show` / `exp view` 且没有同名 experiment 时，CLI 会在“不存在的实验”错误后提示正确命令。仓库确实存在同名 experiment 时仍按合法 id 执行。
 
 ## 两种输出：人读文本与 `--json`
 
-`exp` 的输出只有两种形态，只改变展示，不改变选择、调度、判定、artifact 或退出码：
+`exp` 的输出只有两种形态，只改变展示，不改变选择、调度、判定、Record 提交或退出码：
 
 ```bash
 # 不加 flag = 人读文本：TTY 里是动态 dashboard，管道/CI 日志里自动降级为只追加的纯文本流
@@ -168,75 +219,90 @@ npx niceeval exp compare
 npx niceeval exp compare --json
 
 # CI 门禁:退出码 + JUnit；需要 JSON 汇总时运行后用 show --json 重定向
-npx niceeval exp compare --strict --junit .niceeval/junit.xml
+npx niceeval exp compare --junit ./artifacts/niceeval-junit.xml
 ```
 
-两种形态怎么选见[运行器 · Reporter](/zh/explanation/runner#reporter)；AI 反馈闭环的完整用法（读事件流、按 locator 下钻、局部重跑）见 [AI 反馈闭环](/zh/tutorials/agent-feedback-loop)；CI 集成（GitHub Actions、退出码、JUnit）见 [CI 集成](/zh/tutorials/ci-integration)。
-
-## `session list` / `session show`
+两种形态怎么选见[运行器 · Reporter](/zh/explanation/runner#reporter)。AI 反馈闭环的完整用法见 [AI 反馈闭环](/zh/tutorials/agent-feedback-loop)。CI 集成（GitHub Actions、退出码、JUnit）见 [CI 集成](/zh/tutorials/ci-integration)。进程结束后没有 `watch` 或 session 查询；长期数据从停稳 Record 生成报告。
 
-每次 `niceeval exp …` 调度会在 `.niceeval/sessions/` 留下一份可查询的 Session；查询本身只读，不加载配置、不发现源码、不启动运行时：
+## `view`
 
 ```bash
-npx niceeval session list
-npx niceeval session list --all --json
-npx niceeval session show <sessionId>
+npx niceeval view
+npx niceeval view --run 01H...
+npx niceeval view @01H...
+npx niceeval view --host 192.168.0.199
 ```
 
-默认只列出心跳仍有效的活动 Session；`--all` 追加已封口记录，并把超过 30 秒没有心跳的记录单列为 `stale`。`--json` 输出单个 `niceeval.sessions`（或 `niceeval.session`）文档，不是 `exp --json` 的事件流。
+打开本地记录查看器。它和 `show` 共用默认 Report 与选择规则。不带 locator 或 `--run` 的命令从默认 Record 读取所有身份仍匹配当前项目的结果；精确 `@<AttemptLocator>` 显示该 Attempt 的默认概览；`--run` 读取指定历史 Run。随后内部 host 投影所需事实，并执行一次 Report。
 
-## `view`
+没有显式 `--report` 时，`--run` 使用内建 `run-membership-overview`，精确 locator 使用 `attempt-overview`。`project-current` 才使用配置里的 Report，并在没有配置时回退到通用 `default-overview`。显式 `--report` 始终优先。Config 仍会为 Theme 和 `view` rebuild 加载；这里只说明配置里的 Report 不参与显式 Run 的默认选择。
 
-```bash
-npx niceeval view
-```
+省略 `--host` 时，`view` 只监听 `127.0.0.1`。传入具体 hostname / IP 会显式监听该地址；只写 `--host` 时则监听全部 IPv4 接口。wildcard listener 先打印 loopback URL，再打印可用接口 URL；`--page` 应用到每条 URL，自动打开浏览器只使用第一条。
+
+非 loopback 模式是无认证、无加密的开发服务器。所有网络可达客户端都能读取报告、execution JSON 和 downloads，所以只能在可信网络使用；启动时也会打印同样的警告。server 只接受已公布的 Host authority 与只读 `GET` / `HEAD` 请求；未来写端点必须另行设计认证与 CSRF 边界。
 
-打开本地记录查看器。它和 `show` 共用同一份默认报告和同一套默认选择——对每个 experiment、每个评估用例，取历次运行里最新的判定；每个 experiment 的集合来自 Run `selectedEvalIds`。默认报告直接比较当前 Sample。评估用例 ID 前缀、`--exp`、`--record` 对两者的收窄一致。
+此前的局部执行可能让部分 slot 以 `reference` 采用已有 Attempt。这些是当时的采用事实，不是补跑状态。同一份 `AnalysisSample` 不会在页面请求时重新选择。`--experiment` 可按完整 ID 收窄当前项目目标；`--record` 只在主动读取其它 Record root 时使用。
 
-## `show [id-prefix...]`
+## `show`
 
 ```bash
 npx niceeval show
-npx niceeval show weather/brooklyn
-npx niceeval show @1k2m9qrs
-npx niceeval show @1k2m9qrs --source
-npx niceeval show @1k2m9qrs --execution
-npx niceeval show @1k2m9qrs --execution --expand t2.c3
-npx niceeval show fixtures/button --diff
-npx niceeval show weather/brooklyn --history
+npx niceeval show --run 01H...
+npx niceeval show --run 01H... --run 01J...
+npx niceeval show @01H...
+npx niceeval show @01H... --source
+npx niceeval show @01H... --execution
+npx niceeval show @01H... --timing
+npx niceeval show @01H... --timing=full
+npx niceeval show --run 01H... --page attempt-0123456789ABCDEFGHJKMNPQRS
+npx niceeval show --run 01H... --report ./reports/summary.ts --page overview
 ```
 
-`show` 是终端结果入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。位置参数选「看哪些评估用例」（ID 前缀）或直接用 `@<locator>` 精确选一个 attempt；不带位置参数时直接比较当前 Scope，`--exp` 按 experiment id 路径收窄。
+`show` 是终端报告入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。它不接受模糊的位置选择。精确 `@<AttemptLocator>` 默认显示该 Attempt 的 Evaluation identity、evaluation kind、四态 Verdict、Assertions 和适用的 Score。
 
-`@<locator>` 不带证据 flag 时给出该 attempt 的紧凑全景（断言摘要、执行摘要、可选 OTel 时间、diff 摘要）；`--source`、`--execution`、`--timing`、`--diff` 是证据切面，各自接受任意范围，不限于单个 `@<locator>`——范围含多个 attempt 时按 experiment id、eval id、attempt 序逐 attempt 分节。`--record <目录>` 指定记录根，`--history` 查看跨 Run 趋势。`--exp` 可重复：出现一次收窄范围，两次以上进入对照语义（每个 `--exp` 必须恰好解析到一个 experiment，顺序即对照条件顺序）。完整的阅读顺序、输出示例和 artifact 说明见[查看结果](/zh/tutorials/viewing-results)。
+加 `--source`、`--execution` 或 `--timing` 可查看对应的专用证据面。`--timing` 默认显示精简阶段树；`--timing=full` 还显示 interval identity、parent 和 offset。三种证据面互斥，并且都要求一个精确 Attempt 定位符。
 
-`--execution` 的卡片正文是有界预览：每个内容段（消息正文；工具卡的 input 与 result 各算一段）最多显示前 3 行，每段另有 1 KiB（UTF-8 字节）兜底防单行超长。有折叠的卡片在卡尾报被折的行数与字符数，并自带该卡片的展开句柄，整行就是可复制的完整命令：
+不带 locator 或 `--run` 的 `show` 规划当前项目身份，并扫描默认 Record 中全部 published Run。只有 Experiment、Eval、Attempt 序号、evaluation kind、input identity 与 config identity 仍匹配的 slot 才进入 Sample；命令不会按时间只留一个 Run。没有匹配结果时显示空 Sample，过期结果仍可用完整 `--run` 读取。
 
-```text
-    (+3055 lines · 263161 chars · niceeval show @1k2m9qrs --execution --expand t2.c3)
-```
+`--run` 可重复，只读取这些显式历史 Run。`--experiment <id>` 可重复，按完整 ExperimentId 收窄当前项目目标，不能与 `--run` 合用。`exp`、不带 `--record` 的 `show` 与 `view` 默认使用同一个 `.niceeval/record`。
 
-`--expand <handle>` 只与 `--execution` 组合、要求范围恰好命中一个 attempt，单独输出该卡片的完整落盘内容。句柄 `t<轮次>.c<轮内卡序>`（agent 事件卡）或 `cmd<n>`（失败 Sandbox 命令卡）从截断提示里抄，不自己数。落盘时已过 256 KiB 单值上限的内容展开后如实标注 `truncated` 与原始字节数。`--grep` 命中的卡片同样受预览预算，尾巴照带句柄；`--json` 恒输出完整值、从不截断，与 `--expand` 互斥。
+单个 `--run` 用于核对这一轮的 expected-slot 分母与 membership；多个 `--run` 用同一表形状比较多个固定历史边界。即使两个 Run 指向同一个 Attempt，它们也可能分别由实际执行、自动沿用或人工采用形成。`exp --json` 最后一条 receipt 的 `runIds` 是机器稳定出口；TTY 完成反馈也显示 Run ID。`accept` 的成功反馈会显示新 Run ID，但这行人读文本不是 JSON receipt 或自动化输入契约。
 
-## `--early-exit` 与 `--strict`
+内建 `run-membership-overview` 固定使用 `reportId: "run-membership-overview"`、`pageId: "run-membership"` 和 route `/`。
 
-`--early-exit` 默认关闭：`--attempts` > 1 时默认把每次 attempt 都跑完，给出真实通过率——这是 NiceEval 衡量 agent 稳不稳的核心指标，默认不该被无声截断。只想知道"这题能不能过"、不在乎完整分布时，显式加 `--early-exit`：某个评估用例的一次 attempt 通过后，自动停止该评估用例剩余的 attempts（省钱）。实验文件里写了 `earlyExit: true` 时，用 `--no-early-exit` 强制关掉它。
+`Run membership` 表的稳定 column keys 分成三组：
+
+- row identity：`runId`、`slotId`。
+- Core 与 provenance：`slotState`、`memberRelation`、`sourceAttemptLocator`、`membershipState`、`membershipOutcome`。
+- Attempt 事实：`verdictState`、`verdict`。
+
+单 Run 和多 Run 都按 `runId`、`slotId` 排序；表在排序后最多显示 200 rows，并显示省略数量。
+
+`membershipOutcome` 来自公开 projector，值为 `carried`、`accepted`、`executed`、`not-dispatched` 或 `interrupted`。它不是持久 payload 的 raw `action` 字段。内建表是 bounded summary；已知 Attempt 的身份与证据用 `show @<AttemptLocator>` 下钻，需要其它 Run 字段时显式选择自定义 Report。
 
-`--strict` 不是"更严格地报错"，而是改变软阈值断言的判定：`.atLeast(n)` 这类软阈值（`soft` severity）平时失败不会把整条评估用例判为 `failed`（只是记一条不达标的断言），加了 `--strict` 之后，软阈值没达标也会让整条评估用例的 verdict 计为 `failed`。CI 中推荐加上，避免"断言分数不够但评估用例显示通过"的情况被放过。
+选择完成后，`show` 用已选 handle 读取 Report 声明的 Projection，并形成一次 `ReportExecution`。请求的 Attachment 为 unavailable、migration-required、unsupported、partial 或 invalid 时，命令会原样显示状态；未请求的未知或损坏 Attachment 不影响当前页面。完整契约见[查看结果](/zh/tutorials/viewing-results)。
+
+`view --out <目录>`（或显式 `--run`）使用同一份 ReportExecution 预渲染自包含静态站。目标目录必须不存在；全部页面、下载项与静态资产路径先通过校验。写完全部文件后，exporter 最后创建 `complete` marker。导出过程不会把 Record 路径或 blob 路径交给用户 Report。
+
+命令在持有 sample handle 时完成所需 Projection 和 Report execution。返回的 ReportExecution 不再访问 Record。运行中的 `view` 对变化构造新的固定 execution；成功后替换当前 revision，失败保留 last-good execution。静态 export 只消费已经完成的 execution。
+
+## `--early-exit`
+
+`--early-exit` 默认关闭：`--attempts` > 1 时默认把每次 attempt 都跑完，给出真实通过率——这是 NiceEval 衡量 agent 稳不稳的核心指标，默认不该被无声截断。只想知道"这题能不能过"、不在乎完整分布时，显式加 `--early-exit`：某个评估用例的一次 attempt 通过后，自动停止该评估用例剩余的 attempts（省钱）。实验文件里写了 `earlyExit: true` 时，用 `--no-early-exit` 强制关掉它。
 
 ## 环境变量只放凭据
 
-跑几次、超时、并发、预算、judge 模型和端点、界面语言——这些都是配置，只从 CLI flag、`experiments/` 下的 experiment 文件和 `niceeval.config.ts` 读。优先级从高到低：CLI flag > experiment > `niceeval.config.ts` > 内置默认值。没有对应的环境变量，同一个值不会有第三条来路。
+跑几次、超时、并发、预算、judge 模型和端点——这些都是配置，只从 CLI flag、`experiments/` 下的 experiment 文件和 `niceeval.config.ts` 读。优先级从高到低：CLI flag > experiment > `niceeval.config.ts` > 内置默认值。没有对应的环境变量，同一个值不会有第三条来路。
 
-环境变量留给凭据（API key、provider token）和终端环境（`NO_COLOR`、系统 locale）。每个 agent / sandbox / judge 只认自己那一个变量名，不会在环境里翻找其它 key；启动时自动加载 cwd 下的 `.env`（不覆盖已经存在的环境变量）。完整清单和迁移对照见[配置与环境变量](/zh/tutorials/configuration)。
+环境变量留给凭据（API key、provider token）和终端环境（`NO_COLOR`）。每个 agent / sandbox / judge 只认自己那一个变量名，不会在环境里翻找其它 key。启动时自动加载 cwd 下的 `.env`（不覆盖已经存在的环境变量）。完整清单见[配置与环境变量](/zh/tutorials/configuration)。
 
 ## 退出码
 
 | 退出码 | 含义 |
 |---|---|
 | `0` | 全部评估用例通过（或 `list`、`init`、`clean` 等命令正常完成）。 |
-| `1` | 存在 `failed` / `errored` 的评估用例；或命令用法错误（如 `exp` 没匹配到任何实验、传了不支持的 flag 组合）。 |
-| `2` | 运行时崩溃（未捕获异常），CLI 顶层兜底捕获后退出。 |
+| `1` | 存在 `failed` / `errored` 的评估用例。或命令用法错误（如 `exp` 没匹配到任何实验、传了不支持的 flag 组合）。 |
+| `2` | 运行时崩溃（未捕获异常），CLI 顶层捕获后退出。 |
 | `130` | 收到中断信号（Ctrl-C / SIGTERM）后退出。 |
 
-需要 CI 把软阈值失败也当失败处理时，同时使用 `--strict`（见上）。
+CI 的退出码直接来自 Pass Eval 的 Boolean conditions 与最终 Verdict；JUnit 使用同一份 sealed projection。

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

@@ -1,7 +1,7 @@
 ---
-title: "defineDirectAgent 和 defineSandboxAgent：Adapter 参考"
+title: "defineAgent 和 defineSandboxAgent：Adapter 参考"
 sidebarTitle: "定义 Adapter"
-description: "defineDirectAgent 和 defineSandboxAgent 参考：AgentContext、AgentSession、Sandbox 接口和共享 Sandbox helpers。"
+description: "defineAgent 和 defineSandboxAgent 参考：AgentContext、AgentSession、Sandbox 接口和共享 Sandbox 辅助函数。"
 ---
 
 import { TurnRoundtrip } from '/snippets/diagram-turn-roundtrip.jsx';
@@ -10,20 +10,20 @@ import { TurnRoundtrip } from '/snippets/diagram-turn-roundtrip.jsx';
 
 <TurnRoundtrip />
 
-## `defineDirectAgent`
+## `defineAgent`
 
 用于 direct agent 接入：
 
 ```ts
-import { completeEvidenceCoverage, defineDirectAgent } from "niceeval/adapter";
+import { completeEvidenceCoverage, defineAgent } from "niceeval/adapter";
 ```
 
-`defineDirectAgent` 产出的 `Agent.kind` 恒为 `"direct"`（内部判别字段，不用你声明）。`t` 上没有需要声明才解锁的能力位——`t.sandbox` 这类文件系统断言只在 `defineSandboxAgent` 构造的 Agent（`kind: "sandbox"`）上才有；其余由 `send` 实际返回的事件和 `ctx.session` 的使用决定，详见[能力位参考](/zh/reference/capabilities)。字段全集见下方「Agent 与 Adapter Context 字段」。
+`defineAgent` 产出的 `Agent.kind` 恒为 `"direct"`（内部判别字段，不用你声明）。`t` 上没有需要声明才解锁的能力位——`t.sandbox` 这类文件系统断言只在 `defineSandboxAgent` 构造的 Agent（`kind: "sandbox"`）上才有。其余由 `send` 实际返回的事件和 `ctx.session` 的使用决定，详见[能力位参考](/zh/reference/capabilities)。字段全集见下方「Agent 与 Adapter Context 字段」。
 
 ### direct agent 示例
 
 ```ts
-export default defineDirectAgent({
+export default defineAgent({
   name: "echo",
   evidenceCoverage: completeEvidenceCoverage,
   async send(input) {
@@ -51,7 +51,7 @@ export default defineDirectAgent({
 
 ## `defineSandboxAgent`
 
-用于 coding agent CLI。产出的 `Agent.kind` 恒为 `"sandbox"`——`t.sandbox`、`t.sandbox.fileChanged()` 等文件系统断言只在这类 agent 上解锁。字段全集同样见下方「Agent 与 Adapter Context 字段」的 `SandboxAgentDef`；`ctx.sandbox`(`Sandbox` 接口)的完整方法见再下方「Sandbox 接口」。
+用于 coding agent CLI。产出的 `Agent.kind` 恒为 `"sandbox"`——`t.sandbox`、`t.sandbox.fileChanged()` 等文件系统断言只在这类 agent 上解锁。字段全集同样见下方「Agent 与 Adapter Context 字段」的 `SandboxAgentDef`。`ctx.sandbox`(`Sandbox` 接口)的完整方法见再下方「Sandbox 接口」。
 
 ```ts
 import { completeEvidenceCoverage, defineSandboxAgent } from "niceeval/adapter";
@@ -85,7 +85,7 @@ export default defineExperiment({
 
 ## Agent 与 Adapter Context 字段
 
-`defineDirectAgent`（`DirectAgentDef`）、`defineSandboxAgent`（`SandboxAgentDef`）的构造参数，
+`defineAgent`（`DirectAgentDef`）、`defineSandboxAgent`（`SandboxAgentDef`）的构造参数，
 以及两者的 `send(input, ctx)` 都会拿到的 `ctx`（`AgentContext`）：
 
 {/* GENERATED:BEGIN agent-def */}
@@ -307,6 +307,17 @@ readonly evalId?: string;
 第三方直接构造 AgentContext 时可省略。Adapter 可用它定位与题目同目录的只读宿主资产，
 但不能据此绕过 Sandbox 的隐藏判据隔离。
 
+#### `evalGroup`
+
+```ts
+readonly evalGroup?: {
+  readonly id: string;
+  readonly definitionHash: string;
+};
+```
+
+当前 Attempt 的 Eval Group；未分组 Eval 省略。
+
 #### `attempt`
 
 ```ts
@@ -358,13 +369,10 @@ diagnostic(input: DiagnosticInput): void;
 #### `fact`
 
 ```ts
-fact(key: string, value: string | number | boolean): void;
+fact(name: string, value: JsonValue): void;
 ```
 
-第三条反馈通道:上报本次运行的中性环境观测(如实际生效的 agent 配置、缓存命中状态)。
-落进 `AttemptRecord.facts` 成为一等观测量;不影响 Turn status 或 verdict,不参与
-verdict / 评分 / 指纹。key 匹配 `[a-z0-9._-]{1,64}`,value 是标量;同 key 后写覆盖先写,
-非法 key 或非标量 value 抛错。形状与归属语义见 docs/feature/record/architecture.md#facts运行事实。
+写入本 Attempt 的 generic custom fact document。name 使用反向域格式且不能以 `niceeval.` 开头；同一 owner/name 只允许写一次，第二次写入是 typed error，不替换也不追加。value 可以是任意 JsonValue。`{ observedAt, value }` 经 JSON.stringify 后最多 65,536 UTF-8 bytes；超限同步抛出 `record-custom-fact-too-large`，且不留下部分文件。不影响 Turn status、verdict、评分或指纹。形状与归属语义见 docs/feature/record/architecture.md。
 
 #### `log`
 
@@ -380,7 +388,7 @@ log(msg: string): void;
 `ctx.session`(`AgentSession`)是一条会话线的状态槽:同一条会话线的每次 `send` 拿到同一个 `ctx.session`,新会话线(评估用例第一轮 / `t.newSession()` 之后)拿到一个全新的。存取器:
 
 - `id?: string` / `capture(id): void` —— 会话续接·服务端记历史时用:`id` 是本线记过的会话 id(新线是 `undefined`),`capture` 记回传的 id(只在还没记过时落地)。
-- `createSessionSlot<T>(name)` —— 在 Adapter 模块作用域创建一个 typed slot；slot 按 symbol 身份隔离。
+- `createSessionSlot<T>(name)` —— 在 Adapter 模块作用域创建一个 typed slot。slot 按 symbol 身份隔离。
 - `get(slot)` / `set(slot, value)` —— 存取客户端历史或 Adapter 私有状态。
 - `take(slot)` —— 读取并删除 HITL 停轮现场，一次消费。
 
@@ -388,7 +396,7 @@ log(msg: string): void;
 
 ## Sandbox 接口
 
-Sandbox 型 agent 的 `ctx.sandbox`(`Sandbox`)是当前隔离环境的句柄；`CommandOptions` 是 `runCommand` / `runShell` 的可选项：
+Sandbox 型 agent 的 `ctx.sandbox`(`Sandbox`)是当前隔离环境的句柄。`CommandOptions` 是 `runCommand` / `runShell` 的可选项：
 
 {/* GENERATED:BEGIN sandbox-methods */}
 
@@ -418,10 +426,11 @@ readonly sandboxId: string;
 readonly otlpHost: string | null;
 ```
 
-本地 OTLP 接收器的目标 host。
-- `string`:Sandbox 内可通过该 hostname 回连宿主 OTLP 端口(如 docker 的 `host.docker.internal`)。
-- `null`:Sandbox 运行在远程云端(如 e2b/vercel),无法访问宿主本地端口 → 跳过 tracing。
-  可通过环境变量 `NICEEVAL_OTLP_HOST` 强制覆盖(如配置 tunnel 时)。
+OTLP receiver 的放置能力。
+- `string`:Sandbox 内可通过该 hostname 访问宿主 receiver。
+- `null`:provider 不承诺宿主回连；runner 尝试在 Sandbox 内启动 attempt-scope receiver。
+  这不保证 tracing 成功；镜像缺少 receiver 所需运行时时只记录 supplemental diagnostic。
+`defineConfig({ telemetry: { host } })` 可在作者已经提供受控 tunnel 时显式覆盖。
 
 #### `appendLog`
 
@@ -533,4 +542,4 @@ readonly signal?: AbortSignal;
 
 ## ctx 与 t
 
-`ctx` 是 adapter 侧看到的运行上下文；`t` 是评估用例作者看到的测试上下文。两者使用同一批运行数据，但职责不同。
+`ctx` 是 adapter 侧看到的运行上下文。`t` 是评估用例作者看到的测试上下文。两者使用同一批运行数据，但职责不同。

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

@@ -18,7 +18,7 @@ export default defineConfig({
 });
 ```
 
-`report` 收 `defineReport` 的产物本身（import 自己的报告文件），不是路径字符串。`niceeval show` 与 `niceeval view` 不带 `--report` 时装载它，没写就装载内置的默认报告；`--report` 按次覆盖，`--report standard` 回到内置报告。写法与整套报告能力见[编写自定义报告](/zh/tutorials/custom-reports#设成项目默认)。
+`report` 收 `defineReport` 的产物本身（import 自己的报告文件），不是路径字符串。`niceeval show` 与 `niceeval view` 不带 `--report` 时装载它，没写就装载内置的默认报告。`--report` 按次覆盖，`--report standard` 回到内置报告。写法与整套报告能力见[编写自定义报告](/zh/tutorials/custom-reports#设成项目默认)。
 
 ## Config 字段
 
@@ -29,7 +29,7 @@ export default defineConfig({
 #### `report`
 
 ```ts
-report?: ReportDefinition;
+report?: Report;
 ```
 
 view/show 的项目默认报告。
@@ -40,7 +40,7 @@ view/show 的项目默认报告。
 theme?: ThemeDefinition;
 ```
 
-view 的项目默认主题。
+view 的 host-owned closed visual token declaration.
 
 #### `name`
 
@@ -51,15 +51,6 @@ name?: LocalizedText;
 项目名,显示在 `niceeval view` 顶部 hero(`<h1>`),省略则回退到通用标题。
 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
 
-#### `locale`
-
-```ts
-locale?: string;
-```
-
-CLI 与运行时文案的界面语言(BCP 47,如 `"en"` / `"zh-CN"`);CI 里想让日志恒定一种语言就写这个。
-省略则按系统 locale(`LC_ALL` / `LC_MESSAGES` / `LANG`)判定,都没有时用 `zh-CN`。
-
 #### `workspace`
 
 ```ts
@@ -120,8 +111,8 @@ OTLP 接收配置,niceeval 项目内唯一入口(不读 NICEEVAL_OTLP_* 环境
 临时端口(经 ctx.telemetry 交给 adapter)。代价:固定端口下同机同时只能跑一个 niceeval 进程,
 且该端口被别的进程占用时会报错——换一个空闲端口写回这里即可。
 `host` 是报给 adapter 的接收端 hostname(而非监听地址,监听地址恒为 0.0.0.0):默认
-"127.0.0.1";docker Sandbox 型 tracing 需要 "host.docker.internal" 之类的场景,或配了隧道
-的远程接入,在这里覆盖。
+"127.0.0.1"。只有作者已经提供受控 tunnel / 可达路由时才在这里覆盖；Docker Sandbox
+默认把 receiver 放在 Sandbox 内，不依赖隐式宿主 gateway。
 
 #### `pricing`
 
@@ -135,4 +126,4 @@ pricing?: globalThis.Record<string, PriceOverride>;
 
 {/* GENERATED:END config-fields */}
 
-[NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：评估用例自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 setup。`Config` 刻意没有 `sandbox` 字段，也不自动探测 provider；请在 Eval 或 Experiment 上声明 template-bearing `SandboxLayer`，让 link planning 在创建任何资源前确定它的 owner 与配对结果。
+[NiceEval](https://niceeval.com/) 把环境准备放在普通代码里：评估用例自己需要的文件写在 `test(t)`，agent 自己的准备写在 adapter 的 setup。`Config` 刻意没有 `sandbox` 字段，也不自动探测 provider。请在 Eval 或 Experiment 上声明 template-bearing `SandboxLayer`，让 link planning 在创建任何资源前确定它的 owner 与配对结果。