Swarm Forge

SwarmForge 简介

SwarmForge 是一个基于 tmux 的本地化智能体编排平台，可将多个 AI 智能体组织成纪律严明的协作团队，让它们像专业的软件工程师一样协同完成项目开发。系统通过共享 git worktree、角色专属提示词与结构化的交接协议，实现多智能体在同一项目上的并行协作。

仓库分支结构

main 分支为文档分支，保存共享的运行脚本与默认章程文章；可运行的配置位于独立的 workflow 分支，每个分支包含 swarmforge/swarmforge.conf、本地章程文章以及角色提示词。

三种工作流

two-pack

两智能体快速后端工作流，适合无需 Gherkin 规约的小型任务。coder 角色基于 TDD 与单元测试实现需求；cleaner 角色批量处理 coder 的交付，进行清理、CRAP/DRY 审查、架构审查以及语言变异硬化。常规流转为 coder -> cleaner -> coder。

four-pack

四智能体精简规约工作流，适合需要 Gherkin 规约的中型项目。specifier 负责将用户意图转化为 Gherkin 验收规约并请求确认；coder 实现已批准的切片；refactorer 执行行为保持型重构、覆盖率提升与变异点扫描；architect 负责高层结构、依赖方向与完成通知。常规流转为 specifier -> coder -> refactorer -> architect -> specifier。

six-pack

六智能体全功能工作流，适合大型项目，每个质量关卡均由独立智能体负责。包含 specifier、coder、cleaner、architect、hardender、QA 六个角色，额外涵盖端到端 QA 流程、变异硬化与最终 UI 验证。

环境准备

运行 SwarmForge 需要本机具备：zsh、git、tmux、Babashka（bb），以及至少一个已配置的智能体后端（codex、claude、copilot 或 grok）。

快速开始

选择目标工作流分支后下载并解压：

# BRANCH 可选 two-pack / four-pack / six-pack
BRANCH=four-pack
curl -L "https://github.com/unclebob/swarm-forge/archive/refs/heads/${BRANCH}.tar.gz" | tar -xz --strip-components=1

进入项目目录后执行 ./swarm 即可启动。首次运行时，包装脚本会从 main 分支下载共享脚本与章程文章，再启动本地配置；后续运行直接复用本地脚本目录。停止时只需关闭 swarmforge.conf 中列出的第一个窗口（即清理窗口）。

系统默认会通过 macOS 的 caffeinate 或 Linux 的 systemd-inhibit 阻止主机休眠，可通过设置 SWARMFORGE_PREVENT_SLEEP=0 禁用该行为。

核心特性

• 配置驱动的拓扑：智能体形态由 swarmforge/swarmforge.conf 定义，而非硬编码。
• 项目本地角色：每个角色由 swarmforge/roles/<role>.prompt 文件描述。
• 分层章程体系：constitution.prompt 引导智能体读取 swarmforge/constitution/articles/ 下的文章。
• 角色级后端选择：支持为不同角色分配 claude、codex、copilot 或 grok。
• 可观测的智能体群：每个角色拥有独立的终端窗口，可实时观察会话状态。
• 自托管、轻量化：仅依赖 tmux 与本地终端，无需额外基础设施。

章程结构

可运行分支的 swarmforge/ 目录典型布局如下：

swarmforge/
  swarmforge.conf
  constitution.prompt
  constitution/
    articles/          # 项目本地章程文章
  roles/               # 角色提示词

共享默认文章位于 main 分支的 swarmforge/constitution/articles/，启动时会被安装到本地目录；已存在的本地文件不会被覆盖，从而允许分支自定义覆盖。命名约定方面，project.prompt 描述工作流的项目形态，local-engineering.prompt 与 local-workflow.prompt 用于在共享文章基础上补充专项规则。如需完全替换共享文章，应使用共享文件名直接覆盖。

交接协议

智能体通过守护进程交付的交接文件通信，不直接发送 tmux 消息。启动时会在每个角色 worktree 下同步 swarmforge/scripts/ 并将其加入 PATH，智能体使用以下三个辅助脚本：

• swarm_handoff.sh <draft-file>：校验并排队待发出的交接。
• ready_for_next.sh：按角色配置的接收模式接受任务。
• done_with_current.sh：按角色配置的接收模式完成任务。

交接支持两种类型：git_handoff（指向已提交版本，commit 缩写必须为恰好 10 位十六进制字符）与 note（单行自由文本，最长 80 字符）。持久化的交接文件位于各 worktree 的 .swarmforge/handoffs/ 目录下，分为 outbox、sent、failed、inbox 子目录。

swarmforge.conf 配置

每行定义一个窗口，格式如下：

window <role> <agent> <worktree> [task|batch] [extra-cli-args...]

接收模式默认为 task，可设为 batch 以批量消费同优先级队列；后续字段透传给智能体 CLI。

# 示例：coordinator 在 master 主目录运行，coder 与 refactorer 使用独立 worktree
window coordinator codex master
window coder codex coder
window refactorer codex refactorer
window architect codex architect

master 为特殊值，表示该角色直接在主工作目录的 master 分支上运行，不创建 .worktrees/master。

tmux 与终端行为

SwarmForge 使用项目专属的 tmux socket（记录于 .swarmforge/tmux-socket），并尊重用户的 base-index 与 pane-base-index 设置。终端后端默认自动检测：macOS 优先使用 AppleScript 打开 Terminal.app，其次为 Windows Terminal（wt.exe），否则在当前 shell 中附加清理会话。可通过 SWARMFORGE_TERMINAL 环境变量强制指定 ghostty、terminal-app、windows-terminal 或 none。

新增终端后端时，在 main 分支的 swarmforge/scripts/terminal-adapters/ 下创建一个以后端命名的脚本，并实现 terminal_backend_label、terminal_backend_can_open_sessions、terminal_backend_tracks_windows、terminal_open_session、terminal_window_exists、terminal_close_window 等契约函数即可。

窗口管理

第一个配置的窗口为清理窗口，关闭它即触发整个 swarm 的关闭流程：销毁 tmux 会话、关闭其余被跟踪窗口。关闭其他被跟踪窗口是非破坏性的，看门狗会自动重新打开对应窗口并重新附加到原 tmux 会话，智能体状态与终端历史得以保留。