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>
2026-04-10 02:30:39 +08:00
parent 513875c623
commit e44b959c85
6 changed files with 913 additions and 215 deletions
--- a/docs/guides/guide_sessions_tools.md
+++ b/docs/guides/guide_sessions_tools.md
@@ -1,25 +1,28 @@
 # sessions_spawn / sessions_send 使用指南

 > 適用版本：OpenClaw v2026.4.x  
-> 更新日期：2026-04-09
+> 更新日期：2026-04-10  
+> 狀態：v4.1 修正版（修正 spawn/send 工具權限行為）

 ---

-## Agents vs Sub-agent Runs
+## 核心概念
+
+### Agent vs Sub-agent Run

 **Agent** = 有自己 workspace、設定檔、記憶的持久實體。在 `openclaw.json` 的 `agents.list` 裡定義。

-**Sub-agent run** = 當一個 Agent 被 `sessions_spawn` 呼叫時，那次在隔離 session 裡的執行。Session key 格式：`agent:<agentId>:subagent:<uuid>`。
+**Sub-agent run** = 當一個 Agent 被 `sessions_spawn` 呼叫時，在隔離 session 裡的那次執行。Session key 格式：`agent:<agentId>:subagent:<uuid>`。

-兩者不是不同等級，只是存在方式不同：同一個 Agent 可以被 spawn 成 sub-agent run 來執行任務，完成後 announce 結果回去。
+同一個 Agent 可以被 spawn 成 sub-agent run 來執行任務，完成後 announce 結果回 parent。

 ---

-## sessions_spawn — 派工（非阻塞）
+## sessions_spawn — 非阻塞派工

 **行為：** 立即返回 `runId` 和 `childSessionKey`，不等待結果。對方 Agent 在獨立 session 執行，完成後 announce 結果。

-**使用場景：** 獨立任務，不需要即時來回溝通。
+**使用場景：** Pipeline 步驟交接、獨立任務、並行研究。

 ```json
 {
@@ -41,23 +44,18 @@
 | `sandbox: "require"` | 強制沙箱隔離 |
 | `model` | 覆蓋模型設定 |

-**限制：**
- 最多 5 層深（spawn 的 spawn 的 spawn...）
- 最多 5 個並行
- 預設葉層 sub-agent 不具備 sessions 工具（無法再 spawn）
-
 ---

-## sessions_send — 同步溝通（可等待回覆）
+## sessions_send — 同步對話（阻塞）

-**行為：** 向另一個 session 傳訊，可設定是否等待回覆。支援最多 5 輪來回。
+**行為：** 向另一個 session 傳訊，sender 等待回覆。支援最多 5 輪來回。

-**使用場景：** 追問細節、審查來回、交叉確認。
+**使用場景：** CEO 問秘書即時問題、depth-0 agent 之間的直接對話。

 ```json
 {
-  "sessionKey": "agent:reviewer:subagent:xxxx",
-  "message": "請審查以下量化策略內容：[...]",
+  "sessionKey": "agent:secretary:subagent:xxxx",
+  "message": "給我今日工作摘要",
  "timeoutSeconds": 60
 }
 ```
@@ -74,14 +72,82 @@

 ---

+## maxSpawnDepth — 子 agent 工具權限控制
+
+這是控制嵌套 spawn 能力的核心參數。
+
+### 設定方式
+
+在 `openclaw.json` 中設定：
+
+```jsonc
+{
+  "tools": {
+    "subagents": {
+      "maxSpawnDepth": 2,           // 允許 depth-1 子 agent 再 spawn
+      "maxChildrenPerAgent": 5,      // 每個 session 最多 5 個子 agent（可調至 20）
+      "maxConcurrent": 8             // 全局最大併發
+    }
+  }
+}
+```
+
+### 各深度的工具權限
+
+| 深度 | 角色 | 可用的 Session 工具 |
+|---|---|---|
+| **Depth 0**（主 agent） | 完整權限 | `sessions_spawn`, `sessions_send`, `subagents`, `sessions_list`, `sessions_history` |
+| **Depth 1**（maxSpawnDepth=1） | 葉層 | ❌ 無任何 session 工具 |
+| **Depth 1**（maxSpawnDepth≥2） | 編排者 | ✅ `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` |
+| **Depth 2+** | 永遠葉層 | ❌ 無任何 session 工具（`sessions_spawn` 永遠被拒絕） |
+
+### 關鍵限制
+
+| 限制 | 說明 |
+|---|---|
+| **`sessions_send` 不授權給任何子 agent** | 無論 maxSpawnDepth 設多少，被 spawn 的 agent 都不能用 `sessions_send` |
+| **通訊方向為單向往上** | 子 agent 只能 announce 結果回 parent，不能橫向溝通 |
+| **同層不能對話** | 兩個 depth-2 的子 agent 之間無法直接通訊 |
+| **Depth 2 永遠是葉層** | 即使 maxSpawnDepth > 2，depth-2 的 agent 也不能再 spawn |
+
+### KingClawArmy 建議設定
+
+```jsonc
+{
+  "tools": {
+    "subagents": {
+      "maxSpawnDepth": 2,           // 策略師（depth 1）可以 spawn 研究員（depth 2）
+      "maxChildrenPerAgent": 7,      // 策略師最多需要 spawn 7 個研究員
+      "maxConcurrent": 8,
+      "allowAgents": ["*"]           // 允許 spawn 任何 agent
+    }
+  }
+}
+```
+
+---
+
 ## 使用情境對照

 | 情境 | 工具 | 原因 |
 |---|---|---|
-| 蒐集資料 | spawn | 獨立任務，不需互動 |
-| 寫回測程式 | spawn | 獨立任務 |
-| 多空平行研究 | spawn（兩個） | 並行執行 |
-| 追問研究員細節 | send | 兩個 agent 直接對話 |
-| 審查員來回審查 | send | 需要 ping-pong |
-| 請秘書做摘要 | spawn 或 send | 依是否需要等待 |
-| Coordinator 討論 | send（逐一收集） | 整合多方觀點 |
+| CEO 啟動量化 pipeline | **spawn** 策略師 | CEO 不能阻塞 |
+| 策略師派工給情報員 | **spawn** | 獨立任務（策略師是 depth-1 編排者） |
+| 策略師並行派工多方/空方 | **spawn**（兩個） | 並行執行 |
+| 策略師發現報告缺漏 | **重新 spawn** | 帶上前次結果 + 修改意見 |
+| 策略師提交審查 | **spawn** 審查員 | 審查是獨立任務 |
+| 審查退回修改 | 策略師**重新 spawn** | 帶上 Review_Report.json 的 issues |
+| CEO 問秘書今日摘要 | **send** | CEO 是 depth-0，需要即時回覆 |
+| 你在 Discord 問 CEO | **Discord message** | 不經 session 工具 |
+
+---
+
+## 常見錯誤
+
+| 錯誤 | 為什麼不行 | 正確做法 |
+|---|---|---|
+| 策略師 send 研究員追問 | 被 spawn 的 agent 沒有 `sessions_send` | 重新 spawn，帶上問題 |
+| CEO 用 send 啟動 pipeline | CEO 會阻塞等整條 pipeline 跑完 | 用 spawn |
+| 研究員之間互相 send | 同層子 agent 不能橫向通訊 | 各自 announce 回策略師，由策略師整合 |
+| 用 Standing Orders 定義 pipeline | 自然語言無強制力 | 用 Lobster DSL 定義 flow |
+| Agent 用自由文字溝通 | 接收方要猜意圖 | 用 Message Envelope + intent |
--- a/docs/guides/guide_tools_skills.md
+++ b/docs/guides/guide_tools_skills.md
@@ -0,0 +1,256 @@
+# MCP Tools & Skills 配置指南
+
+> 適用版本：OpenClaw v2026.4.x  
+> 更新日期：2026-04-10
+
+---
+
+## MCP Tools vs Skills 的差異
+
+| | MCP Tools | Skills |
+|---|---|---|
+| **是什麼** | 獨立程序，透過 Model Context Protocol 提供能力 | `SKILL.md` 資料夾，教 agent 做事的方法論 |
+| **類比** | 一把工具（鋸子、螺絲起子） | SOP 手冊（怎麼組裝傢俱） |
+| **範例** | Tavily = 搜尋能力 | Deep Research = 結構化研究流程 |
+| **可移植性** | 跨平台（Claude Desktop、Cursor 等都能用） | OpenClaw 專用 |
+| **關係** | 獨立運作 | 65% 的 skill 底層會呼叫 MCP tool |
+| **安裝** | `openclaw.json` 設定 | `clawhub install <slug>` |
+
+**簡單說：MCP 是手，Skill 是腦裡的方法論。按角色搭配。**
+
+---
+
+## 配置原則
+
+| 原則 | 說明 |
+|---|---|
+| **按角色配，不要全裝** | 工具定義會佔 context token，太多工具 agent 會選錯 |
+| **蒐集者裝工具，判斷者不裝** | 情報員需要搜尋；策略師只需要讀報告收斂 |
+| **一個 MCP 可以多人共用** | MCP server 啟動一次，多個 agent 共用同一個 |
+| **先跑再加** | 先用最少工具跑通 pipeline，有需求再加 |
+
+---
+
+## Phase 2 — 量化研究團隊配置
+
+### 💹 財經情報研究員 `finance_researcher`
+
+**角色定位：** 資料蒐集者，需要大量外部資料
+
+| 類型 | 工具 | 用途 | 安裝方式 |
+|---|---|---|---|
+| MCP | **Tavily** | AI 優化搜尋，自動帶引用來源 | API key（有免費額度） |
+| MCP | **Firecrawl** | 爬網頁全文，7 秒抓完一頁 | API key |
+| MCP | **Financial Datasets** | 財報、SEC 文件、股價、加密貨幣新聞 | API key |
+| Skill | **Deep Research** | 結構化深度研究流程：搜尋→多源交叉驗證→綜合 | `clawhub install deep-research` |
+| 內建 | `memory_write` | 寫入每日筆記 | 內建 |
+| 內建 | `memory_search` | 搜尋歷史記憶 | 內建 |
+
+### 📈 市場結構研究員 `market_structure_researcher`
+
+**角色定位：** 技術分析專家，需要行情數據
+
+| 類型 | 工具 | 用途 | 安裝方式 |
+|---|---|---|---|
+| MCP | **TradingView MCP** | 30+ 技術指標、K 線圖、情緒指標 | 自架 Python |
+| MCP | **Alpha Vantage** | 即時/歷史行情、外匯、加密、總經數據 | API key（免費） |
+| Skill | **Deep Research** | 配合行情數據做結構化分析 | `clawhub install deep-research` |
+| 內建 | `memory_search` | 搜尋歷史記憶 | 內建 |
+
+### 🚀 多方研究員 `bullish_researcher`
+
+**角色定位：** 觀點整理者，不做資料蒐集
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| 內建 | `memory_search` | 讀取情報員、市場結構的報告（via QMD） |
+
+> 不需要外部 MCP 或 Skill。他的 input 是其他 agent 的報告，不是原始數據。
+> 給他搜尋工具會讓他跑去自己找資料，偏離角色分工。
+
+### 🛡️ 空方研究員 `bearish_researcher`
+
+同多方研究員，只有 `memory_search`。
+
+### 🧭 量化策略師 `quant_strategist`
+
+**角色定位：** 收斂者 + Pipeline Owner
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| 內建 | `memory_search` | 讀取所有研究報告 |
+| 內建 | `sessions_spawn` | 派工給研究員（需要 maxSpawnDepth ≥ 2） |
+| 內建 | `subagents` | 管理子 agent |
+| 內建 | `sessions_list` | 查看 session 狀態 |
+
+> 不需要外部工具。策略師的價值在判斷和收斂，不在蒐集。
+
+### ⚙️ 回測工程師 `quant_engineer`
+
+**角色定位：** 程式碼執行者
+
+| 類型 | 工具 | 用途 | 安裝方式 |
+|---|---|---|---|
+| MCP | **E2B** | 沙箱 Python 環境，裝 pandas/numpy/backtrader | API key |
+| MCP | **FinClaw** | AI 量化引擎：回測、策略進化 | 自架 Python |
+| Skill | **Code Reviewer** | 回測程式碼自我檢查 | `clawhub install code-reviewer` |
+| 內建 | `exec` | 執行命令 | 內建 |
+| 內建 | `file_ops` | 讀寫檔案 | 內建 |
+| 內建 | `memory_write` | 記錄回測結果 | 內建 |
+
+### 🧪 資料分析員 `data_analyst`
+
+**角色定位：** 數據分析 + 視覺化
+
+| 類型 | 工具 | 用途 | 安裝方式 |
+|---|---|---|---|
+| MCP | **E2B** | 跟回測工程師共用沙箱環境 | 同上 |
+| MCP | **Plotly MCP** | 49+ 圖表類型，自然語言生圖 | 自架 Python |
+| Skill | **Deep Research** | 拉外部 benchmark 比對分析 | `clawhub install deep-research` |
+| 內建 | `code_execution` | 跑分析腳本 | 內建 |
+| 內建 | `memory_search` | 搜尋歷史數據 | 內建 |
+| 內建 | `memory_write` | 記錄分析結果 | 內建 |
+
+---
+
+## Phase 1 — 管理團隊配置
+
+### 🎯 CEO `ceo_coo`
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| 內建 | `sessions_spawn` | 啟動 pipeline、派工 |
+| 內建 | `sessions_send` | 問秘書即時問題（depth-0 才能用） |
+| 內建 | `cron` | 排程管理 |
+| 內建 | `memory_search` | 搜尋歷史 |
+| 內建 | Discord 工具 | 跟董事長溝通、推送通知 |
+
+> CEO 不需要外部工具，他的工作是管理和協調。
+
+### 📋 秘書 `secretary`
+
+| 類型 | 工具 | 用途 | 安裝方式 |
+|---|---|---|---|
+| Skill | **GOG (Google Workspace)** | Gmail + Calendar + Drive + Sheets | `clawhub install gog`（如果用 Google 生態） |
+| 內建 | `memory_search` | 搜尋所有 agent 記憶（via QMD） |
+| 內建 | `memory_write` | 寫入摘要、壓縮記憶 |
+| 內建 | Discord 工具 | 推送每日摘要 |
+
+### 🔍 審查員 `reviewer`
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| 內建 | `memory_search` | 讀取被審查的產出 |
+
+> 審查員只需要讀，不需要搜尋或執行。純粹的判斷角色。
+
+---
+
+## Phase 3 — 行銷策略團隊（預規劃）
+
+### 市場研究員 `market_researcher`
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| MCP | **Tavily** | 共用搜尋（同情報員） |
+| MCP | **Exa** | 語意搜尋，按「意思」找內容 |
+| MCP | **Firecrawl** | 爬競品網站 |
+| Skill | **Deep Research** | 結構化市場研究 |
+| 內建 | `memory_write` | 記錄研究 |
+
+### 策略總監 `strategy_director`
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| 內建 | `memory_search` | 讀取市場研究報告 |
+
+> 同策略師邏輯：收斂者不需要外部工具。
+
+### 投放分析師 `ads_analyst`
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| MCP | **廣告平台 API** | Google Ads / Meta Ads 數據（需自行包 MCP） |
+| MCP | **Plotly MCP** | 投放報表視覺化 |
+| 內建 | `memory_write` | 記錄 KPI |
+
+---
+
+## Phase 4 — 內容創意團隊（預規劃）
+
+### 文案撰寫員 `copywriter`
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| Skill | **SEO Blog Writer** | 搜尋優化文章結構 |
+| 內建 | `memory_search` | 讀取品牌語氣庫 |
+
+### 創意總監 `creative_director`
+
+| 類型 | 工具 | 用途 |
+|---|---|---|
+| MCP | **DALL-E / Flux MCP** | 生成參考圖、素材 mock |
+| MCP | **Firecrawl** | 抓競品視覺參考 |
+| 內建 | `memory_search` | 讀取品牌規範 |
+
+---
+
+## MCP Server 安裝總覽
+
+Phase 2 只需要安裝 5 個外部 MCP server：
+
+| # | MCP Server | 誰用 | 類型 | 優先級 |
+|---|---|---|---|---|
+| 1 | **Tavily** | 情報員 (+Phase 3 市場研究員) | API key | 必裝 |
+| 2 | **Firecrawl** | 情報員 (+Phase 3/4) | API key | 必裝 |
+| 3 | **Financial Datasets** 或 **Alpha Vantage** | 情報員 + 市場結構 | API key | 必裝 |
+| 4 | **TradingView MCP** | 市場結構 | 自架 Python | 必裝 |
+| 5 | **E2B** 或 **FinClaw** | 回測 + 資料分析 | API key / 自架 | 必裝 |
+
+Phase 3 新增：
+
+| # | MCP Server | 誰用 | 類型 |
+|---|---|---|---|
+| 6 | **Exa** | 市場研究員 | API key |
+| 7 | **廣告平台 API** | 投放分析師 | 自行包裝 |
+| 8 | **Plotly MCP** | 資料分析 + 投放分析 | 自架 Python |
+
+Phase 4 新增：
+
+| # | MCP Server | 誰用 | 類型 |
+|---|---|---|---|
+| 9 | **DALL-E / Flux** | 創意總監 | API key |
+
+---
+
+## Skill 安裝總覽
+
+| Skill | 誰用 | 安裝指令 | Phase |
+|---|---|---|---|
+| **Deep Research** | 情報員、市場結構、資料分析 | `clawhub install deep-research` | 2 |
+| **Code Reviewer** | 回測工程師 | `clawhub install code-reviewer` | 2 |
+| **GOG** | 秘書（如果用 Google） | `clawhub install gog` | 1 |
+| **SEO Blog Writer** | 文案撰寫員 | `clawhub install seo-blog-writer` | 4 |
+
+---
+
+## 安全注意事項
+
+### ClawHub 安全
+
+ClawHub 曾發生 **ClawHavoc** 惡意 skill 攻擊事件，偽造熱門 skill 名稱植入後門。
+
+| 檢查項目 | 說明 |
+|---|---|
+| 看原始碼 | 安裝前檢查 `SKILL.md` 和 install 腳本 |
+| 看安裝數 | 優先選高安裝數 + verified 標記的 |
+| 看名稱 | 不要裝 typo 版本（如 `deep-reserach`） |
+| 沙箱隔離 | 不信任的 skill 用 `sandbox: "require"` |
+
+### MCP Server 安全
+
+| 檢查項目 | 說明 |
+|---|---|
+| API key 管理 | 用環境變數，不要硬寫在設定檔 |
+| 網路隔離 | 自架的 MCP 只綁 localhost |
+| 權限最小化 | API key 只給必要的 scope |