通用贡献流程

派生 AgentCompass、开发一项聚焦变更、完成验证并提交便于审查的 PR。

AgentCompass 使用派生仓库与拉取请求工作流。每次贡献应保持聚焦，基于最新官方 main，并提供足够证据，便于维护者审查行为、兼容性和用户影响。

​

编码前

1. 搜索已有问题单和 PR，确认是否存在重叠工作。
2. 阅读架构概览，找到行为归属组件。
3. 检查当前实现、配置结构、相邻组件和公开文档。
4. 适用时，根据官方代码仓库、API、论文或 provider 文档建立上游契约。
5. 广泛契约变更或维护成本较高的集成，应先创建问题单或设计讨论。

把可复用基础设施与使用它的集成分开。例如，provider 级网络控制项或资源限制应能独立审查，而不应与单个 Benchmark 混在一起。

​

派生与克隆

遵循 GitHub 的参与项目贡献流程：

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

origin 应指向你的派生，upstream 应指向 open-compass/AgentCompass。

​

创建聚焦分支

从最新上游分支开始：

git fetch upstream
git switch --create feat/<short-topic> upstream/main

分支名应描述一个可审查的关注点：

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

不要在一个 PR 中混合无关重构、依赖升级、格式和功能工作。

​

围绕归属契约开发

实现期间：

• 把行为放在拥有它的组件中。
• 应用推断默认值前保留用户显式设置。
• 通过组件配置契约添加公共参数。
• 确定性规划代码中不能调用 provider 或 model。
• 保留错误类别，并在所有退出路径清理资源。
• 来源变更影响用户时同步更新文档。
• 绝不能提交凭证、私有端点、数据集、容器层或完整结果目录。

修改组件时使用对应集成完成标准：

• Benchmark 集成
• Harness 集成
• Environment 集成

​

编写原子提交

提交信息主题行和 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
test	测试或验证基础设施	test: cover recipe precedence
chore	维护、工具链或依赖工作	chore: update documentation tooling

提交信息主题行应简洁并使用祈使语气。避免 update code、fix issue 或把多个无关变更写进一个摘要。推荐使用如下原子提交历史：

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

​

验证变更

先运行覆盖修改契约的最小检查，再扩展到代表性端到端行为。在 PR 中记录准确命令和重要结果。

Python 格式和检查使用代码仓库当前 pre-commit 配置：

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

文档使用：

cd docs
mint broken-links
mint validate

修改导航、MDX 组件、表格、选项卡或命令示例时，还应使用 mint dev 预览。

​

文档与实现同步

变更影响公共选项、SDK 接口、组件 ID、参数、默认值、兼容性、安装、依赖、结果格式或推荐命令时，应在同一 PR 中更新文档。

• 安装和首次运行行为放在快速开始。
• 配置、操作和故障排查放在用户指南。
• 架构、实现契约、扩展规则和验证标准放在开发者指南。
• 除非维护者明确同意分阶段本地化，否则中英文页面保持相同相对路径。
• 在 docs/docs.json 中添加或删除页面，使用各语言版本相对于站点根目录的链接，并验证生成的命令。

不要让用户根据源码猜测新默认值或兼容性规则。

​

变基与推送

创建或更新 PR 前：

git fetch upstream
git rebase upstream/main

把新分支推送到派生：

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

变基已发布功能分支后，只更新该分支：

git push --force-with-lease

未与协作者协调时，绝不能 强制推送共享分支。

​

创建易于审查的 PR

PR 应说明：

• 问题，以及它为什么属于 AgentCompass。
• 归属组件和重要设计决定。
• 变更前后的用户可见行为和兼容性。
• 准确且脱敏的冒烟测试或复现命令。
• 验证结果和相关得分或产物证据。
• 与实现同步更新的文档。
• 本次范围明确不包含的工作。

兼容性矩阵和结果对比使用紧凑表格。大型输出或完整轨迹应链接稳定外部产物，不要提交到代码仓库。

​

堆叠基础与集成变更

一项贡献依赖可复用基础设施时：

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

每个 PR 摘要只描述自己的关注点。基础变更不能依赖最先使用它的 Benchmark 或 Harness。