KingClawArmy/docs/spec/spec_collaboration_protocol.md

KingClawArmy - 第四部分：Agent 協作協定

日期：2026-04-10
狀態：定稿（遷移至 Paperclip 前的參考版本）

---

4.1 設計原則

原則	說明
Spawn 優先	Pipeline 步驟一律用 sessions_spawn，不阻塞任何 agent
Send 只用於即時對話	只有 depth-0 的獨立 agent 之間才能 sessions_send
策略師主導 Pipeline	量化 pipeline 由策略師 own，CEO 只管啟動和例外
Schema 消除追問	嚴格定義輸出格式，讓 agent 一次交齊，不需要來回追問
向上回報	子 agent 透過 announce 回傳結果，不能橫向對話

---

4.2 通訊工具行為（已驗證）

sessions_spawn — 非阻塞派工

• 立即返回 runId，不等待結果
• 對方在隔離 session 中執行，完成後 announce 結果回 parent
• Parent 可繼續處理其他事

sessions_send — 同步對話（阻塞）

• Sender 等待對方回覆（可設 timeoutSeconds）
• 最多 5 輪來回
• 只有 depth-0 的獨立 agent 能使用

maxSpawnDepth 與工具權限

maxSpawnDepth	Depth-1 子 agent	Depth-2 子 agent
1（預設）	❌ 無 session 工具（葉層）	—
≥ 2	✅ sessions_spawn, subagents, sessions_list, sessions_history	❌ 永遠是葉層

關鍵限制：

• sessions_send 不在任何子 agent 的授權清單中，無論 maxSpawnDepth 設多少
• 通訊方向為單向往上：子 agent 只能 announce 回 parent
• 同層子 agent 之間不能互相通訊
• 最大嵌套深度：5 層
• 最大並行子 agent：5 個（maxChildrenPerAgent，可調至 20）
• 最大併發：8 個（maxConcurrent）

判斷規則

你需要對方「現在立刻回答你」才能繼續嗎？

• Yes → sessions_send（僅限 depth-0 agent）
• No → sessions_spawn

情境	工具	原因
Pipeline 步驟交接	spawn	獨立任務，不需等待
並行研究	spawn（多個）	各做各的
CEO 啟動 pipeline	spawn	CEO 不能被阻塞
CEO 問秘書「今日摘要」	send	CEO 是 depth-0，需要即時回覆
審查員退回修改	重新 spawn	帶上修改意見再跑一次
需要追問細節	重新 spawn	帶上前次結果 + 具體問題

---

4.3 Message Envelope（Agent 間訊息格式）

所有 agent 間的溝通統一使用結構化信封，不使用自由文字：

{
  "from": "bullish_researcher",
  "to": "quant_strategist",
  "intent": "deliver_report",
  "ref_task": "quant-pipeline-2026-04-10",
  "payload": { "$ref": "Bullish_Brief.json" },
  "expect_response": false
}

Intent 類型

intent	方向	說明
assign_task	parent → child	派工指令
deliver_report	child → parent	任務完成，結果在 payload
request_clarification	parent → child	追問（透過重新 spawn）
review_request	→ reviewer	請求審查
review_verdict	reviewer → parent	審查結果：pass / revise / block
collect_opinion	coordinator → agent	收集觀點
escalate	any → CEO	上報異常
notify	any → Discord	通知（非對話）

Payload 規範

• 所有 payload 必須是定義好的 JSON schema（見各 agent 的 AGENTS.md）
• 不在 JSON 之外附加自由文字說明
• 缺少必填欄位時，回傳 missing_fields 清單而非空值

---

4.4 Pipeline 架構

角色分工

CEO 的職責：
  ✅ 接收董事長指令
  ✅ spawn 啟動 pipeline（策略師）
  ✅ 處理 escalation 和 HITL
  ✅ 多 pipeline 並行管理
  ❌ 不逐步 spawn 每個研究員（那是策略師的事）

策略師的職責：
  ✅ 擁有量化 pipeline 的執行權
  ✅ spawn 研究員、收斂結果
  ✅ spawn 審查員、處理 revise
  ✅ 管理研究員的輸出品質
  ❌ 不做資料蒐集（那是研究員的事）

量化 Pipeline 流程

你 → CEO（Discord）→ 「啟動量化 pipeline」
      │
      └─ spawn 策略師（depth 1, maxSpawnDepth ≥ 2）
              │
              ├─ spawn 情報員（depth 2）
              │    └─ announce Finance_Research_Brief.json
              │
              ├─ spawn 市場結構研究員（depth 2，等情報完成）
              │    └─ announce Market_Structure_Report.json
              │
              ├─ spawn 多方研究員（depth 2）──┐ 並行
              ├─ spawn 空方研究員（depth 2）──┘ 並行
              │    └─ 都 announce 完成
              │
              ├─ 策略師自己收斂 → Strategy_Thesis.json
              │
              ├─ spawn 審查員（depth 2）
              │    └─ announce Review_Report.json
              │         ├─ pass → 繼續
              │         ├─ revise → 策略師重新 spawn 被退回的角色（帶修改意見）
              │         │          最多 3 輪，超過 → escalate CEO
              │         └─ block → escalate CEO
              │
              └─ announce 給 CEO「pipeline 完成」
                    │
                    └─ CEO → Discord @董事長 請求批准

Lobster DSL 定義（取代 Standing Orders）

name: daily_quant_pipeline
trigger: cron "30 7 * * 1-5"
owner: quant_strategist

steps:
  - id: intel
    agent: finance_researcher
    action: spawn
    output: Finance_Research_Brief.json

  - id: structure
    agent: market_structure_researcher
    action: spawn
    depends_on: [intel]
    output: Market_Structure_Report.json

  - id: bull
    agent: bullish_researcher
    action: spawn
    depends_on: [structure]
    output: Bullish_Brief.json

  - id: bear
    agent: bearish_researcher
    action: spawn
    depends_on: [structure]
    output: Bearish_Brief.json

  - id: converge
    agent: quant_strategist
    action: self
    depends_on: [bull, bear]
    output: Strategy_Thesis.json

  - id: review
    agent: reviewer
    action: spawn
    depends_on: [converge]
    output: Review_Report.json
    on_revise: retry(converge, max=3)
    on_block: escalate(ceo_coo)

  - id: data_analysis
    agent: data_analyst
    action: spawn
    depends_on: [review]
    condition: review.verdict == "pass"
    output: Data_Analysis_Report.json

  - id: approve
    type: hitl
    channel: "#approvals"
    depends_on: [data_analysis]

追問處理（重新 Spawn 模式）

當策略師發現研究員報告有缺漏，不用 send，用重新 spawn：

{
  "from": "quant_strategist",
  "to": "bullish_researcher",
  "intent": "request_clarification",
  "ref_task": "quant-pipeline-2026-04-10",
  "payload": {
    "previous_report": { "$ref": "Bullish_Brief.json" },
    "missing_fields": ["key_levels[].evidence", "invalidation"],
    "question": "你提到 OB 支撐，請補充具體價位與時間框架"
  }
}

但設計目標是讓追問不需要發生 — 靠嚴格的輸出 schema 讓 agent 一次交齊。

---

4.5 輸出 Schema（核心）

每個 agent 的產出必須遵循定義好的 JSON schema，寫在各 agent 的 AGENTS.md 中。

Finance_Research_Brief.json

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "macro_summary": "...",
  "key_events": [
    { "event": "...", "impact": "bullish|bearish|neutral", "source": "..." }
  ],
  "sentiment": { "overall": "bullish|bearish|neutral", "score": 0.0 },
  "data_sources": ["..."]
}

Market_Structure_Report.json

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "timeframes_analyzed": ["H4", "H1"],
  "structure": {
    "trend": "bullish|bearish|ranging",
    "mss_detected": true,
    "key_levels": [
      { "type": "OB|FVG|POI|support|resistance", "price": 0, "timeframe": "H4", "tested": false }
    ]
  },
  "liquidity_zones": [
    { "type": "buy_side|sell_side", "range": [0, 0], "significance": "high|medium|low" }
  ]
}

Bullish_Brief.json / Bearish_Brief.json

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "thesis": "核心論點（一句話）",
  "arguments": [
    { "point": "...", "evidence": "...", "confidence": 0.0 }
  ],
  "key_levels": [
    { "type": "support|resistance", "price": 0, "timeframe": "H4", "evidence": "..." }
  ],
  "catalysts": ["..."],
  "invalidation": "什麼條件下論點失效",
  "confidence": 0.0,
  "data_sources": ["..."]
}

Strategy_Thesis.json

{
  "date": "2026-04-10",
  "market": "BTC/USDT",
  "direction": "long|short|neutral",
  "thesis": "收斂後的策略論點",
  "entry_zone": [0, 0],
  "stop_loss": 0,
  "take_profit": [0, 0],
  "risk_reward": 0.0,
  "position_size_pct": 0.0,
  "risk_assessment": {
    "max_drawdown_pct": 0.0,
    "bias_check": "confirmed|conflicting",
    "bull_confidence": 0.0,
    "bear_confidence": 0.0
  },
  "invalidation": "...",
  "requires_backtest": true
}

Review_Report.json

{
  "date": "2026-04-10",
  "reviewed_artifact": "Strategy_Thesis.json",
  "verdict": "pass|revise|block",
  "score": 0.0,
  "issues": [
    { "severity": "critical|major|minor", "field": "...", "description": "...", "suggestion": "..." }
  ],
  "revise_target": "quant_strategist|bullish_researcher|...",
  "summary": "..."
}

Data_Analysis_Report.json

{
  "date": "2026-04-10",
  "analyzed_artifact": "Backtest_Delivery.json",
  "metrics": {
    "total_trades": 0,
    "win_rate": 0.0,
    "profit_factor": 0.0,
    "max_drawdown_pct": 0.0,
    "sharpe_ratio": 0.0,
    "avg_rr": 0.0
  },
  "insights": ["..."],
  "recommendation": "proceed|adjust|reject",
  "summary": "..."
}

---

4.6 Review Gate

必審節點	觸發方式	審查標準
量化策略提交	策略師 spawn 審查員	schema 完整性 + 風控邏輯
回測結果提交	策略師 spawn 審查員	績效指標合理性
工程交付	CEO spawn 審查員	程式碼品質 + 測試覆蓋
文案對外	CEO spawn 審查員	品牌一致性 + 法規合規

Revise 流程

審查員 announce: { verdict: "revise", revise_target: "bullish_researcher", issues: [...] }
  ↓
策略師收到 → 重新 spawn 多方研究員，帶上 issues
  ↓
多方研究員修改 → announce 新版本
  ↓
策略師再 spawn 審查員 review
  ↓
最多 3 輪。超過 → escalate CEO → CEO Discord @董事長

---

4.7 HITL 節點

需要董事長批准的事	通知方式
量化策略正式執行	Discord #approvals @董事長
正式部署	Discord #approvals @董事長
DB schema 變更	Discord #approvals @董事長
廣告正式發布	Discord #approvals @董事長
對外訊息發送	Discord #approvals @董事長
金流操作	Discord #approvals @董事長

---

4.8 錯誤處理

錯誤類型	處理方式
Agent 執行超時	策略師重新 spawn，帶上 timeout 通知
Agent 回傳 missing_fields	策略師重新 spawn，明確要求補齊
審查 block	escalate CEO → Discord @董事長
審查 revise 超過 3 輪	escalate CEO → Discord @董事長
Pipeline 異常中斷	CEO 通知 Discord #errors
模型 API 錯誤	自動重試 1 次，失敗 → Discord #errors