在 AI 编程助手遍地开花的 2026 年，Aider 凭借「命令行 AI 结对编程」的独特定位脱颖而出：它不寄生在某款编辑器里，而是直接在你的终端跑起来，读取整个代码库、按你的自然语言指令修改多个文件，并把每一次改动自动提交到 Git。本文从安装、模型配置、三种编辑模式，到对接 One API 网关与一次 FastAPI 实战，带你把 Aider 真正用进日常开发流程。
一、Aider 是什么，为什么值得用
Aider 是一个开源（Apache-2.0）的命令行工具，核心思路是把大模型直接接到你的代码仓库上。和传统「把代码复制进聊天框再粘回来」的方式不同，Aider 自己维护一份仓库地图（repo map），知道每个文件的作用与依赖关系，能够跨文件地理解需求，并直接调用编辑工具改写源码。
它最适合三类场景：第一，给一个已有项目加新功能，比如「给这个 Flask 应用加一个 /health 接口」；第二，修 bug，把报错贴给它让它定位并修复；第三，做小步重构，比如「把这个函数抽成工具类」。所有这些动作，Aider 都会生成 diff，并可选地自动 git commit，让你随时能 review 或回退。
二、安装与最小验证
Aider 要求 Python 3.9 及以上。官方推荐用 pipx 或 uv 隔离安装，避免污染全局环境。
# 用 pip 直接装
pip install aider-install
# 或用 uv（更快、隔离更好）
uv tool install aider-install
# 验证
aider --version
安装完成后，进入任意一个 Git 仓库目录即可启动。Aider 会自动检测当前目录是否为 Git 仓库——如果不是，它会提示你先 git init，因为自动提交依赖 Git。
三、三种编辑模式：edit / ask / architect
Aider 内置三种与模型协作的模式，对应不同的「放权程度」。理解它们的区别，是用好 Aider 的第一步。
| 模式 | 模型能做什么 | 适合场景 |
|---|---|---|
| edit（默认） | 直接读写你指定的文件 | 明确的功能开发、修 bug |
| ask | 只回答、不改动任何文件 | 先问清楚方案再动手 |
| architect | 先出方案与改动清单，再交 edit 模式落地 | 多文件、架构级改动 |
切换模式很简单：在交互界面输入 /mode ask 或启动时加参数。日常开发中，先用 ask 模式让模型输出方案，确认无误再切回 edit 让它真正写代码，是避免「它擅自改了一堆东西」的稳妥做法。如果你在做多智能体编排，思路上与 LangGraph 状态图编排 异曲同工：都是先把「决策」和「执行」解耦。
四、配置模型：从 OpenAI 到本地网关
Aider 底层用 LiteLLM 接入各家模型，因此几乎支持所有主流供应商。最省事的用法是把 OpenAI 的 key 放进环境变量：
export OPENAI_API_KEY="sk-..."
aider --model gpt-4o
但很多团队希望统一走自建网关，既能聚合多家模型，又能做配额与审计。这时把 Aider 指向你自己的 One API 网关 就很合适：
# 指向 OpenAI 兼容网关
export OPENAI_API_BASE="https://your-gateway/v1"
export OPENAI_API_KEY="gateway-token"
# 模型名取网关里配置的渠道名，例如
aider --model openai/your-model-name
如果要完全本地推理、数据不出内网，也可以直连 Ollama。结合 DeepSeek 本地部署 的经验，用量化后的 32B/70B 模型就能获得相当可用的编辑能力：
export OLLAMA_BASE_URL="http://127.0.0.1:11434"
aider --model ollama/qwen2.5-coder:32b
配置项可以固化到项目根目录的 .aider.conf.yml，避免每次敲一长串参数。常见字段包括 model、weak-model（用于只做分类/路由的小模型）、edit-format 和 auto-commits。
五、日常用法：把需求交给 Aider
启动后，先告诉 Aider 它要操作哪些文件，再下达自然语言指令。
# 在交互界面里
/add src/service.py
/add tests/test_service.py
> 给 UserService 增加一个按邮箱精确查找的方法，并补上单元测试
如果你只想跑一次就退出（比如写进脚本或 CI），用 --message 非交互模式：
aider --message "把 config.py 里的超时时间从 30 改成 60 秒" --no-auto-commit
每次改动后，Aider 会打印 diff 并询问是否提交。熟练之后可以开启自动提交，让它每完成一个小任务就生成一条带说明的 commit，配合 Git 的细粒度历史，review 成本很低。
六、与 Git 协作：自动提交与评审
Git 集成是 Aider 最被低估的能力。它不只是「改完帮你 commit」，还提供了一组评审命令：
| 命令 | 作用 |
|---|---|
| /diff | 查看本次会话累积的所有改动 |
| /undo | 撤销上一次 AI 编辑并回退对应 commit |
| /run | 在仓库里执行任意 shell 命令，如跑测试 |
| –watch | 监控文件变化，外部改完也能被 Aider 感知 |
更进阶的玩法，是把 Aider 接进持续集成。例如用 GitHub Actions 搭建的 CI 流水线，在 PR 里让 Aider 根据评审意见自动补一个小修复并提交。注意这个动作要谨慎，务必让人先 review 生成的 diff，再合并。
七、实战：给 FastAPI 项目加一个限流接口
假设你有一个 FastAPI 服务，现在需要加一个带简单令牌桶限流的接口。把需求交给 Aider：
> 在 app/main.py 里新增 GET /api/ping，要求：
> 1. 用内存令牌桶限制每个 IP 每秒最多 5 次请求
> 2. 超限返回 429 和 Retry-After 头
> 3. 补一个对应测试
Aider 会先读懂现有路由结构，再落地下面的实现（示意）：
# app/limiter.py
import time
from collections import defaultdict
_bucket: dict[str, list[float]] = defaultdict(list)
RATE = 5 # 每秒允许次数
CAP = RATE # 桶容量
def allow(ip: str) -> bool:
now = time.time()
ts = _bucket[ip]
ts[:] = [t for t in ts if now - t < 1.0]
if len(ts) >= CAP:
return False
ts.append(now)
return True
# app/main.py 新增
from fastapi import Request, HTTPException
from .limiter import allow
@app.get("/api/ping")
def ping(request: Request):
ip = request.client.host
if not allow(ip):
raise HTTPException(
status_code=429,
headers={"Retry-After": "1"},
detail="too many requests",
)
return {"ok": True}
这段实现与 FastAPI 流式对话 API 的部署方式一脉相承，都是先在本地把接口写稳、再用 Nginx 反向代理 暴露出去。Aider 改完后，跑一遍 /run pytest 确认测试通过，再让它自动提交，整个过程不到一分钟。
八、进阶技巧
语音输入。Aider 内置语音模式，适合手不想离开键盘以外的场景：aider --voice-language zh，用中文口述需求即可。
强弱模型分工。设置 weak-model 让小模型承担「该改哪个文件」「要不要提交」这类路由判断，大模型只负责真正写代码，既省 token 又更快。
仓库地图裁剪。大项目里 Aider 默认会把整个 repo map 塞进上下文，token 消耗惊人。用 /drop 临时排除无关目录，或用 .aiderignore 像 .gitignore 一样屏蔽依赖与生成物，能显著降本。
九、常见坑与排障
| 现象 | 原因与对策 |
|---|---|
| 启动报「not a git repository」 | 进错目录，先 cd 到仓库根或 git init |
| 模型乱改不相关文件 | 开启 architect 模式先出方案；用 /drop 收窄范围 |
| token 消耗过快 | 配置 weak-model、加 .aiderignore、缩小 repo map |
| 网关 401 | 检查 OPENAI_API_BASE 与 OPENAI_API_KEY 是否匹配网关渠道 |
| 中文输入乱码 | 终端用 UTF-8；语音模式显式加 –voice-language zh |
十、总结
Aider 把「命令行 AI 结对编程」从概念变成了每天能用的工具：它读懂你的仓库、按自然语言改代码、自动提交 Git，还能对接 Dify+Ollama 这类私有化方案或 One API 网关统一管理模型。把它放进你的编辑器（配合 VS Code 插件）和容器化开发环境（参考 Docker Compose 编排），就能把重复性编码真正交给 AI，你只负责评审与决策。
