Aider：48.6K Star 的 Terminal Agent 祖师爷——2023 年就发明了 repo map + 自动 commit，上个 release 88% 新代码是自己写的；代价是 main 分支已沉默 3 个月，README 还停在 2025 年中

先建立坐标系：aider 是「所有 terminal coding agent 的爸爸」

工坊写了 80 多篇文章，居然一直没写 aider——这本身就是一个信息点。补课之前先看时间线：aider 2023 年 5 月 9 日建仓。那是什么年代？GPT-4 刚出三个月，GitHub Copilot 还是 IDE 里的补全插件，「agent」这个词在编程圈指的还是 CI 里的自动化任务。Claude Code 是 2025 年 2 月才出的，OpenAI Codex CLI 是 2025 年 4 月，OpenCode 是 2024 年底——aider 比它们全部早一到两年。你现在用的每个 terminal coding agent 的骨架子，几乎都是 aider 先搭的：

• repo map（仓库地图）：把整个代码库压缩成一份带符号定义的提纲塞进上下文，让 agent 在大仓库里不迷路——这是 aider 2023 年首创的，后来 Cursor / Claude Code 的 codebase indexing 思路都跟它同源；
• SEARCH/REPLACE 编辑块：让模型以「查找块 + 替换块」的格式输出修改，而不是重发整个文件——今天 Clawdbot / Cline 那套 diff 交互的原型；
• 自动 git commit：每次 AI 改动落一个带自动生成 message 的 commit，随时 /undo 回滚——「AI 写代码必须留后路」这个习惯，aider 是第一个产品化的；
• Polyglot 基准：aider 的 code editing benchmark 和 LLM leaderboard 是 2024 年各家模型厂商（包括 DeepSeek 出圈时）都拿来引用的行业标准之一。

所以它 48.6K Star 不是「又一个工具」的 Star，是「教科书」的 Star。而且它不是被时代抛弃的老古董：实测装完 v0.86.2 能正常跑通全链路（下面有完整命令），只是 GitHub 元数据开始露出疲态——release 停在 v0.86.0（2025-08-09），PyPI 上有个孤零零的 0.86.2，main 分支 2026-05-22 之后三个月零提交，1,838 个 open issues 无人认领。三年周更的传奇，现在进入休眠。这跟工坊写过的 vibe-kanban（公司倒闭）、Claw Code（195K Star 博物馆展品）凑在一起，是 2026 年开源 coding agent 生态的三张切片。

核心机制一：repo map——tree-sitter 提符号，PageRank 排重要性

aider 上下文压缩的核心是 repomap.py（867 行，全文可读）。机制分三步：

• tree-sitter 提取符号：用 tree-sitter 语法树按语言跑查询（queries），把每个文件里的函数 / 类 / 方法定义连同行号抽出来，生成 tag 列表。支持 100+ 语言，不支持的语种回退到 universal ctags；
• PageRank 排序：把 AST 当图——函数调用关系就是边——跑 PageRank 迭代，被引用多的符号排前面。这就是为什么大仓库里 aider 知道该先看 main() 而不是某个工具函数；
• 按 token 预算截断：--map-tokens 控制地图大小，默认 4096 tokens（实测日志显示 Repo-map: using 4096 tokens, auto refresh——注意 README 文档里还写着 1024，文档又过期了），按排名从高到低往地图里塞，塞不下就砍。

实测 aider --show-repo-map 能看到地图长什么样（就一个 8 行文件的 demo 仓库）：

hello.py:
│def greet(name):
⋮
│def add(a, b):
⋮

每个符号一行，│ 和 ⋮ 是 TreeContext 的树形标记。tag 数据落在仓库根目录的 .aider.tags.cache.v4/（diskcache SQLite，实测两张表 Settings + Cache，按文件路径 + mtime 做缓存键，文件没变就不重新解析）——所以第二次启动地图生成是秒级的。这套「本地语法分析 + 图排序 + 磁盘缓存」的工程组合，今天很多标榜 code intelligence 的新项目（工坊写过的 codedb、codegraph）用的还是同样的思路，只是换成了 C/Rust/Zig。

核心机制二：编辑格式——为什么 gpt-4o-mini 差点把我 demo 仓库写坏

aider 有五种编辑格式（--edit-format 可选 whole / diff / udiff / patch / diff-fenced），每种格式决定「模型怎么把修改吐回来」：

• whole：模型必须返回整个文件的新版本（file listing + fenced content）。上下文贵的模型（gpt-4o-mini 这类小模型）默认用它，因为输出简单、不容易错；
• diff：就是 2025 年以前叫 editblock 的 SEARCH/REPLACE 块——只输出改动段。大模型默认用它，省 token；
• udiff / patch：unified diff 和 git apply 风格的补丁；
• diff-fenced：SEARCH/REPLACE 块外面再套代码围栏，给弱模型降低解析难度。

坑就在格式和模型的不匹配上。我第一轮 mock 测试用的是默认配置（gpt-4o-mini → whole 格式），mock 返回的是 SEARCH/REPLACE 块——结果 aider 把 fence 里的内容当成「整个文件的新版本」直接写盘：hello.py 变成了字面量的 <<<<<<< SEARCH ... >>>>>>> REPLACE 原文，原来的 add() 函数整个没了。这不是 aider 的 bug，是格式契约被打破的正常后果——但对所有「拿老教程的 SEARCH/REPLACE 示例去喂新配置」的人来说，这就是实打实的坑：文件会坏，且 git 里能救（这就是自动 commit 的意义）。

另一个细节：diff 格式内部有个很妙的实现——search_replace.py 里的 RelativeIndenter，把每行缩进改写成「相对上一行的增量」再匹配（缩进变少用 ←←←← 标记）。这样模型写出来的代码块哪怕整体缩进层级跟原文差几级，也能正确对上——这是 2025 年 aider 为弱模型适配做的关键优化之一。还有个冷知识：whole 格式的 few-shot 示例里，aider 会把一段虚构的 show_greeting.py 教学对话（「Change the greeting to be more casual」+ 示例 assistant 回复）内联进每个请求——我扒 mock 请求日志时看到的，8.8K 字符的 system prompt 里全是这种「教学注入」。

核心机制三：git 集成——每次改动一个 commit，错了随时 undo

aider 的工作流哲学是「git 是安全网」：模型每应用一次编辑，它就自动生成一条 commit（--auto-commits 默认开）。commit message 由模型根据 diff 现场生成，实测 mock 返回 feat: make greet more excited，aider 原样落进 git log：

737c9a4 feat: make greet more excited
8f29611 init

配套机制：/undo 回滚上一个 AI commit；--dirty-commits 允许在有未提交改动时也干活（默认会先拦你）；--commit-prompt / COMMIT_PROMPT 自定义 commit 风格；--attribute-co-authored-by 给 commit 加 Co-Authored-By 署名。这套「改一步存一步」的节奏，跟现在 vibe-coding 那种「一口气改 20 个文件再 review」是两种哲学——前者每步可回滚，后者省交互但 diff 巨大。实测全链路只花了 2 个请求：1 个主请求（编辑）+ 1 个 commit message 请求，干净利落。

核心机制四：其他值得知道的——voice、watch、copypaste、lint/test

• Voice-to-code：--voice-input-device 开麦克风说话改代码（whisper 转写），2023 年就有这功能，比现在一堆「语音 agent」早两年；
• --watch-files：盯住 IDE 里的文件，你在编辑器里加注释它就开始干活——「IDE 集成」不用插件，靠文件监听；
• Copy/paste 模式：--copy-paste 把上下文和编辑结果自动复制进剪贴板，配合 ChatGPT / Claude 网页版用——没 API key 也能用上 aider 的上下文管理；
• 图片和网页：聊天里直接贴截图路径或 URL，模型当视觉上下文用；
• --auto-lint / --auto-test：改完自动跑 linter / 测试，红了让模型自己修。

上手：我在沙箱实测跑通的命令（含 mock 全链路验证）

Ubuntu 无头沙箱，Python 3.11 venv。全链路：安装 → 版本 → 命令面 → 坏 key → repo map → mock 服务验证「编辑应用 + 自动 commit」闭环，都走了一遍。

# 1) 安装（两条路都行，官方推荐前者）
python3 -m venv venv && source venv/bin/activate
pip install aider-install && aider-install     # 官方安装器
# 或直接：pip install aider-chat
aider --version                                 # v0.86.2

# 2) 基本用法
export OPENAI_API_KEY=sk-xxx                   # 或 ANTHROPIC_API_KEY / DEEPSEEK_API_KEY
aider hello.py                                  # 交互模式，把文件加进聊天
aider -m "make greet more excited"              # 单次消息，跑完退出
aider --model sonnet                            # 换模型（别名系统很全）
aider --edit-format diff                        # 强制 SEARCH/REPLACE 格式

# 3) 看仓库地图
aider --show-repo-map
# hello.py:
# │def greet(name):
# ⋮
# │def add(a, b):
# ⋮

# 4) 坏 key 实测（不静默，报错清晰）
aider -m "hi" --model gpt-4o-mini
# litellm.AuthenticationError: OpenAIException - Incorrect API key provided:
# sk-inval******-123. You can find your API key at https://platform.openai.com/account/api-keys.

# 5) mock 全链路（本地 OpenAI 兼容服务，SSE 流式）
OPENAI_API_KEY=sk-mock OPENAI_API_BASE=http://127.0.0.1:8778/v1 \
  aider hello.py --model gpt-4o-mini --edit-format diff -m "make greet more excited"
# Model: gpt-4o-mini with diff edit format
# Repo-map: using 4096 tokens, auto refresh
# Tokens: 2.6k sent, 50 received. Cost: $0.00042 message
# Applied edit to hello.py
# Commit 737c9a4 feat: make greet more excited

数据落盘：会话历史 .aider.chat.history.md、输入历史 .aider.input.history、repo map 缓存 .aider.tags.cache.v4/（自动加进 .gitignore）。首次启动默认会问「把 .aider* 加进 .gitignore？」和「要看 release notes 吗？」——非交互模式下全部自动取默认值 Yes，不会卡住（这点比不少 agent 工具强，但要注意它确实动了你的 .gitignore）。

实测与踩坑：5 个坑，第 1 个最危险

• 坑 1（最危险）：格式不匹配会把整个文件写坏。默认配置下 gpt-4o-mini 走 whole 格式，我 mock 返回 SEARCH/REPLACE 块，aider 把 fence 内容当整文件写盘——hello.py 变成字面量标记、add() 函数消失。任何拿 2025 年以前的教程示例（全讲 editblock 块）去喂新模型配置的人都会踩。解法：显式 --edit-format diff（或 udiff），或者干脆让模型按默认格式输出。幸好有自动 commit，git checkout -- . 一条命令就救回来了——这就是「git 是安全网」哲学的现场教学。
• 坑 2：editblock 改名了。v0.86 起 --edit-format 的合法值是 whole / diff / udiff / patch / diff-fenced（还有 editor-* 系列），editblock 这个老名字直接报 invalid choice。网上 90% 的 aider 教程还在写 --edit-format editblock，照抄必挂。
• 坑 3：README 过期严重。推荐模型还停在「Claude 3.7 Sonnet、DeepSeek R1 & Chat V3、OpenAI o1 / o3-mini / GPT-4o」——2025 年中期的榜单；--map-tokens 文档写默认 1024，实测是 4096；「weekly releases」的节奏 2025-08 就断了。看文档请直接看 aider --help 和源码。
• 坑 4：开发休眠期的生态风险。main 分支 2026-05-22 后零提交、release 停在 2025-08、1,838 个 open issues。项目没死（PyPI 0.86.2 还能装、核心链路全通），但不会有新模型适配、新格式支持了——2026 年的新模型（比如各家 o 系列后续）要靠 litellm 层兜底，aider 自己的 model settings 不会更新。
• 坑 5：首次启动的「默认 Yes」。非交互下它会自动把 .aider* 写进你的 .gitignore、自动确认看 release notes——脚本化跑的时候注意这些副作用。另外 analytics 默认开启，--analytics-disable 可关（沙箱里实测日志确认「Analytics have been permanently disabled」会写进会话记录）。

对比：Terminal Coding Agent 族谱上的站位

一句话定位：Claude Code / Codex 是「大厂重兵、按月迭代」的当红炸子鸡，aider 是「单核驱动、三年沉淀、范式输出」的教科书——repo map、编辑块、自动 commit 这三样它都是原创，但它的开发节奏已经追不上 2026 年的模型迭代了。跟工坊写过的其他开源 agent 比：它比 qwen-code（阿里系全家桶）纯粹，比 openclaude（fork 改造）正统，比 deepseek-reasonix（缓存优化狂魔）全面——它是「什么都能接、什么都不锁」的通用底座。

值不值得装：三个场景对号入座

• 想要一个「最小依赖、pip 一装就能跑、git 历史干净」的日常 agent：值得装。没有 node、没有 bun、没有二进制下载，一个 venv + pip 完事；自动 commit + /undo 让「AI 改坏了」的成本降到最低。配合 OpenRouter 或本地 Ollama，几乎零成本起步。
• 想研究 repo map / 编辑格式 / agent 上下文工程：必看。repomap.py（867 行）、search_replace.py 的 RelativeIndenter、coders/ 下每种格式的 prompt 设计，都是教科书级实现，比读论文快。它的 leaderboard 方法论（polyglot 基准）也是理解「模型代码能力评测」的入口。
• 想用一个「不站队」的 agent 跑多模型对比：合适。litellm 底座意味着 OpenAI / Anthropic / DeepSeek / Gemini / 本地模型随便切，--model 别名系统成熟——拿它当模型评测台比单家锁死的工具强。

最后说句公道话：aider 现在最大的风险不是代码烂，是「没人维护」。2026 年的新模型、新协议（MCP 支持很弱、没有 skills 生态）、新交互范式它都跟不上了——如果你要的是「跟着模型能力迭代走」的工具，选当红的那几个；如果你要的是「稳定、可读、可改、范式正统」的底座，aider 依然是那个 48.6K Star 的教科书。Apache-2.0，仓库 github.com/Aider-AI/aider，安装 pip install aider-chat——「AI pair programming in your terminal」，祖师爷教的活儿，到今天依然成立。