gastownhall/gastown

# Gas Town **适用于 Claude Code、GitHub Copilot 及其他 AI 智能体的多智能体编排系统，具备持久化工作追踪功能** ## 概述 Gas Town 是一个工作区管理器，可让您协调多个处理不同任务的 AI 编程智能体（Claude Code、GitHub Copilot、Codex、Gemini 等）。当智能体重启时，Gas Town 不会丢失上下文，而是将工作状态持久化保存在基于 git 的 hook 中，从而实现可靠的多智能体工作流。 ### 这解决了什么问题？ | 挑战 | Gas Town 的解决方案 | | ------------------------------- | -------------------------------------------- | | 智能体在重启时丢失上下文 | 工作状态持久化在基于 git 的 hook 中 | | 手动协调智能体 | 内置邮箱、身份标识和任务交接 | | 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 ``` ## 核心概念 ### 市长 (Mayor) 🎩 您的主要 AI 协调器。市长是一个 Claude Code 实例，拥有关于您的工作区、项目和智能体的完整上下文。**从这里开始** —— 只需告诉市长您想要完成什么即可。 ### 城镇 (Town) 🏘️ 您的工作区目录（例如 `~/gt/`）。包含所有项目、智能体和配置。 ### 钻机 (Rig) 🏗️ 项目容器。每个 rig 封装一个 git 仓库并管理其关联的智能体。 ### 船员 (Crew Member) 👤 您在 rig 中的个人工作区。供您进行实际动手操作的地方。 | 臭鼬 (Polecat) 🦨 具有持久身份但会话短暂的工作智能体。为任务而生，任务完成即结束会话，但其身份和工作历史会被保留。 ### 钩子 (Hook) 🪝 基于 git worktree 的智能体工作持久化存储。可在崩溃和重启后存活。 ### 车队 (Convoy) 🚚 工作追踪单元。捆绑分配给智能体的多个 bead。标记为 `mountain` 的 convoy 可获得自主停滞检测和智能跳过逻辑，专为史诗级规模的执行而设计。 ### Beads 集成 📿 基于 git 的问题追踪系统，将工作状态存储为结构化数据。 **Bead ID**（也称为 **issue ID**）使用前缀 + 5 个字符的字母数字格式（例如 `gt-abc12`、`hq-x7k2m`）。前缀表示项目的来源或 rig。像 `gt sling` 和 `gt convoy` 这样的命令接受这些 ID 来引用特定的工作项。“bead”和“issue”这两个术语可互换使用——beads 是底层数据格式，而 issues 是作为 beads 存储的工作项。 ### 分子 (Molecule) 🧬 协调多步骤工作的工作流模板。配方（TOML 定义）被实例化为带有已追踪步骤的分子。有两种模式：仅限根节点的 wisps（步骤在运行时具体化，轻量级）和 poured wisps（步骤作为子 wisps 具体化，带有检查点恢复功能）。参见 [Molecules](docs/concepts/molecules.md)。 ### 监控：Witness、Deacon、Dogs 🐕 三层看门狗系统保持智能体健康运行： - **Witness** - 每个 rig 的生命周期管理器。监控 polecats，检测卡死的智能体，触发恢复，管理会话清理。 - **Deacon** - 后台监督器，在所有 rig 中运行连续的巡逻周期。 - **Dogs** - 由 Deacon 派遣的基础设施工作者，负责维护任务（例如，Boot 负责分流）。 ### 炼油厂 (Refinery) 🏭 每个 rig 的合并队列处理器。当 polecats 通过 `gt done` 完成工作时，Refinery 会批量处理合并请求，运行验证门，并使用 Bors 风格的二分队列合并到 main 分支。失败的 MR 会被隔离，并进行内联修复或重新派遣。 ### 升级上报 (Escalation) 🚨 按严重性路由的 issue 升级。遇到阻碍的智能体会通过 `gt escalate` 进行上报，这会创建被追踪的 beads，通过 Deacon、Mayor 和（如果需要的话）Overseer 进行路由。严重性级别：CRITICAL (P0)、HIGH (P1)、MEDIUM (P2)。参见 [升级上报](docs/design/escalation.md)。 ### 调度器 (Scheduler) ⏱️ 用于 polecat 派遣的配置驱动容量管理器。通过在可配置的并发限制下批量派遣，防止 API 速率限制耗尽。默认为直接派遣；设置 `scheduler.max_polecats` 以启用带有守护进程的延迟派遣。参见 [调度器](docs/design/scheduler.md)。 ### 降神会 (Seance) 👻 会话发现与接续。通过 `.events.jsonl` 日志发现先前的智能体会话，使智能体能够查询其前任以获取早期工作的上下文和决策。 ``` gt seance # List discoverable predecessor sessions gt seance --talk -p "What did you find?" # One-shot question ``` ### 废土 (Wasteland) 🏜️ 通过 DoltHub 连接各个 Gas Town 的联合工作协调网络。Rigs 发布需求项，认领来自其他城镇的工作，提交完成证明，并通过多维印章赚取可移植的声誉。参见 [废土](docs/WASTELAND.md)。 ## 安装 ### 前置条件 - **Go 1.25+** - [go.dev/dl](https://go.dev/dl/) - **Git 2.25+** - 用于支持 worktree - **Dolt 1.82.4+** - 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** - 用于 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) - **GitHub Copilot CLI**（可选运行时）- [cli.github.com](https://cli.github.com)（需要 Copilot 席位） ### 设置（以下为 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 (Linux only) # macOS: go install 生成的未签名二进制文件会被 macOS SIGKILL。 # 使用 brew install（见上文）或安装 Dolt 并使用 make clone/build： $ brew install dolt $ git clone https://github.com/steveyegge/gastown.git && cd gastown $ make build && mv gt $HOME/go/bin/ # 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 # 添加你的第一个 project 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" export DASHBOARD_PORT=8080 # optional, host port for the web dashboard docker compose build # only needed on first run or after code changes docker compose up -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 ID 创建 convoy gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human # 3. 将工作分配给 agent gt sling gt-abc12 myproject # 4. 跟踪进度 gt convoy list # 5. 监控 agents gt agents ``` ## 常见工作流 ### 市长工作流（推荐） **最适合：** 协调复杂、涉及多个 issue 的工作 ``` 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 # 跟踪进度 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 实例以进行跟踪 bd mol pour release --var version=1.2.0 ``` ### 手动 Convoy 工作流 **最适合：** 直接控制工作分配 ``` # 手动创建 convoy gt convoy create "Bug Fixes" --human # 向现有 convoy 添加 issues gt convoy add hq-cv-abc gt-m3k9p gt-w5t2x # 分配给特定 agents gt sling gt-m3k9p myproject/my-agent # 检查 status gt convoy show ``` ## 运行时配置 Gas Town 支持多种 AI 编程运行时。每个 rig 的运行时设置位于 `settings/config.json` 中。 ``` { "runtime": { "provider": "codex", "command": "codex", "args": [], "prompt_mode": "none" } } ``` **说明：** - Claude 使用 `.claude/settings.json`（通过 `--settings` 标志管理）中的 hooks 来进行邮件注入和启动。 - 对于 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`。 - **GitHub Copilot** (`copilot`) 是一个使用 `--yolo` 实现自主 模式的内置预设。它使用 `.github/hooks/gastown.json` 中的可执行生命周期 hooks（事件与 Claude 相同：`sessionStart`、`userPromptSubmitted`、`preToolUse`、`sessionEnd`）。它使用 5 秒的就绪延迟而不是提示检测。需要 Copilot 席位和组织级别的 CLI 策略。参见 [docs/INSTALLING.md](docs/INSTALLING.md)。 ## 核心命令 ### 工作区管理 ``` 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`、`opencode`、`copilot`、`pi`、`omp` ### 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 ``` ### 监控与健康 ``` gt escalate -s HIGH "description" # Escalate a blocker gt escalate list # List open escalations gt scheduler status # Show scheduler state gt seance # Discover previous sessions gt seance --talk # Query a predecessor session ``` ### Beads 集成 ``` bd formula list # List formulas bd cook # Execute formula bd mol pour # Create trackable instance bd mol list # List active instances ``` ### 废土联邦 ``` gt wl join # Join a wasteland gt wl browse # View wanted board gt wl claim # Claim work gt wl done --evidence # Submit completion ``` ## 编写配方 Gas Town 包含用于常见工作流的内置配方。请参阅 `internal/formula/formulas/` 获取可用的配方。 ## 活动流 `gt feed` 会启动一个交互式终端仪表板，用于实时监控所有智能体的活动。它将 beads 活动、智能体事件和合并队列更新组合成一个三面板的 TUI： - **智能体树** - 按 rig 和角色分组的所有智能体的层级视图 - **Convoy 面板** - 进行中和最近着陆的 convoy - **事件流** - 按时间排列的创建、完成、投递、提醒等动态 ``` 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` 提醒选定的智能体，`h` 进行交接（刷新上下文）。 ## 仪表板 Gas Town 包含一个用于监控您工作区的 Web 仪表板。该仪表板 必须在 Gas Town 工作区 (HQ) 目录内运行。 ``` # 启动 dashboard（默认端口 8080） gt dashboard # 在自定义端口启动 gt dashboard --port 3000 # 启动并自动在浏览器中打开 gt dashboard --open ``` 该仪表板为您提供了工作区中所有动态的 单页概览：智能体、convoy、hooks、队列、issues 和升级上报。它 通过 htmx 自动刷新，并包含一个命令面板，可直接从浏览器运行 gt 命令。 ## 监控与健康 Gas Town 使用三层看门狗链来大规模保持智能体的健康： ``` Daemon (Go process) ← heartbeat every 3 min └── Boot (AI agent) ← intelligent triage └── Deacon (AI agent) ← continuous patrol └── Witnesses & Refineries ← per-rig agents ``` ### Witness（每个 Rig） 每个 rig 都有一个 Witness 来监控其 polecats。Witness 检测卡死的智能体，触发恢复（提醒或交接），管理会话清理，并追踪完成状态。Witness 委派工作而不是直接执行工作。 ### Deacon（跨 Rig） Deacon 在所有 rig 中运行连续的巡逻周期，检查智能体健康状况，派遣 Dogs 执行维护任务，并升级上报单个 Witness 无法解决的问题。 ### 升级上报 当智能体遇到阻碍时，它们会进行升级上报而不是等待： ``` gt escalate -s HIGH "Description of blocker" gt escalate list # List open escalations gt escalate ack # Acknowledge an escalation ``` 升级上报会根据严重性通过 Deacon -> Mayor -> Overseer 进行路由。参见 [升级上报设计](docs/design/escalation.md)。 ## 合并队列 (Refinery) Refinery 通过二分合并队列处理已完成的 polecat 工作： 1. Polecat 运行 `gt done` -> 分支被推送，创建 MR bead 2. Refinery 批量处理待处理的 MR 3. 在合并堆栈上运行验证门 4.为绿色：批处理中的所有 MR 合并到 main 5. 如果为红色：二分查找以隔离失败的 MR，合并正常的那些 这是一个 Bors 风格的合并队列 —— polecats 永远不会直接推送到 main。 ## 调度器 调度器控制 polecat 的派发容量，以防止 API 速率限制耗尽： ``` gt config set scheduler.max_polecats 5 # Enable deferred dispatch (max 5 concurrent) gt scheduler status # Show scheduler state gt scheduler pause # Pause dispatch gt scheduler resume # Resume dispatch ``` 默认模式（`max_polecats = -1`）通过 `gt sling` 立即派遣。当设置了限制时，守护进程会增量进行派遣，并遵循容量限制。参见 [调度器设计](docs/design/scheduler.md)。 ## 降神会 发现并查询先前的智能体会话： ``` gt seance # List discoverable predecessor sessions gt seance --talk # Full context conversation with predecessor gt seance --talk -p "Question?" # One-shot question to predecessor ``` 降神会通过 `.events.jsonl` 日志发现会话，使智能体能够恢复早期工作的上下文和决策，而无需重新阅读整个代码库。 ## 废土联邦 废土是一个联合工作协调网络，通过 DoltHub 连接多个 Gas Town： ``` gt wl join hop/wl-commons # Join a wasteland gt wl browse # View wanted board gt wl claim # Claim a wanted item gt wl done --evidence # Submit completion with evidence gt wl post --title "Need X" # Post new wanted item ``` 完成任务可通过多维印章（质量、速度、复杂度）赚取可移植的声誉。参见 [废土指南](docs/WASTELAND.md)。 ## 遥测 (OpenTelemetry) Gas Town 将所有智能体操作作为结构化日志和指标发送到任何兼容 OTLP 的后端（默认为 VictoriaMetrics/VictoriaLogs）： ``` # 配置 OTLP endpoints export GT_OTEL_LOGS_URL="http://localhost:9428/insert/jsonline" export GT_OTEL_METRICS_URL="http://localhost:8428/api/v1/write" ``` **发出的事件：** 会话生命周期、智能体状态更改、bd 调用及其持续时间、邮件操作、sling/nudge/done 工作流、polecat 生成/移除、公式实例化、convoy 创建、守护进程重启等。 **指标包括：** `gastown.session.starts.total`、`gastown.bd.calls.total`、`gastown.polecat.spawns.total`、`gastown.done.total`、`gastown.convoy.creates.total` 等。 有关完整的事件结构，请参见 [OTEL 数据模型](docs/otel-data-model.md) 和 [OTEL 架构](docs/design/otel/)。 ## 高级概念 ### 推进原则 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（市长增强编排工作流） MEOW 是推荐的模式： 1. **告诉市长** - 描述您想要什么 2. **市长分析** - 将其分解为各项任务 3. **创建 Convoy** - 市长创建带有 beads 的 convoy 4. **生成智能体** - 市长生成分适的智能体 5. **工作分配** - Beads 通过 hooks 投递给智能体 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代码助手, AI协调器, Claude Code, Codex, EVTX分析, Gemini, Git Hook, GitHub Copilot, Git Worktree, PyRIT, Python安全, 上下文持久化, 任务状态追踪, 任务编排, 任务调度, 协作系统, 多智能体系统, 威胁情报, 工作区管理, 工作流自动化, 开发者工具, 提示词工程, 数字取证, 日志审计, 用户代理, 策略决策点, 网络安全研究, 自动化脚本, 请求拦截