# KingClawArmy - 第四部分：Agent 協作協定 > 版本：v4.1 > 日期：2026-04-10 > 狀態：取代 v4.0 協作章節 > 變更：重新定義協作模式、新增 Message Envelope、修正 spawn/send 行為、Pipeline 改由策略師主導 --- ## 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 間的溝通統一使用結構化信封，不使用自由文字： ```json { "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） ```yaml 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： ```json { "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 ```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 ```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 ```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 ```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 ```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 ```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 |