Gas Town Hooks 管理指南基于 base/overrides 模型的集中式 Agent 生命周期钩子体系【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastownGas Towngastown是一个多 Agent 工作区管理器其 Hooks 体系为所有 Agent 角色crew、witness、refinery、polecat、mayor、deacon 等提供集中式的上下文注入与生命周期钩子管理一份共享的 base 配置加上按角色、按 rig 叠加的 override统一生成各角色目录下的.claude/settings.json再通过--settings标志传递给 Claude Code。读完本文你将掌握 Gas Town Hooks 的架构分层、merge 语义、全部gt hooks子命令用法、注册表registry机制以及如何用gt doctor校验同步状态并能直接在自己的 Gas Town 工作区里配置、排障与二次扩展。一、为什么需要集中式 Hooks 管理Gas Town 的每个工作区都运行着多种角色的 Agent概念说明见 docs/concepts/每种角色需要不同的生命周期钩子SessionStart 时注入上下文、Stop 时记录成本、PreToolUse 时拦截危险命令……如果每个角色的配置文件各自维护改动一处策略就要手工同步十几个文件极易漂移。Gas Town 的做法是单一事实来源single source of truth 派生文件维护一份共享 base 配置与少量按角色/按 rig 的 override通过gt hooks sync统一重新生成所有目标的.claude/settings.json生成的配置放在 gastown 管理的父目录而非每个 worktree 内部通过 Claude Code 的--settings path参数按独立优先级层级加载与项目自身的设置加性合并从而保持客户仓库干净。这一设计的核心实现在 internal/hooks/config.go包注释即说明manages a base hook configuration and per-role/per-rig overrides, generating .claude/settings.json files for all agents。不同 Agent 的钩子机制并非所有 Agent 都用settings.jsonGas Town 按 Agent 类型采用不同注入机制Agent钩子机制管理文件Claude Code、Geminisettings.json生命周期钩子role/.claude/settings.jsonOpenCodeJS 插件workDir/.opencode/plugins/gastown.jsGitHub CopilotJSON 生命周期钩子workDir/.github/hooks/gastown.jsonCodex 及其他启动 nudge 兜底无文件仅 nudgeGitHub Copilot 说明Copilot CLI 通过.github/hooks/gastown.json支持完整的可执行生命周期钩子sessionStart、userPromptSubmitted、preToolUse、sessionEnd与 Claude Code 的生命周期覆盖范围相同只是采用 Copilot 的 JSON 格式而非 Claude 的settings.json格式。下文gt hooks命令仅适用于 Claude Code及 Gemini。各 Agent 的钩子模板集中内嵌在 internal/hooks/templates/ 下claude、gemini、opencode、copilot、cursor、codex、pi、omp、vibe 各有目录由通用安装器 internal/hooks/installer.go 通过//go:embed templates/*读取并渲染。二、架构base、overrides 与 merge 策略配置文件布局~/.gt/hooks-base.json ← 共享 base 配置所有 Agent ~/.gt/hooks-overrides/ ├── crew.json ← 所有 crew worker 的 override ├── witness.json ← 所有 witness 的 override ├── gastown__crew.json ← 特指 gastown rig 的 crew override └── ...其中gastown__crew.json的__是目标键gastown/crew中/的文件系统安全替身见 config.go 的OverridePath实现strings.ReplaceAll(target, /, __)。若设置了环境变量GT_HOME则配置目录改为$GT_HOME/.gt读取时采用级联目录搜索gtConfigDirs$GT_HOME/.gt优先~/.gt作为兜底二进制内置默认值作为隐式最后回退config.go。Merge 策略base → role → rigrole越具体越优先以目标gastown/crew为例从 base 配置开始应用crewoverride若存在应用gastown/crewoverride若存在。GetApplicableOverrides的实现印证了这一点gastown/crew返回[crew, gastown/crew]beads/witness返回[witness, beads/witness]config.go。内置角色默认 overrideDefaultOverrides会先于磁盘上的 override 应用磁盘 override 再叠加其上因此用户可以覆盖内置策略config.go。生成的目标Generated targets每个 rig 在共享父目录而非每个 worktree生成设置目标路径Override KeyCrew共享rig/crew/.claude/settings.jsonrig/crewWitnessrig/witness/.claude/settings.jsonrig/witnessRefineryrig/refinery/.claude/settings.jsonrig/refineryPolecats共享rig/polecats/.claude/settings.jsonrig/polecatsTown 级目标mayor/.claude/settings.jsonkey:mayordeacon/.claude/settings.jsonkey:deacon此外若存在deacon/dogs/boot/目录gitignored 的可选看门狗 Agent也会注册boot目标config.go。目标发现逻辑在DiscoverTargets中扫描 town 根目录下具备crew/、witness/、polecats/、refinery/子目录的 rig并为每个角色生成对应Targetconfig.goDiscoverRoleLocations则返回与具体 Agent 无关的角色目录列表供非 Claude Agent 的同步使用config.go。设置如何传递给 Claude Code生成的settings.json通过--settings path传给 Claude Code。注意同目录下 crew 成员共享一份 settings 文件polecats 亦然。同步时保留非 hooks 字段如editorMode、enabledPlugins等由SettingsJSON.Extra原始字段映射在UnmarshalSettings/MarshalSettings中实现往返保留config.go这是文档所述Preserves non-hooks fields的源码级保证。三、命令速查gt hooks全子命令gt hooks根命令挂在GroupConfig组下internal/cmd/hooks.go子命令如下。gt hooks sync— 重新生成全部 settings从 base overrides 重新生成所有.claude/settings.json保留非 hooks 字段editorMode、enabledPlugins 等。gt hooks sync # 写入所有 settings 文件 gt hooks sync --dry-run # 预览变更不实际写入同步核心SyncManagedClaudeSettingsconfig.go的判定逻辑文件已存在、hooks 部分与预期一致且包含 Claude 启动默认字段时返回SyncUnchanged否则 dry-run 返回SyncCreated/SyncUpdated实际写入则通过atomicfile.WriteFile以 0600 权限原子写文件并强制写入enabledPlugins[beadsbeads-marketplace] false。如果存在解析失败的 settings 文件会返回SettingsIntegrityErrorfail-closed 完整性违规。gt hooks diff— 预览差异显示sync将要做的改动而不写入任何内容。gt hooks diff # 显示差异 gt hooks diff --no-color # 纯文本输出gt hooks base— 编辑共享 base 配置在$EDITOR中打开 base 配置缺省回退vi。gt hooks base # 打开编辑器 gt hooks base --show # 打印当前 base 配置实现见 internal/cmd/hooks_base.go文件不存在时先用DefaultBase()创建默认 base编辑结束后重新LoadBase()校验 JSON 合法性并提示执行gt hooks sync传播变更。gt hooks override target— 编辑角色/rig 的 overridegt hooks override crew # 编辑 crew override gt hooks override gastown/witness # 编辑 gastown rig 的 witness override gt hooks override crew --show # 打印当前 override目标支持角色名crew、witness、refinery、polecats、mayor、deacon或rig/role组合polecat单数别名会被规范化为polecatsNormalizeTargetconfig.go。gt hooks list— 列出全部受管位置显示所有受管的 settings 位置及其同步状态。gt hooks list # 显示所有目标 gt hooks list --json # 机器可读输出gt hooks scan— 扫描工作区既有 hooks读取当前 settings 文件并列出其中的 hooks。gt hooks scan # 列出所有 hooks gt hooks scan --verbose # 显示 hook 命令 gt hooks scan --json # JSON 输出gt hooks init— 从现有配置引导 base分析所有现有 settings提取公共 hooks 作为 base并为每个目标的差异生成 override。gt hooks init # 引导 base 与 overrides gt hooks init --dry-run # 预览将要创建的内容仅在尚无 base 配置时可用已有 base 请用gt hooks base编辑。gt hooks registry/gt hooks install— 注册表浏览与安装gt hooks registry # 列出可用 hooks默认只列启用的 gt hooks registry --all # 含禁用 hooks gt hooks registry --verbose # 显示命令与 matcher gt hooks install hook-id # 安装 hook 到 base 配置注册表位于 town 根的hooks/registry.toml实现见 internal/cmd/hooks_registry.go 的LoadRegistryTOML 结构为[hooks.id]字段包括description、event、matchers、command、roles、scope、enabled。四、注册表现状7 个内置 Hook注册表~/gt/hooks/registry.toml当前定义 7 个 hooks其中 5 个默认启用Hook事件启用角色pr-workflow-guardPreToolUse是crew, polecatsession-primeSessionStart是allpre-compact-primePreCompact是allmail-checkUserPromptSubmit是allcosts-recordStop是crew, polecat, witness, refineryclone-guardPreToolUse否crew, polecatdangerous-command-guardPreToolUse是crew, polecatclone-guard默认关闭需用gt hooks install clone-guard显式启用。settings.json 中已存在但尚未入册的 hooks以下 hooks 出现在 settings.json 中但尚未加入 registrybd init guardgastown/crew、beads/crew— 阻止在.beads/内执行bd init*mol patrol guardsgastown 各角色— 阻止创建持久化 patrol 分子必须使用 wispstmux clear-historygastown 根— 会话启动时清除终端历史SessionStart .beads/ 验证gastown/crew、beads/crew— 校验 CWD内置角色默认 override源码级佐证除注册表外config.go 的DefaultOverrides()内置了角色级策略磁盘 override 会叠加其上polecatsStop时执行gt tap polecat-stop-checkgas-lob解决空闲 polecat问题——polecat 干完活却忘记在会话结束前调用gt done该命令幂等先检查心跳状态与分支提交再决定是否执行gt done。crewPreCompact时执行gt handoff --cycle --reason compactiongt-op78——上下文压缩有损改为用全新会话替换收集状态 → 发送 handoff 邮件 → 重新 spawn 面板后继会话通过 SessionStart 钩子gt prime --hook接管被挂钩的工作。witnessPreToolUse拦截bd mol pour类命令patrol-formula-guardgt-e47hxn——patrol 公式必须使用 wisps 而非持久化分子否则会造成跨会话累积的永久 patrol 分子。deacon拦截for/seq批量循环、while true/while :无界循环patrol 必须单周期 gt patrol report或gt handoff同样拦截bd mol pourpatrol 类命令。bootPreToolUse拦截裸tmux send-keys——会在 Deacon TUI 里留下未提交文本应改用gt nudge --modeimmediate deacon message不加--force。refinery与 witness 相同的 patrol-formula-guardrefinery 也运行 patrol必须用 wisps。五、设计决策注册表是目录catalog不是事实来源决策注册表只是目录不是事实来源。注册表registry.toml列出有哪些hooks 可用base/overrides 系统~/.gt/hooks-base.json~/.gt/hooks-overrides/定义在哪里、对谁生效。gt hooks install把注册表中的 hook 拷贝进 base/overrides 配置。这一分离带来按机器定制不同机器 PATH 不同base 可在机器本地调整而不污染共享注册表按角色覆盖per-role override 无需动共享注册表清晰区分存在哪些 hooks与哪些 hooks 在哪里生效。一句话概括注册表是菜单base/overrides 是点单。六、Per-matcher 合并语义重点当 override 与 base 条目具有相同 matcher时override整体替换base 条目matcher 不同则追加override 条目带空 hooks 列表表示删除该 matcher。base 示例{ SessionStart: [ { matcher: , hooks: [{ type: command, command: gt prime }] } ] }witness 的 override{ SessionStart: [ { matcher: , hooks: [{ type: command, command: gt prime --witness }] } ] }结果witness 得到gt prime --witness而非gt prime同 matcher 替换。源码实现位于 internal/hooks/merge.go 的mergeEntries先按 matcher 建索引遍历 base 条目时若命中 override 的 matcher 则替换空 hooks 列表则剔除再追加 override 中新增 matcher 的条目applyOverride对全部 8 种事件类型PreToolUse、PostToolUse、SessionStart、Stop、PreCompact、UserPromptSubmit、WorktreeCreate、WorktreeRemove分别执行该合并。loadConfig还会校验同一事件类型内 matcher 唯一validateUniqueMatchersconfig.go。ComputeExpected的完整合并链config.go磁盘 base 缺失时用DefaultBase()磁盘 base 存在时先用Merge(DefaultBase(), base)做回填保证新增的事件类型自动补上、同时保留用户定制再逐层应用内置DefaultOverrides与磁盘 override。默认 base 配置无 base 配置时系统使用如下合理默认值DefaultBase()config.goSessionStartgt prime --hookPreCompactgt prime --hookUserPromptSubmitgt mail check --injectStopgt costs record 同时内置 PreToolUse 安全护栏gh pr create*、git checkout -b*、git switch -c*触发gt tap guard pr-workflowrm -rf /*、git push --force*、git push -f*触发gt tap guard dangerous-command。命令中的gt前缀会被gtCommand解析为resolveGTBinary()的绝对路径优先os.Executable()其次 PATH 查找见 config.go。Claude 模板 templates/claude/settings-autonomous.json 展示了渲染后的完整形态{{GT_BIN}}占位符会被替换为 gt 二进制绝对路径并带skipDangerousModePermissionPrompt: true、hasCompletedOnboarding: true、theme: dark、permissions.defaultMode: bypassPermissions等非交互会话所需的启动默认字段。七、已知缺口Known Gaps注册表未覆盖全部活跃 hooks— settings.json 中的多个 hooksbd-init-guard、mol-patrol-guard、tmux-clear、cwd-validation不在registry.toml中应补录以便gt hooks install统一管理。gt tap命令目前只有 pr-workflow— tap 框架仅实现了一个 guard注册表中引用的gt tap guard dangerous-command尚不存在。建议实现顺序dangerous-command → bd-init → mol-patrol → audit git-push。没有gt tap disable/enable便捷命令— 按 worktree 启停可通过 override 机制实现gt hooks override配空 hooks 列表但暂无便捷封装。私有 hookssettings.local.json— Claude Code 支持settings.local.json做个人覆盖Gas Town 暂不管理低优先级因为 Gas Town 主要由 Agent 操作。Hook 排序— 当前无需处理merge 链base → override产生确定性顺序per-matcher 合并保证每个事件类型只有一个条目。八、与其它子系统的集成gt rig add新建 rig 时会自动为新 rig 的所有目标crew、witness、refinery、polecats同步 hooks。gt doctorhooks-sync检查会校验所有 settings 文件是否与gt hooks sync将生成的内容一致用gt doctor --fix自动修复不同步的目标。检查实现位于 internal/doctor/hooks_sync_check.go含测试 internal/doctor/hooks_sync_check_test.go。模板安装与自动升级internal/hooks/installer.go 的InstallForRole为各 Agent 预置preset安装钩子/设置文件文件已存在且不含过期模式则不覆盖保护 sync 合并结果检测到过期模式如旧版export PATH格式会破坏 Gemini CLI 的 hook runner则自动升级SyncForRole是显式同步路径gt hooks sync对 OpenCode、Copilot、Pi、OMP 等模板型 Agent 使用不应用于 Claude 的 JSON merge 路径否则会覆盖合并后的 overrides。所有写入均经atomicfile.WriteFile原子完成临时文件 rename防止并发 polecat 启动时交错写入出半截 JSON见 gh#3500。resolveTemplate根据角色是否 autonomoushookutil.IsAutonomousRole选择settings-autonomous.json或settings-interactive.json模板。九、典型工作流工作流 1新 rig 上线后验证 hooksgt hooks list # 查看所有受管目标与同步状态 gt hooks diff # 若某目标不同步先看差异 gt hooks sync # 统一重新生成 gt doctor # 全量体检确认 hooks-sync 检查通过工作流 2为某个角色定制策略gt hooks override crew # 编辑 crew 的 override gt hooks override gastown/witness # 编辑特定 rig 的 witness override gt hooks override crew --show # 确认当前内容 gt hooks sync # 传播变更要禁用某 matcher在 override 中给该 matcher 配空 hooks 列表即可显式删除。工作流 3从注册表安装新 hookgt hooks registry --all # 查看全部 hook含禁用的 gt hooks install clone-guard # 安装到 base 配置 gt hooks base --show # 确认已生效 gt hooks sync # 传播到所有目标工作流 4迁移既有配置到集中管理gt hooks init --dry-run # 先预览将要生成的 base 与 overrides gt hooks init # 确认无误后执行引导 gt hooks sync # 按新 base/overrides 统一生成十、总结Gas Town 的 Hooks 体系用一个base per-role/per-rig overrides的轻量模型解决了多 Agent 工作区中钩子配置的漂移问题注册表回答有哪些 hooksbase/overrides 回答对谁生效gt hooks sync负责把结果确定性地派生到各角色的.claude/settings.json并通过--settings以独立层级传给 Claude Code。per-matcher 的替换/追加/删除三语义让 override 既简洁又精确gt doctor的 hooks-sync 检查则保证派生文件始终与策略一致。结合内置的 pr-workflow、dangerous-command 护栏与各角色的 patrol-formula-guard、session-cycling 等默认策略这套体系为 Gas Town 的自动化 Agent 编排提供了可靠、可审计、可扩展的执行保障。进一步阅读docs/HOOKS.md — Hooks 管理官方文档本文基础internal/hooks/config.go — 配置结构、merge 与目标发现核心实现internal/hooks/merge.go — per-matcher 合并语义实现internal/hooks/installer.go — 多 Agent 模板安装与自动升级internal/hooks/templates/ — 各 Agent 的钩子/设置模板internal/cmd/hooks.go、internal/cmd/hooks_base.go、internal/cmd/hooks_registry.go —gt hooks命令实现internal/doctor/hooks_sync_check.go —gt doctor的 hooks-sync 一致性检查internal/hooks/config_test.go、internal/hooks/merge_test.go、internal/hooks/sync_test.go — merge 与同步语义的测试佐证【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考