测试与验证

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

​

运行基础检查

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

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

uvx pre-commit run --files \
  src/agentcompass/<changed-module>.py \
  docs/en/<changed-page>.mdx \
  docs/zh/<changed-page>.mdx

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

uvx pre-commit run --all-files --show-diff-on-failure

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

文档变更还需要执行文档贡献中的检查。

​

按变更范围验证

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

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 配置数据类，检查自动生成的公开配置结构：

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 输出核对文档中的配置键。

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

uv run agentcompass config show \
  --config <config.yaml> \
  --benchmark <benchmark-id> \
  --harness <harness-id> \
  --env <environment-id>

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

uv run agentcompass launch <orchestration.yaml> --dry-run

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

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

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 组合时，才扩展验证范围。

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

uv run agentcompass summary <run-dir> --dry-run

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

​

记录验证证据

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

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

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