gastownhall/gastown 来源：https://github.com/gastownhall/gastown

Gas Town

用于 Claude Code、GitHub Copilot 及其他 AI 智能体的多智能体编排系统，支持持久化工作追踪

概述

Gas Town 是一个工作区管理器，让你能够协调多个 AI 编码智能体（Claude Code、GitHub Copilot、Codex、Gemini 等）同时处理不同的任务。当智能体重启时，Gas Town 不会丢失上下文，而是将工作状态持久化存储在基于 git 的挂钩（Hooks）中，从而实现可靠的多智能体工作流。

这解决了什么问题？

架构

graph TB
Mayor[市长：AI 协调器]
Town[城镇：工作区 ~/gt/]
Town --> Mayor
Town --> Rig1[工作台：项目 A]
Town --> Rig2[工作台：项目 B]
Rig1 --> Crew1[团队成员：你的工作区]
Rig1 --> Hooks1[挂钩：持久化存储]
Rig1 --> Polecats1[臭鼬：工作智能体]
Rig2 --> Crew2[团队成员]
Rig2 --> Hooks2[挂钩]
Rig2 --> Polecats2[臭鼬]
Hooks1 -.git worktree.-> GitRepo1[Git 仓库]
Hooks2 -.git worktree.-> GitRepo2[Git 仓库]
style Mayor fill:#e1f5ff,color:#000000
style Town fill:#f0f0f0,color:#000000
style Rig1 fill:#fff4e1,color:#000000
style Rig2 fill:#fff4e1,color:#000000

核心概念

市长（The Mayor） 🎩

你的主要 AI 协调器。市长是一个 Claude Code 实例，拥有关于你的工作区、项目和智能体的完整上下文。 从这里开始——只需告诉市长你想完成什么。

城镇（Town） 🏘️

你的工作区目录（例如 ~/gt/）。包含所有项目、智能体和配置。

工作台（Rigs） 🏗️

项目容器。每个工作台包装一个 git 仓库，并管理其关联的智能体。

团队成员（Crew Members） 👤

你在工作台内的个人工作区。在这里进行实际操作。

臭鼬（Polecats） 🦨

具有持久身份标识但会话临时的工作智能体。为任务而生，完成后结束会话，但身份标识和工作历史持久保留。

挂钩（Hooks） 🪝

基于 git worktree 的持久化存储，用于智能体工作。可承受崩溃和重启。

车队（Convoys） 🚚

工作追踪单元。将多个珠串打包分配给智能体。标记为 mountain 的车队拥有自主停滞检测和智能跳过逻辑，适合史诗级规模的执行。

珠串集成（Beads Integration） 📿

基于 git 的问题跟踪系统，将工作状态存储为结构化数据。 珠串 ID（也称为 问题 ID）使用前缀 + 5 字符字母数字格式（例如 gt-abc12、hq-x7k2m）。前缀表示项目的来源或工作台。gt sling 和 gt convoy 等命令接受这些 ID 来引用特定工作项。“珠串”和“问题”可互换使用——珠串是底层数据格式，而问题是作为珠串存储的工作项。

分子（Molecules） 🧬

协调多步工作的工作流模板。公式（TOML 定义）被实例化为具有可追踪步骤的分子。有两种模式：根级独享的轻量 wisps（步骤在运行时物化，轻量）和注入式 wisps（步骤作为子 wisps 物化，支持检查点恢复）。详见 Molecules。

监控：见证者、执事、犬群 🐕

三层看门狗系统保持智能体健康：

• 见证者（Witness） - 每个工作台的生命周期管理器。监控臭鼬、检测卡住的智能体、触发恢复、管理会话清理。
• 执事（Deacon） - 后台主管，在所有工作台上持续运行巡逻周期。
• 犬群（Dogs） - 由执事派发的基础设施工作者，用于维护任务（例如 Boot 用于分流）。

精炼厂（Refinery） 🏭

每个工作台的合并队列处理器。当臭鼬通过 gt done 完成工作时，精炼厂会批量合并请求、运行验证门，并使用类似 Bors 的二分队列合并到主分支。失败的合并请求被隔离，并在线修复或重新派发。

升级（Escalation） 🚨

基于严重性路由的问题升级。遇到阻塞的智能体通过 gt escalate 发起升级，创建可追踪的珠串，通过执事、市长（必要时通过监督者）进行路由。严重性级别：CRITICAL（P0）、HIGH（P1）、MEDIUM（P2）。详见 Escalation。

调度器（Scheduler） ⏱️

用于臭鼬派发的配置驱动容量调节器。通过在可配置的并发限制下批量派发，防止 API 速率限制耗尽。默认为直接派发；设置 scheduler.max_polecats 可启用带守护进程的延迟派发。详见 Scheduler。

通灵（Seance） 👻

会话发现与继续。通过 .events.jsonl 日志发现之前的智能体会话，使智能体能够向前驱会话查询上下文和早期工作的决策。

gt seance               # 列出可发现的前驱会话
gt seance --talk -p "What did you find?"  # 一次性提问

荒原（Wasteland） 🏜️

通过 DoltHub 连接多个 Gas Town 的联邦工作协调网络。工作台可以发布需求项、认领其他城镇的工作、提交完成证据，并通过多维印章获得可迁移声誉。详见 Wasteland。

首次接触 Gas Town？ 请参阅 Glossary 获取术语和概念的完整指南。

安装

前提条件

• Go 1.25+ - go.dev/dl (https://go.dev/dl/)
• Git 2.25+ - 需要 worktree 支持
• Dolt 2.0.7+ - macOS 上 brew install dolt，或参见 github.com/dolthub/dolt (https://github.com/dolthub/dolt)
• beads (bd) 0.55.4+ - 通过 brew install gastown 安装，或参见 github.com/steveyegge/beads (https://github.com/steveyegge/beads)
• sqlite3 - 用于车队数据库查询（macOS/Linux 通常已预装）
• tmux 3.0+ - 推荐用于完整体验
• Claude Code CLI（默认运行时） - claude.ai/code (https://claude.ai/code)
• Codex CLI（可选运行时） - developers.openai.com/codex/cli (https://developers.openai.com/codex/cli)
• GitHub Copilot CLI（可选运行时） - cli.github.com (https://cli.github.com)（需要 Copilot 席位）

安装（下方还有 Docker Compose）

# 安装 Gas Town
$ brew install gastown               # Homebrew（推荐）
$ npm install -g @gastown/gt          # npm
$ go install github.com/steveyegge/gastown/cmd/gt@latest  # 从源码安装（仅 Linux）
# macOS：go install 生成未签名的二进制文件，macOS 会 SIGKILL。
# 请使用上面的 brew install，或安装 Dolt 并用 make 克隆构建：
$ brew install dolt
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ make build && mv gt $HOME/go/bin/
# Windows（或当 go install 失败时）：手动克隆并构建
$ git clone https://github.com/steveyegge/gastown.git && cd gastown
$ go build -o gt.exe ./cmd/gt
$ mv gt.exe $HOME/go/bin/
# 或将 gastown 添加到 PATH
# 如果使用 go install，请将 Go 二进制文件添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）
export PATH="$PATH:$HOME/go/bin"

# 创建工作区并初始化 git
gt install ~/gt --git
cd ~/gt

# 添加你的第一个项目
gt rig add myproject https://github.com/you/repo.git

# 创建你的团队工作区
gt crew add yourname --rig myproject
cd myproject/crew/yourname

# 启动市长会话（你的主界面）
gt mayor attach

Docker Compose

export GIT_USER=""
export GIT_EMAIL=""
export FOLDER="/Users/you/code"
export DASHBOARD_PORT=8080  # 可选，Web 仪表板的主机端口
docker compose build        # 仅在首次运行或代码更改后需要
docker compose up -d
docker compose exec gastown zsh  # 或 bash
gt up
gh auth login               # 如果你想使用 gh
gt mayor attach

快速入门指南

开始使用

运行

gt install ~/gt --git && cd ~/gt && gt config agent list && gt mayor attach

然后告诉市长你想构建什么！

基本工作流

sequenceDiagram
    参与者 你
    参与者 市长
    参与者 车队
    参与者 智能体
    参与者 挂钩
    你->>市长: 告诉市长要构建什么
    市长->>车队: 创建带有珠串的车队
    市长->>智能体: 将珠串派发给智能体
    智能体->>挂钩: 存储工作状态
    智能体->>智能体: 完成工作
    智能体->>车队: 报告完成
    市长->>你: 进度摘要

示例：功能开发

# 1. 启动市长
gt mayor attach

# 2. 在市长会话中，创建带有珠串 ID 的车队
gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human

# 3. 将工作分配给智能体
gt sling gt-abc12 myproject

# 4. 跟踪进度
gt convoy list

# 5. 监控智能体
gt agents

常见工作流

市长工作流（推荐）

最适合： 协调复杂的多问题工作

flowchart LR
Start([启动市长]) --> Tell[告诉市长要构建什么]
Tell --> Creates[市长创建车队 + 智能体]
Creates --> Monitor[通过 convoy list 监控进度]
Monitor --> Done{全部完成？}
Done -->|否| Monitor
Done -->|是| Review[审查工作]

命令：

# 连接到市长
gt mayor attach

# 在市长中，创建车队并让它协调
gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify

# 跟踪进度
gt convoy list

极简模式（无需 Tmux）

手动运行单个运行时实例。Gas Town 仅跟踪状态。

gt convoy create "Fix bugs" gt-abc12        # 创建车队（若跳过 sling 则自动创建）
gt sling gt-abc12 myproject                  # 分配给工作者
claude --resume                               # 智能体读取邮件，运行工作（Claude）
# 或：codex                                    # 在工作区中启动 Codex
gt convoy list                                # 检查进度

珠串公式工作流

最适合： 预定义的可重复流程

公式是嵌入在 gt 二进制文件中的 TOML 定义的工作流（源码在 internal/formula/formulas/ 中）。

示例公式（internal/formula/formulas/release.formula.toml）：

description = "标准发布流程"
formula = "release"
version = 1

[vars.version]
description = "要发布的语义版本号（例如 1.2.0）"
required = true

[[steps]]
id = "bump-version"
title = "更新版本号"
description = "运行 ./scripts/bump-version.sh {{version}}"

[[steps]]
id = "run-tests"
title = "运行测试"
description = "运行 make test"
needs = ["bump-version"]

[[steps]]
id = "build"
title = "构建"
description = "运行 make build"
needs = ["run-tests"]

[[steps]]
id = "create-tag"
title = "创建发布标签"
description = "运行 git tag -a v{{version}} -m 'Release v{{version}}'"
needs = ["build"]

[[steps]]
id = "publish"
title = "发布"
description = "运行 ./scripts/publish.sh"
needs = ["create-tag"]

执行：

# 列出可用公式
bd formula list

# 运行公式，传入变量
bd cook release --var version=1.2.0

# 创建公式实例用于跟踪
bd mol pour release --var version=1.2.0

手动车队工作流

最适合： 直接控制工作分配

# 手动创建车队
gt convoy create "Bug Fixes" --human

# 向已有车队添加问题
gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x

# 分配给特定智能体
gt sling gt-m3k9p myproject/my-agent

# 检查状态
gt convoy show

运行时配置

Gas Town 支持多种 AI 编码运行时。每个工作台的运行时设置位于 settings/config.json 中。

{
  "runtime": {
    "provider": "codex",
    "command": "codex",
    "args": [],
    "prompt_mode": "none"
  }
}

注意：

• Claude 使用 .claude/settings.json（通过 --settings 标志管理）中的挂钩进行邮件注入和启动。
• 对于 Codex，在 ~/.codex/config.toml 中设置 project_doc_fallback_filenames = ["CLAUDE.md"]，以便角色指令被加载。
• 对于没有挂钩的运行时（例如 Codex），Gas Town 在会话就绪后发送一个启动回退：gt prime，对于自主角色可选的 gt mail check --inject，以及 gt nudge deacon session-started。
• GitHub Copilot（copilot）是一个内置预设，使用 --yolo 进入自主模式。它使用 .github/hooks/gastown.json 中的可执行生命周期挂钩（事件与 Claude 相同：sessionStart、userPromptSubmitted、preToolUse、sessionEnd）。使用 5 秒就绪延迟而非提示检测。需要 Copilot 席位和组织级 CLI 策略。详见 docs/INSTALLING.md。

关键命令

工作区管理

gt install              # 初始化工作区
gt rig add              # 添加项目
gt rig list             # 列出项目
gt crew add --rig       # 创建团队工作区

智能体操作

gt agents               # 列出活动智能体
gt sling                # 向智能体分配工作
gt sling --agent cursor # 为此派发/生成覆盖运行时
gt mayor attach         # 启动市长会话
gt mayor start --agent auggie  # 使用特定智能体别名运行市长
gt prime                # 上下文恢复（在已有会话中运行）
gt feed                 # 实时活动馈送（TUI）
gt feed --problems      # 以问题视图启动（卡住智能体检测）

内置智能体预设：claude、gemini、codex、cursor、auggie、amp、opencode、copilot、pi、omp

车队（工作追踪）

gt convoy create [issues...]   # 创建带有问题的车队
gt convoy list                 # 列出所有车队
gt convoy show [id]            # 显示车队详情
gt convoy add                  # 向车队添加问题

配置

# 设置自定义智能体命令
gt config agent set claude-glm "claude-glm --model glm-4"
gt config agent set codex-low "codex --thinking low"

# 设置默认智能体
gt config default-agent claude-glm

监控与健康

gt escalate -s HIGH "description"   # 升级一个阻塞项
gt escalate list                     # 列出未解决的升级
gt scheduler status                  # 显示调度器状态
gt seance                            # 发现前驱会话
gt seance --talk                     # 向前驱会话提问

珠串集成

bd formula list      # 列出公式
bd cook              # 执行公式
bd mol pour          # 创建可追踪的实例
bd mol list          # 列出活动实例

荒原联邦

gt wl join                  # 加入一个荒原
gt wl browse                # 查看需求公告板
gt wl claim                 # 认领工作
gt wl done --evidence       # 提交完成证据

烹饪公式（Cooking Formulas）

Gas Town 包含内置公式，用于常见工作流。参见 internal/formula/formulas/ 获取可用配方。

活动馈送（Activity Feed）

gt feed 启动一个交互式终端仪表板，实时监控所有智能体的活动。它将珠串活动、智能体事件和合并队列更新整合为一个三面板 TUI：

• 智能体树 - 所有智能体的分层视图，按工作台和角色分组
• 车队面板 - 进行中及最近完成的车队
• 事件流 - 按时间顺序的事件馈送，包括创建、完成、派发、轻推等

gt feed                    # 启动 TUI 仪表板
gt feed --problems         # 以问题视图启动
gt feed --plain            # 纯文本输出（无 TUI）
gt feed --window           # 在专用 tmux 窗口中打开
gt feed --since 1h         # 过去一小时的事件

导航： j/k 滚动，Tab 切换面板，1/2/3 跳转到面板，? 帮助，q 退出。

问题视图

当规模达到 20-50+ 个智能体时，在活动流中识别卡住的智能体会变得困难。问题视图通过分析结构化的珠串数据，呈现需要人工干预的智能体。在 gt feed 中按 p（或使用 gt feed --problems 启动）即可切换问题视图，其中按健康状态对智能体进行分组：

干预键（问题视图中）：n 对所选智能体进行轻推，h 进行交接（刷新上下文）。

仪表板（Dashboard）

Gas Town 包含一个 Web 仪表板，用于监控你的工作区。仪表板必须从 Gas Town 工作区（HQ）目录内运行。

# 启动仪表板（默认端口 8080）
gt dashboard

# 在自定义端口启动
gt dashboard --port 3000

# 启动并自动在浏览器中打开
gt dashboard --open

该仪表板提供一个单页概览，展示工作区中正在发生的一切：智能体、车队、挂钩、队列、问题和升级。它通过 htmx 自动刷新，并内嵌…