综合调研

SWE-agent 全家桶深度研究：从 ACI 到 mini-SWE-agent 的极简主义演化

普林斯顿/斯坦福团队围绕 SWE-agent 构建了一个完整的 Coding Agent 研究生态——SWE-agent → SWE-ReX → SWE-smith → mini-SWE-agent。本文从架构、ACI 设计哲学、数据生成、训练闭环到极简化演进做完整拆解，并评估其对 HarnessForge v2 的参考价值。

SWE-agent mini-SWE-agent SWE-smith ACI Coding Agent SWE-bench Agent 架构 数据合成

SWE-agent 全家桶深度研究：从 ACI 到极简主义演化

为什么写这篇

HarnessForge v2 的 Stage 2 需要选定一个 Agent 框架在 CVM 上持续开发并记录轨迹。SWE-agent 是最成熟的开源 Coding Agent 框架之一——19K Stars，NeurIPS 2024 论文，完整的训练数据生成管线。但更重要的是，这个团队在过去两年走过了一条值得研究的演化路径：从精心设计 ACI 工具，到发现”100 行代码 + 只用 Bash 就够了”。这条路径本身比任何单一系统都更有启发价值。

本文不是使用教程，而是对整个 SWE-agent 生态的架构拆解和设计决策分析，重点回答三个问题：

  1. ACI 设计到底贡献了什么？极简化之后还剩什么？
  2. SWE-smith 的数据生成方法论对 HarnessForge 有什么借鉴？
  3. 选 SWE-agent 还是 mini-SWE-agent 作为 HarnessForge v2 的轨迹收集框架？

1. 项目概览与生态地图

1.1 基本信息

属性详情
团队普林斯顿大学 NLP + 斯坦福大学
核心作者John Yang, Carlos E. Jimenez, Kilian Lieret, Alexander Wettig, Shunyu Yao
论文NeurIPS 2024（arXiv:2405.15793）
Stars~19,000
许可证MIT
当前状态维护模式（官方推荐迁移到 mini-SWE-agent）

1.2 生态全景

这个团队围绕”LLM 自动修 Bug”构建了一个完整的研究闭环：

SWE-bench（评测）
    ↓ 定义问题
SWE-agent（推理框架）→ SWE-ReX（远程执行）
    ↓ 生成轨迹
SWE-smith（数据工厂）
    ↓ 合成训练数据
SWE-agent-LM（训练模型）
    ↓ 评测回到
SWE-bench

加上最新的 mini-SWE-agent，一共 6 个项目组成闭环：

项目定位规模发布时间
SWE-bench标准评测集2,294 实例（Verified 500）2023-10
SWE-agent推理框架（ACI 驱动）~15K 行 Python2024-04
SWE-ReX远程沙箱执行引擎独立包2025-02（随 1.0）
SWE-smith训练数据合成工厂52K 任务 + 26K 轨迹2025-05（NeurIPS 2025 Spotlight）
SWE-agent-LM训练后模型Qwen 2.5 Coder 32B 微调2025-05
mini-SWE-agent极简推理框架~100 行核心代码2025-07

这个演化时间线值得注意：从 2024-04 到 2025-07，仅 15 个月，团队从”精心设计工具”走到了”只要 Bash 就行”。

2. SWE-agent 架构深度拆解

2.1 四层架构

┌─────────────────────────────────────────────────┐
│  CLI 入口 (sweagent run / run-batch)            │ ← 配置解析
├─────────────────────────────────────────────────┤
│  Agent 类                                        │ ← 决策核心
│  ├── HistoryProcessor（上下文压缩）               │
│  ├── ActionParser（输出解析）                     │
│  └── forward()（观察→思考→行动循环）             │
├─────────────────────────────────────────────────┤
│  SWEEnv（环境管理）                              │ ← SWE-ReX 薄封装
│  └── SWE-ReX Deployment                         │
│       ├── 本地 Docker 容器                       │
│       └── 远程（Modal/AWS）                      │
├─────────────────────────────────────────────────┤
│  Tools / ACI                                     │ ← 安装到容器 Shell
│  ├── 文件查看器（100 行/次）                     │
│  ├── 文件编辑器 + Linter 门控                    │
│  ├── 全目录搜索（只返回文件名）                  │
│  └── 空输出处理                                  │
└─────────────────────────────────────────────────┘

2.2 Agent Loop 详解

Agent 的核心方法是 forward()，每一轮循环：

  1. 历史压缩：HistoryProcessor 将所有历史消息压缩到模型上下文窗口内。这是与 Claude Code 的一个关键差异——Claude Code 用 compact 摘要机制，SWE-agent 用可配置的压缩器。
  2. 模型推理：将压缩后的历史发送给 LLM，获取输出。
  3. 动作解析：ActionParser 从模型输出中提取可执行的命令。
  4. 执行：通过 SWEEnv → SWE-ReX → Docker Shell 执行命令。
  5. 观察：命令输出追加到历史，进入下一轮。

2.3 配置系统

SWE-agent 的配置用 YAML 文件 + pydantic 验证，分四层：

层级管什么示例
Run Config运行模式单实例 / 批量 / 重试
Agent Config模型 + 模板 + 工具 + 历史处理agent.model.name=gpt-4o
Environment Config执行环境Docker 镜像 / 远程部署
Tool Bundle Config工具包组合文件查看器 + 编辑器 + 搜索

从命令行可以覆盖任意配置项：sweagent run --agent.model.name=claude-sonnet-4 --env.repo.github_url=...

3. ACI：核心贡献与消融实验

3.1 ACI 是什么

ACI（Agent-Computer Interface）是 SWE-agent 论文的核心贡献。类比：

  • HCI（Human-Computer Interface）→ 为人类设计的交互界面
  • ACI（Agent-Computer Interface）→ 为 LLM Agent 设计的交互界面

核心论点：正如好的 UI 能提升人的效率，好的 ACI 能提升 Agent 的效率。模型权重一个字节没动，纯靠接口设计就能大幅提升性能。

3.2 四个 ACI 组件

① 文件查看器（替代 cat）

  • 每次只显示 100 行
  • 支持 scroll up / scroll down / search
  • 为什么不用 cat？实验发现模型面对大量文本会迷失，限制信息量反而提升效果

② 文件编辑器（替代直接写文件）

  • 基于搜索替换的编辑模式
  • 编辑前自动运行 Linter
  • 关键设计：如果编辑引入语法错误，整个编辑操作被拒绝，不写入文件
  • 这个设计直接防止了 Agent 最常见的失败模式——改着改着把文件改坏

③ 全目录搜索

  • 搜索整个项目目录
  • 只返回匹配的文件名，不返回上下文
  • 为什么？实验发现显示更多上下文反而让模型更困惑
  • 又一个”少即是多”的设计

④ 空输出处理

  • 命令成功但无输出时，返回 “Your command ran successfully and did not produce any output.”
  • 避免模型因空白反馈而困惑

3.3 消融实验：ACI 到底值多少分

论文中做了关键消融：

配置SWE-bench Lite 解决率
Shell-only baseline（只有默认 Linux Shell）~7.0%
SWE-agent（完整 ACI）~18.0%
差值+11.0 pp

用 GPT-4 Turbo 做的实验。同一个模型，纯靠 ACI 设计提升了 11 个百分点。论文还指出，虽然 ACI 是针对 GPT-4 Turbo 设计的，但在 Claude 3 Opus 上也有类似提升，说明 ACI 设计有一定的跨模型迁移性。

单独组件的贡献：

移除的组件性能下降
移除 Linter 门控最大的性能下降
移除 100 行限制（改用 cat）显著下降
搜索返回完整上下文（而非只返回文件名）下降
移除空输出处理小幅下降

Linter 门控是最重要的单一设计决策——防止 Agent 破坏代码的能力比帮 Agent 找到代码更重要。

3.4 ACI 设计的四条原则

从论文的实验中可以提炼出四条设计原则：

  1. 信息节制：不要给模型看太多（100 行限制、搜索只返回文件名）
  2. 防错优先：阻止坏操作比启用好操作更重要（Linter 门控）
  3. 明确反馈：每个操作都必须有清晰反馈（空输出处理）
  4. 专用工具优于通用命令：edit 比 echo ... > file 好，open 比 cat 好

4. SWE-ReX：远程执行引擎

4.1 为什么需要单独的执行层

SWE-agent 1.0 之前，执行逻辑耦合在 SWEEnv 类中。1.0 做了关键重构：将执行逻辑抽取为独立包 SWE-ReX。

SWE-ReX 是一个 runtime interface for sandboxed shell environments：

  • 本地 Docker 容器
  • 远程服务器（Modal、AWS、任何支持 SSH 的机器）
  • 支持大规模并行——同时启动几十个容器跑不同实例

4.2 架构

Agent（本地）
    │
    ▼
SWE-ReX Client
    │ （HTTP/gRPC）
    ▼
SWE-ReX Server（容器内）
    │
    ▼
Shell Session

对 HarnessForge v2 的启发：执行层必须与 Agent 逻辑解耦。我们在 CVM 上跑的场景正好需要这种本地 Agent + 远程执行的模式。

5. SWE-smith：数据工厂

5.1 定位

SWE-smith 解决了一个关键瓶颈：SWE-bench 只有 2,294 个人工标注的实例，不够训练。SWE-smith 把任意 GitHub 仓库变成训练数据，产出 52K 合成任务 + 26K 轨迹。

NeurIPS 2025 Datasets & Benchmarks Track Spotlight。

5.2 四阶段流水线

阶段输入输出方法
1. 环境构建GitHub 仓库Docker 镜像自动化 Docker 构建
2. 任务合成仓库代码代码变异实例文件定位 / 程序修复 / SWE-bench 风格
3. 测试过滤变异实例合法任务必须破坏 ≥1 个单元测试
4. Issue 生成合法任务(task, issue_text) 对LLM 生成自然语言描述

5.3 关键设计决策

① 测试过滤是质量核心

不是所有代码变异都是好任务。SWE-smith 要求变异必须破坏至少一个测试——这保证了任务有明确的验证信号。通过测试 = 修好了，没通过 = 还没修好。

这与 HarnessForge v2 的里程碑设计思路一致：每个 milestone 都需要可自动验证的成功标准。

② 三种任务类型

  • 文件定位（File Localization）：给定 issue 描述，找到需要修改的文件
  • 程序修复（Program Repair）：给定 issue + 位置，写出修复
  • SWE-bench 风格（Full Task）：给定 issue，定位 + 修复

三种难度梯度形成了课程学习的可能性。

③ 250+ 仓库覆盖

不只是 SWE-bench 的 12 个 Python 仓库，而是 250+ 个仓库，更多样化。

5.4 训练结果

用 5,017 条轨迹微调 Qwen 2.5 Coder Instruct 32B：

模型SWE-bench Verified
Qwen 2.5 Coder 32B（基座）8.2%
SWE-agent-LM-32B（微调后）40.2%
提升+32.0 pp

5K 条轨迹带来 32 个百分点的提升——这个数据效率值得关注。

5.5 与 HarnessForge v2 的关系

维度SWE-smithHarnessForge v2
任务来源代码变异（合成）真实开发过程（有机）
验证方式单元测试里程碑 + CI
轨迹丰富度单 Agent 修 Bug多角色（Dev + Mentor）长程开发
规模52K 任务 / 26K 轨迹Phase 2 目标 1K+ 轨迹
独特性Bug 修复轨迹Feature 开发 + 重构 + 探索 轨迹

互补关系：SWE-smith 的轨迹覆盖”修 Bug”这个单一模式，HarnessForge v2 覆盖更真实的”从零开发 Feature”场景。两者结合可以在训练数据中覆盖更完整的软件工程能力谱。

6. mini-SWE-agent：极简主义的胜利

6.1 核心数据

属性值
核心代码~100 行 Python
Stars3.8K（2025-07 发布至今）
SWE-bench Verified>74%（Gemini 3 Pro）
最新版本v2.2.8（2026-03-24）
采用者Meta、NVIDIA、IBM、Essential AI、Nebius、Anyscale

6.2 三个颠覆性设计决策

① 唯一工具 = Bash

不用 LLM 的 tool-calling 接口，不实现任何自定义工具。完全依赖 LLM 使用 Shell 的能力。

这意味着：

  • 与任何模型兼容（不依赖特定 API 格式）
  • 不会过拟合到特定 scaffold
  • 轨迹格式极简，天然适合 Fine-tuning / RL

② 每个动作独立执行

用 subprocess.run 而非有状态 Shell 会话。每个命令独立执行，不维护 Shell 状态。

好处：

  • 沙箱切换极简（subprocess.run → docker exec）
  • 没有 Shell 状态泄漏问题
  • 更容易做并行

③ 完全线性历史

轨迹 = 传给 LLM 的消息列表，没有任何处理、压缩、变换。

# mini-SWE-agent 的核心循环（简化）
messages = [system_prompt, user_message]
while not done:
    response = model.chat(messages)
    action = parse(response)
    output = subprocess.run(action)
    messages.append(response)
    messages.append(output)

这对 Fine-tuning 和 RL 研究者来说是理想数据格式——轨迹就是训练样本，无需额外处理。

6.3 与 SWE-agent 的哲学对比

维度SWE-agentmini-SWE-agent
核心假设好的工具设计能提升 Agent强模型不需要特殊工具
工具策略精心设计的 ACI（4 种专用工具）只有 Bash
历史处理HistoryProcessor 压缩完全线性，不压缩
配置复杂度YAML + pydantic 多层配置几乎无配置
代码量~15K 行~100 行
适合场景ACI 研究、工具实验日常使用、训练数据生成、RL 研究
SWE-bench Verified~76%（Claude 4.5 Opus）>74%（Gemini 3 Pro）

6.4 为什么 100 行就够了

这个问题的答案涉及一个更深层的趋势：Agent 框架的复杂度正在向模型迁移。

2024 年初：模型不够强，需要精心设计的工具来弥补（SWE-agent 的 ACI）。 2025 年中：模型变强了，100 行代码 + Bash 就能达到同等性能。 2026 年初：Claude 4.5 Opus 和 Gemini 3 Pro 在 mini-SWE-agent 上跑出 74-77%。

SWE-agent 论文的 ACI 消融（Shell-only 7% vs ACI 18%）是在 2024 年用 GPT-4 Turbo 做的。用 2026 年的模型重做这个消融，差距大概率会缩小——因为模型自己学会了 ACI 试图教它的那些东西（信息节制、防错、明确反馈）。

这不是说 ACI 思想过时了。而是说 ACI 的最佳实现位置可能从”框架”迁移到了”预训练/后训练”。模型通过大量 coding 轨迹训练，已经内化了这些能力。

7. SWE-bench Verified 排行榜（2026-02 数据）

使用 mini-SWE-agent v2.0.0 统一评估的结果：

排名模型解决率平均成本/实例
1Claude 4.5 Opus (high reasoning)76.80%$0.75
2Gemini 3 Flash (high reasoning)75.80%$0.36
2MiniMax M2.5 (high reasoning)75.80%$0.07
4Claude Opus 4.675.60%$0.55
5GPT-5-2 Codex72.80%$0.45
5GLM-5 (high reasoning)72.80%$0.53
9Claude 4.5 Sonnet (high reasoning)71.40%$0.66
10Kimi K2.5 (high reasoning)70.80%$0.15
11DeepSeek V3.2 (high reasoning)70.00%$0.45
14GPT-5 Mini56.20%$0.05

几个值得注意的点：

  • MiniMax M2.5 以 $0.07 的成本达到 75.80%，性价比碾压其他所有模型
  • 顶级模型之间差距很小（76.8% vs 75.8%），SWE-bench Verified 可能接近天花板
  • 值得注意的是 SWE-bench Pro 的最高分只有 46%——Verified 的 500 实例可能已被部分污染

8. 全景对比：Coding Agent 框架

8.1 开源框架定位矩阵

框架核心理念代码量工具策略轨迹格式FT/RL 友好
SWE-agentACI 设计驱动~15K 行4 种专用 ACI 工具需处理中等
mini-SWE-agent极简 + 只要 Bash~100 行只有 Bash线性消息列表✅ 极好
OpenHands完整 IDE 环境~50K 行Jupyter + Browser + FileCodeAct 格式中等
OpenHarness复刻 Claude Code~11K 行43 种工具事件级中等
AiderGit 集成编辑~20K 行专用编辑格式对话格式较差
Codex CLIOpenAI 原生未开源核心沙箱 + 网络隔离不公开N/A

8.2 商业 Agent 对比

产品SWE-bench Verified特色轨迹可导出
Claude Code80.8%（自有框架）深度系统集成、百万 token 上下文❌
Codex CLI~80%+沙箱隔离、多文件并行❌
Cursor~75%（推测）IDE 集成、实时交互❌
Devin~72%（推测）全自主、浏览器 + 终端❌

8.3 关键差异维度

轨迹透明度：只有 SWE-agent / mini-SWE-agent / OpenHands 的轨迹是完全开放可用的。商业产品的轨迹都是黑箱。

数据生成生态：只有 SWE-agent 生态有完整的数据工厂（SWE-smith）。其他框架产出的轨迹可以用，但没有配套的合成任务工具。

与 HarnessForge 的适配度：

需求SWE-agentmini-SWE-agentOpenHandsOpenHarness
CVM 上运行✅（SWE-ReX）✅（subprocess）✅（Docker）✅（Docker）
轨迹完整记录✅✅（最佳）✅✅
FT/RL 友好格式中等✅ 极好中等中等
长程任务支持⚠️ 主要做单 Issue⚠️ 同上⚠️ 同上⚠️ 同上
自定义 Mentor 注入需魔改 Agent需扩展 ~100 行需魔改需魔改
多 Milestone 编排❌ 需自建❌ 需自建❌ 需自建❌ 需自建

9. 版本演进时间线

版本日期关键变化
v0.2.02024-04-15首版，支持本地仓库
v0.3.02024-05-02GitHub Codespaces
v0.4.02024-05-09Web UI
NeurIPS 论文2024-05ACI 概念提出
v0.5.02024-05-28新文档站、任务镜像缓存
v0.6.02024-06-05速度提升 2x
v0.7.02024-09-23EnIGMA 模式（CTF 安全）
v1.0.02025-02-13全面重写：SWE-ReX、并行执行、Tool Bundles、litellm
v1.0.12025-02-28anthropic_filemap 默认配置
v1.1.02025-05-22SWE-smith 集成、多语言/多模态、SWE-agent-LM
mini-SWE-agent2025-07-24100 行代码达到同等性能
mini v2.2.82026-03-24当前最新稳定版

三个关键转折点：

  1. v1.0.0：从”单个框架”变成”平台”（SWE-ReX 解耦）
  2. v1.1.0：从”推理框架”扩展到”训练闭环”（SWE-smith）
  3. mini-SWE-agent：从”平台”回到”极简”（承认模型已经够强）

10. 对 HarnessForge v2 的启发

10.1 选型判断

结论：推荐以 mini-SWE-agent 为基础魔改，而非 SWE-agent。

理由：

维度选 SWE-agent选 mini-SWE-agent
代码理解成本15K 行100 行
魔改难度需深入理解 4 层架构几乎可以从头写
轨迹格式需处理 HistoryProcessor直接可用
沙箱切换已有 SWE-ReXsubprocess → docker exec
Mentor 注入需插入 Agent Loop在消息列表中追加即可
长程支持需自建 milestone 编排同样需要，但修改更简单

mini-SWE-agent 的 100 行核心代码实际上是一个模板——我们需要的是在此基础上加三个东西：

  1. Milestone 编排层：按顺序执行多个子任务，每个子任务有验证条件
  2. Mentor 注入：在 Agent 卡住时向消息列表中追加提示
  3. 轨迹增强记录：在每个动作上标注元信息（哪个 milestone、是否卡住、Mentor 干预类型）

10.2 从 SWE-smith 学到的

SWE-smith 的四阶段流水线（环境构建 → 任务合成 → 测试过滤 → Issue 生成）可以直接映射到 HarnessForge 的 Stage 1：

SWE-smith 阶段HarnessForge Stage 1 对应
环境构建为每个 repo 建 Docker 环境
任务合成从 git log 提取 milestone（我们不合成，用真实的）
测试过滤每个 milestone 必须有可运行的验证（CI/测试/脚本）
Issue 生成为每个 milestone 生成自然语言描述 + 后备提示素材

关键差异：SWE-smith 的任务是合成的（代码变异），我们的任务是有机的（真实开发历史）。有机任务更稀缺但质量更高。

10.3 ACI 思想的迁移价值

虽然 mini-SWE-agent 证明了不需要 ACI 工具，但 ACI 的四条原则仍然适用于 Mentor 提示设计：

  1. 信息节制 → Mentor 不要一次给太多提示，分层递进
  2. 防错优先 → 先检测 Agent 是否在做破坏性操作，再考虑帮它推进
  3. 明确反馈 → Mentor 的每次干预都要有清晰的意图说明
  4. 专用优于通用 → 针对不同卡点类型设计不同的 Mentor 策略

11. 判断与展望

11.1 SWE-agent 生态的战略意义

这个团队做了两件真正有价值的事：

  1. 证明了 ACI 设计的重要性（2024），然后证明了模型够强后 ACI 不再必需（2025）。这种自我否定的诚实态度在学术界不常见。

  2. 构建了完整的训练闭环（SWE-bench → SWE-agent → SWE-smith → SWE-agent-LM → SWE-bench）。这不是一篇论文，是一个研究基础设施。

11.2 SWE-bench 的天花板问题

当前 SWE-bench Verified 排行榜最高分 76.8%，SWE-bench Pro 最高分只有 46%。这暗示：

  • Verified 的 500 实例可能已被部分数据污染（推测）
  • 真实世界的软件工程任务远比 SWE-bench 复杂
  • 需要新的评测来区分”会修 Bug”和”会做工程”

11.3 对行业的影响

mini-SWE-agent 的成功意味着：Coding Agent 的核心竞争力不在框架设计，而在模型能力和训练数据。框架越简单，模型的能力越能直接发挥。

这对我们做数据的人来说是好消息——数据质量决定上限，框架只是容器。HarnessForge v2 的价值不在于我们用什么框架跑 Agent，而在于我们能收集到什么质量的轨迹数据。

参考链接