Pipeline 自動化總覽
設計動機
GatherTech 的多專案開發流程涉及 PM、Dev、Reviewer 三個角色的密集協調。在手動模式下，每個 Issue 都需要 PM 手動執行：
- 撰寫開發指令（
/generate-task） - 通知 Dev 開始開發（
/pick-task） - 等待 Dev 完成回報（
/done） - 建立 PR（
/create-pr） - 等待 Reviewer 審查
- 處理審查結果（
/review-fix或 merge）
當一個專案有 10+ Phase、每 Phase 3~5 個 Issues 時，手動流程成為瓶頸。Pipeline 自動化的目標是：
- 消除等待：Phase 內的 Issue 自動串接，不需 PM 手動監控
- 跨 Phase 銜接：Auto-Advance 機制自動推進下一個 Phase
- 失敗安全：超過重試上限自動暫停，通知人工介入
- 完整追蹤：所有操作記錄在 Linear comment + activity log
三 Agent 角色
| 角色 | 職責 | 決策權限 |
|---|---|---|
| PM Agent | 指揮官：派工、監控進度、建立 PR、處理審查結果 | Issue 排程、PR 時機、是否 retry |
| Dev Agent | 執行者：接收任務、實作功能、回報完成 | 技術實作方案 |
| Reviewer Agent | 品質關卡：審查 PR、產出審查報告 | APPROVE / REQUEST_CHANGES |
關鍵設計：PM 是唯一能改變 Pipeline 狀態的角色。Dev 和 Reviewer 只能透過 Broker 回報結果，由 PM（或 Broker state machine）決定下一步。
系統架構
Broker 內部模組
技術棧
| 元件 | 技術 | 版本 |
|---|---|---|
| Broker Runtime | Node.js | 22+ |
| 語言 | TypeScript | 5.x |
| Agent 通訊 | MCP (Model Context Protocol) | stdio over TCP |
| Dashboard UI | React + Tremor + TailwindCSS | v0.3 |
| 即時更新 | WebSocket | 原生 |
| 狀態持久化 | JSON 檔案 | — |
| Issue 追蹤 | Linear MCP | — |
| 版控 / PR | GitHub + gh CLI | — |
設計原則
1. State Machine 驅動
所有 Pipeline 行為由有限狀態機（FSM）控制。任何操作都必須在合法的狀態下才能執行，不合法的操作會被拒絕並記錄。
2. 訊息佇列解耦
Agent 之間不直接通訊。所有訊息經過 Broker 的優先佇列，確保：
- 高優先訊息（stop、error）不被低優先訊息阻塞
- Agent 斷線時訊息保留在佇列中，重連後自動投遞
3. 失敗即上報
每個 Issue 最多重試 3 次，每個 PR 最多 2 輪 review fix。超過限制自動進入 HUMAN_NEEDED 狀態，暫停 Pipeline 等待人工決策。
4. 完整追蹤鏈
每個 Issue 在 Linear 上有完整的 comment 鏈：
Dev Instructions → Completion Report → PR Created → Review Result → (Review Fix → Fix Report →) Merged
5. 優雅降級
Broker 重啟後從 state.json 恢復狀態。Auto-Advance 計算剩餘冷卻時間繼續執行。Agent 斷線自動重連，佇列訊息重新投遞。
相關文件
| 文件 | 說明 |
|---|---|
| 狀態機定義 | 完整狀態圖 + 轉換規則 |
| End-to-End 流程 | 五階段詳細流程 + Sequence Diagram |
| 訊息協議 | Message 結構、Subject 列表、Priority |
| MCP Tools API | 全部 17 個 tool 的完整參考 |
| 操作手冊 | 啟動、監控、故障排除 |
| 手動流程對照 | Pipeline vs 手動模式比較 |
| Control Tower (v0.6/v0.7) | 增強版：Persistent Queue + Agent Lifecycle Supervisor |