> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 验证与对齐

按照从针对性检查到官方结果对齐的顺序，逐步验证 Benchmark 集成。

使用共享的[测试与验证指南](/zh/developer_guide/contributing/testing)区分代码仓库检查、组件发现、手动冒烟运行，以及依赖外部基础设施的验证证据。

## 验证阶梯

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

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

冒烟测试必须使用真实任务产物和官方评测器，并覆盖以下流程：

```text theme={"system"}
加载任务
  -> 创建 Environment
  -> 准备 Benchmark
  -> 执行 Harness
  -> 收集产物
  -> 评测
  -> 持久化结果
```

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

## provider 与优先级矩阵

对每个与该 Benchmark 配套的 Recipe、provider 和受支持版本，逐项验证以下组合：

| 输入                       | 预期解析结果                    |
| ------------------------ | ------------------------- |
| 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：** 准确的复现命令；除密钥改用环境变量引用外，其余参数均应完整保留。

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

> ✅ 已对齐 · ⚠️ 差异已说明，预计不会实质影响结果 · ❌ 未对齐

解释得分前，必须根据日志对每个未成功的任务分类。不要把失败任务隐藏在平均值中，也不要将仅包含正常完成任务的结果，与官方使用全部任务作为分母的结果直接比较。

## 代码仓库检查

```bash theme={"system"}
uvx pre-commit run --all-files --show-diff-on-failure
cd docs
mint broken-links
mint validate
```

开发 Benchmark 适配器时，可以运行针对该适配器的本地测试。请遵循当前代码仓库的测试策略，并在 PR 中记录可复现的命令和结果。