本页速览普林斯顿团队 2024 年的经典工作，提出 Agent-Computer Interface（ACI）：工具接口该为模型设计，而不是为人设计。靠接口优化把 SWE-bench 解决率从 3.8% 拉到 12.5%，并用 mini-SWE-agent 的 100 行代码反向证明 scaffold 的时代性。

SWE-agent

SWE-agent 是 2024 年最有影响力的开源 coding agent 之一，但它的价值不在「又一个能修 bug 的 agent」，而在于它提出并验证了一个可迁移的方法论：Agent-Computer Interface（ACI）——像研究人机交互（HCI）一样，认真研究模型与计算机之间的接口。这个思想后来渗透进了几乎所有 coding agent 的工具设计，包括你在 Claude Code 和 Cursor 里看到的编辑工具形态。

同时，SWE-agent 团队自己的后续动作——把系统砍到 100 行的 mini-SWE-agent——又亲手给这个故事补了下半集：模型变强之后，精心设计的 scaffold 还剩多少价值？这一页把这两半都讲清楚。

一、学术背景：与 SWE-bench 同源的「出题人做的 agent」

SWE-agent 出自普林斯顿大学 NLP 组（Princeton NLP），核心成员包括 John Yang、Carlos E. Jimenez、Alexander Wettig、Kilian Lieret、Shunyu Yao（ReAct 论文一作）、Karthik Narasimhan 和 Ofir Press。

理解 SWE-agent 必须先理解它和 SWE-bench 的关系：

SWE-bench（arXiv:2310.06770，ICLR 2024）：同一个团队 2023 年 10 月发布的基准，从 12 个知名 Python 仓库（Django、Flask、scikit-learn、matplotlib 等）抽取 2294 个真实 GitHub issue，要求模型生成补丁并通过仓库原有测试。它是 coding agent 领域第一个「贴近真实软件工程」的硬基准，至今仍是事实标准（详见进阶·评估）。
SWE-agent（arXiv:2405.15793，NeurIPS 2024，2024 年 5 月挂出 v1）：出题团队自己做的解题系统。论文标题就叫 SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering。

「出题人做 agent」带来两个独特价值。第一，他们最清楚基准在考什么、难点在哪——SWE-bench 的痛点不是写代码，而是在一个几十万行的陌生仓库里定位、理解、最小化修改。第二，他们天然有动机把 SWE-agent 做成研究平台而非产品：开源、可配置、方便别人做对照实验。后来社区确实把它用成了「scaffold 研究的公共底座」。

论文发布时的成绩：在 SWE-bench 全量测试集上，GPT-4 Turbo + SWE-agent 的 pass@1 为 12.5%，而此前最好的非交互式 RAG 系统只有 3.8%——一个 3 倍多的跃升，且不是靠换模型实现的。这个数字今天看起来很小，但在 2024 年上半年它直接证明了「agent 形态」相对「一次性检索+生成」的压倒性优势，也把社区注意力从 prompt 拉到了 interface。

与 Devin 的时间线巧合

2024 年 3 月 Cognition 发布 Devin 演示，声称在 SWE-bench 上解决约 13.8% 的 issue，但不开放、不复现。SWE-agent 在一个月后以完全开源的姿态拿到可比的成绩，被社区称为「开源版 Devin」。这也是它早期传播极快的原因之一。

二、核心创新：Agent-Computer Interface（ACI）

问题：人在用的工具，模型用不好

论文的出发点是一个观察：人类工程师有 IDE、有鼠标、有视觉工作记忆，工具是围绕「人的长处和短板」设计的。LM agent 是一个全新的用户品类——它的能力和缺陷 profile 跟人完全不同：

维度	人类工程师	LM agent
视觉浏览	强，一眼扫一屏代码	无，只能靠文本窗口逐段读
短期记忆	有限但可靠（刚看过的还记得）	只看 context window 里有什么，滚出去就忘
精确编辑	手抖、点错行，但 IDE 有 undo	行号算术极易出错，错了没人兜底
并行多窗口	可以开十个标签页	单线串行，一步一个动作
犯错代价	低（人能立刻发现）	高（错误输出会污染后续所有推理）

直接给模型一个裸 shell（bash 随便敲）会怎样？论文的消融实验给出了答案：在 SWE-bench Lite 的 300 个实例子集上，同样的 GPT-4 Turbo，裸 shell 基线比完整 ACI 低 10.7 个百分点。也就是说在那个模型能力下，接口设计贡献了比换一代模型还大的增益。

ACI 的四个设计决策

SWE-agent 的 ACI 由一组定制命令和反馈格式构成，核心决策如下：

1. 专用文件查看器，而不是 cat。 模型 cat 一个大文件会瞬间灌爆 context，且多数内容无关。SWE-agent 的 viewer 每次只显示约 100 行（带行号），配 scroll_up / scroll_down / goto 命令翻页。消融显示窗口缩到 30 行会损失约 3.7 个百分点（信息太少，来回翻页浪费步数）；而显示整个文件会让模型「失焦」。100 行是 GPT-4 时代的经验甜点。

2. 受限的编辑命令 + linter 守门。 编辑不用 sed/vim，而是专用的 edit 命令：指定行范围、替换内容。关键设计是每次编辑后自动跑 linter（如 pyflakes），语法错误直接拒绝本次编辑并反馈错误信息——不让坏代码落盘。这利用了模型「即时纠错能力强、自我觉察能力弱」的特点：把「预防错误」做成接口的一部分。消融中移除编辑接口（含 linter）是单项损失最大的一项，约 7.7 个百分点。

3. 克制的搜索反馈。 全目录字符串搜索只返回「哪些文件有匹配」，不返回每个匹配的上下文。团队发现给模型看太多匹配片段反而让它困惑——反馈的信息密度是调参调出来的，不是越多越好。

4. 永不留空的输出。 命令执行成功但无输出时，返回 Your command ran successfully and did not produce any output.，而不是空字符串。空响应会让模型怀疑命令没执行，开始重复尝试或怀疑环境坏了——一个典型的人类绝不会遇到、但模型天天踩的坑。

┌───────────────────────── ACI 交互循环 ─────────────────────────┐
│                                                                │
│  LM ──► 命令（open/edit/scroll_down/search_dir/...）           │
│           │                                                    │
│           ▼                                                    │
│      ACI 层：解析 → 校验 → 执行 → linter 守门                  │
│           │                                                    │
│           ▼                                                    │
│      结构化反馈（100 行窗口 / 文件列表 / 明确的空输出消息）     │
│           │                                                    │
│           └────► 追加进历史，进入下一步推理                    │
└────────────────────────────────────────────────────────────────┘

一段典型的交互长这样（简化示意）：

模型:  open "django/core/management/base.py"
环境:  [File: /repo/django/core/management/base.py (612 lines total)]
       1  import os
       2  import sys
       ...
       100      self.stdout = OutputWrapper(stdout or sys.stdout)

模型:  edit 88:92
       <<replacement code>>
环境:  The file ... has been edited. Review the changes and make sure
       they are as expected (correct indentation, no duplicate lines, etc).
       Edit the file again if necessary.

模型:  python -m pytest tests/admin_scripts/tests.py -x
环境:  3 failed, 41 passed in 12.3s
       FAILED tests/admin_scripts/tests.py::TestRunserver::test_bug_xxxx
       ...

注意反馈文本的语气——「Review the changes and make sure they are as expected」——这是写给人看的提醒，但真正的读者是模型。反馈文案本身就是 prompt engineering 的一部分，每个词都在塑造模型下一步的行为。这一点在组件·Prompt Engineering 里有更系统的展开。

ACI 不是什么

为了避免误读，明确三条边界：

ACI ≠ 工具数量。 SWE-agent 的命令集并不大，赢在每个命令的反馈格式被反复调过。堆 50 个未经打磨的工具是典型的反模式。
ACI ≠ 隐藏复杂性。 它没有替模型「自动修好」任何东西，只是把状态以模型最易消费的方式呈现。模型仍然要自己定位 bug、自己决定改哪几行。
ACI 的有效性依赖底座模型。 论文也测试了 Claude、GPT-3.5 等模型，结论是接口设计的好处大体可迁移，但具体参数（如窗口大小）是针对 GPT-4 调的，换模型要重调。

ACI 的本质是「错误预防 + 反馈工程」

注意这四个决策没有一个是「教模型更强的能力」，全都是在减少模型犯错的概率和让反馈恰好够用。这和人类 UX 设计的原则（affordance、约束、即时反馈）一一对应——这正是论文把 HCI 概念借过来的原因。做工具设计时先问「模型最容易在哪一步搞砸」，比问「还能给模型什么能力」回报高得多。更多通用原则见组件·工具与 MCP。

三、成绩演变：从 12.5% 到被自己的「mini 版」接管

SWE-agent 系谱在 SWE-bench 上的成绩，大致是三个阶段：

时间	系统	成绩	说明
2024-05	GPT-4 Turbo + SWE-agent	12.5%（全量集）	论文数字，此前非交互式 SOTA 3.8%
2024-2025	Claude 3.5/3.7 Sonnet + SWE-agent	持续刷新 Lite/Verified 榜单	SWE-agent 成为各家新模型的标准 scaffold 之一
2025-02	SWE-agent v1.0.1	官方宣布 SWE-bench Full 集 SOTA	release 说明里特别指出：Full 集上非 Lite/Verified 子集的提升更大，「只评 Lite/Verified 会讲不完整的故事」
2025-07 起	各模型 + mini-SWE-agent	Claude 4 Sonnet 64.9%（Verified）	100 行 scaffold 追平重型系统
2026-02	Claude 4.5 Opus (high) + mini-SWE-agent v2.0.0	76.8%（Verified，单次成本 $0.75）	官方 SWE-bench 榜单当前头部区间

两个值得记住的读数。第一，从 12.5% 到 76.8%，两年时间涨了 6 倍，但其中模型换了好几代、scaffold 反而越变越简单——这是理解这个阶段最重要的视角。第二，Verified 子集正在被「刷穿」：头部模型普遍越过 70% 后，社区已在转向更难的 SWE-bench Pro 等新基准，读榜时注意区分数据集版本（SWE-bench Full / Lite / Verified / Pro 是四样东西）。

四、scaffold 研究价值：一组天然的对照实验

SWE-agent 家族对研究社区最大的贡献，可能不是某个具体系统，而是它提供了控制变量的实验台。

SWE-bench 官方榜单上有一组独特的设计：「SWE-bench (bash only)」榜单——所有参评系统都跑同一个 mini-SWE-agent scaffold，唯一变量是底座模型。截至 2026 年，这个榜单从低到高横跨：

同一 scaffold（mini-SWE-agent），只换模型：
  Llama 4 Scout        9.1%
  GPT-4o              21.6%
  Gemini 2.5 Pro      53.6%
  Claude 4 Sonnet     64.9%
  GPT 5.2             72.8%
  Claude 4.5 Opus     76.8%   ← 2026-02

这在 agent 研究里是非常稀缺的设置。对比其他产品的刷榜方式——每家的 scaffold、prompt、重试策略、成本预算都不公开且各不相同——你根本无法回答「分数高是因为模型强还是 harness 强」。而固定 scaffold 的榜单直接给出模型的净能力排序；反过来，固定模型换 scaffold（像 SWE-agent 论文的消融那样），给出的是 scaffold 的净贡献。「模型 × scaffold」两个轴被拆开测量，这是 SWE-agent 一系工作的方法论遗产。

对从业者的直接推论：

评估任何 agent 系统时，永远报告「模型版本 + scaffold 版本」的组合，单独报一个数字没有可比性。
想公平对比两个模型，把它们塞进同一个最简 scaffold（比如直接 fork mini-SWE-agent），而不是各自接在自家 harness 里。
这也是进阶·评估反复强调的：harness 是被测系统的一部分，不是测试设备的一部分。

五、架构与代码组织

SWE-agent 的仓库（github.com/SWE-agent/SWE-agent）是一个为「做实验」而不是「跑产品」设计的代码库，v1.x 时代的结构大致是：

sweagent/
├── agent/          # Agent 主循环：step 逻辑、历史处理器（history processors）
│                   # 负责把超长轨迹压缩/裁剪进 context window
├── environment/    # SWEEnv：Docker 沙箱里起一个带仓库的容器
│                   # 提供 bash 会话、文件读写、命令白名单
├── tools/          # ACI 本体：每个工具一个目录
│                   # （file viewer、edit+lint、search 等，YAML 定义接口）
└── run.py          # 入口：给定 issue → 起环境 → 跑 loop → 存 trajectory

几个对自学者有用的设计点：

工具是配置出来的，不是写死在代码里的。 每个 ACI 工具用 YAML 声明命令名、参数格式、文档字符串和调用方式。想实验一个新接口，加一个目录、写个 YAML 就行——这也是仓库 README 自称「built to make it easy to invent new ACIs」的原因。
History processor 是一等公民。 怎么把已经爆炸的对话历史塞回 context window，被抽象成可插拔的处理器（裁剪、摘要、折叠观察等）。这部分思想在组件·上下文工程里被进一步泛化。
环境执行被抽成 SWE-ReX。 沙箱执行（Docker/云端/本地）后来独立成单独仓库 SWE-ReX，供 SWE-agent 和第三方复用——「执行 runtime」和「agent 逻辑」解耦，是后来的 agent 框架普遍采用的分层。
轨迹（trajectory）全量落盘。 每一步的输入输出都存成结构化文件，配套有 trajectory 浏览器。做可观测性和失败分析时这套东西比任何监控平台都直接。

⚠️ 重要现状提示：官方文档已明确 SWE-agent 进入 maintenance-only 模式，被 mini-SWE-agent 取代。想学最新代码、跑最新榜单，应该看 mini-SWE-agent；SWE-agent 仓库的价值在于读论文复现和做 ACI/工具集消融实验。这是定位问题，不是质量问题。

六、后续发展：团队亲手完成的「自我颠覆」

SWE-agent 团队后续的动作，构成了这个案例最有教育意义的部分——他们主动回答了一个所有 scaffold 作者都该怕的问题：如果模型继续变强，我精心调的这些接口还值多少钱？

mini-SWE-agent：100 行的回答

2025 年 7 月，团队发布 mini-SWE-agent，设计哲学与 SWE-agent 完全相反：

只有 bash 一个工具，连模型原生的 tool-calling API 都不用，全靠文本协议。
完全线性的历史，每步直接 append，不做任何裁剪摘要——轨迹即消息。
每步动作用 subprocess.run 独立执行，不维护有状态的 shell 会话，沙箱化只需把 subprocess.run 换成 docker exec。
核心 agent 类约 100 行 Python。

结果：Claude 4 Sonnet + mini-SWE-agent 在 SWE-bench Verified 上拿到 64.9%，与当时重型系统持平；2026 年初的 v2 版本把 Claude 4.5 Opus 推到 76.8%，官方 README 称整个 Verified 集上可超过 74%。团队给出的解释很坦诚：SWE-agent 时代的许多接口设计（文件查看器、编辑守卫），是在补偿 GPT-4 的能力缺陷；当模型强到能自己写 sed、自己控制输出长度时，这些补偿反而成了束缚和 token 浪费。

mini-SWE-agent 目前仍在活跃演进：已进入 v2 版本，被官方用为 SWE-bench (bash only) 榜单的标准 scaffold，README 称被 Meta、NVIDIA、IBM、Anyscale 等公司及多所大学用于评测和训练（RL/微调时的基座 scaffold——因为足够简单，不会让模型过拟合到特定 harness）。项目方还宣称它被 Ramp 的 SWE-Bench 评测和 DataCurve 的 DeepSWE 评测采用（注：此为项目自述，引用前可自行核对）。

它同时也是一个可以直接用的命令行工具和 Python 库。装法（来自官方 README）：

bash

pip install mini-swe-agent
mini   # 启动 CLI，本地终端里直接干活

Python 绑定同样极简——整个 agent 的就绪过程就这三行：

python

from minisweagent.agents.default import DefaultAgent
from minisweagent.models.litellm_model import LitellmModel
from minisweagent.environments.local import LocalEnvironment

# 模型走 litellm，环境是本地 shell；换成 Docker 只需换 Environment
agent = DefaultAgent(
    LitellmModel(model_name="anthropic/claude-sonnet-4-5"),
    LocalEnvironment(),
)
agent.run("Write a sudoku game")

对照着看，SWE-agent 与 mini-SWE-agent 的分工已经很清晰：

	SWE-agent	mini-SWE-agent
状态	维护模式	活跃开发（v2）
工具	定制 ACI 命令集（YAML 可配）	只有 bash
历史管理	可插拔 history processors	纯线性 append
适用场景	ACI/工具集消融研究、论文复现	日常 CLI、跑榜、RL/微调基座 scaffold
代码量级	完整工程化仓库	核心 agent 类约 100 行

学术线：SWE-smith 与数据侧

团队的另一条线是 SWE-smith（arXiv:2504.21798，NeurIPS 2025 Datasets & Benchmarks Spotlight）：把任意 GitHub 仓库自动变成「SWE-gym」式训练环境，批量造出可验证的软件工程任务，用于生成数万条训练轨迹。逻辑很顺：SWE-bench（评测）→ SWE-agent/mini（scaffold）→ SWE-smith（数据）——一个团队把 coding agent 研究的三块基础设施都补齐了。

关于「商业化」

截至 2026 年 8 月，SWE-agent/mini-SWE-agent 仍是学术主导的开源项目（MIT 协议），没有独立商业公司；SWE-bench 官网致谢的支持方包括 Open Philanthropy、AWS、Modal、a16z、OpenAI、Anthropic 等。团队成员的去向和公司化动态如有更新，请以官网与仓库公告为准，不要采信二手传闻。

七、ACI 思想的可迁移启示

SWE-agent 这个案例最值得带走的东西，按优先级排：

把 agent 当用户，给工具做 UX。 任何领域的 agent（数据库运维、数据分析、客服后台）都该问一遍 SWE-agent 问过的问题：这个接口是按谁的直觉设计的？反馈里有没有模型不需要的噪音？空输出、报错格式、分页粒度，都是性能变量。这条原则已经泛化进了 MCP 时代的工具设计实践，见组件·工具与 MCP。
先做「防错」，再做「赋能」。 linter 守门（坏编辑直接拒绝）比任何「教模型写好代码」的 prompt 都有效。检查你的工具集：哪些错误可以在接口层被结构性消灭，而不是留给模型的自律？
scaffold 有半衰期，把它当易耗品。 ACI 的甜点窗口（100 行文件视图等）是模型能力的函数，模型换代后就要重调——甚至可能像 mini-SWE-agent 一样直接删掉。架构上把 scaffold 做成可替换的薄层，别让它长成无法替换的承重墙。这是实践·设计原则里「保持简单」原则的实证注脚。
消融实验是 scaffold 开发的纪律。 SWE-agent 论文最被低估的部分是那张 Table 2：每个设计决策都有单独的对照数字。给自己的 agent 做同样的纪律——加一个工具前先想好怎么测它的边际贡献。
benchmark 作者下场做 agent，是理解 benchmark 的最快路径。 反过来说，读一个 benchmark 论文时，顺手读出题团队自己做的 baseline agent，你会比 90% 的使用者更早知道分数的「含水量」和天花板在哪。

想动手复现这个思想，最经济的路径是 fork mini-SWE-agent 或照着实践·从零造一个 Agent 写一个 100 行版本，然后在 10 个 SWE-bench Verified 实例上做一次「加 linter vs 不加」的对照——一天之内你会对 ACI 有肌肉记忆级的理解。

参考资料

SWE-agent 论文（arXiv:2405.15793） —— NeurIPS 2024 原文，ACI 概念与消融实验（Table 2）的出处。
SWE-agent GitHub 仓库 —— 已进入维护模式，适合读代码与复现论文实验。
SWE-agent 官方文档：Agent-Computer Interface —— 四个核心 ACI 设计决策的官方阐述，含「SWE-agent 已被 mini 版取代」的声明。
mini-SWE-agent GitHub 仓库 —— 约 100 行的极简 agent，当前 SWE-bench bash-only 榜单的标准 scaffold。
SWE-bench 官方榜单 —— 各模型 × 各 scaffold 的最新成绩与单次成本。
SWE-bench 论文（arXiv:2310.06770） —— 同团队的基准论文，ICLR 2024，理解成绩数字的前提。
SWE-smith GitHub 仓库 —— 团队的数据侧工作：把任意仓库变成 SWE 训练环境（NeurIPS 2025 D&B Spotlight）。
SWE-agent v1.0.1 release notes —— 官方宣布 SWE-bench Full 集 SOTA，并讨论子集评估的局限。

SWE-agent

SWE-agent ​

一、学术背景：与 SWE-bench 同源的「出题人做的 agent」 ​

二、核心创新：Agent-Computer Interface（ACI） ​

问题：人在用的工具，模型用不好 ​

ACI 的四个设计决策 ​

ACI 不是什么 ​

三、成绩演变：从 12.5% 到被自己的「mini 版」接管 ​

四、scaffold 研究价值：一组天然的对照实验 ​

五、架构与代码组织 ​

六、后续发展：团队亲手完成的「自我颠覆」 ​

mini-SWE-agent：100 行的回答 ​

学术线：SWE-smith 与数据侧 ​

七、ACI 思想的可迁移启示 ​

参考资料 ​

SWE-agent

一、学术背景：与 SWE-bench 同源的「出题人做的 agent」

二、核心创新：Agent-Computer Interface（ACI）

问题：人在用的工具，模型用不好

ACI 的四个设计决策

ACI 不是什么

三、成绩演变：从 12.5% 到被自己的「mini 版」接管

四、scaffold 研究价值：一组天然的对照实验

五、架构与代码组织

六、后续发展：团队亲手完成的「自我颠覆」

mini-SWE-agent：100 行的回答

学术线：SWE-smith 与数据侧

七、ACI 思想的可迁移启示

参考资料