> ## 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 集成。

## 验证阶梯

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

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

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

```text theme={"system"}
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`

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

## 代码仓库检查

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

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