论文档案

论文最重要的概念：ACI

人类开发者使用 IDE，不是因为 IDE 比人聪明，而是它把搜索、导航、编辑、诊断和执行组织成适合人的界面。SWE-agent 提出 Agent-Computer Interface（ACI）：语言模型也是一种特殊用户，它需要符合自身能力和局限的计算机接口。

ACI 同时定义两件事：

模型能执行哪些动作
        +
环境状态以什么形式回到模型

它还负责历史如何拼接、错误怎样反馈、哪些过期内容要删除。这个定义几乎就是 Harness 数据面的完整接口层。

为什么普通 Shell 不是中立接口

Linux 命令功能强，但为人设计。一个命令可能有几十个参数，sed 多行编辑容易出错，cat 整个大文件会挤爆上下文，连续 cd/ls/cat 又浪费回合。模型还会忘记当前目录、看错行号或在编辑失败后继续推理。

论文给出四条 ACI 原则：

1. 动作简单、容易理解，参数少且文档短；
2. 动作输出信息密度高，支持高效搜索和导航；
3. 环境反馈简洁且与最近动作相关，例如编辑后展示新内容；
4. Guardrail 帮助快速恢复，例如语法检查和明确错误。

这四条把工具设计从“功能能否实现”推进到“模型能否稳定使用”。

SWE-agent 的接口组成

搜索与导航

专用命令支持按文件名、目录和代码内容搜索。相比让模型自己组合 find | grep，接口返回更稳定、可预测的结果，并能把搜索逐步缩小到文件和符号。

文件查看器

默认只显示最多 100 行的窗口，同时明确展示：完整路径、总行数、当前范围、省略了多少行。模型可用 scroll_up、scroll_down 和 goto 移动。

这不是简单节省 token。固定窗口建立了空间坐标，让模型知道自己看见的是文件哪一段，也避免整文件中大量无关内容稀释当前问题。

专用编辑器

编辑动作支持局部替换，并在修改后自动展示更新后的片段。若编辑引入语法问题，lint guardrail 立即报错，Agent 可以在下一轮修复。

相对 Shell 重定向或 sed，专用编辑动作减少了复制整文件、转义和多行替换错误。

上下文管理

Harness 给模型动作说明和示例，要求每轮生成 Thought 与 Action；格式错误会触发明确重试。历史处理器清理过期文件视图，避免模型看到修改前后的冲突内容。

这体现一个常被忽略的原则：事件日志应完整，但模型上下文不是日志的简单拼接，而是由 reducer 生成的当前视图。

实验设置

主实验使用完整 SWE-bench 2,294 题，消融和分析主要使用 300 题 SWE-bench Lite；另用 HumanEvalFix 测试短代码调试。模型是 GPT-4 Turbo（gpt-4-1106-preview）和 Claude 3 Opus。

每个 SWE-bench 实例 API 预算上限为 4 美元；超过预算时自动提交已有编辑。主要指标为 % Resolved，即 patch 应用后所有目标与回归测试通过。论文还报告解决成功实例的平均 API 成本。

主结果

在同一 GPT-4 Turbo 下，SWE-agent 相对 Shell-only 提升约 64%。HumanEvalFix 上，SWE-agent 达到 88.3% pass@1。

SWE-agent 比一次性 RAG 贵很多，但解决率提升约 6.7 倍。工程选择不能只看成功率：低价值批量任务可能更适合廉价 RAG，高价值复杂修复才值得长轨迹 Agent。

ACI 消融揭示了什么

论文在 SWE-bench Lite 上固定 GPT-4，逐个替换接口：

最反直觉的是：更多上下文会更差。整文件不如 100 行窗口，完整历史不如经过处理的最近观察。ACI 的工作不是最大化信息量，而是最大化当前决策所需的信噪比。

轨迹分析：Agent 怎样成功，又怎样失败

典型成功流程

成功轨迹常从复现问题或定位代码开始。模型可能创建一个 reproduction script，运行它，再根据输出搜索文件、局部修改并重跑。动作频率显示搜索、查看、编辑、执行在不同阶段有明显变化，说明 Agent 会形成“定位—修改—验证”的工作流。

编辑仍是高风险节点

在 2,294 个 GPT-4 Turbo 轨迹中，**1,185 个（51.7%）**至少出现一次失败编辑。Agent 通常能从少量失败中恢复，但失败编辑越多，后续恢复概率越低。Guardrail 减少的不是所有错误，而是错误传播长度。

成功得快，失败拖得久

成功任务中位数约 12 步、$1.21；未成功任务平均约 21 步、$2.52。93% 的成功实例在耗尽预算前主动提交，而整体只有 69% 如此。单纯增加预算很可能扩大无效尾部。

大多数失败不是接口格式问题

论文用 GPT-4o 对 248 条 Lite 未解决轨迹分类，并在人工子集上达到 87% 一致率。约 52% 属于错误实现或过度特化实现。ACI 显著改善交互效率，但无法替代对问题语义和正确修复的理解。

对 Harness 的直接设计规则

工具要按模型的人因工程设计

命令不是越通用越好。每个动作应有短说明、少量参数、稳定输出和明确错误。对高频关键路径，专用动作通常比让模型拼 Shell 更可靠。

观察应是“当前视图”

文件修改后，旧片段应从模型视图移除或标记过期。事件存储保持追加式，context builder 根据当前 workspace 生成最新视图，二者不要混用。

Guardrail 应靠近错误发生点

编辑后立即 lint、命令超时立即返回、patch 冲突立即说明，比最后统一测试更容易恢复。越晚发现，后续 Thought 越可能建立在错误状态上。

无进展检测比盲目加预算更重要

可以综合最近文件 diff、测试结果、重复搜索和成本判断进度。连续若干步状态不变时触发重规划、换策略或停止。

如何复现 ACI 结论

不必先运行完整 SWE-bench。选 30 个可稳定构建的 Lite 任务，固定同一模型和总预算，做以下对照：

1. Shell-only；
2. 加专用搜索；
3. 加 100 行文件查看器；
4. 加局部编辑与 lint；
5. 加历史去重和无进展熔断。

每组记录 resolved、失败编辑数、重复动作数、上下文 token、首次复现用时和总成本。只比较最终成功率会看不出某项接口改动究竟减少了哪种失败。

局限

• ACI 是在小型开发集上人工迭代与参数搜索得到，存在对 SWE-bench 的适配；
• 主结果依赖特定闭源模型版本和价格；
• $4 预算、窗口大小等参数未必适合其他模型；
• 自动失败分类使用 LLM judge，虽然有人工校验，仍会有误差；
• 软件工程只覆盖任务的一部分，缺少需求澄清、代码审查和长期维护；
• Docker/执行权限等基础设施安全不是论文消融重点。

SWE-agent 最有普适性的结论是：模型性能不是模型权重的单变量函数，接口就是认知脚手架。 对 Harness 设计者而言，优化工具的可发现性、局部反馈、错误恢复和上下文视图，常常比继续堆 prompt 更可控、更容易验证。

延伸阅读

• 返回论文谱系与单篇索引
• SWE-bench：任务与执行式验收
• CodeAct：代码作为通用动作语言
• OpenHands：把 ACI 扩展成通用平台