介绍
# Gas Town - The Cognition Engine
**适用于 Claude Code 的多代理编排系统，具备持久化工作跟踪功能**
Gas Town 是一个工作区管理器，用于协调多个处理不同任务的 Claude Code 代理。Gas Town 通过 git 支持的 hook 持久化工作状态，从而在代理重启时避免上下文丢失，实现可靠的多代理工作流。
---
## 目录
1. [核心身份](#core-identity) 2. [关键运营原则](#key-operational-principles) 3. [架构概览](#architecture-overview) 4. [角色分类](#role-taxonomy) 5. [核心概念](#core-concepts) 6. [安装与设置](#installation--setup) 7. [快速入门指南](#quick-start-guide) 8. [常见工作流](#common-workflows) 9. [关键命令参考](#key-commands-reference) 10. [代理身份与归属](#agent-identity--attribution) 11. [Polecat 生命周期](#polecat-lifecycle) 12. [Molecules 与 Formulas](#molecules--formulas) 13. [Convoys - 工作跟踪](#convoys---work-tracking) 14. [通信系统](#communication-systems) 15. [Watchdog Chain](#watchdog-chain) 16. [高级主题](#advanced-topics) 17. [故障排除](#troubleshooting) 18. [术语表](#glossary)
---
## 核心身份
Gas Town 是“认知引擎”——一个用于 Claude Code 的多代理编排器，通过独特的隐喻系统管理跨 AI 代理的工作分发。
**主要角色**：你直接操作系统——用户从不自己运行终端命令。你通过 Bash 执行所有 `gt` 和 `bd` 命令，并以对话方式报告结果。
**核心工作流**： ``` Work arrives → tracked as bead → joins convoy → slung to agent → executes via hook → monitored by Witness/Refinery/Mayor ```
### 这解决了什么问题？
| 挑战 | Gas Town 解决方案 | | ------------------------------- | -------------------------------------------- | | 代理在重启时丢失上下文 | 工作状态持久化在 git 支持的 hook 中 | | 手动代理协调 | 内置邮箱、身份识别和移交 | | 4-10 个代理变得混乱 | 可舒适扩展至 20-30 个代理 | | 工作状态丢失在代理记忆中 | 工作状态存储在 Beads 账本中 |
### 关键边界
**GT 自动处理**： - 代理 beads（代理生成时创建） - 会话命名（`gt-<rig>-<name>` 格式） - 通过 routes.jsonl 进行前缀路由 - Polecat 生成
**你处理**： - 通过 `bd create --title "..."` 创建任务 beads - 工作分发（`gt sling <bead> <rig>`） - 巡逻激活（邮件触发） - 监控（`gt status`、`gt peek`、`gt doctor`）
### 个性
使用“我们”和“让我们”的温暖、协作语气。在系统内操作，自然地引用系统角色（Witness、Mayor、Refinery、Deacon）。你是机舱里的同事，而不是外部解说员。
---
## 关键运营原则
### MEOW (Molecular Expression of Work)
将大目标分解为代理的详细指令。由 Beads、Epics、Formulas 和 Molecules 支持。MEOW 确保工作被分解为可跟踪的原子单元，代理可以自主执行。
### GUPP (Gas Town Universal Propulsion Principle)
> **“如果你的 Hook 上有工作，你必须执行它。”**
这一原则确保代理自主处理可用的工作，而无需等待外部输入。GUPP 是自主运行的心跳。
Gas Town 是一个蒸汽机。代理是活塞。整个系统的吞吐量取决于一件事：当代理在他们的 hook 上发现工作时，他们就会执行。
**为什么这很重要：** - 没有主管轮询询问“你开始了吗？” - Hook 就是你的任务——它是被有意放置在那里的 - 你等待的每一刻都是引擎停滞的时刻 - 其他代理可能会被阻塞，等待你的输出
### NDI (Nondeterministic Idempotence)
通过编排可能不可靠的过程来确保有用结果的总体目标。持久化的 Beads 和监督代理（Witness、Deacon）保证即使在单个操作可能失败或产生不同结果的情况下，工作流最终也能完成。
### 推进原则
所有 Gas Town 代理都遵循相同的核心原则：
> **如果你在 hook 上发现了东西，就执行它。**
无论角色如何，这都适用。Hook 就是你的任务。立即执行它，无需等待确认。Gas Town 是一个蒸汽机——代理是活塞。
**移交契约**：当你被生成时，工作已经为你 hook 好了。系统信任： 1. 你会在你的 hook 上找到它 2. 你会理解它是什么（`bd show` / `gt hook`） 3. 你会立即开始
**推进循环**： ``` 1. gt hook # What's hooked? 2. bd mol current # Where am I? 3. Execute step 4. bd close <step> --continue # Close and advance 5. GOTO 2 ```
**启动行为**： 1. 检查 hook（`gt hook`） 2. 有工作被 hook → 立即执行 3. Hook 为空 → 检查邮件中的附加工作 4. 任何地方都没有 → 错误：上报给 Witness
### 我们正在防止的失败模式
``` Polecat restarts with work on hook → Polecat announces itself → Polecat waits for confirmation → Witness assumes work is progressing → Nothing happens → Gas Town stops ```
### Molecule 导航：定位命令
```bash gt hook # What's on my hook? bd mol current # Where am I in the molecule? bd ready # What step is next? bd show <step-id> # What does this step require? ```
### 之前/之后：步骤转换
**旧工作流（有摩擦）：** ```bash # Finish step 3 bd close gt-abc.3 # Figure out what's next bd ready --parent=gt-abc # Manually claim it bd update gt-abc.4 --status=in_progress # Now finally work on it ```
三个命令。上下文切换。动量丢失。
**新工作流（推进）：** ```bash bd close gt-abc.3 --continue ```
一个命令。自动推进。保持动量。
---
## 架构概览
```mermaid graph TB Mayor[The Mayor<br/>AI Coordinator] Town[Town Workspace<br/>~/gt/]
Town --> Mayor Town --> Rig1[Rig: Project A] Town --> Rig2[Rig: Project B]
Rig1 --> Crew1[Crew Member<br/>Your workspace] Rig1 --> Hooks1[Hooks<br/>Persistent storage] Rig1 --> Polecats1[Polecats<br/>Worker agents]
Rig2 --> Crew2[Crew Member] Rig2 --> Hooks2[Hooks] Rig2 --> Polecats2[Polecats]
Hooks1 -.git worktree.-> GitRepo1[Git Repository] Hooks2 -.git worktree.-> GitRepo2[Git Repository] ```
### 目录结构
``` ~/gt/ Town root ├── .beads/ Town-level beads (hq-* prefix, mail) ├── mayor/ Mayor config │ ├── town.json Town configuration │ ├── CLAUDE.md Mayor context (on disk) │ └── .claude/settings.json Mayor Claude settings ├── deacon/ Deacon daemon │ ├── .claude/settings.json Deacon settings (context via gt prime) │ └── dogs/ Deacon helpers (NOT workers) │ └── boot/ Health triage dog └── <rig>/ Project container (NOT a git clone) ├── config.json Rig identity ├── .beads/ → mayor/rig/.beads (symlink or redirect) ├── .repo.git/ Bare repo (shared by worktrees) ├── mayor/rig/ Mayor's clone (canonical beads) │ └── CLAUDE.md Per-rig mayor context (on disk) ├── witness/ Witness agent home (monitors only) │ └── .claude/settings.json ├── refinery/ Refinery settings parent │ ├── .claude/settings.json │ └── rig/ Worktree on main │ └── CLAUDE.md Refinery context (on disk) ├── crew/ Crew settings parent (shared) │ ├── .claude/settings.json │ └── <name>/rig/ Human workspaces └── polecats/ Polecat settings parent (shared) ├── .claude/settings.json └── <name>/rig/ Worker worktrees ```
**关键点：** - Rig 根目录是一个容器，而不是克隆 - `.repo.git/` 是裸仓库——refinery 和 polecats 是工作树 - 每个 rig 的 `mayor/rig/` 保存规范化的 `.beads/`，其他目录通过重定向继承 - 设置放置在父目录中（而不是 git 克隆）以便向上遍历
### Beads 路由
Gas Town 根据问题 ID 前缀路由 beads 命令。你不需要考虑使用哪个数据库——只需使用问题 ID。
```bash bd show gp-xyz # Routes to greenplace rig's beads bd show hq-abc # Routes to town-level beads bd show wyv-123 # Routes to wyvern rig's beads ```
**工作原理**：路由在 `~/gt/.beads/routes.jsonl` 中定义。每个 rig 的前缀映射到其 beads 位置（该 rig 中 mayor 的克隆）。
| 前缀 | 路由到 | 目的 | |--------|-----------|---------| | `hq-*` | `~/gt/.beads/` | Mayor 邮件、跨 rig 协调 | | `gp-*` | `~/gt/greenplace/mayor/rig/.beads/` | Greenplace 项目问题 | | `wyv-*` | `~/gt/wyvern/mayor/rig/.beads/` | Wyvern 项目问题 |
调试路由：`BD_DEBUG_ROUTING=1 bd show <id>`
### 代理工作目录
每个代理在特定的工作目录中运行：
| 角色 | 工作目录 | 备注 | |------|-------------------|-------| | **Mayor** | `~/gt/mayor/` | 镇级协调员，与 rigs 隔离 | | **Deacon** | `~/gt/deacon/` | 后台监督守护进程 | | **Witness** | `~/gt/<rig>/witness/` | 没有 git 克隆，仅监控 polecats | | **Refinery** | `~/gt/<rig>/refinery/rig/` | 主分支上的工作树 | | **Crew** | `~/gt/<rig>/crew/<name>/rig/` | 持久化的人类工作区克隆 | | **Polecat** | `~/gt/<rig>/polecats/<name>/rig/` | 临时工作器工作树 |
### CLAUDE.md 位置
角色上下文通过 CLAUDE.md 文件或临时注入传递：
| 角色 | CLAUDE.md 位置 | 方法 | |------|-------------------|--------| | **Mayor** | `~/gt/mayor/CLAUDE.md` | 在磁盘上 | | **Deacon** | (无) | 在 SessionStart 时通过 `gt prime` 注入 | | **Witness** | (无) | 在 SessionStart 时通过 `gt prime` 注入 | | **Refinery** | `<rig>/refinery/rig/CLAUDE.md` | 在磁盘上（在工作树内部） | | **Crew** | (无) | 在 SessionStart 时通过 `gt prime` 注入 | | **Polecat** | (无) | 在 SessionStart 时通过 `gt prime` 注入 |
**为什么临时注入？** 将 CLAUDE.md 写入 git 克隆会在代理提交/推送时污染源代码仓库，将 Gas Town 内部信息泄露到项目历史记录中，并与特定于项目的 CLAUDE.md 文件冲突。
### 设置模板
Gas Town 根据角色类型使用两种设置模板：
| 类型 | 角色 | 关键区别 | |------|-------|----------------| | **交互式** | Mayor, Crew | 邮件在 `UserPromptSubmit` hook 上注入 | | **自主式** | Polecat, Witness, Refinery, Deacon | 邮件在 `SessionStart` hook 上注入 |
自主代理可以在没有用户输入的情况下启动，因此它们需要在会话开始时检查邮件。交互式代理等待用户提示。
---
## 角色分类
Gas Town 有几种代理类型，每种都有不同的职责和生命周期。
### 基础设施角色
这些角色管理 Gas Town 系统本身：
| 角色 | 描述 | 生命周期 | |------|-------------|-----------| | **Mayor** | mayor/ 处的全局协调员 | 单例，持久化 | | **Deacon** | 后台监督守护进程 | | **Witness** | 每个 rig 的 polecat 生命周期管理器 | 每个 rig 一个，持久化 | | **Refinery** | 每个 rig 的合并队列处理器 | 每个 rig 一个，持久化 |
### 工作器角色
这些角色执行实际的项目工作：
| 角色 | 描述 | 生命周期 | |------|-------------|-----------| | **Polecat** | 具有自己工作树的临时工作器 | 临时，Witness 管理 | | **Crew** | 具有自己克隆的持久化工作器 | 长期存在，用户管理 | | **Dog** | Deacon 的基础设施任务助手 | 临时，Deacon 管理 |
### 项目角色摘要
| 角色 | 描述 | 主要接口 | | --------------- | ------------------ | -------------------- | | **Mayor** | AI 协调员 | `gt mayor attach` | | **Human (You)** | Crew 成员 | 你的 crew 目录 | | **Polecat** | 工作器代理 | 由 Mayor 生成 | | **Hook** | 持久化存储 | Git 工作树 | | **Convoy** | 工作跟踪器 | `gt convoy` 命令 |
### The Mayor
你的主要 AI 协调员。Mayor 是一个 Claude Code 实例，拥有关于你的工作区、项目和代理的完整上下文。**从这里开始**——只需告诉 Mayor 你想要完成什么。
### The Deacon
运行连续巡逻周期的守护信标。Deacon 确保工作器活动，监控系统健康状况，并在代理无响应时触发恢复。可以将 Deacon 视为系统的看门狗。
### The Witness
负责监管 Rig 内 Polecats 和 Refinery 的巡逻代理。Witness 监控进度，检测卡住的代理，并可触发恢复操作。
### The Refinery
管理 Rig 的合并队列。Refinery 智能地合并来自 Polecats 的变更，处理冲突，并确保在变更进入主分支之前代码质量符合要求。
### Dogs
Deacon 的维护代理团队，负责清理、健康检查和系统维护等后台任务。Dogs 是 Deacon 用于系统级任务的助手，而非工作者。
**重要提示**: Dogs **不是**工作者。这是一个常见的误解。
| 方面 | Dogs | Crew | |--------|------|------| | **所有者** | Deacon | 人类 | | **目的** | 基础设施任务 | 项目工作 | | **范围** | 窄而专注的工具 | 通用型 | | **生命周期** | 非常短（单一任务） | 长期存活 | | **示例** | Boot（对 Deacon 健康进行分诊） | Joe（修复 bug，添加功能） |
### Boot (the Dog)
一个特殊的 Dog，每 5 分钟检查一次 Deacon，确保看门狗本身仍在监视。这建立了一个问责链条。
### Crew vs Polecats
两者都做项目工作，但有关键区别：
| 方面 | Crew | Polecat | |--------|------|---------| | **生命周期** | 持久（用户控制） | 瞬态（Witness 控制） | | **监控** | 无 | Witness 监视、督促、回收 | | **工作分配** | 人类指派或自指派 | 通过 `gt sling` 分配 | | **Git 状态** | 直接推送到 main | 在分支上工作，Refinery 合并 | | **清理** | 手动 | 完成后自动 | | **身份** | `<rig>/crew/<name>` | `<rig>/polecats/<name>` |
**何时使用 Crew**： - 探索性工作 - 长期项目 - 需要人类判断的工作 - 你希望直接控制的任务
**何时使用 Polecats**： - 离散、定义明确的任务 - 批量工作（通过 convoys 跟踪） - 可并行化的工作 - 受益于监督的工作
---
## 核心概念
### Town
管理总部（例如 `~/gt/`）。Town 协调多个 Rig 中的所有工作者，并容纳 Mayor 和 Deacon 等镇级代理。
### Rig
受 Gas Town 管理的特定项目 Git 仓库。每个 Rig 拥有自己的 Polecats、Refinery、Witness 和 Crew 成员。Rig 是实际开发工作发生的地方。
### Hooks
基于 Git worktree 的代理工作持久化存储。在崩溃和重启后依然存活。每个代理的一个特殊的 pinned Bead。Hook 是代理的主要工作队列——当工作出现在你的 Hook 上时，GUPP 规定你必须运行它。
### Bead
以 JSONL 格式存储的、由 Git 支持的原子工作单元。Beads 是 Gas Town 中工作跟踪的基本单元。它们可以代表 issues、任务、epics 或任何可跟踪的工作项。
**Bead IDs**（也称为 **issue IDs**）使用前缀 + 5 个字符的字母数字格式（例如 `gt-abc12`、`hq-x7k2m`）。前缀指示项目的来源或 rig。`gt sling` 和 `gt convoy` 等命令接受这些 ID 以引用特定的工作项。
### Convoy
工作跟踪单元。打包分配给代理的多个 beads。**Convoy** 是你在 Gas Town 中跟踪批量工作的方式。当你启动工作时——即使是一个单独的 issue——也要创建一个 convoy 来跟踪它。
### Formula
基于 TOML 的工作流源模板。Formulas 为常见操作（如巡逻周期、代码审查或部署）定义可重用的模式。
### Protomolecule
用于实例化 Molecules 的模板类。Protomolecules 定义工作流的结构和步骤，而不绑定到特定的工作项。
### Molecule
持久的链式 Bead 工作流。Molecules 代表多步骤过程，其中每个步骤都作为一个 Bead 被跟踪。它们在代理重启后依然存在，并确保复杂工作流完成。
### Wisp
运行后被销毁的瞬态 Beads。Wisps 是用于不需要永久跟踪的瞬态操作的轻量级工作项。
### Slinging
通过 `gt sling` 将工作分配给代理。当你将工作 slinging 给 Polecat 或 Crew 成员时，你是把它放在他们的 Hook 上以供执行。
### Nudging
使用 `gt nudge` 在代理之间进行实时消息传递。Nudges 允许立即通信，而无需经过邮件系统。
### Handoff
通过 `/handoff` 刷新代理会话。当上下文已满或代理需要全新开始时，handoff 将工作状态转移到新会话。
### Seance
通过 `gt seance` 与之前的会话通信。允许代理查询其前代以获取早期工作的上下文和决策。
### Patrol
维持系统心跳的瞬态循环。Patrol 代理（Deacon、Witness）持续循环进行健康检查并根据需要触发操作。
---
## 安装与设置
### 前置条件
#### 必需
| 工具 | 版本 | 检查 | 安装 | |------|---------|-------|---------| | **Go** | 1.24+ | `go version` | 见 [golang.org](https://go.dev/doc/install) | | **Git** | 2.20+ | `git --version` | 见下文 | | **Beads** | latest | `bd version` | `go install github.com/steveyegge/beads/cmd/bd@latest` | | **sqlite3** | - | - | 用于 convoy 数据库查询（通常预装） |
#### 可选（用于 Full Stack Mode）
| 工具 | 版本 | 检查 | 安装 | |------|---------|-------|---------| | **tmux** | 3.0+ | `tmux -V` | 见下文 | | **Claude Code CLI**（默认） | latest | `claude --version` | [claude.ai/claude-code](https://claude.ai/claude-code) | | **Codex CLI**（可选） | latest | `codex --version` | [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli) | | **OpenCode CLI**（可选） | latest | `opencode --version` | [opencode.ai](https://opencode.ai) |
### 设置
```bash # Install Gas Town $ brew install gastown # Homebrew (recommended) $ npm install -g @gastown/gt # npm $ go install github.com/steveyegge/gastown/cmd/gt@latest # From source
# If using go install, add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc) export PATH="$PATH:$HOME/go/bin"
# Create workspace with git initialization gt install ~/gt --git cd ~/gt
# Add your first project gt rig add myproject https://github.com/you/repo.git
# Create your crew workspace gt crew add yourname --rig myproject cd myproject/crew/yourname
# Start the Mayor session (your main interface) gt mayor attach ```
### macOS 安装
```bash # Install Homebrew if needed /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Required brew install go git
# Optional (for full stack mode) brew install tmux ```
### Linux (Debian/Ubuntu) 安装
```bash # Required sudo apt update sudo apt install -y git
# Install Go (apt version may be outdated, use official installer) wget https://go.dev/dl/go1.24.12.linux-amd64.tar.gz sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.12.linux-amd64.tar.gz echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc source ~/.bashrc
# Optional (for full stack mode) sudo apt install -y tmux ```
### Linux (Fedora/RHEL) 安装
```bash # Required sudo dnf install -y git golang
# Optional sudo dnf install -y tmux ```
### Minimal Mode vs Full Stack Mode
Gas Town 支持两种操作模式：
**Minimal Mode（无守护进程）**：手动运行单个运行时实例。Gas Town 仅跟踪状态。
```bash gt convoy create "Fix bugs" gt-abc12 gt sling gt-abc12 myproject cd ~/gt/myproject/polecats/<worker> claude --resume # Or: codex gt convoy list ```
**何时使用**：测试、简单工作流，或者当你更喜欢手动控制时。
**Full Stack Mode（带守护进程）**：代理在 tmux 会话中运行。守护进程自动管理生命周期。
```bash gt daemon start gt convoy create "Feature X" gt-abc12 gt-def34 gt sling gt-abc12 myproject gt mayor attach gt convoy list ```
**何时使用**：具有多个并发代理的生产工作流。
### 选择角色
Gas Town 是模块化的。仅启用你需要的内容：
| 配置 | 角色 | 用例 | |--------------|-------|----------| | **仅 Polecats** | 工作者 | 手动生成，无监控 | | **+ Witness** | + 监控器 | 自动生命周期，卡住检测 | | **+ Refinery** | + 合并队列 | MR 审查，代码集成 | | **+ Mayor** | + 协调器 | 跨项目协调 |
### 分步工作区设置
```bash # 1. Install the binaries go install github.com/steveyegge/gastown/cmd/gt@latest go install github.com/steveyegge/beads/cmd/bd@latest gt version bd version
# 2. Create your workspace gt install ~/gt --shell
# 3. Add a project gt rig add myproject https://github.com/you/repo.git
# 4. Verify installation cd ~/gt gt enable # enable Gas Town system-wide gt git-init # initialize a git repo for your HQ gt up # Start all services gt doctor # Run health checks gt status # Show workspace status ```
---
## 快速入门指南
### 入门
```shell gt install ~/gt --git && cd ~/gt && gt config agent list && gt mayor attach ```
然后告诉 Mayor 你想构建什么！
### 基本工作流
```mermaid sequenceDiagram participant You participant Mayor participant Convoy participant Agent participant Hook
You->>Mayor: Tell Mayor what to build Mayor->>Convoy: Create convoy with beads Mayor->>Agent: Sling bead to agent Agent->>Hook: Store work state Agent->>Agent: Complete work Agent->>Convoy: Report completion Mayor->>You: Summary of progress ```
### 示例：功能开发
```bash # 1. Start the Mayor gt mayor attach
# 2. In Mayor session, create a convoy with bead IDs gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human
# 3. Assign work to an agent gt sling gt-abc12 myproject
# 4. Track progress gt convoy list
# 5. Monitor agents gt agents ```
---
## 常见工作流
### Mayor 工作流（推荐）
**最适合用于**：协调复杂的、多 issue 的工作
```mermaid flowchart LR Start([Start Mayor]) --> Tell[Tell Mayor<br/>what to build] Tell --> Creates[Mayor creates<br/>convoy + agents] Creates --> Monitor[Monitor progress<br/>via convoy list] Monitor --> Done{All done?} Done -->|No| Monitor Done -->|Yes| Review[Review work] ```
**命令：** ```bash # Attach to Mayor gt mayor attach
# In Mayor, create convoy and let it orchestrate gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify
# Track progress gt convoy list ```
### Minimal Mode（无 Tmux）
手动运行单个运行时实例。Gas Town 仅跟踪状态。
```bash gt convoy create "Fix bugs" gt-abc12 # Create convoy gt sling gt-abc12 myproject # Assign to worker claude --resume # Agent reads mail, runs work (Claude) # or: codex # Start Codex in the workspace gt convoy list # Check progress ```
### Beads Formula 工作流
**最适合用于**：预定义的、可重复的过程
Formulas 是存储在 `.beads/formulas/` 中的、由 TOML 定义的工作流。
**示例 Formula** (`.beads/formulas/release.formula.toml`)：
```toml description = "Standard release process" formula = "release" version = 1
[vars.version] description = "The semantic version to release (e.g., 1.2.0)" required = true
[[steps]] id = "bump-version" title = "Bump version" description = "Run ./scripts/bump-version.sh {{version}}"
[[steps]] id = "run-tests" title = "Run tests" description = "Run make test" needs = ["bump-version"]
[[steps]] id = "build" title = "Build" description = "Run make build" needs = ["run-tests"]
[[steps]] id = "create-tag" title = "Create release tag" description = "Run git tag -a v{{version}} -m 'Release v{{version}}'" needs = ["build"]
[[steps]] id = "publish" title = "Publish" description = "Run ./scripts/publish.sh" needs = ["create-tag"] ```
**执行：** ```bash bd formula list # List available formulas bd cook release --var version=1.2.0 # Execute formula bd mol pour release --var version=1.2.0 # Create trackable instance ```
### 手动 Convoy 工作流
**最适合用于**：对工作分配的直接控制
```bash # Create convoy manually gt convoy create "Bug Fixes" --human
# Add issues to existing convoy gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x
# Assign to specific agents gt sling gt-m3k9p myproject/my-agent
# Check status gt convoy show ```
### MEOW (Mayor-Enhanced Orchestration Workflow)
MEOW 是推荐的模式：
1. **告诉 Mayor** - 描述你想要什么 2. **Mayor 分析** - 分解为任务 3. **Convoy 创建** - Mayor 创建带有 beads 的 convoy 4. **Agent 生成** - Mayor 生成合适的代理 5. **工作分配** - Beads 通过 hooks slung 给代理 6. **进度监控** - 通过 convoy 状态跟踪 7. **完成** - Mayor 总结结果
---
## 关键命令参考
### Town 管理
```bash gt install [path] # Create town gt install --git # With git init gt doctor # Health check gt doctor --fix # Auto-repair ```
### 配置
```bash # Agent management gt config agent list [--json] # List all agents (built-in + custom) gt config agent get <name> # Show agent configuration gt config agent set <name> <cmd> # Create or update custom agent gt config agent remove <name> # Remove custom agent (built-ins protected)
# Default agent gt config default-agent [name] # Get or set town default agent ```
**内置代理**：`claude`、`gemini`、`codex`、`cursor`、`auggie`、`amp`
**自定义代理**： ```bash gt config agent set claude-glm "claude-glm --model glm-4" gt config agent set claude "claude-opus" # Override built-in gt config default-agent claude-glm # Set default ```
### Rig 管理
```bash gt rig add <name> <url> gt rig list gt rig remove <name> ```
### Convoy 管理（主仪表板）
```bash gt convoy list # Dashboard of active convoys gt convoy status [convoy-id] # Show progress gt convoy create <name> [issues...] # Create convoy tracking issues gt convoy create "name" gt-a bd-b --notify mayor/ # With notification gt convoy list --all # Include landed convoys gt convoy list --status=closed # Only landed convoys ```
### 工作分配
```bash gt sling <bead> <rig> # Assign to polecat gt sling <bead> <rig> --agent codex # Override runtime gt sling <proto> --on gt-def <rig> # With workflow template ```
### 代理操作
```bash gt agents # List active agents gt mayor attach # Start Mayor session gt mayor start --agent auggie # Run Mayor with specific agent gt prime # Context recovery (run inside session) ```
### 通信
```bash gt mail inbox gt mail read <id> gt mail send <addr> -s "Subject" -m "Body" gt mail send --human -s "..." # To overseer ```
### 升级处理
```bash gt escalate "topic" # Default: MEDIUM severity gt escalate -s CRITICAL "msg" # Urgent, immediate attention gt escalate -s HIGH "msg" # Important blocker gt escalate -s MEDIUM "msg" -m "Details..." ```
### 会话
```bash gt handoff # Request cycle (context-aware) gt handoff --shutdown # Terminate (polecats) gt session stop <rig>/<agent> gt peek <agent> # Check health gt nudge <agent> "message" # Send message to agent gt seance # List discoverable predecessor sessions gt seance --talk <id> # Talk to predecessor (full context) ```
**重要提示**：始终使用 `gt nudge` 向 Claude 会话发送消息。切勿使用原始的 `tmux send-keys`——它无法正确处理 Claude 的输入。
### 紧急情况
```bash gt stop --all # Kill all sessions gt stop --rig <name> # Kill rig sessions ```
### 合并队列 (MQ)
```bash gt mq list [rig] # Show the merge queue gt mq next [rig] # Show highest-priority merge request gt mq submit # Submit current branch to merge queue gt mq status <id> # Show detailed merge request status gt mq retry <id> # Retry a failed merge request gt mq reject <id> # Reject a merge request ```
### Beads 命令 (bd)
```bash bd ready # Work with no blockers bd list --status=open bd list --status=in_progress bd show <id> bd create --title="..." --type=task bd update <id> --status=in_progress bd close <id> bd dep add <child> <parent> # child depends on parent ```
---
## 代理身份与归属
### 为什么身份很重要
当你大规模部署 AI 代理时，匿名工作会带来真正的问题：
- **调试**：“AI 搞坏了它”是可执行的。*哪个* AI？ - **质量跟踪**：你无法改进你无法衡量的东西。 - **合规性**：审计员会问“谁批准了这段代码？”——你需要一个答案。 - **绩效管理**：某些代理在特定任务上比其他代理表现得更好。
### BD_ACTOR 格式约定
`BD_ACTOR` 环境变量以斜杠分隔的路径格式标识代理：
| 角色类型 | 格式 | 示例 | |-----------|--------|---------| | **Mayor** | `mayor` | `mayor` | | **Deacon** | `deacon` | `deacon` | | **Witness** | `{rig}/witness` | `gastown/witness` | | **Refinery** | `{rig}/refinery` | `gastown/refinery` | | **Crew** | `{rig}/crew/{name}` | `gastown/crew/joe` | | **Polecat** | `{rig}/polecats/{name}` | `gastown/polecats/toast` |
### 归属模型
Gas Town 使用三个字段来实现完整的溯源：
**Git 提交：** ```bash GIT_AUTHOR_NAME="gastown/crew/joe" # Who did the work (agent) GIT_AUTHOR_EMAIL="[email protected]" # Who owns the work (overseer) ```
**Beads 记录：** ```json { "id": "gt-xyz", "created_by": "gastown/crew/joe", "updated_by": "gastown/witness" } ```
**事件日志：** ```json { "ts": "2025-01-15T10:30:00Z", "type": "sling", "actor": "gastown/crew/joe", "payload": { "bead": "gt-xyz", "target": "gastown/polecats/toast" } } ```
### 环境变量
#### 核心变量（所有代理）
| 变量 | 用途 | 示例 | |----------|---------|---------| | `GT_ROLE` | 代理角色类型 | `mayor`, `witness`, `polecat`, `crew` | | `GT_ROOT` | 镇（Town）根目录 | `/home/user/gt` | | `BD_ACTOR` | 用于归因的代理身份 | `gastown/polecats/toast` | | `GIT_AUTHOR_NAME` | 提交归因（同 BD_ACTOR） | `gastown/polecats/toast` | | `BEADS_DIR` | Beads 数据库位置 | `/home/user/gt/gastown/.beads` |
#### Rig 级变量
| 变量 | 用途 | 角色 | |----------|---------|-------| | `GT_RIG` | Rig 名称 | witness, refinery, polecat, crew | | `GT_POLECAT` | Polecat 工作节点名称 | 仅 polecat | | `GT_CREW` | Crew 工作节点名称 | 仅 crew | | `BEADS_AGENT_NAME` | 用于 beads 操作的代理名称 | polecat, crew | | `BEADS_NO_DAEMON` | 禁用 beads 守护进程（隔离上下文） | polecat, crew |
#### 其他变量
| 变量 | 用途 | |----------|---------| | `GIT_AUTHOR_EMAIL` | 工作区所有者邮箱（来自 git 配置） | | `GT_TOWN_ROOT` | 覆盖 town 根目录检测（手动使用） | | `CLAUDE_RUNTIME_CONFIG_DIR` | 自定义 Claude 设置目录 |
#### 按角色划分的环境变量
| 角色 | 关键变量 | |------|---------------| | **Mayor** | `GT_ROLE=mayor`, `BD_ACTOR=mayor` | | **Deacon** | `GT_ROLE=deacon`, `BD_ACTOR=deacon` | | **Boot** | `GT_ROLE=boot`, `BD_ACTOR=deacon-boot` | | **Witness** | `GT_ROLE=witness`, `GT_RIG=<rig>`, `BD_ACTOR=<rig>/witness` | | **Refinery** | `GT_ROLE=refinery`, `GT_RIG=<rig>`, `BD_ACTOR=<rig>/refinery` | | **Polecat** | `GT_ROLE=polecat`, `GT_RIG=<rig>`, `GT_POLECAT=<name>`, `BD_ACTOR=<rig>/polecats/<name>` | | **Crew** | `GT_ROLE=crew`, `GT_RIG=<rig>`, `GT_CREW=<name>`, `BD_ACTOR=<rig>/crew/<name>` |
### 能力账本
每一次完成都会被记录。每一次交接都会被日志记录。你关闭的每一个 bead 都将成为已证实能力的永久账本的一部分。
- 你的工作是可见的 - 赎回是真实的（持续的良好工作会随时间积累） - 每一次完成都是自主执行有效的证据 - 你的履历随着每一次完成而增长
---
## Polecat 生命周期
### 三层架构
Polecats 有三个独立运行的生命周期层：
| 层 | 组件 | 生命周期 | 持久性 | |-------|-----------|-----------|-------------| | **Session（会话）** | Claude (tmux 窗格) | 临时 | 每步/交接时循环 | | **Sandbox（沙箱）** | Git worktree | 持久 | 直到被 nuke（清除） | | **Slot（槽位）** | 来自池的名称 | 持久 | 直到被 nuke（清除） |
### 三种运行状态
Polecats 只有三种运行状态。**没有空闲池**。
| 状态 | 描述 | 触发方式 | |-------|-------------|----------------| | **Working（工作中）** | 正在执行分配的任务 | 正常运行 | | **Stalled（停滞）** | 会话在工作中途停止 | 被中断、崩溃或超时 | | **Zombie（僵尸）** | 已完成工作但未能退出 | `gt done` 在清理期间失败 |
**关键区别：**僵尸完成了它们的工作；停滞的 polecats 则没有。
### 自清理 Polecat 模型
**Polecats 负责自身的清理。**当一个 polecat 完成时：
1. 通过 `gt done` 发出完成信号 2. 立即退出其会话（无空闲等待） 3. 请求自身的 nuke（自删除）
### 正确的生命周期
``` ┌─────────────────────────────────────────────────────────────┐ │ gt sling │ │ → Allocate slot from pool (Toast) │ │ → Create sandbox (worktree on new branch) │ │ → Start session (Claude in tmux) │ │ → Hook molecule to polecat │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Work Happens │ │ │ │ Session cycles happen here: │ │ - gt handoff between steps │ │ - Compaction triggers respawn │ │ - Crash → Witness respawns │ │ │ │ Sandbox persists through ALL session cycles │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ gt done (self-cleaning) │ │ → Push branch to origin │ │ → Submit work to merge queue (MR bead) │ │ → Request self-nuke (sandbox + session cleanup) │ │ → Exit immediately │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Refinery: merge queue │ │ → Rebase and merge to main │ │ → Close the issue │ │ → If conflict: spawn FRESH polecat to re-implement │ └─────────────────────────────────────────────────────────────┘ ```
### 会话循环
会话因以下原因循环：
| 触发器 | 操作 | 结果 | |---------|--------|--------| | `gt handoff` | 自愿 | 清理循环以刷新上下文 | | 上下文压缩 | 自动 | 由 Claude Code 强制执行 | | 崩溃/超时 | 失败 | Witness 重启 | | `gt done` | 完成 | 会话退出，Witness 接管 |
### Polecat 身份
Polecat *身份* 是长久的；只有会话和沙箱是临时的。polecat *名称*（Toast, Shadow 等）是来自池的槽位——真正临时的。但*代理身份*会积累工作历史。
### Polecat 分支命名
配置自定义分支名称模板：
```bash # Template Variables {user} # From git config user.name {year} # Current year (YY format) {month} # Current month (MM format) {name} # Polecat name {issue} # Issue ID without prefix {description}# Sanitized issue title {timestamp} # Unique timestamp ```
**默认行为（向后兼容）：** - 带有 issue：`polecat/{name}/{issue}@{timestamp}` - 不带 issue：`polecat/{name}-{timestamp}`
### 反模式
**“空闲” Polecats（它们不存在）**
没有空闲状态。没有工作 polecats 就不存在： 1. 分配工作 → 生成 polecat 2. 工作完成 → `gt done` → 会话退出 → polecat 被 nuke 3. 没有第 3 步让它们等待
如果你看到一个非工作的 polecat，它处于**失败状态**：
| 你看到的 | 实际状态 | 出了什么问题 | |--------------|------------|-----------------| | 会话存在但未工作 | **停滞** | 被中断/崩溃，从未被推动 | | 会话完成但未退出 | **僵尸** | `gt done` 在清理期间失败 |
**手动状态转换（反模式）：** ```bash gt polecat done Toast # DON'T: external state manipulation gt polecat reset Toast # DON'T: manual lifecycle control ```
**正确：** ```bash # Polecat signals its own completion: gt done # (from inside the polecat session)
# Only Witness nukes polecats: gt polecat nuke Toast # (from Witness, after verification) ```
### Witness 职责
Witness **不**： - 强制会话循环（polecats 通过交接自我管理） - 中途中断步骤（除非真的卡住） - Nuke polecats（polecats 通过 `gt done` 自我 nuke）
Witness **会**： - 检测并推动停滞的 polecats - 清理僵尸 polecats - 重启崩溃的会话 - 处理来自卡住 polecats 的升级请求
---
## Molecules（分子）与 Formulas（配方）
### Molecule 生命周期
``` Formula (source TOML) ─── "Ice-9" │ ▼ bd cook Protomolecule (frozen template) ─── Solid │ ├─▶ bd mol pour ──▶ Mol (persistent) ─── Liquid ──▶ bd squash ──▶ Digest │ └─▶ bd mol wisp ──▶ Wisp (ephemeral) ─── Vapor ──┬▶ bd squash ──▶ Digest └▶ bd burn ──▶ (gone) ```
### 核心概念
| 术语 | 描述 | |------|-------------| | **Formula（配方）** | 定义工作流步骤的源 TOML 模板 | | **Protomolecule（原分子）** | 准备好实例化的冻结模板 | | **Molecule（分子）** | 具有可跟踪步骤的活动工作流实例 | | **Wisp（微光）** | 用于巡逻循环的临时分子（永不同步） | | **Digest（摘要）** | 已完成分子的压缩摘要 | | **Shiny Workflow（光鲜工作流）** | 规范的 polecat 配方：设计 → 实现 → 审查 → 测试 → 提交 |
### 导航 Molecules
```bash bd mol current # Where am I? bd mol current gt-abc # Status of specific molecule ```
**无缝过渡：** ```bash bd close gt-abc.3 --continue # Close and advance to next step ```
### Molecule 命令
**Beads 操作：** ```bash bd formula list # Available formulas bd formula show <name> # Formula details bd cook <formula> # Formula → Proto bd mol list # Available protos bd mol show <id> # Proto details bd mol pour <proto> # Create mol bd mol wisp <proto> # Create wisp bd mol bond <proto> <parent> # Attach to existing mol bd mol squash <id> # Condense to digest bd mol burn <id> # Discard wisp bd mol current # Where am I? ```
**Agent 操作：** ```bash gt hook # What's on MY hook gt mol current # What should I work on next gt mol progress <id> # Execution progress gt mol attach <bead> <mol> # Pin molecule to bead gt mol detach <bead> # Unpin molecule gt mol burn # Burn attached molecule gt mol squash # Squash attached molecule gt mol step done <step> # Complete a molecule step ```
### 常见错误：直接读取 Formulas
**错误：** ```bash cat .beads/formulas/mol-polecat-work.formula.toml bd create --title "Step 1: Load context" --type task ```
**正确：** ```bash bd cook mol-polecat-work bd mol pour mol-polecat-work --var issue=gt-xyz bd ready # Find next step bd close <step-id> # Complete it ```
### Polecat 工作流
Polecats 通过它们的 hook 接收工作——一个附加到 issue 的固定分子。
**Polecats 的分子类型：**
| 类型 | 存储 | 用例 | |------|---------|----------| | **常规分子** | `.beads/` (已同步) | 离散交付物，审计跟踪 | | **微光** | `.beads/` (临时) | 巡逻循环，操作循环 |
**Hook 管理：** ```bash gt hook # What's on MY hook? gt mol attach-from-mail <id> # Attach work from mail message gt done # Signal completion (syncs, submits to MQ, notifies Witness) ```
**Polecat 工作流摘要：** ``` 1. Spawn with work on hook 2. gt hook # What's hooked? 3. bd mol current # Where am I? 4. Execute current step 5. bd close <step> --continue 6. If more steps: GOTO 3 7. gt done # Signal completion ```
### 微光 vs 分子 决策
| 问题 | 分子 | 微光 | |----------|----------|------| | 需要审计跟踪吗？ | 是 | 否 | | 会持续重复吗？ | 否 | 是 | | 是离散交付物吗？ | 是 | 否 | | 是操作例程吗？ | 否 | 是 |
### 最佳实践
1. **关键：实时关闭步骤** - 在开始**之前**标记 `in_progress`，在完成后**立即**标记 `closed`。永远不要在最后批量关闭步骤。 2. **使用 `--continue` 推进** - 通过自动推进保持势头 3. **使用 `bd mol current` 检查进度** - 在恢复之前知道你在哪里 4. **压缩已完成的分子** - 创建摘要以进行审计跟踪 5. **销毁常规微光** - 不要累积临时巡逻数据
### 配方解析（三层）
``` TIER 1: PROJECT (rig-level) Location: <project>/.beads/formulas/
TIER 2: TOWN (user-level) Location: ~/gt/.beads/formulas/
TIER 3: SYSTEM (embedded) Location: Compiled into gt binary ```
---
## Convoys - 工作跟踪
### 概念
**Convoy（护送队）**是一个持久跟踪单元，用于监控跨多个 rig 的相关 issue。当你启动工作时——即使是单个 issue——一个 convoy 也会对其进行跟踪。
``` 🚚 Convoy (hq-cv-abc) │ ┌────────────┼────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ gt-xyz │ │ gt-def │ │ bd-abc │ │ gastown │ │ gastown │ │ beads │ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ nux │ │ furiosa │ │ amber │ │(polecat)│ │(polecat)│ │(polecat)│ └─────────┘ └─────────┘ └─────────┘ │ "the swarm" (ephemeral) ```
### Convoy vs Swarm
| 概念 | 持久？ | ID | 描述 | |---------|-------------|-----|-------------| | **Convoy** | 是 | hq-cv-* | 跟踪单元。你创建、跟踪、接收通知的对象。 | | **Swarm** | 否 | 无 | 临时。“当前在此 convoy issue 上工作的工人。” | | **搁浅的 Convoy** | 是 | hq-cv-* | 有就绪工作但未分配 polecats 的 convoy。 |
### Convoy 生命周期
``` OPEN ──(all issues close)──► LANDED/CLOSED ↑ │ └──(add more issues)───────────┘ (auto-reopens) ```
| 状态 | 描述 | |-------|-------------| | `open` | 活跃跟踪，工作进行中 | | `closed` | 所有跟踪的 issue 已关闭，通知已发送 |
将 issue 添加到已关闭的 convoy 会自动重新打开它。
### 命令
```bash # Create convoy gt convoy create "Deploy v2.0" gt-abc bd-xyz --notify gastown/joe
# Check status gt convoy status hq-abc
# List all convoys gt convoy list gt convoy list --all
# Add issues bd dep add hq-cv-abc gt-new-issue --type=tracks ```
**示例 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] ```
### 通知
当 convoy 落地（完成）时，订阅者会收到通知： ```bash 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 ```
### 跨 Rig 跟踪
Convoys 存在于镇级 beads 中（`hq-cv-*` 前缀），可以跟踪来自任何 rig 的 issue：
```bash # Track issues from multiple rigs 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 vs Rig 状态
| 视图 | 范围 | 显示 | |------|-------|-------| | `gt convoy status [id]` | 跨 rig | Convoy 跟踪的 issue + 工人 | | `gt rig status <rig>` | 单个 rig | rig 中的所有工人 + 其 convoy 成员资格 |
使用 convoys 查询“这批工作的状态如何？” 使用 rig 状态查询“这个 rig 里的每个人都在做什么？”
### Sling 时的自动 Convoy
当你没有现有 convoy 而 sling 单个 issue 时，Gas Town 会自动创建一个以便仪表盘可见。
---
## 通信系统
### 邮件协议
Gas Town 代理通过通过 beads 系统路由的邮件消息进行协调。
**消息类型：**
| 类型 | 路由 | 用途 | |------|-------|---------| | `POLECAT_DONE` | Polecat → Witness | 发出工作完成信号 | | `MERGE_READY` | Witness → Refinery | 发出分支准备好合并的信号 | | `MERGED` | Refinery → Witness | 确认合并成功 | | `MERGE_FAILED` | Refinery → Witness | 通知合并失败 | | `REWORK_REQUEST` | Refinery → Witness | 请求因冲突进行 rebase | | `WITNESS_PING` | Witness → Deacon | 二级监控 | | `HELP` | 任何 → 升级目标 | 请求干预 | | `HANDOFF` | 代理 → 自身 | 会话连续性 |
**命令：** ```bash gt mail inbox gt mail read <msg-id> gt mail send <addr> -s "Subject" -m "Body" gt mail ack <msg-id> ```
**消息格式详情：**
**POLECAT_DONE** (Polecat → Witness): ``` Subject: POLECAT_DONE <polecat-name> Body: Exit: MERGED|ESCALATED|DEFERRED Issue: <issue-id> MR: <mr-id> # if exit=MERGED Branch: <branch> ```
**HANDOFF** (代理 → 自身): ``` Subject: 🤝 HANDOFF: <brief-context> Body: attached_molecule: <molecule-id> # if work in progress attached_at: <timestamp>
## Context <freeform notes for successor>
## Status <where things stand>
## Next <what successor should do> ```
### Beads 原生消息传递
用于管理通信的三种珠子类型：
- **群组** (`gt:group`) - 用于邮件分发的命名集合 - **队列** (`gt:queue`) - 工作队列，其中的消息可以被认领 - **频道** (`gt:channel`) - 发布/订阅广播流
```bash # Group management gt mail group create ops-team gastown/witness gastown/crew/max gt mail send ops-team -s "Team meeting" -m "Tomorrow at 10am"
# Channel management gt mail channel create alerts --retain-count=50 gt mail send channel:alerts -s "Build failed" -m "Details..." ```
### 升级协议
**严重程度级别：**
| 级别 | 优先级 | 描述 | |-------|----------|-------------| | **CRITICAL** | P0 | 威胁系统，需要立即关注 | | **HIGH** | P1 | 重要阻碍，需要人工尽快处理 | | **MEDIUM** | P2 | 标准升级 |
**升级类别：**
| 类别 | 描述 | 默认路由 | |----------|-------------|---------------| | `decision` | 存在多条有效路径，需要做出选择 | Deacon -> Mayor | | `help` | 需要指导或专业知识 | Deacon -> Mayor | | `blocked` | 等待无法解决的依赖 | Mayor | | `failed` | 意外错误，无法继续 | Deacon | | `emergency` | 安全或数据完整性问题 | Overseer (直接) | | `gate_timeout` | 闸门未及时解决 | Deacon | | `lifecycle` | Worker 卡住或需要回收 | Witness |
**命令：** ```bash gt escalate "Database migration failed" gt escalate -s CRITICAL "Data corruption detected" gt escalate --type decision "Which auth approach?" ```
### 移交技能
将当前会话移交给新的 Claude 实例，同时保留工作上下文。
**何时使用：** - 上下文已满（接近 token 限制） - 完成了一块逻辑工作 - 需要对问题有全新的视角 - 人类请求会话轮换
**用法：** ```bash /handoff [optional message] ```
**保留的内容：** - 挂载的分子：你的工作任务保留在你的 hook 上 - 珠子状态：所有问题、依赖项、进度 - Git 状态：提交、分支、暂存的更改
**重置的内容：** - 对话上下文：全新的 Claude 实例 - TodoWrite 项：临时的、会话范围的 - 内存状态：任何未提交的分析
---
## 看门狗链
### 概述
Gas Town 使用三层看门狗链进行自主健康监控：
``` Daemon (Go process) ← Dumb transport, 3-min heartbeat │ └─► Boot (AI agent) ← Intelligent triage, fresh each tick │ └─► Deacon (AI agent) ← Continuous patrol, long-running │ └─► Witnesses & Refineries ← Per-rig agents ```
**关键洞察**：守护进程是机械的（无法推理），但健康决策需要智能。Boot 弥合了这一差距。
### 会话所有权
| 代理 | 会话名称 | 位置 | 生命周期 | |-------|--------------|----------|-----------| | Daemon | (Go 进程) | `~/gt/daemon/` | 持久的，自动重启 | | Boot | `gt-boot` | `~/gt/deacon/dogs/boot/` | 临时的，每次 tick 都是新的 | | Deacon | `hq-deacon` | `~/gt/deacon/` | 长期运行的，移交循环 |
### Boot 决策矩阵
| 条件 | 操作 | |-----------|--------| | 会话已死 | START | | 心跳 > 15 分钟 | WAKE | | 心跳 5-15 分钟 + 邮件 | NUDGE | | 心跳正常 | NOTHING |
### 巡逻代理
| 代理 | 巡逻分子 | 职责 | |-------|-----------------|----------------| | **Deacon** | `mol-deacon-patrol` | 代理生命周期、插件执行、健康检查 | | **Witness** | `mol-witness-patrol` | 监控 polecats，推动卡住的 workers | | **Refinery** | `mol-refinery-patrol` | 处理合并队列，审查 MR |
### 健康检查命令
```bash gt deacon health-check <agent> # Send health check ping gt deacon health-state # Show health check state cat ~/gt/deacon/heartbeat.json | jq . # Check Deacon heartbeat gt boot triage # Manual Boot run ```
### 设计理念：为什么需要两个代理？
**问题**：守护进程需要确保 Deacon 是健康的，但是： 1. **守护进程无法推理** - 它是遵循 ZFC 原则的 Go 代码（不推测其他代理） 2. **唤醒会消耗上下文** - 每次生成 AI 代理时，都会消耗上下文 token 3. **观察需要智能** - 区分“代理正在编写大型构件”和“代理卡在工具提示上”需要推理能力
**解决方案**：Boot 是一个狭窄的、临时的 AI 代理，它： - 每次守护进程 tick 时全新运行（无累积的上下文债务） - 做出单一决策：Deacon 是否应该唤醒？ - 决定后立即退出
### 心跳机制
守护进程每 3 分钟运行一次心跳 tick：
```go func (d *Daemon) heartbeatTick() { d.ensureBootRunning() // 1. Spawn Boot for triage d.checkDeaconHeartbeat() // 2. Belt-and-suspenders fallback d.ensureWitnessesRunning() // 3. Witness health d.ensureRefineriesRunning() // 4. Refinery health d.triggerPendingSpawns() // 5. Bootstrap polecats d.processLifecycleRequests() // 6. Cycle/restart requests } ```
**心跳新鲜度：**
| 时长 | 状态 | Boot 操作 | |-----|-------|-------------| | < 5 分钟 | 新鲜 | 无操作（Deacon 活跃） | | 5-15 分钟 | 陈旧 | 如果有待处理邮件则推送 | | > 15 分钟 | 非常陈旧 | 唤醒（Deacon 可能卡住） |
### 状态文件
| 文件 | 用途 | 更新者 | |------|---------|-----------| | `deacon/heartbeat.json` | Deacon 新鲜度 | Deacon（每个周期） | | `deacon/dogs/boot/.boot-running` | Boot 进行中标记 | Boot 生成时 | | `deacon/dogs/boot/.boot-status.json` | Boot 上次操作 | Boot 分诊 | | `deacon/health-check-state.json` | 代理健康跟踪 | `gt deacon health-check` | | `daemon/daemon.log` | 守护进程活动 | 守护进程 | | `daemon/daemon.pid` | 守护进程进程 ID | 守护进程启动时 |
### 降级模式
当 tmux 不可用时，Gas Town 进入降级模式：
| 能力 | 正常 | 降级 | |------------|--------|----------| | Boot 运行 | 作为 tmux 中的 AI | 作为 Go 代码（机械） | | 观察窗格 | 是 | 否 | | 推送代理 | 是 | 否 | | 启动代理 | tmux 会话 | 直接生成 |
---
## 高级主题
### 运行时配置
Gas Town 支持多种 AI 编码运行时。每个机架的设置位于 `settings/config.json`：
```json { "runtime": { "provider": "codex", "command": "codex", "args": [], "prompt_mode": "none" } } ```
### 模型评估和 A/B 测试
Gas Town 的归因功能支持客观的模型比较：
```bash # Deploy different models on similar tasks gt sling gt-abc gastown --model=claude-sonnet gt sling gt-def gastown --model=gpt-4
# Compare outcomes bd stats --actor=gastown/polecats/* --group-by=model ```
### 跨机架工作模式
**选项 1：Worktrees（首选）** ```bash gt worktree beads # Creates ~/gt/beads/crew/gastown-joe/ ```
**选项 2：分派给本地 Workers** ```bash bd create --prefix beads "Fix authentication bug" gt convoy create "Auth fix" bd-xyz gt sling bd-xyz beads ```
### 稀疏检出（源码仓库隔离）
Gas Town 使用稀疏检出来排除 Claude Code 上下文文件： ```bash git sparse-checkout set --no-cone '/*' '!/.claude/' '!/CLAUDE.md' '!/CLAUDE.local.md' ```
### Mol Mall（未来）
Gas Town 公式的市场——就像分子界的 npm。
**URI 方案：** ``` hop://molmall.gastown.io/formulas/[email protected] ```
**命令（未来）：** ```bash gt formula install mol-code-review-strict gt formula upgrade mol-polecat-work gt formula publish mol-polecat-work ```
### 联邦
联邦通过 Highway Operations Protocol 支持跨组织共享公式。
### 仪表板
```bash gt dashboard --port 8080 open http://localhost:8080 ```
功能： - 实时代理状态 - 车队进度跟踪 - Hook 状态可视化 - 配置管理
### Shell 补全
```bash gt completion bash > /etc/bash_completion.d/gt gt completion zsh > "${fpath[1]}/_gt" gt completion fish > ~/.config/fish/completions/gt.fish ```
---
## 故障排除
### 常见问题
| 问题 | 解决方案 | |---------|----------| | 代理位于错误的目录 | 检查 cwd，`gt doctor` | | 珠子前缀不匹配 | 检查 `bd show` 与机架配置 | | Worktree 冲突 | 确保 polecats 设置 `BEADS_NO_DAEMON=1` | | Worker 卡住 | `gt nudge`，然后 `gt peek` | | Git 状态脏乱 | 提交或丢弃，然后 `gt handoff` | | `gt: command not found` | 将 `$HOME/go/bin` 添加到 PATH | | `bd: command not found` | `go install github.com/steveyegge/beads/cmd/bd@latest` | | 守护进程未启动 | 检查 tmux：`tmux -V` | | 代理失去连接 | `gt hooks list` 然后 `gt hooks repair` | | 车队卡住 | `gt convoy refresh <convoy-id>` | | Mayor 无响应 | `gt mayor detach` 然后 `gt mayor attach` |
### 健康检查
```bash gt doctor # Run health checks gt doctor --fix # Auto-repair common issues gt doctor --verbose # Detailed output gt status # Show workspace status ```
### 调试
```bash BD_DEBUG_ROUTING=1 bd show <id> # Debug beads routing gt peek <agent> # Check agent health tail -f ~/gt/daemon/daemon.log # View daemon log ```
### 常见错误
1. **使用 dogs 处理用户工作**：Dogs 是 Deacon 的基础设施。请使用 crew 或 polecats。 2. **混淆 crew 和 polecats**：Crew 是持久的且由人工管理。Polecats 是临时的。 3. **在错误的目录中工作**：Gas Town 使用 cwd 进行身份检测。 4. **工作已挂载时等待确认**：挂载就是你的任务分配。立即执行。 5. **当分派更合适时创建 worktrees**：如果工作应由目标机架拥有，请分派。 6. **直接阅读公式**：使用 `bd cook` → `bd mol pour` 流水线代替。 7. **批量关闭分子步骤**：实时关闭步骤以维护准确的时间线。
---
## 术语表
### 环境 - **Town**：管理总部（例如 `~/gt/`）。协调多个机架中的所有 workers。 - **Rig**：受 Gas Town 管理的特定于项目的 Git 仓库。
### Town 级角色 - **Mayor**：行政首长代理，负责发起车队并协调工作。 - **Deacon**：运行连续巡逻周期的守护进程信标，用于系统健康监控。 - **Dogs**：Deacon 的维护代理团队，负责后台任务。 - **Boot**：一种特殊的 Dog，每 5 分钟检查一次 Deacon。
### Rig 级角色 - **Polecat**：产生合并请求的临时 worker 代理。 - **Refinery**：管理机架的合并队列。 - **Witness**：监督 Polecats 和 Refinery 的巡逻代理。 - **Crew**：长期存在的、命名的代理，用于持久协作。
### 工作单元 - **Bead**：以 JSONL 格式存储的基于 Git 的原子工作单元。 - **Formula**：基于 TOML 的工作流源模板。 - **Protomolecule**：用于实例化 Molecules 的模板类。 - **Molecule**：持久的链式 Bead 工作流。 - **Wisp**：运行后销毁的临时 Beads。 - **Hook**：用于每个代理工作队列的特殊固定 Bead。
### 工作流命令 - **Convoy**：包装相关 Beads 的主要工单。 - **Slinging**：通过 `gt sling` 将工作分配给代理。 - **Nudging**：使用 `gt nudge` 在代理之间进行实时消息传递。 - **Handoff**：通过 `/handoff` 进行代理会话刷新。 - **Seance**：通过 `gt seance` 与以前的会话通信。 - **Patrol**：维持系统心跳的临时循环。
### 原则 - **MEOW**：Molecular Expression of Work - 将大目标分解为可跟踪的单元。 - **GUPP**：Gas Town Universal Propulsion Principle - “如果你的 Hook 上有工作，你必须运行它。” - **NDI**：Nondeterministic Idempotence - 通过编排确保有用的结果。
---
## Gas Town 存在的原因
随着 AI 代理成为工程工作流的核心，团队面临着新的挑战：
- **问责制**：谁做了什么？哪个代理引入了这个 Bug？ - **质量**：哪些代理是可靠的？哪些需要调整？ - **效率**：如何将工作路由到正确的代理？ - **规模**：如何在仓库和团队之间协调代理？
Gas Town 是一个编排层，将 AI 代理的工作视为结构化数据。每个操作都有归属。每个代理都有跟踪记录。每项工作都有来源证明。
### 功能：工作历史（代理简历）
**问题**：你想分配一个复杂的 Go 重构任务。你有 20 个代理。有些擅长 Go。有些从未接触过。有些不稳定。你如何选择？
**解决方案**：每个代理都会累积工作历史：
```bash # What has this agent done? bd audit --actor=gastown/polecats/toast
# Success rate on Go projects bd stats --actor=gastown/polecats/toast --tag=go ```
**重要性：** - **绩效管理：** 关于 Agent 可靠性的客观数据 - **能力匹配：** 将工作路由给经过验证的 Agent - **持续改进：** 识别表现不佳的 Agent 以进行调整
### 功能：基于能力的路由
**问题：** 你使用 Go、Python、TypeScript、Rust 进行开发。你拥有能力各异的 Agent。手动分配无法扩展。
**解决方案：** 工作带有技能要求。Agent 具有已证实的能力（源自其工作历史）。匹配是自动的：
```bash # Agent capabilities (derived from work history) bd skills gastown/polecats/toast # → go: 47 tasks, python: 12 tasks, typescript: 3 tasks
# Route based on fit gt dispatch gt-xyz --prefer-skill=go ```
**重要性：** - **效率：** 为正确的任务分配合适的 Agent - **质量：** Agent 在其优势领域工作 - **扩展：** 分配环节无人工瓶颈
### 功能：递归式工作分解
**问题：** 企业级项目很复杂。一个“功能”会变成跨越 8 个代码库、涉及 4 个团队的 50 个任务。扁平的问题列表无法捕捉这种结构。
**解决方案：** 工作自然分解：
``` Epic: User Authentication System ├── Feature: Login Flow │ ├── Task: API endpoint │ ├── Task: Frontend component │ └── Task: Integration tests ├── Feature: Session Management │ └── ... └── Feature: Password Reset └── ... ```
每个层级都有自己的链。自动汇总。你始终清楚自己的进展。
### 功能：跨项目引用
**问题：** 在后端 API 落地之前，你的前端无法发布。它们位于不同的代码库中。传统工具无法追踪这一点。
**解决方案：** 显式的跨项目依赖关系：
``` depends_on: beads://github/acme/backend/be-456 # Backend API beads://github/acme/shared/sh-789 # Shared types ```
### 功能：验证与质量门禁
**问题：** Agent 说“做完了”。真的做完了吗？代码质量是否可接受？是否通过了审查？
**解决方案：** 带有归因信息的结构化验证：
```json { "validated_by": "gastown/refinery", "validation_type": "merge", "timestamp": "2025-01-15T10:30:00Z", "quality_signals": { "tests_passed": true, "review_approved": true, "lint_clean": true } } ```
### 功能：实时动态源
**问题：** 复杂的多 Agent 工作是不透明的。直到完成（或失败）你才知道发生了什么。
**解决方案：** 工作状态作为实时流：
```bash bd activity --follow
[14:32:08] + patrol-x7k.arm-ace bonded (5 steps) [14:32:09] → patrol-x7k.arm-ace.capture in_progress [14:32:10] ✓ patrol-x7k.arm-ace.capture completed [14:32:14] ✓ patrol-x7k.arm-ace.decide completed [14:32:17] ✓ patrol-x7k.arm-ace COMPLETE ```
**重要性：** - **实时调试：** 在问题发生时看到它们 - **状态感知：** 始终知道正在运行什么 - **模式识别：** 发现瓶颈和低效环节
### 企业价值主张
| 能力 | 开发者收益 | 企业收益 | |------------|-------------------|-------------------| | 归因 | 调试 Agent 问题 | 合规审计 | | 工作历史 | 调整 Agent 分配 | 绩效管理 | | 技能路由 | 更快的任务完成 | 资源优化 | | 联邦 | 多代码库项目 | 跨组织可见性 | | 验证 | 质量保证 | 流程执行 | | 动态源 | 实时调试 | 运营感知 |
### 设计理念
1. **归因是必不可少的。** 每个动作都有一个执行者。 2. **工作即数据。** 不仅仅是工单——而是结构化的、可查询的数据。 3. **历史很重要。** 过往记录决定信任度。 4. **默认考虑规模。** 从第一天起就支持多代码库、多 Agent、多组织。 5. **验证优于信任。** 质量门禁是一等公民原语。
---
## 提示
- **始终从 Mayor 开始** - 它被设计为你的主要接口 - **使用 convoys 进行协调** - 它们提供跨 Agent 的可见性 - **利用 hooks 实现持久化** - 你的工作不会消失 - **为重复性任务创建 formulas** - 使用 Beads 配方节省时间 - **监控仪表板** - 获取实时可见性 - **让 Mayor 进行编排** - 它知道如何管理 Agent - **始终使用 `gt --help`** 或 `gt <command> --help` 来验证语法
---
## 许可证
MIT License - 详情请参阅 LICENSE 文件
---
*本词汇表由 [Clay Shirky](https://github.com/cshirky) 在 [Issue #80](https://github.com/steveyegge/gastown/issues/80) 中贡献。*
**安装命令**：`tessl install github:numman-ali/n-skills --skill gastown`