验证与对齐

从专用检查到完整官方结果对齐，验证 Benchmark 集成。

​

验证阶梯

前一级通过后再扩大验证范围：

1. 导入、注册表、配置解析、版本验证和任务选择。
2. 数据集转换、评测器整形、Recipe 和密钥脱敏的专用检查。
3. 并发为 1、关闭重试的单个真实端到端冒烟测试任务。
4. 每个声称支持的 Environment 和推荐 Harness 路径至少一个代表性任务。
5. 每个 provider 的 Recipe 自动路径和显式覆盖路径。
6. 受限网络行为的强制执行测试。
7. 使用官方或推荐配置运行完整官方数据划分。
8. 与公开官方结果进行得分和失败对齐。
9. 代码仓库检查和文档验证。

冒烟测试任务必须使用正常产物和官方评测器，覆盖：

task loading
  -> environment creation
  -> benchmark preparation
  -> harness execution
  -> artifact collection
  -> evaluation
  -> result persistence

不要使用合成空任务，也不要用模拟 Recipe 检查代替真实 sandbox 运行。

​

provider 与优先级矩阵

验证每个相邻 Recipe、provider 和支持的 Benchmark 版本：

输入	预期解析结果
provider 原生选择器 + 显式/任务镜像	provider 原生选择器
显式镜像 + 任务镜像	显式镜像
只有任务镜像	任务镜像
没有镜像来源	文档声明的回退，或提前给出可操作错误
显式与任务资源	显式值逐字段优先；缺少字段继承任务默认值
显式工作区 + Recipe 默认值	显式工作区

自定义镜像提供 Harness 前置条件时，同时确认解析后计划和真实 Harness 启动。

​

网络与安全验证

执行受限时，从 sandbox 内发起真实请求。no-network 必须在传输层失败；agent 遵从指令不是证据。allowlist 需要证明一个允许目标成功、一个拒绝目标失败。存在已知利用场景时，应包含过去暴露含答案材料的目标位置。

确认密钥、代理 URL、令牌和内部端点已脱敏，且失败清理会清理临时网络、代理和 sandbox 资源。

​

完整评测

至少使用一个官方代码仓库、论文、技术报告、博客或排行榜采用的 model 与 Harness 设置，运行完整官方数据划分。对齐所有重要维度：

• 数据集版本、修订版本、数据划分、类别、语言和任务数量。
• model 检查点、端点协议、温度、推理模式和请求体。
• Harness 版本、提示词、安装模式、步骤和成本行为。
• Environment 镜像、工作区、资源、provider 和网络策略。
• 任务、命令和验证器超时；重试；每个任务的尝试数；聚合。

如果目标是每题一次尝试，使用 k=1。框架重试与 Benchmark 采样必须分开。任务覆盖范围、失败分母、model 设置或评测器版本不同却没有明确解释时，不得声称运行已对齐。

​

对齐报告

除非重新运行历史实质影响可比性，否则把最终权威结果集作为一次评测报告。报告必须包含：

1. 结果摘要： 完整分母、正常完成任务、评测器通过/失败、基础设施错误、主要得分和有意义的类别/数据划分结果。
2. 配置对齐矩阵： 官方与 AgentCompass 的 Model、Benchmark、数据集、Harness、提示词、推理、超时、资源、provider、网络、k、重试和聚合设置。
3. 官方结果比较： 引用来源、官方得分和间隔、运行数量、有效尝试、观察到的得分、绝对变化量，以及比较是点对点还是单次运行到分布。
4. 效率与轨迹比较： 官方产物提供时，比较时长、步骤、词元和重要差异。
5. 策略强制执行与可靠性： 解析后网络策略、观察到的阻塞访问权限和分类 runtime 失败。
6. 结论： 通过/总数、百分比、基础设施错误数量、对齐判定结果和剩余差异。
7. 附录 A： 可访问的脱敏评测产物下载链接。
8. 附录 B： 准确的复现命令，只把密钥替换为环境变量引用。

对齐状态列使用 ✅、⚠️ 和 ❌，并在表格后立即添加图例：

✅ Aligned · ⚠️ Explained difference expected not to materially affect the result · ❌ Not aligned

解释得分前，必须根据日志分类每个非成功任务。不要把失败任务隐藏在平均值中，也不要只用正常完成任务与官方全部任务分母比较。

​

代码仓库检查

uvx pre-commit run --all-files --show-diff-on-failure
cd docs
mint broken-links
mint validate

开发 Benchmark 适配器时可以使用专用本地测试。遵循当前代码仓库测试策略，并在 PR 中记录可复现命令和结果。