From da6efce98d509db68d0e780054e8578681014880 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 10 Apr 2026 15:42:26 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=A7=BB=E9=99=A4=20OpenClaw=20?= =?UTF-8?q?=E6=96=87=E6=AA=94=EF=BC=8C=E9=87=8D=E5=BB=BA=E7=82=BA=20Paperc?= =?UTF-8?q?lip=20=E6=AD=A3=E5=BC=8F=E6=96=B9=E6=A1=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 刪除所有 OpenClaw 時期的 spec/、guides/、migration 文檔 - 新增 company.md：公司定義、16 個 agent、4 個 team、skills、package 結構 - 新增 pipelines.md：量化 pipeline 流程、排程定義、審批機制、GPT+Claude 雙模型分級 - 新增 schemas.md：所有 agent 輸出的 JSON schema 定義 - 更新 INDEX.md：乾淨的文件索引與進度追蹤 Co-Authored-By: Claude Opus 4.6 --- docs/INDEX.md | 45 +-- docs/agent_roster.md | 144 ------- docs/company.md | 486 +++++++++++++++++++++++ docs/guides/guide_openclaw_config.md | 187 --------- docs/guides/guide_sessions_tools.md | 153 ------- docs/guides/guide_tools_skills.md | 256 ------------ docs/guides/guide_workspace_files.md | 157 -------- docs/migration_to_paperclip.md | 250 ------------ docs/pipelines.md | 190 +++++++++ docs/schemas.md | 254 ++++++++++++ docs/spec/spec_collaboration_protocol.md | 402 ------------------- docs/spec/spec_org_and_roles.md | 317 --------------- docs/spec/spec_rollout_and_risks.md | 142 ------- docs/spec/spec_scheduling_memory.md | 138 ------- docs/spec/spec_system_overview.md | 95 ----- 15 files changed, 938 insertions(+), 2278 deletions(-) delete mode 100644 docs/agent_roster.md create mode 100644 docs/company.md delete mode 100644 docs/guides/guide_openclaw_config.md delete mode 100644 docs/guides/guide_sessions_tools.md delete mode 100644 docs/guides/guide_tools_skills.md delete mode 100644 docs/guides/guide_workspace_files.md delete mode 100644 docs/migration_to_paperclip.md create mode 100644 docs/pipelines.md create mode 100644 docs/schemas.md delete mode 100644 docs/spec/spec_collaboration_protocol.md delete mode 100644 docs/spec/spec_org_and_roles.md delete mode 100644 docs/spec/spec_rollout_and_risks.md delete mode 100644 docs/spec/spec_scheduling_memory.md delete mode 100644 docs/spec/spec_system_overview.md diff --git a/docs/INDEX.md b/docs/INDEX.md index b93dac5..66ae18f 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -4,51 +4,22 @@ --- -## 遷移規劃 - | 文件 | 內容 | |---|---| -| [migration_to_paperclip.md](migration_to_paperclip.md) | **OpenClaw → Paperclip 遷移規劃**：概念對照、目標結構、Agent 定義、排程轉換、待確認事項 | - ---- - -## spec/ — 系統規格（OpenClaw 時期，遷移參考用） - -| 文件 | 內容 | -|---|---| -| [spec_system_overview.md](spec/spec_system_overview.md) | 系統目標、設計原則、整體架構 | -| [spec_org_and_roles.md](spec/spec_org_and_roles.md) | 組織架構、Agent 清單（15~17 agents）、各角色定義 | -| [spec_collaboration_protocol.md](spec/spec_collaboration_protocol.md) | 協作協定：Message Envelope、Pipeline 架構、輸出 Schema、Review Gate、HITL | -| [spec_scheduling_memory.md](spec/spec_scheduling_memory.md) | 排程觸發、記憶架構、Discord Server 結構 | -| [spec_rollout_and_risks.md](spec/spec_rollout_and_risks.md) | 上線計畫、風險限制、成本控制 | - ---- - -## guides/ — 實作指南（OpenClaw 時期，遷移參考用） - -| 文件 | 內容 | -|---|---| -| [guide_openclaw_config.md](guides/guide_openclaw_config.md) | openclaw.json 結構、Discord 接入、Gateway 管理 | -| [guide_workspace_files.md](guides/guide_workspace_files.md) | 8 個 Workspace 設定檔用途 | -| [guide_sessions_tools.md](guides/guide_sessions_tools.md) | sessions_spawn / sessions_send 行為與規則 | -| [guide_tools_skills.md](guides/guide_tools_skills.md) | MCP Tools & Skills 配置 | - ---- - -## 花名冊 - -| 文件 | 內容 | -|---|---| -| [agent_roster.md](agent_roster.md) | 全體 Agent 花名冊：職稱、代號、模型、狀態、輸出格式、工具配置 | +| [company.md](company.md) | 公司定義、組織架構、團隊與 Agent 完整規格 | +| [pipelines.md](pipelines.md) | Pipeline 流程、排程定義、審批機制 | +| [schemas.md](schemas.md) | 各 Agent 輸出的 JSON Schema 定義 | --- ## 進度追蹤 -| Phase | 說明 | 狀態 | +| 階段 | 說明 | 狀態 | |---|---|---| -| 遷移至 Paperclip | 建立 company package、匯入 agent 定義 | 規劃中 | -| 管理團隊上線 | 執行長 + 秘書 + 審查員 | 待開始 | +| Paperclip onboard | 初始化 Paperclip 環境 | 待執行 | +| 建立 Company Package | 建立目錄結構、寫入所有定義 | 待開始 | +| 匯入 Paperclip | `paperclipai company import` | 待開始 | +| 管理團隊上線 | CEO + 秘書 + 審查員 | 待開始 | | 量化團隊上線 | 7 agents | 待開始 | | 行銷團隊上線 | 3 agents | 待開始 | | 內容團隊上線 | 2 agents | 待開始 | diff --git a/docs/agent_roster.md b/docs/agent_roster.md deleted file mode 100644 index 7390990..0000000 --- a/docs/agent_roster.md +++ /dev/null @@ -1,144 +0,0 @@ -# KingClawArmy Agent 花名冊 - -> 更新日期：2026-04-10 - ---- - -## 管理團隊（Phase 1） - -| 職稱 | Emoji | Agent ID | 模型 | 狀態 | 輸出格式 | MCP Tools | Skills | -|---|---|---|---|---|---|---|---| -| 執行長 | 🎯 | `ceo_coo` | gpt-5.4 | 常駐 | `Task_Spec.json`, `Final_Decision_Packet.json` | — | — | -| 秘書 | 📋 | `secretary` | gpt-5.4-mini | 常駐 | `Meeting_Summary.json`, `State_Diff.json`, `Todo_List.json` | — | GOG（選配） | -| 審查員 | 🔍 | `reviewer` | gpt-5.4 | Warm | `Review_Report.json` | — | — | - -## 量化研究團隊（Phase 2） - -| 職稱 | Emoji | Agent ID | 模型 | 狀態 | 輸出格式 | MCP Tools | Skills | -|---|---|---|---|---|---|---|---| -| 財經情報研究員 | 💹 | `finance_researcher` | gpt-5.4-mini | 喚醒 | `Finance_Research_Brief.json` | Tavily, Firecrawl, Financial Datasets | Deep Research | -| 市場結構研究員 | 📈 | `market_structure_researcher` | gpt-5.4-mini | 喚醒 | `Market_Structure_Report.json` | TradingView, Alpha Vantage | Deep Research | -| 多方研究員 | 🚀 | `bullish_researcher` | gpt-5.4-mini | 喚醒 | `Bullish_Brief.json` | — | — | -| 空方研究員 | 🛡️ | `bearish_researcher` | gpt-5.4-mini | 喚醒 | `Bearish_Brief.json` | — | — | -| 量化策略師 | 🧭 | `quant_strategist` | gpt-5.4 | 喚醒 | `Strategy_Thesis.json` | — | — | -| 回測工程師 | ⚙️ | `quant_engineer` | gpt-5.4 | 喚醒 | `Backtest_Report.json` | E2B / FinClaw | Code Reviewer | -| 資料分析師 | 🧪 | `data_analyst` | gpt-5.4-mini | 喚醒 | `Data_Analysis_Report.json` | E2B, Plotly | Deep Research | - -## 行銷策略團隊（Phase 3 — 預規劃） - -| 職稱 | Emoji | Agent ID | 模型 | 狀態 | 輸出格式 | MCP Tools | Skills | -|---|---|---|---|---|---|---|---| -| 市場研究員 | 🔎 | `market_researcher` | gpt-5.4-mini | 喚醒 | `Market_Research_Brief.json` | Tavily, Exa, Firecrawl | Deep Research | -| 策略總監 | 🎯 | `strategy_director` | gpt-5.4 | 喚醒 | `Brand_Strategy_Plan.json` | — | — | -| 投放分析師 | 📊 | `ads_analyst` | gpt-5.4-mini | 喚醒 | `Ads_Performance_Report.json` | 廣告平台 API, Plotly | — | - -## 內容創意團隊（Phase 4 — 預規劃） - -| 職稱 | Emoji | Agent ID | 模型 | 狀態 | 輸出格式 | MCP Tools | Skills | -|---|---|---|---|---|---|---|---| -| 文案撰寫員 | ✏️ | `copywriter` | gpt-5.4 | 喚醒 | `Copywriting_Pack.json` | — | SEO Blog Writer | -| 創意總監 | 🎨 | `creative_director` | gpt-5.4 | 喚醒 | `Creative_Brief.json` | DALL-E / Flux, Firecrawl | — | - -## 閒聊 - -| 職稱 | Emoji | Agent ID | 模型 | 頻道 | -|---|---|---|---|---| -| 小安 | 🌿 | `main` | gpt-5.4-mini | #閒聊 | - ---- - -## 內建工具分配 - -每個 agent 除了外部 MCP/Skills 外，還有 OpenClaw 內建工具： - -| Agent | 內建工具 | -|---|---| -| 🎯 CEO | `sessions_spawn`, `sessions_send`, `cron`, `memory_search`, Discord 工具 | -| 📋 秘書 | `memory_search`, `memory_write`, Discord 工具 | -| 🔍 審查員 | `memory_search` | -| 💹 情報員 | `memory_write`, `memory_search` | -| 📈 市場結構 | `memory_search` | -| 🚀 多方 | `memory_search` | -| 🛡️ 空方 | `memory_search` | -| 🧭 策略師 | `memory_search`, `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` | -| ⚙️ 回測 | `exec`, `code_execution`, `file_ops`, `memory_write` | -| 🧪 資料分析 | `code_execution`, `memory_search`, `memory_write` | - -> **注意：** 策略師的 session 工具需要 `maxSpawnDepth ≥ 2` 才會生效（他是 depth-1 編排者）。 - ---- - -## Pipeline 流程 - -``` -董事長 → 🎯執行長 spawn → 🧭策略師（pipeline owner, depth 1） - │ - sessions_spawn ┌─┴──────────┐ - ↓ ↓ - 💹情報員 （等待） - (depth 2) - ↓ announce - 📈市場結構 - (depth 2) - ↓ announce - sessions_spawn ┌─┴─┐ - ↓ ↓ - 🚀 🛡️ ← 並行 - 多方 空方 - (depth 2, depth 2) - ↓ ↓ - announce - ↓ - 🧭策略師收斂 - Strategy_Thesis.json - ↓ - sessions_spawn → 🔍審查員 (depth 2) - ↕ revise → 重新 spawn 被退回角色（最多 3 輪） - pass ↓ - sessions_spawn → 🧪資料分析 (depth 2) - ↓ announce - 🧭策略師 announce 給 🎯執行長 - ↓ - 🎯執行長 → Discord #審批 @董事長 - -例外：block → 策略師 escalate 執行長 → 執行長發 #異常 -例外：revise > 3 輪 → 策略師 escalate 執行長 → 執行長發 #審批 @董事長 -例外：每日情報 → 執行長 spawn 情報員 → 情報員 announce → 執行長發 #每日情報 -例外：每日摘要 → 秘書自己發 #每日摘要 / #決策紀錄 -``` - ---- - -## 通訊方式 - -| 方式 | 用途 | 誰能用 | 限制 | -|---|---|---|---| -| `sessions_spawn` | 非阻塞派工 | CEO（depth 0）、策略師（depth 1, 需 maxSpawnDepth ≥ 2） | 最多 5 並行 | -| `sessions_send` | 同步即時對話 | **僅 depth-0 agent**（CEO、秘書） | Sender 阻塞等回覆 | -| `announce` | 子 agent 回傳結果 | 所有被 spawn 的 agent | 單向往上 | -| `message` 工具 | 發到 Discord 頻道 | 通過審查的內容 | — | - ---- - -## Discord 頻道 - -| 頻道 | 誰發 | 內容 | -|---|---|---| -| #執行長 | 🎯 執行長 | 回覆董事長、進度回報 | -| #審批 | 🎯 執行長 | HITL 審批請求 | -| #異常 | 🎯 執行長 | block、錯誤、異常 | -| #每日情報 | 🎯 執行長（轉發） | 情報員的每日情報摘要 | -| #研究討論 | 🎯 執行長（轉發） | 研究過程摘要（pass 後） | -| #策略結果 | 🎯 執行長（轉發） | 最終策略定稿（pass 後） | -| #每日摘要 | 📋 秘書 | 每日工作摘要 | -| #決策紀錄 | 📋 秘書 | 重大決策存檔 | -| #閒聊 | 🌿 小安 | 閒聊放鬆 | - ---- - -## 模型分級 - -| 等級 | 模型 | 適用角色 | -|---|---|---| -| reasoning-heavy | gpt-5.4 | 執行長、審查員、量化策略師、回測工程師 | -| general / research | gpt-5.4-mini | 秘書、財經情報、市場結構、多空研究、資料分析、小安 | diff --git a/docs/company.md b/docs/company.md new file mode 100644 index 0000000..a1d8069 --- /dev/null +++ b/docs/company.md @@ -0,0 +1,486 @@ +# KingClawArmy - 公司定義 + +> 平台：Paperclip（agentcompanies/v1） +> 日期：2026-04-10 + +--- + +## 1. 公司概要 + +**KingClawArmy** 是一個 AI Agent 團隊，負責： + +1. **量化研究**：情報蒐集 → 市場結構分析 → 多空辯論 → 策略形成 → 回測 → 分析 +2. **行銷策略**：市場研究 → 品牌/成長策略 → 投放分析 +3. **內容創作**：策略 → 文案撰寫 → 視覺方向 + +### COMPANY.md Frontmatter + +```yaml +name: KingClawArmy +description: AI Agent 量化研究、行銷策略與內容創作團隊 +slug: kingclawarmy +schema: agentcompanies/v1 +version: 1.0.0 +authors: + - name: Chris +goals: + - 量化研究自動化：從情報蒐集到策略回測的完整 pipeline + - 行銷策略系統化：市場研究、品牌策略、投放追蹤 + - 內容創作流程化：文案與創意 brief 產出 +``` + +--- + +## 2. 組織架構 + +``` +董事長（Chris，人類） +│ +├── 管理團隊 +│ ├── CEO（coordinator） +│ ├── 秘書 +│ └── 審查員 +│ +├── 量化研究團隊 +│ ├── 量化策略師（team lead） +│ ├── 財經情報研究員 +│ ├── 市場結構研究員 +│ ├── 多方研究員 +│ ├── 空方研究員 +│ ├── 回測工程師 +│ └── 資料分析師 +│ +├── 行銷策略團隊 +│ ├── 策略總監（team lead） +│ ├── 市場研究員 +│ └── 投放分析師 +│ +├── 內容創意團隊 +│ ├── 創意總監（team lead） +│ └── 文案撰寫員 +│ +└── 小安（閒聊） +``` + +**總計：16 agents** + +--- + +## 3. Team 定義 + +### management + +```yaml +# teams/management/TEAM.md +name: 管理團隊 +description: 任務調度、記錄摘要、品質審查 +slug: management +schema: agentcompanies/v1 +manager: ../agents/ceo/AGENTS.md +``` + +成員：secretary, reviewer + +### quant-research + +```yaml +# teams/quant-research/TEAM.md +name: 量化研究團隊 +description: 量化研究 pipeline：情報 → 結構 → 多空 → 策略 → 回測 → 分析 +slug: quant-research +schema: agentcompanies/v1 +manager: ../agents/quant-strategist/AGENTS.md +``` + +成員：finance-researcher, market-structure-researcher, bullish-researcher, bearish-researcher, quant-engineer, data-analyst + +### marketing + +```yaml +# teams/marketing/TEAM.md +name: 行銷策略團隊 +description: 市場研究、品牌策略、投放成效追蹤 +slug: marketing +schema: agentcompanies/v1 +manager: ../agents/strategy-director/AGENTS.md +``` + +成員：market-researcher, ads-analyst + +### content + +```yaml +# teams/content/TEAM.md +name: 內容創意團隊 +description: 文案撰寫與創意方向 +slug: content +schema: agentcompanies/v1 +manager: ../agents/creative-director/AGENTS.md +``` + +成員：copywriter + +--- + +## 4. Agent 定義 + +### 4.1 管理團隊 + +#### ceo + +```yaml +name: 執行長 +title: CEO/COO +reportsTo: null +skills: [] +role: manager +``` + +- **Mission**：接收董事長指令，拆解任務，分派給 sub-agent，追蹤進度，收斂結果 +- **Scope**：派工、溝通、讀取所有 agent 產出、發起審批流程、組裝決策包 +- **Forbidden**：不直接寫文案 / 程式 / 部署 / 做研究 +- **輸出**：`Task_Spec.json`, `Final_Decision_Packet.json` +- **Model Tier**：reasoning-heavy + +#### secretary + +```yaml +name: 秘書 +title: Secretary +reportsTo: ceo +skills: [] +role: general +``` + +- **Mission**：記錄摘要、維護記憶、產出 State Diff、維護 Todo +- **Scope**：讀寫所有 agent 的記憶、產出摘要 +- **Forbidden**：不做策略決策、不分派任務 +- **輸出**：`Meeting_Summary.json`, `State_Diff.json`, `Todo_List.json` +- **Model Tier**：general + +#### reviewer + +```yaml +name: 審查員 +title: Reviewer +reportsTo: ceo +skills: [] +role: general +``` + +- **Mission**：審查產出品質，判定 pass / revise / block +- **Scope**：唯讀所有 agent 輸出、提出修改建議、風險攔截 +- **Forbidden**：不重寫內容、不拍板決策 +- **輸出**：`Review_Report.json` +- **Model Tier**：reasoning-heavy + +--- + +### 4.2 量化研究團隊 + +#### quant-strategist + +```yaml +name: 量化策略師 +title: Quant Strategist +reportsTo: ceo +skills: [] +role: manager +``` + +- **Mission**：收斂多空觀點成策略規則 + 風控框架 + bias check，主導量化 pipeline +- **Scope**：收斂研究結果、spawn 研究員、管理研究品質 +- **Forbidden**：不寫正式程式碼、不做資料蒐集 +- **輸出**：`Strategy_Thesis.json` +- **Model Tier**：reasoning-heavy + +#### finance-researcher + +```yaml +name: 財經情報研究員 +title: Finance Intelligence Researcher +reportsTo: quant-strategist +skills: [deep-research] +role: general +``` + +- **Mission**：蒐集財經、總經、盤前盤後資訊 +- **Forbidden**：不下交易結論 +- **輸出**：`Finance_Research_Brief.json` +- **Model Tier**：research + +#### market-structure-researcher + +```yaml +name: 市場結構研究員 +title: Market Structure Researcher +reportsTo: quant-strategist +skills: [deep-research] +role: general +``` + +- **Mission**：解析流動性、MSS、OB、FVG、POI +- **Forbidden**：不下最終交易結論 +- **輸出**：`Market_Structure_Report.json` +- **Model Tier**：reasoning-heavy + +#### bullish-researcher + +```yaml +name: 多方研究員 +title: Bullish Researcher +reportsTo: quant-strategist +skills: [] +role: general +``` + +- **Mission**：整理支持做多的論點 +- **Forbidden**：不直接拍板、不做空方論述 +- **輸出**：`Bullish_Brief.json` +- **Model Tier**：reasoning-heavy + +#### bearish-researcher + +```yaml +name: 空方研究員 +title: Bearish Researcher +reportsTo: quant-strategist +skills: [] +role: general +``` + +- **Mission**：整理反對交易的論點 +- **Forbidden**：不直接拍板、不做多方論述 +- **輸出**：`Bearish_Brief.json` +- **Model Tier**：reasoning-heavy + +#### quant-engineer + +```yaml +name: 回測工程師 +title: Quant Engineer +reportsTo: quant-strategist +skills: [code-reviewer] +role: engineer +``` + +- **Mission**：將策略規則轉成 Pine Script / Python 回測 +- **Forbidden**：不自行更改策略方向 +- **輸出**：`Backtest_Report.json` +- **Model Tier**：coder + +#### data-analyst + +```yaml +name: 資料分析師 +title: Data Analyst +reportsTo: quant-strategist +skills: [deep-research] +role: general +``` + +- **Mission**：分析回測結果，計算 KPI，提供洞察 +- **Forbidden**：不自行定策略方向 +- **輸出**：`Data_Analysis_Report.json` +- **Model Tier**：general + +--- + +### 4.3 行銷策略團隊 + +#### strategy-director + +```yaml +name: 策略總監 +title: Strategy Director +reportsTo: ceo +skills: [] +role: manager +``` + +- **Mission**：定義 USP、品牌敘事、campaign、漏斗策略 +- **Forbidden**：不直接寫最終文案 +- **輸出**：`Brand_Strategy_Plan.json`, `Growth_Strategy_Plan.json` +- **Model Tier**：reasoning-heavy + +#### market-researcher + +```yaml +name: 市場研究員 +title: Market Researcher +reportsTo: strategy-director +skills: [deep-research] +role: general +``` + +- **Mission**：蒐集競品、消費者痛點、平台趨勢並分析 +- **輸出**：`Market_Research_Brief.json`, `Market_Analysis_Report.json` +- **Model Tier**：research + +#### ads-analyst + +```yaml +name: 投放分析師 +title: Ads Performance Analyst +reportsTo: strategy-director +skills: [] +role: general +``` + +- **Mission**：分析 CTR / CVR / CPL / ROAS，提出優化建議 +- **輸出**：`Ads_Performance_Report.json` +- **Model Tier**：general + +--- + +### 4.4 內容創意團隊 + +#### creative-director + +```yaml +name: 創意總監 +title: Creative Director +reportsTo: ceo +skills: [] +role: manager +``` + +- **Mission**：平面素材 brief + 影片分鏡 brief +- **輸出**：`Creative_Brief.json`, `Storyboard_Brief.json` +- **Model Tier**：creative + +#### copywriter + +```yaml +name: 文案撰寫員 +title: Copywriter +reportsTo: creative-director +skills: [seo-blog-writer] +role: general +``` + +- **Mission**：廣告文案 + 影片腳本 +- **輸出**：`Copywriting_Pack.json`, `Video_Script_Pack.json` +- **Model Tier**：creative + +--- + +### 4.5 閒聊 + +#### xiao-an + +```yaml +name: 小安 +title: null +reportsTo: ceo +skills: [] +role: general +``` + +- **Mission**：閒聊放鬆 +- **Model Tier**：general + +--- + +## 5. Skills 定義 + +### deep-research + +```yaml +# skills/deep-research/SKILL.md +name: Deep Research +description: 深度網路搜尋與資料整理，支援多來源交叉驗證 +allowed-tools: [web_search, browser] +``` + +使用者：finance-researcher, market-structure-researcher, data-analyst, market-researcher + +### code-reviewer + +```yaml +# skills/code-reviewer/SKILL.md +name: Code Reviewer +description: 程式碼品質審查、回測腳本驗證 +allowed-tools: [code_execution, file_ops] +``` + +使用者：quant-engineer + +### seo-blog-writer + +```yaml +# skills/seo-blog-writer/SKILL.md +name: SEO Blog Writer +description: SEO 優化的部落格文章撰寫 +allowed-tools: [] +``` + +使用者：copywriter + +--- + +## 6. Package 目錄結構 + +``` +kingclawarmy/ +├── COMPANY.md +├── .paperclip.yaml +├── agents/ +│ ├── ceo/AGENTS.md +│ ├── secretary/AGENTS.md +│ ├── reviewer/AGENTS.md +│ ├── quant-strategist/AGENTS.md +│ ├── finance-researcher/AGENTS.md +│ ├── market-structure-researcher/AGENTS.md +│ ├── bullish-researcher/AGENTS.md +│ ├── bearish-researcher/AGENTS.md +│ ├── quant-engineer/AGENTS.md +│ ├── data-analyst/AGENTS.md +│ ├── strategy-director/AGENTS.md +│ ├── market-researcher/AGENTS.md +│ ├── ads-analyst/AGENTS.md +│ ├── creative-director/AGENTS.md +│ ├── copywriter/AGENTS.md +│ └── xiao-an/AGENTS.md +├── teams/ +│ ├── management/TEAM.md +│ ├── quant-research/TEAM.md +│ ├── marketing/TEAM.md +│ └── content/TEAM.md +├── skills/ +│ ├── deep-research/SKILL.md +│ ├── code-reviewer/SKILL.md +│ └── seo-blog-writer/SKILL.md +└── projects/ + ├── daily-quant-pipeline/PROJECT.md + ├── market-intel/PROJECT.md + └── ads-tracking/PROJECT.md +``` + +--- + +## 7. 共用行為規範 + +所有 agent 的 AGENTS.md 結尾附加： + +``` +## 行為規範 + +- 只在你的職權範圍內行動 +- 缺少必要資訊時，回傳 missing_fields 清單 +- 遇到衝突、不確定、高風險時，上報而非猜測 +- 輸出必須遵循指定的 JSON schema +- 不在 JSON 之外添加額外說明 +``` + +--- + +## 8. 待確認事項 + +| 項目 | 問題 | 影響 | +|---|---|---| +| Discord 整合 | Paperclip adapter 是否支援 Discord？或需要 http/process adapter 串接？ | .paperclip.yaml adapter 設定 | +| Pipeline 表達 | project/task 能否表達 sequential + parallel 依賴？ | 量化 pipeline 設計 | +| 審批機制 | approval request 能否對接 Discord 通知？ | HITL 流程 | +| 模型設定 | adapter 支援哪些 model provider？ | adapter type 選擇 | +| 跨 agent 記憶 | 是否有跨 agent 記憶搜尋功能？ | 秘書和策略師的運作方式 | diff --git a/docs/guides/guide_openclaw_config.md b/docs/guides/guide_openclaw_config.md deleted file mode 100644 index 50340f5..0000000 --- a/docs/guides/guide_openclaw_config.md +++ /dev/null @@ -1,187 +0,0 @@ -# OpenClaw 實際設定指南 - -> 適用版本：OpenClaw v2026.4.x -> 更新日期：2026-04-09 - ---- - -## openclaw.json 結構 - -設定檔位置：`~/.openclaw/openclaw.json` - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.openclaw/workspace", - "model": { "primary": "openai-codex/gpt-5.4-mini" } - }, - "list": [ - { - "id": "main" - }, - { - "id": "ceo_coo", - "name": "ceo_coo", - "workspace": "~/.openclaw/workspaces/ceo_coo", - "agentDir": "~/.openclaw/agents/ceo_coo/agent", - "model": "openai-codex/gpt-5.4" - } - ] - }, - "channels": { - "discord": { - "enabled": true, - "token": "", - "guilds": { - "": { - "channels": { - "": {} - } - } - } - } - }, - "bindings": [ - { - "type": "route", - "agentId": "ceo_coo", - "match": { - "channel": "discord", - "peer": { - "kind": "channel", - "id": "" - } - } - } - ] -} -``` - ---- - -## 新增 Agent - -```bash -openclaw agents add \ - --workspace ~/.openclaw/workspaces/ \ - --model \ - --non-interactive -``` - ---- - -## Discord 設定 - -### 1. 接入 Discord Bot - -```bash -openclaw channels add --channel discord --token -``` - -### 2. Discord Developer Portal 必開設定 - -Bot → Privileged Gateway Intents： -- Message Content Intent ✅ -- Server Members Intent ✅ - -### 3. 設定 Guild 頻道白名單 - -在 `openclaw.json` 的 `channels.discord.guilds` 下新增： - -```json -"guilds": { - "": { - "channels": { - "": {} - } - } -} -``` - -### 4. 設定 Agent 路由 Binding - -```json -"bindings": [ - { - "type": "route", - "agentId": "", - "match": { - "channel": "discord", - "peer": { - "kind": "channel", - "id": "" - } - } - } -] -``` - -### 5. 授權 Discord 用戶 - -Bot 初次收到 DM 時會顯示 pairing code： - -```bash -openclaw pairing approve discord -``` - ---- - -## Gateway 管理 - -Gateway 以 systemd user service 常駐： - -```bash -# 啟動 -systemctl --user start openclaw-gateway.service - -# 重啟 -systemctl --user restart openclaw-gateway.service - -# 狀態 -systemctl --user status openclaw-gateway.service - -# 查 log -journalctl --user -u openclaw-gateway.service -f -``` - -設定異動通常不需重啟（熱重載）。 -以下異動需要重啟：Discord token、Channel 設定、Plugin 設定。 - ---- - -## 常用指令 - -```bash -# 查 agent 清單與路由 -openclaw agents list --json - -# 查 channel 連線狀態 -openclaw channels status --probe - -# 查 binding 清單 -openclaw agents bindings - -# 設定 agent 路由 -openclaw agents bind --agent --bind "discord:" - -# 移除 binding -openclaw agents unbind --agent --all -``` - ---- - -## King Claw 實際設定 - -| 項目 | 值 | -|---|---| -| OpenClaw 版本 | v2026.4.9（npm 安裝）| -| Guild ID | `1486353934594342924` | -| #總機 Channel ID | `1486735695124107304` | -| 執行長 Agent ID | `ceo_coo` | -| 執行長模型 | `openai-codex/gpt-5.4` | -| 預設模型 | `openai-codex/gpt-5.4-mini` | -| Agent 總數 | 10（管理 3 + 量化 7）| -| Gateway | systemd user service, port 18789 | - -完整花名冊見 [agent_roster.md](../agent_roster.md)。 diff --git a/docs/guides/guide_sessions_tools.md b/docs/guides/guide_sessions_tools.md deleted file mode 100644 index d11112f..0000000 --- a/docs/guides/guide_sessions_tools.md +++ /dev/null @@ -1,153 +0,0 @@ -# sessions_spawn / sessions_send 使用指南 - -> 適用版本：OpenClaw v2026.4.x -> 更新日期：2026-04-10 -> 狀態：v4.1 修正版（修正 spawn/send 工具權限行為） - ---- - -## 核心概念 - -### Agent vs Sub-agent Run - -**Agent** = 有自己 workspace、設定檔、記憶的持久實體。在 `openclaw.json` 的 `agents.list` 裡定義。 - -**Sub-agent run** = 當一個 Agent 被 `sessions_spawn` 呼叫時，在隔離 session 裡的那次執行。Session key 格式：`agent::subagent:`。 - -同一個 Agent 可以被 spawn 成 sub-agent run 來執行任務，完成後 announce 結果回 parent。 - ---- - -## sessions_spawn — 非阻塞派工 - -**行為：** 立即返回 `runId` 和 `childSessionKey`，不等待結果。對方 Agent 在獨立 session 執行，完成後 announce 結果。 - -**使用場景：** Pipeline 步驟交接、獨立任務、並行研究。 - -```json -{ - "agentId": "finance_researcher", - "task": "蒐集今日盤前財經資訊，輸出 Finance_Research_Brief.json", - "thread": true, - "runtime": "subagent" -} -``` - -**關鍵參數：** - -| 參數 | 說明 | -|---|---| -| `agentId` | 目標 Agent ID | -| `task` | 給對方的任務提示 | -| `runtime` | `subagent`（預設）或 `acp` | -| `thread: true` | 綁定到 Discord 執行緒 | -| `sandbox: "require"` | 強制沙箱隔離 | -| `model` | 覆蓋模型設定 | - ---- - -## sessions_send — 同步對話（阻塞） - -**行為：** 向另一個 session 傳訊，sender 等待回覆。支援最多 5 輪來回。 - -**使用場景：** CEO 問秘書即時問題、depth-0 agent 之間的直接對話。 - -```json -{ - "sessionKey": "agent:secretary:subagent:xxxx", - "message": "給我今日工作摘要", - "timeoutSeconds": 60 -} -``` - -**操作模式：** - -| 模式 | 設定 | 用途 | -|---|---|---| -| 等待回覆 | `timeoutSeconds > 0` | 需要立即得到回應 | -| 即發即忘 | `timeoutSeconds: 0` | 不需等回覆 | -| 多輪來回 | 自動支援，最多 5 輪 | 審查、追問 | - -對方可回覆 `REPLY_SKIP` 提早結束來回。 - ---- - -## 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 - } - } -} -``` - ---- - -## 使用情境對照 - -| 情境 | 工具 | 原因 | -|---|---|---| -| 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 | diff --git a/docs/guides/guide_tools_skills.md b/docs/guides/guide_tools_skills.md deleted file mode 100644 index 339f601..0000000 --- a/docs/guides/guide_tools_skills.md +++ /dev/null @@ -1,256 +0,0 @@ -# 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 ` | - -**簡單說：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 | diff --git a/docs/guides/guide_workspace_files.md b/docs/guides/guide_workspace_files.md deleted file mode 100644 index 8d408bc..0000000 --- a/docs/guides/guide_workspace_files.md +++ /dev/null @@ -1,157 +0,0 @@ -# OpenClaw Workspace 設定檔指南 - -> 適用版本：OpenClaw v2026.4.x -> 更新日期：2026-04-09 - ---- - -## 總覽 - -每個 Agent 的 workspace 資料夾下有固定的 8 個設定檔，OpenClaw 在 session 啟動時自動讀取並組合成 Agent 的身份、行為規則、記憶與任務排程。 - -``` -~/.openclaw/workspaces// -├── SOUL.md ← 性格與邊界 -├── AGENTS.md ← 操作程序手冊 -├── IDENTITY.md ← 公開元數據 -├── USER.md ← 關於人類用戶 -├── TOOLS.md ← 工具使用指南 -├── HEARTBEAT.md ← 定期任務清單 -├── BOOTSTRAP.md ← 首次啟動引導（用完刪） -├── MEMORY.md ← 長期記憶 -└── memory/ - └── YYYY-MM-DD.md ← 每日工作記錄 -``` - ---- - -## 各檔案詳細說明 - -### SOUL.md — 性格與邊界 - -**誰讀：** Agent 自己，每個 session 開始時注入 -**用途：** 定義 Agent 是誰、核心使命、禁止行為 - -**應放內容：** -- 語氣與個性（簡潔、果斷、有主見） -- 職權範圍與使命 -- 嚴格禁止事項 -- 高風險動作清單 - -**原則：短勝於長，銳利勝於模糊。不放生平故事、不堆安全政策。** - ---- - -### AGENTS.md — 操作程序手冊 - -**誰讀：** Agent 自己，每個 session 開始時讀取 -**用途：** 最重要的大文件，記錄「怎麼做」的程序 - -**應放內容：** -- Session 啟動流程（依序讀哪些檔案） -- 記憶記錄規則 -- 任務執行流程 -- Multi-agent 移交協議（spawn/send 哪個 agent） -- Review Gate 觸發條件 -- HITL 審批節點 -- Discord 發言規範 -- 紅線（絕對不能做的事） - -**這是複雜 Agent 最大的檔案。** - ---- - -### IDENTITY.md — 公開元數據 - -**誰讀：** 系統初始化、`openclaw agents set-identity` 指令 -**用途：** 輕量級的公開身份卡片，**要很短** - -**應放內容：** -- 名字（Name） -- 角色標籤（Creature/Role） -- 語言 -- Emoji（簽名） -- Avatar 路徑（可選） - -**不要放行為邏輯，那屬於 SOUL.md 和 AGENTS.md。** - ---- - -### USER.md — 關於人類用戶 - -**誰讀：** Agent 自己，每個 session 讀取 -**用途：** 靜態的用戶資訊，讓 Agent 有個性化的互動 - -**應放內容：** -- 姓名與稱呼 -- 時區 -- 語言偏好 -- 溝通偏好 -- 決策權限說明 - -**不要放機密資訊。手動更新，不常變動。** - ---- - -### TOOLS.md — 工具使用指南 - -**誰讀：** Agent 自己，參考用 -**用途：** 記錄 Agent 可以使用哪些工具以及如何正確使用 - -**應放內容：** -- 可用工具清單與參數說明 -- 使用場景與注意事項 -- 環境特定設定（SSH hosts、API endpoints 等） - -**不要存放 API Key 或機密，用環境變數。** -**不控制工具可用性，只是使用指南。** - ---- - -### HEARTBEAT.md — 定期任務清單 - -**誰讀：** Agent 自己，收到 heartbeat poll 時讀取 -**用途：** 定義 Agent 需要定期檢查或執行的任務 - -**應放內容：** -- 簡短的檢查清單（要小，避免 token 浪費） -- 定期任務說明 - -**空檔案 = 跳過 heartbeat API call。** - ---- - -### BOOTSTRAP.md — 首次啟動引導 - -**誰讀：** Agent 自己，首次啟動時 -**用途：** 引導 Agent 建立身份，完成後自行刪除 - -**應放內容：** -- 引導 Agent 詢問用戶並填寫 IDENTITY.md、USER.md、SOUL.md -- 完成後刪除自身 - -**用完就刪，不需要永久保留。** - ---- - -### MEMORY.md — 長期記憶 - -**誰讀：** Agent 自己，**只在主 session（直接對話）載入，Discord 等群組場合不載入** -**用途：** 跨 session 的長期記憶，由 Agent 自己維護 - -**應放內容：** -- 重要決策記錄 -- 總司令偏好 -- 長期策略方向 -- 需要跨 session 記住的關鍵事項 - -**每日工作記錄放 `memory/YYYY-MM-DD.md`，MEMORY.md 是精煉過的長期記憶。** - ---- - -## 系統行為注意事項 - -- 缺失檔案：系統注入「缺失檔案」標記後繼續執行 -- 大型檔案截斷：單檔上限約 20,000 字元，總計 150,000 字元 -- `openclaw setup` 可重建預設值，不會覆蓋現有檔案 -- 每日筆記系統：`memory/YYYY-MM-DD.md` 自動讀取今日+昨日 diff --git a/docs/migration_to_paperclip.md b/docs/migration_to_paperclip.md deleted file mode 100644 index 2067215..0000000 --- a/docs/migration_to_paperclip.md +++ /dev/null @@ -1,250 +0,0 @@ -# KingClawArmy - OpenClaw 到 Paperclip 遷移規劃 - -> 日期：2026-04-10 -> 狀態：規劃中（尚未執行） - ---- - -## 1. 為什麼遷移 - -OpenClaw 在架構流程管理上的不足已成為瓶頸。Paperclip 提供： - -- **結構化公司組織**：Company → Team → Agent 層級清晰 -- **標準化資料格式**：Agent Companies Spec（agentcompanies/v1），可攜式 markdown package -- **內建任務管理**：Issues、Projects、Goals 三層架構，支援 atomic checkout -- **排程系統**：Routines + cron，取代手動 cron 設定 -- **匯入匯出**：`paperclipai company import/export`，支援 GitHub URL - ---- - -## 2. 概念對照表 - -| OpenClaw 概念 | Paperclip 對應 | 說明 | -|---|---|---| -| `openclaw.json` agents 陣列 | `COMPANY.md` + `agents/*/AGENTS.md` | Agent 定義從集中式 JSON 變成分散式 markdown | -| `SOUL.md` + `IDENTITY.md` | `AGENTS.md` body | 人格、角色、行為規範合併到 AGENTS.md 內文 | -| `AGENTS.md`（OpenClaw 版） | `AGENTS.md` body | 操作程序、輸出格式定義放在 body | -| Agent 分組（管理/量化/行銷/內容） | `teams/*/TEAM.md` | 正式的 team 結構 | -| Agent 間上下級（CEO → 策略師 → 研究員） | `reportsTo` 欄位 | 形成嚴格的回報樹 | -| `cron add --agent` | `.paperclip.yaml` routines | 帶 timezone 的結構化排程 | -| MCP Tools / Skills | `skills/*/SKILL.md` | 遵循 Agent Skills spec | -| Standing Orders / Lobster DSL | Projects + Tasks | 用 project 定義流程，task 定義步驟 | -| `MEMORY.md` + daily notes | 從頭開始 | 不遷移舊記憶 | -| Discord bindings | `.paperclip.yaml` adapter config | 待確認 Paperclip Discord 整合方式 | -| `HEARTBEAT.md` | routines（recurring tasks） | 轉為排程任務 | -| `USER.md` | 不需要 | Paperclip 有自己的 user context | -| `TOOLS.md` | skills 引用 | 工具指南整合到 skills 或 agent instructions | -| Message Envelope / Intent | Paperclip 內建任務流 | 不需要自訂 envelope，用 issue 流轉 | -| Review Gate | Approval Requests | Paperclip 內建審批機制 | -| HITL Discord @mention | Paperclip approval + 外部通知 | 待確認整合方式 | - ---- - -## 3. 目標 Paperclip Package 結構 - -``` -kingclawarmy/ -├── COMPANY.md -├── .paperclip.yaml -│ -├── agents/ -│ ├── ceo/AGENTS.md -│ ├── secretary/AGENTS.md -│ ├── reviewer/AGENTS.md -│ ├── finance-researcher/AGENTS.md -│ ├── market-structure-researcher/AGENTS.md -│ ├── bullish-researcher/AGENTS.md -│ ├── bearish-researcher/AGENTS.md -│ ├── quant-strategist/AGENTS.md -│ ├── quant-engineer/AGENTS.md -│ ├── data-analyst/AGENTS.md -│ ├── market-researcher/AGENTS.md -│ ├── strategy-director/AGENTS.md -│ ├── ads-analyst/AGENTS.md -│ ├── copywriter/AGENTS.md -│ ├── creative-director/AGENTS.md -│ └── xiao-an/AGENTS.md -│ -├── teams/ -│ ├── management/TEAM.md -│ ├── quant-research/TEAM.md -│ ├── marketing/TEAM.md -│ └── content/TEAM.md -│ -├── projects/ -│ ├── daily-quant-pipeline/PROJECT.md -│ ├── market-intel/PROJECT.md -│ └── ads-tracking/PROJECT.md -│ -├── skills/ -│ ├── deep-research/SKILL.md -│ ├── code-reviewer/SKILL.md -│ └── seo-blog-writer/SKILL.md -│ -└── tasks/ - └── (依 project 建立初始 seed tasks) -``` - ---- - -## 4. Agent 定義對照（16 agents） - -### 4.1 管理團隊 - -| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | -|---|---|---|---|---|---| -| `ceo` | 執行長 | CEO/COO | `null` | reasoning-heavy | — | -| `secretary` | 秘書 | Secretary | `ceo` | general | — | -| `reviewer` | 審查員 | Reviewer | `ceo` | reasoning-heavy | — | - -### 4.2 量化研究團隊 - -| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | -|---|---|---|---|---|---| -| `finance-researcher` | 財經情報研究員 | Finance Intelligence Researcher | `quant-strategist` | research | deep-research | -| `market-structure-researcher` | 市場結構研究員 | Market Structure Researcher | `quant-strategist` | reasoning-heavy | deep-research | -| `bullish-researcher` | 多方研究員 | Bullish Researcher | `quant-strategist` | reasoning-heavy | — | -| `bearish-researcher` | 空方研究員 | Bearish Researcher | `quant-strategist` | reasoning-heavy | — | -| `quant-strategist` | 量化策略師 | Quant Strategist | `ceo` | reasoning-heavy | — | -| `quant-engineer` | 回測工程師 | Quant Engineer | `quant-strategist` | coder | code-reviewer | -| `data-analyst` | 資料分析師 | Data Analyst | `quant-strategist` | general | deep-research | - -### 4.3 行銷策略團隊 - -| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | -|---|---|---|---|---|---| -| `market-researcher` | 市場研究員 | Market Researcher | `strategy-director` | research | deep-research | -| `strategy-director` | 策略總監 | Strategy Director | `ceo` | reasoning-heavy | — | -| `ads-analyst` | 投放分析師 | Ads Performance Analyst | `strategy-director` | general | — | - -### 4.4 內容創意團隊 - -| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | -|---|---|---|---|---|---| -| `copywriter` | 文案撰寫員 | Copywriter | `creative-director` | creative | seo-blog-writer | -| `creative-director` | 創意總監 | Creative Director | `ceo` | creative | — | - -### 4.5 閒聊 - -| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | -|---|---|---|---|---|---| -| `xiao-an` | 小安 | — | `ceo` | general | — | - ---- - -## 5. Team 定義 - -| Team Slug | 名稱 | Manager | 成員 | -|---|---|---|---| -| `management` | 管理團隊 | `ceo` | secretary, reviewer | -| `quant-research` | 量化研究團隊 | `quant-strategist` | finance-researcher, market-structure-researcher, bullish-researcher, bearish-researcher, quant-engineer, data-analyst | -| `marketing` | 行銷策略團隊 | `strategy-director` | market-researcher, ads-analyst | -| `content` | 內容創意團隊 | `creative-director` | copywriter | - ---- - -## 6. 排程（Routines）轉換 - -以下 OpenClaw cron 轉為 `.paperclip.yaml` routines： - -| Routine Slug | 原 OpenClaw cron | Paperclip cron | Agent | 說明 | -|---|---|---|---|---| -| `daily-quant-pipeline` | `30 7 * * 1-5` | `30 7 * * 1-5` | ceo | 盤前啟動量化 pipeline | -| `daily-post-market` | `30 18 * * 1-5` | `30 18 * * 1-5` | ceo | 盤後情報整理 | -| `daily-market-intel` | `0 10 * * *` | `0 10 * * *` | market-researcher | 每日市場情報 | -| `weekly-market-report` | `0 9 * * 1` | `0 9 * * 1` | market-researcher | 每週市場分析 | -| `daily-ads-check` | `30 9 * * *` | `30 9 * * *` | ads-analyst | 每日投放 KPI | -| `daily-data-summary` | `0 20 * * *` | `0 20 * * *` | data-analyst | 每日資料摘要 | -| `weekly-data-report` | `0 10 * * 1` | `0 10 * * 1` | data-analyst | 每週數據報告 | - -時區統一使用 `Asia/Taipei`。 - ---- - -## 7. AGENTS.md 內容結構規劃 - -每個 agent 的 `AGENTS.md` 將包含： - -```markdown ---- -name: 執行長 -title: CEO/COO -reportsTo: null -skills: [] -role: manager ---- - -## Mission - -接收董事長指令，拆解任務，分派給 sub-agent，追蹤進度，收斂結果。 - -## Scope - -- 派工、溝通、讀取所有 agent 產出 -- 發起審批流程 -- 組裝決策包 - -## Forbidden - -- 不直接寫文案 / 程式 / 部署 / 做研究 - -## 輸出格式 - -### Task_Spec.json -（schema 定義） - -### Final_Decision_Packet.json -（schema 定義） - -## 行為規範 - -- 只在職權範圍內行動 -- 缺少必要資訊時，回傳 missing_fields 清單 -- 遇到衝突、不確定、高風險時，上報而非猜測 -- 輸出必須遵循指定的 JSON schema -``` - -來源合併方式： -- `IDENTITY.md` 的 name, emoji, role → frontmatter -- `SOUL.md` 的 personality, mission, forbidden → body -- `AGENTS.md`（OpenClaw 版）的操作程序、輸出格式 → body - ---- - -## 8. 待確認事項 - -| 項目 | 問題 | 影響 | -|---|---|---| -| Discord 整合 | Paperclip 是否支援 Discord adapter？或需要用 http/process adapter 串接？ | 影響 .paperclip.yaml 的 adapter 設定 | -| Pipeline 流程 | Paperclip 的 project/task 能否表達 sequential + parallel 的 pipeline？ | 可能需要用 agent instructions 搭配 task 依賴關係 | -| 審批機制 | Paperclip 的 approval request 能否對接 Discord 通知？ | HITL 流程設計 | -| 模型設定 | Paperclip adapter 支援哪些 model provider？ | 影響 adapter type 選擇 | -| 跨 agent 記憶 | Paperclip 是否有跨 agent 記憶搜尋？ | 影響秘書和策略師的運作方式 | -| 工程團隊 | 是否要在初始 package 中包含？ | 可以先不建，之後 import 追加 | - ---- - -## 9. 執行步驟 - -### Phase A：建立 Package（本次目標） - -1. 完成 Paperclip onboard -2. 用 `company-creator` 或手動建立 company package 目錄 -3. 寫 COMPANY.md + .paperclip.yaml -4. 建立 4 個 team -5. 建立 16 個 agent（先建管理團隊 → 量化 → 行銷 → 內容） -6. 建立 skills -7. 用 `paperclipai company import` 匯入 - -### Phase B：驗證 - -1. 確認組織架構正確（reportsTo 樹） -2. 測試每個 agent 能正常回應 -3. 設定排程 -4. 跑一次量化 pipeline 端對端測試 - -### Phase C：調整 - -1. 根據測試結果調整 agent instructions -2. 補充 project + task seed -3. 視需要新增 skills diff --git a/docs/pipelines.md b/docs/pipelines.md new file mode 100644 index 0000000..c314d82 --- /dev/null +++ b/docs/pipelines.md @@ -0,0 +1,190 @@ +# KingClawArmy - Pipeline 與排程 + +> 平台：Paperclip +> 日期：2026-04-10 + +--- + +## 1. 量化研究 Pipeline + +量化策略師主導整個 pipeline，CEO 只管啟動和例外處理。 + +``` +CEO → 量化策略師（pipeline owner） + │ + ├─ 財經情報研究員 + │ └─ Finance_Research_Brief.json + │ + ├─ 市場結構研究員（等情報完成） + │ └─ Market_Structure_Report.json + │ + ├─ 多方研究員 ──┐ + ├─ 空方研究員 ──┘ 並行 + │ └─ Bullish_Brief.json / Bearish_Brief.json + │ + ├─ 策略師收斂 + │ └─ Strategy_Thesis.json + │ + ├─ 審查員 + │ ├─ pass → 繼續 + │ ├─ revise → 重跑被退回角色（最多 3 輪） + │ └─ block → escalate CEO + │ + ├─ 資料分析師（審查 pass 後） + │ └─ Data_Analysis_Report.json + │ + └─ CEO → 董事長審批 +``` + +### Pipeline 步驟定義 + +| Step | Agent | 依賴 | 輸出 | +|---|---|---|---| +| intel | finance-researcher | — | Finance_Research_Brief.json | +| structure | market-structure-researcher | intel | Market_Structure_Report.json | +| bull | bullish-researcher | structure | Bullish_Brief.json | +| bear | bearish-researcher | structure | Bearish_Brief.json | +| converge | quant-strategist | bull, bear | Strategy_Thesis.json | +| review | reviewer | converge | Review_Report.json | +| analysis | data-analyst | review (pass) | Data_Analysis_Report.json | +| approve | HITL (董事長) | analysis | — | + +### 例外處理 + +| 情況 | 處理方式 | +|---|---| +| revise（審查退回） | 重新指派被退回的 agent，帶上修改意見，最多 3 輪 | +| block（審查否決） | escalate 到 CEO，CEO 通知董事長 | +| revise 超過 3 輪 | escalate 到 CEO，CEO 通知董事長 | +| agent 執行超時 | 重新指派，帶上 timeout 通知 | +| agent 回傳 missing_fields | 重新指派，明確要求補齊 | + +--- + +## 2. 排程（Routines） + +時區統一：`Asia/Taipei` + +### .paperclip.yaml routines 定義 + +```yaml +routines: + daily-quant-pipeline: + triggers: + - kind: schedule + cronExpression: "30 7 * * 1-5" + timezone: Asia/Taipei + enabled: true + # CEO 啟動量化 pipeline + + daily-post-market: + triggers: + - kind: schedule + cronExpression: "30 18 * * 1-5" + timezone: Asia/Taipei + enabled: true + # CEO spawn 財經情報研究員做盤後整理 + + daily-market-intel: + triggers: + - kind: schedule + cronExpression: "0 10 * * *" + timezone: Asia/Taipei + enabled: true + # 市場研究員每日市場情報 + + weekly-market-report: + triggers: + - kind: schedule + cronExpression: "0 9 * * 1" + timezone: Asia/Taipei + enabled: true + # 市場研究員每週市場分析報告 + + daily-ads-check: + triggers: + - kind: schedule + cronExpression: "30 9 * * *" + timezone: Asia/Taipei + enabled: true + # 投放分析師每日 KPI 檢查 + + daily-data-summary: + triggers: + - kind: schedule + cronExpression: "0 20 * * *" + timezone: Asia/Taipei + enabled: true + # 資料分析師每日資料摘要 + + weekly-data-report: + triggers: + - kind: schedule + cronExpression: "0 10 * * 1" + timezone: Asia/Taipei + enabled: true + # 資料分析師每週數據報告 +``` + +### 排程對應 Agent + +| Routine | Agent | 頻率 | 說明 | +|---|---|---|---| +| daily-quant-pipeline | ceo | 週一至五 07:30 | 盤前啟動量化 pipeline | +| daily-post-market | ceo | 週一至五 18:30 | 盤後情報整理 | +| daily-market-intel | market-researcher | 每日 10:00 | 每日市場情報 | +| weekly-market-report | market-researcher | 每週一 09:00 | 每週市場分析 | +| daily-ads-check | ads-analyst | 每日 09:30 | 投放 KPI 檢查 | +| daily-data-summary | data-analyst | 每日 20:00 | 每日資料摘要 | +| weekly-data-report | data-analyst | 每週一 10:00 | 每週數據報告 | + +--- + +## 3. 審批機制（HITL） + +以下動作需要董事長批准： + +| 需要審批的事 | 觸發者 | +|---|---| +| 量化策略正式執行 | CEO | +| 正式部署 | CEO | +| DB schema 變更 | CEO | +| 廣告正式發布 | CEO | +| 對外訊息發送 | CEO | +| 金流操作 | CEO | + +### Review Gate + +| 必審節點 | 觸發方式 | 審查標準 | +|---|---|---| +| 量化策略提交 | 策略師指派審查員 | schema 完整性 + 風控邏輯 | +| 回測結果提交 | 策略師指派審查員 | 績效指標合理性 | +| 工程交付 | CEO 指派審查員 | 程式碼品質 + 測試覆蓋 | +| 文案對外 | CEO 指派審查員 | 品牌一致性 + 法規合規 | + +--- + +## 4. 模型分級 + +搭配 GPT 與 Claude 雙模型，依任務特性分配： + +| 等級 | GPT 模型 | Claude 模型 | 適用 Agent | +|---|---|---|---| +| reasoning-heavy | gpt-5.4 | claude-opus-4-6 | CEO, 審查員, 策略師, 市場結構研究員, 多方/空方研究員, 策略總監 | +| general | gpt-5.4-mini | claude-sonnet-4-6 | 秘書, 投放分析師, 資料分析師, 小安 | +| research | gpt-5.4-mini | claude-haiku-4-5 | 財經情報研究員, 市場研究員 | +| coder | gpt-5.4 | claude-sonnet-4-6 | 回測工程師 | +| creative | gpt-5.4 | claude-sonnet-4-6 | 文案撰寫員, 創意總監 | + +每個 agent 可在 `.paperclip.yaml` 中指定主要使用的模型，視任務需求切換。 + +--- + +## 5. 成本控制 + +| 策略 | 做法 | +|---|---| +| 模型分級 | 日常用 research/general，策略收斂才用 reasoning-heavy | +| 排程頻率合理 | 不需要的 agent 不排太密的 cron | +| review 輪數上限 | revise 最多 3 輪，超過 escalate | +| 記憶壓縮 | 定期壓縮避免 context 膨脹 | diff --git a/docs/schemas.md b/docs/schemas.md new file mode 100644 index 0000000..57be364 --- /dev/null +++ b/docs/schemas.md @@ -0,0 +1,254 @@ +# KingClawArmy - 輸出 Schema 定義 + +> 平台：Paperclip +> 日期：2026-04-10 + +每個 agent 的產出必須遵循定義好的 JSON schema，確保一次交齊，減少追問。 + +--- + +## Finance_Research_Brief.json + +產出者：finance-researcher + +```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 + +產出者：market-structure-researcher + +```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 + +產出者：bullish-researcher + +```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": ["..."] +} +``` + +--- + +## Bearish_Brief.json + +產出者：bearish-researcher + +格式同 Bullish_Brief.json，立場相反。 + +--- + +## Strategy_Thesis.json + +產出者：quant-strategist + +```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 + +產出者：reviewer + +```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": "..." +} +``` + +--- + +## Backtest_Report.json + +產出者：quant-engineer + +```json +{ + "date": "2026-04-10", + "strategy_ref": "Strategy_Thesis.json", + "platform": "pine_script|python", + "results": { + "total_trades": 0, + "win_rate": 0.0, + "profit_factor": 0.0, + "max_drawdown_pct": 0.0, + "sharpe_ratio": 0.0, + "avg_rr": 0.0 + }, + "code_artifact": "...", + "notes": "..." +} +``` + +--- + +## Data_Analysis_Report.json + +產出者：data-analyst + +```json +{ + "date": "2026-04-10", + "analyzed_artifact": "Backtest_Report.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": "..." +} +``` + +--- + +## Task_Spec.json + +產出者：ceo + +```json +{ + "task_id": "...", + "title": "...", + "assignee": "agent-slug", + "priority": "high|medium|low", + "description": "...", + "expected_output": "Schema 名稱", + "deadline": "2026-04-10T18:00:00+08:00" +} +``` + +--- + +## Meeting_Summary.json + +產出者：secretary + +```json +{ + "date": "2026-04-10", + "participants": ["agent-slug", "..."], + "key_decisions": ["..."], + "action_items": [ + { "assignee": "agent-slug", "task": "...", "deadline": "..." } + ], + "notes": "..." +} +``` + +--- + +## Brand_Strategy_Plan.json + +產出者：strategy-director + +```json +{ + "date": "2026-04-10", + "usp": "...", + "brand_narrative": "...", + "target_audience": ["..."], + "campaigns": [ + { "name": "...", "channel": "...", "objective": "...", "kpi": "..." } + ], + "funnel_strategy": "..." +} +``` + +--- + +## Ads_Performance_Report.json + +產出者：ads-analyst + +```json +{ + "date": "2026-04-10", + "platform": "...", + "metrics": { + "ctr": 0.0, + "cvr": 0.0, + "cpl": 0.0, + "roas": 0.0, + "spend": 0.0 + }, + "top_creatives": ["..."], + "recommendations": ["..."] +} +``` diff --git a/docs/spec/spec_collaboration_protocol.md b/docs/spec/spec_collaboration_protocol.md deleted file mode 100644 index d8d3f6f..0000000 --- a/docs/spec/spec_collaboration_protocol.md +++ /dev/null @@ -1,402 +0,0 @@ -# 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 間的溝通統一使用結構化信封，不使用自由文字： - -```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 | diff --git a/docs/spec/spec_org_and_roles.md b/docs/spec/spec_org_and_roles.md deleted file mode 100644 index cf4e3ea..0000000 --- a/docs/spec/spec_org_and_roles.md +++ /dev/null @@ -1,317 +0,0 @@ -# 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": "" } - ], - "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 討論時，保持你的角色立場發言 -``` diff --git a/docs/spec/spec_rollout_and_risks.md b/docs/spec/spec_rollout_and_risks.md deleted file mode 100644 index e18478a..0000000 --- a/docs/spec/spec_rollout_and_risks.md +++ /dev/null @@ -1,142 +0,0 @@ -# KingClawArmy - 第八部分：JSON Schema & 第九部分：上線計畫 & 第十部分：風險與限制 - ---- - -## 第八部分：JSON Schema - -JSON Schema 定義各 agent 產出格式，與系統架構無關（純資料格式）。 -詳細 schema 定義請參考各 agent 的 AGENTS.md 或實際輸出範例。 - ---- - -## 第九部分：上線計畫 - -### 9.1 總覽 - -| Phase | 目標 | 上線角色 | 驗收標準 | 狀態 | -|---|---|---|---|---| -| 0 | 基礎設施 | — | OpenClaw + Discord 可用 | ✅ 完成 | -| 1 | 管理閉環 | 3 agents | CEO 派工→秘書記錄→審查審核 | 🔄 進行中 | -| 2 | 量化閉環 | +7 agents | 情報到回測完整 pipeline | 待開始 | -| 3 | 行銷閉環 | +3 agents | 研究→策略→KPI 追蹤 | 待開始 | -| 4 | 內容閉環 | +2 agents | 文案+創意 brief | 待開始 | -| 5 | 工程（依需求） | +0~2 agents | 前後端任務可執行 | 待開始 | - -### 9.2 Phase 0：基礎設施 ✅ - -| 步驟 | 動作 | 驗收 | 狀態 | -|---|---|---|---| -| 0.1 | 安裝 OpenClaw | `openclaw --version` 正常 | ✅ v2026.4.10 | -| 0.2 | 設定 AI model API | OpenClaw 能回應訊息 | ✅ openai-codex | -| 0.3 | 設定記憶引擎 | `memory_search` 可用 | 待確認 | -| 0.4 | 建立 Discord Server + 頻道 | 頻道結構完成 | ✅ King Claw Server | -| 0.5 | 連接 OpenClaw Discord 整合 | Bot 在 Discord 上線 | ✅ #總機 頻道已連接 | -| 0.6 | 建立 `~/.openclaw/openclaw.json` | config 可載入 | ✅ | - -**實際設定筆記：** -- Discord Bot 需在 Developer Portal 開啟 Message Content Intent、Server Members Intent -- 群組頻道路由須在 `channels.discord.guilds..channels` 設定，binding 用 `peer.kind: channel + peer.id: ` -- Gateway 以 systemd user service 方式常駐執行 - -### 9.3 Phase 1：管理閉環 🔄 - -| 步驟 | 動作 | 驗收 | 狀態 | -|---|---|---|---| -| 1.1 | 建立 CEO agent（workspace 完整設定） | Agent 回應正常 | ✅ `ceo_coo` 已建立 | -| 1.2 | 設定 CEO 的 Discord binding | Discord 訊息能路由到 CEO | ✅ #總機 已路由 | -| 1.3 | 手動在 Discord 下達測試任務 | CEO 能理解並回應 | 🔄 測試中 | -| 1.4 | 建立秘書 agent | 秘書能讀取 CEO 產出 | 待開始 | -| 1.5 | 建立審查員 agent | 審查員能回覆 pass/revise | 待開始 | -| 1.6 | 測試 CEO spawn 秘書 | sessions_spawn 正常 | 待開始 | -| 1.7 | 測試 CEO send 審查員 | sessions_send 來回正常 | 待開始 | -| 1.8 | 測試 HITL：CEO @總司令 在 Discord | 收到通知，回覆後 CEO 繼續 | 待開始 | -| 1.9 | 測試跨 agent 記憶 | 秘書能搜尋 CEO 的記憶 | 待開始 | - -**Phase 1 完成標準：** -- [x] CEO 能接收 Discord 指令 -- [ ] CEO 能 spawn/send 其他 agent -- [ ] 秘書能產出摘要 -- [ ] 審查員能 pass/revise -- [ ] Discord HITL 正常 -- [ ] 跨 agent 記憶搜尋正常 - -### 9.4 Phase 2：量化閉環 - -| 步驟 | 動作 | 驗收 | -|---|---|---| -| 2.1 | 建立財經情報研究員 + cron | 每日自動產出報告 | -| 2.2 | 建立市場結構研究員 | 情報完成後自動觸發 | -| 2.3 | 建立多方 + 空方研究員 | 平行產出報告 | -| 2.4 | 建立量化策略研究員 | 能收斂成策略 | -| 2.5 | 測試 coordinator 討論 | CEO 串行收集多空觀點並交給策略研究員 | -| 2.6 | 建立回測工程師 | 產出回測結果 | -| 2.7 | 建立資料分析員 | 分析回測結果 | -| 2.8 | 完整 pipeline 端對端測試 | 從盤前情報到最終分析一次跑通 | -| 2.9 | 審查員 review pipeline | 通過 gate | -| 2.10 | HITL 測試：董事長批准 | Discord 審批正常 | - -### 9.5 Phase 3-5 - -同 v3 版邏輯，依序加入行銷、內容、工程團隊。每加一個 agent： - -1. 建立 workspace（SOUL.md + AGENTS.md + MEMORY.md） -2. 設定 model + tools -3. 加入 openclaw.json -4. 測試 CEO 能 spawn/send -5. 測試記憶讀寫 -6. 跑一次真實任務驗證 - ---- - -## 第十部分：風險與限制 - -### 10.1 已知限制 - -| 限制 | 影響 | 緩解 | -|---|---|---| -| 無原生群組辯論（#18869） | 3+ agent 無法即時辯論 | coordinator 模式替代 | -| sessions_send 最多 5 輪 | peer-to-peer 對話受限 | 大部分場景 5 輪夠用；超過走 coordinator | -| sub-agent 最多 5 層深、5 個並行 | 不能一次 spawn 太多 | 15 agent 分批 spawn，CEO 做排隊 | -| 無視覺化管理 UI | 看不到 org chart | Discord + CLI 管理 | -| OpenClaw 曾有安全漏洞 | RCE 風險 | 保持更新、啟用認證 | - -### 10.2 成本控制 - -| 策略 | 做法 | -|---|---| -| 模型分級 | 日常用便宜的 research/general，策略收斂才用 reasoning-heavy | -| 限制 send 輪數 | peer-to-peer 預設 3 輪，最多 5 輪 | -| coordinator 討論控制 | 每次最多收集 5 個 agent 觀點 | -| cron 頻率合理 | 不需要的 agent 不要排太密 | -| 記憶壓縮 | 秘書每日壓縮，避免 context 膨脹 | - -### 10.3 安全 - -| 項目 | 措施 | -|---|---| -| API Key | 環境變數，不進版本控制 | -| Agent 權限 | SOUL.md 嚴格定義 Forbidden + 工具白名單 | -| 交易執行 | 必須 HITL 批准 | -| Discord | Server 設為私人 | -| OpenClaw 更新 | 追蹤安全公告，及時更新 | - -### 10.4 停損信號 - -| 信號 | 動作 | -|---|---| -| 月費用超預期 2 倍 | 暫停非必要 agent | -| 反覆 revise 超過 5 輪 | 人工介入調整 prompt | -| 回測 winrate > 90% | 停下檢查 overfitting | -| Agent 產出品質下降 | 檢查記憶 + prompt | - ---- - -## 附錄：文件索引 - -| 文件 | 內容 | -|---|---| -| `spec_system_overview.md` | 第一部分：系統總覽 | -| `spec_org_and_roles.md` | 第二、三部分：組織架構 + 角色定義 | -| `spec_collaboration_protocol.md` | 第四部分：協作協定 | -| `spec_scheduling_memory.md` | 第五~七部分：排程 + 記憶 + Discord | -| `spec_rollout_and_risks.md` | 第八~十部分：Schema + 上線 + 風險 | diff --git a/docs/spec/spec_scheduling_memory.md b/docs/spec/spec_scheduling_memory.md deleted file mode 100644 index 6a8b318..0000000 --- a/docs/spec/spec_scheduling_memory.md +++ /dev/null @@ -1,138 +0,0 @@ -# KingClawArmy - 第五部分：排程與觸發 & 第六部分：記憶 & 第七部分：Discord - -> 日期：2026-04-10 -> 狀態：定稿（遷移至 Paperclip 前的參考版本） - ---- - -> **注意：** 協作模式已獨立至 **[spec_collaboration_protocol.md](spec_collaboration_protocol.md)** - ---- - -## 第五部分：排程與觸發 - -### 5.1 Cron 排程 - -```bash -# 量化 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 "每日市場情報" -openclaw cron add --agent market_researcher --cron "0 9 * * 1" --task "每週市場分析報告" - -# 投放分析 — 每日 -openclaw cron add --agent ads_analyst --cron "30 9 * * *" --task "每日投放 KPI 檢查" - -# 資料分析 — 每日 + 每週 -openclaw cron add --agent data_analyst --cron "0 20 * * *" --task "每日資料摘要" -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 流程改由 **Lobster DSL** 定義（見 [spec_v4_collaboration_protocol.md](spec_v4_collaboration_protocol.md) 4.4 節），不再使用 Standing Orders。 - -Cron 觸發 CEO → CEO spawn 策略師 → 策略師按 Lobster DSL 自動執行。 - ---- - -## 第六部分：記憶架構 - -### 6.1 OpenClaw 記憶系統 - -| 層級 | 檔案/機制 | 用途 | -|---|---|---| -| **長期記憶** | `MEMORY.md` | 每個 agent 的永久知識，session 啟動時自動載入 | -| **每日筆記** | `memory/YYYY-MM-DD.md` | 今日工作記錄，自動載入今天+昨天 | -| **夢境整合** | `DREAMS.md` | 可選，定期整合零散記憶 | -| **語意搜尋** | `memory_search` | 混合向量+關鍵字搜尋歷史記憶 | -| **跨 agent** | QMD `extraCollections` | Agent A 搜尋 Agent B 的記憶 | - -### 6.2 記憶分類與負責人 - -| 記憶類型 | 存放位置 | 寫入者 | 讀取者 | -|---|---|---|---| -| 董事長決策 | CEO 的 MEMORY.md | 秘書 | 所有 agent（via QMD） | -| 量化策略規則 | quant_strategist 的 MEMORY.md | 量化策略研究員 | 回測工程師、資料分析員 | -| 回測結果摘要 | data_analyst 的 MEMORY.md | 資料分析員 | 量化策略、CEO | -| 品牌知識庫 | strategy_director 的 MEMORY.md | 策略總監 | 文案、創意 | -| 會議結論 | secretary 的 memory/ 每日筆記 | 秘書 | 所有 agent（via QMD） | -| 個別工作脈絡 | 各 agent 的 memory/ 每日筆記 | 各 agent | 該 agent + 秘書 | - -### 6.3 記憶生命週期 - -| 類型 | 保留方式 | -|---|---| -| MEMORY.md | 永久，除非手動更新 | -| 每日筆記 | 自動載入今天+昨天；更舊的靠 memory_search | -| 秘書壓縮 | 每日 23:00 將當日重點寫入 MEMORY.md，清理冗餘 | - -### 6.4 未來考量 - -當 Phase 3 行銷團隊加入後，跨團隊記憶需求增大時，可考慮導入 **MemOS**（100% 本地、SQLite 後端、混合搜尋、支援多 agent 協作），作為 QMD 的補強或替代。目前 OpenClaw 內建記憶系統足夠 Phase 1-2 使用。 - ---- - -## 第七部分：Discord Server 結構 - -### 7.1 頻道規劃 - -``` -KingClawArmy Discord Server -│ -├── 📋 管理 -│ ├── #執行長 — 執行長回覆董事長、進度回報 -│ ├── #審批 — HITL 審批（董事長在這裡批准） -│ └── #異常 — 錯誤與異常 -│ -├── 📊 量化 -│ ├── #每日情報 — 盤前盤後情報 -│ ├── #研究討論 — 研究過程摘要（pass 後） -│ └── #策略結果 — 策略定稿、回測結果 -│ -├── 📈 行銷 -│ ├── #marketing-intel — 市場情報 -│ └── #ads-performance — 投放 KPI -│ -├── ✏️ 內容 -│ └── #content-briefs — 文案 / 創意 brief -│ -├── 📝 記錄 -│ ├── #每日摘要 — 秘書每日工作摘要 -│ └── #決策紀錄 — 重大決策存檔 -│ -└── 💬 閒聊 - └── #閒聊 — 小安陪聊 -``` - -### 7.2 Discord 互動方式 - -| 你想做的事 | 怎麼做 | -|---|---| -| 下達新指令 | 在 #執行長 跟 CEO agent 說 | -| 查看進度 | 問 CEO 或秘書 | -| 批准高風險動作 | 在 #審批 回覆 approve / reject | -| 看今日摘要 | #每日摘要 自動推送（秘書每日產出） | -| 看回測結果 | #策略結果 | -| 手動發起討論 | @CEO 說「召集量化團隊討論 [主題]」 | -| 緊急停止 | `openclaw tasks flow cancel ` 或 Discord @CEO「停止 [任務]」 | - -### 7.3 通知規則 - -| 事件 | 推送到 | 由誰推送 | -|---|---|---| -| Pipeline 完成 | #策略結果 + #審批 | CEO | -| 審查 pass（需 HITL） | #審批 | CEO | -| 審查 block | #異常 + #審批 | CEO | -| 每日情報 | #每日情報 | CEO（轉發情報員結果） | -| 每日摘要 | #每日摘要 | 秘書 | -| 決策紀錄 | #決策紀錄 | 秘書 | -| 錯誤/異常 | #異常 | CEO | diff --git a/docs/spec/spec_system_overview.md b/docs/spec/spec_system_overview.md deleted file mode 100644 index 3704abd..0000000 --- a/docs/spec/spec_system_overview.md +++ /dev/null @@ -1,95 +0,0 @@ -# KingClawArmy AI Agent Team - 系統規格書 - -> 日期：2026-04-09 -> 狀態：定稿（遷移至 Paperclip 前的參考版本） -> 備註：原為純 OpenClaw 架構，現已決定遷移至 Paperclip - ---- - -## 第一部分：系統總覽 - -### 1.1 系統目標 - -建立一個 AI Agent 團隊（代號 KingClawArmy），能夠： - -1. **量化研究**：情報蒐集 → 市場結構分析 → 多空辯論 → 策略形成 → 回測 → 分析 -2. **行銷策略**：市場研究 → 品牌/成長策略 → 投放分析 -3. **內容創作**：策略 → 文案撰寫 → 視覺方向 -4. **工程開發**：前端/後端（依需求啟用） -5. **自主協作**：Agent 之間能交換資訊、討論、產出 1+1 > 2 的效果 - -### 1.2 設計原則 - -| 原則 | 說明 | -|---|---| -| **一套系統** | 全部用 OpenClaw，不疊加外部系統 | -| **Model-Agnostic** | 不綁定任何 AI 模型，雲端或本地皆可 | -| **漸進式上線** | 一隻一隻加入，觀察調整再擴編 | -| **人類保留最終決策權** | 高風險動作必須經過董事長批准 | -| **討論產生價值** | 關鍵決策點安排多 Agent 協作 | - -### 1.3 整體架構 - -``` -┌────────────────────────────────────┐ -│ 你（董事長） │ -│ Discord 管理 + HITL 審批 │ -└─────────────────┬──────────────────┘ - │ -┌─────────────────▼──────────────────┐ -│ OpenClaw Gateway │ -│ │ -│ ┌─ Agent 管理 ──────────────────┐ │ -│ │ agent routing + bindings │ │ -│ │ sub-agent 派工 │ │ -│ │ sessions_send 溝通 │ │ -│ └───────────────────────────────┘ │ -│ │ -│ ┌─ 任務與排程 ──────────────────┐ │ -│ │ Task Flow 任務管理 │ │ -│ │ Cron 排程（5/6 欄位 + 時區） │ │ -│ │ Hooks 事件觸發（13+ 類型） │ │ -│ │ Standing Orders 常駐指令 │ │ -│ └───────────────────────────────┘ │ -│ │ -│ ┌─ 記憶 ────────────────────────┐ │ -│ │ MEMORY.md 長期記憶 │ │ -│ │ daily notes 每日筆記 │ │ -│ │ memory_search 語意搜尋 │ │ -│ │ QMD/Honcho 跨 agent 記憶 │ │ -│ └───────────────────────────────┘ │ -│ │ -│ ┌─ 工作流 ──────────────────────┐ │ -│ │ Lobster DSL 多步驟流程 │ │ -│ │ 審批 gate + timeout │ │ -│ └───────────────────────────────┘ │ -│ │ -│ ┌─ 整合 ────────────────────────┐ │ -│ │ Discord 完整整合 │ │ -│ │ MCP 3,200+ skills │ │ -│ │ 30+ 通訊平台 │ │ -│ └───────────────────────────────┘ │ -│ │ -│ ┌─ 模型（隨你接）──────────────┐ │ -│ │ Claude / GPT / DeepSeek │ │ -│ │ Gemini / 本地 Ollama / vLLM │ │ -│ └───────────────────────────────┘ │ -└─────────────────────────────────────┘ -``` - -### 1.4 為什麼只用 OpenClaw - -| 之前考慮的工具 | 為什麼不需要 | -|---|---| -| Paperclip | OpenClaw 的 agent routing + Task Flow + cron 已涵蓋調度；Discord 已涵蓋管理介面 | -| Mem0 | OpenClaw 內建記憶 + QMD/Honcho 跨 agent 記憶已足夠 | -| AutoGen | 群組辯論用 coordinator 模式替代；等 OpenClaw #18869 實裝後原生支援 | -| n8n | OpenClaw cron + hooks 已涵蓋排程與事件觸發 | - -### 1.5 已知限制 - -| 限制 | 影響 | 緩解方式 | -|---|---|---| -| 無原生群組辯論（#18869） | 3+ agent 即時辯論不支援 | coordinator 模式串行替代，或等原生支援 | -| 無視覺化管理 UI | 沒有漂亮 dashboard | Discord slash commands + CLI 管理 | -| 無 per-agent 預算 dashboard | 成本追蹤不方便 | 自訂 skill 追蹤 token 用量 |