跳转到主要内容
Experiment 用于比较多组运行配置。典型问题包括：Claude Code 和 Codex 谁在同一批 fixture 上 pass rate 更高？某个 prompt 改动是否降低成本？不同模型的延迟和质量如何取舍？

​
基本形状

一个实验文件 = 一个配置（一个 agent × 一个 model）。model 是单个字符串，不接受数组。要跨模型 / 跨 agent 对比，就在一个实验组文件夹里写多个文件，各钉对照轴之外的一切： 
experiments/
  compare-models/          # 实验组
    gpt-4o-mini.ts         #   一格:钉 model = gpt-4o-mini
    gpt-4o.ts              #   一格:钉 model = gpt-4o

// experiments/compare-models/gpt-4o.ts
import { defineExperiment } from "niceeval";
import { webAgent } from "../../agents/web-agent.ts";

export default defineExperiment({
  description: "AI 助手:gpt-4o",
  agent: webAgent({ baseUrl: "http://127.0.0.1:5188" }),
  model: "gpt-4o",   // 单个字符串;另一个模型就复制一份文件改这一行
  runs: 3,
});

npx niceeval exp compare-models   # 把同组各 model 并排出报告
这样每个配置独立成文件：可命名、可 diff、可单独 review，“这一组就是对照”在文件结构上就讲清楚了。

​
适合比较什么

  • 不同 agent adapters。
  • 不同模型。
  • 不同 prompts 或 feature flags。
  • 不同 sandbox 后端。
  • 同一任务的 pass@N。

​
查看结果

Experiment 输出通常按 (agent, model, eval) 维度展示： 
fixtures/button   claude-code   pass@5 = 4/5 (80%)   mean 34s
fixtures/button   codex         pass@5 = 3/5 (60%)   mean 41s
除了 pass rate，还应该看平均耗时、token、成本和失败类型。

​
设计 experiment 的建议

  • 保持 eval 集合稳定，避免比较时混入新变量。
  • 每个 cell 跑多个 attempts，尤其是非确定性 coding agent。
  • 把预算和并发写清楚。
  • 对“失败原因”做归类，不只看总分。

​
与普通运行的关系

npx niceeval exp <实验> 关注“这一批 eval 在某个配置下是否通过”；实验组关注“多组配置谁更好”。两者使用同一套 eval、agent adapter、scoring 和 artifacts。