实验与生命周期

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 的区别。两格之间只差一个变量（这里是 flags.promptVariant），其余字段逐字相同——差别越少，分数差能归因到的东西越明确：

// experiments/prompts/v1.ts
import { defineExperiment } from "niceeval";
import { webAgent } from "../../agents/web-agent.ts";

export default defineExperiment({
  description: "System Prompt v1（基线）",
  agent: webAgent({
    baseUrl: "https://staging.example.com",
  }),
  model: "gpt-5.4",
  flags: {
    promptVariant: "v1",     // ← 唯一的变量
  },
  attempts: 1,
  budget: 5,
});

// experiments/prompts/v2.ts
import { defineExperiment } from "niceeval";
import { webAgent } from "../../agents/web-agent.ts";

export default defineExperiment({
  description: "System Prompt v2（对比）",
  agent: webAgent({
    baseUrl: "https://staging.example.com",
  }),
  model: "gpt-5.4",
  flags: {
    promptVariant: "v2",     // ← 唯一的变量
  },
  attempts: 1,
  budget: 5,
});

两格写成同一个 flags（或模型对比里两格钉同一个 model，包括两格都写成同一个环境变量默认值）是最常见的失误：跑得完、报告也出得来，但两列数字比的是同一套配置，看不出任何东西。 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` 透传
`attempts`	每个评估用例 × 配置最多跑几次
`earlyExit`	多次运行里通过一次就提前停止。默认关，`attempts` 默认跑满测完整通过率
`evals`	`"*"`、id 前缀数组，或遍历只读 eval 描述并返回 boolean 的函数
`timeoutMs`	单个 attempt 的超时
`budget`	这一格配置的预算上限
`maxConcurrency`	这一格配置的并发上限
`sharedState`	跨 Invocation 共享 checkpoint 的独占 key。只协调状态，不提供存储
`sandbox`	一条 `SandboxLayer`。具体 factory 一次声明 provider 原生 template，并可链 `.prepare()` / `.setup()` / `.teardown()`
`plugins`	显式附着的 NiceEval Plugin occurrence；把一套 identity、flags、Sandbox 命令、生命周期或 Agent Extension 作为完整条件复用
`setup`	实验级 Hook：整个实验只跑一次、在你自己的机器上执行，启动全部 Attempt 共享的服务（见下）
`teardown`	与 `setup` 成对的实验级 Hook：全部 Attempt 收尾后执行一次，当且仅当 `setup` 的时点已经走到（见下）

记下这轮连的是哪个地址，又不让它作废缓存

flags 写的是实验条件，它整袋参与缓存判定：值一变，已经跑完的结果就要重跑。所以隧道地址不要写进 flags——隧道每次重启换一个 URL，写进去就等于每次重启都作废全部已完成结果。这个地址是 setup 跑起来才拿到的，用 ctx.fact() 把它记进结果：

// experiments/shared/nowledge.ts —— 每个 Sandbox 执行一次的 Hook
sandboxSetup(): SandboxHook {
  return async (sandbox, ctx) => {
    ctx.fact("com.example.nowledge-endpoint", env.url); // 这条 Attempt 实际连的实例
    await sandbox.writeText(".nowledge/env", `NMEM_URL=${env.url}\n`);
  };
}

换了 URL 再跑，已完成的照常复用，只跑还缺的：

$ pnpm exec niceeval exp compare/codex--nowledge
╭─ PLAN ──────────────────────────────────────────╮
│ 36 attempts · 36 evals × 1 configs              │
│ 24 of 36 reuse from cache · 12 to run           │
╰─────────────────────────────────────────────────╯

记录一样不少：niceeval show 的 facts: 行会列出这条 Attempt 连的地址，报告也能按它分组。复用进来的结果带的是它当初那一轮的地址，不会被这一轮的新 URL 顶替。服务端版本号则相反：写成 flags: { memoryVersion: "0.10.39" }，换了版本行为可能真的不一样，那种变化就该让结果重跑。判据是谁写下这个值——你在实验里声明的是条件，写 flags。跑起来才知道的是观测，用 ctx.fact()。完整 fact document 不能超过 65,536 UTF-8 bytes；大内容要用专用 Attempt channel 与 blob。Adapter 和评估用例都不需要读、只给报告分组用的标注写 labels。

启动 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 检查、指标上报）只是 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")), // 回存状态
  sandboxReuse: true,
  maxConcurrency: 1,                    // 本 Invocation 内串行
  sharedState: { key: "mempal/codex/cohort-a" },
});

固定的 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,
  sharedState: { key: "nowledge/claude/cohort-a" },
  sandbox: e2bSandbox({ template: "niceeval-agents" })
    .setup(async (sandbox, ctx) => {
      // 每沙箱一次，晚于实验级 setup：把宿主机侧坐标写进沙箱
      await sandbox.writeText(
        ".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 怎么连自己、评估用例的Fixture各在 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.writeText(
          ".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 经环境变量传入。

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

一批真实任务可能需要不同版本的运行时和依赖。把具体的 template-bearing factory 直接放在每条 Eval 上，让任务与执行环境保持为同一份声明：

// evals/astropy-2021.eval.ts
export default defineEval({
  sandbox: e2bSandbox({ template: "codex-python39" }),
  async test(t) {
    // 驱动任务并验证结果
  },
});

// evals/shared/python39.ts —— 用普通 TypeScript 复用，不建 profile registry
import { e2bSandbox } from "niceeval/sandbox";

export const python39 = () => e2bSandbox({ template: "codex-python39" });

// experiments/e2b.ts —— Eval 拥有 template，Experiment 只拥有 agent
import { defineExperiment } from "niceeval";

export default defineExperiment({
  agent: codexAgent(),
});

没有 profile registry，也没有按 source kind 登记的 materializer 表。每个 factory 同时拥有支持声明与实现，physical planning 会在创建任何 Sandbox 前校验所有选中 Eval。重复 template 用普通 TypeScript 辅助函数共享。同一个 Experiment 仍能覆盖全部 Eval，link planning 会逐条把 Eval layer 与 Experiment layer 配对。跨配置比较的设计建议见实验矩阵。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 协作

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

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