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 Taxonomy）

Gas Town 将 Agent 划分为两大类：基础设施角色（管理 Gas Town 系统本身）与工人角色（实际产出项目工作）。

基础设施角色

从架构文档 docs/design/architecture.md 可以看到更细的分工：Mayor 负责跨 Rig 通信与升级（escalation）；Deacon 接收心跳、运行插件与监控；Boot 是 Deacon 的看门狗——当 Deacon 宕机时由 daemon 派生的临时探员做分诊决策；Dogs 则是执行跨 Rig 批处理任务的长期工人。

工人角色

角色 Bead 与代理 Bead 的存储

身份不仅体现在角色划分上，还落实在 Beads 存储层。每个 Agent 都有对应的代理 Bead，位置取决于其作用域（见 docs/design/architecture.md）：

此外，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 的区别

所谓"启动一个 swarm"，实际包含三步：① 创建 convoy（追踪单元）；② 把 Polecat 指派到被追踪的 issue 上；③ swarm 只是这些 Polecat 工作期间的瞬时集合。当所有 issue 关闭时，convoy 落地（land）并通知你，swarm 随之解散。

Convoy 生命周期

OPEN ──(所有 issue 关闭)──► LANDED/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 --merge=direct # 绕过 Refinery 直接合并

添加 issue：

gt 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 --status=open 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 --status=closed # 仅已关闭 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 --merge=direct

其工作流程（源码见internal/cmd/convoy.go中--from-epic分支）：

1. 校验给定 bead 确实是 epic（非 epic 会报错：'%s' is not an epic (type: %s); --from-epic only works with epic beads）
2. 以 BFS 方式遍历父子层级，找出所有可 sling 的后代
3. 创建标准 convoy（hq-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 级 beads（hq-cv-*前缀），可追踪任意 Rig 的 issue：

gt convoy create "Full-stack feature" \ gt-frontend-abc \ gt-backend-def \ bd-docs-xyz

tracks关系的三个特性：

• 非阻塞：不影响 issue 自身的工作流
• 可累加：任何时刻都可以继续添加 issue
• 跨 Rig：convoy 在hq-*，issue 在gt-*、bd-*等任意前缀

Convoy 与 Rig 状态视图的取舍

用 convoy 回答"这批工作进展如何？"，用 rig status 回答"这个 Rig 里的每个人在干什么？"。

Crew vs Polecats：持久工人与瞬态工人

两者都做项目工作，但差异显著：

何时用 Crew

• 探索性工作
• 长期运行的项目
• 需要人类判断的工作
• 你想直接控制的任务

何时用 Polecat

• 离散、定义明确的任务
• 批量工作（用 convoy 追踪）
• 可并行的工作
• 需要监督的工作

Polecat 的"瞬态会话 + 持久身份"设计是理解这一差异的关键。在 docs/concepts/polecat-lifecycle.md 中，这一模型被拆分为三个独立生命周期层：

核心设计原则是"干净完成即退役会话"（retired completion model）：Polecat 完成工作后，其 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 中最常见的误解之一。

Dogs 是 Deacon 执行系统级任务的帮手：

• Boot：在每个 daemon tick 时分诊 Deacon 的健康状态
• 未来可能的 Dog：日志轮转、健康检查等

如果你需要在另一个 Rig 里做工作，用 worktree，而不是 dog。

这一区分同样体现在心跳体系中。Gas Town 有三套不同的心跳存储（见 docs/concepts/heartbeats.md）：Deacon 心跳文件（<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 之所以能保持身份，是因为 Gas Town 的 Worktree 采用.beads/redirect重定向机制（见 docs/design/architecture.md）——polecats、refinery、crew 没有自己的 beads 数据库，而是通过重定向文件指向规范的mayor/rig/.beads，ResolveBeadsDir()跟随重定向链（最大深度 3 层，带环检测），确保一个 Rig 内所有 Agent 共享同一份 beads 数据库。

目录结构：Town 根与 Rig

Town 根目录（~/gt/）包含基础设施目录（mayor/、deacon/）和按项目划分的 Rig。每个 Rig 持有一个裸仓库（.repo.git/）、规范的 beads 数据库（mayor/rig/.beads/）以及各 Agent 目录（witness/、refinery/、crew/、polecats/）。

从 docs/design/architecture.md 可以看完整的目录树设计要点：

~/gt/ Town 根 ├── .beads/ Town 级 beads（hq-* 前缀） │ ├── 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 进程（端口 3307，daemon 管理，数据在~/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>/是面向人类开发者的完整克隆。

身份与归属：一切工作都可溯源

所有工作都归属到实际执行的 Actor：

Git commits: Author: gastown/crew/joe <owner@example.com> Beads issues: created_by: gastown/crew/joe Events: actor: gastown/crew/joe

BD_ACTOR环境变量以斜杠分隔的路径格式标识 Agent，按角色类型格式化（规范见 docs/concepts/identity.md）：

归属贯穿三层数据：Git 提交同时记录GIT_AUTHOR_NAME（执行 Agent）与GIT_AUTHOR_EMAIL（作品归属人/overseer）；beads 记录用created_by/updated_by字段；事件日志全部带actor字段。

身份跨 Rig 保持：

• gastown/crew/joe在~/gt/beads/crew/gastown-joe/工作
• 提交仍归属gastown/crew/joe
• 工作计入 joe 的履历，而非 beads Rig 的工人

基于归属可以执行强大的审计查询：

# 某 Agent 的全部工作 bd audit --actor=gastown/crew/joe # 某 Rig 的全部工作 bd audit --actor=gastown/* # 所有 polecat 工作 bd audit --actor=*/polecats/* # 按 Agent 查 git 历史 git log --author="gastown/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.md）：

1. gt hook # 什么被 hook 了？ 2. bd mol current # 我在哪一步？ 3. 执行该步 4. bd close <step> --continue # 关闭并前进 5. 回到第 2 步

启动行为：① 检查 hook（gt hook）；② 有工作 → 立即执行；③ hook 为空 → 检查邮件中的附带工作；④ 到处都没有 → 报错并升级给 Witness。注意 "hooked"（被指派工作）会触发自主模式，即使没有挂接 molecule；不要与 "pinned"（永久参考 bead）混淆。

模型评估与 A/B 测试：把归属变成决策依据

Gas Town 的归属系统让客观模型对比成为可能：系统按 Agent 追踪完成时间、质量信号与修订次数（revision count）。在相似任务上部署不同模型，然后用bd stats对比结果：

# 各 Agent 完成率 bd stats --group-by=actor # 平均完成周期 bd stats --actor=gastown/polecats/* --metric=cycle-time # 按模型分组的质量对比（修订次数越低，首次通过质量越高） bd stats --actor=gastown/polecats/claude-* --metric=revision-count bd stats --actor=gastown/polecats/gpt-* --metric=revision-count

工作历史（Agent CV）为这类评估提供了原料：bd audit --actor=gastown/polecats/toast查看某 Agent 做过什么，bd stats --actor=gastown/polecats/toast --tag=go查看其在 Go 项目上的成功率。注意能力路由（capability-based routing）与联邦（federation）目前是Planned 状态（见 docs/why-these-features.md 中的状态标注），当前工作分配仍通过gt sling手动进行——引用时请以仓库文档标注为准，不要将其描述为已实现能力。

常见错误清单

1. 用 Dog 做用户工作：Dog 是 Deacon 的基础设施。用户工作请用 crew 或 polecats。
2. 混淆 crew 与 polecat：Crew 持久且由人类管理；Polecat 瞬态且由 Witness 管理。
3. 在错误的目录工作：Gas Town 用 cwd 做身份探测。请待在自己的主目录里。
4. 工作被 hook 后等待确认：hook 本身就是指派。立即执行。
5. 在应该派发时创建 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