跳到主要内容

Pipeline 狀態機

Pipeline 的所有行為由有限狀態機（Finite State Machine）驅動。本頁定義完整的狀態、轉換規則、安全限制。

狀態定義​

狀態語義可執行操作
IDLE空閒，等待啟動新 Phasestart_phase, set_phase_plan, stop_pipeline
PHASE_PREPARINGPhase 初始化中，正在配置 Issuesbegin_developing, stop_pipeline
PHASE_DEVELOPINGDev 正在開發，PM 監控中report_completion, request_human, stop_pipeline
PHASE_REVIEWINGPR 已建立，Reviewer 審查中report_review, request_human, stop_pipeline
COMPLETEDPipeline 所有 Phase 完成stop_pipeline（清理用）
HUMAN_NEEDED需要人工介入（自動暫停）resume, stop_pipeline
PAUSED手動暫停resume, stop_pipeline
STOPPED已終止，不可恢復無（需重新建立 Pipeline）

完整狀態圖​

轉換規則詳解​

IDLE → PHASE_PREPARING​

項目內容
觸發start_phase(phase: number, issues: string[])
Guard當前狀態必須是 IDLE
動作初始化 Phase 資料結構，將所有 issues 標記為 todo
結果進入 PHASE_PREPARING

PHASE_PREPARING → PHASE_DEVELOPING​

項目內容
觸發begin_developing()
Guard當前狀態必須是 PHASE_PREPARING
動作將第一個 issue 標記為 in_progress，開始接收訊息
結果進入 PHASE_DEVELOPING

PHASE_DEVELOPING → PHASE_DEVELOPING（Issue 完成，還有下一個）​

項目內容
觸發report_completion(issue, "pass")
Guard尚有 todo 狀態的 issues
動作將完成的 issue 標記為 done，下一個 issue 標記為 in_progress
結果維持 PHASE_DEVELOPING

PHASE_DEVELOPING → PHASE_REVIEWING（所有 Issues Done）​

項目內容
觸發report_completion(issue, "pass")
Guard本 Phase 所有 issues 都已 done
動作標記 Phase 開發完成，通知 PM 建立 PR
結果進入 PHASE_REVIEWING

PHASE_DEVELOPING → HUMAN_NEEDED（Issue 失敗 3 次）​

項目內容
觸發report_completion(issue, "fail")
Guard該 issue 的 failCount >= 3
動作記錄失敗原因，暫停 Pipeline，通知所有 Agent
結果進入 HUMAN_NEEDED

PHASE_REVIEWING → IDLE（Review 通過，還有下一個 Phase）​

項目內容
觸發report_review("approved", hasNextPhase: true)
GuardPhase Plan 中存在下一個 Phase
動作Merge PR，如果 Auto-Advance 開啟則啟動冷卻計時
結果進入 IDLE（等待 Auto-Advance 或手動啟動下一 Phase）

PHASE_REVIEWING → COMPLETED（最終 Phase 通過）​

項目內容
觸發report_review("approved", hasNextPhase: false)
Guard這是最後一個 Phase
動作Merge PR，標記整個 Pipeline 完成
結果進入 COMPLETED

PHASE_REVIEWING → PHASE_DEVELOPING（Review 要求修正）​

項目內容
觸發report_review("changes")
GuardfixCount < 2
動作PM 產出 fix instructions，重新派工給 Dev
結果回到 PHASE_DEVELOPING

PHASE_REVIEWING → HUMAN_NEEDED（Review 修正超過 2 輪）​

項目內容
觸發report_review("changes")
GuardfixCount >= 2
動作記錄修正歷史，暫停 Pipeline
結果進入 HUMAN_NEEDED

Error Escalation 決策樹​

安全限制摘要​

機制閾值觸發結果
Issue 開發失敗3 次HUMAN_NEEDED
PR Review 被拒2 輪HUMAN_NEEDED
Dev 無回應20 分鐘（2 次 timeout）HUMAN_NEEDED
緊急停止.stop-pipeline 檔案存在STOPPED
Broker 重啟—從 state.json 恢復

狀態持久化​

state.json 結構​

{
  "state": "PHASE_DEVELOPING",
  "phase": 2,
  "issues": {
    "JOP-240": { "status": "done", "failCount": 0 },
    "JOP-238": { "status": "in_progress", "failCount": 0 },
    "JOP-239": { "status": "todo", "failCount": 0 }
  },
  "phasePlan": {
    "planId": "jope-core",
    "phases": [
      { "phase": 1, "issues": ["JOP-237"] },
      { "phase": 2, "issues": ["JOP-240", "JOP-238", "JOP-239", "JOP-241"] }
    ],
    "autoAdvance": true,
    "cooldownMinutes": 5
  },
  "fixCount": 0,
  "autoAdvance": {
    "active": false,
    "targetPhase": null,
    "cooldownEndTime": null
  },
  "agents": {
    "pm": { "connected": true, "lastSeen": "2026-04-11T01:10:00Z" },
    "dev": { "connected": true, "lastSeen": "2026-04-11T01:16:00Z" },
    "reviewer": { "connected": false, "lastSeen": null }
  }
}

恢復邏輯​

Broker 重啟時：

  1. 讀取 state.json，恢復到最後的狀態
  2. 如果 Auto-Advance 正在冷卻中，計算剩餘時間並繼續計時
  3. Agent 重連後，佇列中的未投遞訊息自動重新發送
  4. 如果重啟前是 PHASE_DEVELOPING，等待 Dev 重連後繼續監控