Skip to main content

Pipeline Control Tower

Pipeline Control Tower 是 Pipeline 自動化系統（v0.6 / v0.7）的增強層，解決多 Agent 協作中最棘手的兩個問題：訊息遺失 和 Agent 失聯。

Status：設計完成（2026-04-17），v0.6 / v0.7 實作中 對應 Spec：PM Repo docs/superpowers/specs/2026-04-17-pipeline-control-tower-design.md

設計動機​

Pipeline v0.5 已經實作出完整的 Agent 協作框架：Broker 通訊、State Machine、Safety Monitor、Dashboard。但在實戰中，我們反覆踩到兩個場景：

痛點 1：訊息遺失​

Broker 的 messageStore 與 queue 是 in-memory 結構。任何情況下 Broker 重啟，或 Agent 在處理訊息前斷線，訊息就消失了。

痛點 2：Agent 失聯 = 自動化斷鏈​

  • Reviewer 做完 review 後 session 結束 → PM 下一個指令送到空 session → timeout
  • 使用者手動關閉某個 Windows Terminal tab → Agent 消失但 Supervisor 不知道
  • PM 自己 wait_for_message 卡住或 timeout → 整條 pipeline 停住，需要人介入

這兩個痛點的共通根因是 Agent Lifecycle 管理不足。v0.5 架構假設 Agent 「會一直在」，而真實世界的 Agent 會 exit、crash、被關掉、被 timeout。

Pipeline Control Tower 的目標：讓 Agent 失聯變成設計的一部分，而不是 bug。

核心觀念​

從 "Hope It Gets There" 升級到 "At-Least-Once Delivery"​

所有訊息必須寫入持久化儲存（SQLite），每條訊息有唯一 offset。Agent 處理後送 ACK，Broker 才標為完成。Agent 重連時送 last_seen_offset，Broker 自動補齊漏掉的訊息。

PM 發訊息 ──▶ Broker 寫 SQLite（offset=43）──▶ 送給 Reviewer
                                                    │
                                                    ▼
                                              Reviewer ACK
                                                    │
                                                    ▼
                                         Broker update status=acked

如果 Reviewer 離線，訊息停在 pending 狀態，重連時 replay。

從 "Assume Agent Is Running" 升級到 "Supervise Agent Lifecycle"​

每個 Agent（PM / Dev / Reviewer）各自有一個 Lifecycle State Machine（xstate 實作）。Supervisor 監控狀態，在需要時自動 spawn 新的 agent runtime session：

offline ──PENDING_MESSAGE──▶ spawning ──WS_CONNECTED──▶ online
                                │                         │
                                │ SPAWN_FAIL              │ MESSAGE_DELIVERED
                                ▼                         ▼
                           (backoff retry)           working ──ACK──▶ online
                                                          │
                                                          │ WS_DISCONNECTED
                                                          ▼
                                                      crashed ──backoff──▶ offline

關鍵：Agent exit 不再是 bug，是 normal completion signal。有新訊息 → 自動 spawn；沒事 → 乾淨關閉省 token。

系統架構​

v0.7 完成時的模組全景​

核心資料流​

技術棧​

元件技術說明
RuntimeNode.js 22+延伸既有 Broker repo
語言TypeScript 5.x全棧統一
Persistent Queuebetter-sqlite3Synchronous API、~10k ops/sec、單一檔案
Agent State MachinexstateStatechart、actor model、線上 visualizer
File Watcherchokidar跨平台 file system watcher
Process Spawnexeca + wt.exe啟動 Windows Terminal tabs
DashboardReact 19 + Tremor + Tailwind v4v0.5 既有，持續擴充
部署Windows Service（node-windows / NSSM）開機自啟、crash 自動 restart

v0.6：Persistent Queue​

關鍵變更​

  1. 新增 SQLite schema：messages 表 + agent_offsets 表
  2. ACK 機制：每條訊息要 ack 才標完成，未 ack 會在 reconnect 時 replay
  3. Retention policy：30 天 OR 100k 條訊息自動清理
  4. 漸進式 migration：MCP tool signature 不變，既有 in-memory 結構轉為 hot cache

Message Lifecycle​

       append            send WS           receive ACK
pending ──────▶ delivered ──────▶ acked
    │               │
    │               │ timeout / max retry
    ▼               ▼
 expires ─────▶  failed

影響​

  • ✅ Broker 重啟不丟訊息
  • ✅ Agent 離線期間累積的訊息，上線瞬間補齊
  • ✅ ACK 遺失自動 replay（agent 需冪等）
  • ✅ 訊息有完整 audit trail（timestamp + status + retry count）

v0.7：Agent Lifecycle Supervisor​

關鍵變更​

  1. Per-Agent xstate machine：每個 Agent 有自己的 lifecycle state
  2. SpawnManager：自動呼叫 wt.exe new-tab + agent CLI 的 prompt mode 啟動 /wait-pipeline
  3. SessionLogWatcher：chokidar 監控 agent session log 目錄（jsonl 格式），驅動 Dashboard 的 Activity Feed
  4. Config reload：.pipeline/agents.yaml 改動不影響 running agent，下次 spawn 生效

Spawn 的決策流​

Broker 收到訊息 → 對方離線 → 觸發 PENDING_MESSAGE
             ↓
  Supervisor 查 agent state
             ↓
  ┌──────────┴──────────┐
  │                     │
offline             不在 offline
  ↓                     │
Spawn                 Guard：
wt.exe + agent CLI    不重複 spawn
  ↓
上線後自動拉 queue pending

影響​

  • ✅ Agent 做完 exit 變成設計的一部分（不再是 bug）
  • ✅ 使用者關閉 WT tab 不影響自動化（下次 pending 自動補）
  • ✅ PM 自己也被 Supervisor 管理（PM 失聯也能自動復原）
  • ✅ Dashboard 新增 Respawn / Kill / Send Message 按鈕，手動介入更方便

設計原則​

1. At-Least-Once + 冪等​

訊息可能重送（reconnect replay、ACK 遺失），Agent 邏輯必須設計成冪等。MCP tool 實作要用 message_id dedup。

2. Stateless Agent 模式​

Agent 做完一件事 → exit。下次要做事 → Supervisor spawn 新 session。優點：context 乾淨、省 token、失聯是設計一部分。

3. 延伸而非重寫​

所有新功能作為既有 Broker 的模組擴充，不另起獨立 daemon 或新語言棧。技術選型窗口已在 v0.5 關閉（TypeScript + Node.js）。

4. 分級降級​

  • Level 1 自動：transient error → backoff retry
  • Level 2 通知：連續失敗 → needs_human + Dashboard 警示
  • Level 3 停止：資料損毀 / 不可恢復 → 停 Broker + crash log

5. No Silent Failure​

所有 error 必須寫 activity_log + 廣播 SSE 給 Dashboard。看不到的 error 等於沒處理。

6. 可從手機遠端監控​

Broker HTTP :3101 → Cloudflare Tunnel → 任何裝置可看 Dashboard + 手動介入。不嵌 pty、不打包 Electron。

技術選型決策​

完整 decision log 見對應 Spec 文件。

決策選擇主要替代方案（為何不選）
GUI 型態Web DashboardElectron + embedded terminal — node-pty 在 Windows 有 ConPTY 坑、150MB 打包、失去 WT 體驗
通訊協議WebSocket + SQLite persistent queueZMQ pub/sub — 不保證 delivery、瀏覽器不支援；NATS/Redis — 多依賴 overkill
語言 / runtimeNode.js + TypeScript（延伸既有）.NET 8 + Stateless — Broker v0.5+ 已是 production TS，重寫 2-3 週成本過高
部署形態併入 Broker（同 repo / 同 process）獨立 daemon — Broker 已有 80% 基礎，分拆反而複雜
Agent 運行模式Stateless（做完 exit）Always-on — context overflow 風險 + token 吃重
State machine libraryxstate（v0.7 新模組）Stateless (.NET) — 語言不對；自寫 transitions — agent lifecycle 複雜度高

實作時程​

階段內容時長
v0.6Persistent Queue + ACK + Reconnect Replay3-4 天
v0.7Agent Lifecycle Supervisor + SpawnManager + SessionLogWatcher + Dashboard 擴充4-5 天
總計v0.5 → v0.7 完整升級~2 週

上線後效果預期​

  • 訊息 0 遺失（Broker 重啟、Agent 離線、使用者關 tab 都不影響）
  • Agent 自動回收（做完即 exit，省 token）
  • 失聯自動補（Supervisor 偵測 → wt.exe spawn）
  • 手機 Dashboard 隨時監控（Cloudflare Tunnel 遠端存取）
  • 自動化不再「需要人重啟」（Level 1 失敗自動重試、Level 2 通知、Level 3 才停）

相關文件​

文件說明
Pipeline 自動化總覽v0.5 基礎架構
Pipeline 狀態機PipelineStateMachine 定義
End-to-End 流程五階段完整流程
訊息協議Message 結構、Subject 列表、Priority
操作手冊啟動、監控、故障排除

外部參考​