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

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

## 编码前

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

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

## 派生与克隆

遵循 GitHub 的[参与项目贡献](https://docs.github.com/zh/get-started/exploring-projects-on-github/contributing-to-a-project)流程：

```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
```

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

## 创建聚焦分支

从最新上游分支开始：

```bash theme={"system"}
git fetch upstream
git switch --create feat/<short-topic> upstream/main
```

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

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

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

## 围绕归属契约开发

实现期间：

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

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

* [Benchmark 集成](/zh/developer_guide/benchmark_integration)
* [Harness 集成](/zh/developer_guide/harness_integration)
* [Environment 集成](/zh/developer_guide/environment_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`  |
| `test`     | 测试或验证基础设施     | `test: cover recipe precedence`         |
| `chore`    | 维护、工具链或依赖工作   | `chore: update documentation tooling`   |

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

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

## 验证变更

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

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

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

文档使用：

```bash theme={"system"}
cd docs
mint broken-links
mint validate
```

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

## 文档与实现同步

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

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

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

## 变基与推送

创建或更新 PR 前：

```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 应说明：

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

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

## 堆叠基础与集成变更

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

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

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