实验与生命周期

Experiment 是可签入的运行配置：同一批评估用例对着哪个 adapter、哪个模型、开哪些 flags、跑几次、预算多少，都写在 experiments/ 里。CLI 的位置参数只负责筛评估用例，不负责临时改 agent 或运行配置。

最小实验

// 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 的区别。

// 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,
});

// 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 或者行为。

// 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：

experiments/
  prompts/baseline.ts
  prompts/concise.ts
  retrieval/with-retrieval.ts

npx niceeval exp prompts

报告直接比较当前 Scope 中的这些 experiments，不需要额外分组字段。只想验证某一个配置时，把位置参数写成该配置的完整 id：

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 都不会执行：

// 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 时直接跳过；中断路径上，一次可能挂起的观测不该挡在「拆隧道、退租约」前面：

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 上：

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 · 从官方基线继续构建以提速。 Hook 的执行时机、多 Hook 顺序和失败语义见 Sandbox provider · 生命周期。

与 Sandbox Hook 协作

实验级 Hook 起宿主机侧服务，Sandbox Hook 每个 Sandbox 把坐标写进去、收尾时回存状态——两层在同一个文件里靠模块变量衔接，时序由 runner 保证：实验级 setup 早于本实验任何 Sandbox Hook，Sandbox Hook 读到的变量一定已经赋好值：

// 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。每个实验文件各自调用一次工厂，同一套代码、各自的实例与坐标：

// 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 那几行，生命周期四行接完：

// 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 之后才存在。

服务起多份太贵、必须让同批实验共享一份实例时，用「首进启动、末出关停」的引用计数代替按实验各建一份：

// 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 表再把它映射到具体模板或快照：

// evals/astropy-2021.eval.ts
export default defineEval({
  environment: "python-3.9-astropy-4.2",
  async test(t) {
    // 驱动任务并验证结果
  },
});

// 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" },
  },
});

// 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 复用的数据，同一个实验能覆盖全部评估用例——分数和对比表不会因为环境不同被拆成多个实验。跨配置比较的设计建议见实验矩阵。Adapter 对 ctx.model 和 ctx.flags 的用法见 Adapter。

开始使用

连接 Agent

编写评估

运行、观察与发布

问题排查

实验与生命周期

最小实验

评估不同的 System Prompt 对于 Agent 的影响

编写一组实验

常用字段

启动 Experiment 共享服务

与 Sandbox Hook 协作

多个实验共享同一套生命周期代码

让不同评估用例使用不同预制环境

​最小实验

​评估不同的 System Prompt 对于 Agent 的影响

​编写一组实验

​常用字段

​启动 Experiment 共享服务

​与 Sandbox Hook 协作

​多个实验共享同一套生命周期代码

​让不同评估用例使用不同预制环境

最小实验

评估不同的 System Prompt 对于 Agent 的影响

编写一组实验

常用字段

启动 Experiment 共享服务

与 Sandbox Hook 协作

多个实验共享同一套生命周期代码

让不同评估用例使用不同预制环境