Aider:开发智能体,运行方式为 CLI

Aider 是一个命令行编程智能体,可根据您用法语提出的请求编辑文件,并将每次修改提交到 Git。在本地使用时,它通过 ollama_chat/ 前缀连接 Ollama;最关键的设置是上下文窗口,因为 Ollama 默认会将上下文静默截断至 2 000 个 token。要获得较为舒适的使用体验,至少需要 Devstral 这类拥有 240 亿参数的模型。
真正修改您文件的助手必须是可逆的、可预测的,并且能够在不将代码发送给第三方的情况下运行。Aider 符合这些要求,但前提是为本地模型正确配置它。本指南将涵盖安装、连接 Ollama、模型选择、聊天模式、Git 的作用以及您的测试,最后分析实际操作中遇到的问题。
#Aider 是什么,以及它在您的代码仓库中做什么
Aider 是一款开源命令行编程助手,它将自身定位为在终端中与 AI 进行结对编程的工具。您在 Git 仓库中运行 aider 命令,用自然语言描述一项变更,它就会提出文件修改方案、应用这些修改,然后将其记录为一次提交。它既能使用托管模型(Claude、GPT、DeepSeek),也能使用由 Ollama 或 LM Studio 提供服务的本地模型,因此是少数无需让项目中的任何一行代码离开本机即可使用的代码智能体之一。其官方仓库在 GitHub 上的星标数已超过 49,000。
它有三个区别于普通聊天的特点。首先,它维护一份代码仓库结构图:每次请求时,都会向模型发送文件列表,其中包括各文件的类、函数和主要签名,让模型知道该去哪里查找,而无需您展示全部内容。其次,它与 Git 集成:每次修改都会成为一个可撤销的提交。最后,它会反复运行您指定的命令,包括代码检查器和测试,并尝试修复失败的部分。它不是一个会自主浏览网络或启动服务器的智能体,而是一个由对话驱动的代码编辑器。
#安装 Aider
借助我们的经验和引导式路径,打造你的本地副驾驶,上手你的代码助手。
- 在线空间,终身可用
- PDF + 文件
- 30 天内退款
最简便的官方方法是使用 aider-install 软件包。它会将 Aider 安装到独立的 Python 环境中,并在需要时下载兼容的 Python 版本。此方式要求 Python 版本介于 3.8 和 3.13 之间。macOS、Linux 和 Windows 均提供基于 uv 的单行安装程序。旧的 pipx 安装方法仍然可用,但当前文档推荐使用 aider-install。
接下来进入项目根目录。如果该目录不是 Git 仓库,Aider 会提议创建一个,但最好由你自己初始化:下面所述的整套安全保障都依赖 Git。
#将其连接到 Ollama,避免上下文设置中的陷阱
Aider 针对 Ollama 的官方文档可归纳为四个步骤:设置变量 OLLAMA_API_BASE(通常地址为 http://127.0.0.1:11434),使用 ollama pull 下载模型,启动服务器,然后在模型名称前加上 ollama_chat/ 前缀来运行 aider。文档明确推荐使用 ollama_chat/ 前缀,而不是 ollama/。
代价最大的陷阱是上下文窗口。Ollama 默认使用 2,000 个 token 的上下文,这对编程智能体来说非常小,而且关键的是,它会悄无声息地丢弃超出窗口的内容。因此,您可能在不知情的情况下,与一个只收到您文件开头部分的模型对话。Aider 可以缓解这个问题:默认情况下,它会自行将 Ollama 的上下文窗口设为每次请求的长度,再加上供回复使用的 8,000 个 token。如果您更希望使用固定大小,就需要通过模型设置文件进行配置,而不是使用主配置文件。
上下文会占用内存:KV 缓存随上下文窗口增大而增长,而一个 240 亿参数的模型在 Q4 量化下已经占用约 14 GB,在 16 GB 显卡上留下的余量很少。上下文窗口指南和 KV 缓存量化指南提供了大致的规模参考。
#Aider 该选哪个本地模型
Aider 的表现取决于驱动它的模型,难点有两个:模型既要对代码进行推理,又要遵守严格的编辑格式。不遵守这一格式的模型会生成工具无法应用的修改。Aider 的公开排行榜基于六种编程语言的 225 道 Exercism 练习,衡量的正是这两方面的能力;榜单前列由托管的超大模型占据,能在个人计算机上运行的模型排名则明显靠后。在期待云端级别的结果之前,请先查看这一排行榜。
对于本地工作站,Mistral AI 和 All Hands AI 发布的 Devstral 24B 是一个合理的起点:它专为编程智能体设计,在 Ollama 模型库中的大小为 14 GB,并宣称提供 128,000 个 token 的上下文窗口。如果 GPU 显存为 12 GB 或更少,就需要改用更小的模型,并接受更多格式错误。《最佳本地 LLM 用于编程》指南比较了当前的候选模型;本指南不固定任何排名,因为排名变化太快。
| 可用内存 | 实际可运行的模型规模 | 可以期待 Aider 做到什么 |
|---|---|---|
| 8 至 12 GB | 70至140亿(5至9 GB) | 小范围的定向修改,一次处理一个文件;格式错误频繁 |
| 16 GB | 140至240亿(9至14 GB) | 在较短的上下文下修改两三个文件 |
| 24 GB 及以上 | 240至320亿(14至20 GB) | 日常使用尚可,上下文为 16 000 tokens 或更多 |
| 托管模型 | 超大型模型 | 可靠性更高;仅用于非保密代码仓库 |
#第一个变化:从提示词到提交
- 01添加正确的文件启动 aider 时,传入需要修改的文件,例如 aider src/api.py src/models.py。添加的文件就是它可以编辑的文件;仓库的其余内容则通过仓库映射供它了解。
- 02准确描述更改内容请写出完整的需求:「添加一个 GET /users/:id 端点,返回用户信息;若该用户不存在,则返回 404 错误。」模糊的需求会产生含糊的代码差异。
- 03检查 diffAider 会显示修改并应用它们。继续操作前,请用 /diff 查看这些修改:要拒绝修改,就应在此时提出,而不是再追加三次请求之后。
- 04检查提交每次编辑都会保存,并附带一条描述性消息。如果结果不佳,/undo 会撤销 Aider 所做的最后一次提交。
- 05按小步骤依次推进接下来,逐步要求添加测试、处理边界情况和记录日志,每次只进行一步。小步推进能保持上下文简短,让代码差异清晰可读。
#重要的聊天命令
Aider 提供数十条以斜杠开头的命令;掌握其中几条就足以开展工作。一般规则是:未添加到聊天中的内容无法修改,但仓库图谱能让模型知道其他文件的存在。
- /add et /drop
- 在聊天中添加或移除文件。移除不再需要的文件可以释放上下文,这对于本地模型非常重要。
- /read-only
- 添加一个仅供参考的文件:模型可以读取它,但不能编辑。适用于规范文件或接口契约。
- /ask, /code, /architect
- 切换聊天模式,可仅对一条消息生效,也可通过 /chat-mode 持续生效。
- /run et /test
- /run 启动 shell 命令,并可以将其输出发送到聊天中;/test 启动测试命令,如果测试失败,则将输出添加到聊天中,从而触发修复。
- /diff et /undo
- /diff 显示自您上一条消息以来的更改;/undo 撤销最近一次提交(如果该提交由 Aider 完成)。
- /tokens
- 显示当前上下文使用的 token 数量:要理解本地模型为什么会“忘记”,就应养成查看这一数值的习惯。
- /map
- 显示发送给模型的仓库结构映射。
#聊天模式:code、ask、architect
Aider 有四种聊天模式。code 模式是默认模式,会修改您的文件。ask 模式只讨论代码,绝不会修改代码。architect 模式让两个模型协作:先由架构模型提出解决方案,再由编辑模型将方案转化为具体的文件修改。help 模式回答有关 Aider 本身的问题。不存在名为“paired”的中间模式;能力更强的模型与速度更快的模型如何搭配,可通过 --model 和 --editor-model 选项设置。
文档推荐交替使用 /ask 和 /code:先在 ask 模式下讨论方案,再切换到 code 模式,只需输入一句「go ahead」即可执行商定的计划。这相当于使用单个模型的、更流畅的 architect 模式。对于中等规模的本地模型,这通常是最佳折中方案:既避免将两个模型加载到内存中,又能掌控计划。
architect 模式适用于推理能力强但代码编辑能力较差的模型。该模式需要两次请求,而不是一次:只有在 code 模式经常生成无效的 diff 时才启用。
#Git,你的安全网
Aider 借助 Git,让每次错误都可以撤销。每次编辑时,它都会提交更改,并附上描述性的提交消息;消息由弱模型根据 diff 和对话生成,采用 Conventional Commits(约定式提交)的风格。在修改包含尚未提交的更改的文件之前,它会先提交已有的更改:您的工作与 AI 的修改会在历史记录中保持分开。它创建的提交会在作者名中标注“(aider)”,便于查找。
随之而来的是大量小提交。良好的做法是让 Aider 在专用分支上工作,审阅后先将这些提交压缩合并,再合并分支。有两个选项值得了解:--no-auto-commits 禁用自动提交,--git-commit-verify 重新启用 pre-commit 钩子,而该工具默认通过 --no-verify 绕过这些钩子。如果您的团队依赖这些钩子,这个选项就至关重要。
#让测试在循环中运行
这项设置让 Aider 从代码生成器变成能够自行纠错的工具。启用 --test-cmd 和 --auto-test 后,Aider 会在每次修改后运行您的测试套件;如果命令返回非零退出码,它会读取输出并尝试修复。使用 --lint-cmd 进行 lint 检查也是同样的原理,而且 Aider 默认会对它编辑的文件进行 lint 检查。
有两点需要注意。测试命令必须执行得快:使用本地模型时,每轮循环仅生成就已经需要几十秒。此外,命令必须显示错误,并以非零退出码退出,否则 Aider 会以为一切正常。
#使用本地模型时哪些环节会失败,以及如何绕过这些问题
- 编辑格式错误
- 模型返回了工具无法应用的修改。请换用更大的模型,或测试 architect 模式。Aider 文档专门用一个故障排查页面介绍这些错误。
- 忘记上下文
- 症状:模型忽略了您刚刚添加的文件。可能原因:窗口太小或上下文已饱和。解决方法:使用 /tokens,移除无用文件(/drop),然后使用更大的上下文。
- 文件过长
- 一个包含数千行的文件会占满本地模型的上下文窗口。请将其拆分,或要求只修改某个具体函数。
- 模糊请求
- “改进这段代码”会产生不可预测的代码改动。请明确指出文件、函数和预期行为。
- 令牌限制错误
- Aider 会在模型超出自身限制时发出提示,并建议采取相应措施:要求更小范围的修改、拆分文件或更换模型。
#Aider 还是编辑器中的智能体
Aider 适合在终端中工作、希望保持 Git 历史整洁的用户。如果您更喜欢在 VS Code 中工作,Cline 提供类似的体验,每一步都需确认;如果您想要更自主的终端智能体,可以考虑 OpenCode。选择的关键不在于模型质量——模型质量是相同的——而在于您希望在哪里审阅代码差异。
| 标准 | Aider | 编辑器中的智能体(Cline) | 终端智能体(OpenCode) |
|---|---|---|---|
| 界面 | 终端 | VS Code | 终端 |
| Git 历史记录 | 每次编辑后自动提交 | 由您承担 | 由您承担 |
| 代码仓库上下文 | 代码仓库结构图,手动添加的文件 | 借助工具探索 | 借助工具探索 |
| 理想情况 | 有针对性且经过审查的修改 | 带视觉验证的多步骤任务 | 在终端中执行耗时较长的任务 |
- Aider + Ollama:终端中的完整工作流
- 最适合编程的本地 LLM
- 理解上下文窗口
- Cline + Ollama 位于 VS Code 中
- 终端中的 OpenCode + Ollama
- 在提交前使用本地 LLM 审查代码
- 来源:Aider 关于 Ollama 的文档
- 来源:Aider 的聊天模式
- 来源:Aider 的 Git 集成
- 来源:Aider 中的代码检查(lint)与测试
- 来源:Ollama 模型库中的 Devstral
Aider 真的能配合本地模型运行吗?+
通过 Ollama 使用 Aider 时,应选择哪个模型?+
为什么 Aider 看起来会忘记我的文件?+
如何撤销 Aider 的修改?+
是否应该禁用自动提交?+
Aider 能自动运行我的测试吗?+
有反馈、发现了错误,或想补充说明?请告诉我们,让这份指南对每个人都更有帮助。