Open SWE-01

大家好，

LangChain 官方开源了一个叫 Open SWE 的项目（SWE 是 Software Engineer 的缩写），定位一句话：软件工厂。

啥意思？就是你把活儿丢给它——"把这个 bug 修了"、"给这个 issue 提个 PR"——它自己开一个隔离环境，读代码、改代码、跑测试、提交 PR，全套流程走完，跟雇了个不下班的工程师一样。

它不光写代码，还会审 PR、盯 CI（测试挂了它能自己诊断，是 flaky 就帮你重跑）、从你们仓库的历史评审里学你们的代码风格。

而且完全开源（MIT 协议），可以部署在你自己的服务器上，代码不用出内网。

今天这篇文章，我就把这个项目的源码结构给大家盘一遍。不用你装它，看完你就知道这类 agent 系统是怎么搭起来的。

先看它是怎么工作的：一条流水线

官方的核心概念就一张图：

任务进来（Dashboard / GitHub / Slack / Linear / 定时）
    ↓
规划和调研
    ↓
在隔离沙箱里改代码
    ↓
验证 + 提 PR
    ↓
评审、CI、反馈 →（有问题？回到第一步继续干）

这里有个设计我觉得很值得学：thread（会话）→ invocation（单次执行）→ sandbox（沙箱） 这个概念链。

给你翻译成人话：

  • thread = 一个活儿。你在 GitHub issue 里说"修这个 bug"，它开一个 thread，专属配一个沙箱
  • invocation = 干的一轮。你后来又补一句"顺便把日志也加上"，这是第二轮 invocation，但它接着上一轮的现场干，不用重新理解代码库
  • sandbox = 它的工位。一个隔离的 Linux 环境，跟 thread 同生共死

最让我点头的一个细节：沙箱如果失联了，它宁可整个任务失败，也不会偷偷换个新沙箱——因为新沙箱里没有你改了一半没提交的代码。

说白了：宁可罢工，不能丢活。 这个"安全失败"的思路，做 agent 系统的人应该都刻在脑子里。

技术底座：三层楼，它只盖了顶层

很多人一听到 agent 项目就上来造轮子，Open SWE 没有。它的架构是三层：

┌─────────────────────────────────────┐
│  Open SWE（它自己）                   │
│  工具、提示词、中间件、集成、鉴权、界面   │
├─────────────────────────────────────┤
│  Deep Agents（LangChain 的 harness）  │
│  规划、文件操作、shell、子代理原语       │
├─────────────────────────────────────┤
│  LangGraph（运行时）                  │
│  持久化执行 + 状态管理                 │
└─────────────────────────────────────┘

官方说法是：底下两层是 LangChain 自家产品，Open SWE 只在顶层做软件工程的事，不 fork、不魔改。

好处很实际：底层的 bug 修复和能力升级，它白嫖。

它一共注册了 5 个"角色"（对应代码里的 5 个 graph 入口）：

角色 干啥的
Agent 主力工程师：规划、实现、验证、交付
Reviewer 只读评审员：审 PR，一个字都不许改
Analyzer 评审风格研究员：从历史 review 意见里学你们团队的口味
Chat 客服：回答关于 PR 的问题，不改代码（连沙箱都不用开）
Scheduler 调度员：定时任务 + CI 监控

注意看，能写代码的只有 Agent 一个，其余全是只读的。这个权限切分我们后面聊。

扒源码：目录长这样

我把整个仓库扫了一遍，核心就两大坨：

open-swe/
├── agent/          Python 后端（458 个文件）← 大脑在这
│   ├── graphs/             5 个角色，每个一个 py 文件
│   ├── middleware/         30+ 个中间件 ← 精华在这
│   ├── api/                FastAPI 接口
│   ├── github/  linear/    外部集成
│   ├── mcp/                MCP 工具注入
│   ├── bundled_skills/     内置技能（baby-sit、workspace 管理）
│   └── database/           持久化
├── ui/             Web 面板（TypeScript，445 个文件）
├── desktop/        桌面客户端（实验性，先把本地仓库接进去）
├── tests/          362 个测试，跟 agent/ 一一对应
└── langgraph.json  部署清单：5 个角色在哪注册

前端 445 个文件、后端 458 个，测试 362 个——测试文件数占后端 80%，这个比例在开源项目里算很健康了。

全文最值得学的地方：middleware 目录

如果你只记住文章里的一个点，我希望是这一个。

打开 agent/middleware/，30 多个文件，每个名字都像一个"踩坑记录"：

  • model_fallback.py —— 模型挂了自动降级
  • timeout_wrapup.py —— 快超时时逼着 agent 赶紧收尾，别让它话说一半
  • repair_orphaned_tool_calls.py —— 修复"孤儿工具调用"（LLM 说了要调工具但没收尾的情况）
  • sandbox_circuit_breaker.py —— 沙箱熔断器
  • pr_creation_guard.py —— PR 创建护栏
  • stable_tool_order.py —— 工具列表排序稳定化（防止顺序抖动影响缓存）

看出来了吗？

LLM 本身的能力是"够用"，但离"能干活"之间，全是这些补丁的距离。 一个 agent 系统成熟不成熟，你不用看它的 prompt 多花哨，直接看 middleware 目录，里面每一行都是一次线上事故的学费。

权限这块它做得挺克制

给 agent 开沙箱 + 网络 + shell，等于放虎归山。它加了几道锁：

  • GitHub 凭据不直接塞给沙箱，而是走代理注入，而且只能访问你指定的那几个仓库——查不到凭据时，绝不回退到全量权限
  • 想改 CI workflow 文件？行，先弹出来让人类批准
  • 组织级 + 仓库级双重白名单
  • 评审角色物理只读

自主性和边界，这俩就是这类产品的核心矛盾，它的选择是：默认保守，逐项放开。

最后

Open SWE 现在还标着"active development"，API 随时会变，但它的整体架构——thread/invocation/sandbox 三件套 + 只读角色隔离 + middleware 补丁堆——我认为就是当下生产级 coding agent 的标准答案，值得每个做 AI 工程的人源码级看一遍。

本地跑起来也不难：

git clone https://github.com/langchain-ai/open-swe.git && cd open-swe
uv venv && source .venv/bin/activate
uv sync --all-extras
make build-dashboard   # 构建前端
make dev               # http://localhost:2024 直接开跑

（要接 GitHub/Slack webhook 的话本地得挂个 ngrok，make tunnel 一条命令的事。）