niceeval 0.13.0 → 0.13.2-canary.35

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

@@ -14,7 +14,7 @@ HITL（human-in-the-loop，人工介入）指 agent 在执行中间停下来，
 - **Codex**：审批模式（suggest / auto-edit 等）决定哪些动作要先经人确认，本质是同一扇门。
 - **AI SDK 应用**：工具不带 `execute` 时，工具调用会浮到前端，由界面上的人确认后把结果交回（`addToolResult`），模型再继续——这是自研应用里最常见的审批门写法。
 
-对被测对象来说，这条"停下来等人"的分支和别的行为一样需要回归：批准后该发生的事发生了吗？拒绝后真的没做吗？问错了人、停错了地方呢？但评估用例是自动跑的，里面没有人。[NiceEval](https://niceeval.com/) 的做法是把"人"折叠成三个可编排的动作：看到 agent 停了（`t.parked()`）、检查它在等什么（`t.requireInputRequest()`）、替人回答（`t.respond()`）。批准、拒绝、补充信息，从此都是能写进评估用例的路径。
+对被测对象来说，这条"停下来等人"的分支和别的行为一样需要回归：批准后该发生的事发生了吗？拒绝后真的没做吗？问错了人、停错了地方呢？但评估用例是自动跑的，里面没有人。[NiceEval](https://niceeval.com/) 的做法是把"人"折叠成三个可编排的动作：用 `t.check(turn.status, equals("waiting"))` 确认 agent 停下、用 `t.requireInputRequest()` 检查它在等什么、再用 `t.respond()` 替人回答。批准、拒绝、补充信息，从此都是能写进评估用例的路径。
 
 ## 停轮如何表达：waiting + input.requested
 
@@ -36,10 +36,10 @@ HITL（human-in-the-loop，人工介入）指 agent 在执行中间停下来，
 ## 评估侧：三个动作
 
 ```ts
-import { toolMatch } from "niceeval/expect";
+import { equals, toolMatch } from "niceeval/expect";
 
 const draft = await t.send("给老板发一封周报邮件。");
-draft.parked();                                          // ① 断言这一轮停下了
+t.check(draft.status, equals("waiting"));                // ① 断言这一轮停下了
 
 const req = t.requireInputRequest({ action: "send_email" });   // ② 取出待答请求
 
@@ -47,7 +47,7 @@ await t.respond({ request: req, optionId: "approve" });  // ③ 替人回答,发
 t.calledTool(toolMatch("send_email", { status: "completed" }));
 ```
 
-- `t.parked()` 断言这一轮确实以 waiting 停下。反过来 `t.succeeded()` 在 waiting 轮上会失败——停轮是显式状态，不会被当成"跑完了"。
+- `t.check(draft.status, equals("waiting"))` 断言这一轮确实以 waiting 停下。反过来 `draft.succeeded()` 在 waiting 轮上会失败——停轮是显式状态，不会被当成"跑完了"。
 - `t.requireInputRequest(filter)` 从待处理请求里精确取一个（按 `id` / `prompt` / `action` / `optionIds` 等字段匹配），匹配到 0 个或超过 1 个都会抛，多个请求并停时靠它消歧。
 - `t.respond(...)` 回答并发出下一轮。同类请求要给同一个答案时（比如逐个批准一批改动），`t.respondAll(optionId)` 一次处理完。
 
@@ -57,13 +57,13 @@ t.calledTool(toolMatch("send_email", { status: "completed" }));
 
 HITL 对 Adapter 的全部要求就三件事——前两件发生在停下的那一轮，第三件发生在回答到达的下一轮：
 
-1. **停轮时如实返回 `status: "waiting"`**，不要把挂起报成 `"completed"`，否则 `parked()` 失效、`succeeded()` 假通过。
+1. **停轮时如实返回 `status: "waiting"`**，不要把挂起报成 `"completed"`，否则 `t.check(turn.status, equals("waiting"))` 会失败、`succeeded()` 可能假通过。
 2. **每个待回答的问题吐一条 `input.requested`**，`id` 稳定、字段尽量填全——评估侧的检查和对位全靠它们。
 3. **下一次 `send` 先交裁决、再续跑**：从 `input.responses` 按 `requestId` 把裁决交回应用（不要按顺序猜），然后接着上一轮挂起的地方继续，而不是重发请求。
 
 "挂起的现场"（比如读了一半的 SSE 流）存在本会话线的 `ctx.session` 上。Adapter 用 `createSessionSlot<Pending>()` 声明私有 slot，停轮时 `ctx.session.set(slot, pending)`，回答轮 `ctx.session.take(slot)` 取回，取到即清除。怎么和流式驱动拼起来，见[写 send](/zh/tutorials/write-send#第五步：hitl) 第五步的完整骨架。
 
-和 [NiceEval](https://niceeval.com/) 的其它能力一样，HITL 没有布尔声明：**做到了就是有**。send 返回过 `"waiting"` 并吐了 `input.requested`，`t.respond` 就能工作。没做到，eval 会在第一个 `parked()` 或 `requireInputRequest()` 上明确失败，而不是静默假通过。能力如何从构造中来，见 [Adapter](/zh/explanation/adapter#能力从哪来：构造证明，不是问卷)。
+和 [NiceEval](https://niceeval.com/) 的其它能力一样，HITL 没有布尔声明：**做到了就是有**。send 返回过 `"waiting"` 并吐了 `input.requested`，`t.respond` 就能工作。没做到，eval 会在状态检查或 `requireInputRequest()` 上明确失败，而不是静默假通过。能力如何从构造中来，见 [Adapter](/zh/explanation/adapter#能力从哪来：构造证明，不是问卷)。
 
 ## 拒绝不是故障
 
@@ -81,7 +81,7 @@ HITL 对 Adapter 的全部要求就三件事——前两件发生在停下的那
 
 ## 相关阅读
 
-- [Drive](/zh/explanation/drive#人工介入-hitl) — 评估侧的完整用法：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`。
+- [Drive](/zh/explanation/drive#人工介入-hitl) — 评估侧的完整用法：状态检查、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`。
 - [Adapter](/zh/explanation/adapter#不同回答的入参) — 回答到 Adapter 的结构化入参，四种典型形态。
 - [写 send](/zh/tutorials/write-send) — Adapter 侧实操：typed session slot 与流式 + HITL 的完整骨架。
 - [接入你的 Agent](/zh/tutorials/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。

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

@@ -66,8 +66,8 @@ Reporter 只接入当前 Invocation。它可以把当前进程已知的结果交
 Runner 结束后，用明确 Run 选择查看结果：
 
 ```sh
-npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
-npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
+pnpm exec niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
+pnpm exec niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
 ```
 
 不带 locator 或 `--run` 的 `show` 和 `view` 读取身份仍匹配当前项目的全部结果；locator 与 `--run` 读取指定历史事实。NiceEval 形成 `Sample`，再按选中 Page 或完整站点所需的 Measure 与领域视图取得闭合值。

package/docs-site/zh/index.mdx

@@ -107,8 +107,8 @@ export default defineExperiment({
 
 ```sh
 npx niceeval exp local weather-tool
-npx niceeval show       # 终端读取结果，失败项可继续下钻
-npx niceeval view       # 网页交互浏览
+pnpm exec niceeval show       # 终端读取结果，失败项可继续下钻
+pnpm exec niceeval view       # 网页交互浏览
 ```
 
 如果被测对象是需要隔离工作区的 coding agent（Codex、Claude Code 插件/Skill），评估用例里改用 `t.sandbox.uploadDirectory()` 铺工作区。检查文件变化用 `t.sandbox.fileChanged()` 等归因断言。`t.sandbox.runCommand()` 跑测试。参考独立仓库 [coding-agent-skill](https://github.com/CorrectRoadH/coding-agent-skill)。

package/docs-site/zh/reference/builtin-agents.mdx

@@ -10,17 +10,17 @@ description: "NiceEval 内置的 claude-code、codex、bub 适配器分别做到
 
 | 能力 | 对应的断言 / API |
 |---|---|
-| 收发消息（基础契约） | `t.send()`（可多次调用）、`t.reply`、`turn.outputEquals` / `outputMatches`、按状态判断的 `t.succeeded()` |
-| 事件流完整性 | `calledTool` / `toolOrder` / `usedNoTools` / `maxToolCalls` / `messageIncludes` / `noFailedActions` / `event` / `eventOrder` 等整套作用域断言。**负断言（`notCalledTool` 等）有完整事件流才可信** |
+| 收发消息（基础契约） | `t.send()`（可多次调用）、`t.reply`、`t.check(turn.data, equals(...))` / `matches(...)`、按状态判断的 `t.succeeded()` |
+| 事件流完整性 | `calledTool` / `usedNoTools` / `maxToolCalls` / `noFailedActions` / `event` 等作用域断言；`toolOrder` / `eventOrder` 只在 Turn 或 Session 上接收 matcher。消息用 `t.check(turn.message, includes(...))` 或 `t.check(turn.message, pattern(...))`。**负断言（`notCalledTool` 等）有完整事件流才可信** |
 | 会话续接 | 跨轮记忆断言、`t.newSession()` 会话隔离 |
-| HITL（人工介入） | `t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()` |
+| HITL（人工介入） | `t.check(turn.status, equals("waiting"))`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()` |
 | `tracing` | trace decoding、`niceeval view` 的调用瀑布图 |
 
 ## 三个内置 agent 分别做到哪
 
 | Agent | 收发 | 事件流 | 会话续接 | HITL | tracing | 备注 |
 |---|---|---|---|---|---|---|
-| `claude-code` | ✅ | ✅ | ✅（`claude --resume <id>`） | ❌ | ✅（`http/protobuf` → OTLP，beta 开关） | 内置 parser 自动吐 `compaction` 事件，`t.event("compaction")` 可用 |
+| `claude-code` | ✅ | ✅ | ✅（`claude --resume <id>`） | ❌ | ✅（`http/protobuf` → OTLP，beta 开关） | 内置 parser 自动吐 `compaction` 原始事件，供报告和诊断读取；当前没有公开 `eventMatch` selector |
 | `codex` | ✅ | ✅ | ✅（`codex exec resume <id>`） | ❌ | ✅（`http/json` → OTLP） | 内置 parser 自动吐 `compaction` 事件 |
 | `bub` | ✅ | ✅ | ✅（`--session-id` + tape 续接） | ❌ | ✅（`http/protobuf` → OTLP） | 内置 parser 自动吐 `compaction` 事件 |
 

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

@@ -19,7 +19,7 @@ description: "Agent 的构造方式、运行时行为与必填的六通道 evide
 | `tracing`（OTLP 接收 → `niceeval view` 瀑布图） | CLI 型 Agent 配置 `tracing`。长驻应用在 config 配置固定的 `telemetry` 端口 | Span 只进时间瀑布图，不能填补行为证据缺口 |
 | 跨轮续接与 `t.newSession()` 隔离 | 用 `ctx.session.id` / `capture` 续接后端会话，或用 `ctx.session.get` / `set` 保存 Adapter 私有的强类型历史 | 会话接法决定实际行为，不从一个 evidence bit 推断 |
 | HITL（`t.respond()`） | `send` 返回 `status: "waiting"` 和 `input.requested` | 下一轮回答按结构化 request ID 对位 |
-| Compaction 可见 | 官方 parser 或完整的手写映射发出 `compaction` 事件 | `t.event("compaction")` 还要受下方 `events` 覆盖声明约束 |
+| Compaction 可见 | 官方 parser 或完整的手写映射发出 `compaction` 事件 | 原始事件进入报告与诊断；当前没有公开 `eventMatch` selector |
 
 ## 必填的六通道声明
 

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

@@ -24,10 +24,10 @@ description: "NiceEval CLI 参考：exp、debug、show、view、init、list 和
   <Card title="npx niceeval clean" icon="trash">
     删除明确 writer 留下的 Record 临时目录，不删除正式 Run 或 Attempt。
   </Card>
-  <Card title="npx niceeval show [--run]" icon="terminal">
+  <Card title="pnpm exec niceeval show [--run]" icon="terminal">
     在终端执行报告。不带 locator 或 `--run` 的命令读取当前项目结果；精确 Attempt 定位符或 Run ID 用于审计历史。
   </Card>
-  <Card title="npx niceeval view" icon="eye">
+  <Card title="pnpm exec niceeval view" icon="eye">
     构建完整报告站并在浏览器中托管。它与 `show` 共享选择规则，但会枚举全部页面。
   </Card>
 </CardGroup>
@@ -205,7 +205,7 @@ 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` 是顶层命令，应写成 `pnpm exec niceeval show`、`pnpm exec niceeval view`。误写成 `pnpm exec niceeval exp show` / `exp view` 且没有同名 experiment 时，CLI 会在“不存在的实验”错误后提示正确命令。仓库确实存在同名 experiment 时仍按合法 id 执行。
 
 ## 两种输出：人读文本与 `--json`
 
@@ -227,10 +227,10 @@ npx niceeval exp compare --junit ./artifacts/niceeval-junit.xml
 ## `view`
 
 ```bash
-npx niceeval view
-npx niceeval view --run 01H...
-npx niceeval view @01H...
-npx niceeval view --host 192.168.0.199
+pnpm exec niceeval view
+pnpm exec niceeval view --run 01H...
+pnpm exec niceeval view @01H...
+pnpm exec niceeval view --host 192.168.0.199
 ```
 
 打开本地结果查看器。它和 `show` 共用默认 Report 与选择规则。不带 locator 或 `--run` 的命令读取所有身份仍匹配当前项目的结果；精确 `@<AttemptLocator>` 显示该 Attempt 的默认概览；`--run` 读取指定历史 Run。NiceEval 随后形成固定 Sample、枚举全部 Page 与参数实例，并构建完整站点。
@@ -246,13 +246,13 @@ npx niceeval view --host 192.168.0.199
 ## `show`
 
 ```bash
-npx niceeval show
-npx niceeval show --run 01H...
-npx niceeval show --run 01H... --run 01J...
-npx niceeval show @01H...
-npx niceeval show --run 01H... --page /
-npx niceeval show --run 01H... --report ./reports/summary.tsx --page /overview
-npx niceeval show --run 01H... --report ./reports/summary.tsx --json
+pnpm exec niceeval show
+pnpm exec niceeval show --run 01H...
+pnpm exec niceeval show --run 01H... --run 01J...
+pnpm exec niceeval show @01H...
+pnpm exec niceeval show --run 01H... --page /
+pnpm exec niceeval show --run 01H... --report ./reports/summary.tsx --page /overview
+pnpm exec niceeval show --run 01H... --report ./reports/summary.tsx --json
 ```
 
 `show` 是终端报告入口，适合人直接阅读，也适合 coding agent 在上下文窗口里逐级下钻。它不接受模糊的位置选择。省略 `--page` 时选择默认 Page；提供 `--page <route>` 时只执行这个精确 route。

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

@@ -200,14 +200,14 @@ token 用量或 OTel span 反推得到)。与顶层 `estimatedCostUSD`(价目表
 | `message` | agent（或用户）说了一段话 | `turn.message`、`turn.event(eventMatch("message", ...))`、Judge 的材料 |
 | `operation.started`（`kind: "tool"`） | 发起一次工具调用 | `turn.calledTool(...)`、`turn.toolOrder(...)`、`turn.event(...)` |
 | `operation.finished`（`kind: "tool"`） | 该次工具调用的结果 | 带状态条件的 `ToolMatch` |
-| `operation.started`（`kind: "subagent"`） | 委派一个子 agent | `turn.event(eventMatch("operation.started", ...))` |
-| `operation.finished`（`kind: "subagent"`） | 子 agent 返回 | `turn.event(eventMatch("operation.finished", ...))` |
-| `input.requested` | 停下来等人输入（HITL） | `t.requireInputRequest()`、`turn.event(...)` |
-| `thinking` | 思考文本 | `turn.event(eventMatch("thinking", ...))`、view 展示 |
-| `compaction` | 上下文被压缩 | `turn.event(eventMatch("compaction"))` |
-| `error` | 本轮出错 | `turn.event(eventMatch("error", ...))`、view 展示 |
+| `operation.started`（`kind: "subagent"`） | 委派一个子 agent | 原始事件与报告；当前没有子 agent 专用断言 |
+| `operation.finished`（`kind: "subagent"`） | 子 agent 返回 | 原始事件与报告；失败会进入 `noFailedActions()` 的汇总事实 |
+| `input.requested` | 停下来等人输入（HITL） | `t.check(turn.status, equals("waiting"))`、`t.requireInputRequest()` |
+| `thinking` | 思考文本 | view 展示；当前没有 `eventMatch` selector |
+| `compaction` | 上下文被压缩 | view 展示；当前没有 `eventMatch` selector |
+| `error` | 本轮出错 | view 展示；当前没有 `eventMatch` selector |
 
-事件断言共用三个入口：`event(match)`、`notEvent(match)` 与 `eventOrder(matches)`；它们都接收 `eventMatch(...)`，不另造 selector object 或匿名事件 predicate。
+事件断言共用三个入口：`event(match)`、`notEvent(match)` 与 `eventOrder(matches)`；它们都接收 `eventMatch(...)`，不另造 selector object 或匿名事件 predicate。当前 `eventMatch` 只有 `message`、工具 `operation.started` 与工具 `operation.finished` 三种形状，不能把全部原始 `StreamEvent` 当成可断言 selector。
 
 ## 逐事件说明
 
@@ -267,7 +267,7 @@ events.push({
 });
 ```
 
-`commandProjection()` 保留 Adapter 已确认的 original tokens，并调用同一份 `normalizeLogicalCommand()` 生成 `logical-command/v1` 投影。`pnpm exec niceeval show` 和 `npx niceeval show` 因此都能由 `commandMatch("niceeval", { argsStart: ["show"] })` 精确匹配。
+`commandProjection()` 保留 Adapter 已确认的 original tokens，并调用同一份 `normalizeLogicalCommand()` 生成 `logical-command/v1` 投影。`pnpm exec niceeval show` 能由 `commandMatch("niceeval", { argsStart: ["show"] })` 精确匹配。
 
 只有原生协议已经给出 argv，或协议 grammar 能无歧义地产生单一 invocation，才能把 original 标为 available。协议只给 shell source、内容已截断或脱敏时使用 `opaqueCommandProjection(reason)`；能确认不是 command 时使用 `notCommandProjection()`。无法确认 command / not-command 时降低 actions coverage，不能从 tool name、input 或 shell 文本猜测。
 
@@ -280,7 +280,7 @@ events.push({
   output?: JsonValue, status: "completed" | "failed" }
 ```
 
-被测系统把任务委派给子 agent（等它返回）时吐这一对，`operationId` 配对规则同上。评估作者用 `eventMatch("operation.started", ...)` / `eventMatch("operation.finished", ...)` 比较对应事件。
+被测系统把任务委派给子 agent（等它返回）时吐这一对，`operationId` 配对规则同上。它们会保留在原始事件流与报告中，但当前公开 Assert-first API 没有 `calledSubagent`，`eventMatch(...)` 也不能选择子 agent operation；不要凭空换成另一个 selector。
 
 ### `input.requested` —— 停下等人（HITL）
 
@@ -304,11 +304,11 @@ agent 停轮等人时，每个待回答的问题吐一条，同时该 Turn 的 `
 { type: "error", message: string }
 ```
 
-有就吐，没有不硬造。`compaction` 主要来自 coding agent CLI（上下文满了自动压缩）。
+有就吐，没有不硬造。`compaction` 主要来自 coding agent CLI（上下文满了自动压缩）。这几种原始事件保留给报告与诊断；当前公开 `eventMatch` 不能选择它们。
 
 ## 映射的三条纪律
 
-1. **时序即事实**：事件按真实发生顺序排。`toolOrder` / `eventOrder` 用单调 cursor 匹配不同 occurrence 的子序列，顺序错了断言就失真。
+1. **时序即事实**：事件按真实发生顺序排。`toolOrder` / `eventOrder` 用单调 cursor 匹配不同 occurrence 的子序列，顺序错了断言就失真。`eventOrder` 只排公开 `eventMatch` 支持的事件。
 2. **`operationId` 配对**：每个 started operation 都要有同 `kind`、同 id 的 finished operation。只有配对完成，框架才能把状态与 input 归到同一个逻辑工具 occurrence。
 3. **完整性必须显式**：官方转换器按实际 adapter 能力声明 evidence coverage。负向断言在相关输入或 action coverage 不完整时是 `unavailable`，不会把“没观察到”冒充“没有发生”。手工映射同样要如实声明覆盖范围，见[能力位参考](/zh/reference/capabilities)。
 

package/docs-site/zh/reference/official-adapters.mdx

@@ -16,7 +16,7 @@ description: "NiceEval 内置的 Sandbox 和非 Sandbox 适配器分别是什么
 
 - **鉴权**：`ANTHROPIC_API_KEY`（工厂参数 `apiKey` 可覆盖），可选 `ANTHROPIC_BASE_URL`（工厂参数 `baseUrl`）。
 - **装 MCP server**：`mcpServers` 配置项，`setup` 阶段写进 Sandbox 里用户级的 `~/.claude.json`（顶层 `mcpServers` 字段）。两种形态按字段区分：本地 stdio 进程写 `command`（可带 `args` / `env`）。远程 Streamable HTTP 端点写 `url`（可带 `headers`，逐字进请求头，常用于 `Authorization`），写成 `{ "type": "http", "url": …, "headers": … }` 条目。`url` 要 Sandbox 内可达：服务跑在你自己机器上时，先用 cloudflared / tailscale 这类隧道暴露成公网地址。
-- **装 Skill**：`skills: SkillSpec[]`。本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进 Sandbox 的 project 级 `.claude/skills/<name>/`，claude CLI 原生发现（原生 `Skill` 工具调用被 adapter 归一为 `skill.loaded` 事件，不重复记成工具调用。用 `t.loadedSkill()` 断言，不是 `t.calledTool("Skill", ...)`）。
+- **装 Skill**：`skills: SkillSpec[]`。本地 Skill（`{ kind: "local", path }`，从项目根读文件或目录）或 Repo Skill（`{ kind: "repo", source, ref, skills }`，可钉 commit/tag、可只启用多 Skill 仓库里的一部分）。装进 Sandbox 的 project 级 `.claude/skills/<name>/`，claude CLI 原生发现。adapter 会把原生 `Skill` 调用归一为 `skill.loaded` 原始事件，不重复记成工具调用；当前公开 Assert-first API 没有专用 Skill 断言，也不能把它伪装成 `calledTool("Skill", ...)`。
 - **装原生 Plugin**：`plugins: ClaudeCodePluginSpec[]`，每一项声明 Marketplace 连接（`name` / `source` / 可选 `ref`）和其中的 Plugin 名。这个类型只属于 claude-code，传不进 codex。复用 Sandbox 的 Experiment 不用额外处理残留：每条 Attempt 开始前，同名 marketplace 注册与已装 Plugin 都会按声明的 `source` / `ref` 重新安装。
 - **官方配置文件**：`settingsFile` 是运行 NiceEval 的机器上的本地项目路径，不是 Sandbox 内路径。它指向一份完整的 Claude Code `settings.json`。路径相对项目根，只允许普通相对路径或 `./` 前缀。`..`、绝对路径、`~` 和解析后逃出项目根的符号链接都会报错。
 

package/docs-site/zh/reference/results-data.mdx

@@ -12,6 +12,8 @@ Sample 固定本次选择的 Run、logical Slot 与分母。每个位置保留 `
 
 `--run` 保留指定 Run 的完整计划范围。`project-current` 只保留仍与当前项目身份匹配的范围。两种选择都不会因为某个度量缺少输入而缩小分母。
 
+`project-current` 的成员单位是匹配的 Run slot occurrence，不是去重后的 `(experiment, eval, ordinal)`。同一位置出现在多个匹配 Run 中时，每个 occurrence 都进入 `MetricValue.total`。重复运行或逐条 `accept` 因此可能增加分母。
+
 Sample 只能在 `load()`、Page 或组合组件执行期间传给 Report facade。回调结束后，页面只保留已经关闭的值，不能再次读取结果。
 
 ## 用 `aggregate()` 取得 rows
@@ -58,6 +60,10 @@ Attempt Evidence、Observability、File Changes、Sources 和 Sandbox history
 
 `available`、`partial`、`empty`、`unsupported` 和 `failed` 都是不同状态。不要把 `null` 当成零，也不要用只剩下的可见行数替换总分母。
 
+例如 `formatMetricValue()` 输出的 `2 / 4 slot · partial` 表示四个已选 occurrence 中只有两个提供该 Measure 的输入。这组计数只描述覆盖率；它不是 earned score、通过率或工作完成比例。Measure 自己的 `value` 才是读数。
+
+默认 Overview 不把这组计数重复追加到每个指标单元格。它按题型显示通过率或 earned score，并在结果不完整时用独立的 `Result coverage` 区域显示可用结果数。终端把这个区域渲染成有标题的边框；底层 `MetricValue` 的字段保持不变。
+
 ## 相关页面
 
 - [报告 API](/zh/reference/report-components)：Page、组件、JSON 和全站构建边界。

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

@@ -7,8 +7,8 @@ description: "根据可见错误、Sample 状态和 rebuild 反馈，定位查
 先用明确 Run 读取问题，不要从目录名或时间猜测目标。
 
 ```sh
-npx niceeval show --run <run-id>
-npx niceeval view --run <run-id> --no-open
+pnpm exec niceeval show --run <run-id>
+pnpm exec niceeval view --run <run-id> --no-open
 ```
 
 这两条命令从同一范围形成 Sample，并执行同一份 Report。先确定选择是否正确，再检查页面中的度量和问题。

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

@@ -49,8 +49,8 @@ Agent 应把最后一条 receipt 当作本次调用的交接信息。它不是
 运行结束后，先读取 Run 的 Report：
 
 ```sh
-npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
-npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
+pnpm exec niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
+pnpm exec niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
 ```
 
 `show` 与 `view` 选择 Sample，再取得当前目标需要的闭合分析值。`show` 只执行一个 Page；`view` 构建完整站点。Agent 应区分以下状态：

package/docs-site/zh/tutorials/ci-integration.mdx

@@ -50,7 +50,7 @@ with:
 成功建立 Invocation 后，NDJSON 的最后一行包含 receipt。后续脚本可以读取它的 `runIds`，用明确 Run 选择查看或导出报告：
 
 ```sh
-npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY \
+pnpm exec niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY \
   --out ./report-site \
   --no-open
 ```

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

@@ -101,10 +101,10 @@ export default defineEval({
 ```bash
 npx niceeval exp my-agent        # 跑这个 experiment 下的全部 eval
 npx niceeval exp my-agent refund # 只跑 ID 以 refund 开头的
-npx niceeval view --experiment my-agent  # 本地查看器里看结果
+pnpm exec niceeval view --experiment my-agent  # 本地查看器里看结果
 ```
 
-**验证运行结果**：终端会显示动态 dashboard，完成和排队数量在原位更新。失败、错误和 warning 会保留在输出中。运行结束后会打印摘要和 receipt；用其中的 Run ID 也可以执行 `npx niceeval view --run <runId>`，查看每条评估用例逐轮的输入、事件和评分明细。
+**验证运行结果**：终端会显示动态 dashboard，完成和排队数量在原位更新。失败、错误和 warning 会保留在输出中。运行结束后会打印摘要和 receipt；用其中的 Run ID 也可以执行 `pnpm exec niceeval view --run <runId>`，查看每条评估用例逐轮的输入、事件和评分明细。
 
 没跑通时，按报错的位置分三类排查：
 

package/docs-site/zh/tutorials/custom-reports.mdx

@@ -173,10 +173,10 @@ export default defineConfig({
 ## 运行、读取和发布
 
 ```sh
-npx niceeval show --run <run-id> --report ./reports/quality.tsx
-npx niceeval show --run <run-id> --report ./reports/quality.tsx --json
-npx niceeval view --run <run-id> --report ./reports/quality.tsx --no-open
-npx niceeval view --run <run-id> --report ./reports/quality.tsx --out ./quality-site
+pnpm exec niceeval show --run <run-id> --report ./reports/quality.tsx
+pnpm exec niceeval show --run <run-id> --report ./reports/quality.tsx --json
+pnpm exec niceeval view --run <run-id> --report ./reports/quality.tsx --no-open
+pnpm exec niceeval view --run <run-id> --report ./reports/quality.tsx --out ./quality-site
 ```
 
 前三条命令从相同选择形成 Sample，但范围不同：`show` 和 `show --json` 只执行一个 Page，并只捕获该页的 projection closure；`view` 与 `view --out` 枚举全部 Page 后形成完整站点及 `_niceeval/data/projections.json`。该文件的 bytes 进入 revision identity。view 的成功 rebuild 原子替换当前站点；失败时保留上一份可用站点。`--out` 必须指向不存在的目录。

package/docs-site/zh/tutorials/deploy-report-site.mdx

@@ -7,7 +7,7 @@ description: "将 view --out 生成的完整自包含报告目录部署到任意
 先生成完整报告站，再部署输出目录。托管平台不读取源 Record，也不需要安装或运行 NiceEval。
 
 ```sh
-npx niceeval view --experiment checkout \
+pnpm exec niceeval view --experiment checkout \
   --out ./report-site \
   --no-open
 ```
@@ -15,7 +15,7 @@ npx niceeval view --experiment checkout \
 要部署一次明确运行，请从 receipt 读取 Run ID：
 
 ```sh
-npx niceeval view --run <run-id> --out ./report-site --no-open
+pnpm exec niceeval view --run <run-id> --out ./report-site --no-open
 ```
 
 ## CI 流程
@@ -30,7 +30,7 @@ GitHub Actions 的构建任务示例：
 
 ```yaml
 - name: 生成报告站
-  run: npx niceeval view --experiment checkout --out ./report-site --no-open
+  run: pnpm exec niceeval view --experiment checkout --out ./report-site --no-open
 
 - name: 上传静态站点目录
   uses: actions/upload-pages-artifact@v3

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

@@ -180,6 +180,9 @@ export default defineExperiment({
 共享宿主或不可信 Agent使用 managed模式。它在 inner daemon之外增加 profile attestation、单容器
 资源限制、跨进程容量准入、独占外层网络和 watchdog恢复：
 
+NixOS宿主先按照[在 NixOS上配置 Managed DinD](/zh/tutorials/nixos-managed-dind)部署并验证 profile，
+再配置下面的 Experiment。
+
 ```ts title="experiments/dind-managed.ts"
 import { defineExperiment } from "niceeval";
 import { codexAgent } from "niceeval/adapter";

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

@@ -75,8 +75,8 @@ api-validation   claude-code             pass@3 = 1/3 (33%)    mean 41s
 除了 pass rate，还应该看平均耗时、token、成本和失败类型。
 
 ```bash
-npx niceeval show --experiment models
-npx niceeval view --experiment models
+pnpm exec niceeval show --experiment models
+pnpm exec niceeval view --experiment models
 ```
 
 每个 experiment 用自己的 `evals` 选择评估用例。函数形式会遍历所有已发现的评估用例：

package/docs-site/zh/tutorials/handle-execution-failures.mdx

@@ -108,7 +108,7 @@ npx niceeval exp compare evals/coding
 需要查看某个 Attempt 的原始错误和重试摘要时，使用终端给出的定位符：
 
 ```shell
-npx niceeval show @<attempt-locator>
+pnpm exec niceeval show @<attempt-locator>
 ```
 
 自定义 Adapter 如果有专用的受理前拒绝信号，可以提供 `classifySendFailure`。该字段的类型和边界见 [`defineSandboxAgent` 参考](/zh/reference/define-agent#definesandboxagent)。

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

@@ -87,7 +87,7 @@ Sandbox 不需要 Node.js 或 npm。`createNpmCliInstaller` 在宿主机上下
 安装或复检失败时，Attempt 会在 `agent.ensure` 阶段变成 `errored`。终端会给出 Attempt 定位符。
 
 ```shell
-npx niceeval show @<attempt-locator>
+pnpm exec niceeval show @<attempt-locator>
 ```
 
 先检查错误里的包名、版本和目标平台。修正 `identity`、npm 包或安装步骤后，重新运行原命令。

package/docs-site/zh/tutorials/nixos-managed-dind.mdx

@@ -0,0 +1,160 @@
+---
+title: "在 NixOS 上配置 Managed DinD"
+sidebarTitle: "NixOS Managed DinD"
+description: "使用 NiceEval 的 NixOS module 部署 managed rootless Docker profile，并通过 doctor 验证宿主环境。"
+---
+
+Managed rootless DinD 适合在共享 NixOS 宿主上运行不可信 Agent。NiceEval 的 NixOS module 会创建专用
+系统用户、rootless Docker daemon、容量受限的数据盘、资源 slice 和 watchdog。日常运行 NiceEval
+不需要 `sudo`，但首次部署和更新系统配置需要管理员权限。
+
+如果任务可以信任 Agent，或者只在一次性 VM 中运行，先阅读[让 Sandbox 使用 Docker](/zh/tutorials/docker-in-docker)
+选择 Docker socket 或 raw privileged DinD。它们不需要本页的宿主 profile。
+
+## 前置条件
+
+开始前确认：
+
+- NixOS 使用 flake 管理系统配置；
+- 宿主使用 systemd 和 cgroup v2；
+- 你知道日常运行 NiceEval 的 NixOS 用户名；
+- 宿主有足够的 CPU、内存和磁盘留给评估容器。
+
+下面假设系统配置仓库已经有 `flake.nix`，配置名是 `my-host`，日常用户名是 `alice`。请把它们替换成
+自己的值。
+
+## 引入 NiceEval module
+
+在系统配置的 `flake.nix` 中加入 NiceEval input，并把 module 放进主机的 `modules`：
+
+```nix title="flake.nix"
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    niceeval.url = "github:NiceEval/NiceEval";
+  };
+
+  outputs = { self, nixpkgs, niceeval, ... }: {
+    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        niceeval.nixosModules.default
+        ./configuration.nix
+      ];
+    };
+  };
+}
+```
+
+第一次运行 Nix 命令后，Nix 会把 NiceEval 的具体 commit 写进你的 `flake.lock`。提交这份锁文件，避免
+不同机器在未确认的时间使用不同 module 版本。
+
+## 声明 profile
+
+在 NixOS 配置中声明一个名为 `default` 的 profile：
+
+```nix title="configuration.nix"
+{ ... }:
+{
+  services.niceeval.dockerProfiles.default = {
+    enable = true;
+    accessUsers = [ "alice" ];
+
+    capacity = {
+      cpus = 4;
+      memory = "8G";
+      pids = 4096;
+      maxContainers = 2;
+      maxBuilds = 1;
+    };
+
+    aggregate = {
+      cpus = 6;
+      memory = "12G";
+      pids = 6144;
+    };
+
+    storage = {
+      size = "30G";
+      backing = "loop-ext4";
+    };
+  };
+}
+```
+
+`capacity` 是 NiceEval 可以分配给评估任务的预算。`aggregate` 是 daemon、构建进程、watchdog 和评估
+容器共同受到的硬限制，因此每一项都不能小于 `capacity`。两者之间的余量留给宿主侧开销。
+
+`loop-ext4` 会在 `/var/lib/niceeval/docker-profiles/default.img` 创建稀疏镜像，并挂载为 Docker
+data root。`size` 是这个 profile 的磁盘上限，不代表 rebuild 时立即占用同等物理空间。
+
+## 应用系统配置
+
+先检查配置能够求值，再切换系统：
+
+```bash
+nix flake check
+sudo nixos-rebuild switch --flake .#my-host
+```
+
+module 会把 `alice` 加入 profile 的 access group。rebuild 完成后退出当前登录会话并重新登录，让新组
+成员身份生效。只在旧 shell 中重新运行命令不会刷新 supplementary groups。
+
+重新登录后检查服务：
+
+```bash
+systemctl status niceeval-docker-profile-default.service
+systemctl status niceeval-docker-profile-watchdog-default.service
+```
+
+两个服务都应显示 `active (running)`。失败时读取对应 unit 的日志：
+
+```bash
+journalctl -u niceeval-docker-profile-default.service -b
+journalctl -u niceeval-docker-profile-watchdog-default.service -b
+```
+
+## 验证 profile
+
+进入已经安装 NiceEval 的评估项目，以日常用户运行：
+
+```bash
+pnpm exec niceeval docker profile list
+pnpm exec niceeval docker profile doctor default --smoke
+```
+
+`list` 应显示 `default`。`doctor --smoke` 会检查 descriptor、Unix socket、cgroup、容量和 watchdog，
+然后启动一个受限的外层容器及一个内层 Alpine 容器。所有项目都通过后，宿主 profile 才可以用于正式
+评估。
+
+不要用 `sudo pnpm exec niceeval ...` 绕过权限错误。日常用户无法访问 profile 时，先确认用户名已经写入
+`accessUsers`，再重新登录并重跑 doctor。
+
+## 在 Experiment 中使用
+
+宿主通过验收后，在 Experiment 的 Docker Sandbox 中引用同一个别名：
+
+```ts
+dockerAccess: {
+  mode: "dind",
+  isolation: "managed-rootless",
+  profile: "default",
+},
+```
+
+Experiment 还必须声明单容器 CPU、内存、PID、只读 rootfs 和 tmpfs。完整配置见
+[让 Sandbox 使用 Docker](/zh/tutorials/docker-in-docker#managed-rootless-dind)。先用较小的
+`maxConcurrency` 运行一次，再根据 profile 的 `capacity` 增加并发。
+
+## 更新 module
+
+需要更新 NiceEval module 时，在系统配置仓库更新对应 input，检查 diff 后重新构建：
+
+```bash
+nix flake update niceeval
+nix flake check
+sudo nixos-rebuild switch --flake .#my-host
+```
+
+更新会改变宿主服务，不能只更新评估项目里的 npm 依赖。保留旧 generation，确认 doctor 和实际评估都
+通过后再清理 NixOS generation。

package/docs-site/zh/tutorials/publish-report.mdx

@@ -7,7 +7,7 @@ description: "用 view --out 导出可离线打开、与源 Record 脱离且包
 `niceeval view --out <目录>` 从已发布结果形成固定 Sample，再构建完整报告站。它不是把当前浏览器页面保存为文件：`pages` 中显式声明的所有普通 Page、参数 Page 实例、资源和下载都必须先关闭并通过校验；Host 不补建详情页。
 
 ```sh
-npx niceeval view --experiment checkout \
+pnpm exec niceeval view --experiment checkout \
   --out ./report-site \
   --no-open
 ```
@@ -15,7 +15,7 @@ npx niceeval view --experiment checkout \
 需要固定到本次运行时，从 receipt 的 `runIds` 取得 Run ID：
 
 ```sh
-npx niceeval view --run <run-id> \
+pnpm exec niceeval view --run <run-id> \
   --out ./report-site \
   --no-open
 ```
@@ -47,14 +47,14 @@ Analysis 的 `partial`、`empty`、`unsupported` 与 `failed` 是可显示的数
 
 ```sh
 # 成功时写入全新目录
-npx niceeval view --run <run-id> --out ./report-site-2026-08-15
+pnpm exec niceeval view --run <run-id> --out ./report-site-2026-08-15
 ```
 
 ## 在 CI 中生成
 
 ```sh
 npx niceeval exp ci --json
-npx niceeval view --experiment ci --out ./report-site --no-open
+pnpm exec niceeval view --experiment ci --out ./report-site --no-open
 ```
 
 若 CI 必须发布刚完成的那次运行，读取第一条命令最后一行 receipt 的 `runIds`，并使用 `view --run <run-id>`。不要让托管平台读取源 Record；它只应部署生成目录。

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

@@ -47,7 +47,7 @@ npx niceeval exp checkout --json
 `--json` 输出当前进程的 NDJSON。最后一条 receipt 包含 `invocationId`、`runIds`、开始时间、结束时间和 completion。外部自动化可以保留 receipt，再根据 `runIds` 选择要查看的 Report。
 
 ```sh
-npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
+pnpm exec niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
 ```
 
 不要把 progress 或 diagnostic 行当作长期结果格式。它们服务当前 Invocation，完整业务事实属于停稳 Record。