Pipeline 訊息協議

所有 Agent 之間的通訊透過 Pipeline Broker 的訊息佇列進行。本頁定義訊息結構、Subject 列表、Priority Queue 機制。

Message 結構

{
  "id": "msg-uuid-v4",
  "from": "pm",
  "to": "dev",
  "subject": "develop",
  "body": {
    "issue": "JOP-240",
    "phase": 2,
    "totalIssues": 4,
    "currentIndex": 1
  },
  "priority": 4,
  "timestamp": "2026-04-11T01:10:00.000Z",
  "replyTo": null,
  "status": "pending"
}

欄位	型別	說明
id	string	UUID v4，全局唯一
from	string	發送者 Agent ID（pm, dev, reviewer）
to	string	接收者 Agent ID
subject	string	訊息類型（見下方列表）
body	object	訊息內容（依 subject 不同而異）
priority	number	1（最高）~ 5（最低）
timestamp	string	ISO-8601 時間戳
replyTo	string | null	回覆對象的 message ID（用於對話串）
status	string	pending → delivered → replied（或 expired）

---

Priority Queue

訊息按優先級排序，同優先級按時間排序（FIFO）。

---

Subject 完整列表

PM → Dev

Subject	Priority	Payload	說明
develop	4	{ issue, phase, totalIssues, currentIndex, retry? }	派發 Issue 給 Dev 開發
fix_review_changes	4	{ issues, fixInstructions, prUrl }	PR 審查被拒，派發修正指令
session_reset	5	{ reason, nextPhase }	要求 Dev 重啟 session（Auto-Advance 用）

Dev → PM

Subject	Priority	Payload	說明
issue_complete	4	{ issue, phase, summary, branch, testResults }	Issue 開發完成
issue_failed	4	{ issue, error, attempt, failCount }	Issue 開發失敗
ready	5	{ nextPhase }	Dev 回應 session_reset，準備就緒
alert	2	{ message, severity }	Dev 遇到需注意的問題
needs_human	2	{ reason, type }	Dev 判斷需人工介入

PM → Reviewer

Subject	Priority	Payload	說明
review_pr	4	{ prUrl, phase, issues[], repo }	請 Reviewer 審查 PR

Reviewer → PM

Subject	Priority	Payload	說明
review_approved	3	{ prUrl, phase, summary }	PR 審查通過
review_changes	3	{ prUrl, issues[], comments, severity }	PR 審查要求修正

Pipeline（Broker 自動產生）→ All

Subject	Priority	Payload	說明
auto_advance	3	{ stage, targetPhase, cooldownMs }	Auto-Advance 進度通知
auto_advance_complete	3	{ phase, issues[] }	Auto-Advance 完成，下一 Phase 就緒
phase_ready	4	{ nextPhase, autoAdvance }	Phase 就緒（Auto-Advance 關閉時）
needs_human	2	{ reason, type, fromState }	安全機制觸發，Pipeline 暫停
stop	1	{ reason }	Pipeline 停止
error	1	{ message, stack }	系統錯誤
info	5	{ message }	一般資訊

---

訊息流向圖

---

訊息持久化

tracker.json 結構

{
  "messages": [
    {
      "id": "msg-abc-123",
      "from": "pm",
      "to": "dev",
      "subject": "develop",
      "body": { "issue": "JOP-240" },
      "priority": 4,
      "timestamp": "2026-04-11T01:10:00Z",
      "status": "delivered",
      "deliveredAt": "2026-04-11T01:10:01Z",
      "repliedAt": null,
      "replyTo": null
    }
  ]
}

狀態追蹤

狀態	說明
pending	已入佇列，尚未投遞（Agent 可能離線）
delivered	已投遞給目標 Agent
replied	Agent 已透過 reply_message 回覆
expired	超時未投遞（timeout 設定後）

---

重連與訊息重投

重連行為規則

1. Client 端：TCP 斷線後每 3 秒自動重試連線
2. Broker 端：斷線時拒絕該 Agent 的 pending request（返回 error）
3. 佇列保留：斷線期間的新訊息保留在佇列中，不丟棄
4. 重連投遞：Agent 重連並呼叫 wait_for_message 後，按優先級投遞所有 pending 訊息
5. Auto-Advance：如果斷線的是 Dev，且正在 Auto-Advance 的 session_reset 階段，等待 3 分鐘後若仍未重連則取消 Auto-Advance 並進入 HUMAN_NEEDED