Aider：在终端里结对编程的 AI，把每次改动都变成一次 Git 提交

一、起因：给 12 万行遗留 Django 收口 HTTP 调用

我们有个跑了六年的内部中台，Django 单体，12 万行 Python，Python 3.8。历史包袱里最烦的一条是：各业务模块直接 `requests.get/post` 调下游，超时、重试、traceId 注入各写各的，全仓 387 个文件里有裸调用。SRE 要求统一收口到内部 SDK，顺带给关键函数补类型注解。 一开始的估算是 4 个后端 6 周。但这活儿的技术含量低、模式高度重复，属于典型的"人做会疯、机器做刚好"的场景。我作为团队里管 AI 工具的，接了这个改造。

二、需求拆解

• 上下文：单文件改动往往依赖跨文件的调用约定（SDK 构造、异常类型、重试策略），工具必须能看到符号级的仓库上下文，而不是只把当前文件塞进 prompt。
• 性能：387 个文件要在夜间窗口批量跑完，单文件端到端（含 lint、跑测试）控制在 5 分钟内。
• 成本：LLM 预算每月 300 美元以内，每次调用要能按文件、按 commit 审计 token。
• 部署约束：代码不出内网，必须走公司内部 LLM 网关；所有改动要能逐 commit review、能单独 revert。

三、方案设计：为什么是 Aider

Aider（Aider-AI/aider，Python，Apache 2.0，49,374 star / 5,033 fork，2026-05-22 还有提交）本质是"终端里的 AI 结对编程"。 备选方案我看了三个：Cursor 批量改造基本靠手动，脚本化能力弱；Copilot Workspace 代码要出境，直接出局；自己写脚本调 LLM 改文件——能跑，但代码上下文怎么选、模型返回的 diff 怎么可靠地 apply、失败怎么回滚，这三件事全得自己造。 选 Aider 的决定性理由有两条：一是它的 repo map 用 tree-sitter 抽符号级结构，不用把整仓塞 prompt 就能让模型知道调用关系；二是它原生绑 Git，每轮改动自动落一次 commit，`/undo` 就能退。对我们这种"必须可审计、可回滚"的批量改造，这不是加分项，是准入项。

四、落地实现

4.1 配置：接内部网关，约束行为

# .aider.conf.yml
model: openai/Qwen2.5-Coder-32B-Instruct
openai-api-base: http://llm-gateway.internal/v1
openai-api-key: env:INTERNAL_LLM_KEY
auto-commits: true
attribute-author: false
attribute-committer: false
map-tokens: 4096
read: CONVENTIONS.md
lint-cmd:
  - "python: ruff check --fix"
test-cmd: pytest -q tests/test_http_migration.py

`CONVENTIONS.md` 里写死约束：不得重命名公共函数、不得改动异常类型、不得动 migrations 目录。这份文件每轮都会被读进上下文，比在 prompt 里重复啰嗦靠谱。

4.2 单点验证：先拿一个模块人机对话

git checkout -b refactor/http-sdk
aider app/order/services.py app/order/client.py

# 会话内
/add CONVENTIONS.md mycorp/http/client.py
> 把本文件所有 requests 调用替换为 mycorp.http.Client，
> 保留原有超时值，异常统一转成 UpstreamError，不改其他逻辑
/run pytest -q tests/test_order_http.py
/diff
/undo   # 不满意就退，每次改动都是一个 commit

这一步跑了 11 个文件，摸清了模型的脾气：它对"替换"很稳，对"顺手优化"很上瘾。

4.3 批量执行：无头模式 + 自己控提交粒度

#!/usr/bin/env bash
set -uo pipefail

grep -rl "import requests" --include="*.py" app/ \
  | grep -v "/migrations/" > files.txt

while read -r f; do
  aider --no-auto-commits --yes --message \
    "把本文件所有 requests 调用替换为 mycorp.http.Client，保留超时值，异常转为 UpstreamError。" \
    "$f" || { echo "$f" >> failed.txt; git checkout -- "$f"; continue; }

  # 只接受小改动，diff 超过 60 行说明模型跑偏了
  changed=$(git diff --numstat "$f" | awk '{print $1+$2}')
  if [ "$changed" -gt 60 ]; then
    echo "$f $changed" >> oversized.txt; git checkout -- "$f"; continue
  fi

  git add "$f"
  git commit -q -m "refactor(http): migrate $(basename "$f") to internal SDK"
done 

关键点是**把提交权收回来**：批量场景下 aider 的自动提交粒度太细，而且会跟仓库的 pre-commit hook 打架。这里用 `--no-auto-commits`，配合"diff 行数阈值"这道闸门，把明显跑偏的改动直接丢弃。

五、效果与数据

指标	人工方案（预估）	Aider 方案（实测）
完成 387 个文件	4 人 × 6 周	3 人日（含 review）
单文件端到端耗时	约 25 分钟	平均 3.5 分钟
首次 diff 可用率	—	62%，加 lint/test 自愈循环后 89%
回归测试通过率	—	91% → 99.2%（剩余为预存在失败）
LLM 总支出	—	约 $186（估算，含重试，共 1200+ 次调用）
人力成本	约 ¥48,000	约 ¥3,600（估算）

单次改造成本约 $0.05（估算，32B 模型走内部网关）。最终人工只 review 了 412 个 commit，其中 31 个被 revert。

六、踩过的坑

坑一：repo map 把 token 撑爆

现象：跑大文件时反复报上下文超限，`/tokens` 显示光 repo map 就占了 60k。 排查：`.py` 被索引的不只业务代码，还有 protobuf 生成文件和 `migrations/`，这些文件符号多、价值为零。 解决：加 `.aiderignore` 排除生成目录，配置里 `map-tokens: 4096` 封顶，对大文件加 `--subtree-only`。token 消耗直接降了约 70%。

坑二：auto-commit 撞上 pre-commit hook

现象：aider 提交时被仓库的 ruff/black hook 拦下，它认为提交失败，把同一份改动反复提交了四遍。 解决：批量模式一律 `--no-auto-commits`；交互模式则把格式化交给 aider 自己的 `lint-cmd`，让它在提交前就修干净，而不是等 hook 来拒。

坑三：模型"顺手"重构

现象：只让它换 HTTP 客户端，它把一个内部函数重命名了，下游 import 全挂。 排查：`git diff` 里出现了与任务无关的符号改名。 解决：三件事——`CONVENTIONS.md` 明确禁止、`test-cmd` 让模型自己跑测试兜底、批量脚本加 diff 行数阈值自动丢弃。第三道闸门拦下的比前两道加起来还多。

七、复盘与扩展

做对的：**先选形态再选模型**。终端 + Git 原生这个形态，决定了改造过程天然产出可审计的 commit 流水，比任何 prompt 技巧都值钱。另外"先单点验证 11 个文件再批量"这个顺序不能省，模型的脾气只能在真实 diff 里摸出来。 做差的：一开始没有 golden set，前 50 个文件全靠人肉 review 才发现"顺手重构"的问题，返工了大约半天。批量循环也没做并发控制——aider 是单进程，我们后面靠多个 worktree 并行才把夜间窗口用满，但同一个仓的 Git 锁有过两次冲突。 扩展方向：把 `--message` 模式接到 CI 上，让 PR 里的 lint 失败自动生成修复 commit；低风险重命名走本地小模型，跨模块重构才路由到大模型，成本还能再降一个量级；`.aider.conf.yml` + `CONVENTIONS.md` 应该进团队模板仓，而不是每个项目重写一遍。