niceeval 0.9.0 → 0.10.0

package/docs-site/zh/tutorials/agent-onboarding.mdx

@@ -0,0 +1,100 @@
+---
+title: "Coding Agent 从零接入项目"
+sidebarTitle: "Coding Agent 从零接入"
+description: "给 Coding Agent 的完整接入流程：探索项目、与用户确认路径、配置 Judge、写出 Adapter / Experiment / 评估用例并跑通第一个实验。"
+---
+
+这一页是 Coding Agent 把 NiceEval 接入一个项目的执行步骤。前提：`niceeval` 依赖已经装进项目、`niceeval init` 已经运行，你是从随包 `INDEX.md` 进入本页的。用用户的语言与用户交流；所有 API、字段和 CLI 行为以随包文档为准，不要凭训练记忆现编。
+
+## 第 1 步：探索项目，再和用户确认
+
+这一步决定后面整条路径。**先自己读代码探明，把探到的结论列给用户核对，探不到的再提问**——不要一上来就抛一串问题，也不要没探就假设。要探明的信息：
+
+1. **这是个什么 Agent**：读 README、`package.json` 依赖、路由和 agent loop 代码，判断它是用什么写的（AI SDK、LangGraph、OpenAI Agents SDK、Claude Agent SDK、自研 loop……），核心用例是什么（客服？SQL？编码任务？）。
+2. **前端和 Agent 怎么通信**：HTTP 还是 gRPC / WebSocket？协议是标准的还是自己实现的——AI SDK UI Message Stream、OpenAI Responses / Chat Completions 这类标准协议，还是 SDK 原生事件流透传，还是用户自定义的 JSON/SSE 帧？这直接决定 Adapter 是用内置的（零映射）还是手写 `send`（要自己写事件映射）。
+3. **后端有没有接 OTel**：搜有没有 OTel SDK 初始化、AI SDK telemetry、LangSmith / OpenLLMetry / OpenInference 这类埋点。已经有的话 Tier 2 几乎零成本。
+4. **用户自己有没有做 A/B Test / feature flag**：应用里已有变体开关的话，Experiment 的 `flags` 可以直接透传给它（Tier 3 的现成入口）。
+5. **Judge 用什么**：语义评分（`t.judge.autoevals.*`）要一个**与被测 Agent 分离的 Judge 模型**，走 OpenAI 兼容的 `/chat/completions` 协议——OpenAI 官方、DeepSeek、任何兼容该协议的网关都行。问用户手上有哪个服务的 key、想用什么 Judge 模型（没有内置默认模型，必须显式指定）。用户暂时没有 key 也不阻塞：Judge 断言会静默跳过，先用精确断言跑通。
+6. **是不是 Agent 本体要进 Sandbox**：被测对象是 coding agent CLI、或给 coding agent 写的 Skill/Plugin/Hook/MCP server（要在隔离 workspace 里改文件/跑命令）的话，必须走 Sandbox，不能像 HTTP 服务那样直接 `send`。默认建议 `dockerSandbox()`，但**要先跟用户确认**——本机/CI 有没有 Docker、要不要 Vercel Sandbox 或其它远程 Provider；用户没有异议就默认走 Docker。Provider 只能写在代码里（Experiment 或 `niceeval.config.ts` 的 `sandbox` 字段），没有 CLI flag，也不会自动探测——见[选择 Sandbox Provider](/zh/tutorials/sandbox-providers)。
+
+探完之后，向用户**介绍接入等级**并给出推荐（详见[接入等级](/zh/explanation/tier)）：
+
+- **Tier 1（只接 send）**：应用一行不改，全套断言（文本、Judge、多轮、工具、HITL）都在这一档。
+- **Tier 2（send + OTel）**：应用把 OTel span 也发 NiceEval 一份，换 `niceeval view` 的调用瀑布图；已有埋点（第 3 点探到的）就零改动。
+- **Tier 3（侵入改造 + flags）**：把应用内部变体暴露成 `flags` 做 feature A/B；已有 A/B 开关（第 4 点探到的）就是现成入口。
+
+**默认推荐先 Tier 1 跑通，再升 Tier 2**——尤其当第 3 点探到应用已有 OTel 时，明确告诉用户「升 Tier 2 只是把 span 多发一份，成本接近零」。Tier 3 只在用户明确要做变体对比时提。
+
+按探明的形态挑对应文档，不要在没读的情况下直接开始写 Adapter：
+
+| 被测对象 | 去读 |
+|---|---|
+| 用 Vercel AI SDK（`useChat` 后端）写的应用 | [内置 Agent 参考](/zh/reference/builtin-agents)：内置 `uiMessageStreamAgent` 无侵入接入，不用手写事件映射 |
+| coding agent CLI（claude-code / codex / bub 等改文件的任务） | [在 Sandbox 中评测 Agent](/zh/tutorials/sandbox-agent)：要配 `sandbox`，默认 `dockerSandbox()`，先跟用户确认 Provider |
+| 给 Claude Code / Codex 写的 Skill、Plugin、Hook 或 MCP server | [评测 Coding Agent 扩展](/zh/examples/coding-agent-extensions)：同样跑在 Sandbox 里，Provider 确认方式同上 |
+| 其它自研 agent loop、LangGraph、OpenAI Agents SDK、已部署 Agent | [接入自己的 Agent](/zh/tutorials/connect-your-agent) 起步，手写 `send` 的完整教程在[编写 send](/zh/tutorials/write-send) |
+| 纯函数、没有独立服务的场景 | 先读[接入自己的 Agent](/zh/tutorials/connect-your-agent) 里「为什么不直调」那段，跟用户确认这确实是他们要的边缘用法，再继续 |
+
+## 第 2 步：配置 Judge
+
+把第 1 步问到的 Judge 服务配上。Judge 走 **OpenAI 兼容的 `/chat/completions`** 协议，在 `niceeval.config.ts` 里配：
+
+```ts
+import { defineConfig } from "niceeval";
+
+export default defineConfig({
+  judge: {
+    model: "gpt-5.4-mini",                // 必填：没有内置默认模型
+    // 用非 OpenAI 官方的兼容服务（DeepSeek、网关等）时再加这两项：
+    // baseUrl: "https://api.deepseek.com/v1",
+    // apiKeyEnv: "DEEPSEEK_API_KEY",     // key 从这个环境变量读；不配默认读 OPENAI_API_KEY
+  },
+});
+```
+
+两个要提醒用户的点：
+
+- **key 解析不到时 Judge 断言会静默跳过**（不报错、不记分）——评估用例全绿不代表 Judge 真的跑了。所以配完先跑一条带 `t.judge` 的评估用例，在 `niceeval view` 里确认有 Judge 分数。
+- Judge 模型要**与被测 Agent 分离**，避免同一个模型给自己打分。模型解析优先级（单次调用 → 评估用例级 → 全局配置）和三种评分形状见 [Judge](/zh/explanation/judge)，`judge` 字段全集见 [defineConfig 参考](/zh/reference/define-config)。
+
+## 第 3 步：写三件套
+
+按第 1 步选中的方向读完对应文档后，依次写：
+
+1. **Adapter**（`agents/*.ts` 或用户项目里约定的目录）——只填 `defineAgent` 的 `send`，配置走工厂参数，不写死、不读 `process.env`。契约见 [Adapter](/zh/explanation/adapter)，API 签名见 [defineAgent 参考](/zh/reference/define-agent)，事件映射见[事件参考](/zh/reference/events)。
+2. **Experiment**（`experiments/*.ts`）——引用上面的 Adapter，声明 `model`、`flags`、`runs` 等。模型对比写两个实验文件，各自钉一个 `model`；`evals: (eval) => boolean` 决定各自运行哪些评估用例。路径只负责 id 和批量运行，报告读取每份快照的 `selectedEvalIds`。
+3. **评估用例**（`evals/*.eval.ts`）——**先探明这个应用是干嘛的，再写一条贴着它真实功能的评估用例**：读它的 README、路由、工具定义或系统提示，找出它的核心用例（客服机器人就问一条真实的客服问题、SQL agent 就给一个真实的查询任务），拿这个用例做第一条评估用例的输入和断言，不要写「你好」这种和应用无关的占位输入。形式上仍从最小写起：一句输入，`t.succeeded()` + 一个针对预期回答的内容断言，跑通再加断言密度。写法见[编写评估用例](/zh/tutorials/authoring)，断言与评分见[评分指南](/zh/tutorials/scoring-guide)，签名见 [defineEval 参考](/zh/reference/define-eval)。
+
+参数怎么从 Experiment 流到 Adapter、静态配置和每轮动态值怎么分（工厂参数 vs `ctx`），见[接入自己的 Agent](/zh/tutorials/connect-your-agent)。
+
+架构上有两条硬规则，写 Adapter 时不要违反：
+
+- **不做进程内直调**。就算 agent runtime 和评估用例在同一个代码库里，Adapter 也要走 HTTP（或对应传输层），不要把 `fetch` 换成直接 `import` 被测函数——原因见[接入自己的 Agent](/zh/tutorials/connect-your-agent) 里「为什么不直调」。
+- **评估用例侧不代管被测进程**。不 spawn 应用、不另开端口；应用由用户自己按平时的方式启动（`pnpm dev` 之类），Adapter 连不上时报「先起应用」这类明确的错误，不要自己起服务。
+
+## 第 4 步：跑通并验证
+
+```sh
+<包管理器> exec niceeval exp models   # 按路径运行两个模型配置
+<包管理器> exec niceeval view                 # 查看器里看对比结果
+```
+
+按 [Coding Agent 反馈闭环](/zh/tutorials/agent-feedback-loop)用 `niceeval show`、`--transcript`、`--trace` 和 `--diff` 完成运行、观察、修改和重跑；查看器用法见[查看结果](/zh/tutorials/viewing-results)。没跑通分三类定位：`fetch` 直接抛错 → 应用没起来或 URL 不对；`t.succeeded()` 不过 → 应用回了非成功状态；只有内容断言不过 → 接入已经通了，调断言或调应用。
+
+## 第 5 步：收尾，告诉用户做了什么
+
+跑通之后先总结，再谈下一步。总结要说清：接了什么被测对象、生成了哪几个文件（Adapter / Experiment / 评估用例各在哪）、`niceeval exp compare-models` 和 `niceeval view` 怎么跑、第一次运行的结果是什么样。不要在没被要求的情况下顺手重构用户已有代码，也不要在这几个文件之外新增抽象。
+
+## 第 6 步：问用户要不要往深了接
+
+总结完之后，把还能往深接的选项列给用户——每一项都说清**能做什么、大概改多少代码、买到什么好处**，让用户自己选，不要自作主张多做：
+
+| 能做什么 | 改动量 | 好处 | 文档 |
+|---|---|---|---|
+| 工具调用断言（`t.calledTool()` 等） | 只改 Adapter：把应用响应映射成标准事件流，约 10–30 行映射代码 | 评估用例能断言「Agent 有没有调对工具、参数对不对」，不再只看最终回复 | [编写 send](/zh/tutorials/write-send)、[事件参考](/zh/reference/events) |
+| 多轮对话、会话隔离 | 只改 Adapter：接上 `ctx.session`（`history()` 或 `id` + `capture()`），几行到十几行 | 评估用例能写多轮场景、`t.newSession()` 验证会话间不串味 | [驱动多轮交互](/zh/explanation/drive)、[编写 send](/zh/tutorials/write-send) |
+| 人工审批流（HITL） | 只改 Adapter：停轮返回 `waiting` + `input.requested`，回答轮续跑，约 10–20 行 | 评估用例能覆盖「批准/拒绝之后 Agent 行为对不对」这类审批场景 | [HITL](/zh/explanation/hitl) |
+| 调用瀑布图（升 Tier 2） | 应用已有 OTel 埋点（第 1 步探过）：只是把 span 多发一份给 NiceEval，几行配置；没埋点：补一段通用 OTel 初始化 | `niceeval view` 里看到应用内部每次模型调用、工具执行的耗时和 token 时间线；不影响任何断言 | [配置 OTel](/zh/tutorials/connect-otel) |
+| feature A/B 对比（升 Tier 3） | 改应用：把变体暴露成 `flags` 可切换的配置，改动量取决于应用；已有 A/B 开关（第 1 步探过）就是现成入口 | Experiment 层面直接对比「改 prompt / 换工具集 / 开关 feature 谁更好」 | [组织 Experiment](/zh/tutorials/experiments)、[接入等级](/zh/explanation/tier) |
+
+共同点也要讲给用户：这些全是给 Adapter 或应用加增量，**已写的评估用例一行不用改**。三档投入分别买到什么、什么时候值得升级，见[接入等级](/zh/explanation/tier)。第 1 步探到应用已有 OTel 埋点的话，瀑布图那条要主动推荐——成本接近零。

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) —— 断言读取的事件结构。