niceeval 0.4.3 → 0.4.5

package/docs-site/zh/index.mdx

@@ -0,0 +1,180 @@
+---
+title: "NiceEval"
+sidebarTitle: "首页"
+description: "NiceEval 是一个渐进式、全功能、开发体验友好、Agent Native 的 AI agent eval 工具。"
+---
+
+<div align="center">
+
+# NiceEval
+
+**渐进式、全功能、开发体验友好、Agent Native 的 AI agent eval 工具**
+
+</div>
+
+[NiceEval](https://niceeval.com/) 是一个受 [eve](https://eve.dev) 启发的 agent-native eval 工具。它首先追求良好的开发体验：一个项目可以在 10 分钟左右接入，eval 文件足够直观，结果也足够容易读。
+
+它也足够通用：可以用来 eval 给 Claude Code / Codex 写的 coding-agent 插件、Hook 和 Skill，也可以 eval 你自己的 AI Agent 应用。无论你的应用基于 AI SDK、LangGraph、Pi，还是自研 agent loop，都可以通过 adapter 接入。
+
+eval 运行完成后，[NiceEval](https://niceeval.com/) 会生成易读报告和结构化 artifacts，让你能查看 agent 的行为细节，调试失败原因，并持续优化 pass rate、成本和延迟。
+
+<CardGroup cols={3}>
+  <Card title="Claude Code / Codex 插件" icon="plug" href="/zh/example/claude-code-codex-plugin">
+    用 sandbox workspace 让 coding agent 跑真实任务，再用测试、diff 和工具调用记录验证插件行为。
+  </Card>
+  <Card title="Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
+    用 experiment setup 注入 Skill，再与无 Skill baseline 批量比较通过率、成本和行为差异。
+  </Card>
+  <Card title="AI Agent 应用" icon="globe" href="/zh/example/ai-agent-application">
+    用 `defineAgent` 包装你的 AI Agent，把回复、工具调用和结构化输出纳入同一套 eval。
+  </Card>
+</CardGroup>
+
+## 架构
+
+[NiceEval](https://niceeval.com/) 支持两种接入方式，取决于被测系统是否需要隔离工作区。
+
+### 模式一：Sandbox
+
+跑 Codex、Claude Code 等需要 sandbox 的 coding agent：
+
+```text
+   evals/*.eval.ts
+        │
+        ▼
+   ┌────────────┐
+   │  niceeval  │
+   └────────────┘
+        │
+        │ Agent 适配器（官方）
+        ▼
+   ┌───────────────────────────────┐
+   │        Docker Sandbox         │
+   │    ┌───────────────────────┐  │
+   │    │ Codex / Claude Code / │  │
+   │    │ 需要隔离工作区的应用  │  │
+   │    └───────────────────────┘  │
+   └───────────────────────────────┘
+```
+
+### 模式二：直连
+
+直接连接你自己的 AI Agent：
+
+```text
+   evals/*.eval.ts
+        │
+        ▼
+   ┌────────────┐
+   │  niceeval  │
+   └────────────┘
+        │
+        │ Agent 适配器（官方 / 自定义）
+        ▼
+   ┌────────────────────────────┐
+   │     你自己的 AI Agent      │
+   │ (AI SDK · LangGraph · Pi · │
+   │    自研 agent loop 等)     │
+   └────────────────────────────┘
+```
+
+- **[NiceEval](https://niceeval.com/) 核心** 负责发现 eval、调度运行、打分、生成报告与 artifacts。
+- **Agent 适配器** 是开放边界：你决定如何调用被测系统，以及如何把输出映射成标准事件流。
+- **Sandbox** 负责文件系统隔离：需要真实 workspace 的 coding agent 使用 Docker 或云端 sandbox；自有 Web Agent 可以直连，无需 Docker。
+
+## 核心概念一览
+
+| 概念 | 一句话 |
+|---|---|
+| [Eval](/zh/concepts/evals) | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
+| [Experiment](/zh/concepts/experiment) | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
+| [Adapter](/zh/concepts/adapter) | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
+| [Sandbox](/zh/guides/sandbox-backends) | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
+| [Tier](/zh/concepts/tier) | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
+
+完整术语表见[架构概览](/zh/concepts/overview)。
+
+## 示例
+
+跑一条 eval 需要两个文件：eval 本身（测什么）和 experiment（跑哪个 agent）。CLI 不接受裸 eval id——`niceeval exp <experiment> <eval 前缀>` 里的 experiment 才决定「连哪个被测对象」。下面是一个直连 Web Agent 的真实场景（完整项目见仓库 `examples/zh/ai-sdk/`），验证 agent 遇到实时天气问题时会调用工具、并基于工具结果作答，而不是凭空编造：
+
+```ts
+// evals/weather-tool.eval.ts
+import { defineEval } from "niceeval";
+
+export default defineEval({
+  description: "测试 agent 在实时天气问题中正确调用工具并基于结果作答的能力",
+
+  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);
+  },
+});
+```
+
+```ts
+// experiments/local.ts
+import { defineExperiment } from "niceeval";
+import { webAgent } from "./adapter"; // 你自己写的 Adapter，接被测 Web Agent
+
+export default defineExperiment({
+  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
+  model: "gpt-5.4",
+});
+```
+
+```sh
+npx niceeval exp local weather-tool
+npx niceeval view
+```
+
+如果被测对象是需要隔离工作区的 coding agent（Codex、Claude Code 插件/Skill），evals 里改用 `t.sandbox.uploadDirectory()` 铺工作区、`t.sandbox.fileChanged()` / `t.sandbox.file()` 检查改了什么文件、`t.sandbox.runCommand()` 跑测试——参考仓库 `examples/zh/coding-agent-skill/`。
+
+## 快速开始
+
+如果你想让 coding agent 直接帮项目接入 [NiceEval](https://niceeval.com/)，可以把对应场景页交给它读：
+
+```text
+READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/claude-code-codex-plugin.mdx and install niceeval for this repo.
+READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/claude-code-codex-skill.mdx and install niceeval for this repo.
+READ https://raw.githubusercontent.com/CorrectRoadH/niceeval/refs/heads/main/docs-site/zh/example/ai-agent-application.mdx and install niceeval for this repo.
+```
+
+<CardGroup cols={3}>
+  <Card title="如果你需要 eval 你的 Claude Code / Codex 插件" icon="plug" href="/zh/example/claude-code-codex-plugin">
+    从真实插件任务出发，上传 workspace、注入插件，并用 pass rate 看插件是否稳定工作。
+  </Card>
+  <Card title="如果你需要 eval 你的 Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
+    验证 Skill 是否被加载、是否按约定使用工具、是否产出可测试结果。
+  </Card>
+  <Card title="如果你需要 eval 你的 AI Agent 应用" icon="globe" href="/zh/example/ai-agent-application">
+    包装你的 agent 接口，写对话、工具调用、结构化输出和成本断言。
+  </Card>
+</CardGroup>
+
+## 常见问题
+
+<AccordionGroup>
+  <Accordion title="需要注册账号吗？">
+    不需要。跑 eval 和 `niceeval view` 看报告全在本地完成；只有被测对象本身是需要隔离工作区的 coding agent 时，才会用到 Docker 或 E2B 这类 sandbox 后端。
+  </Accordion>
+  <Accordion title="我的 Agent 不是用 TypeScript / JavaScript 写的，能接吗？">
+    能。Adapter 只是对着应用本来暴露的接口（HTTP、gRPC、WebSocket 都行）收发；应用本身用什么语言写、部署在哪里，[NiceEval](https://niceeval.com/) 不关心，见 [Adapter](/zh/concepts/adapter)。
+  </Accordion>
+  <Accordion title="能接到 CI 里吗？">
+    能，见 [CI 集成](/zh/guides/ci-integration)。
+  </Accordion>
+</AccordionGroup>
+
+<Tip>
+  想先走最小路径，读 [快速开始](/zh/quickstart)。想理解边界，读 [架构概览](/zh/concepts/overview)。
+</Tip>

package/docs-site/zh/introduction.mdx

@@ -0,0 +1,140 @@
+---
+title: "NiceEval：面向 Agent 的评估工具"
+sidebarTitle: "介绍"
+description: "NiceEval 帮助团队衡量、评估并改进生产环境中的 AI：比较模型、迭代 Agent、发现回归、用真实数据持续改进。"
+---
+
+[NiceEval](https://niceeval.com/) 是一个 Agent 评估工具，帮助团队衡量、评估并改进生产环境中的 AI。借助 NiceEval，团队可以比较模型、迭代 Agent、发现回归问题，并利用真实用户数据持续改进 AI 应用。它追求低心智负担的 DX：大多数项目都可以在 10 分钟左右接入，写出第一条 eval，并开始稳定地检查 agent 行为。
+
+NiceEval 以本地优先为核心：你的评估在你自己的环境中运行，不需要先开账号、连平台才能跑第一条 eval。当团队需要分享评估结果、做回归跟踪时，可以通过 Report 上报到 BrainTrust 等平台，或者自定义报告导出。
+
+它既能评估用于 Claude Code / Codex 的 Plugins、Hook 和 Skill，也能直接评你自己的 AI Agent 应用。无论你的 Agent 基于 AI SDK、LangGraph、Pi 还是自研 loop，都可以通过 Adapter 接入同一套评估体系。
+
+## 30 秒看懂 DX
+
+一个 eval 就是一个 TypeScript 文件：给 agent 发消息，断言它做对了什么。
+
+```ts
+// evals/eval-tool-call.eval.ts
+import { defineEval } from "niceeval";
+
+export default defineEval({
+  description: "测试 agent 在实时天气问题中正确调用工具并基于结果作答的能力",
+
+  async test(t) {
+    const turn = await t.send("北京今天天气怎么样？");
+    t.succeeded();
+
+    await t.group("调用 get_weather 且城市正确", () => {
+      t.calledTool("get_weather", { input: { city: "北京" } });
+      t.messageIncludes(/°C|气温|天气|晴|多云|雨/);
+    });
+
+    const second = await t.send("上海明天天气怎么样?");
+    second.messageIncludes("上海");
+
+    t.judge.autoevals
+      .closedQA("助手是否基于工具返回的天气数据作答，而不是凭空编造温度？")
+      .atLeast(0.7);
+  },
+});
+```
+
+```sh
+pnpm exec niceeval exp local eval-tool-call  # 用 local experiment 只跑 eval-tool-call
+pnpm exec niceeval view                      # 查看评估结果
+```
+
+## 为什么有了 DeepEval、LangFuse、BrainTrust 还需要 NiceEval
+
+NiceEval 是一个 Agent-Native 的评估工具。Dataset / golden 那一套「构建 Input 与 Expected Output」的模式，并不适合真实的 Agent 评估——现在的 Agent 要在多轮对话、多 agent 协作、工具调用、Skill 加载等细粒度场景下被检查，NiceEval 就是为这类场景设计的：断言直接落在工具调用、消息内容、结构化输出和用量上，而不是要求你先手工准备一份 golden 数据集。
+
+像 LangFuse、BrainTrust 这类工具更偏 tracing 和监控，对「写 eval、跑 eval、看结果」这条路径来说太重；NiceEval 从一开始就针对这条路径做了友好的开发体验。两者也不冲突：NiceEval 能与 LangFuse、BrainTrust 共存——可以用它们做 tracing，或者把评估结果上传到两者。
+
+## 你可以评什么
+
+<CardGroup cols={2}>
+  <Card title="Coding Agent" icon="code">
+    把 Claude Code、Codex、bub 放进 Sandbox，给它任务，再用真实测试和文件断言验证结果。
+  </Card>
+  <Card title="你自己的 AI Agent 应用" icon="globe">
+    直连你的应用接口，断言回复、工具调用和结构化输出。
+  </Card>
+</CardGroup>
+
+## 两种接入模式
+
+<Tabs>
+  <Tab title="Sandbox mode">
+    适合 Codex、Claude Code 这类必须在真实文件系统中改代码、跑命令的 coding agent。
+
+    ```text
+       evals/*.eval.ts
+            │
+            ▼
+       ┌────────────┐
+       │  niceeval  │
+       └────────────┘
+            │
+            │ Agent 适配器(官方)
+            ▼
+       ┌───────────────────────────────┐
+       │        Docker Sandbox         │
+       │    ┌───────────────────────┐  │
+       │    │ Codex / Claude Code / │  │
+       │    │ 需要隔离工作区的应用  │  │
+       │    └───────────────────────┘  │
+       └───────────────────────────────┘
+    ```
+  </Tab>
+  <Tab title="Direct mode">
+    适合你自己的 AI Agent，不需要 Docker。
+
+    ```text
+       evals/*.eval.ts
+            │
+            ▼
+       ┌────────────┐
+       │  niceeval  │
+       └────────────┘
+            │
+            │ Agent 适配器(官方，或者自己实现)
+            ▼
+       ┌────────────────────────────┐
+       │     你自己的 AI Agent      │
+       │ (AI SDK · LangGraph · Pi · │
+       │    自研 agent loop 等)     │
+       └────────────────────────────┘
+    ```
+  </Tab>
+</Tabs>
+
+## 核心概念一览
+
+| 概念 | 一句话 |
+|---|---|
+| Eval | 一个测试用例：写在 `evals/*.eval.ts` 里，描述测什么。 |
+| Experiment | 可签入的运行配置：决定连哪个 Adapter、什么 model、什么 flags。 |
+| Adapter | 连接被测系统的适配层：实现一个 `send`，把返回翻译成标准事件流。 |
+| Sandbox | 需要隔离工作区的 coding agent 才用得到；直连 Web Agent 不需要。 |
+| Tier | 接入 Adapter 的三档投入：Tier 1 只接 send，Tier 2 加 OTel 换调用瀑布图，Tier 3 侵入改造做 feature A/B。 |
+
+完整术语表见[架构概览](/zh/concepts/overview)。
+
+## 从你的场景开始
+
+<CardGroup cols={3}>
+  <Card title="评估 Claude Code / Codex 插件" icon="puzzle-piece" href="/zh/example/claude-code-codex-plugin">
+    把插件放进真实 workspace，比较有插件和无插件时的通过率、成本、耗时和行为差异。
+  </Card>
+  <Card title="评估 Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
+    对比有 Skill 和无 Skill 的 coding-agent 任务，衡量 Skill 是否真的提升结果。
+  </Card>
+  <Card title="评估你的 AI Agent 应用" icon="robot" href="/zh/example/ai-agent-application">
+    直连你自己的应用接口，断言工具调用、图片理解和多轮会话。
+  </Card>
+</CardGroup>
+
+## 接下来读什么
+
+[快速开始](/zh/quickstart) 会带你安装 [NiceEval](https://niceeval.com/)、构建 eval、得到评估报告。

package/docs-site/zh/quickstart.mdx

@@ -0,0 +1,137 @@
+---
+title: "为你的 Agent 项目设置评估"
+sidebarTitle: "快速开始"
+description: "安装 NiceEval，写三个文件，10 分钟内对你自己的应用跑通第一条 eval。"
+---
+
+接入你自己的应用只需要三个文件：一个 **adapter**（怎么调你的应用）、一个 **experiment**（评谁、跑几次）、一条 **eval**（断言什么）。下面是完整的最短路径；写给 coding agent 的一键接入和场景示例在后面。
+
+## 让 AI 帮你接入 (推荐)
+<Steps>
+  <Step title="安装">
+    ```text
+    READ https://niceeval.com/INIT.md and install niceeval for this repo.
+
+    ```
+  </Step>
+  <Step title="运行测试">
+    ```bash
+    pnpm exec niceeval exp 实验名
+    ```
+  </Step>
+  <Step title="查看结果">
+    ```text
+    pnpm exec niceeval view
+    ```
+  </Step>
+</Steps>
+
+
+## 人工接入
+
+```bash
+pnpm add -D niceeval
+pnpm exec niceeval init
+```
+
+### Adapter
+Adapter 是连接 Agent 与 [NiceEval](https://niceeval.com/) 的中间层。有三种不同程序的接入方式，从无侵入式到部分修改你的 Agent 代码，来解锁更有用的评估功能。 见[Tier](/zh/concepts/tier)。
+
+```ts
+// agents/my-bot.ts
+import { defineAgent } from "niceeval/adapter";
+
+export default defineAgent({
+  name: "my-bot",
+  async send(input, ctx) {
+    // 示例地址：换成你自己 agent 的真实端点（HTTP、CLI、SDK 都行，只要 send 里能拿到回复文本）
+    const r = await fetch("http://localhost:3000/chat", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ message: input.text, model: ctx.model }), // ← experiment.model 经 ctx.model 到这里
+      signal: ctx.signal,
+    });
+    const body = await r.json();
+    return {
+      status: r.ok ? "completed" : "failed",
+      events: [{ type: "message", role: "assistant", text: body.reply }],
+    };
+  },
+});
+```
+
+### Experiment
+
+```ts
+// experiments/my-bot.ts
+import { defineExperiment } from "niceeval";
+import myBot from "../agents/my-bot.ts";
+
+export default defineExperiment({
+  description: "my-bot 基线",
+  model: "gpt-4o",
+  agent: myBot,
+  runs: 1,
+});
+```
+
+### Eval
+
+```ts
+// evals/refund-policy.eval.ts
+import { defineEval } from "niceeval";
+import { includes } from "niceeval/expect";
+
+export default defineEval({
+  description: "退款政策问答",
+  async test(t) {
+    await t.send("你们的退款政策是什么?");
+    t.succeeded();
+    t.check(t.reply, includes("30 天"));
+  },
+});
+```
+
+```bash
+pnpm exec niceeval exp my-bot   # 跑起来
+pnpm exec niceeval view         # 本地查看器里看结果
+```
+
+到这里第一条 eval 已经跑通。
+
+这个最小 adapter 是**单轮**的——第二轮不会记得第一轮说了什么，因为还没告诉应用怎么接上历史。多轮会话和工具调用事件（解锁 `t.calledTool()`）、HITL、tracing 一样，都是之后给 adapter 加的可选增量：顺着[接入你的 Agent](/zh/guides/connect-your-agent)逐层往下走即可，已写的 eval 不用改。
+
+## 按场景走
+
+已经知道自己要评什么的话，直接从对应场景开始：
+
+<CardGroup cols={3}>
+  <Card title="如果你需要 eval 你的 Claude Code / Codex 插件" icon="plug" href="/zh/example/claude-code-codex-plugin">
+    适合插件、Hook、MCP server 和项目级 coding-agent 扩展。
+  </Card>
+  <Card title="如果你需要 eval 你的 Claude Code / Codex Skill" icon="wand-magic-sparkles" href="/zh/example/claude-code-codex-skill">
+    适合验证 Skill 是否被触发、是否按流程执行、是否真的提升任务成功率。
+  </Card>
+  <Card title="如果你需要 eval 你的 AI Agent 应用" icon="globe" href="/zh/example/ai-agent-application">
+    适合 AI SDK、LangGraph、Pi 或自研 agent 应用的完整示例。
+  </Card>
+</CardGroup>
+
+## 放进 CI
+
+```yaml
+name: evals
+on: [pull_request]
+jobs:
+  evals:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npm exec niceeval exp my-bot
+```
+
+<Tip>
+  接下来读 [编写 eval](/zh/guides/authoring) 和 [评分指南](/zh/guides/scoring-guide)，把示例替换成你的真实场景。
+</Tip>