Gas Town 多智能体工作区架构全解角色体系、Convoy 追踪与跨 Rig 协作模式【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown本文以 Gas Town 官方架构总览docs/overview.md为核心骨架结合仓库内 Convoy、Polecat 生命周期、身份归属、推进原理等概念文档与 Go 源码实现系统讲解 Gas Town 的角色分类Mayor / Deacon / Witness / Refinery / Polecat / Crew / Dog、用 Convoy 追踪批量化工作、Crew 与 Polecat 的选型、跨 Rig 的 Worktree 与派发两种协作路径、身份与归属模型、推进原理以及常见误用陷阱。读完本文你将能准确理解 Gas Town 各角色之间的职责边界掌握gt convoy、gt worktree、gt sling等核心命令的实战用法并能基于归属数据开展模型评估与 A/B 测试。为什么需要 Gas Town多智能体工程的新问题当 AI Agent 逐渐成为工程工作流的中心角色团队会遇到传统工具无法回答的四类问题问责Accountability谁做了什么这个 bug 是哪个 Agent 引入的质量Quality哪些 Agent 可靠哪些需要调优效率Efficiency如何把工作路由给正确的 Agent规模Scale如何跨仓库、跨团队协调大量 Agent传统工具帮不上忙CI/CD 追踪的是构建而非能力Git 追踪的是提交而非 Agent 表现项目管理工具追踪的是工单而非谁实际做了什么、做得怎么样。Gas Town 的答案是把 AI Agent 的工作当作结构化数据来处理——每一次动作都被归属attributed每一个 Agent 都有履历记录track record每一份工作都有完整来源provenance。这并非监控主义而是任何严肃工程系统都应具备的可见性。设计动机的完整论述见 docs/why-these-features.md术语速查见 docs/glossary.md。角色分类Role TaxonomyGas Town 将 Agent 划分为两大类基础设施角色管理 Gas Town 系统本身与工人角色实际产出项目工作。基础设施角色角色描述生命周期Mayor全局协调者处理跨 Rig 通信与升级单例常驻Deacon后台监督守护进程看门狗链持续运行 Patrol 周期单例常驻Witness每个 Rig 的 Polecat 生命周期管理者监控、催促nudge、回收每 Rig 一个常驻Refinery每个 Rig 的合并队列处理器负责 rebase 与合并每 Rig 一个常驻从架构文档 docs/design/architecture.md 可以看到更细的分工Mayor 负责跨 Rig 通信与升级escalationDeacon 接收心跳、运行插件与监控Boot 是 Deacon 的看门狗——当 Deacon 宕机时由 daemon 派生的临时探员做分诊决策Dogs 则是执行跨 Rig 批处理任务的长期工人。工人角色角色描述生命周期Polecat拥有持久身份、但会话短暂的工作者由 Witness 管理Witness 管理详见 docs/concepts/polecat-lifecycle.mdCrew拥有自己克隆仓库的持久工人由用户管理长期存活用户管理DogDeacon 执行基础设施任务的帮手身份持久Deacon 管理角色 Bead 与代理 Bead 的存储身份不仅体现在角色划分上还落实在 Beads 存储层。每个 Agent 都有对应的代理 Bead位置取决于其作用域见 docs/design/architecture.mdAgent 类型作用域Bead 位置Bead ID 格式MayorTown~/gt/.beads/hq-mayorDeaconTown~/gt/.beads/hq-deaconBootTown~/gt/.beads/hq-bootDogsTown~/gt/.beads/hq-dog-nameWitnessRigrig/.beads/prefix-rig-witnessRefineryRigrig/.beads/prefix-rig-refineryPolecatsRigrig/.beads/prefix-rig-polecat-nameCrewRigrig/.beads/prefix-rig-crew-name此外hq-*前缀的角色 Bead如hq-witness-role、hq-polecat-role是全局模板每个代理 Bead 通过role_bead字段引用自己的角色定义。这正是角色分类在数据模型层的落地。Convoy追踪工作的主要单元Convoy是 Gas Town 追踪批量化工作的核心单元。当你启动工作——哪怕只是一个 issue——都应该创建一个 convoy 来追踪它。它的完整设计见 docs/concepts/convoy.md。快速上手# 创建追踪若干 issue 的 convoy gt convoy create Feature X gt-abc gt-def --notify overseer # 查看进度 gt convoy status hq-cv-abc # 活跃 convoy 的仪表盘 gt convoy list # 查看所有 convoy含已落地/关闭的 gt convoy list --all为什么 Convoy 重要单一视图一眼看清当前在途工作全貌跨 Rig 追踪convoy 位于hq-*issue 可分布于gt-*、bd-*等多个前缀自动通知工作落地时自动通知订阅者历史记录gt convoy list --all保留已完成工作的完整记录Convoy 与 Swarm 的区别概念持久ID描述Convoy是hq-cv-*追踪单元。你创建、追踪、被通知的对象Swarm否无瞬时概念当前正在处理这个 convoy 各 issue 的工人集合Stranded Convoy是hq-cv-*有就绪工作但没有 Polecat 接手的 convoy需要关注所谓启动一个 swarm实际包含三步① 创建 convoy追踪单元② 把 Polecat 指派到被追踪的 issue 上③ swarm 只是这些 Polecat 工作期间的瞬时集合。当所有 issue 关闭时convoy 落地land并通知你swarm 随之解散。Convoy 生命周期OPEN ──(所有 issue 关闭)──► LANDED/CLOSED ↑ │ └──(添加更多 issue)────────────┘ (自动重新打开)状态描述open活跃追踪工作进行中closed所有被追踪 issue 已关闭通知已发送向已关闭的 convoy 添加 issue 会自动将其重新打开——这一行为在源码层面由internal/cmd/convoy.go的创建/追加逻辑支撑。Convoy 命令详解创建 convoy# 跨 Rig 追踪多个 issue gt convoy create Deploy v2.0 gt-abc bd-xyz --notify gastown/joe # 单个 issue 也建 convoy保证仪表盘可见性 gt convoy create Fix auth bug gt-auth-fix # 使用配置中的默认通知 gt convoy create Feature X gt-a gt-b gt-c # 高级用法源码 internal/cmd/convoy.go 中支持的全部模式 gt convoy create Release prep gt-abc --notify # 通知默认到 mayor/ gt convoy create Release prep gt-abc --notify ops/ # 通知到 ops/ 订阅者 gt convoy create Feature rollout gt-a gt-b --owner mayor/ --notify ops/ gt convoy create Feature rollout gt-a gt-b gt-c --molecule mol-release # 挂接分子 gt convoy create --owned Manual deploy gt-abc # 调用方管理生命周期 gt convoy create Quick fix gt-abc --mergedirect # 绕过 Refinery 直接合并添加 issuegt convoy add hq-cv-abc gt-new-issue gt convoy add hq-cv-abc gt-issue1 gt-issue2 gt-issue3 # 向已关闭的 convoy 添加需先重新打开 bd update hq-cv-abc --statusopen gt convoy add hq-cv-abc gt-followup-fix查看状态gt convoy status hq-abc # 显示 issue 与活跃工人即 swarm gt convoy status # 不带 id所有活跃 convoy仪表盘示例输出 hq-cv-abc: Deploy v2.0 Status: ● Progress: 2/4 completed Created: 2025-12-30T10:15:00-08:00 Tracked Issues: ✓ gt-xyz: Update API endpoint [task] ✓ bd-abc: Fix validation [bug] ○ bd-ghi: Update docs [task] ○ gt-jkl: Deploy to prod [task]列表仪表盘gt convoy list # 活跃 convoy默认主注意力视图 gt convoy list --all # 全部含已落地 gt convoy list --statusclosed # 仅已关闭 gt convoy list --json # JSON 输出通知机制当 convoy 落地所有被追踪 issue 关闭订阅者会收到通知gt convoy create Feature X gt-abc --notify gastown/joe # 显式订阅者 gt convoy create Feature X gt-abc --notify mayor/ --notify --human # 多个订阅者通知内容示例 Convoy Landed: Deploy v2.0 (hq-cv-abc) Issues (3): ✓ gt-xyz: Update API endpoint ✓ gt-def: Add validation ✓ bd-abc: Update docs Duration: 2h 15m从 Epic 创建 Convoy自动发现子工作当规划/拆解工具已经把工作组织成带子实现 bead 的 epic 时可以直接从 epic 自动发现被追踪的 issue# 从 epic 自动发现子项 gt convoy create --from-epic gt-epic-abc # 覆盖 convoy 名称默认取 epic 标题 gt convoy create --from-epic gt-epic-abc Custom convoy name # 与其他标志组合 gt convoy create --from-epic gt-epic-abc --owned --mergedirect其工作流程源码见internal/cmd/convoy.go中--from-epic分支校验给定 bead 确实是 epic非 epic 会报错%s is not an epic (type: %s); --from-epic only works with epic beads以 BFS 方式遍历父子层级找出所有可 sling 的后代创建标准 convoyhq-cv-*追踪所有可 sling 的子项task、bug、feature、chore 类型不可 sling 的类型子 epic、decision会被递归进入但绝不直接追踪只有叶子工作项出现在 convoy 中。Sling 自动建 Convoy当你 sling 单个 issue 且不存在既有 convoy 时gt sling bd-xyz beads/amber会自动完成三件事① 创建 convoy名称为 Work: bd-xyz② 追踪该 issue③ 指派 Polecat。即使是一个人的 swarm也能获得 convoy 可见性。跨 Rig 追踪语义Convoy 存在于 town 级 beadshq-cv-*前缀可追踪任意 Rig 的 issuegt convoy create Full-stack feature \ gt-frontend-abc \ gt-backend-def \ bd-docs-xyztracks关系的三个特性非阻塞不影响 issue 自身的工作流可累加任何时刻都可以继续添加 issue跨 Rigconvoy 在hq-*issue 在gt-*、bd-*等任意前缀Convoy 与 Rig 状态视图的取舍视图范围展示内容gt convoy status [id]跨 Rigconvoy 追踪的 issue 工人gt rig status rig单 RigRig 内所有工人 各自的 convoy 成员关系用 convoy 回答这批工作进展如何用 rig status 回答这个 Rig 里的每个人在干什么。Crew vs Polecats持久工人与瞬态工人两者都做项目工作但差异显著方面CrewPolecat生命周期持久用户控制瞬态Witness 控制监控无Witness 监视、催促、回收工作分配人工指派或自领通过gt sling抛掷Git 状态直接推 main在分支上工作由 Refinery 合并清理手动完成后自动身份rig/crew/namerig/polecats/name何时用 Crew探索性工作长期运行的项目需要人类判断的工作你想直接控制的任务何时用 Polecat离散、定义明确的任务批量工作用 convoy 追踪可并行的工作需要监督的工作Polecat 的瞬态会话 持久身份设计是理解这一差异的关键。在 docs/concepts/polecat-lifecycle.md 中这一模型被拆分为三个独立生命周期层层组件生命周期持久性身份层Agent bead、CV 链、工作历史永久永不消亡沙箱层Git worktree、分支每次指派/清理窗口为工作创建清理后退役会话层Claudetmux pane、上下文窗口每步临时随 step/handoff 轮换核心设计原则是干净完成即退役会话retired completion modelPolecat 完成工作后其 Agent 身份与合并证据持久保留但已完成的会话不会回到空闲复用池。gt done后的典型流程源码见internal/cmd/done.go的retirePolecatSessionAfterDone与POLECAT_DONE通知逻辑推分支 → 提交 MR 到合并队列 → 清空 hook → 设置状态为 done → 用 PID 排除方式自杀会话 → 留下分支/MR 元数据供 Witness/refinery 清理。会话轮换如gt handoff是正常操作而非故障——沙箱与 slot 在整个指派期间持续存在。Dogs vs Crew最常见的一个误解Dogs 不是工人。这是 Gas Town 中最常见的误解之一。方面DogsCrew所有者Deacon人类目的基础设施任务项目工作范围窄、聚焦的小工具通用目的生命周期非常短单任务长期存活示例Boot分诊 Deacon 健康状态Joe修 bug、加功能Dogs 是 Deacon 执行系统级任务的帮手Boot在每个 daemon tick 时分诊 Deacon 的健康状态未来可能的 Dog日志轮转、健康检查等如果你需要在另一个 Rig 里做工作用 worktree而不是 dog。这一区分同样体现在心跳体系中。Gas Town 有三套不同的心跳存储见 docs/concepts/heartbeats.mdDeacon 心跳文件townRoot/deacon/heartbeat.json由gt deacon heartbeat写入、会话心跳由gt heartbeat --state...写入、Witness 读取、以及 agent bead 上的heartbeat:EPOCH标签由gt mol await-signal更新。监控脚本的黄金法则是绝不要仅凭单一存储判定 Agent 卡死应先交叉检查 tmux 会话活动因为存储陈旧但会话活跃往往是心跳写入偏差heartbeat-write divergence而非卡死——stuck-agent-dog 插件正是这样做的。跨 Rig 工作模式当某个 Crew 成员需要在另一个 Rig 工作有两条路径方案一Worktree首选在目标 Rig 创建 worktree# gastown/crew/joe 需要修 beads 的 bug gt worktree beads # 创建 ~/gt/beads/crew/gastown-joe/ # 身份保持BD_ACTOR gastown/crew/joe目录结构源码见internal/cmd/worktree.go支持gt worktree rig、gt worktree remove rig、gt worktree rig --no-cd等子命令~/gt/beads/crew/gastown-joe/ # joe来自 gastown在 beads 上工作 ~/gt/gastown/crew/beads-wolf/ # wolf来自 beads在 gastown 上工作方案二派发给目标 Rig 的本地工人适合应由目标 Rig 拥有所有权的工作# 在目标 Rig 创建 issue bd create --repo beads Fix authentication bug # 创建 convoy 并 sling 到目标 Rig gt convoy create Auth fix bd-xyz gt sling bd-xyz beads何时选哪种场景方案快速修复某处问题Worktree工作应计入你自己的履历Worktree工作应由目标 Rig 团队完成派发基础设施/系统级任务交给 Deacon从架构上补充一点worktree 之所以能保持身份是因为 Gas Town 的 Worktree 采用.beads/redirect重定向机制见 docs/design/architecture.md——polecats、refinery、crew 没有自己的 beads 数据库而是通过重定向文件指向规范的mayor/rig/.beadsResolveBeadsDir()跟随重定向链最大深度 3 层带环检测确保一个 Rig 内所有 Agent 共享同一份 beads 数据库。目录结构Town 根与 RigTown 根目录~/gt/包含基础设施目录mayor/、deacon/和按项目划分的 Rig。每个 Rig 持有一个裸仓库.repo.git/、规范的 beads 数据库mayor/rig/.beads/以及各 Agent 目录witness/、refinery/、crew/、polecats/。从 docs/design/architecture.md 可以看完整的目录树设计要点~/gt/ Town 根 ├── .beads/ Town 级 beadshq-* 前缀 │ ├── metadata.json Beads 配置dolt_mode、dolt_database │ └── routes.jsonl 前缀 → Rig 路由表 ├── .dolt-data/ 集中的 Dolt 数据目录 ├── daemon/ Daemon 运行时状态 ├── deacon/ Deacon 工作区 │ └── dogs/name/ Dog 工人目录 ├── mayor/ Mayor 代理主目录 ├── settings/ Town 级设置 ├── directives/ Town 级角色指令operator 策略 ├── formula-overlays/ Town 级公式覆盖 └── rig/ 项目容器不是 git clone ├── config.json Rig 身份与 beads 前缀 ├── mayor/rig/ 规范克隆beads 在这里不是 Agent ├── refinery/ Refinery 代理主目录 ├── witness/ Witness 代理主目录无克隆 ├── crew/name/ 人类工作区完整克隆 └── polecats/name/ 工人 worktree基于 mayor/rig两个值得注意的架构事实其一所有 beads 数据存放在每个 town 唯一的 Dolt SQL Server 进程端口 3307daemon 管理数据在~/gt/.dolt-data/中没有嵌入式 Dolt 回退——服务器若宕机bd会快速失败并提示gt dolt start其二Polecat 与 refinery 是 git worktree 而非完整克隆git worktree add -b polecat/name-timestamp polecats/name见internal/polecat/manager.go而crew/name/是面向人类开发者的完整克隆。身份与归属一切工作都可溯源所有工作都归属到实际执行的 ActorGit commits: Author: gastown/crew/joe ownerexample.com Beads issues: created_by: gastown/crew/joe Events: actor: gastown/crew/joeBD_ACTOR环境变量以斜杠分隔的路径格式标识 Agent按角色类型格式化规范见 docs/concepts/identity.md角色类型格式示例MayormayormayorDeacondeacondeaconWitness{rig}/witnessgastown/witnessRefinery{rig}/refinerygastown/refineryCrew{rig}/crew/{name}gastown/crew/joePolecat{rig}/polecats/{name}gastown/polecats/toast归属贯穿三层数据Git 提交同时记录GIT_AUTHOR_NAME执行 Agent与GIT_AUTHOR_EMAIL作品归属人/overseerbeads 记录用created_by/updated_by字段事件日志全部带actor字段。身份跨 Rig 保持gastown/crew/joe在~/gt/beads/crew/gastown-joe/工作提交仍归属gastown/crew/joe工作计入 joe 的履历而非 beads Rig 的工人基于归属可以执行强大的审计查询# 某 Agent 的全部工作 bd audit --actorgastown/crew/joe # 某 Rig 的全部工作 bd audit --actorgastown/* # 所有 polecat 工作 bd audit --actor*/polecats/* # 按 Agent 查 git 历史 git log --authorgastown/crew/joe推进原理蒸汽机与活塞所有 Gas Town Agent 遵循同一个核心原则如果你的 hook 上有东西你就去执行它。无论角色如何都适用。Hook 就是你的指派——它被放置在那里是刻意的。等待确认的每一刻都是引擎熄火的时刻。Gas Town 是一台蒸汽机Agent 是活塞。推进的关键支撑是分子导航Molecule Navigation提供的明确路标gt hook # 我的 hook 上有什么 gt prime # 显示内联公式清单 bd show issue-id # 我指派的 issue 是什么推进循环详见 docs/concepts/propulsion-principle.md1. gt hook # 什么被 hook 了 2. bd mol current # 我在哪一步 3. 执行该步 4. bd close step --continue # 关闭并前进 5. 回到第 2 步启动行为① 检查 hookgt hook② 有工作 → 立即执行③ hook 为空 → 检查邮件中的附带工作④ 到处都没有 → 报错并升级给 Witness。注意 hooked被指派工作会触发自主模式即使没有挂接 molecule不要与 pinned永久参考 bead混淆。模型评估与 A/B 测试把归属变成决策依据Gas Town 的归属系统让客观模型对比成为可能系统按 Agent 追踪完成时间、质量信号与修订次数revision count。在相似任务上部署不同模型然后用bd stats对比结果# 各 Agent 完成率 bd stats --group-byactor # 平均完成周期 bd stats --actorgastown/polecats/* --metriccycle-time # 按模型分组的质量对比修订次数越低首次通过质量越高 bd stats --actorgastown/polecats/claude-* --metricrevision-count bd stats --actorgastown/polecats/gpt-* --metricrevision-count工作历史Agent CV为这类评估提供了原料bd audit --actorgastown/polecats/toast查看某 Agent 做过什么bd stats --actorgastown/polecats/toast --taggo查看其在 Go 项目上的成功率。注意能力路由capability-based routing与联邦federation目前是Planned 状态见 docs/why-these-features.md 中的状态标注当前工作分配仍通过gt sling手动进行——引用时请以仓库文档标注为准不要将其描述为已实现能力。常见错误清单用 Dog 做用户工作Dog 是 Deacon 的基础设施。用户工作请用 crew 或 polecats。混淆 crew 与 polecatCrew 持久且由人类管理Polecat 瞬态且由 Witness 管理。在错误的目录工作Gas Town 用 cwd 做身份探测。请待在自己的主目录里。工作被 hook 后等待确认hook 本身就是指派。立即执行。在应该派发时创建 worktree如果工作应由目标 Rig 拥有所有权请改为派发。延伸阅读docs/concepts/convoy.md — Convoy 完整设计、生命周期与全部命令docs/concepts/polecat-lifecycle.md — Polecat 三层生命周期与退役模型docs/concepts/identity.md — BD_ACTOR 格式规范与审计查询docs/concepts/propulsion-principle.md — 推进原理与失败模式docs/concepts/heartbeats.md — 三套心跳存储与监控准则docs/design/architecture.md — 两级 Beads 架构、目录树、Dolt 存储与合并队列docs/why-these-features.md — 特性背后的设计动机与实现状态docs/glossary.md — 术语速查MEOW、GUPP、NDI、Bead、Molecule、Hook 等【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Gas Town 多智能体工作区架构全解：角色体系、Convoy 追踪与跨 Rig 协作模式
Gas Town 多智能体工作区架构全解角色体系、Convoy 追踪与跨 Rig 协作模式【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown本文以 Gas Town 官方架构总览docs/overview.md为核心骨架结合仓库内 Convoy、Polecat 生命周期、身份归属、推进原理等概念文档与 Go 源码实现系统讲解 Gas Town 的角色分类Mayor / Deacon / Witness / Refinery / Polecat / Crew / Dog、用 Convoy 追踪批量化工作、Crew 与 Polecat 的选型、跨 Rig 的 Worktree 与派发两种协作路径、身份与归属模型、推进原理以及常见误用陷阱。读完本文你将能准确理解 Gas Town 各角色之间的职责边界掌握gt convoy、gt worktree、gt sling等核心命令的实战用法并能基于归属数据开展模型评估与 A/B 测试。为什么需要 Gas Town多智能体工程的新问题当 AI Agent 逐渐成为工程工作流的中心角色团队会遇到传统工具无法回答的四类问题问责Accountability谁做了什么这个 bug 是哪个 Agent 引入的质量Quality哪些 Agent 可靠哪些需要调优效率Efficiency如何把工作路由给正确的 Agent规模Scale如何跨仓库、跨团队协调大量 Agent传统工具帮不上忙CI/CD 追踪的是构建而非能力Git 追踪的是提交而非 Agent 表现项目管理工具追踪的是工单而非谁实际做了什么、做得怎么样。Gas Town 的答案是把 AI Agent 的工作当作结构化数据来处理——每一次动作都被归属attributed每一个 Agent 都有履历记录track record每一份工作都有完整来源provenance。这并非监控主义而是任何严肃工程系统都应具备的可见性。设计动机的完整论述见 docs/why-these-features.md术语速查见 docs/glossary.md。角色分类Role TaxonomyGas Town 将 Agent 划分为两大类基础设施角色管理 Gas Town 系统本身与工人角色实际产出项目工作。基础设施角色角色描述生命周期Mayor全局协调者处理跨 Rig 通信与升级单例常驻Deacon后台监督守护进程看门狗链持续运行 Patrol 周期单例常驻Witness每个 Rig 的 Polecat 生命周期管理者监控、催促nudge、回收每 Rig 一个常驻Refinery每个 Rig 的合并队列处理器负责 rebase 与合并每 Rig 一个常驻从架构文档 docs/design/architecture.md 可以看到更细的分工Mayor 负责跨 Rig 通信与升级escalationDeacon 接收心跳、运行插件与监控Boot 是 Deacon 的看门狗——当 Deacon 宕机时由 daemon 派生的临时探员做分诊决策Dogs 则是执行跨 Rig 批处理任务的长期工人。工人角色角色描述生命周期Polecat拥有持久身份、但会话短暂的工作者由 Witness 管理Witness 管理详见 docs/concepts/polecat-lifecycle.mdCrew拥有自己克隆仓库的持久工人由用户管理长期存活用户管理DogDeacon 执行基础设施任务的帮手身份持久Deacon 管理角色 Bead 与代理 Bead 的存储身份不仅体现在角色划分上还落实在 Beads 存储层。每个 Agent 都有对应的代理 Bead位置取决于其作用域见 docs/design/architecture.mdAgent 类型作用域Bead 位置Bead ID 格式MayorTown~/gt/.beads/hq-mayorDeaconTown~/gt/.beads/hq-deaconBootTown~/gt/.beads/hq-bootDogsTown~/gt/.beads/hq-dog-nameWitnessRigrig/.beads/prefix-rig-witnessRefineryRigrig/.beads/prefix-rig-refineryPolecatsRigrig/.beads/prefix-rig-polecat-nameCrewRigrig/.beads/prefix-rig-crew-name此外hq-*前缀的角色 Bead如hq-witness-role、hq-polecat-role是全局模板每个代理 Bead 通过role_bead字段引用自己的角色定义。这正是角色分类在数据模型层的落地。Convoy追踪工作的主要单元Convoy是 Gas Town 追踪批量化工作的核心单元。当你启动工作——哪怕只是一个 issue——都应该创建一个 convoy 来追踪它。它的完整设计见 docs/concepts/convoy.md。快速上手# 创建追踪若干 issue 的 convoy gt convoy create Feature X gt-abc gt-def --notify overseer # 查看进度 gt convoy status hq-cv-abc # 活跃 convoy 的仪表盘 gt convoy list # 查看所有 convoy含已落地/关闭的 gt convoy list --all为什么 Convoy 重要单一视图一眼看清当前在途工作全貌跨 Rig 追踪convoy 位于hq-*issue 可分布于gt-*、bd-*等多个前缀自动通知工作落地时自动通知订阅者历史记录gt convoy list --all保留已完成工作的完整记录Convoy 与 Swarm 的区别概念持久ID描述Convoy是hq-cv-*追踪单元。你创建、追踪、被通知的对象Swarm否无瞬时概念当前正在处理这个 convoy 各 issue 的工人集合Stranded Convoy是hq-cv-*有就绪工作但没有 Polecat 接手的 convoy需要关注所谓启动一个 swarm实际包含三步① 创建 convoy追踪单元② 把 Polecat 指派到被追踪的 issue 上③ swarm 只是这些 Polecat 工作期间的瞬时集合。当所有 issue 关闭时convoy 落地land并通知你swarm 随之解散。Convoy 生命周期OPEN ──(所有 issue 关闭)──► LANDED/CLOSED ↑ │ └──(添加更多 issue)────────────┘ (自动重新打开)状态描述open活跃追踪工作进行中closed所有被追踪 issue 已关闭通知已发送向已关闭的 convoy 添加 issue 会自动将其重新打开——这一行为在源码层面由internal/cmd/convoy.go的创建/追加逻辑支撑。Convoy 命令详解创建 convoy# 跨 Rig 追踪多个 issue gt convoy create Deploy v2.0 gt-abc bd-xyz --notify gastown/joe # 单个 issue 也建 convoy保证仪表盘可见性 gt convoy create Fix auth bug gt-auth-fix # 使用配置中的默认通知 gt convoy create Feature X gt-a gt-b gt-c # 高级用法源码 internal/cmd/convoy.go 中支持的全部模式 gt convoy create Release prep gt-abc --notify # 通知默认到 mayor/ gt convoy create Release prep gt-abc --notify ops/ # 通知到 ops/ 订阅者 gt convoy create Feature rollout gt-a gt-b --owner mayor/ --notify ops/ gt convoy create Feature rollout gt-a gt-b gt-c --molecule mol-release # 挂接分子 gt convoy create --owned Manual deploy gt-abc # 调用方管理生命周期 gt convoy create Quick fix gt-abc --mergedirect # 绕过 Refinery 直接合并添加 issuegt convoy add hq-cv-abc gt-new-issue gt convoy add hq-cv-abc gt-issue1 gt-issue2 gt-issue3 # 向已关闭的 convoy 添加需先重新打开 bd update hq-cv-abc --statusopen gt convoy add hq-cv-abc gt-followup-fix查看状态gt convoy status hq-abc # 显示 issue 与活跃工人即 swarm gt convoy status # 不带 id所有活跃 convoy仪表盘示例输出 hq-cv-abc: Deploy v2.0 Status: ● Progress: 2/4 completed Created: 2025-12-30T10:15:00-08:00 Tracked Issues: ✓ gt-xyz: Update API endpoint [task] ✓ bd-abc: Fix validation [bug] ○ bd-ghi: Update docs [task] ○ gt-jkl: Deploy to prod [task]列表仪表盘gt convoy list # 活跃 convoy默认主注意力视图 gt convoy list --all # 全部含已落地 gt convoy list --statusclosed # 仅已关闭 gt convoy list --json # JSON 输出通知机制当 convoy 落地所有被追踪 issue 关闭订阅者会收到通知gt convoy create Feature X gt-abc --notify gastown/joe # 显式订阅者 gt convoy create Feature X gt-abc --notify mayor/ --notify --human # 多个订阅者通知内容示例 Convoy Landed: Deploy v2.0 (hq-cv-abc) Issues (3): ✓ gt-xyz: Update API endpoint ✓ gt-def: Add validation ✓ bd-abc: Update docs Duration: 2h 15m从 Epic 创建 Convoy自动发现子工作当规划/拆解工具已经把工作组织成带子实现 bead 的 epic 时可以直接从 epic 自动发现被追踪的 issue# 从 epic 自动发现子项 gt convoy create --from-epic gt-epic-abc # 覆盖 convoy 名称默认取 epic 标题 gt convoy create --from-epic gt-epic-abc Custom convoy name # 与其他标志组合 gt convoy create --from-epic gt-epic-abc --owned --mergedirect其工作流程源码见internal/cmd/convoy.go中--from-epic分支校验给定 bead 确实是 epic非 epic 会报错%s is not an epic (type: %s); --from-epic only works with epic beads以 BFS 方式遍历父子层级找出所有可 sling 的后代创建标准 convoyhq-cv-*追踪所有可 sling 的子项task、bug、feature、chore 类型不可 sling 的类型子 epic、decision会被递归进入但绝不直接追踪只有叶子工作项出现在 convoy 中。Sling 自动建 Convoy当你 sling 单个 issue 且不存在既有 convoy 时gt sling bd-xyz beads/amber会自动完成三件事① 创建 convoy名称为 Work: bd-xyz② 追踪该 issue③ 指派 Polecat。即使是一个人的 swarm也能获得 convoy 可见性。跨 Rig 追踪语义Convoy 存在于 town 级 beadshq-cv-*前缀可追踪任意 Rig 的 issuegt convoy create Full-stack feature \ gt-frontend-abc \ gt-backend-def \ bd-docs-xyztracks关系的三个特性非阻塞不影响 issue 自身的工作流可累加任何时刻都可以继续添加 issue跨 Rigconvoy 在hq-*issue 在gt-*、bd-*等任意前缀Convoy 与 Rig 状态视图的取舍视图范围展示内容gt convoy status [id]跨 Rigconvoy 追踪的 issue 工人gt rig status rig单 RigRig 内所有工人 各自的 convoy 成员关系用 convoy 回答这批工作进展如何用 rig status 回答这个 Rig 里的每个人在干什么。Crew vs Polecats持久工人与瞬态工人两者都做项目工作但差异显著方面CrewPolecat生命周期持久用户控制瞬态Witness 控制监控无Witness 监视、催促、回收工作分配人工指派或自领通过gt sling抛掷Git 状态直接推 main在分支上工作由 Refinery 合并清理手动完成后自动身份rig/crew/namerig/polecats/name何时用 Crew探索性工作长期运行的项目需要人类判断的工作你想直接控制的任务何时用 Polecat离散、定义明确的任务批量工作用 convoy 追踪可并行的工作需要监督的工作Polecat 的瞬态会话 持久身份设计是理解这一差异的关键。在 docs/concepts/polecat-lifecycle.md 中这一模型被拆分为三个独立生命周期层层组件生命周期持久性身份层Agent bead、CV 链、工作历史永久永不消亡沙箱层Git worktree、分支每次指派/清理窗口为工作创建清理后退役会话层Claudetmux pane、上下文窗口每步临时随 step/handoff 轮换核心设计原则是干净完成即退役会话retired completion modelPolecat 完成工作后其 Agent 身份与合并证据持久保留但已完成的会话不会回到空闲复用池。gt done后的典型流程源码见internal/cmd/done.go的retirePolecatSessionAfterDone与POLECAT_DONE通知逻辑推分支 → 提交 MR 到合并队列 → 清空 hook → 设置状态为 done → 用 PID 排除方式自杀会话 → 留下分支/MR 元数据供 Witness/refinery 清理。会话轮换如gt handoff是正常操作而非故障——沙箱与 slot 在整个指派期间持续存在。Dogs vs Crew最常见的一个误解Dogs 不是工人。这是 Gas Town 中最常见的误解之一。方面DogsCrew所有者Deacon人类目的基础设施任务项目工作范围窄、聚焦的小工具通用目的生命周期非常短单任务长期存活示例Boot分诊 Deacon 健康状态Joe修 bug、加功能Dogs 是 Deacon 执行系统级任务的帮手Boot在每个 daemon tick 时分诊 Deacon 的健康状态未来可能的 Dog日志轮转、健康检查等如果你需要在另一个 Rig 里做工作用 worktree而不是 dog。这一区分同样体现在心跳体系中。Gas Town 有三套不同的心跳存储见 docs/concepts/heartbeats.mdDeacon 心跳文件townRoot/deacon/heartbeat.json由gt deacon heartbeat写入、会话心跳由gt heartbeat --state...写入、Witness 读取、以及 agent bead 上的heartbeat:EPOCH标签由gt mol await-signal更新。监控脚本的黄金法则是绝不要仅凭单一存储判定 Agent 卡死应先交叉检查 tmux 会话活动因为存储陈旧但会话活跃往往是心跳写入偏差heartbeat-write divergence而非卡死——stuck-agent-dog 插件正是这样做的。跨 Rig 工作模式当某个 Crew 成员需要在另一个 Rig 工作有两条路径方案一Worktree首选在目标 Rig 创建 worktree# gastown/crew/joe 需要修 beads 的 bug gt worktree beads # 创建 ~/gt/beads/crew/gastown-joe/ # 身份保持BD_ACTOR gastown/crew/joe目录结构源码见internal/cmd/worktree.go支持gt worktree rig、gt worktree remove rig、gt worktree rig --no-cd等子命令~/gt/beads/crew/gastown-joe/ # joe来自 gastown在 beads 上工作 ~/gt/gastown/crew/beads-wolf/ # wolf来自 beads在 gastown 上工作方案二派发给目标 Rig 的本地工人适合应由目标 Rig 拥有所有权的工作# 在目标 Rig 创建 issue bd create --repo beads Fix authentication bug # 创建 convoy 并 sling 到目标 Rig gt convoy create Auth fix bd-xyz gt sling bd-xyz beads何时选哪种场景方案快速修复某处问题Worktree工作应计入你自己的履历Worktree工作应由目标 Rig 团队完成派发基础设施/系统级任务交给 Deacon从架构上补充一点worktree 之所以能保持身份是因为 Gas Town 的 Worktree 采用.beads/redirect重定向机制见 docs/design/architecture.md——polecats、refinery、crew 没有自己的 beads 数据库而是通过重定向文件指向规范的mayor/rig/.beadsResolveBeadsDir()跟随重定向链最大深度 3 层带环检测确保一个 Rig 内所有 Agent 共享同一份 beads 数据库。目录结构Town 根与 RigTown 根目录~/gt/包含基础设施目录mayor/、deacon/和按项目划分的 Rig。每个 Rig 持有一个裸仓库.repo.git/、规范的 beads 数据库mayor/rig/.beads/以及各 Agent 目录witness/、refinery/、crew/、polecats/。从 docs/design/architecture.md 可以看完整的目录树设计要点~/gt/ Town 根 ├── .beads/ Town 级 beadshq-* 前缀 │ ├── metadata.json Beads 配置dolt_mode、dolt_database │ └── routes.jsonl 前缀 → Rig 路由表 ├── .dolt-data/ 集中的 Dolt 数据目录 ├── daemon/ Daemon 运行时状态 ├── deacon/ Deacon 工作区 │ └── dogs/name/ Dog 工人目录 ├── mayor/ Mayor 代理主目录 ├── settings/ Town 级设置 ├── directives/ Town 级角色指令operator 策略 ├── formula-overlays/ Town 级公式覆盖 └── rig/ 项目容器不是 git clone ├── config.json Rig 身份与 beads 前缀 ├── mayor/rig/ 规范克隆beads 在这里不是 Agent ├── refinery/ Refinery 代理主目录 ├── witness/ Witness 代理主目录无克隆 ├── crew/name/ 人类工作区完整克隆 └── polecats/name/ 工人 worktree基于 mayor/rig两个值得注意的架构事实其一所有 beads 数据存放在每个 town 唯一的 Dolt SQL Server 进程端口 3307daemon 管理数据在~/gt/.dolt-data/中没有嵌入式 Dolt 回退——服务器若宕机bd会快速失败并提示gt dolt start其二Polecat 与 refinery 是 git worktree 而非完整克隆git worktree add -b polecat/name-timestamp polecats/name见internal/polecat/manager.go而crew/name/是面向人类开发者的完整克隆。身份与归属一切工作都可溯源所有工作都归属到实际执行的 ActorGit commits: Author: gastown/crew/joe ownerexample.com Beads issues: created_by: gastown/crew/joe Events: actor: gastown/crew/joeBD_ACTOR环境变量以斜杠分隔的路径格式标识 Agent按角色类型格式化规范见 docs/concepts/identity.md角色类型格式示例MayormayormayorDeacondeacondeaconWitness{rig}/witnessgastown/witnessRefinery{rig}/refinerygastown/refineryCrew{rig}/crew/{name}gastown/crew/joePolecat{rig}/polecats/{name}gastown/polecats/toast归属贯穿三层数据Git 提交同时记录GIT_AUTHOR_NAME执行 Agent与GIT_AUTHOR_EMAIL作品归属人/overseerbeads 记录用created_by/updated_by字段事件日志全部带actor字段。身份跨 Rig 保持gastown/crew/joe在~/gt/beads/crew/gastown-joe/工作提交仍归属gastown/crew/joe工作计入 joe 的履历而非 beads Rig 的工人基于归属可以执行强大的审计查询# 某 Agent 的全部工作 bd audit --actorgastown/crew/joe # 某 Rig 的全部工作 bd audit --actorgastown/* # 所有 polecat 工作 bd audit --actor*/polecats/* # 按 Agent 查 git 历史 git log --authorgastown/crew/joe推进原理蒸汽机与活塞所有 Gas Town Agent 遵循同一个核心原则如果你的 hook 上有东西你就去执行它。无论角色如何都适用。Hook 就是你的指派——它被放置在那里是刻意的。等待确认的每一刻都是引擎熄火的时刻。Gas Town 是一台蒸汽机Agent 是活塞。推进的关键支撑是分子导航Molecule Navigation提供的明确路标gt hook # 我的 hook 上有什么 gt prime # 显示内联公式清单 bd show issue-id # 我指派的 issue 是什么推进循环详见 docs/concepts/propulsion-principle.md1. gt hook # 什么被 hook 了 2. bd mol current # 我在哪一步 3. 执行该步 4. bd close step --continue # 关闭并前进 5. 回到第 2 步启动行为① 检查 hookgt hook② 有工作 → 立即执行③ hook 为空 → 检查邮件中的附带工作④ 到处都没有 → 报错并升级给 Witness。注意 hooked被指派工作会触发自主模式即使没有挂接 molecule不要与 pinned永久参考 bead混淆。模型评估与 A/B 测试把归属变成决策依据Gas Town 的归属系统让客观模型对比成为可能系统按 Agent 追踪完成时间、质量信号与修订次数revision count。在相似任务上部署不同模型然后用bd stats对比结果# 各 Agent 完成率 bd stats --group-byactor # 平均完成周期 bd stats --actorgastown/polecats/* --metriccycle-time # 按模型分组的质量对比修订次数越低首次通过质量越高 bd stats --actorgastown/polecats/claude-* --metricrevision-count bd stats --actorgastown/polecats/gpt-* --metricrevision-count工作历史Agent CV为这类评估提供了原料bd audit --actorgastown/polecats/toast查看某 Agent 做过什么bd stats --actorgastown/polecats/toast --taggo查看其在 Go 项目上的成功率。注意能力路由capability-based routing与联邦federation目前是Planned 状态见 docs/why-these-features.md 中的状态标注当前工作分配仍通过gt sling手动进行——引用时请以仓库文档标注为准不要将其描述为已实现能力。常见错误清单用 Dog 做用户工作Dog 是 Deacon 的基础设施。用户工作请用 crew 或 polecats。混淆 crew 与 polecatCrew 持久且由人类管理Polecat 瞬态且由 Witness 管理。在错误的目录工作Gas Town 用 cwd 做身份探测。请待在自己的主目录里。工作被 hook 后等待确认hook 本身就是指派。立即执行。在应该派发时创建 worktree如果工作应由目标 Rig 拥有所有权请改为派发。延伸阅读docs/concepts/convoy.md — Convoy 完整设计、生命周期与全部命令docs/concepts/polecat-lifecycle.md — Polecat 三层生命周期与退役模型docs/concepts/identity.md — BD_ACTOR 格式规范与审计查询docs/concepts/propulsion-principle.md — 推进原理与失败模式docs/concepts/heartbeats.md — 三套心跳存储与监控准则docs/design/architecture.md — 两级 Beads 架构、目录树、Dolt 存储与合并队列docs/why-these-features.md — 特性背后的设计动机与实现状态docs/glossary.md — 术语速查MEOW、GUPP、NDI、Bead、Molecule、Hook 等【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
