概述

Aider 是一个创新的开源 AI 结对编程工具，旨在通过人工智能技术提升软件开发效率。它是一个基于命令行的工具，允许开发者直接在本地 git 仓库中与 AI 模型协作编写代码。

资料来源：aider/README.md:1-50

Aider 的核心设计理念是将大型语言模型（LLM）的强大能力与传统的版本控制系统相结合，为开发者提供一个全新的编程工作流。

核心特性

多模型支持

Aider 支持多种主流 AI 模型后端，包括：

资料来源：aider/llms.py:1-100

深度 Git 集成

Aider 与 Git 版本控制系统深度集成，提供了以下功能：

• 自动提交：AI 每次修改后自动创建有意义的提交信息
• 差异对比：支持查看 AI 修改的代码差异
• 分支管理：可以在不同分支上进行开发
• 历史回溯：通过 git 操作回溯代码历史

资料来源：aider/coder.py:50-150

系统架构

组件架构图

graph TD
    A[用户终端] --> B[Aider CLI]
    B --> C[命令解析器]
    C --> D[聊天控制器]
    D --> E[LLM 适配器]
    E --> F[代码编辑器]
    F --> G[Git 集成层]
    G --> H[文件系统]
    E --> I[AI 模型服务]
    I --> E

核心模块说明

资料来源：aider/main.py:1-80

工作流程

典型使用流程

graph LR
    A[初始化项目] --> B[启动 Aider]
    B --> C[发送编程请求]
    C --> D{AI 理解意图}
    D -->|理解成功| E[生成/修改代码]
    D -->|理解失败| F[请求澄清]
    E --> G[代码审查]
    G --> H[自动 Git 提交]
    H --> I[返回结果]

1. 初始化阶段：用户通过命令行启动 Aider 并指定要编辑的仓库
2. 对话阶段：用户通过自然语言描述编程需求
3. 生成阶段：AI 模型理解需求后生成或修改代码
4. 验证阶段：用户确认或让 AI 迭代修改
5. 提交阶段：修改自动以 git 提交的形式保存

资料来源：aider/chat.py:100-200

安装与配置

环境要求

• Python 3.8 或更高版本
• Git 版本控制工具
• 对应的 AI 模型 API 密钥

快速开始

# 安装 Aider
pip install aider-chat

# 配置 API 密钥
export OPENAI_API_KEY=your-key-here
# 或
export ANTHROPIC_API_KEY=your-key-here

# 在 git 仓库中启动
cd your-project
aider

资料来源：aider/README.md:100-150

配置文件

Aider 通过以下方式管理配置：

资料来源：aider/main.py:80-150

技术亮点

智能代码编辑

Aider 采用先进的提示工程技术，能够：

• 准确理解用户的编程意图
• 保持代码风格一致性
• 遵循项目现有的编码规范
• 正确处理多文件依赖关系

资料来源：aider/coder.py:150-250

安全与隐私

• 所有代码处理在本地完成
• API 密钥通过环境变量管理
• 支持使用本地部署的模型
• 不收集或上传源代码

相关资源

• 官方文档：https://aider.chat/docs/
• GitHub 仓库：https://github.com/Aider-AI/aider
• 问题反馈：GitHub Issues

总结

Aider 代表了 AI 辅助编程工具的新一代发展方向，它通过深度集成 AI 能力与成熟的版本控制系统，为开发者提供了一个高效、安全、可持续的 AI 结对编程环境。无论是小型个人项目还是大型企业代码库，Aider 都能显著提升开发效率。

资料来源：aider/__init__.py:1-30

系统要求

Python 版本兼容性

Aider 支持以下 Python 版本：

资料来源：CONTRIBUTING.md:1

核心依赖

Aider 的核心功能依赖以下关键库：

资料来源：requirements.txt:1-50

安装方式

使用 pip 安装

通过 Python 包管理器 pip 进行安装是最简单的方式：

pip install aider-chat

使用 uv 安装

如果使用 uv 作为包管理工具：

uv pip install aider-chat

使用 Docker 部署

Docker 安装方式适合需要隔离环境的用户：

docker pull aiderai/aider

Aider 提供了官方 Dockerfile，位于 docker/Dockerfile。Docker 镜像基于 Python 运行环境，包含所有必要的依赖项。

资料来源：docker/Dockerfile:1

从源码安装

对于需要最新功能或参与开发的用户，可以从源码安装：

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

或使用 uv：

git clone https://github.com/Aider-AI/aider.git
cd aider
uv pip install -e .

安装流程图

graph TD
    A[开始安装] --> B{选择安装方式}
    B --> C[pip 安装]
    B --> D[Docker 安装]
    B --> E[从源码安装]
    C --> F[安装 aider-chat]
    D --> G[拉取 Docker 镜像]
    E --> H[克隆源码仓库]
    H --> I[安装可编辑模式]
    F --> J[配置 LLM API]
    G --> J
    I --> J
    J --> K[验证安装]
    K --> L[安装完成]

环境配置

LLM API 配置

安装完成后，需要配置 LLM 提供商。支持的模型包括：

• OpenAI：GPT-4o、o1、o3-mini 等
• Anthropic：Claude 系列
• 本地模型：通过兼容接口连接
• 其他：支持 litellm 的所有模型

环境变量

可通过以下环境变量进行配置：

资料来源：aider/website/examples/update-docs.md:1

依赖模块说明

核心功能依赖

requirements.txt 定义了项目的核心依赖：

aiohappyeyeballs>=2.6.1
aiohttp>=3.13.3
anyio>=4.12.1
httpx>=0.27.0
packaging>=26.0
pathspec>=1.0.4
pexpect>=4.9.0
psutil>=7.2.2
typer>=0.24.1

资料来源：requirements.txt:1-30

可选功能模块

requirements-help.txt 包含以下扩展依赖：

资料来源：requirements/requirements-help.txt:1-80

代码规范要求

开发者在安装开发环境时需遵循以下规范：

代码风格

• 遵循 PEP 8 规范
• 最大行长度：100 字符
• 使用 isort 排序导入
• 使用 Black 格式化代码

开发环境设置

1. 安装 pre-commit hooks（自动格式化代码）
2. 运行测试前确保安装开发依赖
3. Python 版本必须在 3.9-3.12 范围内

资料来源：CONTRIBUTING.md:1-30

验证安装

安装完成后，运行以下命令验证：

aider --version

或启动交互式会话：

aider

常见问题

依赖冲突

如果遇到依赖冲突，建议使用虚拟环境：

python -m venv aider-env
source aider-env/bin/activate  # Linux/Mac
# 或
aider-env\Scripts\activate     # Windows
pip install aider-chat

权限问题

Linux/Mac 用户可能需要使用 --user 安装：

pip install --user aider-chat

或将 pip 安装路径添加到 PATH 环境变量。

Git 依赖

Aider 依赖 Git 进行版本控制，确保系统已安装 Git：

git --version

概述

Aider 是一个终端中的 AI 结对编程工具，它使开发者能够与大型语言模型（LLM）协作来启动新项目或扩展现有代码库。该工具的核心设计围绕命令行界面、LLM 集成、Git 工作流自动化和代码编辑能力展开。

Aider 支持多种 LLM 提供商，包括 DeepSeek、Claude 3.7 Sonnet、OpenAI o1、o3-mini、GPT-4o 等，同时也支持本地模型运行。

概述

Aider 的代码编辑器模块是整个工具的核心组件之一，负责管理与大型语言模型（LLM）的代码交互、修改和应用。该模块采用策略模式设计，通过多个专门的编码器（coder）类来处理不同类型的代码编辑场景，从简单的代码块替换到复杂的统一差异（unified diff）应用。代码编辑器模块与 Git 版本控制系统深度集成，自动为每次修改生成语义化的提交信息，使开发者能够方便地回溯、对比和撤销 AI 产生的变更。

Aider 支持多种代码编辑策略，包括编辑块模式（Edit Block）、整文件模式（Whole File）、差异模式（Udiff）和补丁模式（Patch），每种模式都针对特定的使用场景和 LLM 能力进行了优化。这种模块化的架构设计允许开发者在不同场景下选择最合适的编辑策略，同时也便于扩展新的编辑模式以适应未来 LLM 能力的提升。

架构设计

核心类结构

Aider 的代码编辑器模块采用分层架构设计，基类 BaseCoder 定义了所有编码器必须实现的接口和通用功能，而具体的编辑策略则由子类实现。这种设计遵循了面向对象编程的开闭原则，使得添加新的编辑策略时无需修改现有代码。编码器类负责解析 LLM 返回的编辑指令、验证语法正确性、执行文件修改以及与 Git 仓库进行交互。

graph TD
    A[用户请求] --> B{编辑策略选择}
    B --> C[EditBlockCoder]
    B --> D[WholeFileCoder]
    B --> E[UdiffCoder]
    B --> F[PatchCoder]
    C --> G[解析编辑指令]
    D --> G
    E --> G
    F --> G
    G --> H[验证语法]
    H --> I[执行文件修改]
    I --> J[Git 自动提交]
    J --> K[返回结果给用户]

基类设计

BaseCoder 类作为所有编码器的抽象基类，定义了代码编辑的核心接口和行为。基类实现了与 LLM 的通信机制、文件系统的读写操作、Git 仓库的状态管理以及用户交互界面的构建。每个具体的编码器只需重写特定的方法来适配其独特的编辑策略，而无需重新实现通用的功能逻辑。基类还负责维护编辑上下文，确保 LLM 能够理解当前代码的状态和修改历史。

classDiagram
    class BaseCoder {
        +repo Repo
        +io InputOutput
        +edit_format: str
        +cur_markers: list
        +show_source: bool
        +get_context() list
        +run()
        +send_new_content()
        +edit_response() bool
        +commit()
    }
    
    class EditBlockCoder {
        +done_messages: list
        +edit_block_additions() bool
        +replace_markers()
    }
    
    class WholeFileCoder {
        +write_file()
        +check_syntax()
    }
    
    class UdiffCoder {
        +udiff_edit_response()
        +parse_diff()
    }
    
    class PatchCoder {
        +apply_patch()
        +validate_patch()
    }
    
    BaseCoder <|-- EditBlockCoder
    BaseCoder <|-- WholeFileCoder
    BaseCoder <|-- UdiffCoder
    BaseCoder <|-- PatchCoder

编辑策略类型

编辑块模式（Edit Block）

编辑块模式是 Aider 默认的编辑策略，适用于大多数代码修改场景。该模式使用特殊的标记语法来标识需要修改的代码区域，LLM 在生成的响应中使用这些标记来指定新代码应该插入的位置和范围。编辑块模式的优势在于它能够精确定位修改位置，即使文件很长也能准确应用变更，而不会影响文件中的其他内容。

编辑块模式的工作流程包括：首先解析 LLM 响应中的特殊标记（如 <<<<<<< ORIGINAL 和 =======），然后提取原始代码和新代码的边界，接着执行文本替换操作，最后验证修改后的文件语法是否正确。这种模式特别适合处理函数级别的修改、添加新的代码段或者替换现有的逻辑实现。

整文件模式（Whole File）

整文件模式采用替换整个文件内容的方式来应用修改，适用于需要对文件进行大幅度重构的场景。当 LLM 返回完整的文件内容时，Aider 会用新内容完全替换旧文件。这种模式的优点是实现简单、不容易出现部分更新的问题，但缺点是当文件较长时会消耗更多的输入 token，因为它需要重新发送整个文件内容给 LLM。

整文件模式在以下场景中特别有用：语言转换（如从 Python 2 迁移到 Python 3）、大规模重构需要同时修改多处代码、以及 LLM 更好地理解完整上下文时。该模式还支持语法检查功能，可以在应用修改前验证代码的语法正确性，避免将明显错误的代码写入文件。

统一差异模式（Udiff）

统一差异模式使用标准的 unified diff 格式来表示代码修改，这是开发者熟悉的传统 diff 格式。LLM 生成包含上下文行的差异信息，Aider 解析这些差异并应用到源文件中。这种模式的优点是与现有的代码审查工具和版本控制系统高度兼容，便于人类理解和审查 LLM 生成的修改。

Udiff 模式特别适合与支持 unified diff 的 LLM 一起使用，或者当需要将 LLM 的修改集成到已有的代码审查流程中时。该模式能够保留修改的历史上下文，使得 diff 输出更加可读和易于理解。

补丁模式（Patch）

补丁模式基于标准的 patch 格式来处理代码修改，提供了一种更加结构化的修改方式。与 Udiff 模式类似，Patch 模式也生成可读的差异输出，但格式更加规范化，便于解析和处理。Aider 在应用补丁时会进行多重验证，包括检查文件的当前状态是否与补丁期望的状态匹配。

核心组件详解

文件输入输出管理

InputOutput 类负责管理与用户的交互输入输出，以及文件的读写操作。该类封装了 prompt_toolkit 库的交互式输入功能，支持命令历史记录、自动补全和自定义样式等特性。InputOutput 类维护了输入历史文件和聊天历史文件的路径，使得用户的输入历史可以在会话之间持久化保存。

graph LR
    A[用户输入] --> B[InputOutput]
    B --> C[PromptSession]
    B --> D[FileHistory]
    C --> E[终端显示]
    D --> F[历史文件]

Git 集成

代码编辑器模块与 Git 深度集成，实现了自动提交功能。每次 LLM 产生的修改都会被自动提交到本地 Git 仓库，并生成语义化的提交信息。这些提交信息描述了修改的内容和目的，便于开发者理解变更历史。Aider 使用熟悉的 Git 工具来管理修改历史，支持查看差异（diff）、管理分支和撤销（undo）AI 的修改。

Lint 和测试集成

Aider 支持在每次修改后自动运行 linter 和测试套件。当 LLM 生成的代码导致 linter 检测到问题时，Aider 可以请求 LLM 自动修复这些问题。这种自动化的工作流程确保了代码质量的持续维护，减少了手动检查和修复的工作量。

配置与使用

命令行参数

环境变量

工作流程

sequenceDiagram
    participant User as 用户
    participant IO as InputOutput
    participant Coder as Coder
    participant LLM as LLM
    participant Git as Git
    participant FS as 文件系统

    User->>IO: 发送请求
    IO->>Coder: 转发请求
    Coder->>FS: 读取当前文件
    Coder->>Coder: 生成上下文
    Coder->>LLM: 发送编辑请求
    LLM-->>Coder: 返回编辑指令
    Coder->>Coder: 解析并验证
    Coder->>FS: 写入修改
    Coder->>Git: 创建提交
    Coder-->>User: 返回结果

技术栈

代码编辑器模块依赖以下核心技术组件：

• prompt_toolkit：用于构建交互式命令行界面
• GitPython：用于与 Git 仓库进行交互
• tiktoken：用于 LLM 输出的分词和标记
• tree-sitter 或 AST 解析器：用于语法验证

扩展与定制

开发者可以通过继承 BaseCoder 类来创建自定义的编辑策略。新的编码器类需要实现以下核心方法：

1. get_context()：返回发送给 LLM 的上下文信息
2. edit_response()：解析 LLM 的响应并应用修改
3. commit()：创建 Git 提交

这种扩展机制使得 Aider 能够适应不同的编辑需求和 LLM 能力，为未来可能出现的新编辑模式提供了良好的扩展基础。

功能概述

Aider 的 Git 集成提供以下核心能力：

资料来源：README.md

核心组件

Repository 管理器

aider/repo.py 模块负责管理与 Git 仓库的交互。该模块处理仓库检测、文件状态追踪和提交历史管理。

graph TD
    A[用户运行 aider] --> B{检测 Git 仓库}
    B -->|是| C[初始化 Repository]
    B -->|否| D[禁用 Git 功能]
    C --> E[加载 .aiderignore]
    E --> F[扫描已修改文件]
    F --> G[准备自动提交]

差异处理模块

aider/diffs.py 负责生成和管理代码差异。当 AI 完成修改后，该模块计算并格式化变更内容，供提交时展示。

资料来源：aider/diffs.py

命令行配置

Git 相关参数

资料来源：aider/args.py

环境变量配置

自动提交机制

Aider 采用智能自动提交策略，每次 AI 修改代码后都会创建包含有意义提交信息的提交。

graph LR
    A[AI 修改代码] --> B[生成变更]
    B --> C[生成语义化提交信息]
    C --> D[执行 git add]
    D --> E[执行 git commit]
    E --> F[记录到提交历史]

提交信息生成

Aider 会分析代码变更内容，自动生成描述性的提交信息。例如：

aider: Updated function signature in main.py
aider: Fixed main() function to accept input and output keyword arguments
aider: Added padding inside the border of the blockquote

资料来源：aider/commands.py

忽略文件配置

.aiderignore 语法

.aiderignore 文件使用与 .gitignore 类似的语法规则，用于指定哪些文件不应被 Aider 追踪和修改。

# 忽略临时文件
*.tmp
*.log

# 忽略构建产物
dist/
build/
__pycache__/

.gitignore 集成

当 --gitignore 参数启用时（默认行为），Aider 会自动将以下文件添加到项目的 .gitignore：

• .aider* - Aider 配置和缓存文件
• .aider.history - 聊天历史记录

资料来源：aider/args.py

使用流程

graph TD
    A[启动 aider] --> B{检测 Git 仓库}
    B -->|未检测到| C[显示警告或禁用 Git 功能]
    B -->|检测到| D[加载 Git 配置]
    D --> E[加载 .aiderignore]
    E --> F[等待用户指令]
    F --> G{AI 执行修改}
    G -->|是| H{auto-commits 启用?}
    H -->|是| I[创建自动提交]
    H -->|否| J[仅修改文件]
    I --> K[显示提交哈希]
    J --> F

与其他工具的集成

查看差异

用户可以通过标准 Git 命令查看 Aider 所做更改：

# 查看工作区差异
git diff

# 查看提交历史
git log

# 查看特定提交
git show <commit-hash>

撤销更改

# 撤销最近一次提交（保留文件更改）
git reset --soft HEAD~1

# 完全撤销提交
git reset --hard HEAD~1

资料来源：README.md

开发指南

本地测试

在开发环境中测试 Git 集成时，建议：

1. 使用测试仓库而非生产代码库
2. 启用 --show-diffs 以验证提交内容
3. 设置 AIDER_AUTO_COMMITS=0 进行调试

提交规范

项目使用 PEP 8 风格指南，代码格式化由 Black 和 isort 自动处理。提交前请运行预提交钩子以确保代码符合规范。

资料来源：CONTRIBUTING.md

功能概述

Aider 的仓库映射功能使 AI 助手能够全面把握代码库的整体架构。通过构建代码库的"地图"，Aider 可以在处理请求时准确定位相关代码片段，理解模块间的依赖关系，从而生成更加准确和上下文相关的代码修改建议。

资料来源：aider/website/index.html

核心特性

资料来源：aider/website/index.html

工作原理

仓库映射系统通过以下步骤构建代码库的映射：

graph TD
    A[代码库扫描] --> B[文件发现]
    B --> C[语言检测]
    C --> D[语法树解析]
    D --> E[依赖关系提取]
    E --> F[构建依赖图谱]
    F --> G[存储到 RepoMap]
    G --> H[为 LLM 提供上下文]

扫描阶段

Aider 会递归扫描项目目录，识别所有需要分析的文件。这一过程考虑 .gitignore 规则，跳过不应纳入分析的二进制文件和无关文档。

解析阶段

对于每种支持的语言，Aider 使用 Tree-sitter 解析语法树，提取关键的语法元素：

• 函数定义 - 识别函数名、参数和作用域
• 类定义 - 分析类的继承关系和成员
• 导入语句 - 追踪模块间的依赖关系
• 变量声明 - 理解变量的定义和使用位置

图谱构建

解析完成后，系统构建一个反映代码库拓扑结构的依赖图谱。这个图谱使得 Aider 能够：

1. 快速定位与当前修改相关的所有代码文件
2. 理解修改可能影响的上下游模块
3. 在多个相关位置之间做出协调一致的修改

配置选项

与 Tree-sitter 的集成

Aider 的仓库映射功能深度集成了 Tree-sitter 技术。Tree-sitter 是一个用于解析编程语言的开源库，能够生成高效的增量语法解析树。

资料来源：requirements/common-constraints.txt

支持的编程语言包括但不限于：

• Python
• JavaScript/TypeScript
• Rust
• Go
• C/C++
• Ruby
• PHP
• HTML/CSS

每种语言都有对应的 Tree-sitter 语言包支持，这些语言包存储在 aider/queries/tree-sitter-languages/ 和 aider/queries/tree-sitter-language-pack/ 目录中。

使用场景

大型项目导航

在包含数百或数千个文件的大型代码库中，仓库映射帮助 Aider 快速理解代码的组织结构，准确地定位到与用户请求相关的代码区域。

关联代码修改

当用户请求修改一个函数或类时，Aider 可以通过仓库映射识别所有使用该函数或继承该类的位置，确保修改的一致性和完整性。

依赖感知重构

在进行重构操作时，仓库映射提供依赖关系的完整视图，帮助 AI 评估修改的潜在影响范围。

性能优化

为了在大型代码库中保持响应速度，Aider 实现了以下优化策略：

1. 增量更新 - 仅在文件实际变更时重新解析相关文件
2. 智能缓存 - 缓存已解析的语法树供后续使用
3. 选择性加载 - 根据需要动态加载特定模块的详细信息
4. 字符限制 - 通过 AIDER_REPOMAP_CHARS 控制发送到 LLM 的上下文大小

技术架构

graph LR
    A[用户请求] --> B[RepoMap 控制器]
    B --> C{缓存检查}
    C -->|命中| D[返回缓存数据]
    C -->|未命中| E[文件系统扫描]
    E --> F[Tree-sitter 解析]
    F --> G[依赖图谱构建]
    G --> H[存储映射结果]
    H --> I[返回给 LLM]

限制与注意事项

1. 解析精度 - 对于某些非标准编码的文件，解析可能失败
2. 循环依赖 - 包含循环依赖的代码库可能导致图谱构建复杂化
3. 外部依赖 - 映射仅涵盖本地代码仓库，不包括外部包或库
4. 性能瓶颈 - 超大型代码库（超过 10 万行代码）可能需要较长的初始扫描时间

概述

Aider 是一个终端中的 AI 结对编程工具，其核心功能之一是与各种大语言模型（LLM）进行集成。通过模块化的设计架构，Aider 支持连接到几乎任何 LLM API，包括 OpenAI、Anthropic、DeepSeek、OpenRouter 等主流服务提供商，同时也支持本地模型部署。

LLM 集成模块在整个系统中承担着关键角色，它负责：

• 与远程 API 服务建立安全连接
• 管理对话上下文和历史记录
• 处理模型响应和错误恢复
• 支持多种模型配置和参数调优
• 实现流式输出和批量处理能力

资料来源：README.md

架构设计

核心组件关系

graph TD
    A[User Input] --> B[Main Application]
    B --> C[InputOutput Module]
    C --> D[LLM Module]
    D --> E[models.py]
    D --> F[llm.py]
    E --> G[Model Metadata]
    F --> H[API Providers]
    H --> I[OpenAI]
    H --> J[Anthropic Claude]
    H --> K[DeepSeek]
    H --> L[OpenRouter]
    H --> M[Local Models]
    G --> N[model-metadata.json]

模块职责划分

资料来源：aider/models.py

模型配置系统

模型元数据管理

Aider 使用 JSON 格式的元数据文件 model-metadata.json 来存储支持的模型信息。该文件包含每个模型的以下属性：

• 模型标识符和显示名称
• 支持的 API 提供商
• 上下文窗口大小
• 默认参数配置
• 特殊功能支持标志

支持的模型分类

Aider 支持的模型可分为以下几个主要类别：

OpenAI 系列

• GPT-4o
• o1、o3-mini
• GPT-4 Turbo

Anthropic 系列

• Claude 3.7 Sonnet
• Claude 3.5 Sonnet
• Claude 3 Opus

其他主流模型

• DeepSeek
• 本地部署模型
• 通过 OpenRouter 访问的各类模型

资料来源：README.md

LLM 通信机制

API 连接流程

sequenceDiagram
    participant User
    participant App as Main Application
    participant LLM as LLM Module
    participant API as External API
    
    User->>App: Submit Request
    App->>LLM: Format Prompt
    LLM->>API: Send API Request
    API->>LLM: Receive Response
    LLM->>App: Parse Response
    App->>User: Display Result

错误处理与重试

LLM 模块实现了完善的错误处理机制，包括：

• 网络超时自动重试
• API 限流处理
• 响应格式验证
• 降级策略支持

资料来源：aider/llm.py

OpenRouter 集成

OpenRouter 路由机制

OpenRouter 是一个统一的 LLM 路由服务，允许用户通过单一接口访问多个模型提供商。Aider 通过专门的 openrouter.py 模块实现与 OpenRouter 的集成：

• 自动选择最优模型
• 成本优化路由
• 统一的 API 封装
• 认证和密钥管理

配置示例

# 使用 OpenRouter
aider --model openrouter/anthropic/claude-3.5-sonnet --api-key openrouter=<key>

# 指定提供商
aider --model deepseek --api-key deepseek=<key>

资料来源：aider/openrouter.py

使用配置

命令行参数

环境变量配置

Aider 支持通过环境变量配置 API 密钥，优先级如下：

1. 命令行 --api-key 参数
2. 环境变量 OPENAI_API_KEY
3. 配置文件中的密钥

资料来源：aider/website/_includes/get-started.md

上下文管理

上下文窗口策略

LLM 模块负责管理和优化上下文窗口的使用：

• 自动截断过长的对话历史
• 智能选择相关上下文
• 标记文件内容的优先级
• 管理令牌使用预算

令牌统计

Aider 追踪并报告令牌使用情况，包括：

• 每条消息的输入/输出令牌数
• 每周总处理令牌数
• 各模型使用比例统计
• REDACTED 模型的隐私处理

资料来源：scripts/my_models.py

扩展与定制

添加新模型支持

要在 Aider 中添加新的模型支持，需要：

1. 在 model-metadata.json 中添加模型元数据
2. 在相应模块中实现 API 封装
3. 更新文档中的模型列表
4. 测试连接和功能完整性

本地模型支持

Aider 支持连接本地运行的 LLM 服务：

• 配置自定义 API 端点
• 支持 OpenAI 兼容接口
• 支持 Llama.cpp 等本地推理框架
• 可调节的连接参数

安全性考虑

密钥管理

Aider 在处理 API 密钥时遵循以下安全原则：

• 密钥不写入日志或错误消息
• 支持环境变量注入
• 本地存储加密（如使用配置文件）
• 清晰的权限控制机制

数据隐私

• 对新模型或不常用模型使用 REDACTED 标识
• 最小化外部数据传输
• 支持完全离线的本地部署

故障排除

常见问题

资料来源：CONTRIBUTING.md

相关资源

• 安装指南
• 使用文档
• LLM 连接配置
• 配置选项
• LLM 排行榜

概述

Aider 的命令系统是用户与 AI 编程助手交互的核心机制。通过该系统，用户可以在聊天界面中输入自然语言请求和特殊命令来控制代码编辑、Git 操作、文件管理和工具调用等行为。命令系统与 LLM 集成，支持自动提交、代码差异显示、历史记录管理等高级功能。

Aider 的命令系统主要分为两类：

1. 内置命令：以 / 开头的系统级命令，如 /help、/diff、/commit 等
2. 自然语言请求：用户直接输入的描述性文本，由 LLM 解析并生成相应的代码修改

命令系统架构遵循模块化设计，核心组件包括命令解析器、历史记录管理器和输入输出处理模块。资料来源：aider/commands.py

核心组件

命令解析器 (commands.py)

aider/commands.py 是命令系统的核心模块，负责定义和处理所有内置命令。该模块实现了命令的注册、解析和执行机制。

资料来源：aider/commands.py:1-50

历史记录管理器 (history.py)

aider/history.py 负责管理聊天历史和命令历史，提供会话持久化和历史回溯功能。

资料来源：aider/history.py:1-30

帮助系统 (help.py)

aider/help.py 提供命令系统的帮助信息，支持用户查询可用命令及其用法。

# 帮助信息的显示格式
class HelpCommand:
    def __init__(self, commands):
        self.commands = commands
    
    def show_help(self):
        # 输出所有可用命令列表
        pass

资料来源：aider/help.py:1-20

命令执行流程

graph TD
    A[用户输入] --> B{解析输入}
    B -->|以 / 开头| C[内置命令]
    B -->|普通文本| D[自然语言请求]
    C --> E[命令注册表查询]
    E --> F[执行命令处理函数]
    D --> G[发送给 LLM]
    G --> H[生成响应和代码修改]
    F --> I[返回结果]
    H --> J[应用代码修改]
    I --> K[显示输出]
    J --> K

内置命令参考

文件操作命令

Git 命令

资料来源：aider/commands.py:50-150

系统命令

输入输出处理

Aider 使用 InputOutput 类处理命令行输入输出，支持多种输入源和输出目标。

class InputOutput:
    def __init__(self, pretty, yes, input_history_file, chat_history_file, input=None, output=None):
        self.input = input
        self.output = output
        self.pretty = pretty
        self.yes = yes
        self.input_history_file = input_history_file
        self.chat_history_file = chat_history_file

资料来源：aider/getinput.py:1-20

Prompt Toolkit 集成

Aider 使用 prompt_toolkit 库提供增强的命令行编辑体验：

session = PromptSession(
    message=show,
    completer=completer_instance,
    history=FileHistory(self.input_history_file),
    style=style,
    reserve_space_for_menu=4,
    complete_style=CompleteStyle.MULTI_COLUMN,
    input=self.input,
    output=self.output,
)
line = session.prompt()

资料来源：aider/getinput.py:30-50

命令行参数

Aider 主程序支持以下命令行参数：

资料来源：aider/main.py:1-100

自动提交机制

Aider 的命令系统与 Git 深度集成，支持自动提交功能：

graph LR
    A[代码修改完成] --> B{auto-commits 启用?}
    B -->|是| C[生成提交信息]
    B -->|否| D[等待手动提交]
    C --> E[执行 git commit]
    E --> F[显示提交结果]

自动提交的提交信息由 LLM 根据代码更改内容自动生成，格式遵循语义化提交规范。

资料来源：aider/coder.py:200-250

错误处理

命令系统实现了完善的错误处理机制：

# 错误显示示例
self.io.tool_error("Malformed ORIGINAL/UPDATE blocks, retrying...")
self.io.tool_error(Text(err))

资料来源：aider/coder.py:250-280

配置选项

可通过环境变量或配置文件调整命令系统行为：

扩展命令系统

开发者可以通过修改 commands.py 添加自定义命令：

class CustomCommand:
    name = "custom"
    description = "执行自定义操作"
    
    def run(self, args, io):
        # 命令实现
        pass

自定义命令需要在命令注册表中注册才能生效。

最佳实践

1. 命令前缀：使用 / 前缀调用内置命令，避免与自然语言请求混淆
2. 文件指定：在多文件项目中，明确指定要操作的文件路径
3. 确认机制：重要操作前，系统会要求用户确认，可使用 --yes 参数跳过
4. 历史记录：定期备份 .aider.history 文件以保留重要对话上下文

系统架构概述

Aider 的配置系统由三个核心模块组成，形成一个完整的配置生命周期管理流程。args.py 负责命令行参数的解析，args_formatter.py 提供参数格式化能力，format_settings.py 则处理设置值的格式化输出。这种分层设计确保了配置逻辑的清晰分离和高度可维护性。

graph TD
    A[用户输入] --> B[环境变量]
    A --> C[命令行参数]
    D[默认值] --> E[参数解析 args.py]
    B --> E
    C --> E
    E --> F[格式化 args_formatter.py]
    E --> G[设置格式化 format_settings.py]
    F --> H[应用配置]
    G --> H

核心模块详解

参数解析模块 (args.py)

aider/args.py 是配置系统的核心入口，负责定义和解析所有命令行参数。该模块使用 Python 标准库中的 argparse 模块构建完整的命令行接口，支持超过三十种配置选项，涵盖模型选择、API 密钥管理、历史记录控制、输出格式设置等各个方面。

参数解析采用分层覆盖策略，用户可以通过三种方式设置配置：直接使用命令行参数、提供环境变量、或依赖系统默认值。这种设计允许用户在保持配置灵活性的同时，通过环境变量实现自动化部署场景下的配置管理。

主要参数类别包括：

参数格式化模块 (args_formatter.py)

aider/args_formatter.py 负责将解析后的参数转换为用户友好的显示格式。该模块提供了参数描述的格式化能力，支持生成帮助文本和使用示例。在命令行界面中，当用户执行 aider --help 时，正是通过此模块生成详细的帮助文档。

参数格式化器还负责处理参数的特殊显示逻辑，例如布尔值的反向显示（--no-pretty 与 --pretty 的关系）、环境变量提示的生成，以及多值参数的格式化展示。

设置格式化模块 (format_settings.py)

aider/format_settings.py 实现了应用程序运行时的设置格式化功能。该模块将配置系统中的各类设置值转换为适合在终端显示的格式，支持彩色输出、表格布局和分类展示等多种显示模式。

设置格式化模块与应用程序的输入输出子系统紧密集成，通过统一的接口为不同模块提供配置值的展示服务。这种设计确保了配置信息在应用程序各个部分的一致性和可读性。

配置层级与优先级

Aider 采用明确的配置优先级体系，从高到低依次为：命令行参数、环境变量、默认值。这种设计允许在不同部署场景下灵活控制配置行为，同时保持配置接口的一致性。

graph LR
    A[命令行参数] --> Z[最终配置]
    B[环境变量] --> Z
    C[默认值] --> Z
    A --> |最高优先级| Z
    B --> |次高优先级| Z
    C --> |最低优先级| Z

环境变量命名规范

配置系统为每个命令行参数提供了对应的环境变量支持。环境变量采用 AIDER_ 前缀加上参数名称大写的命名方式。例如，--history-file 参数对应的环境变量为 AIDER_HISTORY_FILE，--model 参数对应 AIDER_MODEL。这种标准化命名规范使得在脚本和容器环境中配置 Aider 变得直观便捷。

支持的完整环境变量映射包括：

配置传递机制

配置系统通过 InputOutput 类实现参数在应用程序内部的传递。该类封装了输入输出相关的配置，包括终端美化设置、历史记录文件路径、控制台交互选项等。配置对象在应用程序启动时创建，随后被传递到各个需要访问配置的模块中。

class InputOutput:
    def __init__(self, pretty, yes, input_history_file, 
                 chat_history_file, input=None, output=None):
        self.input = input
        self.output = output
        # ... 其他初始化逻辑

配置传递采用依赖注入模式，各模块通过构造函数或方法参数接收所需的配置对象，而非直接访问全局配置状态。这种设计提高了代码的可测试性和模块间的解耦程度。

主要配置选项

模型配置

模型配置控制 Aider 与 LLM 交互的核心行为。用户可以通过 --model 参数指定使用的模型，如 gpt-4、claude-3-sonnet-20240229、deepseek 等。模型配置影响上下文窗口大小、API 端点选择以及提示词的适配逻辑。

输出格式配置

输出格式配置决定终端显示的视觉风格。主要选项包括：

• --pretty：启用彩色输出和富文本格式
• --no-pretty：禁用美化，使用纯文本输出
• --show-diffs：在提交时显示变更差异

自动行为配置

自动行为配置控制 Aider 的自主操作能力：

• --auto-commits：自动提交 AI 产生的代码更改
• --no-auto-commits：手动确认后才提交
• --yes：自动确认所有确认提示

文件与目录配置

配置验证与错误处理

配置系统在解析参数时执行基本的验证逻辑。对于必需参数（如 API 密钥），系统会在启动时检查是否提供了有效的值。对于冲突的选项组合（如同时指定多个互相排斥的参数），系统会抛出明确的错误信息并提示正确的用法。

错误处理遵循用户友好的原则，错误消息不仅指出问题所在，还提供解决问题的建议。这种设计使得即使是不熟悉命令行工具的用户也能快速定位和解决配置问题。

扩展配置能力

Aider 的配置系统支持通过添加新的参数定义来扩展配置选项。开发者需要在 args.py 中添加新的参数定义，并在相关的配置处理模块中实现对应的处理逻辑。这种扩展机制允许在不修改核心架构的情况下添加新的配置功能。

配置系统的扩展遵循开闭原则：对扩展开放，对修改封闭。新增配置选项时，只需在指定的扩展点添加相应的定义，而无需修改现有的配置处理流程。

总结

Aider 的配置系统通过模块化设计实现了灵活、高效的配置管理能力。三层架构（参数解析、格式化、传递）确保了配置逻辑的清晰分离，环境变量支持提供了自动化部署的便利，而分层优先级体系则满足了不同场景下的配置需求。配置系统与应用程序的其他部分紧密集成，共同构成了 Aider 作为 AI 结对编程工具的核心能力基础。

功能概述

语音输入（Voice-to-Code）是 Aider 提供的一种创新特性，允许用户通过语音与 AI 编程助手进行交流，从而摆脱键盘输入的限制。用户可以直接用语音描述新功能、测试用例或 bug 修复的需求，Aider 会自动理解并实现相应的代码变更。

这一功能极大地提升了编程效率，特别是对于需要快速记录灵感、编写长篇代码注释或进行大量重构的场景。用户无需切换窗口或中断工作流程，即可通过语音指令驱动代码编辑。

核心组件

语音输入模块

aider/voice.py 文件包含了语音输入的核心实现逻辑，负责处理语音识别、音频录制和语音命令解析等功能。

输入输出管理

语音输入与 Aider 的标准输入输出系统深度集成，通过 InputOutput 类统一处理各类输入源：

# aider/getinput.py
class InputOutput:
    def __init__(
        self,
        pretty=True,
        yes=False,
        input_history_file=None,
        chat_history_file=None,
        input=None,
        output=None,
        user_input_color="blue",
        tool_output_color=None,
        tool_error_color="red",
    ):
        no_color = os.environ.get("NO_COLOR")
        if no_color is not None and no_color != "":
            pretty = False

        self.user_input_color = user_input_color if pretty else None
        self.tool_output_color = tool_output_color if pretty else None
        self.tool_error_color = tool_error_color if pretty else None

资料来源：aider/getinput.py

工作流程

语音命令处理流程

graph TD
    A[用户语音输入] --> B[麦克风录制音频]
    B --> C[语音识别引擎]
    C --> D[文本命令生成]
    D --> E[命令解析器]
    E --> F{命令类型判断}
    F -->|代码编辑| G[生成编辑指令]
    F -->|代码查询| H[生成查询指令]
    F -->|代码审查| I[生成审查指令]
    G --> J[Coder 模块处理]
    H --> J
    I --> J
    J --> K[执行代码变更]
    K --> L[自动提交到 Git]

语音输入与标准输入的切换

Aider 支持在语音输入和标准键盘输入之间无缝切换。用户可以在任意时刻使用语音命令，系统会自动将语音内容转换为代码指令并执行。

graph LR
    A[键盘输入] <--> B[InputOutput]
    C[语音输入] <--> B
    B --> D[统一消息处理]
    D --> E[命令执行引擎]

使用场景

主要应用场景

资料来源：aider/website/index.html

集成方式

Aider 的语音功能可以通过以下方式调用：

1. IDE/编辑器集成：在代码中添加注释描述需求
2. 命令行直接调用：使用语音命令启动对话
3. 对话中途切换：在键盘输入和语音输入之间自由切换

技术实现

错误处理机制

语音输入模块包含完善的错误处理机制，确保在识别失败或音频问题发生时能够优雅降级：

# aider/coder.py 中的错误处理示例
<<<<<<< ORIGINAL
            self.console.print("[red]", Text(err))
=======
            self.io.tool_error("Malformed ORIGINAL/UPDATE blocks, retrying...")
            self.io.tool_error(Text(err))
>>>>>>> REPLACE

资料来源：aider/coder.py

环境变量配置

语音输入功能支持通过环境变量进行配置：

配置选项

命令行参数

语音输入相关的命令行参数允许用户精细控制功能行为：

• --no-auto-commits：禁用自动提交，适合需要人工审核的场景
• --show-diffs：显示代码差异，帮助用户确认语音命令的执行结果
• --yes：自动确认所有操作，无需手动确认语音生成的内容

资料来源：aider/website/examples/update-docs.md

与其他功能的协作

与代码编辑系统的集成

语音输入生成的命令会通过 SearchReplaceBlock 格式传递给代码编辑系统：

graph TD
    A[语音输入] --> B[文本命令]
    B --> C[命令解析]
    C --> D[SearchReplaceBlock 生成]
    D --> E[Coder.editblock 编辑]
    E --> F[文件变更]
    F --> G[Git 自动提交]

与 lint 和测试的联动

语音输入触发的代码变更会自动通过配置的 linter 和测试套件验证：

• 自动运行代码检查工具
• 执行单元测试验证功能正确性
• 自动修复 linter 发现的问题

资料来源：aider/website/index.html

最佳实践

语音输入优化建议

1. 清晰简洁：使用简短的语音命令，避免长篇描述
2. 关键词明确：包含具体的文件名、函数名或变量名
3. 增量修改：将大型重构分解为多个语音命令序列
4. 及时确认：重要变更前查看 diff 输出确认意图

适用场景判断

总结

语音输入功能是 Aider 区别于传统 CLI 编程工具的重要特性，它将自然语言处理与代码编辑深度结合，让开发者能够以更直观的方式与 AI 协作。通过与 Git 集成、自动测试和代码 linting 的配合，语音输入不仅提升了编码效率，还保证了代码质量和变更可追溯性。

Pitfall Log / 踩坑日志

项目：Aider-AI/aider

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:638629097 | https://github.com/Aider-AI/aider | host_targets=claude, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:638629097 | https://github.com/Aider-AI/aider | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:638629097 | https://github.com/Aider-AI/aider | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:638629097 | https://github.com/Aider-AI/aider | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:638629097 | https://github.com/Aider-AI/aider | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:638629097 | https://github.com/Aider-AI/aider | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:638629097 | https://github.com/Aider-AI/aider | release_recency=unknown