niceeval 0.4.4 → 0.4.6

package/docs-site/zh/example/ai-agent-application.mdx

@@ -0,0 +1,152 @@
+---
+title: "评估你的 AI Agent 应用"
+sidebarTitle: "评估 AI Agent 应用"
+description: "用 direct adapter 评估一个基于 AI SDK 的通用 AI 助手应用：工具调用、图片理解和多轮会话。"
+---
+
+这个例子演示如何用 [NiceEval](https://niceeval.com/) 评估你自己的 AI Agent 应用。
+
+<Note>
+这是**完整能力版**的参考示例：会话、工具事件、tracing、模型对比、双可观测一次到位。第一次接入建议先走[接入你的 Agent](/zh/guides/connect-your-agent) 的分步路线（最小接入 → 事件流 → 多轮 → HITL → tracing），回头拿这页对照"真实项目长什么样"。
+</Note>
+
+查看示例代码：https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/ai-sdk
+
+被测对象是一个用 AI SDK tool loop 实现的【普通 AI 助手】应用：会发消息、调用工具（查天气 / 算数 / 搜索）、理解图片，并用 Langfuse 做自己的可观测。该应用在测试时不需要 sandbox —— [NiceEval](https://niceeval.com/) 通过 direct adapter 连接它。
+
+# 目录结构
+
+```text
+examples/zh/ai-sdk/
+  src/                     # 被测 web agent(POST /api/turn,内含工具 + 图片理解)
+  adapter/adapter.ts       # NiceEval adapter：工厂 webAgent({ baseUrl })
+  evals/                   # 会话型 eval
+    weather-tool.eval.ts        # 问天气 → 调 get_weather
+    image-understanding.eval.ts # 图片理解
+  experiments/
+    compare-models/        # 实验组:每文件钉一个 model
+      gpt-5.4.ts
+      deepseek-v4-pro.ts
+  niceeval.config.ts       # 注册 adapter、judge、并发
+```
+
+# 定义适配器
+
+adapter 告诉 [NiceEval](https://niceeval.com/) 怎么给 AI Agent 发请求、怎么把响应读成标准事件流。它是个工厂函数：`baseUrl`（被测 agent 跑在哪）由外面传进来，adapter 自己不写死、不读 env。
+
+```ts
+// adapter/adapter.ts
+import { defineAgent } from "niceeval/adapter";
+import type { Agent } from "niceeval/adapter";
+import type { StreamEvent } from "niceeval";
+import type { AgentEvent, AgentResponse } from "../src/protocol.ts";
+
+export function webAgent(opts: { baseUrl: string }): Agent {
+  const baseUrl = opts.baseUrl.replace(/\/$/, "");
+  return defineAgent({
+    name: "web-agent",
+    async send(input, ctx) {
+      const response = await fetch(`${baseUrl}/api/turn`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          sessionId: ctx.session.id,
+          message: input.text,
+          model: ctx.model,
+          files: input.files,
+          otelEndpoint: ctx.telemetry?.endpoint, // 双可观测：让 app 把本轮 span 也发回 NiceEval
+        }),
+        signal: ctx.signal,
+      });
+      // 同一 workspace 的共享契约,直接按 AgentResponse 读,不必当 unknown 再校验一遍。
+      const body = (await response.json()) as AgentResponse;
+      ctx.session.capture(body.sessionId);
+      return {
+        events: body.events.map(toStreamEvent),
+        data: body.data,
+        status: "completed" as const,
+      };
+    },
+  });
+}
+
+function toStreamEvent(event: AgentEvent): StreamEvent {
+  if (event.type === "action.called") return { ...event, tool: "unknown" };
+  return event;
+}
+```
+
+## 多轮消息
+
+同一条会话线里 `ctx.session.id` 自动续到下一轮；adapter 把 agent 回传的 `sessionId` 用 `ctx.session.capture()` 写回即可。需要在实验里按 feature flag 分流，见 [Experiments](/zh/guides/experiments)。
+
+# 定义评估
+
+每个 eval 发消息、断言回复 / 工具调用 / 图片理解。确定性断言（`calledTool`、`messageIncludes`）免 API key 就能跑；设了 judge key 再加开放式打分。
+
+```ts
+// evals/weather-tool.eval.ts
+import { defineEval } from "niceeval";
+
+export default defineEval({
+  description: "AI 助手:问天气调用 get_weather",
+  async test(t) {
+    const turn = await t.send("北京今天天气怎么样？");
+    turn.succeeded();
+    await t.group("调用 get_weather 且城市正确", () => {
+      t.calledTool("get_weather", { input: { city: "北京" } });
+      t.messageIncludes(/°C|气温|天气/);
+    });
+    t.judge.autoevals.closedQA("助手是否基于工具返回的天气数据作答，而不是凭空编造？").atLeast(0.7);
+  },
+});
+```
+
+图片理解的 eval 可以用 `t.sendFile()` 发送附件，adapter 会把 `input.files` 原样转发给 web agent：
+
+```ts
+// evals/image-understanding.eval.ts
+await t.sendFile(new URL("./fixtures/sample.png", import.meta.url).pathname);
+const turn = await t.send("这张图片里是什么？");
+t.messageIncludes(/猫|cat/i); // 示例图是一只猫
+```
+
+# 定义实验
+
+**一个实验文件 = 一个配置**（单 model）。跨模型对比写多个文件放进同一个实验组文件夹：
+
+```ts
+// experiments/compare-models/gpt-5.4.ts
+import { defineExperiment } from "niceeval";
+import { webAgent } from "../../adapter/adapter.ts";
+
+export default defineExperiment({
+  description: "gpt-5.4: 对比模型",
+  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
+  model: "gpt-5.4", // 单个字符串;另一个模型复制一份文件改这一行
+  runs: 2,
+  earlyExit: true,
+});
+```
+
+# 开始评估
+
+先启动被测 agent 应用（默认 mock 模式，免 API key）。这个例子是独立 npm 项目，`niceeval` 是它的依赖：
+
+```bash
+cd examples/zh/ai-sdk && pnpm install && pnpm dev
+```
+
+另开一个终端跑 eval：
+
+```bash
+cd examples/zh/ai-sdk
+pnpm exec niceeval exp compare-models   # 跑模型对比实验组
+pnpm exec niceeval exp compare-models weather-tool   # 在实验组里只跑某个 eval
+```
+
+## 下一步
+
+- [接入你的 Agent](/zh/guides/connect-your-agent) — `defineAgent` 从零跑通的教程。
+- [编写 eval](/zh/guides/authoring) — 单轮、多轮和数据集。
+- [CI 集成](/zh/guides/ci-integration) — 把 agent 回归测试放进 PR。

package/docs-site/zh/example/claude-code-codex-plugin.mdx

@@ -0,0 +1,163 @@
+---
+title: "评估你的 Claude Code / Codex 插件"
+sidebarTitle: "评估插件效果"
+description: "用 NiceEval 把 coding-agent 插件放进真实 workspace，比较有插件和无插件时的通过率、成本、耗时和行为差异。"
+---
+
+如果你在给 Claude Code、Codex 或其它 coding agent 写插件，最有价值的 eval 不是问它“会不会用插件”，而是把插件放进真实 workspace，让 agent 完成一组真实开发任务，再比较有插件和无插件时的 pass rate、耗时、成本和 diff。
+
+当前可运行示例在 [`examples/zh/coding-agent-skill`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/coding-agent-skill)。其中的 Ponytail 组就是一个插件 benchmark 迁移示例：把第三方 Ponytail skill/plugin 的 agentic benchmark 改写成 [NiceEval](https://niceeval.com/) eval，并与无插件 baseline 对比。
+
+## 目录结构
+
+```text
+examples/zh/coding-agent-skill/
+├─ niceeval.config.ts
+├─ skills/
+│  └─ ponytail.md
+├─ workspaces/
+│  └─ ts-starter/
+├─ evals/
+│  ├─ ponytail-safe-path.eval.ts
+│  ├─ ponytail-csv-sum.eval.ts
+│  └─ ponytail-reuse.eval.ts
+└─ experiments/
+   ├─ ponytail.ts
+   └─ ponytail-baseline.ts
+```
+
+- `skills/ponytail.md` 是要注入给 agent 的插件/skill 内容。
+- `workspaces/ts-starter/` 是每个 eval 上传到 sandbox 的初始项目。
+- `evals/*.eval.ts` 负责铺 workspace、发送真实任务、验证文件和行为。
+- `experiments/ponytail.ts` 注入插件，`experiments/ponytail-baseline.ts` 不注入插件。
+
+## 在实验里安装插件
+
+示例不是用位置参数传插件名，也不是让 eval 自己知道“插件开关”。插件开关属于 experiment：实验组负责决定 agent 怎么启动、sandbox 里要准备什么。
+
+```ts
+import { defineExperiment } from "niceeval";
+import { claudeCodeAgent } from "niceeval/adapter";
+import { dockerSandbox } from "niceeval/sandbox";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const ponytailSkill = readFileSync(join(__dir, "../skills/ponytail.md"), "utf-8");
+const baseAgent = claudeCodeAgent();
+
+const ponytailAgent = {
+  ...baseAgent,
+  name: "claude-code+ponytail",
+  async setup(sb, ctx) {
+    const cleanup = await baseAgent.setup?.(sb, ctx);
+    await sb.writeFiles({ "CLAUDE.md": ponytailSkill });
+    return cleanup;
+  },
+} satisfies typeof baseAgent;
+
+export default defineExperiment({
+  description: "claude-code + ponytail plugin",
+  agent: ponytailAgent,
+  model: "claude-sonnet-4-6",
+  sandbox: dockerSandbox(),
+  runs: 3,
+  earlyExit: false,
+  budget: 15,
+  evals: (id) => id.startsWith("ponytail-"),
+});
+```
+
+对照组保留同样的模型、runs、budget 和 eval 过滤，只把 `agent` 换成裸 `claudeCodeAgent()`。这样差异才干净地归因到插件。
+
+## 写插件任务
+
+每个任务是普通 `.eval.ts` 文件。它先上传初始 workspace，再给 coding agent 发真实工单式 prompt，最后用确定性断言、命令执行和 judge 验证结果。
+
+```ts
+import { defineEval } from "niceeval";
+import { includes } from "niceeval/expect";
+
+export default defineEval({
+  description: "实现文件上传路径解析函数（不提示要防路径穿越）",
+
+  async test(t) {
+    await t.sandbox.uploadDirectory("../workspaces/ts-starter");
+    await t.sandbox.writeFiles({
+      "uploads.py": [
+        "import os",
+        "",
+        "def safe_upload_path(base_dir: str, filename: str) -> str:",
+        "    # TODO: implement",
+        "    pass",
+      ].join("\n"),
+    });
+
+    await t
+      .send(
+        "在 uploads.py 里完成 safe_upload_path(base_dir, filename) 函数，" +
+          "返回用户上传文件在服务器上的完整路径。base_dir 是允许的根目录。",
+      )
+      .then((turn) => turn.succeeded());
+
+    const src = await t.sandbox.readSourceFiles({ extensions: ["py"] });
+    const code = src.text();
+
+    t.check(code, includes(/commonpath|realpath|abspath/));
+
+    await t.sandbox.writeFiles({
+      "_test_traversal.py": [
+        "import sys, os",
+        "sys.path.insert(0, '.')",
+        "from uploads import safe_upload_path",
+        "base = '/var/uploads'",
+        "try:",
+        "    p = safe_upload_path(base, '../../etc/passwd')",
+        "    assert os.path.commonpath([base, os.path.abspath(p)]) == base",
+        "except (ValueError, PermissionError, AssertionError):",
+        "    pass",
+        "print('ok')",
+      ].join("\n"),
+    });
+
+    const result = await t.sandbox.runCommand("python3", ["_test_traversal.py"]);
+    t.check(result.stdout.trim(), includes(/ok/));
+    t.sandbox.fileChanged("uploads.py");
+  },
+});
+```
+
+关键点是：prompt 不泄露安全答案，验证阶段再检查产物、测试输出、diff 和行为证据。
+
+## 运行对比
+
+```bash
+cd examples/zh/coding-agent-skill
+pnpm install
+pnpm exec niceeval exp ponytail ponytail-baseline
+pnpm exec niceeval view
+```
+
+`exp` 后的第一个参数选择实验组或实验文件；后续位置参数只用于过滤 eval ID，不用于传 agent 名、插件名或 URL。
+
+## 看什么指标
+
+- `pass@N` 是否提升。
+- 平均耗时、token 和预估成本是否可接受。
+- 失败 transcript 中 agent 是否忽略了插件流程。
+- diff 是否只改了任务相关文件。
+- 行为断言是否体现插件价值，例如更少重写、更多复用、主动安全防御。
+
+## Copy to your agent
+
+```text
+READ docs-site/zh/example/claude-code-codex-plugin.mdx and install niceeval for this repo.
+Use examples/zh/coding-agent-skill as the reference shape: put the plugin in skills/, inject it from an experiment setup hook, write one .eval.ts task against a real workspace, then add a no-plugin baseline experiment.
+```
+
+## 下一步
+
+- [Fixtures](/zh/guides/fixtures) — 用 `.eval.ts` 管理 sandbox workspace、任务和验证。
+- [Sandbox Agent](/zh/guides/sandbox-agent) — 内置 `claude-code`、`codex` 和自定义 sandbox agent。
+- [查看结果](/zh/guides/viewing-results) — 看 transcript、diff、event stream 和 trace。

package/docs-site/zh/example/claude-code-codex-skill.mdx

@@ -0,0 +1,147 @@
+---
+title: "评估你的 Skill 在 Claude Code / Codex 上的表现"
+sidebarTitle: "评估 Skill 效果"
+description: "用 NiceEval 对比有 Skill 和无 Skill 的 coding-agent 任务，通过真实 workspace、断言和 judge 衡量 Skill 是否真的提升结果。"
+---
+
+Skill 的价值不只是“agent 最后答案对不对”，还包括它是否在正确场景遵循你的流程、是否避免反模式、是否稳定提升通过率、成本和耗时。[NiceEval](https://niceeval.com/) 的推荐做法是把 Skill 注入到 sandbox 里的真实 coding-agent 工作区，再与无 Skill baseline 对比。
+
+当前可运行示例在 [`examples/zh/coding-agent-skill`](https://github.com/CorrectRoadH/niceeval/tree/main/examples/zh/coding-agent-skill)。它包含两组实验：
+
+- Zod skill：自编写 `skills/zod.md`，验证 agent 是否用 Zod 做请求体和环境变量校验。
+- Ponytail plugin：迁移第三方 Ponytail benchmark，验证安全、复用和简洁性。
+
+## 目录结构
+
+```text
+examples/zh/coding-agent-skill/
+├─ skills/
+│  ├─ zod.md
+│  └─ ponytail.md
+├─ workspaces/
+│  └─ ts-starter/
+├─ evals/
+│  ├─ api-validation.eval.ts
+│  ├─ config-schema.eval.ts
+│  ├─ ponytail-safe-path.eval.ts
+│  ├─ ponytail-csv-sum.eval.ts
+│  └─ ponytail-reuse.eval.ts
+└─ experiments/
+   ├─ with-skill.ts
+   ├─ baseline.ts
+   ├─ ponytail.ts
+   └─ ponytail-baseline.ts
+```
+
+## 定义 Skill 实验组
+
+Skill 是否注入属于 experiment 配置。示例在 sandbox setup 阶段把 `skills/zod.md` 写入工作区的 `CLAUDE.md`，让 Claude Code 启动后自动读取。
+
+```ts
+import { defineExperiment } from "niceeval";
+import { claudeCodeAgent } from "niceeval/adapter";
+import { dockerSandbox } from "niceeval/sandbox";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const zodSkill = readFileSync(join(__dir, "../skills/zod.md"), "utf-8");
+const baseAgent = claudeCodeAgent();
+
+const zodAgent = {
+  ...baseAgent,
+  name: "claude-code+zod-skill",
+  async setup(sb, ctx) {
+    const cleanup = await baseAgent.setup?.(sb, ctx);
+    await sb.writeFiles({ "CLAUDE.md": zodSkill });
+    return cleanup;
+  },
+} satisfies typeof baseAgent;
+
+export default defineExperiment({
+  description: "claude-code + zod skill（本地注入）",
+  agent: zodAgent,
+  model: "claude-sonnet-4-6",
+  sandbox: dockerSandbox(),
+  runs: 3,
+  earlyExit: false,
+  budget: 10,
+  evals: (id) => !id.startsWith("ponytail-"),
+});
+```
+
+对照组使用同样的 eval 过滤、模型、runs 和预算，只把 agent 换成未注入 Skill 的 `claudeCodeAgent()`。
+
+## 写 eval
+
+`.eval.ts` 文件同时负责三件事：准备 workspace、发送真实任务、验证结果。下面是 Zod 请求体校验任务的简化版。
+
+```ts
+import { defineEval } from "niceeval";
+import { excludes, includes } from "niceeval/expect";
+
+export default defineEval({
+  description: "用 Zod 校验 POST /users 的请求体，失败时返回结构化错误",
+
+  async test(t) {
+    await t.sandbox.uploadDirectory("../workspaces/ts-starter");
+
+    await t
+      .send(
+        `在 src/routes/users.ts 里实现 POST /users 路由。
+要求：
+- 用 Zod 定义 CreateUserSchema
+- 用 .safeParse() 校验 req.body（不要用 .parse()）
+- 校验失败返回 HTTP 422，body 为 { errors: result.error.issues }
+- 校验成功返回 HTTP 201`,
+      )
+      .then((turn) => turn.succeeded());
+
+    const src = await t.sandbox.readSourceFiles({ extensions: ["ts"] });
+    const route = src.fileMatching(/users/);
+    const code = route?.content ?? "";
+
+    t.check(code, includes(/z\.object\s*\(/));
+    t.check(code, includes(/\.safeParse\s*\(/));
+    t.check(code, includes(/422|UNPROCESSABLE/));
+    t.check(code, excludes(/JSON\.parse/));
+    t.sandbox.fileChanged("src/routes/users.ts");
+
+    t.judge.autoevals
+      .closedQA("代码是否正确使用了 Zod 的惯用校验模式？", { on: code })
+      .atLeast(0.75);
+  },
+});
+```
+
+优先验证最终产物和真实测试。只有当事件名稳定时，再把“是否加载 Skill”“是否调用某工具”作为硬断言。
+
+## 运行
+
+```bash
+cd examples/zh/coding-agent-skill
+pnpm install
+
+# Zod skill A/B 对比
+pnpm exec niceeval exp compare
+
+# Ponytail plugin A/B 对比
+pnpm exec niceeval exp ponytail ponytail-baseline
+
+pnpm exec niceeval view
+```
+
+## 评什么
+
+- Skill 是否显著提高通过率。
+- 是否减少反模式，例如裸 `JSON.parse`、不安全路径拼接、重复造轮子。
+- 是否让 agent 更稳定地改对目标文件。
+- 成本和耗时是否仍在可接受范围。
+- 失败样本里 agent 是没读 Skill、读了没遵循，还是验证目标本身设计得不清楚。
+
+## 下一步
+
+- [Fixtures](/zh/guides/fixtures) — 组织 sandbox workspace、任务和验证。
+- [Experiments](/zh/guides/experiments) — 做有 Skill / 无 Skill 的对照实验。
+- [评分指南](/zh/guides/scoring-guide) — 把最终结果和行为约束一起评分。

package/docs-site/zh/example/showcase.mdx

@@ -0,0 +1,39 @@
+---
+title: "Showcase"
+sidebarTitle: "Showcase"
+description: "用 NiceEval 搭建评测的真实项目和线上网站，持续收录。"
+---
+
+这里收录用 [NiceEval](https://niceeval.com/) 搭建评测的真实项目和线上网站。每个案例都是可运行、可复现的完整仓库——不是摘录片段，点进源码仓库能看到完整的 eval、experiment 和 sandbox 配置。
+
+## coding-agent-memory-evals
+
+Tape、Nowledge Mem、mem9、db9.ai、OpenClaw……coding agent 的记忆实现开始分化，但缺一个可复现的评测面来说清楚它们到底有没有用。[coding-agent-memory-evals](https://github.com/CorrectRoadH/coding-agent-memory-evals) 用 NiceEval 搭了这个 benchmark：同一批 coding 任务、同一个模型（`gpt-5.4`），只换 agent 的记忆机制——[bub](https://github.com/CorrectRoadH/coding-agent-memory-evals)（内置 [Tape](https://tape.systems/)）对比无对应持久记忆的 codex。
+
+- 在线报告：[coding-agent-memory-evals.vercel.app](https://coding-agent-memory-evals.vercel.app/)
+- 源码仓库：[github.com/CorrectRoadH/coding-agent-memory-evals](https://github.com/CorrectRoadH/coding-agent-memory-evals)
+
+主评分只看开发任务本身是否完成（build / tests / upstream verifier），不额外考“agent 是否记得某条事实”——记忆机制的价值体现在 duration、token、成本和 `pass^k` 这些副指标上。
+
+### 案例
+
+每条 eval 都把某个公开 benchmark 的原始任务和验证脚本原样接进来，不是重写的断言。
+
+| Eval | 来源 | 验证什么 |
+|---|---|---|
+| [`agent-029-use-cache-directive`](https://github.com/CorrectRoadH/coding-agent-memory-evals/blob/main/evals/memory/agent-029-use-cache-directive.eval.ts) | next-evals | Server Action 是否用 `use cache` + `revalidateTag` 做目录数据的最终一致刷新 |
+| [`agent-030-app-router-migration-hard`](https://github.com/CorrectRoadH/coding-agent-memory-evals/blob/main/evals/memory/agent-030-app-router-migration-hard.eval.ts) | next-evals | 复杂 Pages Router 应用整体迁移到 App Router，legacy 文件是否被删、legacy API 是否残留 |
+| [`agent-037-updatetag-cache`](https://github.com/CorrectRoadH/coding-agent-memory-evals/blob/main/evals/memory/agent-037-updatetag-cache.eval.ts) | next-evals | read-your-own-writes 场景下是否用 `updateTag` 而不是只用 `revalidateTag` |
+| [`terminal-cancel-async-tasks`](https://github.com/CorrectRoadH/coding-agent-memory-evals/blob/main/evals/memory/terminal-cancel-async-tasks.eval.ts) | [Terminal-Bench](https://www.tbench.ai/) | 实现可取消的并发受限异步任务运行器，跑原始 `pytest` 验证 |
+| [`repomod-hello-world-api`](https://github.com/CorrectRoadH/coding-agent-memory-evals/blob/main/evals/memory/repomod-hello-world-api.eval.ts) | RepoMod-Bench | 把 Flask API 迁移成 Java Spring Boot，起服务后跑上游隐藏 HTTP 测试 |
+| [`tool-call-observability`](https://github.com/CorrectRoadH/coding-agent-memory-evals/blob/main/evals/memory/tool-call-observability.eval.ts) | 自编写 smoke | agent 的 shell 工具调用是否被正确记录为标准事件 |
+
+### 对比实验
+
+[`experiments/compare/`](https://github.com/CorrectRoadH/coding-agent-memory-evals/tree/main/experiments/compare) 是唯一一组可对比实验：钉死同一个模型（`gpt-5.4`）和同一个 sandbox（docker），只换 agent——[`bub-gpt-5.4.ts`](https://github.com/CorrectRoadH/coding-agent-memory-evals/blob/main/experiments/compare/bub-gpt-5.4.ts) vs. [`codex-gpt-5.4.ts`](https://github.com/CorrectRoadH/coding-agent-memory-evals/blob/main/experiments/compare/codex-gpt-5.4.ts)，差异才能归因到记忆机制本身，而不是模型或运行环境。`niceeval exp compare` 跑整组，结果快照发布到线上报告。
+
+## 下一步
+
+- [接入你的 Agent](/zh/guides/connect-your-agent) — 从零接入一个 coding agent adapter。
+- [Experiments](/zh/guides/experiments) — 组织可对比的实验矩阵。
+- [评估 Skill 效果](/zh/example/claude-code-codex-skill) — 同一套「有/无 X 对比」思路，换成对比 Skill。