docs: 移除 v4 版號命名，新增 Paperclip 遷移規劃

- spec 檔案重新命名去除 v4 前綴 - 更新所有內部交叉引用 - 新增 migration_to_paperclip.md：概念對照、目標結構、Agent 定義、排程轉換 - INDEX.md 標記 OpenClaw 時期文檔為遷移參考用 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-10 15:32:07 +00:00
parent e44b959c85
commit 253f38a75e
8 changed files with 295 additions and 55 deletions
--- a/docs/spec/spec_org_and_roles.md
+++ b/docs/spec/spec_org_and_roles.md
@@ -0,0 +1,317 @@
+# KingClawArmy - 第二部分：組織架構 & 第三部分：角色定義
+
+---
+
+## 第二部分：組織架構
+
+### 2.1 團隊結構
+
+```
+董事長（你，人類，透過 Discord 操作）
+│
+├── 管理團隊 (3 agents)
+│   ├── CEO/COO          ← coordinator，管理所有 sub-agent
+│   ├── 秘書             ← 記憶管理、摘要、狀態追蹤
+│   └── 審查員           ← 品質把關 pass/revise/block
+│
+├── 量化研究團隊 (7 agents)
+│   ├── 財經情報研究員
+│   ├── 市場結構研究員
+│   ├── 多方研究員
+│   ├── 空方研究員
+│   ├── 量化策略研究員（含風控）
+│   ├── 回測工程師
+│   └── 資料分析員
+│
+├── 行銷策略團隊 (3 agents)
+│   ├── 市場研究員
+│   ├── 策略總監
+│   └── 投放成效分析師
+│
+├── 內容創意團隊 (2 agents)
+│   ├── 文案撰寫員
+│   └── 創意總監
+│
+└── 工程團隊 (0~2 agents)
+    ├── 前端工程師
+    └── 後端工程師
+```
+
+**總計：15 ~ 17 agents**
+
+### 2.2 OpenClaw Agent 配置結構
+
+每個 agent 在 `~/.openclaw/openclaw.json` 中定義：
+
+```jsonc
+{
+  "agents": [
+    {
+      "name": "ceo_coo",
+      "model": "claude-sonnet-4-6",  // 或任何模型
+      "workspace": "~/.openclaw/workspaces/ceo_coo",
+      "bindings": [
+        { "channel": "discord:#commands", "guild": "<guild_id>" }
+      ],
+      "system_prompt_file": "SOUL.md",
+      "memory_engine": "qmd",
+      "tools": ["sessions_spawn", "sessions_send", "cron", "memory_search"]
+    }
+    // ... 其他 agents
+  ]
+}
+```
+
+### 2.3 Agent 間的關係（routing）
+
+```
+CEO/COO (coordinator)
+├── sessions_spawn → 財經情報研究員（派工，異步）
+├── sessions_spawn → 市場結構研究員
+├── sessions_spawn → 多方研究員 / 空方研究員（平行派工）
+├── sessions_spawn → 量化策略研究員
+├── sessions_send  → 審查員（同步來回審查）
+├── sessions_send  → 秘書（同步請求摘要）
+└── Discord @mention → 你（HITL 審批）
+```
+
+### 2.4 狀態分類
+
+| 狀態 | 說明 | 角色 | OpenClaw 實現 |
+|---|---|---|---|
+| **常駐** | 持續運行 | CEO/COO、秘書 | Standing Orders + 高頻 cron |
+| **Warm** | 高頻喚醒 | 審查員 | 事件觸發（hooks） |
+| **喚醒** | 排程或事件觸發 | 其餘所有 agent | cron + hooks |
+
+---
+
+## 第三部分：角色定義
+
+> 所有 agent 運行於 OpenClaw  
+> 每個 agent 有獨立的 workspace（SOUL.md + MEMORY.md + AGENTS.md）
+
+### 3.0 模型等級分類
+
+| 等級 | 說明 | 適用模型舉例 |
+|---|---|---|
+| **reasoning-heavy** | 深度推理、策略收斂、審查 | Claude Opus, GPT-4o, DeepSeek-V3 |
+| **general** | 通用管理、摘要、整理 | Claude Sonnet, GPT-4o-mini |
+| **coder** | 寫程式、回測 | Claude Sonnet, Codex, DeepSeek-Coder |
+| **creative** | 文案、創意發想 | Claude Sonnet, GPT-4o |
+| **research** | 資料蒐集、整理 | Claude Haiku, GPT-4o-mini |
+
+---
+
+### 3.1 管理團隊
+
+#### CEO/COO
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `ceo_coo` |
+| **模型等級** | general |
+| **狀態** | 常駐 |
+| **Mission** | 接收董事長指令，拆解任務，用 `sessions_spawn` 分派給 sub-agent，追蹤進度，收斂結果 |
+| **Scope** | 派工（spawn）、溝通（send）、讀取所有 agent 產出、發起 Discord 討論、組裝決策包 |
+| **Forbidden** | 不直接寫文案 / 程式 / 部署 / 做研究 |
+| **輸出** | Task_Spec.json, Final_Decision_Packet.json |
+| **OpenClaw 工具** | `sessions_spawn`, `sessions_send`, `cron`, `memory_search`, Discord 工具 |
+| **Escalation** | 高風險 → Discord @你 |
+
+#### 秘書
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `secretary` |
+| **模型等級** | general |
+| **狀態** | 常駐 |
+| **Mission** | 記錄摘要、維護 MEMORY.md、產出 State Diff、維護 Todo |
+| **Scope** | 讀寫所有 agent 的 memory（via QMD extraCollections）、產出摘要 |
+| **Forbidden** | 不做策略決策、不分派任務 |
+| **輸出** | Meeting_Summary.json, State_Diff.json, Todo_List.json |
+| **OpenClaw 工具** | `memory_search`, `memory_write`, Discord 工具 |
+| **Escalation** | 記憶衝突 → 上報 CEO |
+
+#### 審查員
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `reviewer` |
+| **模型等級** | reasoning-heavy |
+| **狀態** | warm（事件觸發） |
+| **Mission** | 審查產出品質，判定 pass / revise / block |
+| **Scope** | 唯讀所有 agent 輸出、提出修改建議、風險攔截 |
+| **Forbidden** | 不重寫內容、不拍板決策 |
+| **輸出** | Review_Report.json |
+| **OpenClaw 工具** | `memory_search`, `sessions_send`（回覆審查結果給 CEO） |
+| **Escalation** | block → CEO → 可能 Discord @你 |
+
+---
+
+### 3.2 量化研究團隊
+
+#### 財經情報研究員
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `finance_researcher` |
+| **模型等級** | research |
+| **Mission** | 蒐集財經、總經、盤前盤後資訊 |
+| **Forbidden** | 不下交易結論 |
+| **輸出** | Finance_Research_Brief.json |
+| **OpenClaw 工具** | web_search, browser, memory_write |
+
+#### 市場結構研究員
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `market_structure_researcher` |
+| **模型等級** | reasoning-heavy |
+| **Mission** | 解析流動性、MSS、OB、FVG、POI |
+| **Forbidden** | 不下最終交易結論 |
+| **輸出** | Market_Structure_Report.json |
+| **OpenClaw 工具** | 行情資料 MCP, memory_search |
+
+#### 多方研究員
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `bullish_researcher` |
+| **模型等級** | reasoning-heavy |
+| **Mission** | 整理支持做多的論點 |
+| **Forbidden** | 不直接拍板、不做空方論述 |
+| **輸出** | Bullish_Research_Report.json |
+| **OpenClaw 工具** | memory_search（讀取研究報告） |
+
+#### 空方研究員
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `bearish_researcher` |
+| **模型等級** | reasoning-heavy |
+| **Mission** | 整理反對交易的論點 |
+| **Forbidden** | 不直接拍板、不做多方論述 |
+| **輸出** | Bearish_Research_Report.json |
+| **OpenClaw 工具** | memory_search（讀取研究報告） |
+
+#### 量化策略研究員（含風控）
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `quant_strategist` |
+| **模型等級** | reasoning-heavy |
+| **Mission** | 收斂多空觀點成策略規則 + 風控框架 + bias check |
+| **Forbidden** | 不寫正式程式碼 |
+| **輸出** | Quant_Strategy_Spec.json |
+| **OpenClaw 工具** | memory_search, sessions_send（向多方/空方追問） |
+
+#### 回測工程師
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `quant_engineer` |
+| **模型等級** | coder |
+| **Mission** | 將策略規則轉成 Pine Script / Python 回測 |
+| **Forbidden** | 不自行更改策略方向 |
+| **輸出** | Backtest_Delivery.json |
+| **OpenClaw 工具** | exec, code_execution, file_ops, memory_write |
+
+#### 資料分析員
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `data_analyst` |
+| **模型等級** | reasoning-heavy / general |
+| **Mission** | 分析回測結果，計算 KPI，提供洞察 |
+| **Forbidden** | 不自行定策略方向 |
+| **輸出** | Data_Analysis_Report.json |
+| **OpenClaw 工具** | code_execution, memory_search, memory_write |
+
+---
+
+### 3.3 行銷策略團隊
+
+#### 市場研究員
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `market_researcher` |
+| **模型等級** | research |
+| **Mission** | 蒐集競品、消費者痛點、平台趨勢並分析 |
+| **輸出** | Market_Research_Brief.json, Market_Analysis_Report.json |
+| **OpenClaw 工具** | web_search, browser, memory_write |
+
+#### 策略總監
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `strategy_director` |
+| **模型等級** | reasoning-heavy |
+| **Mission** | 定義 USP、品牌敘事、campaign、漏斗策略 |
+| **Forbidden** | 不直接寫最終文案 |
+| **輸出** | Brand_Strategy_Plan.json, Growth_Strategy_Plan.json |
+| **OpenClaw 工具** | memory_search |
+
+#### 投放成效分析師
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `ads_analyst` |
+| **模型等級** | general |
+| **Mission** | 分析 CTR / CVR / CPL / ROAS，提出優化建議 |
+| **輸出** | Ads_Performance_Report.json |
+| **OpenClaw 工具** | 廣告平台 MCP, memory_write |
+
+---
+
+### 3.4 內容創意團隊
+
+#### 文案撰寫員
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `copywriter` |
+| **模型等級** | creative |
+| **Mission** | 廣告文案 + 影片腳本 |
+| **輸出** | Copywriting_Pack.json, Video_Script_Pack.json |
+| **OpenClaw 工具** | memory_search（品牌語氣庫） |
+
+#### 創意總監
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `creative_director` |
+| **模型等級** | creative |
+| **Mission** | 平面素材 brief + 影片分鏡 brief |
+| **輸出** | Static_Creative_Brief.json, Storyboard_Brief.json |
+| **OpenClaw 工具** | memory_search（品牌規範）, image tools（如有） |
+
+---
+
+### 3.5 工程團隊（依需求啟用）
+
+#### 前端工程師 / 後端工程師
+
+| 項目 | 內容 |
+|---|---|
+| **Agent ID** | `frontend_engineer` / `backend_engineer` |
+| **模型等級** | coder |
+| **Mission** | 前端開發 / API + DB 開發 |
+| **OpenClaw 工具** | exec, file_ops, code_execution, browser |
+
+---
+
+### 3.6 SOUL.md 共用結尾
+
+每個 agent 的 `SOUL.md` 結尾附加：
+
+```text
+## 行為規範
+
+- 只在你的職權範圍內行動
+- 缺少必要資訊時，回傳 missing_fields 清單
+- 遇到衝突、不確定、高風險時，上報而非猜測
+- 輸出必須遵循指定的 JSON schema
+- 不在 JSON 之外添加額外說明
+- 在 Discord 討論時，保持你的角色立場發言
+```