niceeval 0.9.1 → 0.10.0

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

@@ -0,0 +1,211 @@
+---
+title: "编写评估用例: 单轮、多轮和数据集模式"
+sidebarTitle: "评估用例"
+description: "用 defineEval 编写评估用例，包括单轮对话、多轮对话、数据驱动测试、Sandbox Workspace 和评估的生命周期与 Fixture。"
+---
+
+## `defineEval` 的结构
+
+```ts
+import { defineEval } from "niceeval";
+
+export default defineEval({
+  description?: string;
+  tags?: string[];
+  judge?: JudgeConfig;
+  reporters?: Reporter[];
+  timeoutMs?: number;
+  environment?: string;
+  metadata?: Record<string, unknown>;
+  async setup(sandbox, ctx) { /* task fixture + progress/diagnostic */ },
+  async test(t) { /* interactions + assertions */ },
+});
+```
+
+## `tags` 与 `environment`
+
+```ts
+// evals/coding/fix-button.eval.ts → id: coding/fix-button
+export default defineEval({
+  description: "修复 Button 组件",
+  tags: ["coding", "frontend"],
+  environment: "node-22",
+  async test(t) { /* coding task */ },
+});
+
+// evals/research/gpu-literature.eval.ts → id: research/gpu-literature
+export default defineEval({
+  description: "在 GPU 环境检索论文",
+  tags: ["research"],
+  environment: "gpu",
+  async test(t) { /* research task */ },
+});
+```
+
+`tags` 可供 `--tag` 和 experiment 的 `evals` 谓词读取。`environment` 只声明环境 profile；具体 image / template 由 experiment 使用的 Sandbox 配置映射。
+
+## 单轮评估
+
+```ts
+import { defineEval } from "niceeval";
+import { includes } from "niceeval/expect";
+
+export default defineEval({
+  description: "Brooklyn weather query",
+  async test(t) {
+    await t.send("What's the weather like in Brooklyn today?");
+    t.succeeded();
+    t.calledTool("get_weather", { input: { city: "Brooklyn" }, count: 1 });
+    t.check(t.reply, includes("sunny"));
+  },
+});
+```
+
+`t.send()` 驱动一次交互，`t.succeeded()` 和 `t.calledTool()` 是作用域断言，`t.check()` 是立即记录的值断言。
+
+### `Turn` 对象
+
+| 属性 | 说明 |
+|---|---|
+| `turn.events` | 标准事件流，主要事实来源 |
+| `turn.data` | 结构化输出 |
+| `turn.status` | `"completed"`、`"failed"` 或 `"waiting"` |
+| `turn.usage` | token / cost 等 usage |
+| `turn.message` | assistant 文本回复 |
+| `turn.toolCalls` | 本轮工具调用 |
+
+## 多轮评估
+
+```ts
+export default defineEval({
+  description: "Draft an email, then send it on confirmation",
+  async test(t) {
+    const draft = await t.send("Draft a follow-up email.");
+    draft.succeeded();
+    t.check(draft.message, includes("Best"));
+
+    await t.send("Looks good, send it.");
+    t.calledTool("send_email");
+  },
+});
+```
+
+需要并行独立会话时，用 `t.newSession()`。
+
+## 数据驱动测试（dataset fan-out）
+
+一个文件可以导出评估用例数组：
+
+```ts
+export default rows.map((row) =>
+  defineEval({
+    description: row.task,
+    async test(t) {
+      await t.send(row.prompt);
+      t.check(t.reply, equals(row.expected));
+    },
+  }),
+);
+```
+
+生成 ID 为 `sql/0000`、`sql/0001` 等。详见 [数据驱动测试](/zh/tutorials/dataset-fanout)。
+
+## Sandbox workspace
+
+Coding-agent 评估用例仍然是普通 `.eval.ts` 文件，只是 test 里会准备 Sandbox workspace、发送任务并检查文件结果：
+
+```ts
+import { defineEval } from "niceeval";
+
+export default defineEval({
+  description: "Create a Button component",
+  async test(t) {
+    await t.sandbox.uploadDirectory("../workspaces/ts-starter");
+    await t.send("Create src/components/Button.tsx with label and onClick props.").then((turn) => turn.succeeded());
+    t.sandbox.fileChanged("src/components/Button.tsx");
+  },
+});
+```
+
+详见 [Fixtures](/zh/tutorials/fixtures)。
+
+## 输出信息
+
+`setup` 用于这条评估用例的 Fixture。第二个参数绑定到评估用例 setup 阶段；`test(t)` 里的反馈绑定到评估用例 run 阶段：
+
+```ts
+export default defineEval({
+  async setup(sandbox, ctx) {
+    ctx.progress({ message: "安装 fixture 依赖" });
+    await sandbox.runCommand("npm", ["install"]);
+  },
+
+  async test(t) {
+    t.progress({ message: "上传隐藏测试", current: 1, total: 2 });
+    await t.sandbox.uploadDirectory("../fixtures/project");
+
+    const preflight = await inspectFixture();
+    if (preflight.usedFallback) {
+      t.diagnostic({
+        code: "fixture-check-degraded",
+        level: "warning",
+        message: "Fixture 预检使用了备用检查器",
+        data: { checker: preflight.checker },
+      });
+    }
+
+    await t.send("完成任务");
+  },
+});
+```
+
+`progress` 只更新运行中的短期状态，不进入结果。`diagnostic` 会写进当前 Attempt 的 `result.json`，但不会代替断言或自动改变判定：业务结论仍用 `t.check` / `t.require` / gate；基础设施无法继续时抛出异常。
+
+## 评估的生命周期
+
+`setup(sandbox, ctx)` 准备 Fixture；配一个 `teardown(sandbox, ctx)` 收尾，两者合起来是这条评估用例的 Fixture，每个 Attempt 各执行一次。执行顺序：`setup` 在 Sandbox 生命周期 Hook 和 git 基线锚点之后、`test(t)` 之前跑；`teardown` 是 Attempt 收尾链的第一段（先评估用例 teardown，再 agent teardown，最后 Sandbox teardown），这时 Sandbox 还活着，收尾代码可以照常读 Sandbox。
+
+大多数 Fixture 不需要 `teardown`——写进 Sandbox 的起始文件、装的依赖随 Sandbox 销毁自动没了。需要 `teardown` 的是**Sandbox 外**的 Fixture：在共享外部服务里为这个 Attempt 建的临时资源（临时 repo、bucket、队列 topic），不收就泄漏。
+
+同一条评估用例的多个 Attempt（`runs` 大于 1、或同批多个实验跑同一条评估用例）并发执行且共享同一个模块，`setup` 的句柄不能放进普通模块变量——会被后一个并发 Attempt 覆写。以 `sandbox` 实例作键存取（`WeakMap`）：sandbox 与 Attempt 一一对应，天然是 per-attempt 键：
+
+```ts
+// evals/pr-review/close-stale.eval.ts
+import { defineEval } from "niceeval";
+import type { Sandbox } from "niceeval/sandbox";
+
+// 并发 Attempt 共享本模块：句柄按 sandbox 键控，不用普通模块变量
+const fixtures = new WeakMap<Sandbox, { repoUrl: string; destroy(): Promise<void> }>();
+
+export default defineEval({
+  async setup(sandbox, ctx) {
+    ctx.progress({ message: "seeding fixture repo" });
+    const fixture = await createFixtureRepo("pr-review/close-stale"); // 沙箱外的临时资源
+    fixtures.set(sandbox, fixture);
+    await sandbox.runCommand("git", ["clone", fixture.repoUrl, "workspace"]);
+  },
+  async teardown(sandbox) {
+    await fixtures.get(sandbox)?.destroy(); // setup 抛错也会进来：没建成就跳过
+  },
+  async test(t) { /* 驱动 agent 清理 stale PR，断言 */ },
+});
+```
+
+`teardown` 当且仅当这条 Attempt 走到过 `setup` 的时点才执行——`setup` 抛错不豁免，收尾代码要对可能没建成的资源做防御。`teardown` 抛错或超过 30 秒清理上限只记 `teardown-failed` 诊断，不改变这个 Attempt 已经产出的判定；要让某个收尾动作影响结论，在 `setup` / `test` 里抛错，不要指望 `teardown` 能改判。
+
+## 命名约定
+
+<CardGroup cols={2}>
+  <Card title="文件名" icon="file">
+    只有 `.eval.ts` 会被 runner 发现。
+  </Card>
+  <Card title="ID 命名空间" icon="folder">
+    `evals/billing/refund.eval.ts` 的 ID 是 `billing/refund`。
+  </Card>
+  <Card title="数据集" icon="database">
+    适合大量结构相同、输入不同的 case。
+  </Card>
+  <Card title="Sandbox workspace" icon="box">
+    适合 coding agent，需要真实文件系统、命令和 diff。
+  </Card>
+</CardGroup>

package/docs-site/zh/{how-to → tutorials}/ci-integration.mdx

@@ -1,10 +1,10 @@
 ---
 title: "在 GitHub Actions 和 CI 中运行 NiceEval"
 sidebarTitle: "CI 集成"
-description: "把 NiceEval 接入 GitHub Actions 或任意 CI。eval 失败时非零退出，输出 JUnit XML，并通过缓存加速重复运行。"
+description: "把 NiceEval 接入 GitHub Actions 或任意 CI。评估用例失败时非零退出，输出 JUnit XML，并通过缓存加速重复运行。"
 ---
 
-Evals 应该和测试一样进入 CI。它们能在 PR 阶段发现 agent 行为回退，也能在 nightly job 中跟踪模型、成本和延迟变化。
+评估用例应该和测试一样进入 CI。它们能在 PR 阶段发现 agent 行为回退，也能在 nightly job 中跟踪模型、成本和延迟变化。
 
 ## 退出码
 
@@ -55,10 +55,10 @@ jobs:
     把 provider token 放进 GitHub Actions secrets。
   </Step>
   <Step title="在 workflow 中传入 env">
-    只在运行 eval 的 step 暴露必要环境变量。
+    只在运行评估用例的 step 暴露必要环境变量。
   </Step>
   <Step title="验证变量存在">
-    用最小 eval 或 `list` / dry run 先验证配置。
+    用最小评估用例或 `list` / dry run 先验证配置。
   </Step>
 </Steps>
 
@@ -74,7 +74,7 @@ niceeval: junit=.niceeval/junit.xml
 
 退出码是第一层红绿信号；JSON、JUnit 和结果快照是完整机器接口，日志行只用于搜索和 annotation。`errored` 行带 locator、eval/experiment 身份、已知时的正式 phase，以及一层 `reason` 摘要。详细 cause、stack 和 diagnostics 保存在 Attempt 的 `result.json`，可在保留 artifact 后运行 `niceeval show @<locator>` 回顾。
 
-CLI 显式要求的 JSON/JUnit 和默认 results artifact 都是 required 输出：写入失败必须让 job 判红，不能只留 warning 后退出 0。想把结果同时上报到 Braintrust 这类实验平台，见 [Reporter 上报](./reporters)。
+CLI 显式要求的 JSON/JUnit 和默认 results artifact 都是 required 输出：写入失败必须让 job 判红，不能只留 warning 后退出 0。把结果同时上报到 Braintrust 等实验平台的配置见 [Reporter 上报](./reporters)。
 
 ## 只检查发现
 
@@ -82,7 +82,7 @@ CLI 显式要求的 JSON/JUnit 和默认 results artifact 都是 required 输出
 npx niceeval list
 ```
 
-适合快速验证 eval 文件能加载、配置没有明显错误。
+适合快速验证评估用例文件能加载、配置没有明显错误。
 
 ## 缓存 `.niceeval/`
 
@@ -94,13 +94,13 @@ npx niceeval list
 npx niceeval exp ci --output ci --max-concurrency 2
 ```
 
-标准 GitHub-hosted runner 上，sandbox eval 并发不宜过高。远程 HTTP eval 可以按服务限流能力调高。
+标准 GitHub-hosted runner 上，Sandbox 评估用例并发不宜过高。远程 HTTP 评估用例可以按服务限流能力调高。
 
 ## 推荐模式
 
 <CardGroup cols={2}>
   <Card title="PR runs" icon="code-pull-request">
-    只跑关键 eval 和高风险路径，保持反馈快。
+    只跑关键评估用例和高风险路径，保持反馈快。
   </Card>
   <Card title="Nightly 全量矩阵运行" icon="moon">
     运行完整 experiment，记录 pass rate、成本和延迟趋势。

package/docs-site/zh/{how-to → tutorials}/connect-otel.mdx

@@ -1,18 +1,18 @@
 ---
 title: "OTel 接入"
 sidebarTitle: "OTel 接入"
-description: "把应用已经在发的 OTel span 也发给 NiceEval 一份，niceeval view 里就有每轮的调用瀑布图。断言不从这里来——接好 send 那一刻断言就齐了。"
+description: "把应用已有的 OTel span 发送给 NiceEval，在 niceeval view 中查看每轮调用瀑布图；评估用例断言仍以 Send 返回的事件和用量为准。"
 ---
 
-先说清这条接入**不**改变什么：断言。`t.calledTool`、`t.maxTokens`、耗时这些判定的依据，全部来自你的 adapter 在 `send` 里返回的 `Turn`（`events` + `usage`）——接好 send 的那一刻，全套断言就齐了，和 OTel 没有关系（见[接入你的 agent](/zh/how-to/connect-your-agent)）。
+OTel 接入**不改变断言的数据来源**。`t.calledTool`、`t.maxTokens` 和耗时判定都读取 Adapter 在 `send` 中返回的 `Turn`（`events` 与 `usage`），见[接入你的 Agent](/zh/tutorials/connect-your-agent)。
 
-OTel 接入买到的是另一样东西：**`niceeval view` 里的调用瀑布图**。应用内部每次模型调用、每次工具执行、各自的耗时和 token，按轮铺开成一条时间线——失败的 eval 为什么失败、慢的轮次慢在哪一步，经常一眼就在瀑布图里。
+OTel span 用于生成 **`niceeval view` 中的调用瀑布图**。瀑布图按轮显示模型调用、工具执行、耗时和 token，帮助定位评估用例失败或轮次变慢的具体步骤。
 
 如果你的应用已经在发 OTel trace——AI SDK 的 telemetry、LangGraph 的 LangSmith 导出、OpenLLMetry / OpenInference 自动埋点，或自己按 GenAI 语义埋的点——那瀑布图的数据你已经在生产了：让应用把 span 也发给 [NiceEval](https://niceeval.com/) 一份即可，应用代码一行不改，仍是无侵入（见 [Tier](/zh/explanation/tier)）。
 
 ## 原理（一段话）
 
-[NiceEval](https://niceeval.com/) 运行时起一个本机 OTLP 接收器，应用把 span 发过来；每轮 `send` 收到的 span 归属到那一轮，归一成 GenAI 语义后写进 `EvalResult.trace`，跑完 `npx niceeval view` 就是瀑布图。**span 只进瀑布图，不进事件流、不喂断言**——埋点缺一块、span 迟到或丢批，只影响瀑布图的完整性，不影响任何判定。
+[NiceEval](https://niceeval.com/) 运行时启动本机 OTLP 接收器。应用发送的 span 会归属到对应 `send` 轮次，归一成 GenAI 语义后写入 `EvalResult.trace`，并由 `npx niceeval view` 显示为瀑布图。**span 只用于瀑布图，不进入事件流，也不参与断言**。埋点缺失、span 迟到或丢批只影响瀑布图完整性，不影响判定。
 
 ## 接法
 
@@ -44,7 +44,7 @@ export default defineAgent({
 
 内置件不用做这件事：`uiMessageStreamAgent` 总会自动把 `ctx.telemetry.headers` 并入请求头。
 
-**2. 端点怎么交给应用**——[NiceEval](https://niceeval.com/) 的接收端点是**启动期配置，不从 send 传**（标准 OTel SDK 也做不到"运行时换端点"：`OTEL_*` 环境变量只在进程启动时读一次）。按部署形态选：
+**2. 向应用提供端点。** [NiceEval](https://niceeval.com/) 的接收端点属于**启动期配置，不从 `send` 传递**。标准 OTel SDK 只在进程启动时读取一次 `OTEL_*` 环境变量。按部署形态选择配置方式：
 
 - **你自己长驻的服务（最常见）**：用**固定端口模式**，在 `niceeval.config.ts` 里钉住接收端口——写了这个配置就等于打开了 OTel 接入：
 
@@ -55,7 +55,7 @@ export default defineAgent({
   });
   ```
 
-  服务启动时一次性配 `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces`，之后跑多少次 eval 都不用改。代价：端口共享意味着同一台机器同时只能跑一个 niceeval 进程；OTel Collector 扇出场景同理指向这个固定端点。`port` 被其它进程占用时 [NiceEval](https://niceeval.com/) 会直接报错提示换一个空闲端口，不会静默失败。
+  服务启动时一次性配 `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces`，之后跑多少次评估用例都不用改。代价：端口共享意味着同一台机器同时只能跑一个 niceeval 进程；OTel Collector 扇出场景同理指向这个固定端点。`port` 被其它进程占用时 [NiceEval](https://niceeval.com/) 会直接报错提示换一个空闲端口，不会静默失败。
 
   报给应用的接收端 hostname 默认是 `127.0.0.1`；docker 型 sandbox tracing 需要 `host.docker.internal`、或配了隧道的远程接入需要别的 hostname 时，加 `host` 覆盖：`telemetry: { host: "host.docker.internal", port: 4318 }`。这两个字段是 [NiceEval](https://niceeval.com/) 里配置 OTLP 接收的唯一入口，不读环境变量。
 
@@ -86,10 +86,10 @@ export default defineAgent({
     LANGSMITH_OTEL_ENABLED=true \
     LANGSMITH_OTEL_ONLY=true \
     OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces \
-    node server.js   # 端点值按「端点怎么交给应用」一节选:注入的 env 或固定端口
+    node server.js   # 端点值按「向应用提供端点」一节选择：注入的 env 或固定端口
     ```
 
-    `LANGSMITH_OTEL_ONLY` 表示只发 OTLP、不发 LangSmith 云端（要双发就去掉它）。这句话在 **Python** 版 `langsmith` SDK 上是真·零代码（import 时自动挂 OTel hook）；**JS** 版（`langsmith@0.7.x`）还需要显式调用一次 `initializeOTEL()`（来自 `langsmith/experimental/otel/setup`），否则只打警告、不产生 span——三个环境变量本身仍然不变。可跑示例（Python 后端，零接线代码）：[`examples/zh/origin/langgraph`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/langgraph)；接入后的完整评测项目见 [`examples/zh/tier1/langgraph`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/langgraph)。
+    `LANGSMITH_OTEL_ONLY` 表示只发 OTLP、不发 LangSmith 云端；需要双发时移除该变量。**Python** 版 `langsmith` SDK 会在 import 时自动注册 OTel hook。**JS** 版（`langsmith@0.7.x`）还需要显式调用 `langsmith/experimental/otel/setup` 导出的 `initializeOTEL()`，否则只输出警告，不产生 span。三个环境变量保持不变。Python 后端示例见 [`examples/zh/origin/langgraph`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/langgraph)，完整评测项目见 [`examples/zh/tier1/langgraph`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/langgraph)。
   </Tab>
   <Tab title="OpenLLMetry">
     ```ts
@@ -113,16 +113,16 @@ export default defineAgent({
   </Tab>
 </Tabs>
 
-## span 怎么归属到轮
+## 把 span 归属到 Turn
 
-并行跑多条 eval 时，同一个接收器会同时收到多条会话的 span，[NiceEval](https://niceeval.com/) 按两条路把它们归到各自的轮：
+并行跑多条评估用例时，同一个接收器会同时收到多条会话的 span，[NiceEval](https://niceeval.com/) 按两条路把它们归到各自的轮：
 
 - **traceparent（推荐，并发安全）**：`send` 发请求时把 `ctx.telemetry.headers`（W3C trace context，每轮一个新 `traceparent`）spread 进请求头。应用的埋点支持 context 传播的话（标准 OTel HTTP 服务端埋点都支持），本轮 span 自动挂到 [NiceEval](https://niceeval.com/) 给的 trace 下，按 traceId 精确归属。
 - **时间窗口（兜底）**：应用不传播 trace context 时，按 send 前后的时间窗归属。窗口只在串行下可靠，所以这种情况 [NiceEval](https://niceeval.com/) 会把这个 agent 的轮次串行执行并在日志里提示，不会静默混流；一旦确认 traceparent 生效，自动恢复并发。
 
 应用侧要及时导出：瀑布图在意的是"这一轮的 span 及时到齐"，用 `SimpleSpanProcessor`（或每轮 flush）——`BatchSpanProcessor` 的缓冲会让 span 跨轮迟到，瀑布图偶发缺尾巴多半是它。
 
-## 已经有自己的 OTel 后端？双发，不用换
+## 保留现有 OTel 后端并双发
 
 应用多半已经把 trace 发给自己的观测后端（Langfuse / SigNoz / 生产 collector）。接 [NiceEval](https://niceeval.com/) **不需要换后端、也不需要第二套埋点**：TracerProvider 支持挂多个 SpanProcessor——同一批 span，两个出口：
 
@@ -146,11 +146,11 @@ provider.register();
 
 不方便改应用代码的话，OTel Collector 扇出——应用只发给 collector，collector 配两个 exporter（你的后端 + [NiceEval](https://niceeval.com/) 的固定端点）。代价是多运维一个组件。
 
-## 瀑布图画得准不准：映射到位什么，就亮起什么
+## 用语义映射控制瀑布图内容
 
-[NiceEval](https://niceeval.com/) 画瀑布图前把每条 span 归一到 GenAI 语义，判定只看两样：`gen_ai.operation.name`（标准操作名）和归一出的 `kind`（语义角色）。对照表——你在 span 上给出什么，瀑布图上就亮起什么：
+[NiceEval](https://niceeval.com/) 在绘制瀑布图前把每条 span 归一到 GenAI 语义。映射读取 `gen_ai.operation.name`（标准操作名）和归一后的 `kind`（语义角色）：
 
-| 你在 span 上给出什么 | 瀑布图上亮起什么 |
+| Span 语义 | 瀑布图内容 |
 |---|---|
 | `gen_ai.operation.name: "chat"`（或 `text_completion` / `embeddings`） | 按**模型调用**着色分类 |
 | `gen_ai.operation.name: "execute_tool"`，或属性里有 `tool_name` | 按**工具执行**着色分类 |
@@ -178,7 +178,7 @@ function mapMySpans(spans: TraceSpan[]): TraceSpan[] {
     // 私有命名 → 标准语义:op 写进 gen_ai.operation.name,kind 定着色
     if (span.name === "my.llm.request") return tagSpan(span, { op: "chat", kind: "model" });
     if (span.name === "my.tool.exec") {
-      // 顺手把私有的调用 id 抄成 call_id,工具 I/O 就能从 send 事件里 join 过来
+      // 把私有调用 id 映射成 call_id，使工具 I/O 能与 send 事件关联
       const attributes = { ...span.attributes, call_id: String(span.attributes?.["my.callId"] ?? "") };
       return tagSpan({ ...span, attributes }, { op: "execute_tool", kind: "tool" });
     }
@@ -187,22 +187,22 @@ function mapMySpans(spans: TraceSpan[]): TraceSpan[] {
 }
 
 export default defineAgent({
-  name: "my-bot",
+  name: "my-agent",
   spanMapper: mapMySpans,
   async send(input, ctx) { /* 同上文接法 */ },
 });
 ```
 
-内置的 `mapCodexSpans`（同样从 `niceeval/adapter` 导出）就是一个现成的 spanMapper 实现，可当参考。spanMapper 是纯观测代码：写错了最多瀑布图着色不对，断言不受任何影响。
+`niceeval/adapter` 导出的 `mapCodexSpans` 是一个可参考的 `spanMapper` 实现。`spanMapper` 只影响观测展示；映射错误会导致瀑布图分类或着色不准确，不影响断言。
 
 ## 边界
 
-- **断言相关的一切都在 send**。想断工具调用，把它映射进 `events`（官方转换器或手写映射，见[写 send](/zh/how-to/write-send)）；想断 usage，`send` 返回里带上。不存在"span 里有、events 里没有，于是断言看 span"的路径。
-- **多轮会话、HITL 不归 span 管**。span 没有"等人输入"语义，会话续接也是应用协议的事——这两样照常在 `send` 里做（会话续接见[写 send](/zh/how-to/write-send)，HITL 概念见 [HITL](/zh/explanation/hitl)）。
+- **断言数据全部来自 `send`**。工具调用需要映射进 `events`（使用内置转换器或手写映射，见[编写 Send](/zh/tutorials/write-send)）；用量需要包含在 `send` 返回值中。Span 中存在但 `events` 中缺失的数据不会参与断言。
+- **多轮会话、HITL 不归 span 管**。span 没有"等人输入"语义，会话续接也是应用协议的事——这两样照常在 `send` 里做（会话续接见[写 send](/zh/tutorials/write-send)，HITL 概念见 [HITL](/zh/explanation/hitl)）。
 - **收不到 span 会有提示**。整个 run 0 span 通常是端点没接上（env 没注入、服务没重启），[NiceEval](https://niceeval.com/) 会在日志里提示；瀑布图为空，断言照常判。
 
 ## 相关阅读
 
-- [接入你的 agent](/zh/how-to/connect-your-agent) —— 断言从哪来：send 的事件映射。
-- [写 send](/zh/how-to/write-send) —— 手写 adapter 的完整教程，第六步就是本页的 adapter 侧接法。
-- [事件流参考](/zh/reference/events) —— 断言消费的事件长什么样。
+- [接入你的 Agent](/zh/tutorials/connect-your-agent) —— `send` 事件映射与断言的数据来源。
+- [编写 Send](/zh/tutorials/write-send) —— 手写 Adapter 的完整教程，第六步是本页的 Adapter 侧配置。
+- [事件流参考](/zh/reference/events) —— 断言读取的事件结构。