niceeval 0.13.0 → 0.13.2-canary.35

package/docs-site/zh/tutorials/rerun-and-cache.mdx

@@ -70,6 +70,22 @@ npx niceeval accept @1K1P0VJAPVJ12
 
 `accept` 先检查所有输入，再发布一个以 `reference` 采用该 Attempt 的新 Run。操作者理由、差异和资格会随该 Run 保存。它不会修改源 Attempt，也不会复制源 Attempt 的业务值。
 
+新 Run 保留该 Experiment 当前完整的 expected-slot 分母。命令中选中的 slot 写作 `accepted`，同 Run 中没有被选中的 sibling slot 写作 `not-dispatched`。因此一次只接受一个 locator 时，这个 Run 的其它位置可能没有指标输入。
+
+每次 `accept` 调用都会发布新 Run，不会修改或合并上一次调用。连续接受同一 Experiment 的多个 locator 后，`project-current` 会保留这些仍匹配的 Run occurrence。默认 Overview 会在有边框的 `Result coverage` 区域提示只有部分预期结果可用；这里的可用数是结果覆盖率，不是通过率或 score。
+
+需要接受同一 Experiment 的多个结果时，把 locator 放进同一条命令：
+
+```sh
+npx niceeval accept @1K1P0VJAPVJ12 @1K1P0VJAPVJ13
+```
+
+同一次调用会为该 Experiment 发布一个 Run，并让两个目标 slot 都成为 `accepted`。需要核对某次接受的精确分母时，复制成功反馈中的 Run ID：
+
+```sh
+npx niceeval show --run <accepted-run-id>
+```
+
 ## 发布后不可修改
 
 Attempt 发布后不可修改。每一次查看都读取当时 Record 中已发布的值；新 Run 或新事实只会以新的发布出现。若 Attempt 或引用无效，Sample 将该 slot 标为 `core-invalid`，而不是 `not-recorded`。

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

@@ -7,8 +7,8 @@ description: "用 show 或 view 从已发布的 Record 选择固定 Sample，并
 运行结束后，从下面两条命令开始：
 
 ```sh
-npx niceeval show
-npx niceeval view
+pnpm exec niceeval show
+pnpm exec niceeval view
 ```
 
 两条命令用相同选择规则形成固定 `Sample`，但执行范围不同。`show` 只读取一个目标 Page；`view` 会先构建完整站点，再把它托管在浏览器中。
@@ -18,7 +18,7 @@ npx niceeval view
 选择一个明确 Run：
 
 ```sh
-npx niceeval show --run 7b8d2ea4-b840-4870-9840-f85a436a5527
+pnpm exec niceeval show --run 7b8d2ea4-b840-4870-9840-f85a436a5527
 ```
 
 普通运行可从 `exp --json` 最后一条 receipt 的 `runIds` 读取 Run ID：
@@ -29,6 +29,8 @@ npx niceeval show --run 7b8d2ea4-b840-4870-9840-f85a436a5527
 
 不带 locator、`--run` 或 `--experiment` 时，命令使用 `project-current`：它保留全部仍与当前项目身份匹配的已发布结果，而不是只选最新一条。需要阅读历史结果时，传入完整 `--run`；要限制当前项目结果时，重复传入完整的 `--experiment <id>`。
 
+`project-current` 按 Run 中的 slot occurrence 保留结果。它不会把多个 Run 里同名的 Experiment、评估用例和 Attempt 序号合并成一个位置。重复运行或分多次执行 `accept` 都可能增加当前 `Sample` 的分母。
+
 Sample 记录每个位置的状态：
 
 | 状态 | 含义 |
@@ -43,10 +45,10 @@ Sample 记录每个位置的状态：
 ## 在终端读取一个 Page
 
 ```sh
-npx niceeval show --run <run-id>
-npx niceeval show --run <run-id> --page /
-npx niceeval show @<attempt-locator>
-npx niceeval show --run <run-id> --report ./reports/quality.tsx --json
+pnpm exec niceeval show --run <run-id>
+pnpm exec niceeval show --run <run-id> --page /
+pnpm exec niceeval show @<attempt-locator>
+pnpm exec niceeval show --run <run-id> --report ./reports/quality.tsx --json
 ```
 
 省略 `--page` 时，`show` 使用 Report 的默认可导航页面。提供 `--page` 时，它只 decode、load、render 和关闭这一个精确 route。参数 Page 不会因此调用 `enumerate()`；其它 Page、Analysis 查询和作者 callback 也不会执行。
@@ -66,11 +68,27 @@ npx niceeval show --run <run-id> --report ./reports/quality.tsx --json
 
 JSON 不包含其它 Page、HTML、React tree、站点 identity 或 Record 读取能力。
 
+## 按题型读取主读数
+
+默认报告按评估类型选择主读数：
+
+- Pass Eval 显示通过率。
+- Score Eval 显示 earned score。
+- mixed Experiment 显示 Score，并在 Pass Eval 子行显示通过率，不把两者合成百分比。
+
+Score Eval 上声明的 `points` 是评分项的贡献权重，不是 Experiment 的固定满分。动态执行、条件分支或不可用材料可能让评分项集合不同，因此默认报告不会自动把 earned score 除以所有源码里声明的 `points`。
+
+项目没有配置 Report 时，`project-current` 使用单页 `default-overview`。显式传入 `--report standard` 会使用相同的题型主读数，并额外提供 Attempts、Traces、Experiment 和 Attempt 详情页。增加详情页不会改变 Score 或通过率的计算口径。
+
+默认 Overview 让主读数保持独立：Score 只显示 earned score，耗时和 token 也只显示各自的值。它不会在这些单元格后面追加容易与分数混淆的 `2 / 4 slot · partial`。
+
+如果部分预期结果不可用，Overview 会在 KPI 和实验表之外显示独立的 `Result coverage` 区域。终端中的这个区域有边框，标题行直接写出“多少个结果可用”；它说明结果完整度，不表示分数、通过率或工作完成比例。结果完整时不显示这个区域。
+
 ## 在浏览器读取完整站点
 
 ```sh
-npx niceeval view --experiment checkout --no-open
-npx niceeval view --run <run-id> --page / --no-open
+pnpm exec niceeval view --experiment checkout --no-open
+pnpm exec niceeval view --run <run-id> --page / --no-open
 ```
 
 view 在启动 server 前枚举所有显式声明的普通 Page 与参数 Page 的全部实例，并验证路径、链接、资源、下载、`_niceeval/data/projections.json` 和预算。`pages` 是唯一页面集合，Host 不会补建详情 route。`--page` 只决定初始打开的已存在 route，不能缩小构建范围。全站 projections 文件的 bytes 属于 revision identity。
@@ -81,7 +99,7 @@ view 在启动 server 前枚举所有显式声明的普通 Page 与参数 Page
 
 ## 读懂不完整数据
 
-`MetricValue` 的 `samples` 是实际贡献数，`total` 是既定分母，`state` 和 `issues` 说明为什么数据不完整。`partial` 可以有数值；`empty`、`unsupported` 与 `failed` 不是零。Evidence refs 保留可复核的定位信息。
+`MetricValue` 的 `samples` 是实际贡献数，`total` 是既定分母，`state` 和 `issues` 说明为什么数据不完整。自定义 Report 使用 `formatMetricValue()` 时仍可得到 `2 / 4 slot · partial` 这类紧凑格式；它表示四个已选位置中有两个提供该指标，不是 score，也不是“完成了一半”。默认 Overview 改用上面的独立覆盖区域。`partial` 可以有数值；`empty`、`unsupported` 与 `failed` 不是零。Evidence refs 保留可复核的定位信息。
 
 Analysis 数据问题继续作为页面内容显示。相反，选中 Page 的 callback、参数 key 或成员资格失败会让 `show` 返回单目标错误；任何全站 Page、路径、资源或预算失败都会阻止新的站点发布。
 

package/docs-site/zh/tutorials/write-send.mdx

@@ -75,7 +75,7 @@ if (!res.requestId) {
 
 `progress` 不落盘。diagnostic 会写入 Attempt-owned 通道，并从已选 Run 的详情页面回顾。HTTP 连接失败或响应无法解析时直接抛错；runner 会记录错误发生在 `agent.run`，并在 `niceeval.verdict` 通道形成 `errored` Verdict。
 
-**这一步支持**：`t.reply`、`t.messageIncludes()`、Judge 的全部对话材料，以及 Experiment 侧的**模型对比**。`ctx.model` 来自 Experiment 的 `model`。运行器原样传递，Adapter 只负责转发。接入等级见 [Tier](/zh/explanation/tier)。
+**这一步支持**：`t.reply` 的直接值检查（`t.check(t.reply, includes(...))` 或 `pattern(...)`）、Judge 的全部对话材料，以及 Experiment 侧的**模型对比**。`ctx.model` 来自 Experiment 的 `model`。运行器原样传递，Adapter 只负责转发。接入等级见 [Tier](/zh/explanation/tier)。
 
 它有两个明显的局限：每轮都是一场全新对话（第二次 `t.send` 接不上第一次），工具调用完全看不见。后面两步各解决一个。
 
@@ -236,10 +236,10 @@ type StreamEvent =
 
 | 你吐的事件 | 解锁的断言 |
 |---|---|
-| `message` | `t.reply`、`t.messageIncludes()`、judge 的对话材料 |
+| `message` | `t.reply`、`t.check(turn.message, includes(...))` / `pattern(...)`、Judge 的对话材料 |
 | tool `operation.started` / `operation.finished`（靠 `operationId` 配对） | `turn.calledTool()` / `turn.toolOrder()` / `turn.maxToolCalls()` / `turn.noFailedActions()`… |
-| `input.requested`（配合 status `"waiting"`） | `t.parked()`、`t.requireInputRequest()`、`t.respond()`（第五步） |
-| `thinking` / `compaction` / `error` | 对应断言与 o11y 计数 |
+| `input.requested`（配合 status `"waiting"`） | `t.check(turn.status, equals("waiting"))`、`t.requireInputRequest()`、`t.respond()`（第五步） |
+| `thinking` / `compaction` / `error` | 报告与诊断；当前没有对应的公开 `eventMatch` selector |
 
 Chat Completions 响应**不保证包含完整过程记录**。应用可能在服务端完成工具循环，只返回最终答案。因此，`turnFromChatCompletion` 的返回不带完整性证明：`calledTool` 等正断言可用，`notCalledTool` 等负断言会提示证据不完整。Responses 协议要求 `output` 数组记录完整过程，`turnFromResponses` 的返回带完整性证明，负断言可信。两者的可信度差异来自接口契约。
 
@@ -249,7 +249,7 @@ Chat Completions 响应**不保证包含完整过程记录**。应用可能在
 
 应用中途停下来等人（工具审批、等补充信息）时，`send` 两侧各有义务：
 
-- **停轮**：返回 `status: "waiting"`，并且每个待回答的问题吐一条带稳定 `id` 的 `input.requested` 事件——`t.parked()`、`t.requireInputRequest()` 读它，回答靠这个 `id` 对位。
+- **停轮**：返回 `status: "waiting"`，并且每个待回答的问题吐一条带稳定 `id` 的 `input.requested` 事件——`t.check(turn.status, equals("waiting"))` 与 `t.requireInputRequest()` 读取它，回答靠这个 `id` 对位。
 - **回答轮**：评估用例里的 `t.respond(...)` 到 Adapter 是**又一次普通的 `send`**（还是同一条会话线、同一份状态），人的裁决以结构化形式随 `input.responses` 到达，每条带 `requestId`、`optionId` 或 `text`（形态见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)）。Adapter 先把裁决交回应用，再接着取结果。被人拒绝的调用，tool `operation.finished` 的 `status` 置 `"rejected"` 而不是 `"failed"`——拒绝是人的决定、不是工具故障，`noFailedActions()` 不误伤。
 
 "停轮时读了一半的现场"（比如一条读到一半的 SSE 流）也存在 `ctx.session` 上。Adapter 先用 `createSessionSlot<Pending>()` 创建私有 slot，停轮时 `ctx.session.set(slot, pending)`，回答轮开头 `ctx.session.take(slot)` 取回。取到即清除，一次消费。
@@ -312,7 +312,8 @@ export default defineAgent({
 
 不需要 HITL 的接口，删掉停轮现场相关的三处（`Pending`、`hold`、开头的 `take` 分支）即可，其余不变。停轮 / 回答 / 续跑的完整心智模型见 [HITL](/zh/explanation/hitl)。
 
-**这一步支持**：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`，以及 `calledTool(toolMatch(..., { status: "rejected" }))` 的精确断言。
+**这一步支持**：`t.check(turn.status, equals("waiting"))`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`。
+被人拒绝的调用可用 `calledTool(toolMatch(..., { status: "rejected" }))` 精确断言。
 
 ## 第六步：接上 OTel trace
 

package/package.json

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