Pipeline 操作手冊
本頁涵蓋 Pipeline 的日常操作：啟動、監控、故障排除、Dashboard 使用。
啟動流程
啟動前檢查清單
啟動指令
Step 1：啟動 Broker
cd D:\WorkSpace\GatherTech\Core\gst-pipeline-broker
npm start
# Broker listening on localhost:3100
# Dashboard available at localhost:3101
Step 2：確認 Agent MCP 設定
每個 Agent 的 .mcp.json 需包含 Pipeline Broker 連線設定：
{
"mcpServers": {
"pipeline": {
"command": "node",
"args": ["D:/WorkSpace/GatherTech/Core/gst-pipeline-broker/dist/client/index.js"],
"env": {
"PIPELINE_HOST": "localhost",
"PIPELINE_PORT": "3100",
"PIPELINE_AGENT_ID": "pm"
}
}
}
}
PIPELINE_AGENT_ID 對應角色：pm、dev、reviewer。
Step 3：啟動 Pipeline
/start-pipeline JOP-236 1
PM Agent 會自動：
- 驗證 Broker + Dev 連線
- 設定 Phase Plan（如果是多 Phase）
- 撰寫 Dev Instructions
- 派發第一個 Issue
- 進入監控迴圈
Dashboard
Dashboard 在 localhost:3101 提供即時視覺化監控。
功能區塊
| 區塊 | 內容 |
|---|---|
| Pipeline Status | 當前狀態、Phase、進度百分比 |
| Agent Health | 三個 Agent 的連線狀態、最後活動時間 |
| Issue Tracker | 每個 Issue 的狀態（todo / in_progress / done / failed） |
| Message Queue | 三個佇列的即時深度、最新訊息 |
| Auto-Advance | 冷卻倒數、當前階段（cooldown / session_reset / ready） |
| Activity Log | 即時事件串流（WebSocket 推送） |
技術棧
- 前端：React + Tremor（圖表元件庫）+ TailwindCSS
- 即時更新：WebSocket 連線到 Broker
- 刷新頻率：WebSocket push（無需輪詢）
常見操作
手動暫停 Pipeline
# PM Agent 中
request_human("需要人工確認：{原因}")
Pipeline 進入 HUMAN_NEEDED，所有 Agent 收到通知。
恢復暫停的 Pipeline
# PM Agent 中
resume()
回到暫停前的狀態（IDLE 或 PHASE_DEVELOPING）。
取消 Auto-Advance
在 Auto-Advance 冷卻期間：
cancel_auto_advance(reason: "需要手動檢查 Phase 2 PR")
Pipeline 維持在 IDLE，等待手動啟動下一 Phase。
跳過某個 Issue
Pipeline 不直接支援「跳過」，但可以：
- 在 Linear 上將該 Issue 標記為
Canceled - 從 Phase Plan 中移除
resume()繼續
緊急停止
方法一（推薦）：
stop_pipeline()
方法二（Broker 層級）：
# 在 Broker 目錄建立停止檔案
touch D:\WorkSpace\GatherTech\Core\gst-pipeline-broker\.stop-pipeline
Broker 偵測到檔案後立即停止，斷開所有 Agent。
故障排除
決策樹
常見問題
Q: Dev Agent 重啟後會遺失進度嗎？
不會。Dev Agent 的 /pick-task 從 Linear comment 讀取 Dev Instructions，不依賴對話 context。重啟後重新 /pick-task 即可接續。未投遞的訊息保留在 Broker 佇列中，重連後自動投遞。
Q: Broker 重啟後 Auto-Advance 會繼續嗎？
會。Broker 啟動時讀取 state.json，如果 Auto-Advance 的 cooldown 尚未過期，會計算剩餘時間並繼續計時。如果已過期，則立即進入 session_reset 階段。
Q: 可以同時跑兩個 Pipeline 嗎？
目前不行。一個 Broker instance 只支援一個 Pipeline。如需平行開發多個專案，需啟動多個 Broker instance（不同 port）。
Q: Review 被拒 2 次後還想繼續怎麼辦？
Pipeline 會進入 HUMAN_NEEDED。人工檢視問題後：
- 手動修正程式碼
resume()恢復 Pipeline- Pipeline 回到
PHASE_DEVELOPING，fixCount 歸零
Q: 如何查看某個 Issue 的完整訊息歷史？
get_message_history(issue: "JOP-240")
回傳該 Issue 相關的所有 send/receive/reply 訊息，含時間戳和狀態。
日誌與追蹤
Activity Log 位置
| 日誌 | 路徑 | 內容 |
|---|---|---|
| PM Log | .pipeline/logs/pm.log | PM 的所有操作記錄 |
| Dev Log | .pipeline/logs/dev.log | Dev 的開發活動 |
| Reviewer Log | .pipeline/logs/reviewer.log | Reviewer 的審查記錄 |
| Pipeline Log | .pipeline/logs/pipeline.log | 狀態轉換、Auto-Advance、安全事件 |
Linear Comment 追蹤鏈
每個 Issue 在 Linear 上有完整的 comment 鏈，作為永久追蹤記錄：
## Dev Instructions ← PM 撰寫（/generate-task 或 Pipeline）
## Completion Report ← Dev 完成（/done）
## PR Created ← PM 建立（/create-pr）
## Review Result ← Reviewer 審查
## Review Fix Instructions ← PM 產出（/review-fix，如有 fix）
## Review Fix Report ← Dev 修正（/done --fix，如有 fix）
PM Session Journal
Pipeline 事件同步記錄在 PM 的 session journal（docs/pm-journal.md）：
- 00:30 [Jope.Core] Pipeline Phase 1 started — JOP-237 (Solution Setup)
- 00:35 [Jope.Core] JOP-237 completed by dev — 22 projects scaffolded
- 00:36 [Jope.Core] PR #1 created (gather-system/Jope.Core)
- 00:40 [Jope.Core] PR #1 approved + merged. Phase 1 COMPLETE