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

# 测试与验证

先用范围最小且可复现的检查验证所改契约，再运行一个真实任务，并记录便于审查的证据。

## 运行基础检查

公开代码仓库目前没有统一的项目测试套件、已声明的 `pytest` 工作流或 CI 测试任务，当前 PR 工作流只运行 `pre-commit`。除非变更新增了真实测试目标且实际运行过，否则不能把笼统的 `pytest` 命令列为代码仓库的验证结果。这不降低正确性要求；仍应结合现有静态检查、组件发现、配置检查、必要的确定性检查和有代表性的单任务执行来验证变更。

开发期间，对修改的文件运行 `pre-commit`：

```bash theme={"system"}
uvx pre-commit run --files \
  src/agentcompass/<changed-module>.py \
  docs/en/<changed-page>.mdx \
  docs/zh/<changed-page>.mdx
```

请求审查前，运行当前 CI 工作流使用的同一条完整命令：

```bash theme={"system"}
uvx pre-commit run --all-files --show-diff-on-failure
```

已配置的钩子会运行 Flake8、isort、YAPF、空白和换行检查、YAML 验证、依赖文件排序以及合并冲突检测。部分钩子会修改文件；应检查差异并重新运行，直到命令成功且没有意外改动。

文档变更还需要执行[文档贡献](/zh/developer_guide/contributing/documentation)中的检查。

## 按变更范围验证

先根据当前安装版本检查组件与配置，不能依赖记忆中的组件列表：

```bash theme={"system"}
uv run agentcompass list benchmark
uv run agentcompass list harness
uv run agentcompass list env
uv run agentcompass list analyzer
```

这些命令可以确认软件包导入时注册装饰器能够正常执行、预期组件已经注册且 ID 不重复；它们不能验证凭证、依赖、provider 可用性、兼容性或任务执行。

对于 Benchmark、Harness 或 Environment 配置数据类，检查自动生成的公开配置结构：

```bash theme={"system"}
uv run agentcompass config docs benchmark <benchmark-id>
uv run agentcompass config docs harness <harness-id>
uv run agentcompass config docs env <environment-id>
```

确认字段名、类型、默认值和说明与实现一致。`config docs` 不支持 Analyzer 的 `conf` 字典和 Recipe 类；对于这些内容，应对照源码和 runtime 输出核对文档中的配置键。

在不启动评测的情况下检查合并后配置：

```bash theme={"system"}
uv run agentcompass config show \
  --config <config.yaml> \
  --benchmark <benchmark-id> \
  --harness <harness-id> \
  --env <environment-id>
```

多请求编排文件可以使用以下试运行命令：

```bash theme={"system"}
uv run agentcompass launch <orchestration.yaml> --dry-run
```

`agentcompass run` 没有 `--dry-run` 选项。编排试运行会验证并输出解析后的请求，但不会加载 Benchmark 任务、打开 Environment、执行 Harness、对结果评分或证明清理行为，因此不能替代单任务冒烟运行。

再运行一个已知任务。选择本地可用的公开 Benchmark 和稳定任务 ID，并尽量减少无关变量：

```bash theme={"system"}
uv run agentcompass run \
  <benchmark-id> \
  <harness-id> \
  "$MODEL_NAME" \
  --env <environment-id> \
  --benchmark-params '{"sample_ids":["<task-id>"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --task-concurrency 1 \
  --max-retries 0 \
  --progress plain \
  --log-level DEBUG
```

应使用该 Benchmark 文档明确支持的组件组合和专属参数。首次诊断时保持 `--max-retries 0`，避免重试掩盖第一次失败。分享命令前必须删除凭证和私有端点信息。

根据变更内容检查生成的 `run_info.json`、`params.json`、`details/`、`summary.md` 和运行日志。仅凭进程退出不能证明结果正确；还应验证任务 ID、解析后的执行计划、状态、错误类别、最终答案或产物、Benchmark 得分、清理事件以及汇总指标使用的分母。

最后只补充所改范围特有的验证：

| 变更类型         | 专属关注点                                                             |
| ------------ | ----------------------------------------------------------------- |
| Benchmark    | 任务准备结果和参考答案；精确任务选择；成功路径和代表性评测失败路径下的状态、得分结构与产物                     |
| Harness      | 支持的 Model 协议和依赖路径；规范化最终答案、轨迹、工具调用与指标；超时和错误映射；会话清理                 |
| Environment  | 打开、执行，以及支持的传输和网络切换；超时与关闭行为；注入失败后没有资源泄漏                            |
| Recipe       | 匹配与不匹配输入；`applied_recipes` 中包含预期 ID；解析后的回退值；兼容的用户显式设置未被覆盖         |
| Analyzer 与结果 | 数据集和输入数据满足声明要求；预期 `analysis_result` 数据；跳过与错误路径；新旧持久化结果；汇总文件包含声明字段 |
| runtime 与配置  | CLI、SDK 和配置输入的请求解析结果一致；覆盖优先级；重试、取消、持久化、清理以及受影响的公开 Environment 组合  |

涉及生命周期或兼容性时，还应检查相关边界，例如可选输入与必需输入、有效零分与评测器失败，或超时、取消后的清理。持久化状态和错误必须能够区分 Harness、Environment 与 Model 故障，不能把不同失败统一成一个通用异常。只有共享 runtime 变更会影响其他公开 Environment 组合时，才扩展验证范围。

有意重写汇总前，先运行：

```bash theme={"system"}
uv run agentcompass summary <run-dir> --dry-run
```

如果变更只涉及解析、合并、匹配、执行计划转换、聚合或序列化逻辑，应在 PR 中补充范围更小的确定性检查。如果没有可复用的测试框架，应提供实际运行的准确命令、调用方式或小型夹具，不能把它描述成自动化测试套件。

## 记录验证证据

PR 中记录的每项检查都应包含：

* 完整且已脱敏的命令、验证所用提交版本、相关依赖或 provider 版本，以及所选公开 Benchmark、任务 ID、Harness、Environment 和 Model 协议；
* 检查结果（通过或失败），以及重要的输出字段或产物路径；
* 未运行的检查、具体原因及其对风险判断的影响；
* 得分对比所使用的任务范围、设置和分母。

不能提交凭证、私有端点、已下载数据集、完整结果目录或大型轨迹。审查者需要更多信息时，应使用小型脱敏摘录或稳定外部产物。