niceeval 0.4.4 → 0.4.6

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

@@ -0,0 +1,113 @@
+---
+title: "把结果上报到 Braintrust 与其它目的地"
+sidebarTitle: "Reporter 上报"
+description: "用内置 reporters 把 eval 结果送到 Braintrust 实验、JUnit XML 或自定义目的地。"
+---
+
+[NiceEval](https://niceeval.com/) 自己跑、自己判分；reporter 负责把结果送出去。控制台输出和 `.niceeval/` artifacts 本身就是内置 reporter，始终开启。其余 reporter 从 `niceeval/reporters` 导入，按需挂载。
+
+挂载位置有两个：
+
+- `niceeval.config.ts` 的 `reporters`：观测整次运行的每个 eval。共享目的地（比如一个 Braintrust 实验）通常写在这里。
+- 单个 eval 的 `reporters`：实例只观测引用它的 eval。多个 eval 引用同一个实例时合并观测，结果落进同一个目的地；已经写在 config 里的实例在 eval 上再列一遍也不会重复上报。
+
+## Braintrust
+
+`Braintrust(...)` 把一次运行作为一个 Braintrust experiment 上传，每个 attempt 一行。放在 config 里覆盖整次运行：
+
+```ts niceeval.config.ts
+import { defineConfig } from "niceeval";
+import { Braintrust } from "niceeval/reporters";
+
+export default defineConfig({
+  reporters: [Braintrust({ project: "weather-agent" })],
+});
+```
+
+只想上报部分 eval 时，挂在 eval 上：
+
+```ts evals/forecast.eval.ts
+import { defineEval } from "niceeval";
+import { Braintrust } from "niceeval/reporters";
+
+export default defineEval({
+  reporters: [Braintrust({ project: "weather-agent" })],
+  async test(t) {
+    await t.send("北京今天适合骑车吗?");
+    t.succeeded();
+  },
+});
+```
+
+前置条件：安装 `braintrust` 包（`npm install braintrust`，它是可选依赖，不装不影响其它功能），并设置 `BRAINTRUST_API_KEY`；需要在代码里显式传 key 时用 `apiKey` 参数。运行结束后终端会打印 experiment URL。
+
+### 上报口径
+
+- 每个 attempt 是 Braintrust 里的一行；`runs: 3` 会产生三行，靠 metadata 里的 `attempt` 区分。
+- soft 断言按名字记为 score；gate 断言记在 `gate:` 前缀下。这样在 Braintrust 的实验对比里，gate 回归和 soft 分数回归用同一套 diff 看。
+- metrics 带开始/结束时间、token 用量和估算成本；缺的数据不写，不补零。
+- metadata 带 `agent`、`model`、`experiment`、`flags`、`outcome` 和失败断言明细，方便在 Braintrust 里按维度过滤。
+
+### 配置项
+
+<ParamField body="project" type="string">
+  Braintrust 项目名。省略时用 `niceeval`。
+</ParamField>
+
+<ParamField body="projectId" type="string">
+  Braintrust 项目 id。与 `project` 给一个即可。
+</ParamField>
+
+<ParamField body="experiment" type="string">
+  实验名。省略时由 Braintrust 自动命名。
+</ParamField>
+
+<ParamField body="baseExperiment" type="string">
+  作为对比基线（diff base）的既有实验名。
+</ParamField>
+
+<ParamField body="baseExperimentId" type="string">
+  作为对比基线的既有实验 id。
+</ParamField>
+
+<ParamField body="update" type="boolean">
+  为 `true` 时更新同名既有实验，而不是新建一个。
+</ParamField>
+
+<ParamField body="metadata" type="Record<string, unknown>">
+  实验级附加 metadata，与 NiceEval 自动写入的字段合并，同名以这里为准。
+</ParamField>
+
+<ParamField body="apiKey" type="string">
+  Braintrust API key。省略时 SDK 读 `BRAINTRUST_API_KEY`。
+</ParamField>
+
+## JUnit 与 Json
+
+`JUnit(path)` 输出 JUnit XML，让失败出现在 CI 的测试报告 UI 里；临时生成可以直接用 CLI 的 `--junit <path>`，不用改配置。`Json(path)` 把完整 `RunSummary` 落成一个 JSON 文件，喂下游脚本或 dashboard。CI 场景的完整接法见[CI 集成](./ci-integration)。
+
+## 自定义 reporter
+
+reporter 是实现若干可选回调的对象，拿到的是和内置 reporter 相同的结构化结果：
+
+```ts
+import type { Reporter } from "niceeval";
+
+const notify: Reporter = {
+  async onEvalComplete(result) {
+    if (result.outcome === "failed") {
+      await fetch("http://localhost:3000/notify", {
+        method: "POST",
+        body: JSON.stringify({ eval: result.id, agent: result.agent }),
+      });
+    }
+  },
+};
+```
+
+- `onRunStart(evals, agent, shape)`：运行开始，收到本次实际要跑的 eval 列表和运行规模。
+- `onEvalComplete(result)`：每个 attempt 完成即时触发，回调串行化，不会交错。
+- `onRunComplete(summary)`：运行结束，收到聚合汇总。
+- `onEvent(event)`：更细粒度的事件流（`eval:start`、`run:budgetExceeded` 等）。
+
+reporter 抛错只会打一条诊断信息，不会让运行中断。只有目的地没被内置覆盖时才需要自定义——`.niceeval/` 的 artifacts 已经记录了全部结果，事后分析直接读它（见[查看结果](./viewing-results)）。

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

@@ -0,0 +1,82 @@
+---
+title: "NiceEval runner 如何调度和执行 eval"
+sidebarTitle: "运行器"
+description: "NiceEval runner 发现 eval，用有界并发调度，缓存结果，重试脆弱基础设施，并执行预算保护。"
+---
+
+Runner 是把 eval 文件变成一次实际运行的执行引擎。它负责发现、过滤、调度、缓存、attempt、reporters 和 artifact 输出。
+
+## 发现
+
+runner 会读取 `evals/` 下的：
+
+- `*.eval.ts` 文件
+- 导出 eval 数组的数据集文件
+
+```bash
+npx niceeval list
+```
+
+`list` 只发现和打印 ID，不执行 eval。
+
+## 过滤
+
+`exp` 命令中,实验名之后的位置参数是 eval ID 前缀：
+
+```bash
+npx niceeval exp local
+npx niceeval exp local weather
+npx niceeval exp local fixtures/button
+```
+
+不要把 agent 名放进位置参数。agent/model/flags 写进 experiment。
+
+## 并发
+
+```bash
+npx niceeval exp local --max-concurrency 8
+```
+
+远程 HTTP agent 可以用更高并发；本地 Docker sandbox 通常需要更低并发，避免 CPU、内存和磁盘竞争。
+
+## runs 与 early-exit
+
+```bash
+npx niceeval exp local fixtures/button --runs 5 --early-exit
+```
+
+`runs` 用于测 pass rate。`early-exit` 会在某个 attempt 通过后停止同一 eval 的剩余尝试。
+
+## 缓存
+
+[NiceEval](https://niceeval.com/) 可以根据输入、配置和相关文件 fingerprint 跳过已通过结果。缓存适合加速迭代，但如果你在调试非确定性行为，应该明确关闭或清理相关缓存。
+
+## 超时和预算
+
+```bash
+npx niceeval exp local --timeout 300000 --budget 5
+```
+
+超时保护单个 eval，预算保护整次运行成本。
+
+## Reporter
+
+runner 在 eval 完成后把结果交给 reporters：
+
+- console reporter 提供实时反馈。
+- JSON artifacts 用于后续分析。
+- JUnit reporter 适合 CI。
+- Braintrust reporter 把一次运行作为实验上报，跨提交比较。
+
+挂载方式和 Braintrust 配置见 [Reporter 上报](./reporters)。
+
+## 输出目录
+
+每次运行会写入 `.niceeval/<timestamp>/`，包括 `summary.json`，以及每个 attempt 的 `events.json`、`sources.json`、`trace.json`、`o11y.json` 和 `diff.json` 等拆分工件。
+
+## 推荐调试流程
+
+1. 先跑 `npx niceeval list` 确认发现结果。
+2. 用 `npx niceeval exp <实验> <ID 前缀>` 缩小到一个 eval。
+3. 失败后运行 `npx niceeval view` 查看 transcript 和 diff。
+4. 再扩大到完整 suite 或 experiment。

package/docs-site/zh/guides/sandbox-agent.mdx

@@ -0,0 +1,139 @@
+---
+title: "沙箱 Agent：评估 Claude Code、Codex 和 bub"
+sidebarTitle: "沙箱 Agent"
+description: "使用 NiceEval 内置 agents 或自定义 adapter，在 Docker 或云端 sandbox 中运行 coding-agent CLI。"
+---
+
+Sandbox agent 会在隔离环境中启动 coding-agent CLI，给它 workspace 和任务，让它自由修改文件、运行命令，然后收集 transcript、diff 和测试结果。
+
+## 内置 sandbox agents
+
+<CardGroup cols={3}>
+  <Card title="claude-code" icon="code">
+    运行 Anthropic Claude Code CLI，需要 `ANTHROPIC_API_KEY`。
+  </Card>
+  <Card title="codex" icon="terminal">
+    运行 OpenAI Codex CLI，需要 `CODEX_API_KEY`。
+  </Card>
+  <Card title="bub" icon="robot">
+    运行 bub coding agent，鉴权遵循 bub CLI 自身约定。
+  </Card>
+</CardGroup>
+
+## 运行内置 agent
+
+在 experiment 里设置 `sandbox`（或者作为项目级兜底写进 `niceeval.config.ts`），选择 [NiceEval](https://niceeval.com/) 在哪里创建隔离环境：
+
+```ts
+// experiments/local.ts
+import { defineExperiment } from "niceeval";
+import { claudeCodeAgent } from "niceeval/adapter";
+import { dockerSandbox } from "niceeval/sandbox";
+
+export default defineExperiment({
+  agent: claudeCodeAgent(),
+  model: "claude-sonnet-4-6",
+  sandbox: dockerSandbox(),
+});
+```
+
+```shell
+export ANTHROPIC_API_KEY=sk-ant-...
+npx niceeval exp local fixtures/button
+
+npx niceeval exp local fixtures/button --runs 10 --early-exit
+```
+
+<Note>
+  没有对应的 CLI flag——后端选择完全写在代码里。如果 experiment 和 `niceeval.config.ts` 都没设置 `sandbox`，[NiceEval](https://niceeval.com/) 在创建 sandbox 时会直接报错，不会自动探测。
+</Note>
+
+内置 agent 从 `niceeval/adapter` 导出的是工厂函数。需要配置鉴权、代理、MCP 或 GitHub skill 时，把这些写进工厂参数；模型仍然写在 experiment 的 `model` 字段，sandbox 后端仍然写在 `sandbox` 字段：
+
+```ts
+import { defineExperiment } from "niceeval";
+import { claudeCodeAgent } from "niceeval/adapter";
+import { dockerSandbox } from "niceeval/sandbox";
+
+export default defineExperiment({
+  agent: claudeCodeAgent({
+    apiKey: process.env.ANTHROPIC_API_KEY,
+    baseUrl: process.env.ANTHROPIC_BASE_URL,
+    maxTurns: 8,
+    mcpServers: [
+      {
+        name: "browser",
+        command: "npx",
+        args: ["-y", "@anthropic/mcp-browser"],
+      },
+    ],
+    skills: ["Effect-TS/skills"],
+  }),
+  model: "claude-sonnet-4-6",
+  sandbox: dockerSandbox(),
+});
+```
+
+## agent 环境变量
+
+| Agent | 必需变量 |
+|---|---|
+| `claude-code` | `ANTHROPIC_API_KEY` |
+| `codex` | `CODEX_API_KEY` |
+| `bub` | 遵循 bub CLI 鉴权 |
+
+## 工作流程
+
+```text
+createSandbox
+  → git init && git commit
+  → adapter.setup?                 # 装 CLI / 写 agent 配置
+  → test(t): uploadDirectory(...)   # 写入这条 eval 的起始文件
+  → adapter.send(input, ctx)
+  → test(t): runCommand(...)        # 手工运行验证命令
+  → collectGeneratedFiles()         # git diff HEAD
+  → sandbox.stop()
+```
+
+起始文件和验证命令都写在 `test(t)` 中。agent 执行阶段只能看到你已经写进 sandbox 的文件。
+
+## 自定义 sandbox agent
+
+```ts
+import { defineSandboxAgent } from "niceeval/adapter";
+
+export default defineSandboxAgent({
+  name: "my-agent",
+  async send(input, ctx) {
+    await ctx.sandbox.runCommand("my-agent", ["run", input.text, "--json-out", "agent-events.json"]);
+    const transcript = await ctx.sandbox.readFile("agent-events.json");
+    return {
+      status: "completed",
+      events: parseTranscript(transcript),
+    };
+  },
+});
+```
+
+## `ctx.model` 与 `ctx.flags`
+
+CLI 传入的模型和自定义 flags 会出现在 adapter context 中。adapter 可以决定如何把它们转成 CLI 参数或 HTTP payload。
+
+## 在 experiment 中使用自定义 agent
+
+```ts
+import { defineExperiment } from "niceeval";
+import { dockerSandbox } from "niceeval/sandbox";
+import myAgent from "./agents/my-agent";
+
+export default defineExperiment({
+  agent: myAgent,
+  model: "claude-sonnet-4-6",
+  sandbox: dockerSandbox(),
+  runs: 3,
+});
+```
+
+<Warning>
+  不要在 runner 里写 agent-specific 分支。差异行为应该放进 adapter。
+</Warning>

package/docs-site/zh/guides/sandbox-backends.mdx

@@ -0,0 +1,75 @@
+---
+title: "Sandbox 后端：Docker、Vercel 与第三方"
+sidebarTitle: "沙箱后端"
+description: "NiceEval 在 Docker 或 Vercel sandbox 中运行 coding agents。了解如何选择后端、配置权限，并通过 warm pools 改善性能。"
+---
+
+Sandbox backend 是创建和管理隔离运行环境的基础设施。[NiceEval](https://niceeval.com/) 把它们包装成同一个 `Sandbox` 接口，所以 adapter 不需要知道当前用的是本地 Docker、Vercel micro-VM 还是第三方云服务。
+
+## `Sandbox` 接口
+
+Adapter 常用操作包括：
+
+| 方法 | 用途 |
+|---|---|
+| `runCommand(cmd, args)` | 运行命令 |
+| `runShell(script)` | 运行 shell 脚本 |
+| `readFile(path)` | 读取文件 |
+| `writeFiles(files)` | 写入一组文件 |
+| `uploadFiles(files)` | 上传 workspace 或测试文件 |
+| `workdir` | 后端真实工作目录；省略的 `cwd` / `targetDir` 都解析到这里 |
+| `runCommand(..., { cwd })` | 单条命令临时切换工作目录；相对路径按 `workdir` 解析 |
+| `stop()` | 销毁环境 |
+
+## 选择后端
+
+选择后端只能写在代码里——没有对应的 CLI flag，[NiceEval](https://niceeval.com/) 也不会自动探测后端。在 experiment 里设置 `sandbox` 字段（或者在 `niceeval.config.ts` 里设置作为项目级兜底），三选一：
+
+```ts
+// experiments/local.ts
+import { defineExperiment } from "niceeval";
+import { dockerSandbox } from "niceeval/sandbox";
+
+export default defineExperiment({
+  agent: myCodingAgent,
+  model: "claude-sonnet-4-6",
+  sandbox: dockerSandbox(), // 或 vercelSandbox() / e2bSandbox()
+});
+```
+
+如果 experiment 和 `niceeval.config.ts` 都没有设置 `sandbox`，[NiceEval](https://niceeval.com/) 在创建 sandbox 时会直接报错，而不会猜一个后端。
+
+三个内置后端的 SDK 不随 NiceEval 一起安装——用哪个就装哪个，避免把用不到的依赖（以及它们的原生构建脚本）带进你的项目：
+
+| 后端 | 安装命令 |
+|---|---|
+| `dockerSandbox()` | `pnpm add dockerode @types/dockerode` |
+| `vercelSandbox()` | `pnpm add @vercel/sandbox` |
+| `e2bSandbox()` | `pnpm add e2b` |
+
+漏装时不会静默失败：NiceEval 在创建 sandbox 的那一刻报错并直接给出上面的安装命令，例如 `Docker sandbox requires 'dockerode'. Install it with: pnpm add dockerode @types/dockerode`。
+
+## Docker
+
+Docker 适合本地开发和标准 CI。优点是简单、可控、无云端依赖；缺点是机器资源有限，冷启动和安装依赖可能较慢。
+
+## Vercel Sandbox
+
+Vercel Sandbox 适合需要云端隔离、更多资源或更稳定环境的任务。需要相应 token 或 OIDC 配置。
+
+## 第三方后端
+
+只要实现 `Sandbox` 接口，就可以接入其他 sandbox provider。adapter 仍然只依赖接口，不依赖 provider 私有 API。
+
+## 权限和 root
+
+不同后端对 root 权限、网络、文件系统和进程生命周期的约束不同。编写 fixture 时尽量避免依赖宿主机环境，把依赖写进 `package.json` 或 fixture setup。
+
+## 性能建议
+
+- 减少 fixture 依赖体积。
+- 使用缓存或预热机制。
+- 控制 `sandboxConcurrency`，避免本地 Docker 资源耗尽。
+- 把慢测试拆成必要的 gate 和可选的 soft 检查。
+
+Warm pools 和复用属于 runner / scheduler 层面的能力，详见 [Runner](/zh/guides/runner)。

package/docs-site/zh/guides/scoring-guide.mdx

@@ -0,0 +1,92 @@
+---
+title: "评分指南: 断言、judge 和成本限制"
+sidebarTitle: "评分指南"
+description: "用 NiceEval 的五种评分机制评估任意 eval：值断言、作用域断言、LLM-as-judge、test-as-scoring 和效率检查。"
+---
+
+好的 eval 应该尽量把“是否成功”拆成可解释的信号。[NiceEval](https://niceeval.com/) 允许你混合精确断言、语义 judge、事件流检查和真实测试。
+
+## 选择断言类型
+
+| 目标 | 推荐机制 |
+|---|---|
+| 回复包含固定字段 | `includes` / `matches` |
+| 结构化 JSON 完全匹配 | `equals` |
+| 工具调用是否发生 | `t.calledTool` / `t.notCalledTool` |
+| 输出是否语义正确 | `t.judge.*` |
+| 代码是否工作 | `t.check(await t.sandbox.runCommand("npm", ["test"]), commandSucceeded())` |
+| 成本是否可控 | `t.maxTokens` / `t.maxCost` |
+
+## 值断言
+
+```ts
+import { includes, equals, matches } from "niceeval/expect";
+
+t.check(t.reply, includes("refund"));
+t.check(turn.data, equals({ intent: "refund" }));
+t.check(t.reply, matches(/order #\d+/));
+```
+
+值断言适合精确、稳定、低歧义的结果。
+
+## 作用域断言
+
+```ts
+t.succeeded();
+t.calledTool("search");
+t.usedNoTools();
+t.sandbox.fileChanged("src/app.ts");
+t.check(await t.sandbox.runCommand("npm", ["test"]), commandSucceeded());
+```
+
+它们检查整次运行的事实，通常来自标准事件流或 sandbox artifacts。
+
+## LLM-as-judge
+
+```ts
+t.judge.autoevals.factuality("Refunds are available within 30 days.", { on: t.reply }).atLeast(0.8);
+t.judge.autoevals.closedQA("The answer is specific, polite, and does not invent policy.", { on: t.reply }).atLeast(0.75);
+```
+
+Judge 适合语义质量，但不适合替代所有确定性断言。能精确检查的地方优先精确检查。
+
+## Gate 和 soft 的取舍
+
+```ts
+t.check(t.reply, includes("refund").gate());
+t.check(t.reply, includes("friendly tone").atLeast(0.7));
+```
+
+- `gate`：失败就是失败。
+- `soft`：保留分数，用于比较质量。
+
+## 代码任务用测试评分
+
+在 `.eval.ts` 里运行项目测试或临时探针：
+
+```ts
+import { commandSucceeded, includes } from "niceeval/expect";
+
+const testResult = await t.sandbox.runCommand("npm", ["test"]);
+t.check(testResult, commandSucceeded());
+
+const src = await t.sandbox.readSourceFiles({ extensions: ["ts"] });
+t.check(src.text(), includes(/z\.object\s*\(/));
+```
+
+## 成本和效率
+
+```ts
+t.maxTokens(25_000);
+t.maxCost(0.1);
+```
+
+对 coding agent 和长链路 agent 尤其有用，可以防止通过大量重试或工具调用掩盖质量问题。
+
+## 实用建议
+
+- 先写 1-2 个 gate，保证任务底线。
+- 再加 soft 分数比较质量。
+- 复杂语义用 judge，但让 judge 有明确 rubric。
+- coding-agent 结果尽量用真实测试验证。
+- 把失败消息写清楚，方便从报告直接定位问题。