从 SWE-agent 到 mini-swe-agent：以大模型能力跃迁为棱镜的架构演进调研报告

不动模型一个字节，只改接口，解决率相对提升约 64%

2024 年 5 月，普林斯顿大学与斯坦福大学的 SWE-bench 原班团队发表 arXiv:2405.15793《SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering》，后被 NeurIPS 2024 正式收录。 论文核心主张极其鲜明：同一个 GPT-4 Turbo，权重一字节不动，仅重新设计模型与代码仓库之间的交互接口，就能把 SWE-bench Lite 解决率从 11.00%（Shell-only 交互式基线）提升到 18.00%，相对提升约 64%。在完整的 SWE-bench Full 上取得 12.47%（286/2294）。

这意味着：在 Agent 系统的性能瓶颈中，Harness 层（包裹模型的外部运行时）的设计可能比模型本身更重要。论文为此提出 ACI（Agent-Computer Interface）专用工具集——窗口化文件查看器、带语法守卫的编辑器、结构化搜索工具、历史压缩链等一系列「保姆式」干预机制，目的只有一个：替模型做它做不好的事。

约 100 行代码 + 裸 bash，解决率约 65%

仅仅 14 个月后，同一团队于 2025 年 7 月 25 日发布 mini-swe-agent。核心 Agent 类被压缩到约 100 行 Python 代码，只保留 bash 一个工具——没有专用文件查看器、没有编辑器、没有历史压缩、没有有状态 Shell 会话。它用 Claude Sonnet 4 在 SWE-bench Verified 上拿到约 65% 的解决率，与当时配置拉满的完整版 SWE-agent + Claude 4 Sonnet（66.60%，SWE-bench 官方榜单，2025-05-22）基本持平。

通用 Shell 为何不适合 LLM：三重障碍

人类工程师使用 Shell 时，依赖视觉模式识别、空间记忆、跨窗口并行注意力、以及略读与选择性聚焦的能力；而 LLM 的认知架构根本不同——顺序 token 处理，对上下文顺序和格式高度敏感，工作记忆有限，且倾向于锚定在提示词中最突出的信息上。

论文 §2 的四条设计原则

工程实现：每个组件都针对一个具体失败模式

• find_file / search_file / search_dir 三个专用命令替代 ls + cd + grep 的多步组合
• 关键在输出管理：每次搜索最多返回 50 条结果，超限则抑制输出并提示模型细化查询——把「上下文淹没」的失败模式转化为自然的精炼循环，迫使模型从模糊搜索走向精确查询

• 有状态查看器，每次固定展示至多 100 行，附带文件路径、总行数与行号，配合 scroll_down / scroll_up / goto 导航
• 网格搜索显示：100 行窗口（18.0%）优于 30 行窗口（14.3%，降 3.7 个百分点），更优于全文展示（12.7%，降 5.3 个百分点）——后者因 LLM 对长上下文中间部分的信息利用率呈 U 形曲线（「lost in the middle」效应），关键代码大概率被淹没

• edit start:end 一步完成多行原子替换，编辑后查看器自动刷新到修改位置
• 核心护栏：编辑先经 linter（如 flake8）检查，若引入语法错误则回滚编辑并把错误信息连同代码片段返回模型；无效编辑直接丢弃、要求重试——针对 LLM「反复编辑同一段代码」的典型失败模式

• 每轮发送给模型前对历史消息做过滤与压缩；核心处理器 LastNObservations 只保留最近 5 轮 observation 的完整内容，更早的观察折叠为单行占位
• 另有标签系统（对编辑、测试等关键工具结果差异化保留）与正则清理器等处理器

量化每个组件的贡献：SWE-bench Lite，同一 GPT-4 Turbo

一句话概括：为 2024 年初主流 LLM 的系统性缺陷做补偿

SWE-agent 的核心假设：2024 年初的主流 LLM（以 GPT-4 Turbo 为代表）在长上下文信息过滤、动作空间认知负荷、语法正确性与自我修正能力上存在系统性缺陷，因此需要 Harness 层在信息呈现、动作约束和错误拦截三个维度上做大量补偿。

这个假设有充分的实验支撑（论文 §5.2）：搭载 GPT-4 Turbo 的 SWE-agent 在 2294 项任务中有 51.7%（1185 条）的交互轨迹存在至少 1 次失败的编辑；任意一次编辑操作最终成功的概率为 90.5%，但在一次编辑失败后，后续成功的概率会降至 57.2%——直接证明模型在代码编辑环节的脆弱性。

mini（v1）设计建立在五个核心原则之上

• Bash-only 工具接口：没有任何 bash 以外的工具，甚至不使用模型的 tool-calling 接口（模型以特定格式输出 bash 命令，由 Harness 正则解析）
• 线性历史透明性：每一步只是往消息列表后面追加，轨迹就是传给模型的消息历史本身
• 无状态执行：每条命令通过 subprocess.run 独立执行，命令之间无隐式状态依赖
• 极简沙箱化：把 subprocess.run 换成 docker exec 即完成隔离
• 通用模型兼容：模型调用统一经 litellm 抽象层接入任意后端

裁掉的是「补偿」，留下的是「骨架」

• 所有专用 ACI 工具（find_file、search_dir、窗口化查看器、edit + lint 守卫）→ 替换为裸 bash
• History Processor 压缩链 → 替换为线性全量历史
• 有状态 Shell 会话（SWE-ReX）→ 替换为 subprocess.run 独立子进程
• Jinja2 模板族 + demonstrations → 替换为三个基础模板 + zero-shot
• LangChain 依赖与复杂配置体系 → 替换为约 200 行可运行系统（官方口径：约 100 行核心 Agent + 约 100 行环境/模型/运行脚本合计），无重型依赖（模型层统一走 litellm，另有 pydantic、jinja2 等轻量依赖）

• 同构的 ReAct 主循环：「组装上下文 → 模型推理 → 解析动作 → 执行动作 → 观察回灌」的语义完全不变
• 异常驱动的控制流：Submitted、LimitsExceeded、FormatError 等终止条件（v2 统一为 InterruptAgentFlow 异常体系）
• 标准化的任务初始化与产出：隔离沙箱 + base commit checkout + patch 文件输出 + .traj 轨迹持久化
• 提交机制：模型通过 echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT 魔法字符串提交最终结果（v1 默认配置 mini.yaml 明确指示该命令）

同量级性能，数量级复杂度差

两者在解决率上基本持平，但 mini 的架构复杂度低了一个数量级。这个「同量级性能、数量级复杂度差」的事实，正是本报告核心命题的经验基础。

mini 自己也在演进：「极简」不等于「拒绝现代接口」

• 默认切换为原生 tool-calling：v2.0.0（官方称「自发布以来最大版本」）默认使用模型原生 tool-calling API（暴露一个 bash 工具），v1 的 regex 文本解析降级为可选配置（litellm_textbased 模型类 / swebench_backticks.yaml）
• 架构重构：动作解析与 observation 格式化职责从 Agent 移到 Model，Agent 退化为简单协调器；配置从 dataclass 改为 Pydantic；异常体系统一为 InterruptAgentFlow
• 体量增长：default.py 从 v1 的约 140 行增至 v2.x 的约 190 行（官网仍沿用 "The 100 line AI agent" 标语）；当前最新版本 v2.4.6（2026-07-23）

2024.05 → 2026.06：一条被两种口径标注的时间线

三个阶段：Harness 主导 → 模型爆发 → 复杂度被替代

• 第一阶段（2024.04—2024.10）：Harness 层主导性能差异。GPT-4 Turbo 在 Full 上只有 12.47%，即便有 ACI 加持也只能到这个水平。此阶段模型是瓶颈，接口设计能带来 64% 的相对提升，但绝对天花板很低。
• 第二阶段（2024.10—2025.09）：模型能力爆发式增长。Claude 3.5 Sonnet 升级版 49.0%（2024.10）→ Claude 3.7 Sonnet 62.3%（2025.02）→ Claude Sonnet 4 72.7%（2025.05）→ Sonnet 4.5 77.2%（2025.09），一年内绝对提升近 45 个百分点，远超 Harness 层的优化速度。
• 第三阶段（2025.07 至今）：Harness 层复杂度被模型能力替代，基准本身开始换代。mini-swe-agent 用极简架构 + Claude Sonnet 4 即达约 65%。此后两件大事改写格局（见下）。

OpenAI 发布《Why SWE-bench Verified no longer measures frontier coding capabilities》，宣布停止报告 Verified 分数。两大理由：其一，对 o3 在 64 次运行中未能稳定解决的 138 道题（占全集 27.6%）的审计发现，其中 59.4% 存在实质缺陷（narrow tests 35.5% + wide tests 18.8% + 其他 5.1%）——注意这是对难钉子题子集的审计结论，并非「全数据集 59.4% 测试有缺陷」；其二，训练污染——GPT-5.2、Claude Opus 4.5、Gemini 3 Flash 均能复述 gold patch。

OpenAI 发布对 SWE-bench Pro 的审计，估计约 30% 题目存在问题（pipeline 标记 27.4%、人工标注 34.1%），并撤回了此前对 Pro 的推荐。与此同时，Pro（1865 题、41 仓库）的厂商自报最高分在 8 个月内从首发的 23.3%（GPT-5）攀升至 81.2%（Claude Fable 5.1，2026-09-11 口径）——分数通胀与可信度危机并存。

移动靶效应：不仅 Harness 设计是靶，基准本身也是靶

SWE-agent 的 ACI 设计是针对 2024 年初的 GPT-4 Turbo 这一特定能力快照做的优化。当模型能力快速迭代时，这些针对特定缺陷的补偿机制会逐渐变得冗余。mini-swe-agent 的出现，本质上是同一团队对自己前作的「时效性审计」——在 2025 年中的模型能力水平下，重新检验哪些干预仍然必要、哪些已经成为开销。

2026 年的新证据让这个效应更加立体：不仅 Harness 设计是移动靶，基准本身也是移动靶——Verified 因饱和与污染退役，Pro 在分数冲到 81% 的同时被审计出三成题目有问题。架构演进研究与基准生命周期管理，已成为同一枚硬币的两面。

从多工具矩阵到单一 bash

SWE-agent 的工具集按职责分四组，每组对应模型的一个特定缺陷：

mini-swe-agent 只有一件工具：bash。模型像人类工程师一样用 ls 探索、cat / nl / sed 查看编辑、grep 搜索、python 跑复现脚本，用 echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT 提交。

从可插拔压缩链到线性全量历史

SWE-agent 的 History Processor 链在每轮发送前对历史做过滤与压缩：LastNObservations 只保留最近 5 轮 observation，过期内容折叠为单行占位；标签系统对关键工具结果差异化保留；正则清理器按规则清理冗余片段。消融实验证明这对 2024 年模型是净收益（Full history 配置下降 3.0 个百分点）。

mini-swe-agent 没有任何历史处理器：self.messages 是一个从 system 消息开始、每轮纯追加的线性列表。

从有状态长会话到无状态单步执行

SWE-agent 的 SWE-ReX 维护有状态的长 Shell 会话，支持 ipython、gdb 等交互式会话，工具间通过环境变量与文件系统共享状态。mini-swe-agent 每条命令通过 subprocess.run 独立执行，命令之间无隐式状态依赖。

从声明式实验平台到代码即配置

SWE-agent 的提示词由 Jinja2 模板族驱动，支持多套模板 + demonstrations + 多配置文件嵌套合并 + 命令行参数覆盖。mini-swe-agent（v1）只有 system_template、instance_template、observation_template 三个基础模板，走 zero-shot 路线，不挂载演示轨迹。

长上下文 / 指令遵循 / 自我修正，三条能力线同时越过阈值

2024 年初的 GPT-4 Turbo 在 128K 上下文窗口中，对中间位置的信息利用率呈 U 形曲线（「lost in the middle」），因此 SWE-agent 必须用 100 行窗口替模型做信息过滤。2025 年的模型（Claude Sonnet 4 的 200K 上下文、Sonnet 4.5 起的 1M token beta）在长上下文利用上有质的飞跃，能够直接从完整文件内容和完整历史中提取关键信息，不再需要外部窗口化。

2024 年的模型使用 sed、grep 等复杂命令行工具时错误率很高，SWE-agent 必须提供简化版专用命令来降低认知负荷。2025 年的模型已能准确使用原生 bash 命令完成搜索、浏览、编辑，甚至能自己组合 sed -i、python -c 等复杂命令。mini v2 默认切换原生 tool-calling（2026-02），是这一机制的最新注脚：连「文本协议解析」这层兜底都失去了必要性。

SWE-agent 的 lint 守卫针对的是模型「编辑后引入语法错误」的问题——在 GPT-4 Turbo 上，51.7% 的任务轨迹存在至少 1 次失败编辑，失败后的续成功率从 90.5% 跌至 57.2%。2025 年的模型不仅产出语法正确代码的概率更高，遇到错误时还能更有效地自我修正（分析错误信息、调整策略、重新尝试），不再需要 Harness 层在编辑前拦截错误。

不同组件对不同能力的依赖不同，「淘汰顺序」也不同

SWE-agent 的消融实验已经暗示了这一点：去掉编辑器降 7.7 个百分点，迭代搜索降 6.0，窗口化降 5.3，历史压缩降 3.0，lint 守卫降 3.0，去掉 demonstrations 只降 1.7——不同组件对不同模型能力的依赖程度不同，因此它们被「淘汰」的时间点也不同。

六个系统-模型组合的解决率全景

成本下降与性能提升同步发生，而非此消彼长

SWE-agent 论文给出了精细的成本账（GPT-4 Turbo）：

• 成功任务：中位成本 $1.21，中位步数 12 步
• 失败任务：平均成本 $2.52，平均步数 21 步
• Full split 已解决实例的平均成本为 $1.59（注意口径：仅在成功解决的实例上平均，不是全体实例的整体平均）
• 93.0% 的已解决实例在耗尽成本预算前主动提交（每实例预算上限为 $4.00）

mini-swe-agent 发布时没有官方成本数字，但 2026 年 SWE-bench 官方 Bash Only 子榜提供了真实数据（该榜独有 "Avg. $" 列，仅 mini 条目披露成本，其他脚手架均为 "-"，因此跨脚手架成本对比无法直接从榜单进行）：

（v2 的 SWE-bench 默认配置：每实例成本上限 $3、步数上限 250。）

一张表看清两个系统的工程体量

三个时间点，三种平衡形态

• 2024 年（SWE-agent + GPT-4 Turbo）：低解决率（12.47%）、中等成本（$1.59/成功实例）、高复杂度 → Harness 层投入大量工程复杂度，但受限于模型能力天花板，绝对性能仍然很低
• 2025 年中（SWE-agent 完整版 + Claude 4 Sonnet）：高解决率（66.60%）、高复杂度 → 模型能力突破天花板后，Harness 层的复杂度开始成为净开销
• 2025–2026（mini + 各代模型）：相近乃至更高的解决率（65% → 76.8%）、显著下降的成本（$1.13 → $0.07 区间）、极低复杂度 → 同样乃至更弱的模型能力定价，用 1/50 的架构复杂度达到更好性能

Live-SWE-agent：从 bash-only 出发、在运行时自主合成工具，已登顶

UIUC 张令明（Lingming Zhang）团队的 Live-SWE-agent（arXiv:2511.13646）从 mini-swe-agent 的 bash-only 脚手架出发，让 Agent 在运行时自主合成软件工程工具——论文定位是 "first live software agent that evolves its own scaffold on the fly, starting from nothing more than bash tools"。

性能数据的版本脉络需要精确引用：论文 v1 的头条数字是 75.4%（SWE-bench Verified，Claude Sonnet 4.5）；v3 摘要已更新为 77.4%（Gemini 3 Pro，无 test-time scaling），并在 SWE-bench Pro 上达 45.8%。更重要的是：截至 2026-09-16，Live-SWE-agent 以 79.20%（Claude 4.5 Opus medium）与 Sonar Foundation Agent 并列 SWE-bench 官方 Bash Only 子榜榜首，超过了所有静态脚手架。这证明「模型自主决定何时需要专用工具」比「预先设计固定工具集」更有效——它已经从「前沿方向」变成了榜单冠军。

SWE-MiniSandbox 与 mini 的训练底座定位

北大团队的 SWE-MiniSandbox（arXiv:2602.11210，2026-02-11 提交）通过内核级隔离机制（namespace 类的独立工作区）替代每实例 Docker 容器，加轻量环境预缓存，磁盘占用降至约 5%，目标正是可扩展的 RL 训练——解决「每个 episode 都要拉起/销毁容器」的效率瓶颈。

这条路线的底座正是 mini 的设计哲学：官方文档明确将 mini 定位为 FT/RL 底座（不想过拟合到特定脚手架时使用），线性历史（轨迹 = 消息流）与无状态执行都是为了训练场景的沙箱化与横向扩展。

关于 Bash Only 子榜的两处事实修正

mini-swe-agent 被 Meta、NVIDIA、IBM、Essential AI、Nebius、Anyscale、Princeton、Stanford 等机构采用。但关于其「评测基础设施」角色，有两处事实必须讲准：

• 「为 Ramp 维护的 SWE-bench 官方榜单供能」是混淆表述。事实是：mini 驱动的是 Ramp 公司自己的榜单（labs.ramp.com/swebench，官方 News 原文 "mini-swe-agent now powers Ramp SWE-Bench"）；而 SWE-bench 官方站的做法是新增「Bash Only」子榜——Verified 标签页现在默认即 bash-only 视图，页面注明 "Defaults to bash-only setting (run with mini-SWE-agent)"。
• 「官方榜单强制使用统一脚手架」不成立。官方 Verified 主榜不强制统一脚手架——OpenHands、SWE-agent、TRAE、Warp 等各用各家脚手架并存；只有 Bash Only 子榜统一用 mini 跑裸模型。

重型脚手架已不占头部（2026-09-16 抓取）

对照重型/复杂脚手架的历史最佳：OpenHands + GPT-5 71.80%（2025-08）、OpenHands + Claude 4 Sonnet 70.40%、SWE-agent 完整版 + Claude 4 Sonnet 66.60%。同系模型直接对照：SWE-agent 完整版 + Claude 4 Sonnet = 66.6%，而 mini + Claude 4.5 Sonnet = 70.6%（$0.56/实例）——极简脚手架反超同系重型脚手架。

与此同时，SWE-agent 完整版发布已停滞：最新 release 为 v1.1.0（2025-05-22），截至 2026-09 已约 16 个月无新版本；官方文档已把 mini-swe-agent 定位为「默认选择」，完整版只推荐给「要实验不同工具集/历史处理器」的研究场景。SWE-bench 团队的新动作则转向：Multimodal / Multilingual 子榜、SWE-smith 训练数据生成、免费云端评测 sb-cli、新基准 ProgramBench。工业界采用持续扩大：DataCurve 的 DeepSWE 长程任务基准用 mini 做评测 harness，官方称 "mini-swe-agent beats Claude Code and Codex on DeepSWE"。

Harness 层继续瘦身，但「极简」的内涵在变化

随着模型在长上下文利用、指令遵循、代码生成质量上持续进步，静态脚手架剩余的模板和配置将进一步简化。但 mini v2 的演进提示了一个方向性修正：瘦身的终点不是「更少的代码行数」，而是「把协议适配层交给模型原生能力」（tool-calling 取代文本解析）。

同时，SWE-bench Pro（1865 题、41 仓库）曾是公认的新天花板，但 2026-07 的 OpenAI 审计（约 30% 题目有问题）使其权威性受损；SWE-rebench（Nebius 的月度刷新去污染基准，注意它不是 Princeton/SWE-bench 团队项目）、ProgramBench 等新基准正在承接「能力天花板」的角色。

自适应复杂度已被提前实现，下一站是「演化的治理」

曾有预言称「2027—2028 年将出现根据任务难度和模型能力动态调整 Harness 复杂度的自适应框架」。这一预言已被 Live-SWE-agent 提前实现（2025-11 论文、2026 年登顶官方子榜）：复杂度的生产者从「人类预先设计」转移为「模型运行时自主生成」。

下一阶段的真问题随之变化——运行时生成的工具如何验证、审计、防退化？自我演化脚手架的可靠性工程（生成工具的测试、版本管理、跨任务迁移性）将成为新的研究焦点。

复杂度下沉的两个边界条件与一个修正

从 SWE-agent 到 mini-swe-agent 的演进，本质上是复杂度从 Harness 层不可逆地下沉到模型权重中的过程。这个趋势的边界条件：

• 下限（固有复杂度）：环境隔离、安全沙箱、成本预算控制、轨迹持久化等「工程基础设施」是任务本身的固有复杂度，不会因模型变强而消失——mini 完整保留了它们，SWE-MiniSandbox 更是在这条线上继续投入
• 上限（骨架内化）：当模型能力足够强时，连「循环 + 执行 + 线性历史」这个骨架都可能被模型内化
• 修正（下沉的非全域性）：下沉在推理侧成立，但在训练数据生产侧不成立——SWE-smith 用完整版 SWE-agent 生成训练数据（多工具、可控、可配恰恰是数据生产的优点）。「不可逆下沉」应精确表述为：推理时 Harness 复杂度不可逆下沉；离线数据生产与实验研究场景保留重型脚手架的生态位

三组关键认知：可靠性来源、可观测性、基准生命周期

2024 年的可靠性主要来自 Harness 层的外部约束（lint 守卫、窗口限制、搜索上限）；2025 年越来越多地来自模型自身的内在能力；2026 年则出现了第三极——运行时生成的可靠性（模型自己造工具并自我约束）。可靠性研究的重点应从「如何设计更好的外部约束」转向「如何评估和增强模型的内在可靠性」，再延伸到「如何治理模型自主生成的脚手架」。

mini 的线性历史设计证明了「透明性本身就是一种可靠性保障」——当你能直接看到模型实际看到的内容时，故障诊断和根因分析变得极其简单。这为 Agent 系统设计提供了一个重要原则：在满足功能需求的前提下，优先选择可观测性最高的架构。

Verified 因饱和 + 污染 + 缺陷退役（2026-02），Pro 在分数冲到 81% 的同时被审计出约三成题目有问题（2026-07）。教训是双重的：其一，任何静态基准都有半衰期，去污染与持续刷新（SWE-rebench 模式）是必需机制；其二，审计基准缺陷与审计 Agent 行为是同构问题——对轨迹做过程分析的方法论（如本项目的 analysis 栈），同样适用于对基准题目做缺陷标注。对「评测 → 分析 → 构造 → 训练 → 评测」闭环而言，基准质量审计应成为闭环中的显式环节，而非外部假设。

Agent 系统的架构复杂度，本质上是模型能力缺口的函数

当模型能力不足时，Harness 层必须承担大量补偿性工作——信息过滤、动作约束、错误拦截、上下文管理——这些工作的工程复杂度与模型能力的缺口成正比。当模型能力跨过临界阈值后，这些补偿性工作可以被逐步收回，复杂度从 Harness 层下沉到模型权重中。

• 下沉之后是演化：复杂度并未消失，而是转变了生产者——Live-SWE-agent 以 mini 为基座运行时合成工具并登顶官方 Bash Only 子榜（79.20%），标志着「极简静态 vs 极简自我演化」取代「重型 vs 极简」成为新的主要矛盾
• 下沉不是全域的：推理侧复杂度下沉的同时，训练数据生产（SWE-smith 用完整版 SWE-agent）与工程基础设施（沙箱、成本、轨迹持久化）保留了重型/复杂度的生态位
• 移动靶不止模型：基准本身也在移动——Verified 退役、Pro 审计反转，基准生命周期管理成为与架构设计同等重要的研究变量