niceeval 0.9.1 → 0.10.2

package/docs-site/zh/how-to/experiments.mdx

@@ -1,86 +0,0 @@
----
-title: "实验矩阵：用运行矩阵比较 agents 和 models"
-sidebarTitle: "实验矩阵"
-description: "使用 NiceEval experiments 让同一批 eval 横跨多个 agents、models 和 flags，比较 pass rate、成本和延迟。"
----
-
-Experiment 用于比较多组运行配置。典型问题包括：Claude Code 和 Codex 谁在同一批 coding-agent 任务上 pass rate 更高？某个 prompt 改动是否降低成本？不同模型的延迟和质量如何取舍？
-
-## 基本形状
-
-**一个实验文件 = 一个配置**（一个 agent × 一个 model）。`model` 是单个字符串，不接受数组。要跨模型 / 跨 agent 对比，就在一个**实验组文件夹**里写多个文件，各钉对照轴之外的一切：
-
-```text
-experiments/
-  compare-models/          # 实验组
-    gpt-5.4.ts             #   一格:钉 model = gpt-5.4
-    deepseek-v4-pro.ts     #   一格:钉 model = deepseek-v4-pro
-```
-
-```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,
-});
-```
-
-```bash
-npx niceeval exp compare-models   # 把同组各 model 并排出报告
-```
-
-这样每个配置独立成文件：可命名、可 diff、可单独 review，"这一组就是对照"在文件结构上就讲清楚了。默认 `niceeval show` / `view` 也沿用这条边界：只把同一文件夹下的 experiment 放进同一张成本 × 端到端成功率图和实验表，不同文件夹分别显示。
-
-某一格结果反常、需要单独复现时，用该配置的完整 id（`组/文件名`）精确只跑这一格，不用先跑完整组：
-
-```bash
-npx niceeval exp compare-models/gpt-5.4
-```
-
-`defineExperiment` 的字段怎么写、`flags` 怎么透传到 adapter，见[写实验](/zh/how-to/write-experiment)。
-
-## 适合比较什么
-
-- 不同 Adapters。
-- 不同模型（Tier 1 接入即可：应用接口暴露模型选择，`model` 经 `ctx.model` 透传）。
-- 不同 prompts 或 feature flags（要求 Tier 3 接入：变体在应用内部，需要应用把它暴露成 experiment 可选的 flag，经 `flags` → `ctx.flags` 透传）。
-- 不同 sandbox provider。
-- 不同运行环境条件（比如装不装某个记忆工具的二进制、有没有预置状态）：环境差异写在 `sandbox` spec 的 `.setup()` / `.teardown()` 钩子里，一个变体一个 experiment 文件，见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
-- 同一任务的 pass@N。
-
-Tier 1 / Tier 2 / Tier 3 的定义见 [Tier](/zh/explanation/tier)。
-
-## 查看结果
-
-Experiment 输出通常按 `(agent, model, eval)` 维度展示：
-
-```text
-api-validation   claude-code+zod-skill   pass@3 = 3/3 (100%)   mean 34s
-api-validation   claude-code             pass@3 = 1/3 (33%)    mean 41s
-```
-
-除了 pass rate，还应该看平均耗时、token、成本和失败类型。
-
-```bash
-npx niceeval show --exp compare-models
-npx niceeval view
-```
-
-`show --exp` 按路径段匹配 id 前缀，所以组名会选中组内所有配置，但不会误中名字只是在字符串上相似的另一个组。`view` 默认加载完整结果，直接在页面里选组；`--exp` 对它只是可选的启动时收窄。
-
-## 设计 experiment 的建议
-
-- 保持 eval 集合稳定，避免比较时混入新变量。
-- 每个 cell 跑多个 attempts，尤其是非确定性 coding agent。
-- 把预算和并发写清楚。
-- 对“失败原因”做归类，不只看总分。
-
-## 与普通运行的关系
-
-`npx niceeval exp <实验>` 关注“这一批 eval 在某个配置下是否通过”；实验组关注“多组配置谁更好”。两者使用同一套 eval、Adapter、scoring 和 artifacts。

package/docs-site/zh/how-to/write-experiment.mdx

@@ -1,164 +0,0 @@
----
-title: "写实验：用 defineExperiment 固定运行配置"
-sidebarTitle: "写实验"
-description: "学习如何在 experiments/ 里用 defineExperiment 选择 agent、传 model 和 flags、设置 runs、预算、并发与 sandbox。"
----
-
-Experiment 是可签入的运行配置：同一批 eval 对着哪个 adapter、哪个模型、开哪些 flags、跑几次、预算多少，都写在 `experiments/` 里。CLI 的位置参数只负责筛 eval，不负责临时改 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` 字段。
-
-## 传 model 和 flags
-
-```ts
-// experiments/concise.ts
-import { defineExperiment } from "niceeval";
-import { webAgent } from "../agents/web-agent.ts";
-
-export default defineExperiment({
-  description: "简洁 prompt 变体",
-  agent: webAgent({
-    baseUrl: "https://staging.example.com",
-    apiKey: process.env.STAGING_AGENT_API_KEY,
-  }),
-  model: "gpt-5.4",
-  flags: {
-    promptVariant: "concise",
-    webResearch: false,
-  },
-  runs: 3,
-  earlyExit: true,
-  budget: 5,
-});
-```
-
-`model` 会作为 `ctx.model` 传给 adapter；应用接口支持模型选择时，adapter 把它放进请求体、header 或 CLI 参数即可。
-
-`flags` 会作为 `ctx.flags` 传给 adapter，也会作为 `t.flags` 出现在 eval 里。语义就是产品 A/B 测试里的 feature flag：一个 experiment 就是一组 flag 取值，例如 prompt 版本、工具集、检索开关；值可以是任意 JSON（变体名、数字、配置对象），不限于布尔。真正按 flag 切换行为的是你的应用或 adapter，[NiceEval](https://niceeval.com/) 只负责原样透传。它与命令行开关是两回事——后者在文档里一律写作 CLI flag 或字面的 `--xxx`。
-
-```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 取值，就把多个文件放进同一个文件夹：
-
-```text
-experiments/
-  prompt-variants/
-    baseline.ts
-    concise.ts
-    with-retrieval.ts
-```
-
-```bash
-npx niceeval exp prompt-variants
-```
-
-这样报告会按同一组展示，差异也能在 Git 里 review。
-
-只想验证组里某一个配置时，把位置参数写成该配置的完整 id（`组/文件名`，不带扩展名），精确匹配到单个文件：
-
-```bash
-npx niceeval exp prompt-variants/concise
-```
-
-用于逐配置排查——确认某一格改动是否达标，不用先跑完整组，也不用把其它配置文件挪出目录。
-
-## 常用字段
-
-| 字段 | 用途 |
-|---|---|
-| `agent` | 选择并配置 adapter；必填 |
-| `model` | 单个模型名，经 `ctx.model` 透传 |
-| `reasoningEffort` | 单个推理努力程度（如 `"high"`），经 `ctx.reasoningEffort` / `t.reasoningEffort` 透传，归属与 `model` 一致 |
-| `flags` | 实验条件（A/B 里的 feature flag），任意 JSON 对象，经 `ctx.flags` / `t.flags` 透传 |
-| `runs` | 每个 eval × 配置最多跑几次 |
-| `earlyExit` | 多次运行里通过一次就提前停止 |
-| `evals` | 限定这一格配置跑哪些 eval |
-| `timeoutMs` | 单个 attempt 的超时 |
-| `budget` | 这一格配置的预算上限 |
-| `maxConcurrency` | 这一格配置的并发上限 |
-| `sandbox` | sandbox agent 使用的固定 spec；spec 可带 `environments` 表按 eval 的环境 profile 换预制产物，也可以链 `.setup()` / `.teardown()` 挂环境钩子 |
-
-Experiment 本身是纯配置数据，没有 `setup` / `teardown` 这类字段。要在跑 agent 前按实验准备环境（装二进制、预热、跨 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 继续派生来提速，见 [沙箱 provider · 从官方基线继续构建以提速](/zh/how-to/sandbox-providers#从官方基线继续构建以提速)。
-
-钩子的执行时机、多钩子顺序和失败语义见 [沙箱 provider · 环境钩子](/zh/how-to/sandbox-providers#环境钩子)。
-
-## 让不同 eval 使用不同预制环境
-
-一批真实任务可能需要不同版本的运行时和依赖。eval 用 `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 前对所有选中的 eval 完成查表；某条 eval 声明的 profile 缺表项会在启动时一次性报出全部缺项。remote Agent 不创建 Sandbox，不参与查表。因为映射是随 spec 复用的数据，同一个实验能覆盖全部 eval——分数和对比表不会因为环境不同被拆成多个实验。
-
-跨配置比较的设计建议见[实验矩阵](/zh/how-to/experiments)。adapter 如何消费 `ctx.model` 和 `ctx.flags` 见[Adapter](/zh/explanation/adapter)。