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

# 通用贡献流程

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

## 准备变更

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

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

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

然后遵循 GitHub 的[参与项目贡献](https://docs.github.com/zh/get-started/exploring-projects-on-github/contributing-to-a-project)流程，先 fork（派生）仓库，再克隆并创建分支：

```bash theme={"system"}
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`。分支名应直接说明本次变更的主题，例如：

```text theme={"system"}
feat/add-example-benchmark
fix/daytona-image-precedence
docs/restructure-developer-guide
```

## 实现并验证

实现期间：

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

修改组件时，还应满足对应集成指南的完成标准：[Benchmark](/zh/developer_guide/extensions/benchmark/overview)、[Harness](/zh/developer_guide/extensions/harness/overview)、[Environment](/zh/developer_guide/extensions/environment/overview)、[Recipe](/zh/developer_guide/extensions/recipe_integration) 和 [Analyzer](/zh/developer_guide/extensions/analyzer_integration)。

把变更组织为原子提交，并让提交信息主题行和 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 和文档可以独立审查，应分别提交：

```text theme={"system"}
feat: add example benchmark runtime
feat: add example benchmark recipes
docs: document example benchmark evaluation
```

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

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

## 提交 PR

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

```bash theme={"system"}
git fetch upstream
git rebase upstream/main
```

首次推送分支时运行：

```bash theme={"system"}
git push --set-upstream origin feat/<short-topic>
```

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

```bash theme={"system"}
git push --force-with-lease
```

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

PR 说明应包含：

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

请求审查前，完成 [PR 检查表](/zh/developer_guide/contributing/pull_request_checklist)。

## 处理有依赖关系的变更

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

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

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