跳转到主要内容
Experiment 是可签入的运行配置：同一批 eval 对着哪个 adapter、哪个模型、哪些 feature flags、跑几次、预算多少，都写在 experiments/ 里。CLI 的位置参数只负责筛 eval，不负责临时改 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 字段。

​
传 model 和 flags

// 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 里。它适合表达 experiment 维度的 feature 开关，例如 prompt 版本、工具集、检索开关。真正按 flag 切换行为的是你的应用或 adapter，NiceEval 只负责原样透传。 
// 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 或 flags，就把多个文件放进同一个文件夹： 
experiments/
  prompt-variants/
    baseline.ts
    concise.ts
    with-retrieval.ts

npx niceeval exp prompt-variants
这样报告会按同一组展示，差异也能在 Git 里 review。

​
常用字段

字段用途
agent选择并配置 adapter；必填
model单个模型名，经 ctx.model 透传
reasoningEffort单个推理努力程度（如 "high"），经 ctx.reasoningEffort / t.reasoningEffort 透传，归属与 model 一致
flags任意 JSON 对象，经 ctx.flags / t.flags 透传
runs每个 eval × 配置最多跑几次
earlyExit多次运行里通过一次就提前停止
evals限定这一格配置跑哪些 eval
timeoutMs单个 attempt 的超时
budget这一格配置的预算上限
maxConcurrency这一格配置的并发上限
sandboxsandbox agent 使用的后端，如 dockerSandbox() / e2bSandbox()
跨配置比较的设计建议见实验矩阵。adapter 如何消费 ctx.model 和 ctx.flags 见Adapter。