Agentsop Aider

Aider SOP — 终端结对编程的操作系统

一句话：Aider 是“git 工作树 + tree-sitter 仓库地图 + 编辑格式 + 人类在环 REPL”的四元组。理解这四个原语，剩下的都是配置。

1. 何时激活本技能

下列任一情形成立时，按本 SOP 进入 Aider 工作模式：

• 任务是编辑已有 git 仓库里的代码（不是从零起项目）。
• 你能把改动范围收敛到 2–5 个文件，或愿意先用 /ask 让模型借助 repo-map 把范围找出来。
• 你需要逐步可回滚的修改历史（每次编辑一个 commit，/undo 一步回退）。
• 你在终端里工作（tmux / 远程 ssh / CI）；或者你在写一个把 Aider 当子进程驱动的 agent。
• 你关心编辑格式对模型质量的影响（diff / udiff / whole / patch 的选择问题）。
• 你需要 BYOM（自带模型），跑本地 LLM 或非主流厂商。

不应激活的反面信号：见 §6 反模式与边界。

2. 核心心智模型

2.1 四个原语

+------------------+   +------------------+   +------------------+   +------------------+
| 1. Git working   |   | 2. Tree-sitter   |   | 3. Edit format   |   | 4. REPL loop     |
|    tree          |   |    repo-map      |   |    (wire proto)  |   |    (你在环里)    |
|                  |   |                  |   |                  |   |                  |
| - per-edit       |   | - symbol-level   |   | - diff / udiff   |   | - /ask /code     |
|   commit         |   |   summary        |   |   / whole /      |   |   /architect     |
| - /undo          |   | - PageRank over  |   |   patch          |   | - 每轮人手确认   |
| - dirty 文件     |   |   import graph   |   | - 模型适配选择   |   | - 不自主         |
|   先 commit 再编 |   | - 动态预算       |   | - JSON 是反模式  |   |                  |
+------------------+   +------------------+   +------------------+   +------------------+

四者缺一不可：

• 去掉 git → 失去回滚与审计；
• 去掉 repo-map → 大仓库里 LLM 找不到正确文件（SWE-Bench Lite 上 repo-map 让 Aider 70.3% 命中正确文件 [aider.chat/2024/05/22/swe-bench-lite.html]）；
• 用错 edit format → 出现“lazy coding”、SEARCH 块找不到、JSON 句法破坏（udiff 在 GPT-4 Turbo 上把 refactor 基准从 20% 拉到 61% [aider.chat/2023/12/21/unified-diffs.html]）；
• 放弃 REPL → 退化为自主 agent，但 Aider 在 SWE-Bench 上恰好证明“人在环 + 多次尝试”比纯自主链路更稳。

2.2 LLM 看到的上下文分三层（优先级递减）

铁律：LLM 只允许编辑 /add-ed 的文件。这是 Aider 的安全边界。模型“改错了文件”几乎总是因为该文件没 /add 或你 /add 了太多无关文件。

2.3 上下文预算（25k 信号阈）

"Above about 25k tokens of context, most models start to become distracted." [aider.chat/docs/troubleshooting/edit-errors.html]

把这条当硬约束：超过 25k tokens，编辑准确率断崖式下降。/tokens 持续监控。

2.4 Repo-map 不是 RAG

repo-map 是 tree-sitter 提取的符号清单（类、函数、签名），用 PageRank 在源文件依赖图上排序，塞给 LLM 当地图。这不是 embedding 检索。

为什么不用 embeddings：

• LLM 能读签名，但读不懂向量。
• 不需要维护索引/重建/失效；代码改了下次自动重生成。
• /map 可以打印出来人工审计，向量做不到。

预算是动态的：你不 /add 任何文件时，map 占用大；/add 了正确文件后，map 自动缩小，省下的 token 给真正的代码。

2.5 编辑格式是“模型适配问题”，不是“用户偏好”

Aider 已经对常见模型选好默认值；只有出现编辑错误时才覆盖。

⇒ 不要把代码编辑包进 JSON tool-call。所有模型在 Aider 的实测里都因此变差，包括 Sonnet（详见 §5 案例 6 与引文）。

3. SOP 工作流

Phase 1 — Bootstrap（每次会话开始）

# 0. 在 git 仓库根目录。stash 或 commit 在途修改。
git status

# 1. 选模型（榜单当前前列：gpt-5, claude-3.7-sonnet, o3-pro, gemini-2.5-pro）
#    [aider.chat/docs/leaderboards/]

# 2. 最小启动 — 让 repo-map 帮 LLM 自己找路
aider

# 3. 范围已知 — 直接预加 + 风格文件
aider src/auth.py tests/test_auth.py --read CONVENTIONS.md

# 4. 强思考 + 廉价编辑（architect 模式）
aider --architect --model o1-preview --editor-model gpt-4o

# 5. 自动测试回路
aider --test-cmd "pytest -x" --auto-test

# 6. 巨型 monorepo
cd packages/feature-foo && aider --subtree-only
# 并维护 .aiderignore

Phase 2 — 收敛范围（/add 纪律）

不知道改哪个文件？
  → /ask which files implement <feature>?     (LLM 用 repo-map 回答)
  → /add 它命名的文件（只加这些）

知道改哪个文件？
  → 启动时 CLI 直接传，或 /add path/to/file.py

需要参考但不允许改的文件（schema, config, conventions）？
  → /read path/to/ref.md

铁律重申：少 /add，敢 /drop。/tokens 看现状。

Phase 3 — 讨论再动手（/ask → /code）

> /ask 当前的 auth 怎么实现？如果改成 JWT 会有什么破坏？
< [模型基于 repo-map + 已 /add 的文件作答]

> /ask 那我们用 PyJWT 还是 authlib？给出权衡。
< [...]

> /code 按刚才讨论的方案，把 sessions 改成 JWT。
< [模型给出 diff]
[Aider 自动应用 → 自动 git commit]

> /test pytest
< [失败时模型看到输出并尝试修复]

"Break your goal down into bite sized steps. Do them one at a time." [aider.chat/docs/usage/tips.html]

Phase 4 — Architect 模式（reasoning ≠ editing）

何时开启：你最好的 reasoner 编辑能力差（典型：o1-preview 单独跑 79.7%，搭配 Sonnet 当 editor 拉到 82.7% [aider.chat/2024/09/26/architect.html]）。

启用：--architect 或 /architect。Aider 自动把 editor 切到 editor-diff / editor-whole。

Phase 5 — 验证（lint / test / run）

/lint                  # 默认 --auto-lint 已开
/test pytest -x        # 失败时输出回填到 chat
/run npm run typecheck # 输出可选择性回填
/diff                  # 看上一轮的 diff

"Aider will try and fix any errors if the command returns a non-zero exit code." [aider.chat/docs/usage/lint-test.html]

formatter 注意：把会重写文件并返回非零的 formatter 包装在双跑脚本里（第一遍 format，第二遍验证）。

Phase 6 — 上下文卫生

Phase 7 — 收尾

• git log --oneline 看一次会话的提交链。
• 想压成一个 feature commit：git rebase -i HEAD~N（先保留中间 commit 当 undo 栈，最后压）。
• 提 PR — 提交信息已经是 Conventional Commits 风格。

4. 操作模型（命令速查）

源：[aider.chat/docs/usage/commands.html]

/add <files>      把文件加入 chat（LLM 可编辑）
/read <file>      加为只读（LLM 不能编辑）
/drop <files>     从 chat 移除
/ls               列出已知文件 + 标注哪些在 chat 里
/ask <q>          只讨论，不动文件
/code <req>       明确要求改代码（不加前缀也行）
/architect <req>  双模型 architect+editor
/model <name>     切换主模型
/clear            清 chat 历史（保留文件）
/reset            丢文件 + 清历史
/tokens           当前 token 占用
/map              打印当前 repo-map
/diff             上一轮的 diff
/undo             回退最近一次 Aider commit
/commit           为 chat 外的改动生成 commit
/run <cmd>        跑命令，可选回填输出（别名 !）
/test <cmd>       跑测试，失败时回填
/web <url>        抓网页转 markdown 进 chat
/copy             复制最后一条回复
/help <q>         关于 Aider 本身的问题

CLI 关键标志：

--model X                 主模型
--editor-model Y          editor 子模型（architect 用）
--edit-format whole|diff|udiff|patch
--editor-edit-format ...  editor 子模型的格式
--architect               进入 architect 模式
--read FILE               只读上下文（可多次）
--map-tokens N            repo-map 预算；N=0 关闭
--subtree-only            仅本子目录 + 子树
--auto-lint / --no-auto-lint
--test-cmd CMD --auto-test
--no-auto-commits         关掉自动提交（不建议）
--no-git                  完全脱 git（失去安全保障）
--message "..."           一次性非交互模式（脚本/agent 用）
--yes                     全部确认（脚本/agent 用）

配置文件：.aider.conf.yml（持久 CLI 默认）、.aiderignore（排除 repo-map 路径）、CONVENTIONS.md（用 --read 加载）。

5. 困境决策案例 (Examples / Scenarios)

案例 1 — “模型一直改错文件”

触发：LLM 改的不是你想改的文件，或编造路径。

诊断：LLM 只能安全编辑 /add 的文件。要么目标没 /add，要么 /add 太多导致干扰。

决策规则：

1. /ls 看现状。
2. 缺目标 → /add path/to/target.py。
3. 太多文件（>4–5 或 tokens > 25k）→ /drop 无关的。
4. 不知道哪个文件 → /ask which file implements X?，让 repo-map 替你答。

为什么有效：/add-ed 文件就是写集合（write-set）。repo-map 只是可读地图，不是写集合。

案例 2 — “大仓库里上下文炸了”

触发：tokens 涨到 25–50k+，响应被截断，模型在 monorepo 上明显变笨。

决策规则（从最便宜的做起）：

关键认知：不要“为了保险全 /add”。SWE-Bench 数据，只靠 repo-map Aider 仍然 70.3% 选对文件 [aider.chat/2024/05/22/swe-bench-lite.html]。

案例 3 — “diff 格式不停 hallucinate / SEARCH 块找不到”

触发：Aider 报 “SEARCH block not found in file”。

诊断：模型给的 SEARCH 文本和文件字节不匹配（空白、前次失败后状态漂移、纯臆造）。

决策规则：

1. /tokens — 接近 25k 时合规率下降。
2. /drop + /clear 减负。
3. 升级模型；弱模型“更容易违背系统提示” [aider.chat/docs/troubleshooting/edit-errors.html]。
4. 兜底格式：--edit-format whole。贵但稳。
5. 试 --architect —— 双步流程对“执行编辑指令”的依从性更高。

历史教训：GPT-4 Turbo 上 unified-diff 把 refactor 基准从 20% 拉到 61%，并把 “lazy comment” 砍到 1/3 [aider.chat/2023/12/21/unified-diffs.html]。说明 格式工程的边际收益经常高于换模型。

案例 4 — “architect 模式值得花这个钱吗？”

触发：硬推理任务；你有 o1/o3（强 reasoner，但编辑差）。

决策规则：

反直觉点：连 Sonnet 自配 editor 也涨（77.4 → 80.5%）。但 +3pp 是否值翻倍的 token 成本，取决于场景。