跳转到主要内容
Runner 是把评估用例文件变成一次实际运行的执行引擎。它负责发现、过滤、调度、缓存、attempt、reporters 和 artifact 输出。

​
发现

runner 会读取 evals/ 下的：
  • *.eval.ts 文件
  • 导出评估用例数组的数据集文件
list 只发现和打印 ID，不执行评估用例。

​
过滤

exp 命令中,实验名之后的位置参数是评估用例 ID 前缀：
不要把 agent 名放进位置参数。agent/model/flags 写进 experiment。

​
并发

远程 HTTP agent 可以用更高并发；本地 Docker Sandbox 通常需要更低并发，避免 CPU、内存和磁盘竞争。

​
runs 与 early-exit

runs 用于测 pass rate。首过即停默认开启：某个 Attempt 通过后，同一 eval 的剩余 Attempt 会被停止。想拿完整的通过率分布时，用 --no-early-exit 关闭，让每个 eval 跑满 runs 次。

​
缓存

NiceEval 可以根据输入、配置和相关文件 fingerprint 跳过已判定为 passed 或 failed 的结果——两者都是判定确定的终态。errored（超时、Sandbox 异常等框架/环境层面的不确定失败）永远重试。缓存适合加速迭代，但如果你在调试非确定性行为，应该明确关闭（--force）或清理相关缓存。

​
超时和预算

超时保护单个评估用例，预算保护整次运行成本。NiceEval 只有在 Attempt 已经发起 Agent Turn、却连续拿不到成本数据时，才提示预算无法执行。如果 Attempt 在 sandbox.create 或 setup 阶段就失败，Agent 尚未运行，CLI 只显示对应的结构化执行错误，不再追加容易误导排查方向的预算警告。

​
Reporter

运行中的反馈由 --output 选择消费者模型；Reporter 负责把完成后的结果写到其它目的地。两者不是同一层：
省略时使用 auto：TTY 选择 Human，CI 环境选择 CI，其它非 TTY 选择 Agent。输出模型只改变反馈，不改变调度、判定或 artifact。 Runner 在评估用例完成后把结果交给 Reporters：
  • JSON artifacts 用于后续分析。
  • JUnit reporter 适合 CI。
  • Braintrust reporter 把一次运行作为实验上报，跨提交比较。
挂载方式和 Braintrust 配置见 Reporter 上报。

​
输出目录

每次运行会写入该实验的结果快照目录 .niceeval/<experiment>/<快照>/，包括快照级 snapshot.json，以及每个 Attempt 的 result.json（判定、断言、结构化错误、diagnostics）和按需生成的 events.json、sources.json、trace.json、o11y.json、diff.json 等拆分 artifact。瞬时 progress 不落盘。

​
推荐调试流程

  1. 先跑 npx niceeval list 确认发现结果。
  2. 用 npx niceeval exp <实验> <ID 前缀> 缩小到一个 eval。
  3. 失败后复制终端里的 locator，先运行 npx niceeval show @<locator> 看错误或断言摘要；需要 Agent 行为时再加 --execution，需要文件变化时加 --diff。
  4. 再扩大到完整 suite 或 experiment。