02-Open SWE架构层v1到v2技术演进与多智能体设计模式关键字Open SWE架构演进、CodingAgentState、多智能体协作、Manager/Planner/Programmer/Reviewer、协调器模式、人在回路、错误恢复、沙箱重建、命令安全验证上一篇文章我们从全局视角看了Open SWE的定位和技术栈。这篇深入架构层重点讲两件事从v1到v2的设计演进以及多智能体协作的设计模式。一、v1架构四大模块 基础设施Open SWE最初发布时2025年8月架构相对简洁。核心是四个角色模块加上一套基础设施┌─────────────────────────────────────────────────────────────┐ │ Open SWE v1 架构 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Manager │ │ │ │ 职责: 接收任务 → 分配沙箱 → 协调流程 → 结果汇总 │ │ │ └──────────────────────┬───────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Planner │ │ │ │ 职责: 分析代码库 → 制定执行计划 → 等待人工审批 │ │ │ └──────────────────────┬───────────────────────────────┘ │ │ │ (审批通过) │ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Programmer │ │ │ │ 职责: 在沙箱中执行计划 → 修改代码 → 运行测试 │ │ │ └──────────────────────┬───────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Reviewer │ │ │ │ 职责: 审查代码质量 → 运行完整测试 → 创建PR │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ─────────────── 基础设施层 ─────────────── │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ GitHub │ │ Daytona │ │ LangSmith│ │ │ │ Webhook │ │ 沙箱 │ │ 追踪 │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────┘v1解决了能不能跑起来的问题。但在实际使用中几个痛点逐渐暴露出来痛点一状态分散。四个模块各自维护自己的状态信息通过消息传递。一旦某个环节出错很难准确定位问题出在哪里。比如Programmer改了代码但测试没跑通Reviewer不知道Programmer改了哪些文件。痛点二错误恢复困难。Agent执行到一半沙箱挂了没有检查点只能从头来。一个跑了20分钟的任务崩溃后重新跑又得等20分钟。痛点三安全边界粗糙。v1的沙箱隔离做了但命令级别的安全验证不够。Agent理论上可以在沙箱里执行任何shell命令虽然不影响宿主机但可能产生意料之外的副作用。二、v2架构三大改进2026年3月的v2版本针对上述痛点做了三个关键改进。2.1 集中式状态管理CodingAgentStatev2引入了CodingAgentState把所有模块的状态集中到一个结构化的状态对象中┌────────────────────────────────────────────────────────────┐ │ CodingAgentState 状态结构 │ ├────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ CodingAgentState │ │ │ ├──────────────────────────────────────────────────┤ │ │ │ │ │ │ │ 任务信息 │ │ │ │ ├── task_description: str # 任务描述 │ │ │ │ ├── source: str # 触发来源 │ │ │ │ └── repo: {owner, name} # 目标仓库 │ │ │ │ │ │ │ │ 规划信息 │ │ │ │ ├── plan: str # 执行计划 │ │ │ │ ├── plan_approved: bool # 是否已审批 │ │ │ │ └── plan_edits: list # 用户修改记录 │ │ │ │ │ │ │ │ 执行信息 │ │ │ │ ├── changed_files: list # 已修改文件列表 │ │ │ │ ├── test_results: dict # 测试结果 │ │ │ │ └── subagent_results: list # 子Agent返回值 │ │ │ │ │ │ │ │ 审批信息 │ │ │ │ ├── pending_approvals: list # 待审批操作 │ │ │ │ ├── approval_status: str # 审批状态 │ │ │ │ └── directory_permissions # 目录级权限 │ │ │ │ │ │ │ │ 安全信息 │ │ │ │ ├── command_audit_log: list # 命令审计日志 │ │ │ │ └── threat_flags: list # 威胁标记 │ │ │ │ │ │ │ └──────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────────┘v1到v2的状态管理变化┌─────────────────────────────────────────────────────────┐ │ 状态管理v1 vs v2 │ ├─────────────────────────────────────────────────────────┤ │ │ │ v1: 分散式 │ │ ┌──────┐ 消息 ┌─────────┐ 消息 ┌──────────┐ │ │ │Manager├────────→│ Planner ├────────→│Programmer│ │ │ └──────┘ └─────────┘ └────┬─────┘ │ │ │ 消息 │ │ ▼ │ │ ┌──────────┐ │ │ │ Reviewer │ │ │ └──────────┘ │ │ 问题: 各模块状态不透明出错难定位 │ │ │ │ ──────────────────────────────────────────────────── │ │ │ │ v2: 集中式 (CodingAgentState) │ │ ┌──────────────────────────────────────────┐ │ │ │ CodingAgentState (共享状态) │ │ │ │ │ │ │ │ 所有模块读写同一个状态对象 │ │ │ │ LangGraph自动持久化到数据库 │ │ │ │ 任何环节崩溃可从最近检查点恢复 │ │ │ └──────────────────────────────────────────┘ │ │ ▲ ▲ ▲ ▲ │ │ │ │ │ │ │ │ Manager Planner Programmer Reviewer │ │ │ │ 优势: 全局可观测 检查点恢复 权限追踪 │ │ │ └─────────────────────────────────────────────────────────┘集中式状态带来的一个重要能力是目录级权限控制。AGENTS.md可以声明哪些目录Agent可以修改、哪些只读# AGENTS.md ## 目录权限 - src/modules/ # 可读写 - src/shared/ # 可读写 - src/legacy/ # 只读禁止修改 - tests/ # 可读写 - scripts/ # 只读当Agent尝试修改只读目录时状态层会拦截操作并记录到审计日志而不是让错误代码被提交。2.2 错误恢复检查点 沙箱重建v2加入了完整的错误恢复机制┌────────────────────────────────────────────────────────────┐ │ v2 错误恢复机制 │ ├────────────────────────────────────────────────────────────┤ │ │ │ 正常流程 │ │ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ │ │规划│──→│编码│──→│测试│──→│审查│──→│ PR│ │ │ └────┘ └────┘ └────┘ └────┘ └────┘ │ │ ▲ ▲ ▲ │ │ │ │ │ 检查点自动保存 │ │ CK-1 CK-2 CK-3 │ │ │ │ ──── 故障场景 ──── │ │ │ │ 场景A: 沙箱崩溃网络超时/资源耗尽 │ │ ┌────┐ ┌────┐ ┌────┐ │ │ │规划│──→│编码│─ ✕ ────→│恢复│ │ │ └────┘ └────┘ │ │ │ │ ▲ ▲ │ 1. 从CK-2恢复状态 │ │ CK-1 CK-2 │ 2. 重建沙箱环境 │ │ │ 3. 重新安装依赖 │ │ │ 4. 从断点继续编码 │ │ └────┘ │ │ │ │ 场景B: 测试失败代码有问题 │ │ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ │ │规划│──→│编码│──→│测试│─ ✕ │修复│──→│测试│ │ │ └────┘ └────┘ └────┘ │ │ └────┘ │ │ ▲ ▲ ▲ │ │ ▲ │ │ CK-1 CK-2 CK-3 │ 1. 分析失败原因 │ │ CK-3 │ 2. 修改代码 │ │ │ 3. 重跑测试 │ │ │ 4. 最多重试3次 │ │ └────┘ │ │ │ │ 场景C: LLM调用失败API限流/服务不可用 │ │ 任何环节都可从最近检查点恢复支持指数退避重试 │ │ │ └────────────────────────────────────────────────────────────┘这个机制的关键在于检查点是自动的。LangGraph在每个节点Node执行完成后自动保存状态快照不需要开发者手动管理。崩溃恢复时只需要告诉LangGraph从最近的检查点继续整个任务状态就会恢复。2.3 安全增强命令安全验证系统v2在安全层做了显著加强引入了validateCommandSafety系统┌────────────────────────────────────────────────────────────┐ │ 命令安全验证流程 │ ├────────────────────────────────────────────────────────────┤ │ │ │ Agent请求执行命令: │ │ rm -rf /tmp/build npm install │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────┐ │ │ │ validateCommandSafety() │ │ │ │ │ │ │ │ 检查1: 命令模式匹配 │ │ │ │ ├── 危险命令黑名单 (rm -rf /, curl|sh) │ │ │ │ ├── 网络外连白名单 (仅允许特定域名) │ │ │ │ └── 文件写入路径限制 (AGENTS.md定义) │ │ │ │ │ │ │ │ 检查2: 提示注入检测 │ │ │ │ ├── 检测嵌入在代码中的系统指令 │ │ │ │ ├── 检测异常环境变量操作 │ │ │ │ └── 检测可疑的文件权限变更 │ │ │ │ │ │ │ │ 检查3: 实时威胁评估 │ │ │ │ ├── 命令是否超出任务范围 │ │ │ │ ├── 是否尝试修改沙箱配置 │ │ │ │ └── 是否尝试访问敏感路径 │ │ │ └────────────────┬───────────────────────────┘ │ │ │ │ │ ┌──────┴──────┐ │ │ ▼ ▼ │ │ ┌────────┐ ┌────────────┐ │ │ │ 通过 │ │ 拦截 │ │ │ │ 执行 │ │ │ │ │ │ 命令 │ │ 记录审计 │ │ │ └────────┘ │ 通知Manager│ │ │ │ 请求审批 │ │ │ └────────────┘ │ │ │ └────────────────────────────────────────────────────────────┘所有命令执行都会被记录到CodingAgentState.command_audit_log中。这个日志是不可篡改的即使Agent试图清理痕迹也会被沙箱层的只读审计机制捕获。三、多智能体协作模式v2的多智能体协作不是一个简单的依次执行模式而是协调器模式Orchestrator Pattern和人在回路HITL的混合架构。3.1 完整协作流程┌────────────────────────────────────────────────────────────┐ │ 多智能体协作完整流程 │ ├────────────────────────────────────────────────────────────┤ │ │ │ ① 任务接收 (Manager) │ │ ┌────────────────────────────────────────────┐ │ │ │ • 从 Slack/Linear/GitHub 接收任务 │ │ │ │ • 解析任务类型和复杂度 │ │ │ │ • 分配云沙箱资源 │ │ │ │ • 初始化 CodingAgentState │ │ │ └─────────────────────┬──────────────────────┘ │ │ ▼ │ │ ② 计划制定 (Planner) │ │ ┌────────────────────────────────────────────┐ │ │ │ • 读取仓库结构和AGENTS.md │ │ │ │ • 分析依赖关系和影响范围 │ │ │ │ • 生成分步执行计划 │ │ │ │ • 写入 State.plan │ │ │ └─────────────────────┬──────────────────────┘ │ │ │ │ │ ┌────┴────┐ │ │ │ HITL │ │ │ │ 审批点 │ │ │ └────┬────┘ │ │ ┌─────────┼─────────┐ │ │ ▼ ▼ ▼ │ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ 批准 │ │ 编辑 │ │ 拒绝 │ │ │ │ 按原计 │ │ 修改计 │ │ 终止 │ │ │ │ 划执行 │ │ 划后 │ │ 任务 │ │ │ │ │ │ 执行 │ │ │ │ │ └───┬────┘ └───┬────┘ └────────┘ │ │ └─────┬───┘ │ │ ▼ │ │ ③ 编码实现 (Programmer 子Agent) │ │ ┌────────────────────────────────────────────┐ │ │ │ • 按计划逐步执行 │ │ │ │ • 复杂步骤拆分为子Agent并行处理 │ │ │ │ • 每个修改写入 State.changed_files │ │ │ │ • 定期保存检查点 │ │ │ │ │ │ │ │ 子Agent编排: │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │子Agent A│ │子Agent B│ │子Agent C│ │ │ │ │ │独立沙箱 │ │独立沙箱 │ │独立沙箱 │ │ │ │ │ │独立状态 │ │独立状态 │ │独立状态 │ │ │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ └───────────┼───────────┘ │ │ │ │ ▼ │ │ │ │ 结果汇总到主Agent │ │ │ └─────────────────────┬──────────────────────┘ │ │ ▼ │ │ ④ 代码审查 (Reviewer) │ │ ┌────────────────────────────────────────────┐ │ │ │ • 检查所有 changed_files │ │ │ │ • 运行完整测试套件 │ │ │ │ • Lint 类型检查 │ │ │ │ • 检查是否遵守AGENTS.md规范 │ │ │ │ • 防止构建失败 │ │ │ └─────────────────────┬──────────────────────┘ │ │ ▼ │ │ ⑤ 交付 (Manager) │ │ ┌────────────────────────────────────────────┐ │ │ │ • commit_and_open_pr (中间件安全网兜底) │ │ │ │ • 关联原始 Issue │ │ │ │ • 通知用户 (Slack/Linear/GitHub) │ │ │ └────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────────┘3.2 协调器模式 vs Pipeline模式为什么选择协调器模式而不是简单的Pipeline┌─────────────────────────────────────────────────────────┐ │ Pipeline模式 vs 协调器模式 │ ├─────────────────────────────────────────────────────────┤ │ │ │ Pipeline模式 (v1近似): │ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │ M │──→│ P │──→│ P │──→│ R │ │ │ └─────┘ └─────┘ └─────┘ └─────┘ │ │ 严格顺序无法回退无法并行 │ │ │ │ 协调器模式 (v2): │ │ ┌─────────┐ │ │ │Manager │ ← 持有全局状态 │ │ │(协调器) │ │ │ └────┬────┘ │ │ ┌────────┼────────┐ │ │ ▼ ▼ ▼ │ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │子Agent│ │子Agent│ │子Agent│ │ │ │ A │ │ B │ │ C │ ← 并行执行 │ │ └──────┘ └──────┘ └──────┘ │ │ │ │ │ │ │ └────────┼────────┘ │ │ ▼ │ │ Reviewer → PR │ │ │ │ 优势: │ │ 1. Manager可以动态调整流程根据任务复杂度 │ │ 2. 子Agent并行执行大幅缩短总时间 │ │ 3. 任何环节失败可以局部重试不影响其他 │ │ 4. HITL审批点可以插入任意位置 │ │ │ └─────────────────────────────────────────────────────────┘协调器模式的本质是把控制权交给Manager。Manager持有全局状态CodingAgentState可以根据任务复杂度决定是否需要子Agent、需要几个、怎么分配。而v1的Pipeline模式是硬编码的四步流程不管任务多简单都得走完全程。3.3 子Agent的独立性保障子Agent并行执行的难点在于不互相干扰。v2通过三个机制解决这个问题机制实现方式解决的问题独立沙箱每个子Agent分配独立的Daytona沙箱文件系统隔离避免互相覆盖独立状态子Agent有自己独立的AgentState上下文隔离不会串数据结果合并主Agent负责合并子Agent的输出冲突检测确保最终一致性举个具体例子假设Agent要把一个大型项目的所有回调代码改成Promise。它会创建5个子Agent分别处理5个目录。每个子Agent在自己沙箱里改代码、跑测试互相看不到。全部完成后主Agent把5个沙箱的修改合并到一个分支上再跑一次完整测试确认没有冲突。四、中间件确定性与AI判断的平衡v2架构里有一个容易被忽视但非常重要的设计中间件系统。┌────────────────────────────────────────────────────────────┐ │ 中间件在Agent循环中的位置 │ ├────────────────────────────────────────────────────────────┤ │ │ │ while (任务未完成): │ │ │ │ ┌──────────────────────────────────────┐ │ │ │ before_model │ │ │ │ check_message_queue_before_model │ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ 检查消息队列 │ │ │ │ │ │ 如果有用户新消息: │ │ │ │ │ │ 注入到当前上下文 │ │ │ │ │ │ Agent在下次调用时就能看到 │ │ │ │ │ └──────────────────────────────┘ │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ LLM 调用 │ │ │ │ (AI做判断: 下一步该做什么) │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ 工具执行 │ │ │ │ (文件操作/Shell命令/Git操作等) │ │ │ │ │ │ │ │ ToolErrorMiddleware: │ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ 工具执行失败时: │ │ │ │ │ │ 不直接崩溃 │ │ │ │ │ │ 格式化错误信息反馈给LLM │ │ │ │ │ │ 让LLM决定如何修复 │ │ │ │ │ └──────────────────────────────┘ │ │ │ └──────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ after_agent │ │ │ │ open_pr_if_needed │ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ Agent循环结束后: │ │ │ │ │ │ 如果有代码修改但没有创建PR │ │ │ │ │ │ 中间件自动补上 │ │ │ │ │ │ 这是最关键的安全网 │ │ │ │ │ └──────────────────────────────┘ │ │ │ └──────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────────┘中间件的存在解决了一个根本性问题AI的判断不可靠。你无法保证Agent每次都能记住做完事要创建PR——它可能被测试失败打断了、可能token用完了、可能就是忘了。open_pr_if_needed中间件确保了这件事一定会发生。这就是确定性与AI判断的平衡关键行为用确定性代码保证中间件灵活决策交给AI模型调用。五、从v1到v2的架构对比总结维度v1v2状态管理分散式各模块独立CodingAgentState集中式错误恢复无检查点崩溃从头来检查点自动保存沙箱自动重建安全验证沙箱隔离粗粒度命令级安全验证 提示注入防护任务编排四步Pipeline协调器模式 动态子Agent权限控制无目录级权限 审计日志HITL基础审批计划编辑 执行干预 双重文本可观测性基础LangSmith追踪全链路审计 命令日志 状态快照v1证明了异步编码Agent这件事是可行的。v2证明了它可以做到生产级别。这个演进路径值得借鉴——不要一开始就追求完美的架构先让系统跑起来然后根据实际痛点逐步加固。系列导航Open SWE实战系列01 Open SWE基础首个开源异步编码智能体架构全景解析02 Open SWE架构层v1到v2技术演进与多智能体设计模式本文03 Open SWE运行时LangGraph平台与云端异步执行机制04 Open SWE协作层GitHub深度集成与人在回路HITL设计05 Open SWE扩展层自定义工具集成与DSL扩展开发06 Open SWE生态层SWE-bench基准测试与模型选型指南07 Open SWE企业级安全加固、可观测性与生产部署08 Open SWE实战从代码重构到自动化CR的完整工作流