基准测试套件
Benchmark Suite 用于回答“这个 Scientific Reasoner 在固定协议下是否稳定、能否泛化、难度是否足够”等评测问题。它独立于普通 Runtime：正常研究不会知道自己是否被评测，也看不到私有 holdout。
如果你的目标只是完成一次研究，不需要 Benchmark。只有在比较 Reasoner、模型路由或版本回归时才使用本章命令。
准备环境
查看命令是否可用：
scientific-agent-bench --help
束流机器学习协议需要 Xsuite 和 PyTorch。源码安装时可以使用：
python -m pip install -e '.[beam-ml]'
若还要通过 OpenAI API 使用真实 LLM：
python -m pip install -e '.[beam-ml-llm]'
运行前还要配置所选 provider 或完成 codex login。先用普通配置做一次小运行，确认插件和模型能工作，再消耗完整 Benchmark 预算。
重复运行一个配置
最简单的评测会从同一配置创建相互隔离的 trial：
scientific-agent-bench \
--data-dir .bench-data \
run examples/beam_ml_llm.yaml \
--runs 3 \
--output reports/repeated.json
适合查看：
- 成功率以及失败类别；
- 每次运行的最终可信指标；
- action、实验、token 和时间用量；
- trial 之间是否真的使用独立运行目录。
--output 未填写时，报告写入 <data-dir>/benchmarks/latest-report.json。评测命令只有在存在有效成功结果时才返回成功退出码。
Generalization 协议
仓库中的 examples/beam_ml_benchmark.yaml 是可直接使用的冻结规格：
scientific-agent-bench \
--data-dir .bench-generalization \
generalization examples/beam_ml_benchmark.yaml \
--output reports/generalization.json \
--markdown reports/generalization.md
它会：
- 在研究开始前固定未见的 Halton holdout；
- 对若干训练样本预算分别运行研究；
- 冻结成功运行的最终 predictor；
- 在研究结束后才做 holdout 推理；
- 与固定 9-NN 基线和消融结果比较；
- 检查私有数据泄漏、研究冻结与运行隔离。
报告中的训练内指标和 holdout 指标不是同一件事。优先查看 generalization gap、各预算趋势、基线差值以及 integrity 状态，不要只摘最高分。
Difficulty 协议
难度协议加入边界富集 holdout、物理参数偏移、重复试验和置信区间。先准备私有数据：
scientific-agent-bench \
--data-dir .bench-difficulty \
difficulty benchmarks/beam_ml_v07.yaml \
--prepare-only
检查生成的 freeze 信息后再正式运行：
scientific-agent-bench \
--data-dir .bench-difficulty \
difficulty benchmarks/beam_ml_v07.yaml \
--output reports/difficulty.json \
--markdown reports/difficulty.md
再次执行同一规格会继续未完成的 replicate slot，并复用已完成且验证通过的准备工作。它不会为了方便而重跑已完成 slot。
覆盖模型设置
三个子命令都接受与 Runtime 类似的 Reasoner 覆盖项，例如：
scientific-agent-bench run examples/beam_ml_llm.yaml \
--runs 2 \
--reasoner real \
--provider codex-cli \
--model YOUR_MODEL_ID \
--temperature 0.2
覆盖模型属于被测系统元数据，不会修改冻结的数据集、目标、预算和协议哈希。如果规格明确冻结了 provider/model，冲突设置会使评测无效或被拒绝。
如何读报告
每份报告至少检查：
benchmark_version和规格哈希是否与预期一致；- Runtime、Benchmark Suite 和 prompt 版本；
- 有效、失败、恢复和跳过的运行数；
- 可信评估指标与置信区间；
- 基线、消融、边界集和物理偏移结果；
- integrity/leakage/freeze 检查是否全部通过；
- 原始 run ID，方便回到 Control Room 或 CLI 审查事件。
如果完整性检查失败，即使数值很好也不要把它当成有效 Benchmark 结果。
保持公平比较
- 比较两种 Reasoner 时使用同一个冻结 spec 和全新的输出目录。
- 不要根据一次私有 holdout 结果反复调整普通研究配置。
- 不要把 Benchmark 私有数据复制进 Runtime 输入。
- 报告均值或中位数时同时保留单次运行和失败率。
- 小样本置信区间应被当作不确定性，而不是装饰。
旧的 scientific-agent benchmark* 命令仍能兼容转发，但会提示弃用。新脚本使用 scientific-agent-bench，避免未来删除兼容层时中断。