> ## 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.

# 验证与对齐

通过原语、优先级、资源、网络、清理和并发测试，确认 Environment 的实际行为与声明一致。

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

## 原语契约测试

在真实 provider 提供的 Environment 中验证：

* 列表形式命令和字符串命令的执行、标准输出、标准错误、非零返回码、超时、工作目录和环境变量。
* 文件与嵌套目录上传/下载、文本读取/写入、缺失路径和路径引用。
* 工作区创建和文档所声明的默认工作区根目录。
* provider 支持端点时，验证端点发现行为。
* 成功、命令错误、超时、取消和部分启动后的会话关闭。

不能只根据模拟 SDK 声称兼容性。

## 配置来源、资源与覆盖矩阵

验证自动推断和显式配置两条路径：

| 场景                | 预期行为                      |
| ----------------- | ------------------------- |
| 提供 provider 原生选择器 | 优先于镜像和任务元数据               |
| 提供显式镜像            | 没有原生选择器时优先                |
| 只有任务镜像            | 兼容 Recipe 将其映射给 provider  |
| 资源默认值 + 显式覆盖      | 显式字段优先，其他任务默认值保留          |
| 显式工作区             | Recipe 和 provider 默认值不得替换 |
| 无效互斥字段            | sandbox 启动前报错并说明解决办法      |

同时核对解析后的执行计划与真实 sandbox 配置是否一致。如果 provider 支持 CPU 和内存限制，应验证限制确实生效；对于文档声称支持的磁盘或 GPU 行为，也要提供实际证据。

## 网络强制执行矩阵

为每个声明的模式：

1. 证明 `public` 能访问获准测试目标。
2. 证明 `no-network` 在传输层拒绝真实出站请求。
3. 对 `allowlist`，证明一个允许目标成功、一个拒绝目标失败。
4. 测试每种文档声明的主机名、通配符、IPv4、IPv6 或 CIDR 条目类型。
5. 声明动态切换时，测试“基线阶段 → 运行阶段 → 评测阶段 → 基线阶段”的切换。对于 `fresh`，证明 provider `open()` 使用基线策略，且只有 `benchmark.evaluate()` 使用评测策略。
6. 确认关闭和失败启动后移除策略和代理资源。

不要使用敏感生产环境端点作为测试目标。检查日志与结果元数据是否泄漏凭证。

## 端到端与并发验证

先以并发 `1` 运行一个真实的 Benchmark/Harness 任务，再运行小型并发批次。如果 provider 声称支持 Recipe 工作流，至少选择一个由 Recipe 提供任务镜像和工作区的 Benchmark，并完成一次正常任务验证。

并发运行应覆盖 provider 启动速率限制、资源名称唯一性、会话隔离、资源清理、SDK 异步行为、配额错误和取消。确认一个 Environment 失败时，不会关闭或破坏另一个任务会话。

验证新 provider 时，如果条件允许，应使用相同的 Model、Benchmark、Harness、镜像、资源和网络策略，与现有 provider 比较任务结果和收集的产物，并解释 provider 专属差异。

## PR 证据

包含：

* 官方 provider API 或 SDK 版本和链接。
* 支持功能和网络矩阵。
* 脱敏后的已解析配置和冒烟测试命令。
* 原语、资源、网络、清理和并发结果。
* Recipe 自动配置和显式覆盖的验证结果。
* 更新后的 Environment 和受影响 Benchmark 文档。

## 代码仓库检查

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