Aider 命令行实战指南

Aider 是跑在终端里的 AI pair programmer，让 LLM 直接在你本地 git 仓库里改代码，每次改动默认自动 commit，可 /undo 回退。它的强项是精准的小范围 patch——手术刀式改代码，不是大范围重构。如果你想要的是"让 AI 帮我把这个函数的逻辑改对"，Aider 是目前最顺手的工具之一；如果你想要的是"让 AI 帮我把整个模块推倒重来"，它不是最佳选择。

安装与启动

推荐用 pipx 安装，隔离环境不污染系统 Python：

pipx install aider-chat

或者用 pip：

python -m pip install aider-chat

验证安装：

aider --version

装好后，cd 进你的项目目录（必须是 git 仓库），直接敲 aider 启动。首次启动会读取当前 git 仓库信息，构建 repo map。如果你没配 API key，Aider 会提示你设置环境变量。

文件上下文管理：Aider 的核心心智

用 Aider 干活，最重要的一件事是搞懂文件上下文管理。LLM 的注意力是有限的，你塞进去的文件越多，它对每个文件的理解就越稀释。Aider 的设计哲学是：只把要改的文件加进聊天，靠 repo map 提供全局上下文。

核心命令：

• /add <file>：把文件加入聊天，让 Aider 能编辑和详查它。只有 /add 进来的文件，Aider 才会动手改。
• /drop <file>：从会话移除文件，释放上下文。改完一个文件，如果后面不再需要它，果断 /drop。
• /clear：清空聊天历史，但保留已 /add 的文件。当你切换到下一个任务时用。
• /reset：丢掉所有文件并清空历史，回到干净状态。

repo map 是 Aider 的关键机制。它会扫描你的整个 git 仓库，生成一个压缩索引——包含有哪些文件、每个文件里有哪些函数/类/符号。这个索引让模型知道"仓库里存在什么"，从而在需要时引用正确的符号名和文件路径，而不需要你把所有文件都 /add 进来。

• --map-tokens <n>：控制 repo map 的 token 上限。默认值依仓库大小动态调整。设 0 禁用 repo map（不推荐，除非你完全不需要全局上下文）。
• /map：打印当前 repo map，看看模型实际看到了什么全局信息。
• /tokens：报告当前聊天上下文的 token 占用，包括系统 prompt、聊天历史、已 add 的文件、repo map 各占多少。

心法：只 /add 真正要改的文件，靠 repo map 提供全局上下文，别把整个仓塞进聊天。 如果你发现 /tokens 显示上下文快满了，第一反应应该是 /drop 非必要文件，而不是换更大上下文窗口的模型。

编辑模式与 chat 模式

Aider 有四种 chat 模式，对应不同的工作方式：

• ask：只问不改。模型回答你的问题，不碰任何文件。适合代码审查、理解代码逻辑。
• code：请求代码改动，这是默认模式。模型会直接编辑 /add 进来的文件。
• architect：双模型模式。一个模型（architect）负责设计改动方案，另一个模型（editor）负责实现。适合复杂改动，让强模型出方案、快模型写代码。
• help：问 Aider 自身用法，相当于内置文档。

编辑格式（edit format）决定了模型用什么方式表达代码改动：

• whole：重写整个文件。简单粗暴，适合小文件。
• diff：搜索/替换块，模型给出要找的旧代码和替换后的新代码。适合中等改动。
• udiff：统一 diff 格式。适合行级精确改动。
• architect：双模型协作，architect 设计 + editor 实现。

编辑格式默认依模型而定——Aider 会根据你选的模型自动挑最合适的格式。你也可以用 --edit-format 或 --chat-mode 手动指定。

一个实战判断：纯 review 用 /ask。如果你只是想让模型看看代码给意见，用默认 code 模式可能触发 edit format 相关的报错（模型试图生成改动但你不想要改动）。/ask 模式下模型只回答不动手，干净利落。进入 ask 模式可以在会话内用 /ask，启动时用 --chat-mode ask。

--architect 双模型模式值得单独说：它让一个模型（通常是你配的主模型）做 architect，设计"怎么改"，另一个模型做 editor，实际执行改动。这样你可以用 Opus 这种强模型出方案，用 Sonnet 这种快模型写代码，兼顾质量和成本。会话内用 /architect 进入。

模型路由：接 OpenAI 兼容端点

Aider 原生支持 OpenAI 兼容端点，这意味着你可以接自建模型、国产模型、任何提供 OpenAI 兼容 API 的服务。

关键 flags：

• --model：指定主模型。接 OpenAI 兼容端点时，模型名前缀用 openai/。
• --openai-api-base：指定 API base URL。
• --openai-api-key：指定 API key（也可以用环境变量 OPENAI_API_KEY）。
• --no-show-model-warnings：关闭模型元数据警告。接自定义模型时 Aider 可能不认识模型名，会报警告，加这个 flag 静音。

完整命令示例（接自建/国产 OpenAI 兼容端点）：

OPENAI_API_KEY="$TOKEN" aider \
  --model openai/<model-name> \
  --openai-api-base https://<endpoint>/v1 \
  --no-show-model-warnings

--weak-model 是个省钱利器。Aider 在生成 commit message、做聊天历史摘要时会用一个"弱模型"——不需要强模型的推理能力，用个便宜快的就行。默认 Aider 会自动选一个，你也可以手动指定：

aider --model openai/strong-model --weak-model openai/cheap-model

会话内切换模型用 /model <name>，搜索可用模型列表用 /models <keyword>。这两个命令让你在不退出 Aider 的情况下灵活切换。

手术刀 patch 工作流

这是本文的重点。所谓"手术刀工作流"，核心思路是：给 Aider 一个狭窄的施工单，让它只改该改的地方，改完就停。 不是让它自由发挥重构你的代码库。

第一步：进入目标子目录 + --subtree-only

大仓库里直接在根目录启动 Aider，它会扫描整个仓库构建 repo map。如果你的仓库有几千个文件，这一步可能很慢，还可能遇到编码错误。正确做法是 cd 进你要改的子目录，加 --subtree-only，让 Aider 只考虑当前 git 子目录的文件。

第二步：控制上下文大小

• --no-auto-commits：关掉自动提交，保留人工审 diff 的环节。手术刀工作流里你必须看 diff。
• --map-tokens 1024：限制 repo map 大小。1024 是个实战中比较好用的值，够模型知道周围有什么，又不会占太多上下文。
• --encoding gb18030：如果你的仓库是老中文 C/C++ 项目，文件编码可能是 GB18030 而非 UTF-8。不加这个 flag，Aider 扫文件时会报编码错误。默认编码是 utf-8。

完整命令示例

cd path/to/target/module

aider \
  --subtree-only \
  --no-auto-commits \
  --map-tokens 1024 \
  --encoding gb18030 \
  --model openai/your-model \
  --openai-api-base https://your-endpoint/v1 \
  --no-show-model-warnings

第三步：写窄 prompt

进入 Aider 后，/add 你要改的文件，然后发 prompt。prompt 的原则：

1. 只实现施工单：明确说"实现 X 功能"，不要说"优化这个模块"。
2. 不重构无关代码：明确告诉模型"不要重构 touched lines 之外的代码"。
3. 不改 touched lines 外的格式：明确说"不要修改无关代码的格式"。
4. show diff and stop：让模型改完就停，不要继续发挥。

一个窄 prompt 的例子：

在 process_payment 函数里，把硬编码的 0.03 手续费改成从 config.fee_rate 读取。
只改这一个函数，不要动其他代码，不要重新格式化文件。改完显示 diff 并停止。

第四步：审 diff、验证、回退

• /diff：显示自上次消息以来的改动。仔细看，确认模型只改了该改的地方。
• /lint：lint 当前 in-chat 的文件。如果没有 in-chat 文件，lint 所有 dirty 文件。Aider 会尝试自动修复 lint 问题。
• /test：跑你指定的测试命令。非零退出码时，输出会自动加进聊天让模型修。
• /undo：如果改得不对，撤销 Aider 做的最后一次 git commit。注意 /undo 依赖 git commit，所以如果你用了 --no-auto-commits，需要先 /commit 才能 /undo——或者你手动 git stash 回退。

手术刀工作流的节奏是：窄 prompt → 看 diff → lint → test → 满意了 commit，不满意 undo。 每一步都在你的掌控之内。

非交互批量执行

Aider 不只是交互式工具，它也支持非交互模式，适合被上层 agent 调用或写脚本批量跑。

关键 flags：

• --message / -m：发单条消息，处理完退出。不进入交互界面。
• --message-file / -f：从文件读消息内容。适合 prompt 很长的情况。
• --yes-always：对所有确认说 yes，非交互模式必备。
• --dry-run：干跑，不改文件。先 dry-run 看看模型会做什么，再正式跑。

一个 --message 示例：

aider \
  --subtree-only \
  --no-auto-commits \
  --yes-always \
  --message "在 utils.py 的 parse_date 函数里，把 dateutil.parser.parse 换成 datetime.fromisoformat，只改这一个函数，不要动其他代码。" \
  utils.py

这条命令会：加载 utils.py，执行 prompt 里的改动，然后退出。你可以接着 git diff 审改动。

非交互模式的核心价值是可组合：上层 agent 生成施工单 → Aider 非交互执行 → 审 diff → 决定 accept 或 reject。整个流程是确定性的、可脚本化的。

警告：不要让上层 agent 打开交互式 Aider 后继续互聊。 交互式 Aider 需要人在终端里操作，agent 没法稳定地和它交互。用 --message 非交互模式才是正道。

另外还有几个非交互的快捷 flags：

• --test：跑测试、修问题后退出。
• --lint：lint 并修文件后退出。
• --commit：提交所有待提交改动后退出。

Git 集成

Aider 和 git 的深度集成是它区别于其他 AI 编程工具的核心特性。

默认行为：--auto-commits（默认 True）。每次 Aider 改完代码，自动 git add + git commit，commit message 由 --weak-model 生成。这意味着每次 AI 改动都是一个独立的 git commit，你可以用 git log 清晰看到 AI 做了什么，用 /undo 回退任意一次改动。

关掉自动提交：--no-auto-commits。如果你想在 commit 前人工审 diff，用这个 flag。改完后用 /commit 手动提交（commit message 可选，不提供的话 Aider 会生成）。

会话内跑 git：/git <command>。比如 /git log --oneline -5 看最近提交，/git status 看状态。注意 /git 的输出不会进聊天，不会消耗模型上下文。

commit message 质量：默认用 --weak-model 生成。如果你发现 commit message 质量不够好，可以换一个更强的 weak model，或者用 --no-auto-commits + 手动 /commit 自己写 message。

实战建议：手术刀工作流用 --no-auto-commits，日常快速改动用默认 auto-commits。 前者你需要控制每一步，后者你信任模型的小改动直接接受。

避坑实践

1. 脏大仓编码错误：进大仓库根目录直接跑 Aider，扫几千个文件时可能遇到 UTF-8/GB18030 编码错误。解法：cd 进目标子目录 + --subtree-only + --encoding gb18030（老中文仓）。
2. 纯 review 触发 edit format 报错：你只想让模型看看代码给意见，但默认 code 模式下模型试图生成改动，可能报 edit format 错误。解法：用 /ask 或启动时 --chat-mode ask。
3. 上层 agent 开交互式 Aider 互聊：agent 没法稳定操作交互式终端。解法：用 --message 非交互模式 + --yes-always。
4. token 失控：上下文快满了模型开始胡说。解法：/tokens 看占用，/drop 移除非必要文件，--map-tokens 1024 限 repo map 大小。
5. --map-tokens 设太大：repo map 占了半数上下文，留给实际代码的空间不够。解法：1024 是个好起点，大仓可以适当调高但别超过 2048。
6. 手术刀当大锤用：让 Aider 一次性重构整个模块，结果改得面目全非。解法：拆成多个窄施工单，每次只改一个函数/一个逻辑点，改完审 diff 再继续。
7. prompt 太宽：说"优化这个函数"而不是"把这里的 O(n²) 查找换成 dict 查找"。解法：prompt 要窄到像 code review 的 comment——明确说改什么、不改什么、改完就停。

速查表

Aider 的价值不在"让 AI 帮你写代码"，而在"让 AI 帮你精准地改代码"。管好上下文、写窄 prompt、审好 diff，它就是你手里最快的那把手术刀。