Gas Town Mountain-Eater 设计解析：基于 Convoy 的自主史诗研磨与卡死自愈机制

Gas Town Mountain-Eater 设计解析：基于 Convoy 的自主史诗研磨与卡死自愈机制

【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown

本文聚焦 Gas Town（multi-agent workspace manager）中用于大型史诗自主执行的设计文档 mountain-eater.md。该文档提出了在机械式 ConvoyManager 之上叠加"判断层"（Mountain-Eater）的完整方案：用mountain标签作为选入机制，由 Witness 跟踪 polecat 失败并自动跳过、Deacon Dog 周期性审计进度并派发调查、Mayor 负责人工级升级通知。读完本文，你将掌握"四层研磨"架构的工作原理、gt mountain命令族的完整用法、失败跳过与恢复的语义，以及哪些部分已在仓库中落地（internal/cmd/mountain.go、internal/witness/mountain.go），哪些仍处于设计阶段。

1. 背景与问题：为什么大型史诗会"卡死"

Gas Town 已经拥有自主史诗执行的几乎所有机械零件：

然而用户报告大型史诗"卡住"：创建一座"任务山"（mountain of beads）、启动 convoy、离开数小时，回来发现 convoy 停在 40% 且没有任何原因提示。

根因：ConvoyManager 是机械式的。它只会在某个 issue 关闭时喂入下一个就绪 issue，无法推理失败模式、无法做跳过决策、无法智能升级。当一个 polecat 在同一个 issue 上反复失败时，机械系统会无限次地重新 sling 它；当依赖图之外存在微妙的阻塞条件时，没有任何组件会发现。

Mountain-Eater 在机械喂给之上增加了一层判断层（judgment layer）——由 Agent 驱动的停滞检测、失败 N 次后跳过、智能升级和完成通知。

2. 核心设计原则：没有任何 Agent 持有主线

单协调者方案失败的根源是滞后（hysteresis）：任何维持"我在驱动这个史诗"循环的 Agent 都会在压缩（compaction）时丢失主线。即使史诗被挂钩，重新 prime 的 Agent 也不会记得协调上下文。

Mountain-Eater 完全绕开了这个问题：

• 史诗本身就是主线（The epic IS the thread）——beads 就是状态；
• 没有 Agent 需要记住任何东西——每次检查都从状态中全新发现；
• Dog 每次带来全新上下文——从构造上杜绝 hysteresis；
• 标签触发巡逻行为——不需要持久的协调者。

这与 Gas Town 的核心原则一脉相承：

• ZFC（Zero Formal Coordination）：Agent 做决策，Go 负责传输。ConvoyManager 是传输层；Dog 做判断。
• NDI（No Designated Identity）：任何 Dog 都能检查任何一座山。不同 Agent，相同结果。
• Discover, Don't Track：bd ready --epic=X与 convoy 状态都从 beads 推导，而非追踪。
• Float over Integer：卡住的 issue 不会让整座山停摆——工作会绕过它继续流动。

3. 架构总览：四层研磨（Four-Layer Grinding）

Layer 0: CONVOY MANAGER (mechanical, Go daemon —— 已构建) 事件驱动喂给 + 滞留扫描 处理快乐路径：issue 关闭 → 喂入下一个就绪 issue Layer 1: WITNESS (reactive, per-rig —— 增强) mountain convoy issue 的 polecat 失败跟踪 同一 issue 失败 3 次及以上 → 标记 blocked、跳过、喂下一个 Layer 2: DEACON DOG (periodic, cross-rig —— 新增) "自上次检查以来这座山有进展吗？" 全新 Dog 在完整上下文下调查停滞 做出判断：跳过、重构、升级 停滞与完成时通知 Mayor Layer 3: MAYOR (strategic, user-facing —— 增强) 接收来自 Layer 2 的停滞升级 跨 rig 判断 完成或不可恢复停滞时通知用户

Layer 0已存在，处理约 80% 的 convoy 执行。Layer 1-2就是 Mountain-Eater——处理那 20% 卡住的部分。Layer 3是约 2% 需要人工判断时的升级路径。

为什么要四层？

冗余监控本身就是韧性（redundant monitoring is resilience）：

• 如果 Witness 漏掉一次完成（崩溃、压缩），ConvoyManager 会在 5 秒事件轮询中补上；
• 如果 ConvoyManager 反复喂入坏 issue，Witness 会抓住失败模式；
• 如果两者都漏掉停滞，Deacon Dog 会在下一个巡逻周期补上。

每一层都独立运作，并从 beads 中发现状态，不存在单点故障。这与 convoy 规范文档 中"冗余观察（redundant observation）"的要求一致——该规范指出多个 Agent 都能检测完成，确保没有单一失败会阻断循环。

4.mountain标签：选入机制与命令入口

一座 mountain 就是带有mountain标签的 convoy。不需要新的实体类型，不需要新的数据库 schema。标签本身就是 Layer 1-2 的选入（opt-in）开关。

# 在史诗上激活 Mountain-Eater gt mountain <epic-id> # 内部执行序列： # 1. gt convoy stage <epic-id> ← 校验 DAG、计算波次 # 2. bd update <convoy> --add-label mountain ← 触发判断层 # 3. gt convoy launch <convoy-id> ← 派发 Wave 1，ConvoyManager 接管 # 查看进度 gt mountain status [epic-id|convoy-id] # 暂停/恢复（保留标签，停止/恢复派发） gt mountain pause <epic-id|convoy-id> gt mountain resume <epic-id|convoy-id> # 取消（移除标签，留下 convoy 供手动管理） gt mountain cancel <epic-id|convoy-id>

普通 convoy（无mountain标签）的行为与今天完全一致。mountain标签把 convoy 选入增强的停滞检测、失败 N 次后跳过、以及主动进度监控。

何时用 Mountain，何时用普通 Convoy

源码视角：gt mountain的真实实现

该 CLI 已在仓库中落地，核心逻辑位于 internal/cmd/mountain.go。runMountain的流程与设计文档完全对应：

1. 校验输入是史诗：调用bdShow(epicID)，若非epic类型则报错mountains require an epic（mountain.go）；
2. Stage：collectBeads收集 beads、buildConvoyDAG构建 DAG、detectErrors/detectWarnings做结构校验、computeWaves计算波次（mountain.go）；
3. 创建 staged convoy：标题自动加前缀"Mountain: "（title := "Mountain: " + result.Title）；
4. 加标签：通过bdAddLabelTown(convoyID, "mountain")在 town beads 库执行bd update <convoy> --add-label=mountain；
5. Launch：transitionConvoyToOpen转换状态并dispatchWave1派发第一波。

命令还支持--force（带警告继续启动）与--json（机器可读输出）两个 flag（mountain.go）。暂停/恢复通过mountain:paused标签实现：pause加标签、resume移除标签，cancel则移除mountain标签并尽力移除mountain:paused（mountain.go）。resolveMountainID同时接受 epic-id 或 convoy-id 作为输入（mountain.go）。

5. Layer 1：Witness 失败跟踪（已实现）

问题

当一个 polecat 在 mountain issue 上失败时，ConvoyManager 的滞留扫描会重新 sling 它。如果 issue 有根本性问题（描述糟糕、任务不可能完成、缺少上下文），就会形成无限 sling-失败循环。

增强

Witness 已经在监控 polecat 完成情况。增强点：对属于 mountain convoy 的 issue 增加失败跟踪：

WITNESS PATROL — mountain failure tracking: For each polecat that exited without completing its issue: issue = polecat's hooked bead convoy = tracking convoy for this issue (if any) if convoy has "mountain" label: increment failure count for this issue (stored as issue note or label) if failure_count >= 3: bd update <issue> --status=blocked --add-label mountain:skipped bd update <issue> --notes "Skipped by Mountain-Eater after 3 polecat failures" log: "Mountain: skipped <issue> after 3 failures" # ConvoyManager's next feed will skip this issue (blocked status) # and feed the next ready issue instead

失败计数存储：使用形如mountain:failures:3的标签挂在 issue 上。标签廉价、可查询、在bd show中可见。无需新 schema。

为什么是 Witness 而不是 ConvoyManager？Witness 已经观察 polecat 生命周期，它知道 polecat 是成功完成还是崩溃了。ConvoyManager 只看到 issue 状态变化——它无法区分"polecat 失败了"和"polecat 还在工作"。

源码证据：internal/witness/mountain.go

Layer 1 已在仓库中完整实现，位于 internal/witness/mountain.go：

• 阈值常量MountainMaxFailures = 3，且被导出供测试使用（mountain.go）；
• trackConvoyFailures由 zombie 检测（DetectZombiePolecats）在所有 zombie 收集完成后调用：只对"有活跃工作且未完成"的 zombie 计数（zombie.HookBead == "" || !zombieImpliesActiveFailure(*zombie)时跳过），ZombieBeadClosedStillRunning与ZombieSubmittedStillRunning这两种不构成活跃失败（mountain.go）；
• TrackConvoyFailure通过bd dep list <issue> --direction=up --type=tracks --json找到跟踪该 issue 的 convoy，再检查 convoy 是否带mountain标签：mountain 走trackMountainFailure，普通 convoy 只记录警告（mountain.go）；
• trackMountainFailure从 issue 标签中解析当前mountain:failures:N，updateMountainFailureCount先移除旧计数标签再加新计数标签（mountain.go）；
• 达到 3 次后skipMountainIssue执行：bd update <issue> --status=blocked --add-label mountain:skipped --notes "Skipped by Mountain-Eater after N polecat failures"（mountain.go）。

对应的单元测试在 internal/witness/mountain_test.go：TestGetMountainFailureCount覆盖无标签、无失败标签、mountain:failures:1、mountain:failures:3、非法计数mountain:failures:abc与空计数等六种情形；TestHasLabel验证标签精确匹配语义（mountain:failures:1不等于mountain）。

跳过语义（Skip Semantics）

被跳过的 issue（带mountain:skipped标签、blocked状态）具有如下性质：

• 从就绪队列排除（blocked 状态）；
• 在gt mountain status输出中可见；
• 由 Layer 2（Deacon Dog）升级给 Mayor；
• 可恢复：bd update <issue> --status=open --remove-label mountain:skipped。

Mountain 会继续绕着被跳过的 issue 研磨。如果被跳过的 issue 在 DAG 中阻塞了其他工作，那些依赖项仍保持 blocked——Dog 会在停滞诊断中报告这一点。

6. Layer 2：Deacon Dog 山岳审计（设计中）

注意：截至当前仓库状态，Layer 2 的巡逻公式与mol-mountain-dog.formula.toml属于设计提案（设计文档状态标注为Design），在internal/formula目录中尚未出现对应实现。以下内容忠实还原设计文档，作为实现蓝图解读。

核心循环

Deacon 的巡逻公式增加一个mountain-audit步骤：

DEACON PATROL — mountain-audit step: mountains = bd list --label mountain --status=open --type=convoy for each mountain: dog_needed = false # Progress check (compare against last audit) current_closed = count of closed issues in this convoy last_closed = read from mountain:audit:<convoy-id> label on deacon bead if current_closed > last_closed: # Making progress — update audit mark, continue update mountain:audit:<convoy-id> = current_closed else if current_closed == total_issues: # Complete — dispatch Dog for cleanup + notification dog_needed = true dog_task = "complete" else: # No progress since last check — dispatch Dog to investigate dog_needed = true dog_task = "stall" if dog_needed: sling mountain-dog formula to a Dog with convoy-id and task type

Mountain Dog 公式

mol-mountain-dog.formula.toml—— 一个短命的 Dog 公式，用于调查 mountain 进度：

[formula] name = "mountain-dog" description = "Investigate mountain convoy progress" type = "worker" [formula.variables] convoy_id = { required = true } task = { required = true } # "stall" or "complete" [[formula.steps]] name = "investigate" description = """ You are a Mountain Dog investigating a mountain convoy. Convoy: {{convoy_id}} Task: {{task}} If task is "stall": 1. Run: gt convoy status {{convoy_id}} 2. Identify why no progress: - Are there skipped issues (mountain:skipped label)? - Are all remaining issues blocked? By what? - Are polecats active but slow? - Is the refinery backed up? 3. If there are ready issues with no polecats: sling them 4. If all remaining issues are skipped/blocked: Mail Mayor: "Mountain {{convoy_id}} stalled: N skipped, M blocked. Remaining DAG cannot progress without intervention." 5. If polecats are active: this is fine, no action needed If task is "complete": 1. Run: gt convoy status {{convoy_id}} 2. Verify all tracked issues are closed 3. If any skipped issues remain: Mail Mayor: "Mountain {{convoy_id}} finished with N skipped issues. Review skipped work: [list issue IDs]" 4. If all clean: Mail Mayor: "Mountain {{convoy_id}} complete. N issues closed in Xh Ym." 5. Run: gt convoy close {{convoy_id}} """

让这套机制成立的 Dog 特性

• 全新上下文（Fresh context）：Dog 从零状态开始，从头读取 convoy 与 beads，无前序会话的 hysteresis；
• 窄范围（Narrow scope）：一个 convoy、一个问题（"卡住了？"或"完成了吗？"），轻松装进单个上下文窗口；
• 短命（Ephemeral）：做完工作、汇报、消亡，无长期协调；
• 跨 rig 可见性（Cross-rig visibility）：Dog 拥有通向多个 rig 的 worktree，可以跨 rig 检查 beads 状态，这对跨 rig convoy 至关重要。

审计频率

Deacon 巡逻周期决定山的审计频率。当前 Deacon 巡逻运行在 feed 驱动 + heartbeat 模型上。对 mountain 而言，关键问题是："一座山卡住多久才会有人注意到？"

• 目标：10-15 分钟内检测到停滞；
• 机制：Deacon 的 heartbeat 间隔（守护进程根据活动每 5-10 分钟 poke Deacon 一次）。每次 heartbeat 运行包含 mountain-audit 步骤的巡逻公式；
• 成本：每个巡逻周期一次bd list --label mountain查询（廉价），外加每个卡住的山一次 Dog spawn（仅在需要时）。

7. Layer 3：Mayor 通知（设计中）

Mayor 从 Dog 收到两类 mountain 邮件：

停滞通知

Subject: Mountain stalled: <convoy-title> Body: Convoy: hq-cv-abc "Rebuild auth system" Progress: 23/35 closed (65%) Stalled for: 15 minutes Skipped issues (polecat failure): gt-xyz "Migrate session store" (failed 3 times) gt-abc "Update JWT validation" (failed 3 times) Blocked issues (DAG): gt-def "Integration tests" (blocked by gt-xyz) gt-ghi "E2E tests" (blocked by gt-def) Active polecats: 0 Ready issues: 0 Action needed: Review skipped issues. Possible fixes: bd update gt-xyz --status=open --remove-label mountain:skipped (retry) bd close gt-xyz --reason="Descoped" (skip permanently, unblocks dependents)

完成通知

Subject: Mountain complete: <convoy-title> Body: Convoy: hq-cv-abc "Rebuild auth system" Result: 33/35 closed, 2 skipped Elapsed: 3h 42m Skipped issues: gt-xyz "Migrate session store" (failed 3 times — needs manual review) gt-abc "Update JWT validation" (failed 3 times — needs manual review)

Mayor 的角色

Mayor不是研磨循环的一部分。它接收通知并可以采取行动，但 mountain 在无 Mayor 介入的情况下自主研磨。Mayor 的行动包括：

• 重试被跳过 issue：bd update <id> --status=open --remove-label mountain:skipped；
• 永久跳过：bd close <id> --reason="Descoped"（解除依赖项的阻塞）；
• 通知用户：转发停滞/完成通知；
• 重构 DAG：移除或添加依赖，绕过阻塞点。

8. 用户体验

启动一座 Mountain

$ gt mountain gt-epic-auth-rebuild Validating epic structure... Epic: gt-epic-auth-rebuild "Rebuild auth system" Tasks: 35 (31 slingable, 4 epics) Waves: 6 (computed from blocking deps) Max parallelism: 4 Warnings: gt-migrate-sessions has no description (may cause polecat confusion) Errors: none Creating convoy... Convoy: hq-cv-m7x "Mountain: Rebuild auth system" Label: mountain Launching Wave 1 (4 tasks)... Slung gt-foundation-types → gastown Slung gt-config-schema → gastown Slung gt-test-fixtures → gastown Slung gt-error-types → gastown Mountain active. ConvoyManager will feed subsequent waves. Deacon will audit progress every ~10 minutes. Check status: gt mountain status hq-cv-m7x

对照源码，这段输出的每个数字都来自真实计算：Tasks/Waves/Max parallelism分别由len(dag.Nodes)、len(waves)与最大波次大小给出；无描述等 warning 来自detectWarnings的 findings；存在 warning 且未带--force时会拒绝启动（convoyStatusStagedWarnings分支，见 mountain.go）。

查看状态

$ gt mountain status Active Mountains: hq-cv-m7x "Rebuild auth system" Progress: ████████████░░░░░░░░ 23/35 (65%) Active: 3 polecats working Ready: 1 issue waiting for polecat Blocked: 6 issues (DAG deps) Skipped: 2 issues (polecat failures) Elapsed: 1h 47m hq-cv-n9y "Migrate database layer" Progress: ██████████████████░░ 18/20 (90%) Active: 2 polecats working Elapsed: 52m

源码中showAllMountainStatus遍历所有带mountain标签的 open convoy，用renderProgressBar渲染 20 格 Unicode 进度条（█/░），并支持--json输出（mountain.go）。

详细状态

$ gt mountain status hq-cv-m7x Mountain: hq-cv-m7x "Rebuild auth system" Epic: gt-epic-auth-rebuild Progress: 23/35 closed (65%) Elapsed: 1h 47m Wave: 4 of 6 Completed (23): ✓ gt-foundation-types, gt-config-schema, gt-test-fixtures, ... Active (3): ⟳ gt-session-handler (polecat: gastown/nux, 12m) ⟳ gt-middleware-chain (polecat: gastown/furiosa, 8m) ⟳ gt-rate-limiter (polecat: gastown/max, 3m) Ready (1): ○ gt-cache-layer (unblocked, waiting for polecat) Skipped (2): ⊘ gt-migrate-sessions (failed 3 times — no description) ⊘ gt-jwt-validation (failed 3 times — test dependency missing) Blocked (6): ◌ gt-auth-integration (needs: gt-session-handler, gt-jwt-validation⊘) ◌ gt-e2e-auth-tests (needs: gt-auth-integration) ... Stall risk: gt-jwt-validation⊘ blocks 4 downstream issues. Fix: bd update gt-jwt-validation --status=open --remove-label mountain:skipped Or: bd close gt-jwt-validation --reason="Descoped"

showMountainDetail在源码中实现了完整分类逻辑：closed→ completed、in_progress/hooked→ active、带mountain:skipped标签 → skipped，其余按 DAG 中是否有未关闭 blocker 分为 blocked / ready（mountain.go）。

9. 全局改进（惠及所有 Convoys）

Mountain-Eater 的设计揭示了不只惠及 mountain、而是惠及所有 convoy的改进点，应当全局应用：

9.1 Polecat 失败跟踪

即使非 mountain convoy 也受益于"这个 issue 已失败 3 次"的信息。Witness 应当跟踪所有convoy-tracked issue 的失败次数，而不仅是 mountain 的。区别在于：mountain 在 3 次失败后自动跳过；普通 convoy 只记录警告。这一差异化逻辑已在TrackConvoyFailure中实现——普通 convoy 返回Warning: polecat failure on convoy-tracked issue ...（mountain.go）。

9.2 滞留扫描中的停滞检测

ConvoyManager 的滞留扫描目前只喂入第一个就绪 issue。增强：如果同一 issue 已被 sling 3 次以上且不断以滞留状态出现，停止重新 sling 并记录警告。这能防止所有 convoy 的无限 sling-失败循环。

9.3 进度可见性

gt convoy status应展示与gt mountain status同样丰富的信息——活跃 polecat、就绪前沿、阻塞 issue、跳过 issue。这对所有 convoy 都有用。

10. 与 Swarm 架构的关系

设计文档引用了一份 swarm 架构设计（swarm 是持久化 molecule、由专职 Agent 协调）。Mountain-Eater 通过不同机制达成同样结果：

Mountain-Eater 是 swarm 架构目标的实现路径：swarm 文档中的"ready front"模型、"gate issues"、"batch management"概念直接适用，区别在于机制——巡逻驱动研磨（patrol-driven grinding）而非协调者驱动研磨（coordinator-driven grinding）。

说明：设计文档中的 swarm 架构链接指向docs/swarm-architecture.md，在当前仓库目录树中该文件未出现，属于悬空链接，读者应以本设计文档 + convoy 规范 为准理解其概念关系。

11. 实现计划与当前落地状态

按 roadmap.md 的 Milestone 5（Mountain-Eater，依赖 Milestone 2 的 stage-launch 管线），变更清单如下：

什么不会改变（What Does NOT Change）

• Convoy 数据模型（仍是hq-cv-*beads 带tracks依赖）；
• ConvoyManager 事件轮询（仍 5 秒、仍在关闭时喂给）；
• ConvoyManager 滞留扫描（仍 30 秒、增强跳过逻辑）；
• Stage-launch 工作流（mountain 直接使用它）；
• Polecat 生命周期（不变）；
• Refinery（不变）。

Layer 0 的既有事实基础

Layer 0 的机械行为已由 convoy 规范 固化并通过测试验证，是 Mountain-Eater 的承载基础，值得单独强调：

• 事件轮询 goroutine：GetAllEventsSince每 5 秒轮询所有 rig 存储 + hq，检测EventClosed/EventStatusChanged(closed)，调用共享观察函数convoy.CheckConvoysForIssue；
• 滞留扫描 goroutine：每 30 秒调用gt convoy stranded --json，对有就绪工作的 convoy 通过gt sling <id> <rig> --no-boot喂入第一个就绪 issue，对空 convoy 调用gt convoy check自动关闭；
• 关键设计决策：SDK 轮询而非 CLI 流式（简化重启语义）；高水位标记（atomic int64）单调推进防重复处理；每次扫描每个 convoy 只喂一个 issue（防批量溢出）；滞留扫描作为安全网（崩溃恢复）；beads 存储为 nil 时仅禁用事件轮询，滞留扫描在降级模式下仍工作。

12. 开放问题

1. gt mountain是否应自动取消 docked rig？如果史诗的 issue 路由到 docked rig，mountain 是否应自动将其 undock？当前倾向：否——要求 rig 处于活跃状态。Mountain 只研磨活跃 rig。
2. 每座山最大并发 polecat 数。Mountain 是否应有可配置的并发上限？ConvoyManager 在每个关闭事件时喂一个 issue。对 mountain，波次切换时可能希望一次派发多个就绪 issue（例如 wave 1 完成、wave 2 有 8 个就绪 issue——一次派发全部 8 个，而非逐个）。
3. 山与山之间的依赖。一座山能否依赖另一座？初始可能不需要——跨山依赖本质上就是 DAG 中的跨 issue 依赖。
4. 通知渠道。Mayor 邮件是当前通知路径。Mountain 是否也应支持 webhook/Slack 通知用户？留待未来工作。

13. 进一步阅读：源码与文档导览

核心实现（已落地）：

• internal/cmd/mountain.go：gt mountain命令族完整实现（activate / status / pause / resume / cancel），含--force与--json；
• internal/witness/mountain.go：Layer 1 失败跟踪（MountainMaxFailures = 3、mountain:failures:N计数、mountain:skipped自动跳过）；
• internal/witness/mountain_test.go：失败计数解析、标签匹配等单元测试。

设计文档（骨架与规范）：

• mountain-eater.md：本文主体设计文档（问题陈述、四层架构、标签语义、各层细节、UX、开放问题）；
• roadmap.md：Milestone 0-5 分阶段路线图，Milestone 5 即 Mountain-Eater 的落地计划；
• spec.md：ConvoyManager 规范（Layer 0 的事件轮询、滞留扫描、共享观察函数、不变量与测试矩阵）。

需要强调的是，本文所述 Mountain-Eater 是一套"机械层已就绪、判断层逐步落地"的设计：Layer 0（ConvoyManager）与 Layer 1（Witness 失败跟踪）已在源码中可用，gt mountain命令可直接上手；Layer 2（Deacon 审计）与 Layer 3（Mayor 升级）仍是设计蓝图，其价值在于定义了"无协调者、以 beads 为状态、以标签触发行为"的自主研磨范式——这正是大型史诗从"卡在 40%"走向"去吃午饭回来就完成了"的关键路径。

【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown