通用贡献流程

AgentCompass 采用派生仓库后提交 PR 的贡献流程。本页说明如何准备一项范围明确的变更、按组件契约实现并验证，以及提交便于审查的 PR；测试和文档的专项规则由对应指南维护。

​

准备变更

编码前，先确认范围与契约：

1. 搜索已有问题单和 PR，确认是否存在重叠工作。
2. 阅读架构概览，确定应由哪个组件负责这项行为。
3. 检查当前实现、配置结构、相邻组件和公开文档。
4. 如果变更依赖外部项目，根据其官方代码仓库、API、论文或 provider 文档确认上游契约。
5. 如果契约变更影响范围较广，或新集成会带来较高的维护成本，先创建问题单或发起设计讨论。

每个 PR 只处理一个明确问题，不要混入无关的重构、依赖升级、格式调整或功能变更。

然后遵循 GitHub 的参与项目贡献流程，先 fork（派生）仓库，再克隆并创建分支：

git clone https://github.com/<your-user>/AgentCompass.git
cd AgentCompass

git remote add upstream https://github.com/open-compass/AgentCompass.git
git fetch upstream
git remote -v
git switch --create feat/<short-topic> upstream/main

origin 应指向你的派生仓库，upstream 应指向 open-compass/AgentCompass。分支名应直接说明本次变更的主题，例如：

feat/add-example-benchmark
fix/daytona-image-precedence
docs/restructure-developer-guide

​

实现并验证

实现期间：

• 把行为实现放在负责它的组件中。
• 推断默认值时，不得覆盖用户的显式设置。
• 新增公开参数时，将其放入对应的组件配置契约。
• 确定性规划代码不得调用 provider 或 Model。
• 保留错误类别，并在所有退出路径清理资源。
• 变更影响公开行为时，在同一 PR 中更新文档；具体规则见文档贡献。
• 绝不能提交凭证、私有端点、数据集、容器层、完整结果目录或大型生成产物。

修改组件时，还应满足对应集成指南的完成标准：Benchmark、Harness、Environment、Recipe 和 Analyzer。

把变更组织为原子提交，并让提交信息主题行和 PR 标题使用相同的变更类型前缀：

前缀	用途	示例
feat	新增用户可见行为或组件支持	feat: add example benchmark
fix	正确性、兼容性或回归修复	fix: preserve explicit task images
docs	仅文档变更	docs: add benchmark integration guide
style	不改变行为的格式	style: normalize code formatting
refactor	行为等价的内部重构	refactor: simplify result processing
chore	维护、工具链或依赖工作	chore: update documentation tooling

主题行应简洁并使用祈使语气。避免使用 update code、fix issue 这类含糊表述；如果实现、Recipe 和文档可以独立审查，应分别提交：

feat: add example benchmark runtime
feat: add example benchmark recipes
docs: document example benchmark evaluation

先运行能够直接验证所改契约的最小检查，再根据风险扩展到有代表性的真实任务和相关失败路径。请求审查前，完成代码仓库要求的完整检查，并在 PR 中记录准确且已脱敏的命令、相关版本、关键结果，以及未执行的必要检查及其原因和风险。

根据变更类型选择检查、任务证据和边界场景，见测试与验证；涉及公开页面、导航、示例或本地化时，同时遵循文档贡献。

​

提交 PR

创建或更新 PR 前，把分支变基到最新的 upstream/main：

git fetch upstream
git rebase upstream/main

首次推送分支时运行：

git push --set-upstream origin feat/<short-topic>

如果已推送的个人功能分支经过变基，使用以下命令更新该分支：

git push --force-with-lease

未经协作者同意，不要强制推送共享分支。

PR 说明应包含：

• 要解决的问题、本次变更的范围，以及明确不处理的内容。
• 负责该行为的组件、重要设计决定，以及变更前后的用户可见行为和兼容性。
• 准确且已脱敏的复现或验证命令、关键结果和必要的产物证据。
• 与实现同步更新的文档。

请求审查前，完成 PR 检查表。

​

处理有依赖关系的变更

如果一项集成依赖可复用的基础设施变更，应把两者拆成独立 PR，使基础设施可以独立审查和复用：

1. 从 upstream/main 创建基础分支并提交基础 PR。
2. 在基础分支上创建集成分支，只用于本地组合测试和后续集成 PR。
3. 基础 PR 合并后，把集成分支变基到更新后的 upstream/main。
4. 检查提交范围，重新运行受影响的验证，再通过 --force-with-lease 更新个人集成分支。

每个 PR 只描述自身范围，并明确依赖关系和合入顺序。基础变更不能依赖最先使用它的 Benchmark 或 Harness。