燃气小镇

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

概述

燃气小镇是一个工作空间管理器，允许您协调多个 AI 编程助手（Claude Code、GitHub Copilot、Codex、Gemini 等）同时处理不同的任务。与传统方式中助手重启后丢失上下文不同，燃气小镇通过 Git 支持的钩子持久化工作状态，从而实现可靠的多智能体工作流。

解决了哪些问题？

挑战	燃气小镇的解决方案
助手重启后丢失上下文	工作状态保存在 Git 支持的钩子中
手动协调助手	内置邮箱、身份和交接机制
4–10 个助手协作变得混乱	可轻松扩展至 20–30 个助手
助手内存中丢失工作状态	工作状态存储在 Beads 账本中

架构

graph TB
    Mayor[市长<br/>AI 协调员]
    Town[城镇工作空间<br/>~/gt/]

    Town --> Mayor
    Town --> Rig1[装置：项目 A]
    Town --> Rig2[装置：项目 B]

    Rig1 --> Crew1[船员成员<br/>您的工作空间]
    Rig1 --> Hooks1[钩子<br/>持久化存储]
    Rig1 --> Polecats1[黄鼠狼<br/>工作者助手]

    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

核心概念

市长 🎩

您的主要 AI 协调员。市长是一个拥有完整工作空间、项目和助手信息的 Claude Code 实例。从这里开始——只需告诉市长您想完成什么。

城镇 🏘️

您的工作目录（例如 ~/gt/）。包含所有项目、助手和配置。

装置 🏗️

项目容器。每个装置包裹一个 Git 仓库，并管理其相关的助手。

船员成员 👤

您在装置中的个人工作空间。您在此进行实际操作。

黄鼠狼 🦨

具有持久身份但会话短暂的工作者助手。它们为特定任务而启动，任务完成后会话结束，但身份和工作历史仍然保留。

钩子 🪝

基于 Git 工作树的助手工作持久化存储。即使崩溃或重启也能保持数据。

运输队 🚚

工作追踪单元。将多个珠子捆绑在一起并分配给助手。标记为 mountain 的运输队具备自主卡顿检测和智能跳过逻辑，适用于大型执行场景。

珠子集成 📿

基于 Git 的问题追踪系统，以结构化数据形式存储工作状态。

珠子 ID（也称为 问题 ID）采用前缀加 5 位字母数字格式（如 gt-abc12、hq-x7k2m）。前缀表示项目的来源或装置。诸如 gt sling 和 gt convoy 等命令可接受这些 ID 来引用特定的工作项。“珠子”和“问题”这两个术语可以互换使用——珠子是底层数据格式，而问题是作为珠子存储的工作项。

分子 🧬

协调多步骤工作的流程模板。配方（TOML 定义）被实例化为带有跟踪步骤的分子。有两种模式：仅根级细丝（运行时展开步骤，轻量级）和浇注细丝（步骤被展开为子细丝，并支持检查点恢复）。详情请参阅 分子。

监控：目击者、执事、警犬 🐕

三级看门狗系统确保助手健康运行：

• 目击者——每装置生命周期管理者。监控黄鼠狼，检测卡住的助手，触发恢复，管理会话清理。
• 执事——后台监督员，在所有装置间持续巡逻。
• 警犬——由执事派遣的基础设施工作人员，负责维护任务（例如引导进行故障排除）。

精炼厂 🏭

每装置的合并队列处理器。当黄鼠狼通过 gt done 完成工作时，精炼厂会批量处理合并请求，运行验证关卡，并使用类似 Bors 的二分队列合并到主分支。失败的 MR 会被隔离，要么就地修复，要么重新调度。

上报 🚨

按严重程度路由的问题上报机制。遇到阻塞的助手可通过 gt escalate 上报，该命令会创建由执事、市长以及（必要时）监督员处理的跟踪珠子。严重等级：CRITICAL（P0）、HIGH（P1）、MEDIUM（P2）。详情请参阅 上报。

调度器 ⏱️

基于配置的黄鼠狼调度容量控制器。通过在可配置的并发限制下批量调度，防止 API 速率限制耗尽。默认为直接调度；设置 scheduler.max_polecats 可启用带有守护进程的延迟调度。详情请参阅 调度器。

通灵会 👻

会话发现与延续。通过 .events.jsonl 日志发现之前的助手会话，使助手能够查询其前任助手，获取早期工作的上下文和决策。

gt seance                       # 列出可发现的前任会话
gt seance --talk <id> -p "你发现了什么？"  # 一次性的提问

荒原 🏜️

通过 DoltHub 连接各个燃气小镇的联邦式工作协调网络。装置发布所需任务，从其他城镇领取工作，提交完成证据，并通过多维印章获得可移植的声誉。详情请参阅 荒原。

初次接触燃气小镇？ 请参阅 术语表，获取完整的术语和概念指南。

安装

先决条件

• Go 1.25+ —— go.dev/dl
• Git 2.25+ —— 用于支持工作树功能
• Dolt 1.82.4+ —— github.com/dolthub/dolt
• beads (bd) 0.55.4+ —— github.com/steveyegge/beads
• sqlite3 —— 用于运输队数据库查询（通常在 macOS/Linux 上已预装）
• tmux 3.0+ —— 推荐以获得完整体验
• Claude Code CLI（默认运行时）—— claude.ai/code
• Codex CLI（可选运行时）—— developers.openai.com/codex/cli
• GitHub Copilot CLI（可选运行时）—— cli.github.com（需要 Copilot 许可）

设置（下方为 Docker Compose 示例）

# 安装燃气小镇
$ brew install gastown                                    # Homebrew（推荐）
$ npm install -g @gastown/gt                              # npm
$ go install github.com/steveyegge/gastown/cmd/gt@latest  # 从源码安装（macOS/Linux）

# 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/  # 或将燃气小镇添加到 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

# 启动 Mayor 会话（你的主界面）
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

然后告诉 Mayor 你想要构建什么！

---

基本工作流程

sequenceDiagram
    participant 你
    participant Mayor
    participant Convoy
    participant Agent
    participant Hook

    你->>Mayor: 告诉 Mayor 要构建什么
    Mayor->>Convoy: 创建包含珠子的 convoy
    Mayor->>Agent: 将珠子发送给代理
    Agent->>Hook: 存储工作状态
    Agent->>Agent: 完成工作
    Agent->>Convoy: 报告完成情况
    Mayor->>你: 进度总结

示例：功能开发

# 1. 启动 Mayor
gt mayor attach

# 2. 在 Mayor 会话中，创建包含珠子 ID 的 convoy
gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human

# 3. 将任务分配给一个代理
gt sling gt-abc12 myproject

# 4. 跟踪进度
gt convoy list

# 5. 监控代理
gt agents

常见工作流程

Mayor 工作流程（推荐）

最适合： 协调复杂的多任务工作

flowchart LR
    Start([启动 Mayor]) --> Tell[告诉 Mayor<br/>要构建什么]
    Tell --> Creates[Mayor 创建<br/>convoy + 代理]
    Creates --> Monitor[通过 convoy 列表监控进度]
    Monitor --> Done{都完成了吗？}
    Done -->|否| Monitor
    Done -->|是| Review[审查工作]

命令：

# 附着到 Mayor
gt mayor attach

# 在 Mayor 中，创建 convoy 并让其协调
gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify

# 跟踪进度
gt convoy list

极简模式（无 Tmux）

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

gt convoy create "修复 bug" gt-abc12   # 创建 convoy（如果省略，则 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

手动 convoy 工作流程

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

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

# 向现有 convoy 添加问题
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 <rig>  # 创建团队工作区

代理操作

gt agents                   # 列出活跃代理
gt sling <珠子 ID> <项目>    # 将工作分配给代理
gt sling <珠子 ID> <项目> --agent cursor   # 覆盖本次 sling/spawn 的运行时
gt mayor attach             # 启动 Mayor 会话
gt mayor start --agent auggie           # 使用特定代理别名运行 Mayor
gt prime                    # 上下文恢复（在现有会话内运行）
gt feed                     # 实时活动信息流（TUI）
gt feed --problems          # 以问题视图启动（检测卡住的代理）

内置代理预设：claude、gemini、codex、cursor、auggie、amp、opencode、copilot、pi、omp

Convoy（工作跟踪）

gt convoy create <名称> [问题...]   # 创建包含问题的 convoy
gt convoy list              # 列出所有 convoy
gt convoy show [ID]         # 显示 convoy 详情
gt convoy add <convoy ID> <问题 ID...>  # 向 convoy 添加问题

配置

# 设置自定义代理命令
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 <id>          # 查询前一个会话

Beads 集成

bd formula list             # 列出配方
bd cook <formula>           # 执行配方
bd mol pour <formula>       # 创建可追踪实例
bd mol list                 # 列出当前活跃实例

荒原联邦

gt wl join <remote>            # 加入荒原
gt wl browse                   # 查看待办事项板
gt wl claim <id>               # 领取任务
gt wl done <id> --evidence <url>  # 提交完成情况

烹饪配方

Gas Town 内置了常见工作流的配方。可用配方请参阅 internal/formula/formulas/。

活动信息流

gt feed 启动一个交互式终端仪表盘，用于实时监控所有代理的活动。它将 beads 活动、代理事件和合并队列更新整合到一个三面板的 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+ 个代理），在活动流中很难发现卡住的代理。问题视图通过分析结构化的 beads 数据，突出显示需要人工干预的代理。

在 gt feed 中按 p 键（或直接使用 gt feed --problems）可以切换到问题视图，该视图按代理的健康状态分组：

状态	条件
GUPP 违规	长时间没有进展的工作
停滞	工作进展缓慢
僵尸	已经死亡的 tmux 会话
运行中	正常运行并取得进展
空闲	当前没有工作任务

干预键（在问题视图中）：n 提醒选中的代理，h 交接（刷新上下文）。

仪表盘

Gas Town 包含一个用于监控工作空间的 Web 仪表盘。该仪表盘必须在 Gas Town 工作空间（HQ）目录内运行。

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

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

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

仪表盘提供了一个单页概览，展示了工作空间中发生的一切：代理、车队、任务、队列、问题和升级情况。它通过 htmx 自动刷新，并包含一个命令面板，允许您直接在浏览器中运行 gt 命令。

监控与健康

Gas Town 使用三层看门狗机制来确保大规模下的代理健康：

守护进程（Go 进程）← 每 3 分钟发送一次心跳
    └── Boot（AI 代理）← 智能分流
        └── Deacon（AI 代理）← 持续巡逻
            └── Witnesses & Refineries ← 每个机架的代理

Witness（每个机架）

每个机架都有一个 Witness，负责监控其 polecats。Witness 能够检测卡住的代理，触发恢复操作（提醒或交接），管理会话清理，并跟踪完成情况。Witness 不会直接执行任务，而是将任务委派给其他代理。

Deacon（跨机架）

Deacon 会在所有机架之间持续巡逻，检查代理的健康状况，派遣 Dogs 处理维护任务，并将个别 Witness 无法解决的问题上报给更高层级。

升级

当代理遇到阻塞问题时，他们会主动升级，而不是等待：

gt escalate -s HIGH "阻塞问题描述"
gt escalate list                    # 列出未处理的升级问题
gt escalate ack <bead-id>           # 确认升级问题

升级问题会根据严重程度依次传递给 Deacon、Mayor 和 Overseer。详细信息请参阅 升级设计。

合并队列（Refinery）

Refinery 通过二分法合并队列处理已完成的 polecat 工作：

1. Polecat 执行 gt done -> 推送分支，创建 MR bead
2. Refinery 将待处理的 MRs 分批处理
3. 对合并后的代码栈运行验证门限
4. 如果通过：该批次的所有 MRs 合并到主分支
5. 如果失败：进行二分查找以隔离失败的 MR，合并其余成功的 MRs

这是一种类似 Bors 的合并队列——polecats 不会直接推送到主分支。

调度器

调度器控制 polecat 的派遣能力，以防止 API 速率限制被耗尽：

gt config set scheduler.max_polecats 5   # 启用延迟派遣（最多 5 个并发）
gt scheduler status                      # 显示调度器状态
gt scheduler pause                       # 暂停派遣
gt scheduler resume                      # 继续派遣

默认模式（max_polecats = -1）会立即通过 gt sling 派遣。当设置了限制后，守护进程会逐步派遣，以遵守容量限制。详细信息请参阅 调度器设计。

Seance

发现并查询之前的代理会话：

gt seance                              # 列出可发现的先前会话
gt seance --talk <id>                  # 与前任代理的完整对话
gt seance --talk <id> -p "Question?"   # 向前任代理提出一次性问题

Seance 通过 .events.jsonl 日志发现会话，使代理能够从之前的工作中恢复上下文和决策，而无需重新阅读整个代码库。

荒原联邦

荒原是一个通过 DoltHub 连接多个 Gas Town 的联邦工作协调网络：

gt wl join hop/wl-commons              # 加入荒原
gt wl browse                           # 查看待办事项板
gt wl claim <id>                       # 领取待办事项
gt wl done <id> --evidence <url>       # 提交完成情况及证据
gt wl post --title "Need X"            # 发布新的待办事项

完成任务可以获得多维度的印章形式的可移植声誉（质量、速度、复杂性）。详细信息请参阅 荒原指南。

遥测（OpenTelemetry）

Gas Town 会将所有代理的操作作为结构化日志和指标发送到任何兼容 OTLP 的后端（默认为 VictoriaMetrics/VictoriaLogs）：

# 配置 OTLP 端点
export GT_OTEL_LOGS_URL="http://localhost:9428/insert/jsonline"
export GT_OTEL_METRICS_URL="http://localhost:8428/api/v1/write"

发出的事件： 会话生命周期、代理状态变化、带有持续时间的 BD 调用、邮件操作、投掷/推动/完成工作流、Polecat 派生/移除、公式实例化、车队创建、守护进程重启等。

指标包括： gastown.session.starts.total、gastown.bd.calls.total、gastown.polecat.spawns.total、gastown.done.total、gastown.convoy.creates.total 等。

完整事件模式请参阅 OTEL 数据模型 和 OTEL 架构。

高级概念

推进原理

Gas Town 使用 Git 钩子作为推进机制。每个钩子都是一个 Git 工作树，具备以下特性：

1. 持久化状态 - 即使代理重启，工作仍能保存。
2. 版本控制 - 所有更改都记录在 Git 中。
3. 回滚能力 - 可以恢复到任意先前状态。
4. 多代理协调 - 通过 Git 共享。

钩子生命周期

stateDiagram-v2
    [*] --> Created: 代理被派生
    Created --> Active: 分配了工作
    Active --> Suspended: 代理暂停
    Suspended --> Active: 代理恢复
    Active --> Completed: 工作完成
    Completed --> Archived: 钩子归档
    Archived --> [*]

MEOW（市长增强型编排工作流）

MEOW 是推荐的模式：

1. 告知市长 - 描述你的需求。
2. 市长分析 - 将任务分解。
3. 创建车队 - 市长创建包含“珠子”的车队。
4. 派生代理 - 市长派生合适的代理。
5. 分配工作 - 通过钩子将“珠子”分发给代理。
6. 进度监控 - 通过车队状态跟踪进展。
7. 完成 - 市长总结结果。

Shell 补全

# Bash
gt completion bash > /etc/bash_completion.d/gt

# Zsh
gt completion zsh > "${fpath[1]}/_gt"

# Fish
gt completion fish > ~/.config/fish/completions/gt.fish

项目角色

角色	描述	主要接口
市长	AI 协调员	gt mayor attach
人类（您）	队员	您的工作目录
Polecat	工作代理	由市长派生
目击者	每个平台的代理健康监测	自动巡逻
执事	跨平台监督守护进程	gt patrol
炼油厂	合并队列处理器	自动处理
钩子	持久化存储	Git 工作树
车队	工作追踪器	gt convoy 命令

小贴士

• 始终从市长开始 - 它是专为您的主要界面设计的。
• 使用车队进行协调 - 车队可以跨代理提供可见性。
• 利用钩子实现持久化 - 您的工作不会丢失。
• 为重复任务创建公式 - 使用“珠子”配方节省时间。
• 使用 gt feed 进行实时监控 - 观察代理活动，及早发现卡住的代理。
• 监控仪表板 - 在浏览器中获取实时可见性。
• 让市长进行编排 - 它知道如何管理代理。

设计文档

如需深入了解技术细节，请参阅 docs/ 目录下的设计文档：

主题	文档
架构	docs/design/architecture.md
术语表	docs/glossary.md
分子	docs/concepts/molecules.md
升级策略	docs/design/escalation.md
调度器	docs/design/scheduler.md
废土	docs/WASTELAND.md
OTEL 数据模型	docs/otel-data-model.md
目击者设计	docs/design/witness-at-team-lead.md
车队生命周期	docs/design/convoy/
Polecat 生命周期	docs/design/polecat-lifecycle-patrol.md
插件系统	docs/design/plugin-system.md
代理提供商	docs/agent-provider-integration.md
钩子	docs/HOOKS.md
安装指南	docs/INSTALLING.md

故障排除

代理失去连接

检查钩子是否正确初始化：

gt hooks list
gt hooks repair

车队卡住

强制刷新：

gt convoy refresh <车队ID>

市长无响应

重启市长会话：

gt mayor detach
gt mayor attach

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

Gas Town 快速上手指南

Gas Town 是一个多智能体编排系统，旨在协调 Claude Code、GitHub Copilot 等 AI 编程助手协同工作。它通过 Git 支持的持久化存储（Hooks）和任务追踪机制（Beads/Convoys），解决了多智能体协作中上下文丢失和状态管理混乱的问题。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

系统要求

• 操作系统: macOS, Linux (Windows 需手动编译或使用 Docker)
• Git: 版本 2.25+ (必须支持 worktree)
• Go: 版本 1.25+
• tmux: 版本 3.0+ (推荐，用于获得完整体验)

核心依赖

• Dolt: 版本 1.82.4+ (分布式 SQL 数据库，用于状态存储)
• beads (bd): 版本 0.55.4+ (问题追踪底层格式)
• sqlite3: 通常 macOS/Linux 预装，用于 convoy 数据库查询

AI 运行时 (至少安装其一)

• Claude Code CLI (默认推荐): claude.ai/code
• Codex CLI (可选): developers.openai.com/codex/cli
• GitHub Copilot CLI (可选): 需拥有 Copilot 席位

国内开发者提示: 由于部分依赖（如 Go 模块、npm 包、Dolt）托管在海外，建议配置国内镜像源以加速下载：

• Go: export GOPROXY=https://goproxy.cn,direct
• npm: npm config set registry https://registry.npmmirror.com
• Git: 若克隆 GitHub 仓库缓慢，可考虑使用镜像站或代理。

2. 安装步骤

您可以选择以下任一方式进行安装：

方式 A：Homebrew (macOS 推荐)

brew install gastown

方式 B：npm (跨平台)

npm install -g @gastown/gt

方式 C：从源码安装 (Go)

# 设置 Go 代理 (可选，加速下载)
export GOPROXY=https://goproxy.cn,direct

# 安装最新正式版
go install github.com/steveyegge/gastown/cmd/gt@latest

# 将 Go bin 目录加入 PATH (如果尚未添加)
export PATH="$PATH:$HOME/go/bin"

方式 D：Docker Compose (隔离环境)

如果您希望避免本地依赖冲突，可使用 Docker：

export GIT_USER="<您的名字>"
export GIT_EMAIL="<您的邮箱>"
export FOLDER="/Users/you/code" # 替换为您的代码目录

docker compose build
docker compose up -d
docker compose exec gastown zsh

初始化工作区

安装完成后，执行以下命令创建初始工作区并关联 Git：

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

# 进入工作区
cd ~/gt

# 添加第一个项目 (Rig)
gt rig add myproject https://github.com/yourname/yourrepo.git

# 创建个人工作空间 (Crew)
gt crew add yourname --rig myproject

# 进入个人工作目录
cd myproject/crew/yourname

3. 基本使用

Gas Town 的核心是 "The Mayor" (市长)，它是一个拥有全局上下文的 AI 协调员。您只需告诉 Mayor 要做什么，它会自动创建任务队列（Convoy）、分配智能体（Polecats）并追踪进度。

启动协调员

运行以下命令启动 Mayor 会话：

gt mayor attach

简单工作流示例

一旦进入 gt mayor attach 会话，您可以直接用自然语言下达指令。例如：

1. 下达指令:

   "我要为 myproject 添加一个用户登录功能，包含前端表单和后端 API。"

   Mayor 会自动：

   • 创建相关的任务项 (Beads)。
   • 组建任务车队 (Convoy)。
   • 调度合适的 AI 智能体 (Polecats) 开始工作。

2. 监控进度 (在另一个终端窗口或退出 Mayor 后):

   # 查看当前所有任务车队状态
   gt convoy list
   
   # 查看正在运行的智能体
   gt agents
   

3. 手动分配任务 (如果不使用 Mayor 自动编排):

   # 创建一个名为 "Fix bugs" 的车队
   gt convoy create "Fix bugs" gt-abc12 gt-def34
   
   # 将特定任务 (bead) 分配给指定项目的智能体
   gt sling gt-abc12 myproject
   
   # 检查状态
   gt convoy show
   

核心概念速查

• Town (~/gt): 总工作区目录。
• Rig: 项目容器，每个 Rig 对应一个 Git 仓库。
• Mayor: 主协调 AI，负责拆解任务和调度。
• Polecats: 执行具体任务的临时工作智能体。
• Beads: 持久化的任务单元 (类似 Issue)，格式如 gt-abc12。
• Convoy: 任务车队，将多个 Beads 打包分配给智能体执行。

现在，您已经准备好使用 Gas Town 协调多个 AI 智能体进行高效开发了！