niceeval 0.12.1 → 0.12.2-canary.31

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

@@ -1,157 +1,81 @@
 ---
-title: "NiceEval runner 如何调度和执行评估用例"
+title: "Runner 如何执行评估"
 sidebarTitle: "运行器"
-description: "NiceEval runner 发现评估用例，用有界并发调度，缓存结果，重试脆弱基础设施，并执行预算保护。"
+description: "了解 Runner 怎样建立 Run、选择执行或采用 Attempt，并返回可供后续读取的 receipt。"
 ---
 
-Runner 是把评估用例文件变成一次实际运行的执行引擎。它负责发现、过滤、调度、缓存、attempt、reporters 和 artifact 输出。
+Runner 把选中的 Experiment 和 Eval 排成一次 Invocation。它在当前进程中安排执行、显示进度，并把停稳后的业务事实写入 Record。
 
-## 发现
+## Invocation、Run 与 Attempt
 
-runner 会读取 `evals/` 下的：
+一次 Invocation 有一个 `invocationId`。每个选中的 Experiment 建立一个 Run；Run 的 expected slots 决定本次分母。
 
-- `*.eval.ts` 文件
-- 导出评估用例数组的测试集文件
+每个 slot 最多有一个 Member。Member 表示这个 slot 被哪个 Attempt 占据：Attempt 的 `origin` 与当前 slot 一致时是 `origin`，采用其它 Run 的 Attempt 时是 `reference`。
 
-```bash
-npx niceeval list
-```
-
-`list` 只发现和打印 ID，不执行评估用例。
-
-发现按文件路径的字典序排，所以文件名前缀就能定顺序：`01-`、`02-` 这样命名的文件，发现顺序就是 01、02。数字前缀要补齐位数——字典序不识别数字大小，`10-` 会排在 `2-` 前面。
-
-## 过滤
-
-`exp` 命令中,实验名之后的位置参数是评估用例 ID 前缀：
+占位怎样形成属于 Run-owned 的 `niceeval.membership-provenance/v1` RecordAttachment。Attempt 始终保存实际执行它的 origin；采用不复制 Verdict、Usage、事件或其他业务事实。
 
-```bash
-npx niceeval exp local
-npx niceeval exp local weather
-npx niceeval exp local fixtures/button
-```
-
-不要把 agent 名放进位置参数。agent/model/flags 写进 experiment。
+## 执行前的规划
 
-## 并发
+`niceeval exp --dry` 在停稳的 Record 上列出每个 slot 的计划。它读取规划需要的 Verdict 与 Eligibility RecordAttachment，再决定执行还是采用已有 Attempt。
 
-```bash
-npx niceeval exp local --max-concurrency 8
+```sh
+npx niceeval exp checkout --dry
 ```
 
-远程 HTTP agent 可以用更高并发；本地 Docker Sandbox 通常需要更低并发，避免 CPU、内存和磁盘竞争。
-
-把跑得慢的实验和跑得快的实验混在一次命令里跑是安全的：并发名额优先给「要跑最多轮才能跑完」的实验（比如 `maxConcurrency: 1` 又有几十个 Attempt 的那个），快的实验见缝插针补空位。慢实验有一段 `setup`（起隧道、起共享服务）时也一样——它等 `setup` 的这段时间不占名额，别的实验照常跑，`setup` 一好它就拿下一个空出来的名额，不用为它单开一次命令。
-
-两道闸怎么配、共享状态怎么串行、执行顺序怎么钉死，见[并发与执行顺序](/zh/tutorials/concurrency)。
-
-### 执行顺序
+carry 只在终态、输入身份、超时和 `--rerun` 条件都合适时发生。资格、身份和采用理由作为事实写入目标 Run 的 Membership provenance Attachment。分析选择与 reuse planning 是两件事：前者建立查看分母，后者决定本次要执行哪些 slot。
 
-结果永远按发现顺序输出，跟这次开了多大并发无关，所以终端里的行序和报告里的行序是稳定的、可以直接 diff。只希望读起来有序的话到这里就够了，不用动并发。
+规划完成后，Runner 才启动需要执行的 Attempt。详情见[重跑与沿用](/zh/tutorials/rerun-and-cache)。
 
-实际的执行顺序是另一回事：并发大于 1 时，谁先开跑不做承诺。名额优先给要跑最多轮才能跑完的实验，拿到名额之后创建 Sandbox、跑各层 `setup` 的快慢也各不相同。
+## 当前进程反馈
 
-需要「前一条评估用例跑完再跑下一条」——比如后一条要用到前一条写进记忆库的内容——把该实验的 `maxConcurrency` 设成 1，并且同一个实验只开一个终端跑。这时执行顺序就是发现顺序。`attempts` 大于 1 时按轮次跑：这批评估用例各跑一遍算一轮，跑完再开下一轮，同一条评估用例的多次 Attempt 不连在一起。多开终端时两边各有一条串行队列，合起来的先后就不按命名了。
+运行时的进度、活动 Attempt 和短诊断只服务当前进程。终端可以显示它们，`--json` 也会输出相同的机器可读反馈。
 
-还要注意结果沿用：上一次已经判定的评估用例这次直接复用、不再执行，它写进去的状态也就不会重新产生。顺序依赖这份状态时，用 `--rerun all` 从头跑。
-
-## attempts 与首过即停
-
-```bash
-npx niceeval exp local fixtures/button --attempts 5
-npx niceeval exp local fixtures/button --attempts 5 --early-exit
+```sh
+npx niceeval exp checkout --json
 ```
 
-`attempts` 用于测 pass rate，默认跑满 `attempts` 次，给出完整的通过率分布。首过即停默认关闭；只想知道"这题能不能过"、不在乎完整分布时，用 `--early-exit` 打开——某个 Attempt 通过后，同一 eval 的剩余 Attempt 会被停止。
-
-`attempts` 的多次 Attempt 默认并发派发，并发上限由 `--max-concurrency`（或该实验的 `maxConcurrency`）决定——不会等上一次的结果出来再决定要不要派发下一次。首过即停能省下的，只是还没抢到并发名额、原本要排队的那些 Attempt；已经在跑的不受影响。想要"跑一次，过了就停、没过才跑下一次"这种一个接一个的效果，把该实验的 `maxConcurrency` 设成 1 并开启 `earlyExit`：并发名额只有一个时，同一个 eval 的 Attempt 只能排队依次跑，首过即停自然就能在下一次派发前生效。
-
-## 缓存
-
-[NiceEval](https://niceeval.com/) 按 fingerprint 跳过已判定为 `passed` 或 `failed` 的结果——两者都是判定确定的终态。`errored`（超时、Sandbox 异常等框架/环境层面的不确定失败）永远重试。
-
-fingerprint 由两部分组成：
-
-- **评估用例的源码**：`.eval.ts` 文件本身，加上它 import 的项目内模块，以及用 `loadYaml` / `loadJson` / `loadText` 读进来的数据文件。隐藏测试脚本、参考实现这类判据文件用 `loadText` 读入，改动同样触发重跑；用 `fs` 自己读的文件不在 fingerprint 里。loader 要写在模块顶层——缓存判断发生在运行之前，写进 `test(t)` 里会直接报错。断言抽在公共 helper 里时，改那个 helper 会让引用它的评估用例全部重跑。
-- **运行配置**：实验 ID、Agent、model、flags、Sandbox、`Judge` 的模型与端点，以及 `--strict`。超时上限不在里面——它决定等不等得到，不决定跑出来的结果是什么。
-
-被测程序自己的源码、Agent CLI 的版本、Sandbox 镜像的内容都不在 fingerprint 里。改了这些要复验，用 `--rerun`（只重跑失败项）或 `--rerun all`（全部重跑）。调试非确定性行为时同样用 `--rerun all`。
-
-哪一处改动作废哪些结果、`--rerun` 三档各采信什么，逐场景的对照见[重跑与沿用](/zh/tutorials/rerun-and-cache)。
-
-## 并行开多个终端
-
-想同时跑几个 Experiment，直接开几个终端各跑各的；一场大实验嫌慢，就再开一个终端跑同一条命令，两边会自动分工：
-
-```bash
-# 各跑各的：两个实验并行
-npx niceeval exp compare/codex     # 终端 1
-npx niceeval exp compare/claude    # 终端 2
-
-# 给同一场实验加速：同一条命令再跑一遍
-npx niceeval exp compare/bub       # 终端 1
-npx niceeval exp compare/bub       # 终端 2
+`exp --json` 输出 NDJSON。progress 与 diagnostic 行描述当前 Invocation；它们不是 Record 的解码格式。最后恰好一行是轻量 `InvocationReceipt`：
+
+```json
+{
+  "type": "receipt",
+  "receipt": {
+    "invocationId": "01J8ZK3M6P4T7V9X2C5N8QW0RY",
+    "runIds": ["01J9ZK3M6P4T7V9X2C5N8QW0RY"],
+    "startedAt": "2026-08-09T10:00:00.000Z",
+    "completedAt": "2026-08-09T10:01:00.000Z",
+    "completion": "completed"
+  }
+}
 ```
 
-每次运行写自己的结果快照目录，互不覆盖。就算两条命令选中了同一批评估用例，NiceEval 也不会把任何一条跑两遍：每条评估用例开跑前会在 `.niceeval/locks/` 下拿一把带心跳的锁，锁是跑到哪条拿哪条，不会一口气把整批占住。另一次运行撞到锁，就先去跑还没人认领的评估用例——所以同一条命令开两个终端就是加速：两边自动认领不同的评估用例，各按自己的 `--max-concurrency` 推进，总吞吐接近两边之和。撞锁的评估用例在 live 面板上单独计成 `elsewhere`（别人在运行），并显示一行 `waiting on another run` 说明在等谁；对方跑完、锁一放开，等待方接着往下走。每条评估用例拿到锁的那一刻，都会按缓存规则再看一眼它当前的结果：另一次运行已经跑完落盘的直接复用，还缺的 Attempt 才自己跑。所以不管两个终端的快慢怎么错开，两边最后都拿到完整结果，每条评估用例只花一份钱。
-
-锁不会合并两边的并发名额：两个终端各有自己的 `--max-concurrency` 和实验 `maxConcurrency`，Sandbox Provider 和模型接口承受的是两边之和，配额紧张时把两边都调低一点。需要保护同一 checkpoint 时，用实验的 `sharedState.key` 串行完整恢复和回存窗口。
-
-某次运行被 `kill -9` 或断电杀掉时，它留下的锁不会卡住后来者：心跳停止 30 秒后，下一次运行会自动接管这把锁照常跑。`.niceeval/locks/` 不需要手工清理。
+receipt 只说明本次调用的身份、Run、时间与完成状态。需要 Verdict、Usage、诊断或报告聚合时，用其中的 `runIds` 重新读取已发布的 Record。
 
-## Turn 瞬时错误重试
+## Run 如何发布
 
-限流、连接建立失败这类瞬时错误，NiceEval 会在同一个 Turn 里自动做有限次数的指数退避重试，不需要你重跑整个实验；等待重试的 Attempt 会把全局并发名额让给别的 Attempt，但实验自己的 `maxConcurrency` 名额不让——声明了 `maxConcurrency: 1` 的串行实验在退避期间也不会有第二个 Attempt 提前进场。只有能确认 Agent 还没开始处理这次输入的错误才会重试——请求已经开始、中途断流的情况不重试，直接记为 `errored`，避免 Agent 把已经做过的操作再做一遍。重试用尽仍失败时，该 Attempt 记为 `errored`，下次运行照常重试（见上面的缓存规则）。
-
-## 声明失败的波及范围
-
-有些失败你第一次看到就知道不止这一次：整个 Experiment 共享的服务死了，每条评估用例都会同样死；某条评估用例的 fixture 文件缺失，`attempts: 5` 五次都会同样死。不声明的话，NiceEval 只能一条条撞——每个 Attempt 各自创建 Sandbox、各自失败，同一个死因烧几十遍。把你知道的告诉它，第一次撞上就停：
-
-```ts
-import { ExperimentFatalError } from "niceeval";
-
-// 在 setup 或校验代码里抛出:这个 Experiment 还没跑的 Attempt 全部停止派发
-throw new ExperimentFatalError("记忆服务探活失败——修好隧道、更新 .env 后重跑");
-```
-
-只影响一条评估用例的死因（fixture 缺失）抛 `EvalFatalError`，只停这一条的剩余 Attempt，别的评估用例照常跑。错误 message 会原样出现在终端通知和结果快照里，写成「现象 + 下一步」，就是留给修的人的字条。服务在 run 中途死掉、失败以连接错误的形态冒出来时，给 Experiment 配 `classifyFailure`，只认自己共享服务的 host 来识别它。
-
-停下来的 Attempt 计入 `unstarted`，这次运行的结论是 `incomplete`，不会伪装成全绿；同批其它 Experiment 不受影响。修好环境后重跑同一条命令就是续跑：已通过的照常复用，只补跑死掉与没跑的部分，没有任何标记要解除。只声明你能确定的死因——「看起来像基建问题」不算确定；拿不准就让它落成单条 Attempt 的失败，多烧的是一个 Sandbox 的钱，错停的是整批数据。
-
-## 超时和预算
-
-```bash
-npx niceeval exp local --timeout 300000 --budget 5
-```
-
-超时保护单个评估用例，预算保护整次运行成本。NiceEval 只有在 Attempt 已经发起 Agent Turn、却连续拿不到成本数据时，才提示预算无法执行。如果 Attempt 在 `sandbox.create` 或 setup 阶段就失败，Agent 尚未运行，CLI 只显示对应的结构化执行错误，不再追加容易误导排查方向的预算警告。
+Runner 先写 Run Core、Member、Attempt 和它们的 RecordAttachment。所有 durable 内容写完后，最后创建零字节 `complete`。在此之前退出、I/O 失败或中断会留下未完成目录；它不进入 reader、Sample 或 reuse，可用 `niceeval clean` 清理。
 
 ## Reporter
 
-运行中的反馈只有两种形态，Reporter 是另一层，负责把运行结束后的结果写到其它目的地：
-
-```bash
-npx niceeval exp local          # 人读文本：TTY 下原地刷新 live 面板，非 TTY（管道、CI 日志）自动降级成只追加的文本流
-npx niceeval exp local --json   # 机器面：stdout 一行一个 JSON 对象，start 打头、result 收尾
-```
+Reporter 只接入当前 Invocation。它可以把当前进程已知的结果交给外部系统；`--junit` 也会写出供 CI 平台读取的文件。
 
-`--json` 不逐条打印每次状态变化：只有失败、错误和去重后的 warning 立即追加一行，长时间没有这些事件才补一条 `progress` 心跳。两种形态读取同一套事实，调度、判定和 artifact 完全一致，只是呈现不同。
+这些输出不拥有 Record。Verdict、Usage、断言与诊断仍属于停稳 Record 的 Attachment。需要在后续步骤查看完整结果时，使用 receipt 的 `runIds` 选择 Sample，再运行 `show`、`view` 或 `view --out`。
 
-Runner 在评估用例完成后把结果交给 Reporters：
+## 停稳后查看
 
-- JSON artifacts 用于后续分析。
-- JUnit reporter 适合 CI。
-- Braintrust reporter 把一次运行作为实验上报，跨提交比较。
+Runner 结束后，用明确 Run 选择查看结果：
 
-挂载方式和 Braintrust 配置见 [Reporter 上报](/zh/tutorials/reporters)。
+```sh
+npx niceeval show --run 01J9ZK3M6P4T7V9X2C5N8QW0RY
+npx niceeval view --run 01J9ZK3M6P4T7V9X2C5N8QW0RY --no-open
+```
 
-## 输出目录
+不带 locator 或 `--run` 的 `show` 和 `view` 读取身份仍匹配当前项目的全部结果；locator 与 `--run` 读取指定历史事实。内部 host 形成纯
+`AnalysisSample`，按 Report 声明投影所需事实，并生成固定的 `ReportExecution`。
+已发布的 Run 不可修改；再次查看会形成新的选择与 execution。
 
-每次运行会写入该实验的结果快照目录 `.niceeval/<experiment>/<快照>/`，包括快照级 `snapshot.json`，以及每个 Attempt 的 `result.json`（判定、断言、结构化错误、diagnostics）和按需生成的 `events.json`、`sources.json`、`trace.json`、`o11y.json`、`diff.json` 等拆分 artifact。瞬时 progress 不落盘。
+## 结束状态
 
-## 推荐调试流程
+进程退出状态反映这次 Runner 已知的 Verdict、执行错误和 Invocation completion。CI 可以用退出状态决定是否通过；机器调用方可以读取最后的 receipt，再用 `runIds` 选择要显示或导出的结果。
 
-1. 先跑 `npx niceeval list` 确认发现结果。
-2. 用 `npx niceeval exp <实验> <ID 前缀>` 缩小到一个 eval。
-3. 失败后复制终端里的 locator，先运行 `npx niceeval show @<locator>` 看错误或断言摘要；需要 Agent 行为时再加 `--execution`，需要文件变化时加 `--diff`。
-4. 再扩大到完整 suite 或 experiment。
+没有建立 Invocation 的输入错误没有 receipt。此时先修正命令、Experiment 或选择条件，再重新运行。

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

@@ -20,7 +20,7 @@ import { TierLadder } from '/snippets/diagram-tier-ladder.jsx';
 
 ## Tier 2：send + OTel
 
-还是同一个 `send`、同一套事件映射，只是让应用把 OTel span 也发给 [NiceEval](https://niceeval.com/) 一份。应用已埋点（AI SDK telemetry、LangGraph、OpenLLMetry / OpenInference、自埋 gen_ai）就零改动；没埋点补的是一段通用 OTel 初始化——这属于可观测性建设，不是为评估用例定制的改造。
+还是同一个 `send`、同一套事件映射，只是让应用把 OTel span 也发给 [NiceEval](https://niceeval.com/) 一份。应用已埋点（AI SDK telemetry、LangGraph、OpenLLMetry / OpenInference、自埋 gen_ai）就零改动。没埋点补的是一段通用 OTel 初始化——这属于可观测性建设，不是为评估用例定制的改造。
 
 这一档买到的是**观测**：`niceeval view` 的调用瀑布图——应用内部每次模型调用、每次工具执行、各自的耗时与 token，按轮铺成时间线。断言不受影响：span 只进瀑布图，不进事件流、不喂断言。走法见[OTel 接入](/zh/tutorials/connect-otel)。
 
@@ -36,7 +36,7 @@ import { TierLadder } from '/snippets/diagram-tier-ladder.jsx';
 
 ## 怎么升级
 
-三级递进不互斥：先用 Tier 1 跑通基线和模型对比；要调用瀑布图，升 Tier 2；要对照应用内部变体，再升 Tier 3。每次升级都只是给 Adapter 或应用加东西，experiment 侧怎么组织对比见[实验](/zh/explanation/experiment)。
+三级递进不互斥：先用 Tier 1 跑通基线和模型对比。要调用瀑布图，升 Tier 2。要对照应用内部变体，再升 Tier 3。每次升级都只是给 Adapter 或应用加东西，experiment 侧怎么组织对比见[实验](/zh/explanation/experiment)。
 
 ## 相关阅读
 

package/docs-site/zh/index.mdx

@@ -51,7 +51,7 @@ import { DirectMode } from '/snippets/diagram-direct-mode.jsx';
 
 - **[NiceEval](https://niceeval.com/) 核心** 负责发现评估用例、调度运行、打分、生成报告与 artifacts。
 - **Agent 适配器** 是开放边界：你决定如何调用被测系统，以及如何把输出映射成标准事件流。
-- **Sandbox** 负责文件系统隔离：需要真实 workspace 的 coding agent 使用 Docker 或云端 Sandbox；自有 Web Agent 可以直连，无需 Docker。
+- **Sandbox** 负责文件系统隔离：需要真实 workspace 的 coding agent 使用 Docker 或云端 Sandbox。自有 Web Agent 可以直连，无需 Docker。
 
 ## 核心概念一览
 
@@ -60,34 +60,36 @@ import { DirectMode } from '/snippets/diagram-direct-mode.jsx';
 | [评估用例](/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 不需要。 |
+| [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 遇到实时天气问题时会调用工具、并基于工具结果作答，而不是凭空编造：
+跑一条评估用例需要两个文件：评估用例本身（测什么）和 experiment（跑哪个 agent）。CLI 不接受单独的评估用例 id——`niceeval exp <experiment> <eval 前缀>` 里的 experiment 才决定「连哪个被测对象」。下面是一个直连 Web Agent 的真实场景（完整项目见仓库 `examples/zh/ai-sdk/`），验证 agent 遇到实时天气问题时会调用工具、并基于工具结果作答，而不是凭空编造：
 
 ```ts
 // evals/weather-tool.eval.ts
 import { defineEval } from "niceeval";
+import { includes } from "niceeval/expect";
 
 export default defineEval({
+  judge: true,
   description: "测试 agent 在实时天气问题中正确调用工具并基于结果作答的能力",
 
   async test(t) {
     const turn = await t.send("北京今天天气怎么样？");
-    turn.succeeded();
+    turn.succeeded().label("Turn 成功");
 
-    await t.group("调用 get_weather 且城市正确", () => {
-      t.calledTool("get_weather", { input: { city: "北京" } });
-      t.messageIncludes(/°C|气温|天气|晴|多云|雨/);
+    await t.group("调用 get_weather 且回答天气", () => {
+      t.calledTool("get_weather").label("调用天气工具");
+      t.check(turn.message, includes("天气")).label("说明天气");
     });
 
-    t.judge.autoevals
-      .closedQA("助手是否基于工具返回的天气数据作答，而不是凭空编造温度？")
-      .atLeast(0.7);
+    turn.judge.autoevals.closedQA("助手是否基于工具返回的天气数据作答？")
+      .atLeast(0.7)
+      .label("回答有依据");
   },
 });
 ```
@@ -109,7 +111,7 @@ npx niceeval show       # 终端读取结果，失败项可继续下钻
 npx niceeval view       # 网页交互浏览
 ```
 
-如果被测对象是需要隔离工作区的 coding agent（Codex、Claude Code 插件/Skill），评估用例里改用 `t.sandbox.uploadDirectory()` 铺工作区、`t.sandbox.fileChanged()` / `t.sandbox.file()` 检查改了什么文件、`t.sandbox.runCommand()` 跑测试——参考独立仓库 [coding-agent-skill](https://github.com/CorrectRoadH/coding-agent-skill)。
+如果被测对象是需要隔离工作区的 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)。
 
 ## 快速开始
 
@@ -135,10 +137,10 @@ READ https://niceeval.com/INIT.md and set up niceeval for this repo: install it,
 
 <AccordionGroup>
   <Accordion title="需要注册账号吗？">
-    不需要。跑评估用例和 `niceeval view` 看报告全在本地完成；只有被测对象本身是需要隔离工作区的 coding agent 时，才会用到 Docker 或 E2B 这类 Sandbox provider。
+    不需要。跑评估用例和 `niceeval view` 看报告全在本地完成。只有被测对象本身是需要隔离工作区的 coding agent 时，才会用到 Docker 或 E2B 这类 Sandbox provider。
   </Accordion>
   <Accordion title="我的 Agent 不是用 TypeScript / JavaScript 写的，能接吗？">
-    能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发；应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/explanation/adapter)。
+    能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发。应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/explanation/adapter)。
   </Accordion>
   <Accordion title="能接到 CI 里吗？">
     能，见 [CI 集成](/zh/tutorials/ci-integration)。

package/docs-site/zh/introduction.mdx

@@ -17,40 +17,42 @@ NiceEval 以本地优先为核心：你的评估在你自己的环境中运行
 ```ts
 // evals/eval-tool-call.eval.ts
 import { defineEval } from "niceeval";
+import { includes } from "niceeval/expect";
 
 export default defineEval({
+  judge: true,
   description: "测试 agent 在实时天气问题中正确调用工具并基于结果作答的能力",
 
   async test(t) {
     const turn = await t.send("北京今天天气怎么样？");
-    t.succeeded();
+    turn.succeeded().label("Turn 成功");
 
-    await t.group("调用 get_weather 且城市正确", () => {
-      t.calledTool("get_weather", { input: { city: "北京" } });
-      t.messageIncludes(/°C|气温|天气|晴|多云|雨/);
+    await t.group("调用 get_weather 且回答天气", () => {
+      t.calledTool("get_weather").label("调用天气工具");
+      t.check(turn.message, includes("天气")).label("说明天气");
     });
 
     const second = await t.send("上海明天天气怎么样?");
-    second.messageIncludes("上海");
+    t.check(second.message, includes("上海")).label("第二轮回答上海");
 
-    t.judge.autoevals
-      .closedQA("助手是否基于工具返回的天气数据作答，而不是凭空编造温度？")
-      .atLeast(0.7);
+    turn.judge.autoevals.closedQA("助手是否基于工具返回的天气数据作答？")
+      .atLeast(0.7)
+      .label("回答有依据");
   },
 });
 ```
 
 ```sh
 pnpm exec niceeval exp local eval-tool-call  # 用 local experiment 只跑 eval-tool-call
-pnpm exec niceeval show                      # 终端读取结果，适合人和 AI
-pnpm exec niceeval view                      # 在网页中浏览
+pnpm exec niceeval show             # 当前项目全部仍有效的结果，适合人和 AI
+pnpm exec niceeval view             # 在网页中浏览同一份 Sample
 ```
 
 ## 为什么有了 DeepEval、LangFuse、BrainTrust 还需要 NiceEval
 
-NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「构建 Input 与 Expected Output」的模式，并不适合真实的 Agent 评估——现在的 Agent 要在多轮对话、多 agent 协作、工具调用、Skill 加载等细粒度场景下被检查，NiceEval 就是为这类场景设计的：断言直接落在工具调用、消息内容、结构化输出和用量上，而不是要求你先手工准备一份 golden 测试集。
+NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「构建 Input 与 Expected Output」的模式，并不适合真实的 Agent 评估。现在的 Agent 要在多轮对话、多 agent 协作、工具调用、Skill 加载等细粒度场景下被检查，NiceEval 就是为这类场景设计的：断言直接落在工具调用、消息内容、结构化输出和用量上，而不是要求你先手工准备一份 golden 测试集。
 
-像 LangFuse、BrainTrust 这类工具更偏 tracing 和监控，对「写评估用例、跑评估用例、看结果」这条路径来说太重；NiceEval 从一开始就针对这条路径做了友好的开发体验。两者也不冲突：NiceEval 能与 LangFuse、BrainTrust 共存——可以用它们做 tracing，或者把评估结果上传到两者。
+像 LangFuse、BrainTrust 这类工具更偏 tracing 和监控，对「写评估用例、跑评估用例、看结果」这条路径来说太重。NiceEval 从一开始就针对这条路径做了友好的开发体验。两者也不冲突：NiceEval 能与 LangFuse、BrainTrust 共存——可以用它们做 tracing，或者把评估结果上传到两者。
 
 ## 你可以评什么
 
@@ -85,7 +87,7 @@ NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「
 | 评估用例 | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
 | Experiment | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
 | Adapter | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
-| Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
+| Sandbox | 需要隔离工作区的 coding agent 才用得到。直连 Web Agent 不需要。 |
 | Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
 
 完整术语表见[架构概览](/zh/explanation/overview)。