niceeval 0.9.1 → 0.10.0

package/docs-site/zh/tutorials/write-experiment.mdx

@@ -0,0 +1,355 @@
+---
+title: "实验与生命周期"
+sidebarTitle: "实验"
+description: "如何写好实验。选择 Agent、传递 model 和 flags，设置 runs、预算、并发与 Sandbox，并用 setup / teardown 起停实验级共享服务。"
+---
+
+Experiment 是可签入的运行配置：同一批评估用例对着哪个 adapter、哪个模型、开哪些 flags、跑几次、预算多少，都写在 `experiments/` 里。CLI 的位置参数只负责筛评估用例，不负责临时改 agent 或运行配置。
+
+## 最小实验
+
+```ts
+// experiments/local.ts
+import { defineExperiment } from "niceeval";
+import { webAgent } from "../agents/web-agent.ts";
+
+export default defineExperiment({
+  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
+});
+```
+
+`agent` 放的是已经配置好的 agent 实例。被测系统的 URL、鉴权、协议细节通常传给 adapter 工厂；运行器不会单独保存一个 `agentConfig` 字段。
+
+## 评估不同的 System Prompt 对于 Agent 的影响
+使用 flag 机制，配置不同的 Flag，设置两个实验，对比不同 Prompt 的区别。
+
+```ts
+// experiments/concise.ts
+import { defineExperiment } from "niceeval";
+import { webAgent } from "../agents/web-agent.ts";
+
+export default defineExperiment({
+  description: "测试 V1 System Prompt",
+  agent: webAgent({
+    baseUrl: "https://staging.example.com",
+  }),
+  model: "gpt-5.4",
+  flags: {
+    promptVariant: "v1",
+  },
+  runs: 1,
+  earlyExit: true,
+  budget: 5,
+});
+```
+
+```ts
+// experiments/concise.ts
+import { defineExperiment } from "niceeval";
+import { webAgent } from "../agents/web-agent.ts";
+
+export default defineExperiment({
+  description: "测试 V1 System Prompt",
+  agent: webAgent({
+    baseUrl: "https://staging.example.com",
+  }),
+  model: "gpt-5.4",
+  flags: {
+    promptVariant: "v1",
+  },
+  runs: 1,
+  earlyExit: true,
+  budget: 5,
+});
+```
+
+
+`model` 会作为 `ctx.model` 传给 Adapter；如果你的 Agent 支持模型选择，自己构建请求
+
+`flags` 会作为 `ctx.flags` 传给 Adapter，也会作为 `t.flags` 出现在评估用例里。
+
+语义就是产品 A/B 测试里的 feature flag，应该编写 Adapter 把 Flag 发给你的 Agent，Agent 根据 Flag 切换不同的 System Prompt 或者行为。
+
+```ts
+// agents/web-agent.ts
+async send(input, ctx) {
+  await fetch(`${baseUrl}/api/turn`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      message: input.text,
+      model: ctx.model,
+      flags: ctx.flags,
+    }),
+    signal: ctx.signal,
+  });
+}
+```
+
+## 编写一组实验
+
+一个实验文件是一格配置。要比较多个模型、agent 或 flag 取值，就写多个文件；目录只负责 id：
+
+```text
+experiments/
+  prompts/baseline.ts
+  prompts/concise.ts
+  retrieval/with-retrieval.ts
+```
+
+```bash
+npx niceeval exp prompts
+```
+
+报告直接比较当前 Scope 中的这些 experiments，不需要额外分组字段。
+
+只想验证某一个配置时，把位置参数写成该配置的完整 id：
+
+```bash
+npx niceeval exp prompts/concise
+```
+
+用于逐配置排查——确认某一格改动是否达标，不用先跑完整组，也不用把其它配置文件挪出目录。
+
+## 常用字段
+
+| 字段 | 用途 |
+|---|---|
+| `agent` | 选择并配置 adapter；必填 |
+| `model` | 单个模型名，经 `ctx.model` 透传 |
+| `reasoningEffort` | 单个推理努力程度（如 `"high"`），经 `ctx.reasoningEffort` / `t.reasoningEffort` 透传，归属与 `model` 一致 |
+| `flags` | 实验条件（A/B 里的 feature flag），任意 JSON 对象，经 `ctx.flags` / `t.flags` 透传 |
+| `runs` | 每个评估用例 × 配置最多跑几次 |
+| `earlyExit` | 多次运行里通过一次就提前停止 |
+| `evals` | `"*"`、id 前缀数组，或遍历只读 eval 描述并返回 boolean 的函数 |
+| `timeoutMs` | 单个 attempt 的超时 |
+| `budget` | 这一格配置的预算上限 |
+| `maxConcurrency` | 这一格配置的并发上限 |
+| `sandbox` | sandbox agent 使用的固定 spec；spec 可带 `environments` 表按评估用例的环境 profile 换预制产物，也可以链 `.setup()` / `.teardown()` 挂环境 Hook |
+| `setup` | 实验级 Hook：整个实验只跑一次、在你自己的机器上执行，启动全部 Attempt 共享的服务（见下） |
+| `teardown` | 与 `setup` 成对的实验级 Hook：全部 Attempt 收尾后执行一次，当且仅当 `setup` 的时点已经走到（见下） |
+
+## 启动 Experiment 共享服务
+
+有些资源是「一个实验一份、所有 Attempt 共用」的：一条到内网记忆服务的隧道、一个实验专用的 mock server、一个 license 租约。这类资源写进一对实验级 Hook `setup` / `teardown`：整场至多各跑一次。`setup` 在这个实验第一个要派发的 Attempt 前执行；`teardown` 在全部 Attempt 收尾后执行（运行被中断也执行），当且仅当 `setup` 的时点已经走到才触发——`setup` 抛错同样要走到 `teardown`，收尾代码要对可能未赋值的变量做防御。上一次的结果全部被复用、这个实验一个 Attempt 都不需要真正运行时，`setup` 和 `teardown` 都不会执行：
+
+```ts
+// setup 拿到的地址、密钥放模块变量：teardown 和同文件里的 agent（每个 Attempt 都会执行、晚于 setup）直接读它。
+let tunnel: { url: string; apiKey: string; stop(): Promise<void> };
+
+export default defineExperiment({
+  agent: nowledgeAgent(() => ({ url: tunnel.url, apiKey: tunnel.apiKey })),
+  evals: ["memory/"],
+  async setup(ctx) {
+    ctx.progress({ message: "starting nowledge tunnel" });
+    tunnel = await nowledgeTunnel({ signal: ctx.signal });
+  },
+  async teardown(ctx) {
+    ctx.progress({ message: "stopping nowledge tunnel" });
+    await tunnel?.stop(); // setup 抛错也会走到这里：对可能未赋值的变量做防御
+  },
+});
+```
+
+`setup` 在跑的时候，终端的 `ACTIVE` 区会显示一行 `experiment setup · <实验 id>`，`ctx.progress(...)` 的消息就更新在这一行末尾；等它的 Attempt 计入排队数，这不是卡住。在 CI 或 agent 输出里，`setup` / `teardown` 的开始和结束各追加一行。
+
+`setup` 抛错时，这个实验的每条 Attempt 都记为 `errored`（错误码 `experiment-setup-failed`）、逐条进报告；同一批的其它实验照常跑——环境起不来不该伪装成绿，也不该连坐别人。
+
+`teardown` 里资源释放是必达底线：用 `try/finally` 包住，不管前面的观测代码是否出错都要执行。观测类动作（health probe、指标上报）只是 best-effort——给它自己的短超时、失败不要拦住释放，并在 `ctx.signal.aborted` 时直接跳过；中断路径上，一次可能挂起的观测不该挡在「拆隧道、退租约」前面：
+
+```ts
+async teardown(ctx) {
+  try {
+    if (!ctx.signal.aborted) {
+      await tunnel?.probe({ timeoutMs: 10_000 }).catch(() => {});
+    }
+  } finally {
+    await tunnel?.stop(); // 释放是必达底线，无论观测成败都要执行
+  }
+},
+```
+
+`setup` / `teardown` 只管「在你机器上、一个实验一份」的服务。要在跑 agent 前按实验在**Sandbox 里**准备环境（装二进制、预热、跨 attempt 载入和回存状态），挂在 `sandbox` 字段的 spec 上：
+
+```ts
+export default defineExperiment({
+  agent: codexAgent({ mcpServers: [mempalMcp] }),
+  sandbox: e2bSandbox({ template: "fasteval-agents" })
+    .setup(mempalSetup("codex"))        // 预检、写动态配置、预热、载入状态
+    .teardown(mempalTeardown("codex")), // 回存状态
+  maxConcurrency: 1,                    // 载入和回存之间不能并发，声明串行
+});
+```
+
+固定的 Agent CLI、系统包和大模型缓存应先做进 image/template/snapshot；`.setup()` 不应在每个 Attempt 重建同一套环境。从官方 Docker 镜像、E2B 模板或 Vercel runtime 派生预制环境的步骤见 [Sandbox Provider · 从官方基线继续构建以提速](/zh/tutorials/sandbox-providers#从官方基线继续构建以提速)。
+
+Hook 的执行时机、多 Hook 顺序和失败语义见 [Sandbox provider · 生命周期](/zh/tutorials/sandbox-providers#生命周期)。
+
+### 与 Sandbox Hook 协作
+
+实验级 Hook 起宿主机侧服务，Sandbox Hook 每个 Sandbox 把坐标写进去、收尾时回存状态——两层在同一个文件里靠模块变量衔接，时序由 runner 保证：实验级 `setup` 早于本实验任何 Sandbox Hook，Sandbox Hook 读到的变量一定已经赋好值：
+
+```ts
+// experiments/compare/claude--nowledge.ts
+import { defineExperiment } from "niceeval";
+import { e2bSandbox } from "niceeval/sandbox";
+import { nowledgeAgent, nowledgeTunnel } from "../../agents/nowledge.ts";
+import { loadMemoryState, saveMemoryState } from "../shared/memory-state.ts";
+
+let tunnel: { url: string; apiKey: string; stop(): Promise<void> };
+
+export default defineExperiment({
+  agent: nowledgeAgent(() => ({ url: tunnel.url, apiKey: tunnel.apiKey })),
+  evals: ["memory/"],
+  maxConcurrency: 1, // [载入…回存] 是临界区，声明式串行
+  sandbox: e2bSandbox({ template: "niceeval-agents" })
+    .setup(async (sandbox, ctx) => {
+      // 每沙箱一次，晚于实验级 setup：把宿主机侧坐标写进沙箱
+      await sandbox.writeFiles({
+        ".nowledge/config.json": JSON.stringify({ url: tunnel.url, apiKey: tunnel.apiKey }),
+      });
+      await loadMemoryState(sandbox, ctx.experimentId);
+    })
+    .teardown(async (sandbox, ctx) => {
+      await saveMemoryState(sandbox, ctx.experimentId); // 每沙箱回存跨 attempt 状态
+    }),
+  async setup(ctx) {
+    tunnel = await nowledgeTunnel({ signal: ctx.signal }); // 整场一次，宿主机侧
+  },
+  async teardown() {
+    await tunnel?.stop(); // 全部 Attempt 收尾后拆
+  },
+});
+```
+
+一份实验文件从上往下读就是完整的运行说明：整场一次的宿主机资源在实验级 Hook 对里；每 Sandbox 的写入与回存在 `sandbox` 链式 Hook 里，读实验级产物；agent 怎么连自己、评估用例的任务夹具各在 agent 定义与 `EvalDef` 里，不进实验文件。
+
+### 多个实验共享同一套生命周期代码
+
+对比组里常常是几个实验对着同一类基础设施——同一个记忆产品，claude 与 codex 各一格对照，起停机制完全一样。把起停写成一个**工厂函数**，返回共享同一闭包的整套件：实验级 Hook 对、给 agent / MCP 工厂读坐标的 getter、把坐标写进 Sandbox 的 sandbox Hook。每个实验文件各自调用一次工厂，同一套代码、各自的实例与坐标：
+
+```ts
+// experiments/shared/nowledge.ts —— 启停一份代码；实例、坐标每实验一份
+import type { ExperimentHookContext } from "niceeval";
+import type { SandboxHook } from "niceeval/sandbox";
+
+export function nowledgeLifecycle() {
+  let instance: string | undefined;
+  let env: { url: string; apiKey: string } | undefined;
+
+  return {
+    /** agent / MCP 工厂经它读连接信息：闭包值，setup 之后才存在 */
+    endpoint: () => env!,
+
+    async setup(ctx: ExperimentHookContext) {
+      instance = `exp-${ctx.experimentId.replace(/[^A-Za-z0-9]+/g, "-")}`;
+      ctx.progress({ message: `[nowledge] activating ${instance}` });
+      await memctl("up", instance); // 容器 + 隧道，全新记忆库
+      env = await readInstanceEnv(instance);
+    },
+
+    async teardown(ctx: ExperimentHookContext) {
+      if (!instance) return; // setup 没走到起实例就抛了：无事可扫
+      await memctl("down", instance); // 释放是必达底线
+    },
+
+    /** 每沙箱一次：把闭包坐标写进沙箱 */
+    sandboxSetup(): SandboxHook {
+      return async (sandbox) => {
+        await sandbox.writeFiles({
+          ".nowledge/env": `NMEM_URL=${env!.url}\nNMEM_API_KEY=${env!.apiKey}\n`,
+        });
+      };
+    },
+  };
+}
+```
+
+实验文件里换 agent 只换 agent 那几行，生命周期四行接完：
+
+```ts
+// experiments/compare/codex-gpt-5.4--nowledge.ts
+const nowledge = nowledgeLifecycle();
+export default defineExperiment({
+  agent: codexAgent(nowledgeCodexConfig(nowledge.endpoint)),
+  sandbox: e2bSandbox({ template: CODEX_TEMPLATE }).setup(nowledge.sandboxSetup()),
+  setup: nowledge.setup,
+  teardown: nowledge.teardown,
+  maxConcurrency: 1, // 中心化记忆库，attempt 串行累积
+});
+```
+
+两条纪律保证多个实验并发跑同一套代码不互相踩踏：
+
+- **工厂在 import 期只创建闭包，不做 I/O、不读配置**——实验文件在 `niceeval exp` 的发现阶段就会被 import，import 抛错会连累同批无关实验；所有硬失败留给 `setup`。
+- **运行时坐标活在工厂闭包里，不放模块级单例**——同批并行的两个实验各持一份，互不覆写；坐标在 `setup` 之后才存在。
+
+服务起多份太贵、必须让同批实验共享一份实例时，用「首进启动、末出关停」的引用计数代替按实验各建一份：
+
+```ts
+// experiments/shared/nowledge-shared.ts
+let refs = 0;
+let starting: Promise<void> | undefined;
+let service: { url: string; stop(): Promise<void> } | undefined;
+
+export const sharedNowledge = {
+  async setup() {
+    refs += 1;
+    starting ??= startNowledge().then((s) => { service = s; });
+    await starting; // 并发实验等同一个启动；启动失败各自抛错
+  },
+  async teardown() {
+    refs -= 1;
+    if (refs === 0) {
+      await service?.stop(); // 启动失败时 service 未赋值，防御式跳过
+      service = undefined;
+      starting = undefined;
+    }
+  },
+};
+```
+
+计数能保持平衡，靠的是成对触发规则本身：`teardown` 当且仅当同层 `setup` 时点走到过才执行、`setup` 抛错也照样配对触发 `teardown`，`refs` 不会泄漏。
+
+边界在生命周期：同批共享的服务活不过这次 run。要**跨 run** 存在的服务（先起好、连续跑多次 `niceeval exp`）仍归外部编排（`docker compose` 之类）起停，URL 经环境变量传入。
+
+## 让不同评估用例使用不同预制环境
+
+一批真实任务可能需要不同版本的运行时和依赖。评估用例用 `environment` 声明一个与 provider 无关的 profile ID；sandbox spec 的 `environments` 表再把它映射到具体模板或快照：
+
+```ts
+// evals/astropy-2021.eval.ts
+export default defineEval({
+  environment: "python-3.9-astropy-4.2",
+  async test(t) {
+    // 驱动任务并验证结果
+  },
+});
+```
+
+```ts
+// experiments/shared.ts —— 一个 provider 一张表，所有实验共用
+import { e2bSandbox } from "niceeval/sandbox";
+
+export const e2b = e2bSandbox({
+  template: "codex-default",              // 未声明 environment 的 eval 用它
+  environments: {
+    "python-3.9-astropy-4.2": { template: "codex-python39" },
+  },
+});
+```
+
+```ts
+// experiments/e2b.ts —— 实验保持一行 diff，覆盖全部 eval
+import { defineExperiment } from "niceeval";
+import { e2b } from "./shared";
+
+export default defineExperiment({
+  agent: codexAgent(),
+  sandbox: e2b,
+});
+```
+
+`environment` 是非空的稳定字符串，不是包版本约束。`environments` 表的值就是该 provider 预制产物字段的覆盖（Docker 的 `image`、E2B 的 `template`、Vercel 的 `snapshotId`）。NiceEval 在启动任何 Sandbox 前对所有选中的评估用例完成查表；某条评估用例声明的 profile 缺表项会在启动时一次性报出全部缺项。remote Agent 不创建 Sandbox，不参与查表。因为映射是随 spec 复用的数据，同一个实验能覆盖全部评估用例——分数和对比表不会因为环境不同被拆成多个实验。
+
+跨配置比较的设计建议见[实验矩阵](/zh/tutorials/experiments)。Adapter 对 `ctx.model` 和 `ctx.flags` 的用法见 [Adapter](/zh/explanation/adapter)。

package/docs-site/zh/{how-to → tutorials}/write-send.mdx

@@ -1,30 +1,30 @@
 ---
-title: "如何写好 Send"
-sidebarTitle: "如何写好 Send"
-description: "手写 Adapter 的 send 函数，一条主线七步走：发消息拿回复、接上之前的消息、记录消费、把工具解析成事件、人工介入（HITL）、接上 OTel trace、透传 experiment 的 flags。每一步只在上一步的代码上多几行，每一步解锁一组断言。"
+title: "编写 Send"
+sidebarTitle: "编写 Send"
+description: "分七步编写 Adapter 的 send 函数：发送消息、续接会话、记录用量、映射工具事件、处理人工介入（HITL）、接入 OTel trace，并透传 Experiment flags。"
 ---
 
-[Adapter](/zh/explanation/adapter) 讲了契约：`send` 传入 `TurnInput` 和 `AgentContext`，返回 `Turn`。这一页讲怎么写它——从"发一条消息拿到回复"的最小形态起步，一步一步加到完整接入。每一步只在上一步的代码上多几行，前面已有的部分在代码里用 `// ……省略` 标出；每一步末尾说明这几行解锁了哪些断言。改完任何一步都能立刻验证：把新解锁的断言写进一条 eval 重跑 `npx niceeval exp`，`niceeval view` 里能看到这一步新增的数据——多轮轨迹、用量、工具事件、待回答请求。
+[Adapter](/zh/explanation/adapter) 定义了 `send` 的契约：接收 `TurnInput` 和 `AgentContext`，返回 `Turn`。本教程从发送一条消息开始，逐步加入完整接入所需的能力。每一步只增加少量代码，已有部分以 `// ……省略` 标出；步骤末尾列出新增数据支持的断言。完成任一步后，都可以把对应断言写进评估用例，重跑 `npx niceeval exp`，再在 `niceeval view` 中检查多轮轨迹、用量、工具事件或待回答请求。
 
 三个贯穿全文的原则：
 
-- **接的位置永远是用户前端本来就在用的那个接口。** 页面调哪个端点、收什么格式，Adapter 就调哪个端点、收什么格式——不为 eval 开新接口，也不 import 应用内部代码直调函数（为什么，见[接入你的 Agent](/zh/how-to/connect-your-agent)）。
-- **你唯一真正手写的是 transport**——URL、鉴权、请求体每家本来就不一样。解析（原始返回 → 标准事件流）有官方转换器，从 `niceeval/adapter` 导出；编排（会话续接、HITL 暂停恢复）的状态槽就挂在 `ctx.session` 上，取用即可，不需要额外声明什么。
+- **连接用户前端正在使用的接口。** Adapter 调用相同端点并接收相同格式，不为评估用例新建接口，也不 import 应用内部代码直接调用函数。具体原因见[接入你的 Agent](/zh/tutorials/connect-your-agent)。
+- **只手写 transport。** URL、鉴权和请求体取决于应用。`niceeval/adapter` 提供从原始返回到标准事件流的转换器；`ctx.session` 提供会话续接与 HITL 暂停恢复所需的状态 API。
 - **运行反馈走 `ctx`，不直接写终端。** 长步骤用 `ctx.progress(...)`；需要在运行后回顾的退化或异常上下文用 `ctx.diagnostic(...)`；无法继续时抛错。不要从 Adapter 调用 `console.log/error` 或写 `process.stdout/stderr`。
 
-![一次 t.send 的完整往返：eval 调用 t.send，运行器组装 TurnInput 与 ctx，adapter 调用你的应用并返回标准事件流 Turn。](/images/agent-turn-roundtrip-zh.svg)
+![一次 t.send 的完整往返：评估用例调用 t.send，运行器组装 TurnInput 与 ctx，adapter 调用你的应用并返回标准事件流 Turn。](/images/agent-turn-roundtrip-zh.svg)
 
-## 起点：你的应用接口是什么形状
+## 确认应用接口形状
 
-[NiceEval](https://niceeval.com/) 不发明协议。你的应用大概率建在下面某种业界协议（或其变体）之上，官方件按这几种形状备齐：
+[NiceEval](https://niceeval.com/) 不定义新的应用协议。现有应用通常使用下列协议或其变体，内置转换器按这些响应形状提供：
 
-| 协议 | 谁在定义 | 一句话介绍 | 参考 |
+| 协议 | 定义方 | 说明 | 参考 |
 |---|---|---|---|
 | **Chat Completions** | OpenAI；业界事实标准，几乎所有模型服务商都提供兼容端点 | 无状态一问一答：客户端每轮发完整 `messages` 列表，一个 JSON 回来 | [API 参考](https://platform.openai.com/docs/api-reference/chat) |
 | **Responses / Open Responses** | OpenAI（Responses API）；Open Responses 是基于它的开放规范，OpenAI 发起、Hugging Face 等社区共建，用于多提供商互操作 | 有状态、面向 agent：请求带 `previous_response_id` 由服务端续接历史，`output` 数组承诺记录全过程 | [API 参考](https://platform.openai.com/docs/api-reference/responses) · [Open Responses 规范](https://www.openresponses.org/specification) |
 | **AI SDK（Vercel）** | Vercel；TypeScript 生态的事实标准 | 不是线上协议而是 SDK：`generateText` 返回完整结果，`useChat` 走它定义的 UI Message Stream 流协议 | [generateText 参考](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text) · [UI Message Stream 协议](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol) |
 
-下面的主线用一个 Chat Completions 形接口的应用（最常见的形状）从零写到完整；接口是 Responses 形或流式的，替换件在第二、四步各自给出。
+以下步骤使用 Chat Completions 形接口。Responses 形接口和流式接口的替换实现分别在第二步和第四步给出。
 
 ## 第一步：发一条消息，拿到回复
 
@@ -72,15 +72,15 @@ if (!res.requestId) {
 
 `progress` 不落盘；diagnostic 会随 Attempt 保存并可通过 locator 回顾。HTTP 连接失败或响应无法解析时直接抛错，runner 会记录错误发生在 `agent.run`，并把 Attempt 标为 `errored`。
 
-**这一步解锁**：`t.reply`、`t.messageIncludes()`、judge 的全部对话材料，以及 experiment 侧的**模型对比**（`ctx.model` 就是 experiment 声明的 `model`，运行器原样递给你、Adapter 不解释含义，只转发——不需要等到后面的步骤，也不需要应用配合做任何改造，分档见 [Tier](/zh/explanation/tier)）。
+**这一步支持**：`t.reply`、`t.messageIncludes()`、Judge 的全部对话材料，以及 Experiment 侧的**模型对比**。`ctx.model` 来自 Experiment 的 `model`；运行器原样传递，Adapter 只负责转发。接入等级见 [Tier](/zh/explanation/tier)。
 
 它有两个明显的局限：每轮都是一场全新对话（第二次 `t.send` 接不上第一次），工具调用完全看不见。后面两步各解决一个。
 
 ## 第二步：接上之前的消息
 
-运行器在会话上只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（eval 的第一轮，或 `t.newSession()` 之后）拿到一个全新的。**
+运行器在会话上只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（评估用例的第一轮，或 `t.newSession()` 之后）拿到一个全新的。**
 
-"之前的消息"怎么接，取决于应用接口的形状。业界统共两种模式，`ctx.session` 上各备了一对存取器：
+会话续接方式取决于应用接口形状。`ctx.session` 为两种常见模式分别提供一对存取器：
 
 - **客户端带全量历史**（服务端无状态，每轮发完整消息列表：Chat Completions 形是典型）→ `ctx.session.history<TMsg>()`
 - **服务端记历史**（接口收一个会话 id：Responses 形的 `previous_response_id`、各 SDK 的原生 session / thread）→ `ctx.session.id` + `ctx.session.capture(id)`
@@ -129,7 +129,7 @@ export default defineAgent({
 
 `capture` 只在还没记过 id 时落地，后端重复回传（甚至因 fork 变了）也不会覆盖正在续接的线。
 
-**这一步解锁**：多轮对话，以及 `t.newSession()` 的会话隔离。
+**这一步支持**：多轮对话，以及 `t.newSession()` 的会话隔离。
 
 ## 第三步：记录消费
 
@@ -149,7 +149,7 @@ export default defineAgent({
 
 `Usage` 的完整字段还有可选的 `cacheReadTokens` / `cacheWriteTokens`、请求次数 `requests`，以及 `costUSD`——网关回了实测成本就填它，优先于价格表估算。接口不回用量就整个不填 `usage`，其它断言不受影响。这段照抄也是过渡：下一步的官方转换器会连 `usage` 一起填好。
 
-**这一步解锁**：`t.maxTokens()` / `t.maxCost()` 评分器（`maxCost` 用 `costUSD` 或配置里的价格表估算），以及报告和 `niceeval view` 里的用量。
+**这一步支持**：`t.maxTokens()` / `t.maxCost()` 评分器（`maxCost` 用 `costUSD` 或配置里的价格表估算），以及报告和 `niceeval view` 里的用量。
 
 ## 第四步：把工具解析成事件
 
@@ -196,19 +196,19 @@ type StreamEvent =
 
 接口不是这个形状，就换对应的件：
 
-| 接口的到达形状 | 官方件 | 你写什么 |
+| 接口响应形状 | 内置实现 | 需要编写的代码 |
 |---|---|---|
-| Chat Completions 形返回 | `fromChatCompletion(res)` | 零映射 |
-| Responses 形返回 | `fromResponses(res)` | 零映射 |
-| AI SDK `generateText` 的完整结果 | `fromAiSdk(result)` | 零映射 |
-| 流式：SDK 原生事件透传（一帧一个完整单元） | `fromClaudeSdkMessages()` / `fromPiAgentEvents()` / `fromCodexThreadEvents()` | 零映射 |
-| 流式：AI SDK 的 UI Message Stream（`useChat` 协议） | `uiMessageStreamAgent()` | 零映射（整个 Agent 都是现成的，连 send 都不用写） |
+| Chat Completions 形返回 | `fromChatCompletion(res)` | 无需手写映射 |
+| Responses 形返回 | `fromResponses(res)` | 无需手写映射 |
+| AI SDK `generateText` 的完整结果 | `fromAiSdk(result)` | 无需手写映射 |
+| 流式：SDK 原生事件透传（一帧一个完整单元） | `fromClaudeSdkMessages()` / `fromPiAgentEvents()` / `fromCodexThreadEvents()` | 无需手写映射 |
+| 流式：AI SDK 的 UI Message Stream（`useChat` 协议） | `uiMessageStreamAgent()` | 无需手写 `send` 或事件映射 |
 | 流式：逐 token / 逐参数增量 | 协议方官方 reducer；没有才用 `deltaStream({ toOps })` | 一张"帧类型 → 操作"映射表 |
 | 只有最终答案 | 手写几条 events | 一条 `message` 起步（第一步就是这个档） |
 
-预设的件只到"形状"为止，不到"协议"为止——接口的到达形状统共就这几种，每种一个官方件；只有"增量流且协议方没有官方 reducer"这一种情况需要你写映射，而且写的是声明（这一帧对应哪个操作），拼接、配对、落地时机由 `deltaStream` 统一管。
+内置转换器按响应形状工作，不假设具体应用协议。只有增量流且协议方没有现成 reducer 时才需要编写映射；映射只声明每一帧对应的操作，拼接、配对和落盘时机由 `deltaStream` 处理。
 
-归一完成后，你吐哪种事件，eval 作者就能写哪族断言：
+归一完成后，你吐哪种事件，评估用例作者就能写哪族断言：
 
 | 你吐的事件 | 解锁的断言 |
 |---|---|
@@ -217,16 +217,16 @@ type StreamEvent =
 | `input.requested`（配合 status `"waiting"`） | `t.parked()`、`t.requireInputRequest()`、`t.respond()`（第五步） |
 | `thinking` / `compaction` / `error` | 对应断言与 o11y 计数 |
 
-一个如实交代：Chat Completions 这个形状**不承诺**"返回 = 全量过程记录"（应用完全可能在服务端跑完工具循环、只把最终答案吐给你），所以 `fromChatCompletion` 的返回不带完整性证明——`calledTool` 这类正断言照常可用，`notCalledTool` 这类负断言会提示不可信。Responses 形正相反：协议契约承诺 `output` 数组记录全过程，`fromResponses` 的返回自带完整性证明，负断言可信。同样零映射，可信度的差别完全来自接口形状本身。
+Chat Completions 响应**不保证包含完整过程记录**。应用可能在服务端完成工具循环，只返回最终答案。因此，`fromChatCompletion` 的返回不带完整性证明：`calledTool` 等正断言可用，`notCalledTool` 等负断言会提示证据不完整。Responses 协议要求 `output` 数组记录完整过程，`fromResponses` 的返回带完整性证明，负断言可信。两者的可信度差异来自接口契约。
 
-**这一步解锁**：`t.calledTool()`、`t.toolOrder()`、`t.maxToolCalls()`、`t.noFailedActions()` 等整族工具断言。
+**这一步支持**：`t.calledTool()`、`t.toolOrder()`、`t.maxToolCalls()`、`t.noFailedActions()` 等工具断言。
 
 ## 第五步：HITL
 
 应用中途停下来等人（工具审批、等补充信息）时，`send` 两侧各有义务：
 
 - **停轮**：返回 `status: "waiting"`，并且每个待回答的问题吐一条带稳定 `id` 的 `input.requested` 事件——`t.parked()`、`t.requireInputRequest()` 读它，回答靠这个 `id` 对位。
-- **回答轮**：eval 里的 `t.respond(...)` 到 Adapter 是**又一次普通的 `send`**（还是同一条会话线、同一份状态），人的裁决以结构化形式随 `input.responses` 到达，每条带 `requestId`、`optionId` 或 `text`（形态见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)）。Adapter 先把裁决交回应用，再接着取结果。被人拒绝的调用，`action.result` 的 `status` 置 `"rejected"` 而不是 `"failed"`——拒绝是人的决定、不是工具故障，`noFailedActions()` 不误伤。
+- **回答轮**：评估用例里的 `t.respond(...)` 到 Adapter 是**又一次普通的 `send`**（还是同一条会话线、同一份状态），人的裁决以结构化形式随 `input.responses` 到达，每条带 `requestId`、`optionId` 或 `text`（形态见[不同回答的入参](/zh/explanation/adapter#不同回答的入参)）。Adapter 先把裁决交回应用，再接着取结果。被人拒绝的调用，`action.result` 的 `status` 置 `"rejected"` 而不是 `"failed"`——拒绝是人的决定、不是工具故障，`noFailedActions()` 不误伤。
 
 "停轮时读了一半的现场"（比如一条读到一半的 SSE 流）也存在 `ctx.session` 上：停轮时 `ctx.session.hold(现场)`，回答轮开头 `ctx.session.take()` 取回——取到即清除，一次消费。
 
@@ -286,13 +286,13 @@ export default defineAgent({
 
 不需要 HITL 的接口，删掉停轮现场相关的三处（`Pending`、`hold`、开头的 `take` 分支）即可，其余不变。停轮 / 回答 / 续跑的完整心智模型见 [HITL](/zh/explanation/hitl)。
 
-**这一步解锁**：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`，以及 `calledTool(..., { status: "rejected" })` 的精确断言。
+**这一步支持**：`t.parked()`、`t.requireInputRequest()`、`t.respond()` / `t.respondAll()`，以及 `calledTool(..., { status: "rejected" })` 的精确断言。
 
 ## 第六步：接上 OTel trace
 
 应用已经埋了点（标准 OTel HTTP 服务端埋点即可）的话，接入分两半——一半是启动期配置，一半在 `send` 里。分清它们就是分清「不变的」和「每轮变的」。
 
-**端点是启动期配置，不从 send 传。** [NiceEval](https://niceeval.com/) 的 OTLP 接收地址每次运行都一样，所以它不走 `ctx`：在 `niceeval.config.ts` 里把接收端口钉住，应用启动时把自己的 OTel exporter 指向这个固定 URL，之后跑多少次 eval 都不用再改：
+**端点是启动期配置，不从 send 传。** [NiceEval](https://niceeval.com/) 的 OTLP 接收地址每次运行都一样，所以它不走 `ctx`：在 `niceeval.config.ts` 里把接收端口钉住，应用启动时把自己的 OTel exporter 指向这个固定 URL，之后跑多少次评估用例都不用再改：
 
 ```ts
 // niceeval.config.ts
@@ -307,7 +307,7 @@ export default defineConfig({
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces node server.js
 ```
 
-**send 里传的是本轮的 trace context，不是端点。** `ctx.telemetry.headers` 是运行器每轮新生成的 W3C `traceparent` 头——把它 spread 进请求，应用这一轮产生的 span 就精确挂到本轮的 trace 下，并发跑多条 eval 时归属不混。回到主线的 chat-app，`send` 里只多一行：
+**send 里传的是本轮的 trace context，不是端点。** `ctx.telemetry.headers` 是运行器每轮新生成的 W3C `traceparent` 头——把它 spread 进请求，应用这一轮产生的 span 就精确挂到本轮的 trace 下，并发跑多条评估用例时归属不混。回到主线的 chat-app，`send` 里只多一行：
 
 ```ts
     const res = await fetch(`${BASE_URL}/v1/chat/completions`, {
@@ -318,7 +318,7 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces node server.js
 
 `ctx.telemetry` 只在配置了 OTel 接入时出现，没配时 spread 一个 `undefined` 也安全，这行可以常驻。不带这个头 span 也能收到，但归属退化成时间窗口、该 agent 的轮次会降为串行——带上它是并发下归属准确的来源。
 
-**这一步解锁**：`niceeval view` 里的调用瀑布图——应用内部每次模型调用、每次工具执行的耗时与 token，按轮铺成时间线。断言不变：判定依据在前几步的事件映射里已经齐了，span 只进瀑布图、不喂断言。接收器怎么起、span 怎么归属到轮，见 [OTel 接入](/zh/how-to/connect-otel)。
+**这一步支持**：`niceeval view` 中按轮显示调用瀑布图，包括模型调用、工具执行、耗时与 token。断言仍读取前几步产生的事件；span 只用于瀑布图。接收器配置和 span 归属规则见 [OTel 接入](/zh/tutorials/connect-otel)。
 
 ## 第七步：透传 experiment 的 flags（A/B 对比）
 
@@ -345,26 +345,26 @@ export default defineExperiment({
 });
 ```
 
-两个 experiment 文件各声明一份 `flags`，`npx niceeval exp` 分别跑同一批 eval，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/explanation/tier)；`flags` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/how-to/write-experiment)。
+两个 experiment 文件各声明一份 `flags`，`npx niceeval exp` 分别跑同一批评估用例，就是一组 A/B 对比。这是三档接入里的 Tier 3（要求应用配合暴露开关），投入与回报见 [Tier](/zh/explanation/tier)；`flags` 与 `model`、`runs` 等其余 experiment 字段见[写实验](/zh/tutorials/write-experiment)。
 
-**这一步解锁**：同一批 eval 跨变体的成绩对比。
+**这一步支持**：同一批评估用例跨变体的成绩对比。
 
 ## 对照：五个 t API 到 send 的形态
 
-七步写完，回头看 eval 侧的五个驱动 API——它们到 `send` 只是同一个函数收到不同字段，没有第二个要实现的方法：
+七步写完，回头看评估用例侧的五个驱动 API——它们到 `send` 只是同一个函数收到不同字段，没有第二个要实现的方法：
 
-| eval 侧 | 到 Adapter 时 | `send` 收到什么 |
+| 评估用例 API | Adapter 调用 | `send` 输入 |
 |---|---|---|
 | `t.send(text)` | 一次 `send` | `input.text`；`ctx.session` 是这条会话线的自有状态 |
 | `t.sendFile(path, text?)` | 一次 `send` | 同上，外加 `input.files`（base64 的 `InputFile[]`）；按应用接口的方式放进请求体，不支持多模态就忽略 |
-| `t.newSession()` | 不直接触发 `send` | 开第二条会话线；该线随后第一次 `send` 拿到一份**全空的**状态——和整个 eval 的第一次 `send` 形态完全相同 |
+| `t.newSession()` | 不直接触发 `send` | 开第二条会话线；该线随后第一次 `send` 拿到一份**全空的**状态——和整个评估用例的第一次 `send` 形态完全相同 |
 | `t.respond(...answers)` | 一次**普通的** `send` | `input.text` = 回答文本；`input.responses` 逐请求一条 `{ requestId, optionId }`（自由文本回答则是 `{ requestId, text }`）；还是同一条线、同一份状态 |
-| `t.respondAll(optionId)` | 一次**普通的** `send` | 同上，每条待处理请求各一条回答；`optionId` 已在 eval 侧对每条请求校验过存在，写错直接抛，不会静默传给应用 |
+| `t.respondAll(optionId)` | 一次**普通的** `send` | 同上，每条待处理请求各一条回答；`optionId` 已在评估用例侧对每条请求校验过存在，写错直接抛，不会静默传给应用 |
 
 ## 相关阅读
 
-- [Adapter](/zh/explanation/adapter) — 契约本身：`send` 传入什么返回什么、三个接入等级、能力从哪来。
-- [接入你的 Agent](/zh/how-to/connect-your-agent) — 接入全景：最小接入、参数通道与增量地图。
+- [Adapter](/zh/explanation/adapter) — `send` 的输入、输出、三个接入等级和能力来源。
+- [接入你的 Agent](/zh/tutorials/connect-your-agent) — 最小接入、参数传递与可选能力。
 - [HITL](/zh/explanation/hitl) — 停轮等人的完整概念：握手时序与两侧义务。
-- [Drive](/zh/explanation/drive) — eval 侧视角：`t.send()`、`t.newSession()` 与 HITL 怎么用。
+- [Drive](/zh/explanation/drive) — 评估用例侧的 `t.send()`、`t.newSession()` 与 HITL 用法。
 - [Assert](/zh/explanation/assert) — 标准事件流驱动的完整断言词汇。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -64,8 +64,8 @@
       "types": "./dist/report/built-in/index.d.ts",
       "import": "./dist/report/built-in/index.js"
     },
-    "./report/react/styles.css": "./src/report/react/styles.css",
-    "./report/react/enhance.js": "./src/report/react/enhance.js"
+    "./report/react/styles.css": "./src/report/assets/styles.css",
+    "./report/react/enhance.js": "./src/report/assets/enhance.js"
   },
   "files": [
     "INDEX.md",
@@ -76,8 +76,11 @@
     "docs-site/images"
   ],
   "dependencies": {
+    "@vercel/analytics": "^2.0.1",
+    "@vercel/speed-insights": "^2.0.0",
     "autoevals": "0.0.132",
     "effect": "^3.21.4",
+    "mermaid": "^11.16.0",
     "tar-stream": "^3.1.7",
     "tsx": "^4.19.2"
   },
@@ -166,6 +169,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "niceeval": "node bin/niceeval.js",
+    "e2e": "tsx e2e/scripts/run.ts",
     "gen:diff-code": "tsx scripts/gen-diff-code.ts",
     "docs:reference": "tsx scripts/generate-reference.ts",
     "tiers:sync": "node scripts/sync-tiers.mjs sync",
@@ -174,7 +178,7 @@
     "build:report": "tsc -p tsconfig.report-build.json && node scripts/prune-report-dist.mjs",
     "build:index": "tsx scripts/generate-reference.ts --bundled-index",
     "site:dev": "cd site && node scripts/dev.mjs",
-    "site:build": "cd site && next build",
+    "site:build": "cd site && next build && cd .. && tsx scripts/submit-indexnow.ts",
     "docs:dev": "node scripts/docs-dev.mjs",
     "docs:validate": "cd docs-site && npx --yes mint@latest validate",
     "docs:links": "cd docs-site && npx --yes mint@latest broken-links --check-anchors --check-redirects"