Skip to main content

Pipeline End-to-End 流程

Pipeline 自動化的完整生命週期分為五個階段。本頁以 Sequence Diagram 詳細說明每個階段的操作流程。

階段一：Phase Setup — PM 派工​

觸發條件​

  • PM 執行 /start-pipeline {parentId} {phase}
  • 或 Auto-Advance 完成後自動觸發

詳細步驟​

  1. 驗證 Broker 連線

    • 呼叫 get_pipeline_status() 確認 Broker 運行中
    • 確認 Dev Agent 已連線（agents.dev.connected = true）
    • 若任一失敗，提示使用者並中止

  2. 取得 Phase Issues

    • 從 Linear 取得 Parent Issue 的所有 Sub-Issues
    • 篩選符合 [P{phase}] 的 Issues（或使用 Phase Plan）
    • 按 Issue ID 排序（即開發順序）

  3. 設定 Phase Plan（多 Phase 專案）

    set_phase_plan(
      planId: "jope-core",
      phases: [
        { phase: 1, issues: ["JOP-237"] },
        { phase: 2, issues: ["JOP-240", "JOP-238", "JOP-239", "JOP-241"] },
        ...
      ],
      autoAdvance: true,
      cooldownMinutes: 5
    )

  4. 撰寫 Dev Instructions

    • 對每個 Issue 發送 Linear comment：## Dev Instructions
    • 內容包含：
      • Target Agent 名稱
      • Feature branch 名稱：feature/{issue-id}-{description}
      • Base branch（從 repo-config.json 查表）
      • Spec Kit 參考路徑（constitution, spec, plan, tasks）
      • Task 列表 + Acceptance Criteria
      • Branch 建立指令

  5. 初始化 Pipeline 狀態

    start_phase(phase: 1, issues: ["JOP-237"])

  6. 派發第一個 Issue

    • Linear 更新第一個 Issue 狀態為 In Progress
    • 發送訊息給 Dev： 
      send_message(to: "dev", subject: "develop", body: {
        issue: "JOP-237",
        phase: 1,
        totalIssues: 1,
        currentIndex: 1
      })
    • 切換狀態： 
      begin_developing()

Sequence Diagram​

階段二：Development Loop — Dev 開發​

觸發條件​

PM 進入 PHASE_DEVELOPING 狀態後，自動開始監控迴圈。

PM 監控迴圈邏輯​

LOOP:
  msg = wait_for_message(agentId: "pm", timeout: 3600)
  
  SWITCH msg.subject:
    "issue_complete" → 處理完成
    "issue_failed"   → 處理失敗
    "alert"          → 記錄 / 升級
    "needs_human"    → 暫停 Pipeline
    TIMEOUT          → 檢查 Dev 健康

Dev 端行為​

  1. 收到 develop 訊息
  2. 執行 /pick-task {issueId}：
    • 從 Linear 取得 Issue 詳情 + Dev Instructions comment
    • 建立 feature branch
    • 開始開發
  3. 開發完成後執行 /done：
    • 產出 Completion Report（branch, files, tests）
    • 透過 Broker 回報：report_completion(issue, "pass")
    • PM 收到 issue_complete 訊息

Sequence Diagram​

失敗重試流程​

階段三：PR Creation — 建立 PR​

觸發條件​

所有 Phase Issues 的 report_completion 都回傳 pass，Pipeline 進入 PHASE_REVIEWING 狀態。

詳細步驟​

  1. 收集 PR 內容

    • Git log：git log --oneline {target}..{source}
    • Diff stat：git diff --stat {target}..{source}
    • Linear Issue 資訊：title, description, acceptance criteria
    • Completion Report comment 內容

  2. 偵測 Spec Kit（如果適用）

    • 檢查 repo 是否有 specs/spec.md + .specify/memory/constitution.md
    • 提取 Constitution 原則、User Story、驗收場景
    • 寫入 PR body 的 ## Spec Reference 區塊

  3. 偵測 Per-Phase PR

    • 從 commit 訊息提取所有 Issue ID（regex: (GST-\d+|JOP-\d+|LEY-\d+)）
    • PR title 格式：feat(scope): Phase {n} - {description} ({issue-ids})
    • Body 包含所有 Issues 的 Closes {ID}

  4. 建立 PR

    • 使用 gh pr create 透過 PM Bot GitHub App
    • 必須使用 --body-file（PowerShell 不支援 inline \n）

  5. 發送 Linear Comment

    • 對每個相關 Issue 發送 ## PR Created comment
    • 內容：PR URL, repo, branch, timestamp

  6. 通知 Reviewer

    send_message(to: "reviewer", subject: "review_pr", body: {
      prUrl: "https://github.com/gather-system/Jope.Core/pull/4",
      phase: 4,
      issues: ["JOP-246", "JOP-244", "JOP-245", "JOP-247", "JOP-248"],
      repo: "gather-system/Jope.Core"
    })

階段四：Review Loop — 審查​

觸發條件​

PR 建立後，PM 發送 review_pr 訊息給 Reviewer。

Reviewer 端行為​

  1. 收到 review_pr 訊息
  2. 執行 code-review skill 審查 PR
  3. 產出 Review Report（Critical / High / Medium / Low 分級）
  4. 回報結果：
    • 通過：report_review(result: "approved", hasNextPhase: true/false)
    • 拒絕：report_review(result: "changes", prId: "PR #4")

Sequence Diagram（含 Fix Round）​

階段五：Auto-Advance — 跨 Phase 自動推進​

觸發條件​

  • report_review("approved") 且 hasNextPhase = true
  • Phase Plan 的 autoAdvance = true

Auto-Advance 三階段​

階段動作時間
Cooldown冷卻等待，讓 Broker 穩定預設 5 分鐘
Session Reset通知 Dev 重啟 session等待 Dev 回應（最多 3 分鐘）
ReadyDev 就緒，啟動下一 Phase立即

Sequence Diagram​

手動推進（Auto-Advance 關閉時）​

如果 autoAdvance = false，Review 通過後 Broker 發送 phase_ready 訊息：

PM 收到 phase_ready
→ 使用者手動執行：/start-pipeline {parentId} {nextPhase}
→ 回到階段一

實際案例：Jope.Core Phase 1~4​

以下是 Jope.Core 底層框架 Pipeline 的實際執行紀錄（2026-04-11）：

PhaseIssues內容PRReview耗時
1JOP-237Solution Setup（22 projects）PR #1✅ Approved (0H)10 min
2JOP-240, 238, 239, 241Abstractions + Logging + ConfigPR #2❌→✅ Fix 5H31 min
3JOP-243, 242Transport Layer（Serial + TCP）PR #3✅ Approved (0H)19 min
4JOP-246, 244, 245, 247, 248Protocol Layer（Modbus + 3 vendors）PR #4❌→✅ Fix 9H~2 hr

觀察重點：

  • Phase 1, 3 一次通過；Phase 2, 4 各一輪 fix
  • Fix 都在同一輪完成（fixCount = 1），未觸發 HUMAN_NEEDED
  • Auto-Advance 在每個 Phase 完成後自動推進
  • 全程 PM 只需在 Pipeline 起點啟動，後續由 Broker 自動驅動