SWE-Agent — Princeton SWE-bench 解法

是什么

SWE-Agent 是 Princeton 2024 年做的专门给 LLM 设计的命令行界面，让 LLM 在 SWE-bench（一个真实 GitHub issue 修复评测集）上自动改 bug。

日常类比：你给小学生一把瑞士军刀（什么都能干，但每个工具都要先学），结果他切水果反而切到手；不如直接给他一把削皮刀——只能削皮，但怎么用都不会出错。

react 给 LLM 任意 shell（ls / cd / vim / sed / awk 全开），SWE-Agent 给 LLM 量身定制的精简菜单：每个工具都易学且不易出错，而且反馈能让 LLM 看懂（不像 shell 报错满屏 stack trace）。

为什么重要

不理解 SWE-Agent，下面这些事都没法解释：

• 为什么 OpenHands / Cline / Cursor / Claude Code 的工具列表都很短，且名字都很像（view / edit / run）——它们都学了 ACI 的设计
• 为什么”给 LLM 一个 shell 让它干活”听起来直觉但效果很差——LLM 容易迷路、改错、卡死
• 为什么同一个 GPT-4，换上 SWE-Agent 的接口，SWE-bench Lite 解决率从 12.5% 跳到 26.9%——没换模型，只换 UI
• 为什么 agentless 后来反过来说”agent 有时候不如 pipeline”——SWE-Agent 是 agent 路线的代表，两条路在 2024 年正好对立

核心要点

SWE-Agent 的核心概念叫 ACI（Agent-Computer Interface，agent 专用接口）。它的三个支柱：

1. 专用工具，不是通用 shell：只给 LLM 五个核心命令——navigate（在文件树里移动）/ search（按关键词搜代码）/ open（打开某文件并显示一段窗口）/ edit（在指定行替换内容）/ run_tests（跑测试）。每个工具的输出都为 LLM 优化过——格式工整、行号清晰、错误信息简短。

2. 窗口式上下文管理：LLM 上下文有限。SWE-Agent 不让它一次看 1000 行代码，而是开个滑动窗口（默认 100 行），LLM 用 scroll_up / scroll_down 移动窗口。类比：你在 IDE 里也不会一次看完整文件，是用滚动条上下翻。

3. 历史压缩：跑了 30 多步后，前面的命令历史会爆。SWE-Agent 把旧命令折叠成”摘要”，只保留最近几步详细输出。类比：长会议把前面讨论压成一句”已确定 X、Y”，再继续讨论。

这三个加起来就是一个完整的 ACI：LLM 看到的不是真实电脑，而是一个为 LLM 简化过的电脑。

实践案例

案例 1：bug 修复全流程

GitHub issue：json.dumps fails on datetime objects。

SWE-Agent 的动作序列：

1. search "json.dumps"       → 找到 src/json/encoder.py 第 247 行
2. open src/json/encoder.py  → 打开窗口看到 default() 方法
3. scroll_down               → 看完整方法
4. edit 247:255 加 datetime 处理分支
5. run_tests tests/test_json → 通过
6. submit                    → 提交补丁

整个过程 LLM 没用 shell——它只用这几个为它设计的命令。每一步输出格式都一样（行号 + 代码 + 当前位置），LLM 不会迷路。

案例 2：与 agentless 对比

同一个 bug，两种修法：

维度	SWE-Agent	agentless
形式	30+ 轮 agent 循环（边想边干）	3 步 pipeline（定位 → 修复 → 验证）
自由度	高，LLM 自己决定下一步	低，每步固定流程
SWE-bench Lite	26.9% (Claude 3.5 + ACI)	27.3%（GPT-4o + pipeline）
失败模式	navigate 错路径 / 卡循环	定位错文件就全错
调试	难，要看 30 步 trace	易，三步分别看

性能差不多，思路完全相反。这是 2024 年 LLM 工程界一个标志性分歧。

案例 3：失败模式（你能看到 SWE-Agent 卡在哪）

实际跑起来 SWE-Agent 经常出这几种问题：

1. navigate 错路径：LLM 以为文件在 src/utils/ 实际在 tests/utils/，开错文件后所有后续操作都白费
2. edit 改坏导致测试雪崩：edit 把缩进改错（Python 致命），后面 run_tests 全失败，但 LLM 看不出根因
3. 死循环：search 不到东西 → 换关键词再 search → 还是不到 → 一直 search 到耗尽 turn 上限

这些失败模式直接启发了后来 agentless 的设计：“那干脆不让 agent 自由发挥，每步都规定死。“

踩过的坑

1. ACI 不等于”功能少就行”：早期版本工具更少（只有 view / edit），但 LLM 反而更容易卡——因为没有 search 它就只能挨个 open。够用 + 易学 才是 ACI 的精髓
2. edit 要返回完整上下文：edit 只返回”成功/失败”是不够的——LLM 看不见改完的代码长什么样会反复瞎改。SWE-Agent 的 edit 永远返回改后的窗口给 LLM 看
3. test 输出要截断：pytest 跑 1000 个测试可能输出 5MB，塞进上下文会爆。SWE-Agent 只保留第一个失败的 trace + 总结
4. 不能给 sudo / rm -rf：早期跑过几次 LLM “rm -rf src/” 然后宣告 bug 修复——测试没了当然全过。后来工具集做了白名单

适用 vs 不适用场景

适用：

• 真实 GitHub issue 修复（SWE-bench 是它的主场）
• 中等大小代码库（< 100 万行）—— 太小用 agentless，太大 ACI 也救不了
• 需要”探索 + 试错”的任务——agent 路线的优势就是不预设流程

不适用：

• bug 定位极明确的场景 → 直接用 agentless pipeline 更稳
• 高 stake 生产代码 → agent 30 步里任何一步出错都会被引入，不如人工
• 多文件大改动 → SWE-Agent 默认窗口式编辑，跨文件协调能力弱

历史小故事（可跳过）

• 2024-04：Princeton NLP（Yang / Jimenez 等，与 SWE-bench 同组）发 SWE-Agent 论文。第一次提出 ACI 概念，把 SWE-bench Lite 从 12.5% 推到 26.9%
• 2024-05：OpenHands（前身 OpenDevin）社区项目复用 SWE-Agent 的工具集设计——同样是 view / edit / run / search 五件套
• 2024-08：agentless 论文发表，明确反对 agent 路线：“不用 agent，3 步 pipeline 就够了”。在 SWE-bench 上跑出和 SWE-Agent 接近的分数
• 2025：Claude Code / Cursor / Cline 这些产品都学到”工具不要太通用”——它们的 file_edit / grep / bash 都是 SWE-Agent ACI 思路的延伸

学到什么

1. 接口决定上限：同一个 LLM 模型，给不同接口，能力天差地别。换 UI 比换模型便宜得多
2. 为 LLM 设计 UI 不是为人设计 UI：人喜欢功能多、灵活；LLM 喜欢功能少、可预测、反馈清晰
3. 工具反馈格式很关键：每个工具的输出格式要稳定、有结构，LLM 才能稳定解析。乱七八糟的 stack trace 是 LLM 的噩梦
4. agent vs pipeline 是路线分歧：SWE-Agent 代表 agent 派（自由发挥），agentless 代表 pipeline 派（每步规定死）。两条路都能到 ~27%，工具设计者要根据场景选

延伸阅读

• 论文 PDF：arXiv:2405.15793（Princeton NLP，NeurIPS 2024）
• 项目代码：github.com/princeton-nlp/SWE-agent（开源，活跃维护）
• SWE-bench leaderboard：swebench.com（看 SWE-Agent 历史排名变化）
• agentless —— 反 agent 论的代表，与 SWE-Agent 对照看
• react —— SWE-Agent 的循环控制思想来自 ReAct

关联

• react —— 提供 think → act → observe 的循环框架，SWE-Agent 在其上加了 ACI
• agentless —— 反对 agent 路线，与 SWE-Agent 形成路线分歧
• swe-bench —— 评测集，SWE-Agent 的主战场
• toolformer —— “LLM + 工具”的早期工作，SWE-Agent 把”工具”细化到了”为 LLM 优化的工具”

反向链接

• agentless —— Agentless — 反 Agent 派的 SWE-bench 解法
• apex-policy-exploration —— APEX — 给自进化 agent 配一张”策略图”防止它走老路
• code-as-agent-harness —— Code as Agent Harness — 把代码当 agent 的”骨架”来重新看 agentic AI
• continue —— Continue — 让 AI code review 跑成 git 跟踪的 PR status check
• copilot-rct —— Copilot RCT — AI 编程助手的第一个严格随机对照实验
• crewai —— CrewAI — 把多 Agent 编排做成”组团队”
• misevolution-2509 —— Misevolution — 自进化 agent 也会”越改越坏”，连顶配模型也躲不过
• openhands —— OpenHands — 开源 AI 软件工程师
• react —— React UI 组件库
• self-evolving-agents-survey —— 自进化 AI agent 综述 — 给”会自己升级”的 agent 画一张统一地图
• swe-bench —— SWE-bench — 真实 GitHub Issue 评测