跳到主要内容
Code Agents

第4章 SWE-Agent 与 ACI 论文精读

深度精读 SWE-Agent (NeurIPS 2024)、OpenHands、CodeR、SWE-Search、MAGIS、Aider repo map 等 Code Agent 奠基论文,理解 ACI(Agent-Computer Interface)设计哲学

paper swe-agent aci openhands coder swe-search magis repo-map

第4章 📄 SWE-Agent 与 ACI 论文精读

一句话:ACI(Agent-Computer Interface)是 Code Agent 时代的”操作系统接口”——Princeton 团队在 SWE-Agent(NeurIPS 2024)中提出:为人设计的 bash/vim 给 LLM 用根本不行,得专门为 LLM 设计接口 ——这一思想是所有现代 Code Agent(包括 Cursor、Claude Code、OpenHands)的奠基。

📑 目录

一、为什么要专门精读这些论文

商业产品(Cursor / Devin / Claude Code)是黑盒,你看不到:

  • 它们怎么决定 prompt 模板
  • 它们怎么设计 tool 接口
  • 它们怎么从失败中恢复

开源论文 + 实现是唯一窗口。本章精读 6 个奠基级工作:

  1. SWE-Agent(2024-04,NeurIPS 2024)—— ACI 鼻祖 ⭐⭐⭐
  2. OpenHands(2024-07)—— SWE-Agent 的产品化继承
  3. CodeR(2024-06)—— 多 agent + 任务图
  4. SWE-Search(2024-10)—— MCTS 搜索增强
  5. MAGIS(2024-03)—— 多 agent 角色分工(类比 SWE 团队)
  6. Aider repo map(2023+)—— 不是论文但思想极重要

二、SWE-Agent ⭐(NeurIPS 2024)

论文:Yang et al., “SWE-Agent: Agent-Computer Interfaces Enable Automated Software Engineering”,NeurIPS 2024,arXiv 2405.15793。

作者:John Yang, Carlos E. Jimenez, Alexander Wettig, Kilian Lieret, Shunyu Yao, Karthik Narasimhan, Ofir Press(普林斯顿)。

2.1 核心问题

bash 是给人用的,LLM 用 bash 表现极差。

具体例子:用 GPT-4 + bash 直接跑 SWE-bench,Pass Rate 只有 1.96%。 但同样 GPT-4 配上 SWE-Agent 的 ACI ——Pass Rate 飙到 12.47%(SWE-bench Lite 上)。

6 倍提升——纯靠改接口,不换模型。

2.2 ACI 是什么

Agent-Computer Interface:专门为 LLM 设计的”操作系统接口”,对比传统接口:

传统(给人)ACI(给 LLM)
cat file.py 输出全文,可能 1 万行open file.py 只显示前 100 行 + “Total: 1234 lines”
vim 全屏交互goto N / scroll_up / scroll_down 离散指令
grep -r "pattern" . 输出杂乱search_dir <pattern> 结构化输出 + 高亮
sed -i 's/x/y/' file 易错edit <line> <new> 失败给详细错误
编辑后无确认编辑后自动展示更新后的 100 行,LLM 立刻看到结果

2.3 ACI 的 6 个核心工具

┌─────────────────────────────────────────────────┐
│  1. open <file>          打开文件                  │
│  2. goto N               跳到第 N 行              │
│  3. scroll_up / scroll_down  翻页                 │
│  4. create <file>        创建空文件               │
│  5. edit <start>:<end> <new>  替换某行范围        │
│  6. search_dir <pat> [dir]   搜索                 │
│  7. submit               提交补丁                  │
└─────────────────────────────────────────────────┘

每个工具:

  • 入参极简(LLM 容易学会调用)
  • 出参结构化(JSON-like,LLM 容易解析)
  • 错误信息友好(失败时告诉 LLM 怎么修)

2.4 关键洞察:Edit 工具的设计精髓

# ❌ 不好的接口
edit("oldtext", "newtext")
# 问题:LLM 经常猜错 oldtext(因为缩进、空格),猜不准就丢失编辑

# ✅ SWE-Agent 的接口
edit("21:25", """
def hello():
    print("world")
""")
# 优势:
# 1. 行号精确,不猜
# 2. 自动验证缩进/语法,失败给错误信息
# 3. 编辑成功后自动 print 更新后的 100 行,LLM 验证

# 失败示例:
# Error: edited file is not valid Python (line 24: unexpected indent)
# Hint: Try edit again with correct indentation.

2.5 实验结果(论文 Table 4)

系统模型SWE-bench Lite PassSWE-bench full Pass
GPT-4 + raw bashGPT-41.96%1.74%
SWE-Agent + GPT-4GPT-418.0%12.47%
SWE-Agent + Claude 3 OpusClaude 3 Opus18.13%11.65%

结论:ACI 设计 > 模型升级。

三、ACI 黄金原则

SWE-Agent 论文与后续工作总结的 5 大黄金原则:

3.1 Simple(简洁)

工具数 < 10 个,每个工具 1-3 个参数。LLM 工具学习曲线越陡,失败率越高。

3.2 Concise output(输出简洁)

  • 一次只给 LLM 100 行(不是全文件)
  • 用 emoji / 高亮标记重要信息
  • 不输出冗余(如 --total: 1234 lines, 27Kb 比 cat 整个文件好得多)

3.3 Augment, not replace(增强,不取代)

ACI 是给 LLM 的”放大镜”,不是把 bash 完全屏蔽。需要时仍可让 LLM 调 raw bash(比如装依赖)。

3.4 Faithful errors(诚实的错误)

# 好的错误
Error: file 'src/util.py' not found.
Suggestion: Did you mean 'src/utils.py'?

# 坏的错误
Error: ENOENT

3.5 Self-validating(自验证)

每个 action 之后,自动展示结果状态。LLM 不用问”我刚才改对了吗”——它眼里已经看到了。

⭐ 这 5 条是设计任何 agent tool(不只是 code)的通用原则。MCP 协议、Anthropic Tool Use、OpenAI Function Calling 都遵循。

四、OpenHands(arXiv 2407.16741)

论文:Wang et al., “OpenHands: An Open Platform for AI Software Developers as Generalist Agents”,arXiv 2407.16741。

主要贡献:把 SWE-Agent 的 ACI 思想产品化 + 平台化:

4.1 增强点

  1. 更完整的 Action 集合:从 SWE-Agent 的 6 个扩展到 20+

    • 加入 browser (上 Stack Overflow / 看文档)
    • 加入 jupyter (跑 notebook 验证想法)
    • 加入 task_finished / delegate 等 control flow action

  2. Multi-Agent 框架:

    Manager Agent (LLM 1)
     ├── Coder Agent (LLM 2)
     ├── Reviewer Agent (LLM 3)
     └── Tester Agent (LLM 4)

  3. Sandbox 强化:Docker + Firecracker 双方案,可控的资源 quota。

  4. Action-Observation pair 标准化:

    Action:       run_command("pytest test_foo.py")
Observation:  CommandOutput(exit_code=1, stdout="...", stderr="FAIL test_foo")

4.2 实验结果

框架模型SWE-bench Verified
OpenHands(默认)Claude 3.5 Sonnet26%
OpenHandsGPT-4o22%
OpenHands(2026 最新)Claude Sonnet 4.566%

注:从 2024 的 26% 到 2026 的 66%——模型能力增长 + scaffolding 改进双驱动。

4.3 工程价值

OpenHands = 当前最完整、最工程化的开源 Code Agent。

  • 50K+ stars,活跃 contributors
  • Docker / Cloud 双部署
  • SDK + CLI 双入口
  • 已被 SWE-bench 官方 evaluator 集成

五、CodeR / MAGIS / SWE-Search

5.1 CodeR(arXiv 2406.01304)

贡献:用任务图(task graph) 拆解 SWE-bench 问题。

Issue: "测试在 macOS 上失败"
  ↓
Task Graph:
  ├── 1. Locate failing test
  ├── 2. Read test file + traceback
  ├── 3. Identify root cause
  ├── 4. Patch
  └── 5. Verify

每个 task 由独立 sub-agent 执行

核心 idea:任务越复杂,显式拆图比单 LLM 一次出方案稳定得多。

5.2 MAGIS(arXiv 2403.17927)

贡献:多 agent + SWE 团队角色映射。

Manager           — 决策、分配
Repository Custodian — 维护 repo 索引
Developer         — 写代码
QA Engineer       — 写/跑测试

每个 agent 独立 LLM,通过 message passing 协作。

类比:MAGIS 把”软件公司里的角色”映射到 agent ——这一思想后来被 AutoGen / CrewAI / LangGraph Hierarchical 等多 agent 框架广泛吸收(详见模块六 Agent Runtime)。

5.3 SWE-Search(arXiv 2410.20285)

贡献:Monte Carlo Tree Search + 自我反思 增强 Code Agent。

核心思路:

  • 每个 step,agent 生成多个候选 action
  • 用 LLM 做 evaluator 评分
  • MCTS 选最优分支扩展
  • 失败时反思,更新 belief

实验结果:在 SWE-Agent baseline 上 +10% 左右(SWE-bench Lite)。

trade-off:更准确,但成本(LLM 调用次数)高 5-10 倍。

六、Aider’s repo map(非论文,但同样重要)

虽然 Aider 没正式发论文,但作者 Paul Gauthier 在博客系统讨论了 repo map 设计哲学。地址:https://aider.chat/2023/10/22/repomap.html

6.1 问题

LLM 上下文有限。全文塞 repo 不可行:

  • 1000 文件 × 平均 200 行 = 20 万行
  • 完全超出 1M context window
  • 而且大部分代码与当前任务无关

6.2 Aider 的解法

用 tree-sitter 解析每个文件,只提取类名 + 函数签名 + 重要变量:

# 全文(500 行)
class UserService:
    def __init__(self, db, cache):
        self.db = db
        self.cache = cache
        # ... 100 行实现 ...
    
    def get_user(self, user_id):
        # ... 50 行实现 ...
    
    # ...10 个其他方法...

# repo map 只显示
class UserService:
    def __init__(self, db, cache)
    def get_user(self, user_id)
    def update_user(self, user_id, data)
    # ...

6.3 PageRank-like 重要性

Aider 还用 PageRank-like 算法 排序 ——被引用最多的类/函数优先纳入 repo map(因为它们最关键)。

6.4 与 Cursor / OpenHands 的比较

  • Cursor:用 embedding-based RAG(把代码切片做向量索引)
  • OpenHands:用 grep / find tool 让 agent 主动探索
  • Aider:用 tree-sitter + PageRank 静态生成 repo map

三种思路 trade-off:

  • Embedding:对自然语言查询友好,但对代码符号查询弱
  • Grep:精确,但要求 agent 知道关键词
  • repo map:不需要 agent 探索,直接给静态地图——但更新不及时(改文件后要重新生成)

业界趋势:三种结合用——Cursor 自带 embedding,Composer 模式下也支持 grep tool;OpenHands 在 grep 之外加了向量索引;Aider 在 repo map 之外也支持 grep。

七、Auto-Code-Rover(arXiv 2404.05427)

贡献:把 spec extraction + code retrieval 结合,首次系统讨论”Code Agent 怎么找到正确的代码位置”。

7.1 核心 pipeline

Issue
  ↓
1. Spec Extraction(LLM)
   "这个 bug 的根因是 X 类的 Y 方法在条件 Z 下行为错误"
  ↓
2. Code Retrieval
   - search_class("X")
   - search_method("Y")
   - get_callers(Y)
  ↓
3. Patch Generation
   只针对找到的少量代码段生成 patch
  ↓
4. Verification
   跑测试

7.2 关键洞察

  • 不是”agent 自己探索” ——而是先用 LLM 抽 spec,再有针对性地检索
  • 减少 agent 走弯路(乱看不相关代码)

对比:OpenHands 是”勤奋型”(让 agent 自己 grep),Auto-Code-Rover 是”思考型”(先想清楚再找)。两种思路各有适用场景。

八、对比与综合

8.1 核心思想脉络

SWE-Agent(2024-04)
   └── 提出 ACI ——LM-friendly 接口
       │
       ├── OpenHands(2024-07)
       │   └── 工程化 + Multi-Agent + Browser 扩展
       │
       ├── CodeR(2024-06)
       │   └── 任务图拆解
       │
       ├── MAGIS(2024-03)  ← 注:实际比 SWE-Agent 早 1 个月
       │   └── 多 agent 角色分工
       │
       ├── Auto-Code-Rover(2024-04)
       │   └── Spec 抽取 + 检索
       │
       └── SWE-Search(2024-10)
           └── MCTS 搜索 + 反思

Aider(2023-08+, 非论文)
   └── repo map = 静态 lazy 索引

8.2 设计原则总结

原则来源应用
ACI(LM-friendly 接口)SWE-Agent所有 Code Agent
Multi-agent 角色分工MAGISOpenHands / AutoGen / CrewAI
任务图拆解CodeR复杂 issue 处理
Spec 先于 CodeAuto-Code-RoverCursor BugBot / Sweep
Repo mapAiderCursor / Continue.dev
MCTS 搜索SWE-Search高准确度场景

8.3 推荐精读顺序

  1. SWE-Agent ⭐⭐⭐ 必读 —— ACI 奠基
  2. OpenHands ⭐⭐ 必读 —— 产品化继承
  3. Aider repo map blog ⭐⭐ 必读 —— 索引设计
  4. MAGIS / CodeR ⭐ 选读 —— 多 agent 思想
  5. Auto-Code-Rover ⭐ 选读 —— 检索思路
  6. SWE-Search ⭐ 选读 —— 高级搜索

✅ 自我检验清单

  • 能解释什么是 ACI(Agent-Computer Interface)
  • 能背出 SWE-Agent 的 6 个核心工具
  • 能说出 ACI 的 5 大设计原则
  • 能解释为什么 GPT-4 + raw bash 在 SWE-bench 只有 1.96%
  • 能区分 OpenHands / CodeR / MAGIS / SWE-Search 的核心 idea
  • 能讲清楚 Aider repo map 的设计动机
  • 能说出 Auto-Code-Rover 的 spec-first 思路与”勤奋探索型”的差异

📚 参考资料

核心论文

官方实现

博客 / 二次资料

下一章:第5章 SWE-bench 全家桶与代码评测 —— SWE-bench / Verified / Lite / Multimodal / Live / Multi-SWE-bench / LiveCodeBench / Aider polyglot 全景对比与避坑指南。