docs: v4.1 協作協定重構、新增工具配置指南

- 新增 spec_v4_collaboration_protocol.md:Message Envelope、Intent 類型、
  Pipeline 改由策略師主導、Lobster DSL 取代 Standing Orders、輸出 Schema 定義
- 新增 guide_tools_skills.md:每個角色的 MCP Tools + Skills 配置對照表
- 改寫 guide_sessions_tools.md:修正 maxSpawnDepth 行為,sessions_send 不授權給子 agent
- 更新 agent_roster.md:新增 MCP Tools / Skills 欄位
- 更新排程記憶文件:移除舊協作章節,指向新協作協定
- 更新 INDEX.md:v4.1 索引與變更紀錄

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Chris
2026-04-10 02:30:39 +08:00
parent 513875c623
commit e44b959c85
6 changed files with 913 additions and 215 deletions

View File

@@ -0,0 +1,404 @@
# 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 由策略師 ownCEO 只管啟動和例外 |
| **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 層
- 最大並行子 agent5 個(`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 EnvelopeAgent 間訊息格式)
所有 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 流程
```
你 → CEODiscord→ 「啟動量化 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 |

View File

@@ -1,91 +1,14 @@
# KingClawArmy - 第四部分:協作模式 & 第五部分:排程與觸發 & 第六部分:記憶 & 第七部分Discord
# KingClawArmy - 第五部分:排程與觸發 & 第六部分:記憶 & 第七部分Discord
> 版本v4.1
> 日期2026-04-10
> 狀態:協作模式已獨立至 [spec_v4_collaboration_protocol.md](spec_v4_collaboration_protocol.md)
---
## 第四部分協作模式
### 4.1 三種模式(全部在 OpenClaw 內完成)
| 模式 | OpenClaw 實現 | 場景 |
|---|---|---|
| **Orchestrator** | CEO 用 `sessions_spawn` 派工給 sub-agent | 日常任務分派 |
| **Peer-to-Peer** | Agent 之間用 `sessions_send` 來回溝通(最多 5 輪) | 追問、澄清、交叉驗證 |
| **Coordinator 討論** | CEO 用 `sessions_send` 逐一收集觀點再收斂 | 多方意見整合、辯論替代 |
### 4.2 協作模式詳細流程
#### Orchestrator派工
```
CEO 收到任務
sessions_spawn("finance_researcher", task="蒐集今日盤前資訊")
財經情報研究員在獨立 session 中執行
完成後 push 結果回 CEO
CEO 收到結果spawn 下一個 agent
```
#### Peer-to-Peer直接溝通
```
量化策略研究員讀完多方報告後有疑問
sessions_send("bullish_researcher", "你提到 OB 支撐,具體是哪個價位?")
多方研究員回覆ping-pong 最多 5 輪)
量化策略研究員獲得澄清,繼續工作
```
#### Coordinator 討論(辯論替代方案)
```
CEO 需要整合多空觀點
step 1: sessions_send("bullish_researcher", "總結你的核心做多論點")
step 2: sessions_send("bearish_researcher", "總結你的核心做空論點")
step 3: sessions_send("bearish_researcher", "針對多方的論點 [X],你的反駁是?")
step 4: sessions_send("bullish_researcher", "針對空方的反駁 [Y],你的回應是?")
step 5: sessions_send("quant_strategist", "以下是雙方觀點 [全文],請收斂成策略")
CEO 收到策略規格
```
### 4.3 什麼場景用什麼模式
| 場景 | 模式 | 理由 |
|---|---|---|
| 蒐集資料 | Orchestrator spawn | 獨立任務,不需互動 |
| 寫回測程式 | Orchestrator spawn | 獨立任務 |
| 多空辯論 | Coordinator 討論 | 需要多方觀點交叉 |
| 追問細節 | Peer-to-Peer send | 兩個 agent 直接對話 |
| 審查來回 | Peer-to-Peer send | 審查員與被審者 ping-pong |
| 跨團隊對齊 | Coordinator 討論 | CEO 逐一收集再收斂 |
| 你下達指令 | Discord → CEO | 你對 CEO 說話 |
| 需要你批准 | CEO → Discord @你 | HITL |
### 4.4 Review Gate
| 必審節點 | 觸發方式 |
|---|---|
| 量化策略提交 | CEO spawn 審查員 review |
| 回測結果提交 | CEO spawn 審查員 review |
| 工程交付 | CEO spawn 審查員 review |
| 文案對外 | CEO spawn 審查員 review |
### 4.5 HITL 節點
| 需要你批准的事 | 通知方式 |
|---|---|
| 正式部署 | Discord #approvals @你 |
| DB schema 變更 | Discord #approvals @你 |
| 廣告正式發布 | Discord #approvals @你 |
| 對外訊息發送 | Discord #approvals @你 |
| 金流操作 | Discord #approvals @你 |
| 量化策略正式執行 | Discord #approvals @你 |
> **注意:** 原第四部分協作模式」已重寫並移至獨立文件:
> **[spec_v4_collaboration_protocol.md](spec_v4_collaboration_protocol.md)**
> 包含Message Envelope、Intent 類型、Pipeline 架構、spawn/send 規則、輸出 Schema、Review Gate、HITL 節點
---
@@ -94,9 +17,12 @@ CEO 收到策略規格
### 5.1 Cron 排程
```bash
# 財經情報 — 每日盤前盤後
openclaw cron add --agent finance_researcher --cron "30 7 * * 1-5" --task "盤前資訊蒐集"
openclaw cron add --agent finance_researcher --cron "30 18 * * 1-5" --task "盤後資訊整理"
# 量化 pipeline — 每日盤前自動啟動
# 由 CEO spawn 策略師,策略師接管後續流程
openclaw cron add --agent ceo_coo --cron "30 7 * * 1-5" --task "啟動每日量化 pipeline"
# 財經情報(獨立)— 盤後整理
openclaw cron add --agent ceo_coo --cron "30 18 * * 1-5" --task "spawn 財經情報研究員做盤後整理"
# 市場研究 — 每日 + 每週
openclaw cron add --agent market_researcher --cron "0 10 * * *" --task "每日市場情報"
@@ -113,42 +39,11 @@ openclaw cron add --agent data_analyst --cron "0 10 * * 1" --task "每週數據
openclaw cron add --agent secretary --cron "0 23 * * *" --task "每日記憶壓縮與 State Diff"
```
### 5.2 事件觸發鏈(量化 pipeline
### 5.2 事件觸發鏈
透過 CEO 的 Standing Orders 定義:
Pipeline 流程改由 **Lobster DSL** 定義(見 [spec_v4_collaboration_protocol.md](spec_v4_collaboration_protocol.md) 4.4 節),不再使用 Standing Orders
```
CEO Standing Order: 量化研究流程
當收到財經情報完成通知:
→ spawn market_structure_researcher
當收到市場結構報告完成通知:
→ spawn bullish_researcher平行
→ spawn bearish_researcher平行
當收到多方 + 空方報告都完成:
→ 執行 coordinator 討論(收集雙方觀點)
→ spawn quant_strategist帶入討論結果
當收到量化策略完成通知:
→ spawn quant_engineer
當收到回測完成通知:
→ spawn data_analyst
當收到資料分析完成通知:
→ send secretary做摘要
→ spawn reviewer審查整條 pipeline
當收到審查 pass
→ 組裝 Final_Decision_Packet
→ Discord @董事長 請求批准
當收到審查 revise
→ 退回被點名角色
→ 如超過 3 輪 → Discord @董事長 介入
```
Cron 觸發 CEO → CEO spawn 策略師 → 策略師按 Lobster DSL 自動執行。
---
@@ -183,6 +78,10 @@ CEO Standing Order: 量化研究流程
| 每日筆記 | 自動載入今天+昨天;更舊的靠 memory_search |
| 秘書壓縮 | 每日 23:00 將當日重點寫入 MEMORY.md清理冗餘 |
### 6.4 未來考量
當 Phase 3 行銷團隊加入後,跨團隊記憶需求增大時,可考慮導入 **MemOS**100% 本地、SQLite 後端、混合搜尋、支援多 agent 協作),作為 QMD 的補強或替代。目前 OpenClaw 內建記憶系統足夠 Phase 1-2 使用。
---
## 第七部分Discord Server 結構
@@ -193,14 +92,14 @@ CEO Standing Order: 量化研究流程
KingClawArmy Discord Server
├── 📋 管理
│ ├── #dashboard每日摘要、系統狀態
│ ├── #approvals — HITL 審批(在這裡批准)
│ └── #errors — 錯誤與異常
│ ├── #執行長 執行長回覆董事長、進度回報
│ ├── #審批 — HITL 審批(董事長在這裡批准)
│ └── #異常 — 錯誤與異常
├── 📊 量化
│ ├── #quant-briefing — 盤前盤後情報
│ ├── #quant-discussion — 討論區coordinator 討論結果貼這
│ └── #quant-results — 策略定稿、回測結果
│ ├── #每日情報 — 盤前盤後情報
│ ├── #研究討論 — 研究過程摘要pass 後
│ └── #策略結果 — 策略定稿、回測結果
├── 📈 行銷
│ ├── #marketing-intel — 市場情報
@@ -209,20 +108,23 @@ KingClawArmy Discord Server
├── ✏️ 內容
│ └── #content-briefs — 文案 / 創意 brief
── 📝 記錄
├── #meeting-logs — 所有 coordinator 討論記錄
└── #decision-log — 重大決策
── 📝 記錄
├── #每日摘要 — 秘書每日工作摘要
└── #決策紀錄 — 重大決策存檔
└── 💬 閒聊
└── #閒聊 — 小安陪聊
```
### 7.2 Discord 互動方式
| 你想做的事 | 怎麼做 |
|---|---|
| 下達新指令 | 在 #dashboard 或 DM 跟 CEO agent 說 |
| 下達新指令 | 在 #執行長 跟 CEO agent 說 |
| 查看進度 | 問 CEO 或秘書 |
| 批准高風險動作 | 在 #approvals 回覆 approve / reject |
| 看今日摘要 | #dashboard 自動推送(秘書每日產出) |
| 看回測結果 | #quant-results |
| 批准高風險動作 | 在 #審批 回覆 approve / reject |
| 看今日摘要 | #每日摘要 自動推送(秘書每日產出) |
| 看回測結果 | #策略結果 |
| 手動發起討論 | @CEO 說「召集量化團隊討論 [主題]」 |
| 緊急停止 | `openclaw tasks flow cancel <id>` 或 Discord @CEO「停止 [任務]」 |
@@ -230,9 +132,10 @@ KingClawArmy Discord Server
| 事件 | 推送到 | 由誰推送 |
|---|---|---|
| 任務完成 | 對應區域頻道 | CEO |
| 審查 passHITL | #approvals | CEO |
| 審查 block | #errors + #approvals | CEO |
| 每日摘要 | #dashboard | 秘書 |
| 討論結論 | #meeting-logs | 秘書 |
| 錯誤/異常 | #errors | 相關 agent |
| Pipeline 完成 | #策略結果 + #審批 | CEO |
| 審查 passHITL | #審批 | CEO |
| 審查 block | #異常 + #審批 | CEO |
| 每日情報 | #每日情報 | CEO轉發情報員結果 |
| 每日摘要 | #每日摘要 | 秘書 |
| 決策紀錄 | #決策紀錄 | 秘書 |
| 錯誤/異常 | #異常 | CEO |