> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # 外部工具生态 > 这是研究性参考文档。记录 2025-2026 年主流 Agentic Factory 工具的架构、对比，以及与 retaintive 现有系统的关系映射。 > > 最后更新：2026-03 *** ## 生态全景：五层结构 ``` Layer 5 产品化 SaaS Devin AI（$500/月） ↓ Layer 4 开源工厂框架 Gas Town + Beads（本地） ComposioHQ agent-orchestrator ↓ Layer 3 Agentic IDE Claude Code ← retaintive 在这层 Cursor / Cline / Goose / OpenHands ↓ Layer 2 LLM 模型 Claude（Anthropic）/ GPT / Gemini ↓ Layer 1 基础协议 MCP（Model Context Protocol，Anthropic → Linux Foundation） ``` **retaintive 目前在 Layer 3**，正在向 Layer 4 演进。 *** ## Gas Town + Beads 深度解析 ### 项目基本信息 | | Gas Town | Beads | | ---------- | ----------------------------------------------------------- | ------------------------------------------------------- | | **GitHub** | [steveyegge/gastown](https://github.com/steveyegge/gastown) | [steveyegge/beads](https://github.com/steveyegge/beads) | | **Stars** | 12.6K | **19.4K** | | **语言** | Go | Go + TypeScript | | **最新版本** | 活跃维护 | v0.62.0（2026-03-16） | | **许可证** | 开源 | MIT | | **作者** | Steve Yegge（前 Google/Amazon 工程师） | 同上 | ### 运行方式（本地，不是云端） **完全本地运行**，不是 SaaS： ``` 你的机器（Mac / Linux 服务器） ├── Mayor（持续运行的 Claude Code 实例，全局上下文） ├── Polecat-1（tmux 窗口 1，独立 Claude Code） ├── Polecat-2（tmux 窗口 2，独立 Claude Code） ├── Polecat-3（tmux 窗口 3，独立 Claude Code） └── .beads/（Dolt 数据库，任务状态持久化） ``` **「隔夜自动跑」需要机器保持开机**（Mac 不睡眠，或部署在 $5/月的 VPS 上）。Mayor 是一个持续运行的进程，机器关机就停了。 ### 所用 LLM Mayor 和 Polecats 都是 **Claude Code 实例**（默认使用 Claude Sonnet 或 Opus）。Gas Town 也支持 Codex CLI（OpenAI）作为可选 agent runtime，但 Claude Code 是默认和推荐的。 ### 角色体系：Steve Yegge 的西部小镇比喻 Steve Yegge 用「加油站小镇」（Gas Town）作为系统主题，每个角色都有对应的西部公路小镇概念： | 英文角色名 | 中文直译 | 实际意思 | 为什么这么叫 | | ---------------- | ----- | ---------------------------------- | ---------------------------------------------- | | **Gas Town** | 加油站小镇 | 整个多 agent 工作台框架 | 补给站，让 agent 加满油继续跑 | | **Mayor** | 市长 | AI 协调员，持续运行，有全局上下文，负责分配任务 | 管理整个小镇，是最高权威 | | **Polecats** | 臭鼬 | Worker agent，在不同 worktree 间穿梭执行任务 | 臭鼬会在墙壁和栅栏之间钻洞——Polecats 在 repo 和 worktree 之间穿梭 | | **Rigs** | 钻井平台 | 每个代码 repo 的容器/上下文 | 油井钻台，生产原料的地方 | | **Hooks** | 钩子 | Git worktree-based 持久化存储，任务状态记录在这里 | 把东西挂起来不让掉 | | **Convoys** | 货运队 | 一批任务的追踪单元（相当于 Sprint） | 运输队伍，把一批货（任务）从 A 送到 B | | **Crew Members** | 船员 | 人类工作者（你） | 船上的人，在关键节点做决策 | | **Formulas** | 配方 | 可重复任务的模板（相当于 Recipes） | 下次还能用的方法论 | **Polecat 的深层含义**：Polecats（臭鼬）之所以是这个名字，是因为它们不固定在某一个地方，而是在不同的 git worktree 之间穿梭，就像臭鼬在房屋之间钻洞一样。每个 Polecat 都是无状态的 worker，可以拿起任何任务，在对应的 worktree 里做完，然后移动到下一个。 ### 依赖栈类比解释 Gas Town 的依赖栈看起来很重，但每一个都有明确原因： | 工具 | 版本要求 | 一句话是什么 | 为什么 Gas Town 需要它 | | ------------------- | ------- | ---------------------------------------------------- | ------------------------------------------------------------------------------ | | **Go** | 1.23+ | 编译型编程语言 | Gas Town 本体用 Go 写的，但安装后是预编译二进制，你**不需要懂 Go** | | **Dolt** | 1.82.4+ | 「Git for databases」：SQL 数据库，支持 branch / merge / diff | Beads 的数据库后端。多个 Polecat 并发写任务状态时，像 git merge 一样自动合并冲突，不互相覆盖 | | **Beads** | 0.55.4+ | 任务数据库 CLI（在 Dolt 上运行） | 存 Polecat 的任务认领状态、依赖关系，Mayor 从这里知道「谁在做什么」 | | **tmux** | 3.0+ | 终端复用器（一个 terminal 里开多个会话） | 每个 Polecat 是一个 Claude Code 进程，Gas Town 用 tmux 管理 N 个进程同时跑，不需要开 N 个 terminal 窗口 | | **Claude Code CLI** | 最新 | Agentic IDE | Mayor 和 Polecats 的大脑，实际执行 AI 推理和代码操作的部分 | | **sqlite3** | — | 轻量关系数据库 | 辅助存储，Gas Town 内部用的 | **Dolt 类比**：想象你的 SQL 数据库有 `git branch`、`git merge`、`git diff` 命令。Dolt 就是这个。当 Polecat-1 和 Polecat-2 同时更新同一条任务记录时，Dolt 在字段级别做 merge，不是简单覆盖谁最后写的那个值。 **tmux 类比**：你在一个 terminal 里，但看起来像有 5 个 terminal 在并行跑。每个 Polecat 占一个 tmux 窗口，Mayor 可以在不同窗口之间传消息、观察状态。关掉 laptop 盖子 → tmux session 里的 Polecats 继续跑（如果在远端服务器上）。 ### Beads 技术架构 Beads 是独立于 Gas Town 的工具，Gas Town 依赖它，但你也可以单独用 Beads： ``` .beads/ ← 项目本地目录，可以提交进 git ├── (Dolt 数据库) ← 当前后端（v0.51.0 起，替换了之前的 SQLite） └── config.yaml CLI 命令： bd create ← 创建任务 bd ready ← 列出依赖已满足、可以开始的任务 bd update --claim ← 原子认领（防止两个 Polecat 抢同一个任务） bd dep add ← 设置任务依赖 bd show ← 查看当前状态 bd compact ← 压缩 DB（定期维护，防止膨胀） MCP Server：可以被 Claude Code 直接调用（agent 可以读写任务状态） ``` **并发写入机制**：多个 Polecat 同时写同一个 task 记录时，Beads 使用 Dolt 的 cell-level merge 自动合并（按字段级别合并，不互相覆盖）。这是 Beads 选择 Dolt 作为后端的核心原因。 **已知问题**： - `BD_BRANCH` 环境变量与 `gt hook` / `bd show` 冲突（issue #1921） - 版本升级需要 Gas Town 同步跟进（历史上每次大版本都有兼容性 PR） - DB 会膨胀，需定期 `bd compact` *** ## Mayor vs Meegle 适配问题（⚠️ 重要说明） 这里有一个**很容易混淆的误区**：Mayor 和 Meegle 不是天生适配的。 ### Mayor 的任务来源 Mayor 的设计假设：任务从以下地方来 ``` Mayor 能原生读的任务来源： ✅ Beads 队列（bd create 写进去的任务） ✅ GitHub Issues（通过 gh CLI 读取） ✅ GitHub Projects / Milestones ❌ Meegle（没有原生支持） ``` **Mayor 不会原生读取 Meegle 的工单**。如果想让 Mayor 执行 Meegle 里的任务，需要自己写一个 bridge 脚本（详见 [Factory 演进路线图](/ai/factory/factory-evolution-roadmap.md) 的 Meegle → Beads Bridge 设计）。 ### 为什么这个容易误解 直觉上，Meegle 是任务管理系统，Mayor 是任务调度 AI，「它们应该能配合」。但： - Meegle 是飞书生态的产品，有自己的 API 体系 - Gas Town 是独立开源工具，设计时没有考虑飞书集成 - 打通需要维护一个定期 polling 的脚本 ### 正确的分工理解 ``` Meegle = 你和团队看的产品任务板 Phase 0-2 在这里：讨论需求、拆分设计、记录决策 Beads = Agent 执行时的内存 Phase 3 在这里：agent 从这里认领任务、更新进度、记录依赖 之间的 bridge = 你（或者你写的脚本）把 Meegle 的 Phase 2 产出 → 写进 Beads ``` *** ## Beads vs Meegle 层级区别 这两个工具在表面上都是「任务管理」，但是给不同对象用的： | 维度 | Beads | Meegle | | --------- | ------------------------------------ | ---------------------------------------- | | **主要用户** | Agent（机器用） | 你和团队（人用） | | **时间层级** | 执行时（Phase 3） | 设计时（Phase 0-2） | | **任务粒度** | 技术子任务（「更新 contacts 表索引」） | 业务功能（「Phase 2: Contacts 核心架构」） | | **状态机** | pending → claimed → done（机器状态） | Todo → In Progress → Review → Done（人类流程） | | **防碰撞机制** | `--claim` 原子认领，Dolt cell-level merge | 手动分配，没有并发保护 | | **依赖关系** | `bd dep add`，agent 自动等依赖完成 | 靠人类口头沟通 | | **关系** | Meegle 的产出物写进 Beads | Beads 的完成状态同步回 Meegle | **比喻**：Meegle 是项目管理白板，Beads 是车间里的工单架。白板给 PM 和工程师开会用，工单架给机器人取件用。它们解决不同层级的问题，缺一不可。 *** ## Gas Town 类比：它不是 k8s Gas Town 经常被类比为「代码版 Kubernetes」，但两者的核心差异值得深入理解： | 维度 | Kubernetes（k8s） | Gas Town | | ----------- | ------------------------------ | ------------------------------------ | | **调度对象** | 无状态 container（有什么 CPU/内存就往哪里塞） | 有上下文的 AI agent（需要懂任务语义才能分配） | | **调度策略** | 资源利用率最大化（bin packing） | 哪个 Polecat 懂这个代码 → 分配给它 | | **通信方式** | Service → Pod（HTTP/TCP 协议） | Mayor → Polecat（自然语言，通过 tmux 消息） | | **失败处理** | 重启 Pod（无状态恢复） | Park & Notify（escalate 给人类，状态有意义） | | **「工人」的知识** | Container 不懂业务，只跑指令 | Polecat 是 Claude 实例，理解代码语义、历史决策、业务背景 | **更准确的类比**：Gas Town 更像一个 **Tech Lead + 工程师团队**，而不是容器调度器。 - **Mayor** = Tech Lead（知道整体 roadmap，知道每个人擅长什么，做 trade-off 决策） - **Polecats** = 工程师团队（接任务、写代码、遇到问题 escalate 给 Tech Lead） - **Beads** = Sprint Board（大家共享的任务状态） - **Rigs** = 各个服务的代码库 k8s 解决的是「把无状态容器往有资源的机器上塞」；Gas Town 解决的是「把需要理解的任务交给能理解的 agent，并协调它们不互相踩踏」。 *** ## ComposioHQ agent-orchestrator | | 信息 | | ---------- | --------------------------------------------------------------------------------- | | **GitHub** | [ComposioHQ/agent-orchestrator](https://github.com/ComposioHQ/agent-orchestrator) | | **Stars** | 4.1K | | **语言** | TypeScript | | **定位** | 批量一次性执行：spec → parallel worktrees → 批量 PR | ### 工作方式 ``` ao init --auto（自动检测 tech stack） ↓ 生成 agentRules（base.md + typescript.md + react.md...） ↓ 读 spec/issue 文件 ↓ 拆任务 → 并行 git worktrees ↓ CI 失败 → 自动路由回对应 agent 修 ↓ merge conflict → 自动处理 ↓ 批量 PR ``` ### 已知问题（用户反馈） - tmux session 死了界面假死（假装还在跑） - 消息发送了但 agent 没收到（竞争条件） - health check 显示绿色但检查的是旧路径 ### Gas Town vs ComposioHQ | 维度 | Gas Town + Beads | ComposioHQ | | ------------------ | ------------------------------- | ------------------------- | | **模式** | 长期常驻工厂，任务持续涌入 | 批量一次性执行 | | **上手难度** | ❌ 高（Dolt + Go + tmux 全套） | ✅ 低（`npx ao init --auto`） | | **成熟度** | ✅ Beads 19K stars，持续迭代 | ⚠️ 较早期，有竞争条件 bug | | **任务持久性** | ✅ Polecats 有持久 identity | ❌ 无状态，任务跑完就消失 | | **TypeScript 支持** | ✅ | ✅ 有 typescript.md 模板 | | **Claude Code 集成** | ✅ 原生（Beads 有 Claude Code hooks） | ✅ 官方支持 | *** ## Gas Town 替换 vs 叠加分析 Gas Town 引入时，不是「替换你现有的一切」，而是**精确叠加在 Phase 3 执行层**。弄清楚哪些被替换、哪些被增强、哪些完全不动，是引入前的关键判断。 | 现有配置 | Gas Town 之后 | 影响 | | --------------------------- | ------------------ | ------------------------- | | CLAUDE.md（规则文件） | ✅ 保留，Mayor 也会读 | Mayor 理解执行策略 | | execution-policy.md | ✅ 保留，Mayor 也会读 | Mayor 理解 Park & Notify 条件 | | .claude/skills/（23 个） | ✅ 保留，Polecats 也能调用 | Polecats 继承所有专业能力 | | Meegle MCP（7 个 tools） | ✅ 保留，Phase 0-2 不变 | 业务任务管理层完全不动 | | git worktree（手动管理） | ✅ → ⚡ 自动化 | Gas Town 自动创建/清理 worktree | | 你手动分配任务 | ✅ → ⚡ Mayor 接管 | 你退到 review 角色 | | working-memory/（session 记忆） | ✅ → ⚡ Beads 替代 | Beads 的任务状态更持久、更结构化 | | Phase 0-2（人机协作设计） | ✅ 完全不变 | Gas Town 只参与 Phase 3 | | Task Spec 必须有验收标准 | ✅ 更严格的要求 | Mayor 拒绝没有验收标准的任务 | **结论**：Phase 0-2（你做的设计和决策部分）完全不动。Gas Town 只改变 Phase 3（执行层）的自动化程度，从「你手动启动 + 分配」变成「Mayor 自动调度」。 *** ## 与 retaintive 现有系统的关系映射 | retaintive 现有概念 | Gas Town 对应概念 | 说明 | | ------------------------ | --------------------------- | --------------------------- | | Orchestrator + N Workers | **Mayor + Polecats** | 同一个模式，Gas Town 是具体实现 | | git worktree × N（手动） | **Hooks** | Gas Town 自动管理 worktree | | Park & Notify | **Escalation** | Mayor 上报给人类的机制 | | Circuit Breaker | **max\_turns 限制** | Gas Town 有类似的终止条件 | | working-memory/ | **Beads .beads/** | Beads 是更强的 working-memory | | Meegle MCP 触发 | ❌ 无原生支持 | 需要自己写 Meegle → Beads bridge | | execution-policy.md | **Mayor 读取的规则** | Mayor 也需要读 execution-policy | | Task Spec（验收标准） | **Beads task + bd dep add** | 等价，但 Beads 有依赖图 | **Gas Town 不是替代 retaintive 现有系统，而是 Phase 3 执行层的升级**。Phase 0-2（人做的部分）完全不变。 *** ## 引入时机：什么时候该考虑 Gas Town **现在不适合的原因**： - 依赖栈太重（Dolt + Go + tmux + Beads = 半天安装 + 1-2 周稳定期） - Meegle 没有原生集成，要自己写 bridge - 并行任务量不够大（\< 5 个/天），用 Claude Code 原生 worktree 就够 - Beads 升级频率高（v0.62.0 在几天前发布），Gas Town 跟进成本持续存在 **适合引入的触发条件**（满足任意 2 个）： - [ ] 每周并行任务 > 10 个 - [ ] 经常出现「两个 agent 改了同一个文件」的冲突 - [ ] 你需要任务依赖图（「GAP 7 必须等 GAP 3 完成」） - [ ] 你有一台专用的 dev 服务器可以 24/7 运行 Mayor - [ ] Meegle → Beads bridge 已经写好并稳定 ### ⚠️「隔夜自动跑」的前提条件 Gas Town 最吸引人的能力是「Mayor 在你睡觉时自动分配和执行任务」。但这个能力有一个**前提**： ``` Mayor 能自动执行任务 ⟺ 任务有明确的验收标准 没有验收标准的任务 → Mayor 不知道什么叫「做完了」 → 要么跑偏，要么无限循环 → 浪费 Claude API tokens，产出垃圾 ``` **实际含义**： - Phase 0（大任务探索）和 Phase 1（架构讨论）产出的是模糊想法 → **绝不能直接进 Beads 让 Mayor 跑** - 只有 Phase 2 完成后（Task Spec 有：目标 + 受影响文件 + 验收测试 + 约束）的子任务 → 才能安全地让 Mayor 自动执行 - 「夜里自动跑」= Phase 2 白天完成 → 睡前 `bd create` 写进 Beads → Mayor 隔夜执行 → 早上看 PR 这个约束与 retaintive 的 [Agentic Software Factory 操作手册](/ai/factory/agentic-software-factory-playbook.md) 完全一致：Phase 3 是 Execution，前提是 Phase 2 已产出清晰的 Task Spec。 **可以现在就引入（低成本）**： ```bash brew install beads # 单独安装 Beads，不需要 Gas Town 全套 bd init # 初始化项目 bd create # 创建任务 bd update --claim # Agent 认领任务 ``` Beads 单独用 = 有任务依赖图 + 防碰撞，但不需要 Dolt/Go/tmux。 *** ## 其他工具速查 | 工具 | 类型 | 与 retaintive 的关系 | | ---------------------- | ------------------------------- | ----------------------------------- | | **Goose**（Block） | Agentic IDE，model-agnostic，本地运行 | Claude Code 替代品，已有 Claude Code 就不需要 | | **Cline** | VS Code 插件版 Claude Code | Claude Code 替代品，不引入 | | **OpenHands** | 云端 Agentic IDE | Claude Code 替代品，不引入 | | **Devin AI** | 商业化 issue→PR SaaS（$500/月） | 太贵，但 Interactive Planning 流程值得参考 | | **LangChain open-swe** | 云端 orchestrator，内置 sandbox | 备选方案，云端跑 | **Goose 的深一层解释**：Block 开源的 model-agnostic Agentic IDE，支持切换 Claude / GPT / 其他 LLM。对已深度使用 Claude Code 的团队没有额外价值——Goose 的优势在于 model 灵活性，而 retaintive 不需要这个灵活性。 *** ## Sources - [Gas Town GitHub](https://github.com/steveyegge/gastown) - [Beads GitHub](https://github.com/steveyegge/beads) - [Beads 架构解析](https://virtuslab.com/blog/ai/beads-give-ai-memory/) - [Beads v0.51.0 迁移到 Dolt](https://gist.github.com/tmchow/f539adef1d11974eb51478a32a72ff68) - [ComposioHQ agent-orchestrator](https://github.com/ComposioHQ/agent-orchestrator) - [Agent Swarms 实战](https://juhache.substack.com/p/on-the-road-to-agent-swarms)