steveyegge/gastown

# Gas Town **具备持久化工作追踪功能的 Claude Code 多智能体编排系统** ## 概述 Gas Town 是一个工作区管理器，允许您协调多个处理不同任务的 Claude Code 智能体。Gas Town 通过在基于 git 的 hooks 中持久化工作状态，避免了智能体重启时丢失上下文的问题，从而实现可靠的多智能体工作流。 ### 解决什么问题？ | 挑战 | Gas Town 解决方案 | | ------------------------------- | -------------------------------------------- | | 智能体重启时丢失上下文 | 工作状态持久化在基于 git 的 hooks 中 | | 手动协调智能体 | 内置邮箱、身份和交接机制 | | 4-10 个智能体变得混乱 | 可轻松扩展至 20-30 个智能体 | | 工作状态丢失在智能体内存中 | 工作状态存储在 Beads 账本中 | ### 架构 ``` graph TB Mayor[The Mayor
AI Coordinator] Town[Town Workspace
~/gt/] Town --> Mayor Town --> Rig1[Rig: Project A] Town --> Rig2[Rig: Project B] Rig1 --> Crew1[Crew Member
Your workspace] Rig1 --> Hooks1[Hooks
Persistent storage] Rig1 --> Polecats1[Polecats
Worker agents] Rig2 --> Crew2[Crew Member] Rig2 --> Hooks2[Hooks] Rig2 --> Polecats2[Polecats] Hooks1 -.git worktree.-> GitRepo1[Git Repository] Hooks2 -.git worktree.-> GitRepo2[Git Repository] 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) 🏗️ 项目容器。每个 rig 封装一个 git 仓库并管理其关联的智能体。 ### 成员 (Crew Members) 👤 您在 rig 中的个人工作区。您进行实际操作的地方。 ### 臭鼬 (Polecats) 🦨 具有持久身份但会话短暂的工作智能体。为任务而生，任务完成后会话结束，但身份和工作历史记录会保留。 ### Hooks 🪝 基于 git worktree 的智能体工作持久化存储。能够经受崩溃和重启。 ### 车队 (Convoys) 🚚 工作追踪单元。将分配给智能体的多个 beads 捆绑在一起。 ### Beads 集成 📿 基于 git 的问题追踪系统，将工作状态存储为结构化数据。 **Bead ID**（也称为 **issue ID**）使用前缀 + 5 个字符的字母数字格式（例如 `gt-abc12`, `hq-x7k2m`）。前缀表示项目的来源或 rig。像 `gt sling` 和 `gt convoy` 这样的命令接受这些 ID 来引用特定的工作项。术语“bead”和“issue”可互换使用——beads 是底层数据格式，而 issues 是存储为 beads 的工作项。 ## 安装 ### 前置条件 - **Go 1.23+** - [go.dev/dl](https://go.dev/dl/) - **Git 2.25+** - 用于 worktree 支持 - **Dolt 1.82.4+** - [github.com/dolthub/dolt](https://github.com/dolthub/dolt) - **beads (bd) 0.55.4+** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads) - **sqlite3** - 用于 convoy 数据库查询（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) ### 设置（Docker-Compose 方式见下文） ``` # 安装 Gas Town $ brew install gastown # Homebrew (recommended) $ npm install -g @gastown/gt # npm $ go install github.com/steveyegge/gastown/cmd/gt@latest # From source (macOS/Linux) # Windows (或如果 go install 失败)：手动 clone 并 build $ git clone https://github.com/steveyegge/gastown.git && cd gastown $ go build -o gt.exe ./cmd/gt $ mv gt.exe $HOME/go/bin/ # or add gastown to PATH # 如果使用 go install，请将 Go binaries 添加到 PATH (添加到 ~/.zshrc 或 ~/.bashrc) export PATH="$PATH:$HOME/go/bin" # 通过 git initialization 创建 workspace gt install ~/gt --git cd ~/gt # 添加你的第一个项目 gt rig add myproject https://github.com/you/repo.git # 创建你的 crew workspace gt crew add yourname --rig myproject cd myproject/crew/yourname # 启动 Mayor session (你的主界面) gt mayor attach ``` ### Docker Compose ``` export GIT_USER="" export GIT_EMAIL="" export FOLDER="/Users/you/code" docker compose up --build -d docker compose exec gastown zsh # or bash gt up gh auth login #if you want gh to work gt mayor attach ``` ## 快速入门指南 ### 入门 运行 ``` gt install ~/gt --git && cd ~/gt && gt config agent list && gt mayor attach ``` 然后告诉市长您想构建什么！ ### 基本工作流 ``` 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 ``` ### 示例：功能开发 ``` # 1. 启动 Mayor gt mayor attach # 2. 在 Mayor session 中，使用 bead IDs 创建 convoy gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human # 3. 将工作分配给 agent gt sling gt-abc12 myproject # 4. Track progress gt convoy list # 5. Monitor agents gt agents ``` ## 常见工作流 ### 市长工作流（推荐） **最适合：** 协调复杂的多问题工作 ``` flowchart LR Start([Start Mayor]) --> Tell[Tell Mayor
what to build] Tell --> Creates[Mayor creates
convoy + agents] Creates --> Monitor[Monitor progress
via convoy list] Monitor --> Done{All done?} Done -->|No| Monitor Done -->|Yes| Review[Review work] ``` **命令：** ``` # 连接到 Mayor gt mayor attach # 在 Mayor 中，创建 convoy 并让其进行 orchestrate gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify # Track progress gt convoy list ``` ### 最小模式（无 Tmux） 手动运行单个运行时实例。Gas Town 仅跟踪状态。 ``` gt convoy create "Fix bugs" gt-abc12 # Create convoy (sling auto-creates if skipped) gt sling gt-abc12 myproject # Assign to worker claude --resume # Agent reads mail, runs work (Claude) # 或：codex # 在 workspace 中启动 Codex gt convoy list # Check progress ``` ### Beads 公式工作流 **最适合：** 预定义的、可重复的流程 公式是嵌入在 `gt` 二进制文件中的 TOML 定义工作流（源码位于 `internal/formula/formulas/`）。 **公式示例** (`internal/formula/formulas/release.formula.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"] ``` **执行：** ``` # 列出可用的 formulas bd formula list # 使用 variables 运行 formula bd cook release --var version=1.2.0 # 创建 formula instance 以进行 tracking bd mol pour release --var version=1.2.0 ``` ### 手动 Convoy 工作流 **最适合：** 直接控制工作分配 ``` # 手动创建 convoy gt convoy create "Bug Fixes" --human # 将 issues 添加到现有 convoy gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x # 分配给特定 agents gt sling gt-m3k9p myproject/my-agent # 检查状态 gt convoy show ``` ## 运行时配置 Gas Town 支持多种 AI 编码运行时。针对每个 rig 的运行时设置位于 `settings/config.json` 中。 ``` { "runtime": { "provider": "codex", "command": "codex", "args": [], "prompt_mode": "none" } } ``` **注意：** - Claude 使用 `.claude/settings.json` 中的 hooks（通过 `--settings` 标志管理）来进行邮件注入和启动。 - 对于 Codex，请在 `~/.codex/config.toml` 中设置 `project_doc_fallback_filenames = ["CLAUDE.md"]`，以便读取角色指令。 - 对于没有 hooks 的运行时（例如 Codex），Gas Town 会在会话准备好后发送一个启动回退：`gt prime`，可选 `gt mail check --inject` 用于自主角色，以及 `gt nudge deacon session-started`。 ## 关键命令 ### 工作区管理 ``` gt install # Initialize workspace gt rig add # Add project gt rig list # List projects gt crew add --rig # Create crew workspace ``` ### 智能体操作 ``` gt agents # List active agents gt sling # Assign work to agent gt sling --agent cursor # Override runtime for this sling/spawn gt mayor attach # Start Mayor session gt mayor start --agent auggie # Run Mayor with a specific agent alias gt prime # Context recovery (run inside existing session) gt feed # Real-time activity feed (TUI) gt feed --problems # Start in problems view (stuck agent detection) ``` **内置智能体预设**：`claude`, `gemini`, `codex`, `cursor`, `auggie`, `amp` ### Convoy（工作追踪） ``` gt convoy create [issues...] # Create convoy with issues gt convoy list # List all convoys gt convoy show [id] # Show convoy details gt convoy add # Add issues to convoy ``` ### 配置 ``` # 设置自定义 agent command gt config agent set claude-glm "claude-glm --model glm-4" gt config agent set codex-low "codex --thinking low" # 设置默认 agent gt config default-agent claude-glm # 查看 config gt config show ``` ### Beads 集成 ``` bd formula list # List formulas bd cook # Execute formula bd mol pour # Create trackable instance bd mol list # List active instances ``` ## 编写公式 Gas Town 包含用于常见工作流的内置公式。请参阅 `internal/formula/formulas/` 获取可用的配方。 ## 活动流 `gt feed` 启动一个交互式终端仪表板，用于实时监控所有智能体的活动。它将 beads 活动、智能体事件和合并队列更新结合到一个三面板 TUI 中： - **智能体树** - 按 rig 和角色分组的所有智能体的层级视图 - **Convoy 面板** - 进行中和最近落地的 convoys - **事件流** - 按时间顺序排列的创建、完成、sling、nudge 等信息流 ``` gt feed # Launch TUI dashboard gt feed --problems # Start in problems view gt feed --plain # Plain text output (no TUI) gt feed --window # Open in dedicated tmux window gt feed --since 1h # Events from last hour ``` **导航：** `j`/`k` 滚动，`Tab` 切换面板，`1`/`2`/`3` 跳转到面板，`?` 获取帮助，`q` 退出。 ### 问题视图 在大规模（20-50+ 个智能体）情况下，在活动流中发现卡住的智能体变得很困难。问题视图通过分析结构化的 beads 数据，让需要人工干预的智能体浮出水面。 在 `gt feed` 中按 `p`（或使用 `gt feed --problems` 启动）以切换问题视图，该视图按健康状态对智能体进行分组： | 状态 | 条件 | |-------|-----------| | **GUPP 违规** | 已挂钩的工作长时间无进展 | | **停滞** | 已挂钩的工作进度减少 | | **僵尸** | 已死的 tmux 会话 | | **工作中** | 活跃，正常推进中 | | **空闲** | 无已挂钩的工作 | **干预按键**（在问题视图中）：`n` nudge 选定的智能体，`h` handoff（刷新上下文）。 ## 仪表板 Gas Town 包含一个用于监控工作区的 Web 仪表板。仪表板必须在 Gas Town 工作区 (HQ) 目录内运行。 ``` # 启动 dashboard (默认端口 8080) gt dashboard # 在自定义端口启动 gt dashboard --port 3000 # 启动并自动在 browser 中打开 gt dashboard --open ``` 仪表板为您提供工作区中发生的所有事情的单页概览：智能体、convoys、hooks、队列、issues 和升级。它通过 htmx 自动刷新，并包含一个命令面板，用于直接从浏览器运行 gt 命令。 ## 高级概念 ### 推进原理 Gas Town 使用 git hooks 作为推进机制。每个 hook 是一个带有以下功能的 git worktree： 1. **持久状态** - 工作在智能体重启后依然存活 2. **版本控制** - 所有更改都在 git 中跟踪 3. **回滚能力** - 恢复到任何先前的状态 4. **多智能体协调** - 通过 git 共享 ### Hook 生命周期 ``` stateDiagram-v2 [*] --> Created: Agent spawned Created --> Active: Work assigned Active --> Suspended: Agent paused Suspended --> Active: Agent resumed Active --> Completed: Work done Completed --> Archived: Hook archived Archived --> [*] ``` ### MEOW (Mayor-Enhanced Orchestration Workflow) MEOW 是推荐的模式： 1. **告诉市长** - 描述您想要什么 2. **市长分析** - 分解为任务 3. **创建 Convoy** - 市长创建带有 beads 的 convoy 4. **生成智能体** - 市长生成分配适当的智能体 5. **工作分发** - 通过 hooks 将 beads sling 给智能体 6. **进度监控** - 通过 convoy 状态进行跟踪 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` | | **人类** | Crew 成员 | 您的 crew 目录 | | **臭鼬** | 工作智能体 | 由市长生成分配 | | **Hook** | 持久化存储 | Git worktree | | **Convoy** | 工作追踪器 | `gt convoy` 命令 | ## 技巧 - **总是从市长开始** - 它被设计为您的主要接口 - **使用 convoys 进行协调** - 它们提供跨智能体的可见性 - **利用 hooks 进行持久化** - 您的工作不会消失 - **为重复任务创建公式** - 使用 Beads 配方节省时间 - **使用 `gt feed` 进行实时监控** - 观察智能体活动并尽早发现卡住的智能体 - **监控仪表板** - 在浏览器中获得实时可见性 - **让市长进行编排** - 它知道如何管理智能体 ## 故障排除 ### 智能体失去连接 检查 hooks 是否已正确初始化： ``` gt hooks list gt hooks repair ``` ### Convoy 卡住 强制刷新： ``` gt convoy refresh ``` ### 市长无响应 重启市长会话： ``` gt mayor detach gt mayor attach ``` ## 许可证 MIT License - 详见 LICENSE 文件

标签：AI 协调器, AI 工作空间管理, Claude Code, EVTX分析, EVTX分析, Git Worktree, Git 钩子, PyRIT, SOC Prime, 上下文保持, 任务调度, 分布式 AI, 基于 Git 的存储, 多智能体系统, 多智能体编排, 大语言模型工具, 工作流自动化, 开发工具, 持久化上下文, 数字员工, 日志审计, 智能体协作, 状态管理, 生产力工具, 网络安全研究, 自动化运维, 请求拦截