Skip to main content

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 會自動：

  1. 驗證 Broker + Dev 連線
  2. 設定 Phase Plan（如果是多 Phase）
  3. 撰寫 Dev Instructions
  4. 派發第一個 Issue
  5. 進入監控迴圈

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 不直接支援「跳過」，但可以：

  1. 在 Linear 上將該 Issue 標記為 Canceled
  2. 從 Phase Plan 中移除
  3. 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。人工檢視問題後：

  1. 手動修正程式碼
  2. resume() 恢復 Pipeline
  3. Pipeline 回到 PHASE_DEVELOPING，fixCount 歸零

Q: 如何查看某個 Issue 的完整訊息歷史？​

get_message_history(issue: "JOP-240")

回傳該 Issue 相關的所有 send/receive/reply 訊息，含時間戳和狀態。

日誌與追蹤​

Activity Log 位置​

日誌路徑內容
PM Log.pipeline/logs/pm.logPM 的所有操作記錄
Dev Log.pipeline/logs/dev.logDev 的開發活動
Reviewer Log.pipeline/logs/reviewer.logReviewer 的審查記錄
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