niceeval 0.4.3 → 0.4.5

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

@@ -0,0 +1,79 @@
+---
+title: "让 coding agent 读结果并自主迭代"
+sidebarTitle: "Agent 反馈闭环"
+description: "NiceEval 的运行输出为 coding agent 设计:跑完直接给出 summary.json 路径,agent 读结构化结果和 artifacts,修完再跑,直到全绿。"
+---
+
+Eval 的价值在闭环:不只是人看报告,而是让 coding agent(Claude Code、Codex 等)自己跑 eval、自己读失败原因、自己改被测程序、再跑验证。NiceEval 的输出为这个循环设计——每次运行结束,CLI 直接打出结构化结果的路径,agent 不需要解析人类向的流式输出。
+
+## 一次完整的循环
+
+<Steps>
+  <Step title="跑">
+    ```bash
+    npx niceeval exp local
+    ```
+  </Step>
+  <Step title="读">
+    运行结束时 CLI 输出结构化结果入口:
+
+    ```text
+    Structured results: .niceeval/2026-07-09T10-00-00-000Z/summary.json
+    ```
+
+    `summary.json` 里每条结果带 `outcome`、失败断言明细和 `artifactsDir`。`artifactsDir` 指向该次 attempt 的 artifacts 目录:`events.json` 是完整的 agent transcript(含工具调用),`trace.json` 是执行 trace,`diff.json` 是 sandbox 里的文件改动。字段说明见[查看结果](/zh/guides/viewing-results)。
+  </Step>
+  <Step title="修">
+    先判断缺陷在哪一侧:被测程序,还是 eval 本身(断言过紧、fixture 错误、setup 缺失)。修对应的一侧,不要为了变绿而放宽断言。
+  </Step>
+  <Step title="再跑">
+    ```bash
+    npx niceeval exp local weather
+    ```
+
+    位置参数按 eval id 前缀只重跑失败的部分。已通过的 eval 会被指纹缓存跳过;`--force` 全量重跑。
+  </Step>
+</Steps>
+
+给 agent 的提示词可以直接这样写:
+
+```text
+跑 npx niceeval exp local,读输出末尾的 summary.json 和失败结果的 artifacts,
+修掉失败的 eval,再跑,直到全部通过。
+```
+
+## AGENTS.md 指引区块
+
+模型的训练数据里没有 NiceEval。`npx niceeval init` 会在项目的 `AGENTS.md` 里写入一个托管区块,告诉 agent 先读随包文档再动手:
+
+```md
+<!-- BEGIN:niceeval-agent-rules -->
+# niceeval is NOT in your training data
+
+Its APIs and conventions may differ from anything you have seen. Read the relevant
+guide in `node_modules/niceeval/docs-site/` (English at the top level, Chinese under
+`zh/`) before writing any eval, experiment, adapter, or niceeval config. After a run,
+read the `summary.json` path the CLI prints for structured results.
+<!-- END:niceeval-agent-rules -->
+```
+
+标记之外的内容不会被改动;升级 NiceEval 后重跑 `npx niceeval init` 会刷新标记之内的指引。文档随 npm 包发布在 `node_modules/niceeval/docs-site/`,agent 读到的永远是和安装版本一致的行为,而不是训练数据里的旧记忆。
+
+## 报错自带修法
+
+配置和运行期错误直接给出修法与随包文档路径,agent 读到报错就能自修,不必先搜索:
+
+```text
+Could not find niceeval.config.ts.
+Ways to fix:
+  - [init] Run `npx niceeval init` to scaffold niceeval.config.ts and evals/
+  - [cd] Run from the project root that contains niceeval.config.ts
+  Docs: node_modules/niceeval/docs-site/quickstart.mdx
+```
+
+## 从查看器转交给 agent
+
+人在 `npx niceeval view` 里看到失败时,不必手工整理上下文:
+
+- 榜单右上角的 **Copy fix prompt** 把全部失败打包成一段可直接粘给 agent 的修复 prompt——失败清单、artifacts 路径、判断与重跑步骤都在里面。
+- 打开单个 attempt 的弹窗,同名按钮只打包这一条失败,适合逐条转交。

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

@@ -0,0 +1,129 @@
+---
+title: "编写 eval: 单轮、多轮和数据集模式"
+sidebarTitle: "编写 eval"
+description: "学习如何用 defineEval 编写 NiceEval eval，包括单轮断言、多轮对话、数据驱动测试和 sandbox workspace。"
+---
+
+每个 [NiceEval](https://niceeval.com/) eval 都是一个 TypeScript 文件，默认导出 `defineEval(...)`。核心原则是：**路径即身份**、**一个文件一个 eval**、**线性书写并就地断言**。
+
+## `defineEval` 的结构
+
+```ts
+import { defineEval } from "niceeval";
+
+export default defineEval({
+  description?: string;
+  tags?: string[];
+  judge?: JudgeConfig;
+  reporters?: Reporter[];
+  timeoutMs?: number;
+  metadata?: Record<string, unknown>;
+  async test(t) { /* interactions + assertions */ },
+});
+```
+
+<Warning>
+  不要设置 `id` 或 `name`。`evals/weather/brooklyn.eval.ts` 会自动变成 ID `weather/brooklyn`。
+</Warning>
+
+## 单轮 eval
+
+```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` | 本轮工具调用 |
+
+## 多轮 eval
+
+```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）
+
+一个文件可以导出 eval 数组：
+
+```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/guides/dataset-fanout)。
+
+## Sandbox workspace
+
+Coding-agent eval 仍然是普通 `.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/guides/fixtures)。
+
+## 命名约定
+
+<CardGroup cols={2}>
+  <Card title="文件名" icon="file">
+    只有 `.eval.ts` 会被 runner 发现。
+  </Card>
+  <Card title="目录分组" 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/guides/ci-integration.mdx

@@ -0,0 +1,97 @@
+---
+title: "在 GitHub Actions 和 CI 中运行 NiceEval"
+sidebarTitle: "CI 集成"
+description: "把 NiceEval 接入 GitHub Actions 或任意 CI。eval 失败时非零退出，输出 JUnit XML，并通过缓存加速重复运行。"
+---
+
+Evals 应该和测试一样进入 CI。它们能在 PR 阶段发现 agent 行为回退，也能在 nightly job 中跟踪模型、成本和延迟变化。
+
+## 退出码
+
+默认情况下，只要存在失败的 gate，[NiceEval](https://niceeval.com/) 将以非零状态码退出。CI 中通常使用 `--strict`，让失败更明确。
+
+```bash
+npx niceeval exp ci --strict
+```
+
+## GitHub Actions 示例
+
+```yaml
+name: evals
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  evals:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npx niceeval exp ci --strict
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## 配置 secrets
+
+<Steps>
+  <Step title="在仓库中添加 secrets">
+    把 provider token 放进 GitHub Actions secrets。
+  </Step>
+  <Step title="在 workflow 中传入 env">
+    只在运行 eval 的 step 暴露必要环境变量。
+  </Step>
+  <Step title="验证变量存在">
+    用最小 eval 或 `list` / dry run 先验证配置。
+  </Step>
+</Steps>
+
+## JUnit reporter
+
+```ts
+import { defineConfig } from "niceeval";
+import { Console, JUnit } from "niceeval/reporters";
+
+export default defineConfig({
+  reporters: [Console(), JUnit(".niceeval/junit.xml")],
+});
+```
+
+CI 可以上传 JUnit XML，让失败出现在测试报告 UI 里。想把结果同时上报到 Braintrust 这类实验平台，见 [Reporter 上报](./reporters)。
+
+## 只检查发现
+
+```bash
+npx niceeval list
+```
+
+适合快速验证 eval 文件能加载、配置没有明显错误。
+
+## 缓存 `.niceeval/`
+
+可以在 CI 中缓存 `.niceeval/`，但要确保 fingerprint 覆盖了影响结果的输入。对于 nightly 基准，通常保留完整 artifacts 更有价值。
+
+## 控制并发
+
+```bash
+npx niceeval exp ci --max-concurrency 2
+```
+
+标准 GitHub-hosted runner 上，sandbox eval 并发不宜过高。远程 HTTP eval 可以按服务限流能力调高。
+
+## 推荐模式
+
+<CardGroup cols={2}>
+  <Card title="PR runs" icon="code-pull-request">
+    只跑关键 eval 和高风险路径，保持反馈快。
+  </Card>
+  <Card title="Nightly 全量矩阵运行" icon="moon">
+    运行完整 experiment，记录 pass rate、成本和延迟趋势。
+  </Card>
+</CardGroup>

package/docs-site/zh/guides/connect-otel.mdx

@@ -0,0 +1,208 @@
+---
+title: "OTel 接入"
+sidebarTitle: "OTel 接入"
+description: "把应用已经在发的 OTel span 也发给 NiceEval 一份，niceeval view 里就有每轮的调用瀑布图。断言不从这里来——接好 send 那一刻断言就齐了。"
+---
+
+先说清这条接入**不**改变什么：断言。`t.calledTool`、`t.maxTokens`、耗时这些判决的依据，全部来自你的 adapter 在 `send` 里返回的 `Turn`（`events` + `usage`）——接好 send 的那一刻，全套断言就齐了，和 OTel 没有关系（见[接入你的 agent](/zh/guides/connect-your-agent)）。
+
+OTel 接入买到的是另一样东西：**`niceeval view` 里的调用瀑布图**。应用内部每次模型调用、每次工具执行、各自的耗时和 token，按轮铺开成一条时间线——失败的 eval 为什么失败、慢的轮次慢在哪一步，经常一眼就在瀑布图里。
+
+如果你的应用已经在发 OTel trace——AI SDK 的 telemetry、LangGraph 的 LangSmith 导出、OpenLLMetry / OpenInference 自动埋点，或自己按 GenAI 语义埋的点——那瀑布图的数据你已经在生产了：让应用把 span 也发给 [NiceEval](https://niceeval.com/) 一份即可，应用代码一行不改，仍是无侵入（见 [Tier](/zh/concepts/tier)）。
+
+## 原理（一段话）
+
+[NiceEval](https://niceeval.com/) 运行时起一个本机 OTLP 接收器，应用把 span 发过来；每轮 `send` 收到的 span 归属到那一轮，归一成 GenAI 语义后写进 `EvalResult.trace`，跑完 `npx niceeval view` 就是瀑布图。**span 只进瀑布图，不进事件流、不喂断言**——埋点缺一块、span 迟到或丢批，只影响瀑布图的完整性，不影响任何判决。
+
+## 接法
+
+**1. adapter 侧**——`send` 照常写（事件映射还是你的映射），只多一行：把本轮的 `traceparent` 随请求带过去：
+
+```ts
+// agents/support-bot.ts
+import { defineAgent } from "niceeval/adapter";
+
+export default defineAgent({
+  name: "support-bot",
+  async send(input, ctx) {
+    // 示例地址：换成你自己 agent 的真实端点
+    const r = await fetch("http://localhost:5188/chat", {
+      method: "POST",
+      // traceparent 随请求带过去:本轮 span 挂到 NiceEval 的 trace 下,并发下归属才精确
+      headers: { "content-type": "application/json", ...ctx.telemetry?.headers },
+      body: JSON.stringify({ message: input.text, model: ctx.model }),
+      signal: ctx.signal,
+    });
+    const body = await r.json();
+    return {
+      status: r.ok ? "completed" : "failed",
+      events: mapToEvents(body),   // 断言的依据在这里,和没接 OTel 时一样
+    };
+  },
+});
+```
+
+内置件不用做这件事：`uiMessageStreamAgent` 总会自动把 `ctx.telemetry.headers` 并入请求头。
+
+**2. 端点怎么交给应用**——[NiceEval](https://niceeval.com/) 的接收端点是**启动期配置，不从 send 传**（标准 OTel SDK 也做不到"运行时换端点"：`OTEL_*` 环境变量只在进程启动时读一次）。按部署形态选：
+
+- **你自己长驻的服务（最常见）**：用**固定端口模式**，在 `niceeval.config.ts` 里钉住接收端口——写了这个配置就等于打开了 OTel 接入：
+
+  ```ts
+  // niceeval.config.ts
+  export default defineConfig({
+    telemetry: { port: 4318 },   // 接收器固定监听 http://localhost:4318/v1/traces
+  });
+  ```
+
+  服务启动时一次性配 `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces`，之后跑多少次 eval 都不用改。代价：端口共享意味着同一台机器同时只能跑一个 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 接收的唯一入口，不读环境变量。
+
+- **子进程 / 由 [NiceEval](https://niceeval.com/) 拉起的进程**（CLI 型 agent）：什么都不用做。`ctx.telemetry.env`（标准 `OTEL_*` 环境变量，ready-to-spread）注入进程环境，每次 run 是新进程、读到新端点。
+
+**3. 应用侧**——按你的埋点生态各自几行配置：
+
+<Tabs>
+  <Tab title="AI SDK">
+    推荐官方 OTel 集成（`@ai-sdk/otel`，产标准 GenAI 语义）；老的 `experimental_telemetry`（`ai.*`）也能画：
+
+    ```ts
+    import { generateText } from "ai";
+
+    const result = await generateText({
+      model, tools, messages,
+      experimental_telemetry: { isEnabled: true },
+    });
+    ```
+
+    exporter 走标准 OTel Node SDK，endpoint 指向 [NiceEval](https://niceeval.com/)（注入的 env 或固定端口）。可跑示例：应用侧埋点见 [`examples/zh/origin/ai-sdk-v7`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/origin/ai-sdk-v7)（`src/backend/otel.ts`，官方 `@ai-sdk/otel`），接入后的完整评测项目见 [`examples/zh/tier1/ai-sdk-v7`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/tier1/ai-sdk-v7)。
+  </Tab>
+  <Tab title="LangGraph / LangChain">
+    零依赖路线，三个环境变量：
+
+    ```bash
+    LANGSMITH_TRACING=true \
+    LANGSMITH_OTEL_ENABLED=true \
+    LANGSMITH_OTEL_ONLY=true \
+    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces \
+    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)。
+  </Tab>
+  <Tab title="OpenLLMetry">
+    ```ts
+    import * as traceloop from "@traceloop/node-server-sdk";
+
+    traceloop.initialize({ disableBatch: true });
+    // endpoint 用标准 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量
+    ```
+  </Tab>
+  <Tab title="OpenInference">
+    ```python
+    from openinference.instrumentation.langchain import LangChainInstrumentor
+    from phoenix.otel import register
+
+    register()  # 或标准 OTel SDK;endpoint 走 OTEL_EXPORTER_OTLP_ENDPOINT
+    LangChainInstrumentor().instrument()
+    ```
+  </Tab>
+  <Tab title="自己埋的 gen_ai">
+    按 [OTel GenAI 语义约定](https://opentelemetry.io/docs/specs/semconv/gen-ai/)埋：模型调用 span 名 `chat {model}`，工具 span 名 `execute_tool {tool}`，属性带 `gen_ai.operation.name`、`gen_ai.tool.name` / `gen_ai.tool.call.id`。这是 [NiceEval](https://niceeval.com/) 归一的目标语义，画出来的瀑布图最完整。
+  </Tab>
+</Tabs>
+
+## span 怎么归属到轮
+
+并行跑多条 eval 时，同一个接收器会同时收到多条会话的 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 后端？双发，不用换
+
+应用多半已经把 trace 发给自己的观测后端（Langfuse / SigNoz / 生产 collector）。接 [NiceEval](https://niceeval.com/) **不需要换后端、也不需要第二套埋点**：TracerProvider 支持挂多个 SpanProcessor——同一批 span，两个出口：
+
+```ts
+// instrumentation.ts —— 应用启动时初始化一次:一份埋点,两个出口
+import { NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+
+export const provider = new NodeTracerProvider({
+  spanProcessors: [
+    // 出口 1:你自己的后端,一直发
+    new SimpleSpanProcessor(new OTLPTraceExporter({ url: process.env.MY_COLLECTOR_URL })),
+    // 出口 2:NiceEval。线上没有这个变量时,这个出口根本不存在——线上线下同一份代码
+    ...(process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+      ? [new SimpleSpanProcessor(new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT }))]
+      : []),
+  ],
+});
+provider.register();
+```
+
+不方便改应用代码的话，OTel Collector 扇出——应用只发给 collector，collector 配两个 exporter（你的后端 + [NiceEval](https://niceeval.com/) 的固定端点）。代价是多运维一个组件。
+
+## 瀑布图画得准不准：映射到位什么，就亮起什么
+
+[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` | 按**工具执行**着色分类 |
+| `gen_ai.operation.name: "invoke_agent"` / `"create_agent"` | 按**子 agent** 着色分类 |
+| 属性 `call_id` = 你 send 事件里的 `callId` | 该工具 span 自动补上真实入参/出参（`io.input` / `io.output`，从 send 返回的事件按 callId join 过来——很多埋点默认不采内容，这条路不受影响） |
+| span 状态 = error | 红色标错 |
+| 什么都没给（归一成 `other`） | 时间线还在；大 trace（>150 span）时按内部噪声折叠掉 |
+| 其余属性 | 原样保留，view 里点开下钻 |
+
+应用直接按 GenAI semconv 埋点（上文「自己埋的 gen_ai」tab）时这一切自动成立；主流格式（AI SDK、LangSmith、OpenLLMetry / OpenInference）的常见形状也在通用兜底的识别范围内。
+
+### 私有埋点：自己写映射
+
+埋点是应用私有形状、通用兜底认不出时，两条路：
+
+- **改埋点（推荐）**：在应用侧给 span 补一个 `gen_ai.operation.name` 属性——一行改动，你自己的观测后端也同样受益。
+- **写 `spanMapper`**：不方便动应用时，在 agent 上声明一个纯函数，渲染前把私有 span 翻成上表的语义。`tagSpan`（把判定写回 span，原有属性只增不改）和 `heuristicTag`（通用兜底判定）都从 `niceeval/adapter` 导出：
+
+```ts
+import { defineAgent, tagSpan, heuristicTag } from "niceeval/adapter";
+import type { TraceSpan } from "niceeval";
+
+function mapMySpans(spans: TraceSpan[]): TraceSpan[] {
+  return spans.map((span) => {
+    // 私有命名 → 标准语义: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 过来
+      const attributes = { ...span.attributes, call_id: String(span.attributes?.["my.callId"] ?? "") };
+      return tagSpan({ ...span, attributes }, { op: "execute_tool", kind: "tool" });
+    }
+    return tagSpan(span, heuristicTag(span));   // 其余交给通用兜底
+  });
+}
+
+export default defineAgent({
+  name: "my-bot",
+  spanMapper: mapMySpans,
+  async send(input, ctx) { /* 同上文接法 */ },
+});
+```
+
+内置的 `mapCodexSpans`（同样从 `niceeval/adapter` 导出）就是一个现成的 spanMapper 实现，可当参考。spanMapper 是纯观测代码：写错了最多瀑布图着色不对，断言不受任何影响。
+
+## 边界
+
+- **断言相关的一切都在 send**。想断工具调用，把它映射进 `events`（官方转换器或手写映射，见[写 send](/zh/guides/write-send)）；想断 usage，`send` 返回里带上。不存在"span 里有、events 里没有，于是断言看 span"的路径。
+- **多轮会话、HITL 不归 span 管**。span 没有"等人输入"语义，会话续接也是应用协议的事——这两样照常在 `send` 里做（会话续接见[写 send](/zh/guides/write-send)，HITL 概念见 [HITL](/zh/concepts/hitl)）。
+- **收不到 span 会有提示**。整轮 0 span 通常是端点没接上（env 没注入、服务没重启），[NiceEval](https://niceeval.com/) 会在日志里提示；瀑布图为空，断言照常判。
+
+## 相关阅读
+
+- [接入你的 agent](/zh/guides/connect-your-agent) —— 断言从哪来：send 的事件映射。
+- [写 send](/zh/guides/write-send) —— 手写 adapter 的完整教程，第六步就是本页的 adapter 侧接法。
+- [事件流参考](/zh/reference/events) —— 断言消费的事件长什么样。