深入解读 aider 项目贡献指南：从开发环境搭建到测试与依赖管理

导读

aider 是一款运行在终端中的 AI 结对编程工具（AI pair programming in your terminal），支持与 Claude、GPT、DeepSeek 等 LLM 结对，在一个已有代码库上直接以自然语言对话完成编码任务。本项目以 CONTRIBUTING.md 为官方贡献入口，系统规定了外部开发者提交 Bug 报告、功能请求与 Pull Request 的完整流程。本篇基于该文档并结合仓库中的源码与配置文件，为有意参与 aider 开发的贡献者提供一份端到端指南：如何在干净环境中克隆并搭建可编辑的开发环境、遵守代码风格与无类型注解的编码规范、正确运行与编写 pytest 测试、用 pip-tools/uv 流程管理依赖，以及构建 Docker 镜像与 Jekyll 文档站。

一、贡献入口与总体协作流程

1.1 三类受欢迎的贡献形式

根据 CONTRIBUTING.md，项目欢迎以三种形式参与贡献：

1. Bug 报告（bug reports）：请在 GitHub Issues 中提交，便于维护者跟踪问题并讨论潜在的解决方案或增强点；
2. 功能请求（feature requests）：同样通过 Issues 提交；
3. Pull Request（PR）：小改动可直接提交 PR；如果涉及较大或影响深远的功能变更，请先在一个 Issue 中与维护者讨论，再着手实现，以避免返工并确保改动能够平滑合入。

把 Bug 与功能请求沉淀为 Issue，可以让讨论过程公开可追溯，这是仓库协作的基础约定。

1.2 LLM 代码编辑基准结果的贡献通道

aider 的一个特色是围绕“LLM 修改既有代码的能力”建立了可量化的评测体系。仓库在 benchmark/README.md 中说明：其评测基于 Exercism 编码练习，评估自然语言编码请求能否被翻译为「可执行且通过单元测试」的文件内容，即端到端检验 LLM 的编码能力，以及它是否能把代码编辑格式化成 aider 可以落盘的格式。

CONTRIBUTING.md 明确邀请社区贡献 LLM 基准结果（LLM benchmark results）：

• 运行方式与评测参数见 benchmark/README.md；
• 提交方式为「修改 leaderboard 结果数据文件并打开一个 PR」，这些 YAML 数据位于 aider/website/_data 目录。

实际打开该目录，可以看到 polyglot_leaderboard.yml、edit_leaderboard.yml、refactor_leaderboard.yml、o1_polyglot_leaderboard.yml 等文件——它们是官方排行榜的数据源。参考 benchmark/README.md 中的示例，一条评测记录是一个 YAML 条目，包含 model、edit_format、pass_rate_1、pass_rate_2、commit_hash、seconds_per_case、total_cost 等字段，其中以 pass_rate_#（全部测试通过的任务百分比）为核心指标；同时记录 commit_hash（评测时仓库的 git 哈希，若有未提交改动会标注 (dirty)），以便可靠复现每次评测。因此提交结果前养成「先 commit 再跑评测」的习惯是有意义的。注意：基准评测工具链会执行 LLM 生成的未经人工审查的代码，必须在 Docker 容器内运行以限制潜在危害，且这些脚本主要面向维护者而非普通终端用户（详见 benchmark/README.md）。

1.3 许可协议

在提交 PR 之前，请先审阅项目的 Individual Contributor License Agreement（个人贡献者许可协议），文档原文位于 aider/website/docs/legal/contributor-agreement.md。所有贡献者都将在 PR 流程中受邀完成该协议，这为代码合入与后续使用扫清了授权障碍。项目本身采用 Apache License，仓库根目录下的 LICENSE.txt 即为许可证全文。

二、搭建可编辑的开发环境

CONTRIBUTING.md 建议把虚拟环境创建在仓库目录之外，以保证开发环境隔离、同时避免污染仓库工作区。

2.1 克隆仓库

git clone https://github.com/Aider-AI/aider.git
cd aider

2.2 创建并激活虚拟环境

使用 Python 3.9 及更高版本内置的 venv 模块（仓库根目录 pyproject.toml 的 requires-python = ">=3.10,<3.15" 与文档所称 3.9~3.12 的支持范围互为印证）：

python -m venv /path/to/venv

激活方式因平台而异：

• Windows：

  /path/to/venv/Scripts/activate
  

• Unix / macOS：

  source /path/to/venv/bin/activate
  

2.3 以可编辑模式安装项目

以可编辑模式（editable mode）安装，改动源码后无需重新安装包即可立即生效：

pip install -e .

该命令读取根目录 pyproject.toml 的 [project] 配置：包名为 aider-chat，动态依赖取自根目录 requirements.txt，同时定义控制台脚本入口 aider = "aider.main:main"。安装后，命令行工具 aider 直接可用。

2.4 安装运行时依赖与开发依赖

pip install -r requirements.txt

开发工作至少还应安装开发依赖：

pip install -r requirements/requirements-dev.txt

requirements 目录按用途拆分了多份依赖清单：除了根目录清单，还有 requirements-dev.in/.txt（开发依赖）、requirements-help.*（帮助文档相关）、requirements-browser.*（浏览器/截图功能）、requirements-playwright.*（Playwright 浏览器自动化），以及 common-constraints.txt、python-compat.in、pydub.in、tree-sitter.in 等补充文件。如果开发内容涉及这些可选能力，应一并对口安装。这些 .txt 锁文件均由 scripts/pip-compile.sh 生成并提交入库（详见下文「依赖管理」）。

2.5 安装 Pre-commit 钩子（可选但推荐）

项目使用 pre-commit 钩子做代码格式化与静态检查。安装后，每次 git commit 都会自动运行钩子：

pre-commit install

根目录 .pre-commit-config.yaml 显示该项目实际启用了四类钩子：isort（import 排序，采用 --profile black）、black（代码格式化，--line-length 100）、flake8（静态检查，--show-source）与 codespell（拼写检查）。也就是说，文档章节「编码规范」中强调的格式约定全部由这套钩子落地执行。

2.6 一条命令完成全套安装（macOS/Linux）

以下命令把上述步骤串成一条链，便于在类 Unix 系统上一键完成：

python3 -m venv ../aider_venv \
 && source ../aider_venv/bin/activate \
 && pip3 install -e . \
 && pip3 install -r requirements.txt \
 && pip3 install -r requirements/requirements-dev.txt

至此即拥有一个可用的 aider 开发环境，可以开始改代码、跑测试。

2.7 构建 Docker 镜像

仓库在 docker/Dockerfile 中提供了两阶段 Dockerfile：aider（基础镜像）与 aider-full（额外含 help/browser/Playwright 等可选依赖与 boto3、torch CPU 版）。按 CONTRIBUTING.md 的说明构建镜像：

docker build -t aider -f docker/Dockerfile .

从 docker/Dockerfile 可见其默认基于 python:3.12-slim-bookworm，在镜像内创建 /venv 虚拟环境、以 UID 1000 创建 appuser，并设置 HOME=/app 以便把容器内 ~/.aider 的缓存落到宿主机当前项目目录而不是随容器退出被丢弃，最终入口为 /venv/bin/aider。

2.8 本地构建文档站（Jekyll）

项目的文档站由 Jekyll 构建并托管在 aider/website 目录下。本地构建步骤：

1. 安装 Ruby 与 Bundler（若尚未安装）；

2. 进入 aider/website 目录；

3. 安装所需 gems：

   bundle install
   

4. 构建文档：

   bundle exec jekyll build
   

5. 边编辑边预览（可选）：

   bundle exec jekyll serve
   

构建产物输出到 aider/website/_site 目录。aider/website/Gemfile 与 scripts/jekyll_build.sh 提供了 Gem 清单与一键构建脚本，可作为本地构建的参考入口。

三、编码规范

3.1 支持的 Python 版本与语言约束

• Python 兼容性：文档声明 aider 支持 Python 3.9、3.10、3.11 与 3.12；提交代码时需保证兼容这些受支持的版本。仓库根目录 pyproject.toml 将 requires-python 声明为 >=3.10,<3.15，并在 classifiers 中同时列出了 3.10~3.14，二者共同刻画了当前官方支持与打包环境的大致范围。
• 不使用类型注解（No Type Hints）：这是本项目明确的技术取向——代码不采用 Python 类型提示，贡献者应遵循既有风格，不要在新增代码中引入类型注解。

3.2 代码风格

项目遵循 PEP 8，单行最大长度 100 字符；import 排序使用 isort，代码格式化使用 Black。请在提交前安装 pre-commit 钩子，以便自动完成这些格式化工作。

这些约定在配置层面同样可见：根目录 .pre-commit-config.yaml 中 black 钩子的参数即 --line-length 100，与文档的 100 字符上限一致；flake8 负责行宽与编码规范的静态校验。此外 pyproject.toml 还开启了 codespell 配置（跳过 *.svg、Gemfile.lock、tests/fixtures/*、aider/website/assets/* 等文件），作为拼写检查的第二道防线。

四、测试体系

4.1 测试框架与目录约定

项目使用 pytest 运行单元测试。测试文件位于 tests 目录，命名遵循 test_*.py 约定。目录按被测范围分层：tests/basic 覆盖核心模块（如 test_coder.py、test_repomap.py、test_udiff.py），另有 tests/help、tests/browser、tests/scrape 与存放跨语言标签查询样例的 tests/fixtures。

根目录 pytest.ini 给出了官方测试运行配置：默认 testpaths 依次指向 tests/basic、tests/help、tests/browser、tests/scrape，并通过 addopts = -p no:warnings 关闭告警噪音、通过环境变量 AIDER_ANALYTICS=false 在测试中禁用遥测统计。

4.2 运行测试

在项目根目录直接运行整套测试：

pytest

也可以只跑特定测试文件或测试用例：

pytest tests/basic/test_coder.py
pytest tests/basic/test_coder.py::TestCoder::test_specific_case

编写新功能或修改既有代码时，应补充与之匹配的测试以维持覆盖率；Mock 数据与测试数据建议就近放入测试文件，或在 tests/ 内新增独立的 fixtures 或工具函数。

4.3 持续集成

项目使用 GitHub Actions 做 CI，CONTRIBUTING.md 提到两类测试工作流：

• ubuntu-tests.yml：在 Ubuntu 上针对 Python 3.9~3.12 运行测试；
• windows-tests.yml：在 Windows 上运行测试。

两类工作流在向 main 分支推送或发起 PR 时触发，并忽略仅涉及 aider/website/** 与 README.md 的改动。另有 docker-build-test.yml 负责在每个推送/PR 事件时构建 Docker 镜像（检出代码、准备 Docker、登录 DockerHub、构建但不推送），以验证镜像可随时产出。

需要说明的是，当前仓库快照未包含 .github/workflows/ 目录内容，以上描述以 CONTRIBUTING.md 所述为准；CI 配置的细节建议以实际仓库中该目录下的 YAML 文件为最终依据。

五、依赖管理：.in 与 .txt 的双文件工作流

引入新依赖时，不要直接改锁文件，而是遵循「源码清单 + 编译锁定」的两层结构：

1. 把新依赖加入合适的 requirements.in 清单：主依赖写进根目录 requirements.in，开发依赖写进 requirements-dev.in，其余可选能力写入对应的 requirements-*.in；

2. 重新编译生成对应的 requirements.txt：

   pip install pip-tools
   ./scripts/pip-compile.sh
   

pip-compile.sh 支持透传一个参数给 pip-compile，例如全量升级依赖时：

./scripts/pip-compile.sh --upgrade

实际执行依赖编译的是 scripts/pip-compile.sh，从其实现可以看到该项目当前基于 uv pip compile 构建完整依赖链：先编译出全量共用的 requirements/common-constraints.txt 以保证所有子清单版本互不冲突；随后编译主依赖生成临时清单，再将 tree-sitter、numpy、scipy 三类特殊依赖交由 tree-sitter.in、python-compat.in、pydub.in 单独归并进根目录 requirements.txt；最后循环编译 dev、help、browser、playwright 四份后缀清单。因此，贡献者在本地对 .in 的任何增删，都应通过该脚本重新生成 .txt 并随 PR 一并提交。

注：CONTRIBUTING.md 原文示例写作 pip install pip-tools + ./scripts/pip-compile.sh，而仓库当前 scripts/pip-compile.sh 内部已切换为 uv pip compile 的实现；实际提交依赖变更时，请以仓库内当前脚本的实现为准。

六、Pre-commit 钩子进阶用法

安装钩子后它们会在每次 git commit 时自动执行；需要手动触发（例如对全部存量文件跑一遍检查）时可运行：

pre-commit run --all-files

.pre-commit-config.yaml 中按序注册的 isort、black、flake8、codespell 会依次处理暂存内容，任何一条失败都会阻断提交。建议开发流程为：pre-commit install → 修改代码 → 提交时由钩子自动整理 import 与格式 → 需要时用 pre-commit run --all-files 对全仓做一次性体检。

七、从文档到仓库：贡献者行动清单

把上面所有要点收敛成一份可直接执行的自检清单：

1. 先讨论后动手：大改动先在 Issue 中沟通，小改动可直接提交 PR；
2. 环境就绪：仓库外建 venv → pip install -e . → 安装根目录 requirements.txt 与 requirements/requirements-dev.txt；
3. 格式化合规：安装 .pre-commit-config.yaml 钩子，遵守 PEP 8、100 字符行宽、isort + Black 格式，且不写类型注解；
4. 测试护航：针对改动在 tests 补 test_*.py，根目录执行 pytest（配置见 pytest.ini）；
5. 依赖合规：新依赖写入 requirements 下对应的 .in 文件，并用 scripts/pip-compile.sh 重新生成锁文件后一并提交；
6. 可选验证：按需在本地构建 Docker 镜像（docker/Dockerfile）或 Jekyll 文档站（aider/website，产物在 _site）；
7. 授权与来源：审阅 aider/website/docs/legal/contributor-agreement.md；若贡献 LLM 基准结果，则修改 aider/website/_data 下的 leaderboard YAML 数据文件并提交 PR。

遵循这套规范，既能降低维护者的评审成本，也能让你的代码改动更快、更稳地合入这个「用 AI 结对编程」的开源项目。