niceeval 0.15.1-canary.76 → 0.16.1

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

@@ -1,14 +1,14 @@
 ---
 title: "实验（Experiment）：评谁、怎么跑"
 sidebarTitle: "实验"
-description: "Experiment 是可签入的运行配置：同一批评估用例对着哪个 agent、哪个模型、开哪些 flags、跑几次。评估用例与 experiment 分开的原因——晚绑定，让同一份评估用例换着对象跑。"
+description: "Experiment 是可签入的运行配置：同一批评估用例对着哪个 Agent、哪个模型、开哪些 flags、跑几次。评估用例与 Experiment 分开，同一批评估用例才能换着对象跑。"
 ---
 
-**experiment** 对着哪个 agent、用哪个模型、开哪些 flags、跑几次。用于做 AB 测试、模型对比、feature 对比——`flags` 就是 A/B 测试里的 feature flag，一个 experiment 是一组 flag 取值。
+Experiment 说明对着哪个 Agent、用哪个模型、开哪些 flags、跑几次。它用来比较模型、prompt 和功能开关：`flags` 就是 A/B 测试里的 feature flag，一个 Experiment 是一组 flag 取值。
 
-## 一个 experiment 里有什么
+## 一个 Experiment 里有什么
 
-experiment 是 `experiments/` 下可签入的 TypeScript 文件，核心就几个字段：
+Experiment 是 `experiments/` 下可签入的 TypeScript 文件，核心就几个字段：
 
 ```ts
 // experiments/concise.ts
@@ -21,27 +21,27 @@ export default defineExperiment({
 });
 ```
 
-- `agent`：评谁。放的是已经配置好的实例——被测系统的 URL、鉴权传给 Adapter 工厂，不进 experiment 的其它字段。
-- `model` / `flags`：由 Adapter 消费的实验条件。`flags` 只接受扁平的字符串、有限数字或布尔值。[NiceEval](https://niceeval.com/) 不解释具体策略；普通 Adapter 声明 `parseFlags` 时先同步校验和规范化，再经 `ctx` 递给 Adapter，由 Adapter 随请求转发、应用按需切换——这正是 [Tier](/zh/explanation/tier) 里模型对比（Tier 1）和 feature A/B（Tier 3）的通道。
-- `attempts`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[写实验](/zh/tutorials/write-experiment)。
+- `agent`：评谁。这里放已经配置好的 Adapter 实例。被测系统的地址和鉴权在创建实例时传给 Adapter，不写进 Experiment 的其它字段。
+- `model` / `flags`：交给 Adapter 的实验条件。`flags` 只接受扁平的字符串、有限数字或布尔值，NiceEval 不解释它们的含义。Adapter 声明了 `parseFlags` 时，先校验和规范化，再经 `ctx` 交给 Adapter；Adapter 随请求转发，应用按值切换行为。模型对比（Tier 1）和功能 A/B（Tier 3）都走这条路，见[接入等级](/zh/explanation/tier)。
+- `attempts`、`budget`、并发、`sandbox` 等运行参数：怎么跑、跑多少。完整字段见[编写实验](/zh/tutorials/write-experiment#常用字段)。
 
 Experiment 还有一对实验级 Hook `setup` / `teardown`：整个实验只跑一次，在你自己的机器上执行，用来起停所有 Attempt 共享的服务（比如一条到内网服务的隧道、一个实验专用的 mock server）。
 
-`setup` 在本实验第一个 Attempt 派发前执行。`teardown` 在全部 Attempt 收尾后执行（中断也执行），当且仅当 `setup` 的时点已经走到才触发。
+`setup` 在这个实验的第一个 Attempt 开始前执行。`teardown` 在全部 Attempt 结束后执行，运行被中断时也会执行；但只有 `setup` 已经执行过，`teardown` 才会执行。
 
-要按实验在 Sandbox 里准备环境，把 action 挂在 `sandbox` 字段的 `.before()` 链上。稳定 action 会按指纹形成可复用准备前缀；动态回调可以用 `context.onCleanup()` 登记收尾。写法见[写实验 · 启动 Experiment 共享服务](/zh/tutorials/write-experiment#启动-experiment-共享服务)与[Sandbox · 按顺序准备 Sandbox](/zh/tutorials/sandbox-providers#按顺序准备-sandbox)。
+要在 Sandbox 里为整个实验准备环境，把准备步骤挂在 `sandbox` 字段的 `.before()` 上。内容不变的步骤下次可以直接沿用；动态回调可以用 `context.onCleanup()` 登记收尾。写法见[启动实验共享服务](/zh/tutorials/experiment-services)与[Sandbox · 按顺序准备 Sandbox](/zh/tutorials/sandbox-providers#按顺序准备-sandbox)。
 
-同一实验里的评估用例需要不同预制环境时，把对应的 template-bearing `sandbox` layer 直接放在各评估用例上，并让 Experiment 不再提供 template。重复 layer 用普通 TypeScript 辅助函数复用；这里没有 environment profile registry。同一个 Experiment 仍能覆盖全部评估用例，因为 link planning 会逐条把评估用例 layer 与 Experiment layer 配对。写法见[写实验 · 让不同评估用例使用不同预制环境](/zh/tutorials/write-experiment#让不同评估用例使用不同预制环境)。
+同一个实验里，不同评估用例需要不同的预制环境时，把指定预制环境的 `sandbox` 配置写在各评估用例上，Experiment 就不再指定。重复的配置用普通的 TypeScript 函数复用，不需要额外注册。同一个 Experiment 仍然能覆盖全部评估用例，NiceEval 会逐条把评估用例的配置和 Experiment 的配置合在一起。写法见[编写实验 · 不同评估用例需要不同环境](/zh/tutorials/write-experiment#不同评估用例需要不同环境)。
 
 ## 矩阵对比
 
-要比较的每个变体写一个 experiment 文件：两个模型就是两个文件，只差 `model` 一行。prompt A/B 就是只差一个参数。同一批评估用例在多个 experiment 下各跑一遍，固定 Inspection operation 在同一 `PublicationCutoff` 中比较已发布 Attempt；每个 Experiment 保留自己的评估用例集合与分母，不伪造共同交集。适合比什么、结果怎么读，见[实验矩阵](/zh/tutorials/experiments)。
+要比较的每个变体写一个 Experiment 文件：两个模型就是两个文件，只差 `model` 一行。prompt A/B 就是只差一个参数。同一批评估用例在多个 Experiment 下各跑一遍，再比较同一时刻已发布的结果。每个 Experiment 按自己跑的评估用例计算分母，不会硬凑一个共同的交集。适合比什么、结果怎么读，见[编写实验](/zh/tutorials/write-experiment#比较两个模型)。
 
-只用于报告归类、不会改变 Attempt 里发生什么的值写进 `labels`。它们是 Run 的不可变配置上下文，不会透传给 Adapter 或评估用例。改变 `labels` 后再次运行会建立带新标注的 Run，并可按当次 policy 引用既有 Attempt；历史 Run 保留当时的 `labels`。
+只用于报告归类、不影响运行过程的值写进 `labels`。它们记在 Run 上，不会传给 Adapter 或评估用例。改了 `labels` 再运行，会建立一个带新标注的 Run，没受影响的旧结果照常沿用；历史 Run 保留当时的 `labels`。
 
 ## 相关阅读
 
-- [写实验](/zh/tutorials/write-experiment) — `defineExperiment` 的完整字段：attempts、预算、并发与 sandbox。
-- [实验矩阵](/zh/tutorials/experiments) — 跨 agent / model / flags 的对比怎么组织、怎么读结果。
-- [评估](/zh/explanation/evals) — 另一半：评估用例是什么、生命周期与 verdict。
+- [编写实验](/zh/tutorials/write-experiment) — 比较模型和 prompt、读对比结果，以及常用字段。
+- [启动实验共享服务](/zh/tutorials/experiment-services) — `setup` / `teardown` 的写法与时序。
+- [评估](/zh/explanation/evals) — 另一半：评估用例是什么、生命周期与判定。
 - [Tier](/zh/explanation/tier) — `model` / `flags` 各在哪一档生效。

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

@@ -12,7 +12,7 @@ Judge 用独立裁判模型评估事实一致性、摘要忠实度和说明质
 在模块顶层写出标准。`rubric` 说明评价维度，`anchors` 给连续质量量尺提供可校准的落点：
 
 ```ts
-import { closeQA, defineJudge } from "niceeval";
+import { defineJudge } from "niceeval";
 
 const explainsRisk = defineJudge({
   name: "explains-risk",
@@ -51,29 +51,36 @@ export default defineEval({
 
 需要观察图片内容时，在材料中放入 `judgeImage({ body, mediaType })`。它冻结 PNG 或 JPEG 字节，不创建另一个裁判，也不发起额外请求。图片和文字经同一次 Judge 调用发送，并保存在同一条断言的证据中。接线步骤见 [附加图片材料](/zh/tutorials/verify-judge#附加图片材料)。
 
-`t.judge(material, explainsRisk)` 与 `t.check(material, explainsRisk)` 都登记一条测量 Assertion。它们会共享材料快照、预算、求值、审计、封口和 handle；没有 Match 允许列表。
+`t.judge(material, explainsRisk)` 与 `t.check(material, explainsRisk)` 都登记一条测量 Assertion。它们会共享材料快照、预算、求值、审计、结果保存和 handle；没有 Match 允许列表。
 
 ## 直接使用现成 Judge
 
 root `t`、Session 与 Turn 都提供现成方法，并返回 Assertions 的 `MeasurementAssertionHandle<Kind>`。例如：
 
 ```ts
-const answer = await t.send("根据材料回答问题。");
-
-answer.closeQA({
-  input: "根据材料回答问题。",
-  output: answer.message,
-  context: "材料只说明产品在周五发布。",
-}).gate(0.8).label("只依据材料回答");
-
-// 与上一条调用等价的 factory 形式：
-answer.check(
-  { input: "根据材料回答问题。", output: answer.message, context: "材料只说明产品在周五发布。" },
-  closeQA(),
+import { eventMatch } from "niceeval/expect";
+const answer = await t.send("列出风险与回滚步骤。");
+answer.closeQA("这轮是否说明风险和可执行的回滚步骤？")
+  .gate(0.8).label("回滚说明");
+
+// 特殊检查可以显式选择全部助手发言。
+answer.closeQA(
+  eventMatch("message", { role: "assistant" }),
+  "全部发言是否清楚说明风险？",
 ).gate(0.8);
 ```
 
-可直接调用的方法是 `factuality(material, options?)`、`faithfulness(material, options?)`、`instructionFollowing(material, options?)`、`pairwisePreference(material, options?)` 和 `closeQA(material, options?)`。它们只 factory 后交给当前接收者的 `check`，不会多登记 Assertion。
+`closeQA(selector, question, options?)` 将全部命中材料保序交给一次 Judge。问题是只依据材料回答的验收问题，不是预设答案。
+Agent 的 `closeQA(question, options?)` 默认使用该 Turn、Session 或 Attempt 的完整正式历史，包含消息与工具事实。它不会只挑最后一句或成功操作。
+显式 EventMatch 选择三类事件视图；工具输入和回执问答使用 ToolMatch，或自定义 MaterialMatch。
+
+这些写法都组合评分 Match 并交给同一个 `check`。`usedNoTools()` 等应用断言则封装固定判据，不接受另一个 Match。
+满足条件为1，条件不成立为0，证据不足为 `unavailable`。完整空集为0且不调用模型；材料缺失或超限不能补零或截断后评分。
+
+Adapter 通过 `create` 提供应用 ctx，`defineMaterialMatch` 的同步 reader 在断言登记时读取当前只读 ctx。
+selector 的 predicate 只判断单项；`and` 约束同一项。普通存在性用 `t.check(selector).gate()`，整组问答用 `t.closeQA(selector, question).gate(0.8)`。
+
+`factuality`、`faithfulness`、`instructionFollowing` 与 `pairwisePreference` 接收显式材料，构造 Match 后交给同一 `check`。
 
 ## 配置裁判 Provider
 
@@ -99,6 +106,7 @@ export default defineConfig({
 | `OpenAIProvider` | OpenAI 或显式兼容网关 | `OPENAI_API_KEY` |
 | `VercelProvider` | Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
 | `OpenRouterProvider` | OpenRouter | `OPENROUTER_API_KEY` |
+
 | `TypesafeProvider` | TypeSafe System One | `TYPESAFE_API_KEY` |
 
 四个工厂都从 `niceeval/judge` 导出。Vercel 工厂表示 AI Gateway，不表示 Vercel Sandbox 或通用 AI SDK model object。

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

@@ -1,37 +1,60 @@
 ---
-title: "NiceEval 的运行后数据流"
-sidebarTitle: "架构概览"
-description: "理解 Record、固定 Inspection operation、Query、Show 和 View 的职责边界。"
+title: "NiceEval 的整体模型：一次评估由哪些部分组成"
+sidebarTitle: "整体模型"
+description: "评估用例、Experiment、Adapter、Sandbox、Runner 和 Record 各管什么，它们怎样连成一次运行，以及为什么同一条评估要跑多次。"
 ---
 
-NiceEval 将运行后的数据分成三层。Record 保存 Run 与已发布 Attempt 的运行事实。Inspection operation 关闭读取语义。三个 consumer 各自交付结果。
+一次评估回答一个问题：被测对象在这个配置下，能不能把这件事做对。NiceEval 把这个问题拆成几个部分，每部分只管一件事。
 
 ```text
-published Run and Attempt facts
-        ↓
-fixed Inspection operations
-        ↓
-machine Query | terminal Show | browser View
+评估用例（什么算做对）      Experiment（对着谁、怎么跑）
+            \                    /
+             \                  /
+              Runner（调度 Attempt、打分）
+                       │
+                 Adapter（连接被测对象）
+                       │
+          被测对象（直连，或在 Sandbox 里运行）
+                       │
+          Record（保存每个 Attempt 的结果）
+                       │
+       show（终端） · view（浏览器） · query（JSON）
 ```
 
-## Record 保存事实
+## 评估用例：什么算做对
 
-每个项目只有一个 canonical `.niceeval/record.sqlite`。Runner 创建 Run 时冻结预期 slot；每个 Attempt 在自己的原子发布事务完成后立即成为可读事实，即使 origin Run 仍是 `active`。已发布 Attempt 和终态 Run 都不可修改。
+评估用例写在 `evals/*.eval.ts` 里，说明发什么、检查什么。它不写对着哪个 Agent、用哪个模型跑，所以同一条评估用例可以换着被测对象跑。
 
-一次 Invocation 完整收尾并通过 portable gate 后，canonical 文件本身即可复制或归档。`query` 和 `show` 的 `--record <file>` 会完整校验外部副本后只读打开。
+检查分两类。确定的事实用确定的规则检查，例如调用了哪个工具、测试有没有通过。开放式的质量交给 Judge，也就是裁判模型，由它按你写的标准打分。见[评估用例](/zh/explanation/evals)和 [Judge](/zh/explanation/judge)。
 
-## Inspection 关闭读取语义
+## Experiment：对着谁、怎么跑
 
-Inspection operation 在返回前决定 source、selector、sealed cutoff、数据缺口、issues、Evidence 和比较方式。它返回可编码 plain data，不把 reader、数据库连接或文件路径交给调用者。
+Experiment 写在 `experiments/` 里，说明用哪个 Adapter、哪个模型、开哪些 flags、每条评估跑几次。要比较两个模型，就写两份只差 `model` 的 Experiment，对着同一批评估用例各跑一遍。见 [Experiment](/zh/explanation/experiment)。
 
-固定 catalog 提供 Run、Attempt、trace、diff、sources、artifacts 和 Run comparison。新的读取需求通过新 operation 或穷尽 union 扩展表达，不通过临时 SQL、JSON path 或公式实现。
+## Adapter 和 Sandbox：怎样连上被测对象
 
-## 三个独立 Consumer
+Adapter 是你写的连接代码。它把评估用例里的动作发给被测对象，再把返回翻译成 NiceEval 能读的事件，例如回复、工具调用和用量。接入可以从只实现 `send` 开始，需要时再加 OTel 或 flags，见 [Adapter](/zh/explanation/adapter) 和[接入等级](/zh/explanation/tier)。
 
-- `niceeval query` 是 machine Query，面向 AI、脚本和 CI。它输出 `niceeval.query/v1` JSON document。
-- `niceeval show` 是 terminal Show，面向人在终端快速审阅和下钻。
-- `niceeval view` 是 browser View，面向人在受保护的 loopback 浏览器使用固定第一方 Insight。
+Coding Agent 要在真实文件系统里改代码、跑命令，NiceEval 先创建一个隔离的 Sandbox，再在里面启动 Agent。直连的 Web Agent 和业务应用不需要 Sandbox。
 
-三个 consumer 共享同一个固定 Inspection result。它们各自负责 JSON protocol、终端文字布局或浏览器界面，不共享 formatter、路由、组件、主题或呈现 schema，也不重选成员或重算业务结果。
+## Runner 和 Attempt：为什么同一条评估要跑多次
 
-继续阅读 [CLI](/zh/reference/cli) 了解完整命令，或阅读 [Record](/zh/explanation/record) 了解外部文件的校验边界。
+LLM 的输出不确定，同一个问题这次答对，下次可能答错。只跑一次，说明不了改动是否真的有效。所以 Experiment 用 `attempts` 指定每条评估用例跑几次，每一次叫一个 Attempt。
+
+Runner 按 Experiment 选出评估用例，展开成一批 Attempt，按并发限制调度执行。每个 Attempt 得到一个判定：`passed`、`failed`、`errored` 或 `skipped`。一批 Attempt 汇总起来，就是这条评估在这个配置下的通过率。计分制评估累计分数而不是读通过率，见[通过制与计分制](/zh/tutorials/evaluation-kinds)。
+
+`failed` 和 `errored` 要分开看。`failed` 是被测对象正常回复了，但没做对。`errored` 是没能拿到可信的结果，例如服务没启动或凭据失效，它说明的是环境问题，不是被测对象的能力。
+
+## Record：结果留下来，供对比和追查
+
+每个 Attempt 跑完，结果连同对话、工具调用、文件改动、耗时和花费，一起保存在项目的 `.niceeval/record.sqlite`，这就是 Record。
+
+结果留下来有两个用处。一是追查：回到某一次失败，看被测对象实际做了什么。二是沿用：再次运行时，没受改动影响的结果直接沿用，只重跑受影响的部分，见[重跑与沿用](/zh/tutorials/rerun-and-cache)。
+
+读结果有三个入口：`show` 在终端逐层查看，你和 Coding Agent 都用它排查；`view` 在浏览器里翻对话和耗时；`query` 输出 JSON，给脚本和 CI 读取。三处读到的结论一致，见[运行结果的数据流](/zh/explanation/results-flow)。
+
+## 接下来
+
+- 第一次使用：读[快速开始](/zh/tutorials/quickstart)。
+- 想了解某个部分：按上面每节末尾的链接继续读。
+- 想查字段和命令：去 [Reference](/zh/reference/define-eval)。

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

@@ -1,31 +1,46 @@
 ---
 title: "Record"
 sidebarTitle: "Record"
-description: "了解 canonical SQLite Record 的写入、携带与读取边界。"
+description: "了解项目结果文件 .niceeval/record.sqlite 保存什么、怎样复制给别人，以及读取时会校验什么。"
 ---
 
-Record 是项目唯一的持久事实集。canonical SQLite 文件位于 `.niceeval/record.sqlite`。
+你想把一次运行的结果交给同事复核，或者归档一份基线留着以后对比。NiceEval 的所有运行结果都在一个文件里：项目里的 `.niceeval/record.sqlite`，这就是 Record。
 
-Run create、运行中的聚合、已发布 Attempt、Attachment、Content、协调状态和 Invocation Session 都是同一份 ProjectDatabase 的 rows。
+## Record 里有什么
 
-Run 创建后立即可发现。Attempt 完成原子发布后，就能在固定 `PublicationCutoff` 中被读取；Run 不必先收口。
+Run、运行中的汇总、已发布的 Attempt，以及它们的附件和内容，都保存在这个文件里。缓存、凭据和用户级服务状态不在里面。
 
-Inspection、`query`、`show` 和 `view` 都遵守这条边界。发布后的 Attempt closure 不可修改。缓存、凭据和 OS-user Service state 不属于 Record。
+Run 一创建就能被查到。Attempt 跑完并发布后，就能被读取，不必等所在的 Run 结束。已发布的 Attempt 不会再被修改。`query`、`show` 和 `view` 都只读已发布的结果。
 
-## 携带 Record
+## 把结果交给别人
+
+运行完整结束后，直接复制这个文件：
 
 ```sh
 cp .niceeval/record.sqlite ./baseline.record.sqlite
-niceeval query explain --record ./baseline.record.sqlite --request request.json
-niceeval show --record ./baseline.record.sqlite
 ```
 
-canonical 文件本身即可复制或归档。不要复制 WAL、checkpoint 或 staging 文件，也不要在复制后修改 SQLite 内容。
+只复制 `record.sqlite` 本身。不要复制旁边的 WAL、checkpoint 或 staging 文件，复制后也不要修改里面的 SQLite 内容。
+
+拿到别人的文件后，用 `--record` 指向它：
+
+```sh
+pnpm exec niceeval show --record ./baseline.record.sqlite
+pnpm --silent exec niceeval query explain --record ./baseline.record.sqlite --request request.json
+```
+
+`view` 只读当前项目的 `.niceeval/record.sqlite`，不接受 `--record`。
+
+## 读取外部文件前会先校验
+
+`query` 和 `show` 把 `--record` 指定的文件当作不可信输入。只有格式版本完全匹配、SQLite 完整性检查通过、内部数据一致时，命令才会读取。校验不通过时，命令直接报错，不会迁移、修补或只读一部分。
+
+文件被拒绝时，先确认它是运行结束后复制的完整单文件，复制期间没有别的进程在写。具体错误和下一步见[排查失败的评估结果](/zh/troubleshooting/debugging#无法打开结果)。
 
-`query` 与 `show` 把 `--record` 指定的文件当 hostile input。只有精确 current schema、SQLite integrity 和领域不变量全部成立时才读取；命令不会迁移、修补或部分读取。Record 仍可能包含敏感业务内容；分享者负责权限、脱敏和保留策略。
+Record 可能包含敏感的业务内容，例如对话原文和文件改动。分享前由你负责权限、脱敏和保留期限。
 
-## 读取边界
+## Record 不负责什么
 
-Record 不负责统计、比较或页面。固定 Inspection operation 在一个 `PublicationCutoff` 读取已发布事实，再把闭合结果交给 `query`、`show` 或第一方 `view`。读取路径不能把数据库、reader、Content handle 或 SQL 能力交给外部代码。
+Record 只保存结果，不做统计、比较或页面。NiceEval 内置的固定查询读取已发布的结果，再把完整的查询结果交给 `query`、`show` 或 `view`。外部代码拿不到数据库连接、读取对象或 SQL 能力。
 
-查看 [CLI](/zh/reference/cli) 选择读取方式。
+选择哪种查看方式见 [CLI](/zh/reference/cli)。

package/docs-site/zh/explanation/results-flow.mdx

@@ -0,0 +1,37 @@
+---
+title: "NiceEval 的运行后数据流"
+sidebarTitle: "运行结果的数据流"
+description: "理解运行结果保存在哪里，以及 query、show 和 view 三个查看入口各管什么。"
+---
+
+一次运行结束后，你可能在终端看结果，也可能在浏览器里翻对话，或者让 CI 脚本读 JSON。三种方式看到的是同一份结果，只是排版不同。这一页说明结果保存在哪里、怎样被读出来，以及三个查看入口各管什么。
+
+```text
+项目里的 .niceeval/record.sqlite（已发布的 Run 和 Attempt）
+        ↓
+NiceEval 内置的固定查询
+        ↓
+query（JSON） | show（终端） | view（浏览器）
+```
+
+## 结果保存在一个文件里
+
+每个项目的运行结果都保存在 `.niceeval/record.sqlite`，这就是 Record。`niceeval exp` 开始时创建 Run，并记下这次计划要跑的所有 Attempt。每个 Attempt 跑完就单独发布，马上可以读到，不必等整个 Run 结束。已发布的 Attempt 和已结束的 Run 都不会再被修改。
+
+运行完整结束后，这个文件本身就可以复制或归档。要读别人交给你的副本时，给 `query` 或 `show` 加 `--record <file>`；NiceEval 会先完整校验这个文件，再只读打开。
+
+## 读取规则由 NiceEval 固定
+
+读取结果时，选哪些 Run、读到哪个时刻为止、哪些结果缺失、有哪些问题、用什么证据、怎样比较，都由 NiceEval 内置的固定查询决定。查询返回的是普通数据，不会把数据库连接、文件路径或读取对象交给调用者。
+
+内置查询覆盖 Run、Attempt、trace、diff、sources、artifacts 和 Run 之间的比较。你不能用临时 SQL、JSON path 或公式自定义读取方式。
+
+## 三个查看入口
+
+- `niceeval show` 在终端里先看总览，再逐层查看某个 Attempt 的对话、耗时和改动。你和 Coding Agent 都用它排查问题。
+- `niceeval query` 输出结构化 JSON，给脚本和 CI 读取，Agent 需要精确字段时也用它。
+- `niceeval view` 给人在浏览器用，打开只监听本机地址、受访问保护的 Insight 界面。
+
+三个入口读到的是同一份查询结果。它们只负责各自的排版：JSON、终端文字或浏览器页面。它们不会各自挑选结果，也不会重新计算通过率或分数，所以同一个 Run 在三处看到的结论一致。
+
+完整命令见 [CLI](/zh/reference/cli)。结果文件怎样复制和校验，见 [Record](/zh/explanation/record)。

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

@@ -1,13 +1,34 @@
 ---
-title: "运行、封口与读取"
+title: "运行怎样产出可读的结果"
 sidebarTitle: "运行器"
-description: "了解 Runner 如何发布 Run，以及读取路径为什么只看已封口事实。"
+description: "了解 Runner 怎样创建 Run、逐个发布 Attempt，以及查看命令为什么只读已发布的结果。"
 ---
 
-Runner 为选中的 Experiment 创建 Run，并在创建事务中冻结 `runId`、`invocationId` 与全部 expected slots。每个 Attempt 完成自己的 closure 后独立原子发布；已发布 Attempt 即使其 Run 仍为 `active`，也能被读取、比较、沿用或显式采用。尚未发布的聚合和晚到写入不对读取面可见。
+你启动 `niceeval exp` 后，还没等它跑完就想看已经出来的结果，或者想知道运行中途被打断时哪些结果还算数。这一页说明 Runner 怎样把一次运行变成可以查看的结果。
 
-命令结束后的 receipt 给出 `createdRunIds` 与 `publicationCutoff`。把它们作为稳定的运行边界：人用 `niceeval view --run <run-id>` 审阅，AI、脚本和 CI 先从 `niceeval query discover` 获取可用 operation，再运行对应 request。
+## Run 在开始时就定下要跑什么
 
-View 在一个固定 `PublicationCutoff` 中读取事实。新 publication 出现后，页面提示用户刷新；用户确认后才切换到新的 cutoff。
+Runner 为每个选中的 Experiment 创建一个 Run。创建时，它记下 `runId`、这次运行的 `invocationId`，以及这次计划要跑的所有 Attempt。之后这份计划不会再变，所以通过率的分母在开始时就确定了。
 
-Runner 不把数据库、执行工作目录或未封口记录交给读取路径。运行后查看的 selector、缺口、Evidence 与 comparison 由固定 Inspection operation 决定。
+## 每个 Attempt 跑完就单独发布
+
+一个 Attempt 跑完、结果全部写好后，会单独发布。发布后它马上可以被查看、比较、在下次运行中沿用，或用 `niceeval accept` 明确采用，即使所在的 Run 仍是 `active`。
+
+还没发布的 Attempt、尚未算完的汇总，以及晚到的写入，都不会出现在任何查看命令里。所以你在运行中途看到的每条结果都是完整的，不会读到写了一半的数据。
+
+## 运行结束时拿到这次的 Run ID
+
+`niceeval exp` 结束时，终端的 `NEXT` 面板会列出这次新建的 Run，并给出两条查看命令：
+
+```sh
+pnpm exec niceeval show --run <run-id>
+pnpm exec niceeval view --run <run-id>
+```
+
+加 `--json` 时，最后一行是这次运行的 receipt，里面的 `createdRunIds` 列出新建的 Run，`publicationCutoff` 标记这次运行结束时已发布到哪里。`publicationCutoff` 不要解析，原样传给后续命令。脚本和 CI 先运行 `niceeval query discover` 找到可用的查询，再发送完整 request。
+
+## 浏览器页面不会自己跳到新结果
+
+`niceeval view` 打开时，固定读取当时已发布的结果。之后又有新的 Attempt 发布时，页面会提示刷新；你确认后，页面才切换到最新结果。这样你在对比数据时，页面不会中途变化。
+
+Runner 不会把数据库、执行时的工作目录或尚未发布的记录交给查看命令。查看时选哪些结果、缺了什么、用什么证据、怎样比较，都由 NiceEval 内置的固定查询决定，见[运行结果的数据流](/zh/explanation/results-flow)。

package/docs-site/zh/index.mdx

@@ -1,135 +1,46 @@
 ---
 title: "NiceEval"
 sidebarTitle: "首页"
-description: "NiceEval 是框架无关的 Agent-Native 评估框架与 Harness，为你的 AI 应用构建评估提供完整的闭环。"
+description: "像写单元测试一样写评估，像做实验一样比较 Agent。用 TypeScript 断言工具调用、回复、代码改动和业务结果，在本地反复运行并追查每一次失败。"
 ---
 
-import { SandboxMode } from '/snippets/diagram-sandbox-mode.jsx';
-import { DirectMode } from '/snippets/diagram-direct-mode.jsx';
-
 <div align="center">
 
 # NiceEval
 
-**为你的 AI 应用打造的 Agent-Native 评估框架与 Harness**
+**像写单元测试一样写评估，像做实验一样比较 Agent**
 
 </div>
 
-[NiceEval](https://niceeval.com/) 是一个受 [eve](https://eve.dev) 启发的 Agent-Native 评估框架与 Harness：`defineEval` 负责写清楚测什么，Harness 负责连接被测对象、运行、评分并生成报告。两者合在一起，就是从编写评估用例到查看结果、优化 Agent 的完整闭环。它首先追求良好的开发体验：一个项目可以在 10 分钟左右接入，评估用例文件足够直观，结果也足够容易读。
+你改了 prompt、换了模型、给 Coding Agent 写了一个新 Skill，或者调了 LLM 游戏里的 NPC，想知道它到底有没有变好。NiceEval 让你用 TypeScript 写下“什么算做对”，然后反复运行、打分、比较，并回到每一次失败去看 Agent 实际做了什么。
 
-它也框架无关、足够通用：可以用来评估给 Claude Code / Codex 写的 Coding Agent 插件、Hook 和 Skill，也可以评估你自己的 AI Agent 应用。无论你的应用基于 AI SDK、LangGraph、Pi，还是自研 Agent loop，都可以通过 Adapter 接入。
+所有运行都在你自己的机器和 CI 里完成，不需要注册账号。
 
-Run 会持续发布已完成的 Attempt 到项目内唯一的 Record。你可以用 `niceeval show` 快速审阅，用 `query` 交给自动化，并在 `niceeval view` 中查看同一批事实的详情、通过率、成本和延迟。
+## 从这里开始
 
 <CardGroup cols={3}>
-  <Card title="Agent Framework 接入" icon="code-branch" href="/zh/examples">
-    对照 AI SDK、Claude SDK、Codex SDK、pi-agent-core 和 LangGraph 的可运行接入项目。
+  <Card title="NiceEval 是什么" icon="book-open" href="/zh/introduction">
+    适合评什么、一条评估用例长什么样、和其它工具有什么不同。
   </Card>
-  <Card title="Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
-    用真实 Workspace 和对照实验衡量 Skill、提示词与 Plugin Benchmark 的实际收益。
+  <Card title="快速开始" icon="play" href="/zh/tutorials/quickstart">
+    十分钟左右跑通第一条评估用例，并看到结果。
   </Card>
-  <Card title="自写 Adapter" icon="globe" href="/zh/examples/ai-agent-application">
-    查看一个覆盖工具、图片、多轮、模型对比和 OTel 的完整 AI Agent 项目。
+  <Card title="可运行示例" icon="grid-2" href="/zh/examples">
+    AI SDK、Claude SDK、Codex SDK、Pi、LangGraph 的完整接入项目。
   </Card>
 </CardGroup>
 
-## 架构
-
-[NiceEval](https://niceeval.com/) 支持两种接入方式，取决于被测系统是否需要隔离工作区。
-
-### 模式一：Sandbox
-
-跑 Codex、Claude Code 等需要 Sandbox 的 coding agent：
-
-<SandboxMode />
-
-### 模式二：直连
-
-直接连接你自己的 AI Agent：
-
-<DirectMode />
-
-- **NiceEval runner** 负责发现评估用例、调度运行、打分并发布 Run 与 Attempt 事实。
-- **Agent 适配器** 是开放边界：你决定如何调用被测系统，以及如何把输出映射成标准事件流。
-- **Sandbox** 负责文件系统隔离：需要真实 workspace 的 coding agent 使用 Docker 或云端 Sandbox。自有 Web Agent 可以直连，无需 Docker。
-
-## 核心概念一览
-
-| 概念 | 一句话 |
-|---|---|
-| [评估用例](/zh/explanation/evals) | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
-| [Experiment](/zh/explanation/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
-| [Adapter](/zh/explanation/adapter) | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
-| [Sandbox](/zh/tutorials/sandbox-providers) | 需要隔离工作区的 coding agent 才用得到。直连 Web Agent 不需要。 |
-| [Tier](/zh/explanation/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
-
-完整术语表见[架构概览](/zh/explanation/overview)。
-
-## 示例
-
-跑一条评估用例需要两个文件：评估用例本身（测什么）和 experiment（跑哪个 agent）。CLI 不接受单独的评估用例 id——`niceeval exp <experiment> <eval 前缀>` 里的 experiment 才决定「连哪个被测对象」。下面是一个直连 Web Agent 的真实场景（完整项目见仓库 `examples/zh/ai-sdk/`），验证 agent 遇到实时天气问题时会调用工具、并基于工具结果作答，而不是凭空编造：
-
-```ts
-// evals/weather-tool.eval.ts
-import { defineEval, defineJudge } from "niceeval";
-import { includes } from "niceeval/expect";
-
-const groundedWeatherAnswer = defineJudge({
-  name: "grounded-weather-answer",
-  rubric: "根据 question 评价 answer 是否给出具体天气信息，而不是拒绝或含糊作答。",
-});
-
-export default defineEval({
-  judge: groundedWeatherAnswer,
-  description: "测试 agent 在实时天气问题中正确调用工具并基于结果作答的能力",
-
-  async test(t) {
-    const turn = await t.send("北京今天天气怎么样？");
-    turn.succeeded().label("Turn 成功");
-
-    await t.group("调用 get_weather 且回答天气", () => {
-      t.calledTool("get_weather").label("调用天气工具");
-      t.check(turn.message, includes("天气")).label("说明天气");
-    });
-
-    t.judge({ question: turn.input, answer: turn.message }, groundedWeatherAnswer).gate(0.7)
-      .label("回答有依据");
-  },
-});
-```
-
-```ts
-// experiments/local.ts
-import { defineExperiment } from "niceeval";
-import { webAgent } from "./adapter"; // 你自己写的 Adapter，接被测 Web Agent
-
-export default defineExperiment({
-  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
-  model: "gpt-5.4",
-});
-```
-
-```sh
-npx niceeval exp local weather-tool
-pnpm exec niceeval query discover  # 让 AI、脚本或 CI 发现固定 JSON operation
-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)。
-
-## 快速开始
-
-先从[快速开始](/zh/tutorials/quickstart)完成第一次运行。接入现有应用时，按[接入你的 Agent](/zh/tutorials/connect-your-agent)选择 Adapter 和 Experiment。
+## 按你要评的对象
 
 <CardGroup cols={3}>
-  <Card title="浏览所有可运行示例" icon="grid-2" href="/zh/examples">
-    按被测对象选择接入前后源码和完整项目。
+  <Card title="你自己的 AI Agent" icon="globe" href="/zh/tutorials/connect-your-agent">
+    写一个 Adapter 连上 Agent 接口，断言回复、工具调用和结构化输出。
   </Card>
-  <Card title="评估 Coding Agent 扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
-    复用真实 Workspace、Baseline 和多 Arm 实验设计。
+  <Card title="Coding Agent 和它的扩展" icon="wand-magic-sparkles" href="/zh/examples/coding-agent-extensions">
+    在 Sandbox 里给 Agent 一个真实仓库，用对照实验衡量 Skill 和 Plugin 的效果。
   </Card>
-  <Card title="自写 Adapter" icon="globe" href="/zh/examples/ai-agent-application">
-    查看自定义 HTTP 协议和事件映射的完整项目。
+  <Card title="任何 AI 应用，比如 LLM 游戏" icon="gamepad" href="/zh/tutorials/custom-application">
+    把发帖、回复、NPC 行动这类业务操作原样交给评估用例，检查结构化结果和世界状态。
   </Card>
 </CardGroup>
 
@@ -137,16 +48,12 @@ pnpm exec niceeval view            # 在网页中审阅结果
 
 <AccordionGroup>
   <Accordion title="需要注册账号吗？">
-    不需要。跑评估用例和 `niceeval view` 审阅结果都在本地完成。只有被测对象本身需要隔离工作区时，才会用到 Docker 或 E2B 这类 Sandbox Provider。
+    不需要。运行评估和查看结果都在本地完成。只有被测对象需要隔离环境时，才会用到 Docker 或 E2B 这类 Sandbox Provider。
   </Accordion>
-  <Accordion title="我的 Agent 不是用 TypeScript / JavaScript 写的，能接吗？">
-    能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发。应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/explanation/adapter)。
+  <Accordion title="我的 Agent 不是用 TypeScript 写的，能接吗？">
+    能。评估用例和 Adapter 用 TypeScript 写，被测应用可以是任何语言。Adapter 只是通过 HTTP、gRPC 或 WebSocket 请求应用已有的接口，见 [Adapter](/zh/explanation/adapter)。
   </Accordion>
   <Accordion title="能接到 CI 里吗？">
-    能，见 [CI 集成](/zh/tutorials/ci-integration)。
+    能。在 CI 里运行同一条 `niceeval exp` 命令，退出码反映评估是否通过，见 [CI 集成](/zh/tutorials/ci-integration)。
   </Accordion>
 </AccordionGroup>
-
-<Tip>
-  想先走最小路径，读 [快速开始](/zh/tutorials/quickstart)。想理解边界，读 [架构概览](/zh/explanation/overview)。
-</Tip>