From 8d976106347804c60612b4d695ec07539daaea52 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 9 Apr 2026 03:39:29 +0800 Subject: [PATCH] Initial commit: KingClawArmy AI Agent Team spec v4 Pure OpenClaw architecture for 15-17 agent team covering quant research, marketing, content, and engineering. Includes org structure, role definitions, collaboration patterns, scheduling, memory architecture, Discord integration, rollout plan, and JSON schemas. Co-Authored-By: Claude Opus 4.6 --- .gitignore | 1 + docs/agent_company_master_overview_v2.md | 207 +++++++ docs/agent_company_runtime_config_v2.md | 221 ++++++++ docs/agent_company_schema_templates_v2.md | 513 ++++++++++++++++++ docs/spec_v3_collaboration.md | 203 +++++++ docs/spec_v3_org_and_roles.md | 399 ++++++++++++++ docs/spec_v3_rollout_and_risks.md | 187 +++++++ docs/spec_v3_scheduling_memory_discord.md | 194 +++++++ docs/spec_v3_schemas.md | 412 ++++++++++++++ docs/spec_v3_system_overview.md | 129 +++++ ...spec_v4_collaboration_scheduling_memory.md | 238 ++++++++ docs/spec_v4_org_and_roles.md | 317 +++++++++++ docs/spec_v4_rollout_and_risks.md | 138 +++++ docs/spec_v4_system_overview.md | 96 ++++ 14 files changed, 3255 insertions(+) create mode 100644 .gitignore create mode 100644 docs/agent_company_master_overview_v2.md create mode 100644 docs/agent_company_runtime_config_v2.md create mode 100644 docs/agent_company_schema_templates_v2.md create mode 100644 docs/spec_v3_collaboration.md create mode 100644 docs/spec_v3_org_and_roles.md create mode 100644 docs/spec_v3_rollout_and_risks.md create mode 100644 docs/spec_v3_scheduling_memory_discord.md create mode 100644 docs/spec_v3_schemas.md create mode 100644 docs/spec_v3_system_overview.md create mode 100644 docs/spec_v4_collaboration_scheduling_memory.md create mode 100644 docs/spec_v4_org_and_roles.md create mode 100644 docs/spec_v4_rollout_and_risks.md create mode 100644 docs/spec_v4_system_overview.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e43b0f9 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.DS_Store diff --git a/docs/agent_company_master_overview_v2.md b/docs/agent_company_master_overview_v2.md new file mode 100644 index 0000000..c84f1d2 --- /dev/null +++ b/docs/agent_company_master_overview_v2.md @@ -0,0 +1,207 @@ +# AI Agent Company - 主檔總覽（精簡定稿版） + +> 用途：總覽主檔 +> 內容：角色、狀態池、模型配置、觸發方式、上線順序 +> 備註：已正式拆出 **回測工程師 / Quant Engineer** + +--- + +## 1. 最終組織結構 + +| 層級 | 職權 | +|---|---| +| 董事長層 | 董事長 | +| 核心管理層 | CEO / COO、秘書、審查員 | +| 情報層 | 財經情報研究員、市場情報研究員 | +| 量化線 | 市場結構研究員、多方研究員、空方 / 反方研究員、量化策略研究員、風控研究員、回測工程師 / Quant Engineer、資料分析員 | +| 策略與成長層 | 品牌策略總監、成長策略總監、市場研究分析師、投放成效分析師 | +| 內容與創意層 | 廣告文案撰寫員、影片腳本撰寫員、平面視覺設計總監、影片分鏡創意總監 | +| 工程層 | 前端工程師、後端工程師 | + +--- + +## 2. 角色職權表 + +### 2.1 核心管理層 + +| 職權 | 任務目標 | 不該做的事 | +|---|---|---| +| 董事長 | 最終拍板、資源決策、是否上線與發布 | 不做細部執行 | +| CEO / COO | 拆任務、分派、收斂、匯報 | 不直接寫文案、不直接寫程式、不直接部署 | +| 秘書 | 摘要、State Diff、Todo、記憶壓縮 | 不做策略決策 | +| 審查員 | pass / revise / block、風險攔截 | 不重寫全部內容、不直接拍板 | + +### 2.2 情報與量化線 + +| 職權 | 任務目標 | 不該做的事 | +|---|---|---| +| 財經情報研究員 | 搜集財經、總經、盤前盤後資訊 | 不下交易結論 | +| 市場情報研究員 | 搜集競品、消費者痛點、平台趨勢 | 不下商業策略結論 | +| 市場結構研究員 | 解析流動性、結構、掃單、MSS、OB、FVG、POI | 不直接下最終交易結論 | +| 多方研究員 | 專門整理支持交易 / 做多的論點 | 不直接拍板 | +| 空方 / 反方研究員 | 專門整理反對交易 / 做空 / 放棄交易的論點 | 不直接拍板 | +| 量化策略研究員 | 收斂觀點形成正式規則 | 不寫正式程式碼 | +| 風控研究員 | 設計風控規則、bias check、position sizing | 不發明策略方向 | +| 回測工程師 / Quant Engineer | 將策略規則轉成 Pine / Python 回測、接資料、產出回測結果 | 不自行改策略方向、不自行做最終績效結論 | +| 資料分析員 | SQL、KPI、回測分析、expectancy / drawdown / winrate 洞察 | 不自行定策略方向 | + +### 2.3 行銷、內容、工程層 + +| 職權 | 任務目標 | 不該做的事 | +|---|---|---| +| 品牌策略總監 | 定 USP、受眾、主訴求、品牌敘事 | 不直接寫最終文案 | +| 成長策略總監 | 定 campaign、漏斗、轉換策略 | 不寫底層 SQL | +| 市場研究分析師 | 分析市場變化與競品反應 | 不盯每日廣告 KPI | +| 投放成效分析師 | 分析 CTR / CVR / CPL / ROAS 與投放優化 | 不做品牌定位 | +| 廣告文案撰寫員 | 廣告文案、Hook、Body、CTA、版本矩陣 | 不改整體策略 | +| 影片腳本撰寫員 | 短影音腳本、旁白、節奏、鏡頭腳本 | 不負責平面廣告文案 | +| 平面視覺設計總監 | 圖像 brief、平面素材 QA、視覺一致性 | 不負責影片分鏡 | +| 影片分鏡創意總監 | 分鏡 brief、動態素材結構、影片 QA | 不負責平面素材 | +| 前端工程師 | 前端頁面、UI 互動、追蹤埋點 | 不決定商業策略 | +| 後端工程師 | API、資料庫、Directus、自動化整合 | 不寫廣告文案 | + +--- + +## 3. 狀態池（256GB 定稿） + +| 狀態 | 角色 | +|---|---| +| 常駐 | CEO / COO、秘書 | +| warm | 審查員、前端工程師、後端工程師 | +| 喚醒 | 財經情報研究員、市場情報研究員、市場結構研究員、多方研究員、空方 / 反方研究員、量化策略研究員、風控研究員、回測工程師 / Quant Engineer、品牌策略總監、成長策略總監、市場研究分析師、投放成效分析師、廣告文案撰寫員、影片腳本撰寫員、平面視覺設計總監、影片分鏡創意總監、資料分析員 | + +--- + +## 4. 256GB 模型配置 + +| 職權 | 推薦模型 | 類型 | 狀態 | +|---|---|---|---| +| CEO / COO | Qwen3.5-27B | 通用主腦 | 常駐 | +| 秘書 | Qwen2.5-14B-Instruct | 小中型通用 | 常駐 | +| 審查員 | gpt-oss-120b 或 DeepSeek-V3.2 插槽 | reasoning / review | warm | +| 財經情報研究員 | Qwen2.5-14B-Instruct | 情報整理 | 喚醒 | +| 市場情報研究員 | Qwen2.5-14B-Instruct | 情報整理 | 喚醒 | +| 市場結構研究員 | DeepSeek-V3.2 插槽 | 結構推理 | 喚醒 | +| 多方研究員 | gpt-oss-120b 或 DeepSeek-V3.2 插槽 | 辯論 / 推理 | 喚醒 | +| 空方 / 反方研究員 | gpt-oss-120b 或 DeepSeek-V3.2 插槽 | 辯論 / 推理 | 喚醒 | +| 量化策略研究員 | gpt-oss-120b 或 DeepSeek-V3.2 插槽 | 高階策略推理 | 喚醒 | +| 風控研究員 | DeepSeek-V3.2 插槽 | reasoning | 喚醒 | +| 回測工程師 / Quant Engineer | Qwen3-Coder-30B-A3B-Instruct | coder | 喚醒 | +| 資料分析員 | DeepSeek-V3.2 插槽（深度）/ Qwen3.5-27B（一般） | 分析 | 喚醒 | +| 品牌策略總監 | gpt-oss-120b 或 Qwen3.5-122B-A10B 插槽 | 高階策略 | 喚醒 | +| 成長策略總監 | gpt-oss-120b 或 Qwen3.5-122B-A10B 插槽 | 高階策略 | 喚醒 | +| 市場研究分析師 | gpt-oss-120b 或 DeepSeek-V3.2 插槽 | 深度分析 | 喚醒 | +| 投放成效分析師 | gpt-oss-120b 或 DeepSeek-V3.2 插槽 | 深度分析 | 喚醒 | +| 廣告文案撰寫員 | 台灣語感 8B 級模型 | 文案模型 | 喚醒 | +| 影片腳本撰寫員 | 台灣語感 8B 級模型 | 文案模型 | 喚醒 | +| 平面視覺設計總監 | Qwen3-VL-8B-Instruct | VL | 喚醒 | +| 影片分鏡創意總監 | Qwen3-VL-8B-Instruct | VL | 喚醒 | +| 前端工程師 | Qwen3-Coder-30B-A3B-Instruct | coder | warm | +| 後端工程師 | Qwen3-Coder-30B-A3B-Instruct | coder | warm | + +--- + +## 5. 觸發條件 + +### 5.1 定時觸發 + +| 角色 | 頻率 | 說明 | +|---|---|---| +| 財經情報研究員 | 每日盤前一次、盤後一次 | 蒐集財經與盤勢資訊 | +| 市場情報研究員 | 每日 1 次 | 蒐集市場、競品、痛點資訊 | +| 市場研究分析師 | 每週 1 次 | 市場趨勢與競品分析 | +| 投放成效分析師 | 每日 1 次 | 廣告 KPI 檢查 | +| 資料分析員 | 每日 1 次 + 每週 1 次週報 | KPI、報表與洞察 | + +### 5.2 事件觸發 + +| 角色 | 觸發條件 | +|---|---| +| CEO / COO | 新任務進來、各部門完成輸出、審查回來、提案前 | +| 秘書 | 會議結束、狀態改變、待辦更新 | +| 審查員 | 草稿完成、部署前、高風險操作前、revise 超過輪數 | +| 市場結構研究員 | 財經情報與行情資料齊備時 | +| 多方研究員 | 市場結構報告與財經情報完成後 | +| 空方 / 反方研究員 | 市場結構報告與財經情報完成後 | +| 量化策略研究員 | 多方 / 空方研究報告完成後 | +| 風控研究員 | 量化策略規格完成後 | +| 回測工程師 / Quant Engineer | 量化策略 + 風控規格完成後 | +| 品牌策略總監 | 新產品 / 新 campaign / 方向重定 | +| 成長策略總監 | 品牌策略完成後、Campaign 執行前 | +| 廣告文案撰寫員 | 成長策略完成後、需要新文案版本時 | +| 影片腳本撰寫員 | 需要影片腳本時 | +| 平面視覺設計總監 | 需要平面素材 brief 時 | +| 影片分鏡創意總監 | 需要分鏡或影片素材時 | +| 前端工程師 | 收到前端任務、Review 打回修正 | +| 後端工程師 | 收到後端任務、Review 打回修正 | + +### 5.3 人工決策 + +| 角色 | 觸發條件 | +|---|---| +| 董事長 | 最終提案、高風險動作、部署前、預算與上線決策 | + +--- + +## 6. 工具權限 + +| 角色 | 可用工具 | 禁用工具 | +|---|---|---| +| 財經情報研究員 | 搜尋、爬蟲、清洗、去重 | DB schema 修改、部署 | +| 市場情報研究員 | 搜尋、爬蟲、清洗、去重 | DB schema 修改、部署 | +| 市場結構研究員 | 行情資料、結構分析工具、圖表讀取 | 正式部署、DB schema 修改 | +| 多方研究員 | 唯讀研究報告與結構報告 | 直接下單、正式部署 | +| 空方 / 反方研究員 | 唯讀研究報告與結構報告 | 直接下單、正式部署 | +| 量化策略研究員 | 讀研究報告、策略規格工具 | 正式交易執行 | +| 風控研究員 | 讀策略規格、風控規則工具 | 正式交易執行 | +| 回測工程師 / Quant Engineer | repo、回測框架、歷史資料、sandbox | 正式交易執行、正式部署 | +| 品牌策略總監 | 品牌知識庫、Research 摘要 | shell、DB schema 修改 | +| 成長策略總監 | 策略知識庫、Research 摘要 | shell、DB schema 修改 | +| 廣告文案撰寫員 | 文案資料、品牌語氣庫 | shell、部署 | +| 影片腳本撰寫員 | 文案資料、品牌語氣庫 | shell、部署 | +| 平面視覺設計總監 | 素材規格、品牌規範、VL 任務工具 | 正式發布、DB schema 修改 | +| 影片分鏡創意總監 | 素材規格、品牌規範、VL 任務工具 | 正式發布、DB schema 修改 | +| 前端工程師 | repo、前端 build、tracking 測試 | 正式 DB schema 修改 | +| 後端工程師 | API / DB / Directus / sandbox | 正式發布（需 gate） | +| 審查員 | 所有輸出唯讀檢查 | 正式改檔、正式部署 | +| 秘書 | 所有摘要與狀態讀寫 | shell、正式部署 | +| CEO / COO | 任務總覽、所有角色輸出唯讀 | 正式部署、正式寫 DB | + +--- + +## 7. Review Gate / HITL + +### 7.1 必審節點 + +| 節點 | 原因 | +|---|---| +| 跨部門產出整合完成後 | 確保整體對齊 | +| 工程交付前 | 確保 API / schema / build 合理 | +| 量化策略提交前 | 確保規則與 bias check 合理 | +| 回測結果提交前 | 確保回測設定、交易成本、偏誤檢查合理 | +| 廣告 / 文案對外前 | 避免承諾過度與品牌風險 | +| 部署前 | 高風險必審 | + +### 7.2 必須 HITL 節點 + +| 節點 | 原因 | +|---|---| +| 正式環境部署前 | 高風險 | +| 資料庫 schema 變更前 | 高風險 | +| 廣告正式發布前 | 涉及預算與品牌 | +| 對外正式訊息發送前 | 涉及品牌與客戶 | +| 涉及金流 / 核心商業資料操作前 | 高風險 | +| 涉及量化策略正式自動執行前 | 高風險 | + +--- + +## 8. 上線順序（量化優先版） + +| 階段 | 上線角色 / 模組 | 目的 | +|---|---|---| +| Step 1 | CEO / COO、秘書、審查員 | 跑通核心管理閉環 | +| Step 2 | 財經情報研究員、市場結構研究員、多方研究員、空方 / 反方研究員、量化策略研究員、風控研究員、回測工程師 / Quant Engineer、資料分析員 | 跑通量化研究與回測閉環 | +| Step 3 | 前端工程師、後端工程師、sandbox runner | 跑通工程閉環 | +| Step 4 | 市場情報研究員、品牌策略總監、成長策略總監、市場研究分析師、投放成效分析師 | 跑通情報與策略閉環 | +| Step 5 | 廣告文案撰寫員、影片腳本撰寫員、平面視覺設計總監、影片分鏡創意總監 | 跑通內容與創意閉環 | +| Step 6 | scheduler、權限矩陣、Review Gate、HITL | 升級到可營運版 | diff --git a/docs/agent_company_runtime_config_v2.md b/docs/agent_company_runtime_config_v2.md new file mode 100644 index 0000000..e5fcedf --- /dev/null +++ b/docs/agent_company_runtime_config_v2.md @@ -0,0 +1,221 @@ +# AI Agent Company - Runtime 配置檔（Prompt / LangGraph / Scheduler） + +> 用途：只放 runtime 設定 +> 內容：角色 prompt 規格、LangGraph 節點命名、scheduler / webhook / cron、第一梯隊量化優先版 + +--- + +## 1. 角色 Prompt 共用規則 + +### 1.1 Prompt 必備欄位 + +| 欄位 | 說明 | +|---|---| +| Role | 角色名稱 | +| Mission | 任務目標 | +| Scope | 允許做的事 | +| Forbidden | 禁止事項 | +| Inputs | 預期輸入 | +| Outputs | 預期輸出 | +| Success Criteria | 成功標準 | +| Failure Conditions | 失敗條件 | +| Escalation | 何時交給 CEO / 審查員 / 董事長 | +| Style | 輸出風格 | +| Output Rule | 必須輸出 JSON | + +### 1.2 Prompt 共用結尾 +```text +You must only operate within your assigned role boundary. +Do not perform work outside your scope. +If required information is missing, explicitly return the missing_fields list. +If there is conflict, uncertainty, or high risk, escalate instead of guessing. +Your output must follow the required JSON schema exactly. +Do not add extra commentary outside the JSON payload. +``` + +--- + +## 2. 各角色 Prompt 規格（簡版） + +| 角色 | Mission | Forbidden | Output | +|---|---|---|---| +| CEO / COO | 拆任務、分派、收斂、匯報 | 不直接寫文案 / 寫程式 / 部署 | Task_Spec.json、Final_Decision_Packet.json | +| 秘書 | 摘要、State Diff、Todo、記憶壓縮 | 不做策略決策 | Meeting_Summary.json、State_Diff.json、Todo_List.json | +| 審查員 | pass / revise / block、風險攔截 | 不重寫全部內容 | Review_Report.json | +| 財經情報研究員 | 財經 / 總經 / 盤前盤後資訊整理 | 不下交易結論 | Finance_Research_Brief.json | +| 市場結構研究員 | 結構、流動性、MSS、POI 分析 | 不下最終交易結論 | Market_Structure_Report.json | +| 多方研究員 | 建立支持交易論點 | 不直接拍板 | Bullish_Research_Report.json | +| 空方 / 反方研究員 | 建立反對交易論點 | 不直接拍板 | Bearish_Research_Report.json | +| 量化策略研究員 | 收斂成正式規則 | 不寫正式程式碼 | Quant_Strategy_Spec.json | +| 風控研究員 | 風控框架、bias check、position sizing | 不發明策略方向 | Risk_Control_Spec.json | +| 回測工程師 / Quant Engineer | 把規則轉成 Pine / Python 回測 | 不自行改策略方向 | Backtest_Delivery.json | +| 資料分析員 | KPI、回測分析、洞察 | 不自行定策略方向 | Data_Analysis_Report.json | +| 品牌策略總監 | USP、受眾、品牌敘事 | 不直接寫最終文案 | Brand_Strategy_Plan.json | +| 成長策略總監 | Campaign、funnel、轉換策略 | 不寫底層 SQL | Growth_Strategy_Plan.json | +| 市場研究分析師 | 市場變化與競品分析 | 不盯每日 KPI | Market_Analysis_Report.json | +| 投放成效分析師 | CTR / CVR / CPL / ROAS 診斷 | 不做品牌定位 | Ads_Performance_Report.json | +| 廣告文案撰寫員 | 廣告文案、Hook、CTA | 不改整體策略 | Copywriting_Pack.json | +| 影片腳本撰寫員 | 影片腳本、旁白、節奏 | 不做平面廣告文案 | Video_Script_Pack.json | +| 平面視覺設計總監 | 平面 brief、素材 QA | 不負責影片分鏡 | Static_Creative_Brief.json | +| 影片分鏡創意總監 | 分鏡 brief、影片視覺 QA | 不負責平面素材 | Storyboard_Brief.json | +| 前端工程師 | 前端頁面、UI、埋點 | 不定商業策略 | Frontend_Delivery.json | +| 後端工程師 | API、DB、Directus、自動化 | 不寫廣告文案 | Backend_Delivery.json | + +--- + +## 3. LangGraph 節點命名 + +### 3.1 命名規則 + +| 規則 | 說明 | +|---|---| +| 小寫 snake_case | 統一命名 | +| `role_*` | 角色節點 | +| `sys_*` | 系統節點 | +| `gate_*` | 審核節點 | +| `hitl_*` | 人工中斷節點 | + +### 3.2 節點表 + +| 類型 | 節點名稱 | 用途 | +|---|---|---| +| 系統 | `sys_receive_request` | 接收董事長需求 | +| 角色 | `role_ceo_dispatch` | CEO 拆任務 | +| 角色 | `role_secretary_summarize` | 秘書摘要與 state diff | +| 角色 | `role_reviewer_audit` | 審查員審核 | +| 系統 | `sys_prepare_final_packet` | 組裝決策包 | +| HITL | `hitl_chairman_decision` | 董事長決策 | +| 角色 | `role_finance_research` | 財經情報研究員 | +| 角色 | `role_market_research` | 市場情報研究員 | +| 角色 | `role_market_structure` | 市場結構研究員 | +| 角色 | `role_bullish_case` | 多方研究員 | +| 角色 | `role_bearish_case` | 空方 / 反方研究員 | +| 角色 | `role_quant_strategy` | 量化策略研究員 | +| 角色 | `role_risk_control` | 風控研究員 | +| 角色 | `role_quant_backtest` | 回測工程師 / Quant Engineer | +| 角色 | `role_data_analysis` | 資料分析員 | +| 角色 | `role_brand_strategy` | 品牌策略總監 | +| 角色 | `role_growth_strategy` | 成長策略總監 | +| 角色 | `role_market_analysis` | 市場研究分析師 | +| 角色 | `role_ads_analysis` | 投放成效分析師 | +| 角色 | `role_ad_copywriting` | 廣告文案撰寫員 | +| 角色 | `role_video_script` | 影片腳本撰寫員 | +| 角色 | `role_static_creative` | 平面視覺設計總監 | +| 角色 | `role_storyboard_creative` | 影片分鏡創意總監 | +| 角色 | `role_frontend_build` | 前端工程師 | +| 角色 | `role_backend_build` | 後端工程師 | +| 系統 | `sys_run_sandbox_tests` | sandbox 驗證 | +| gate | `gate_quant_review` | 量化策略與回測前審核 | +| gate | `gate_engineering_review` | 工程交付前審核 | +| gate | `gate_content_review` | 對外文案與素材前審核 | +| HITL | `hitl_db_schema_approval` | 正式 DB schema 變更前批准 | +| HITL | `hitl_production_deploy_approval` | 正式部署前批准 | +| HITL | `hitl_quant_execution_approval` | 量化策略正式自動執行前批准 | + +--- + +## 4. 量化優先主流程 + +| 順序 | 節點 | +|---:|---| +| 1 | `sys_receive_request` | +| 2 | `role_ceo_dispatch` | +| 3 | `role_finance_research` | +| 4 | `role_market_structure` | +| 5 | `role_bullish_case` | +| 6 | `role_bearish_case` | +| 7 | `role_quant_strategy` | +| 8 | `role_risk_control` | +| 9 | `role_quant_backtest` | +| 10 | `role_data_analysis` | +| 11 | `role_secretary_summarize` | +| 12 | `gate_quant_review` | +| 13 | `sys_prepare_final_packet` | +| 14 | `hitl_chairman_decision` | + +--- + +## 5. scheduler / webhook / cron 對照表 + +### 5.1 cron 任務 + +| 任務名稱 | 類型 | 建議排程 | 觸發節點 | +|---|---|---|---| +| finance_morning_scan | cron | 每日 07:30 | `role_finance_research` | +| finance_evening_scan | cron | 每日 18:30 | `role_finance_research` | +| market_daily_scan | cron | 每日 10:00 | `role_market_research` | +| ads_daily_check | cron | 每日 09:30 | `role_ads_analysis` | +| data_daily_summary | cron | 每日 20:00 | `role_data_analysis` | +| market_weekly_review | cron | 每週一 09:00 | `role_market_analysis` | +| data_weekly_report | cron | 每週一 10:00 | `role_data_analysis` | +| secretary_daily_compact | cron | 每日 23:00 | `role_secretary_summarize` | + +### 5.2 webhook 任務 + +| 任務名稱 | webhook 來源 | 觸發節點 | +|---|---|---| +| chairman_new_request | 董事長輸入 / UI 表單 | `sys_receive_request` | +| campaign_metrics_updated | 廣告平台資料同步 | `role_ads_analysis` | +| backtest_finished | 回測服務完成 | `role_data_analysis` | +| market_data_ready | 市場資料服務完成 | `role_market_structure` | +| frontend_review_failed | sandbox / review 回報 | `role_frontend_build` | +| backend_review_failed | sandbox / review 回報 | `role_backend_build` | +| final_packet_ready | 系統收斂完成 | `hitl_chairman_decision` | + +### 5.3 內部事件觸發 + +| 上一節點完成後 | 自動觸發下一節點 | +|---|---| +| `role_ceo_dispatch` | `role_finance_research` 或其他專才 | +| `role_finance_research` | `role_market_structure` | +| `role_market_structure` | `role_bullish_case`、`role_bearish_case` | +| `role_bullish_case` + `role_bearish_case` | `role_quant_strategy` | +| `role_quant_strategy` | `role_risk_control` | +| `role_risk_control` | `role_quant_backtest` | +| `role_quant_backtest` | `role_data_analysis` | +| `role_data_analysis` | `role_secretary_summarize` | +| `role_secretary_summarize` | `role_reviewer_audit` | +| `role_reviewer_audit` verdict=revise | 回退到被點名角色 | +| `role_reviewer_audit` verdict=pass | `sys_prepare_final_packet` | +| `sys_prepare_final_packet` | `hitl_chairman_decision` | + +### 5.4 HITL 節點表 + +| 節點 | 人工角色 | 說明 | +|---|---|---| +| `hitl_chairman_decision` | 董事長 | 最終提案批准 / 拒絕 / 修改 | +| `hitl_db_schema_approval` | 董事長 | 正式 DB schema 變更前批准 | +| `hitl_production_deploy_approval` | 董事長 | 正式部署前批准 | +| `hitl_campaign_launch_approval` | 董事長 | 廣告正式發布前批准 | +| `hitl_external_message_approval` | 董事長 | 對外正式訊息前批准 | +| `hitl_quant_execution_approval` | 董事長 | 量化策略正式自動執行前批准 | + +--- + +## 6. 第一梯隊量化優先版 + +| 梯隊 | 角色 | +|---|---| +| 第一梯隊 | CEO / COO、秘書、審查員、財經情報研究員、市場結構研究員、多方研究員、空方 / 反方研究員、量化策略研究員、風控研究員、回測工程師 / Quant Engineer、資料分析員 | +| 第二梯隊 | 前端工程師、後端工程師 | +| 第三梯隊 | 市場情報研究員、品牌策略總監、成長策略總監、市場研究分析師、投放成效分析師 | +| 第四梯隊 | 廣告文案撰寫員、影片腳本撰寫員、平面視覺設計總監、影片分鏡創意總監 | + +### 第一梯隊最小可跑閉環 + +| 階段 | 節點 | +|---|---| +| 1 | 董事長提出量化任務 | +| 2 | CEO 拆成量化 Task_Spec | +| 3 | 財經情報研究員收集資料 | +| 4 | 市場結構研究員做結構分析 | +| 5 | 多方研究員提出支持論點 | +| 6 | 空方 / 反方研究員提出反對論點 | +| 7 | 量化策略研究員形成正式規則 | +| 8 | 風控研究員補齊風控與 bias check | +| 9 | 回測工程師將規則落地為 Pine / Python 回測 | +| 10 | 資料分析員接回測結果做分析 | +| 11 | 秘書輸出 Summary / State Diff / Todo | +| 12 | 審查員做量化 Review | +| 13 | CEO 組 Final_Decision_Packet | +| 14 | 董事長批准或退回 | diff --git a/docs/agent_company_schema_templates_v2.md b/docs/agent_company_schema_templates_v2.md new file mode 100644 index 0000000..d4b34a1 --- /dev/null +++ b/docs/agent_company_schema_templates_v2.md @@ -0,0 +1,513 @@ +# AI Agent Company - Schema 模板檔（JSON 規格專用） + +> 用途：只放 JSON schema template +> 原則：只保留格式，不放假資料 + +--- + +## 1. 共用欄位 + +```json +{ + "task_id": "", + "project_id": "", + "role": "", + "timestamp": "", + "status": "", + "input_version": "" +} +``` + +--- + +## 2. 核心管理層 + +### Chairman_Request_Packet.json +```json +{ + "task_id": "", + "project_id": "", + "role": "chairman", + "timestamp": "", + "status": "pending", + "input_version": "", + "request": "", + "constraints": [""], + "priority": "", + "attachments": [""] +} +``` + +### Task_Spec.json +```json +{ + "task_id": "", + "project_id": "", + "role": "ceo_coo", + "timestamp": "", + "status": "", + "input_version": "", + "goal": "", + "success_criteria": [""], + "routes": [ + { + "role": "", + "subtask": "", + "required_output": "" + } + ], + "priority": "", + "notes": [""] +} +``` + +### Meeting_Summary.json +```json +{ + "task_id": "", + "project_id": "", + "role": "secretary", + "timestamp": "", + "status": "done", + "input_version": "", + "topic": "", + "participants": [""], + "key_points": [""], + "decision": "", + "unresolved": [""] +} +``` + +### State_Diff.json +```json +{ + "task_id": "", + "project_id": "", + "role": "secretary", + "timestamp": "", + "status": "done", + "input_version": "", + "added": [""], + "changed": [""], + "removed": [""] +} +``` + +### Todo_List.json +```json +{ + "task_id": "", + "project_id": "", + "role": "secretary", + "timestamp": "", + "status": "done", + "input_version": "", + "items": [ + { + "owner": "", + "task": "", + "deadline": "" + } + ] +} +``` + +### Review_Report.json +```json +{ + "task_id": "", + "project_id": "", + "role": "reviewer", + "timestamp": "", + "status": "done", + "input_version": "", + "verdict": "", + "issues": [ + { + "severity": "", + "category": "", + "evidence": "", + "required_fix": "" + } + ], + "notes": "" +} +``` + +### Final_Decision_Packet.json +```json +{ + "task_id": "", + "project_id": "", + "role": "ceo_coo", + "timestamp": "", + "status": "done", + "input_version": "", + "summary": "", + "options": [ + { + "name": "", + "description": "", + "pros": [""], + "cons": [""], + "risk_level": "" + } + ], + "recommended_option": "", + "review_verdict": "", + "decision_needed": [""] +} +``` + +--- + +## 3. 情報與量化線 + +### Finance_Research_Brief.json +```json +{ + "task_id": "", + "project_id": "", + "role": "finance_intelligence_researcher", + "timestamp": "", + "status": "done", + "input_version": "", + "sources": [ + { + "title": "", + "url": "", + "canonical_url": "", + "published_at": "", + "source_type": "", + "summary": "", + "confidence": "", + "freshness_bucket": "", + "dedupe_key": "" + } + ], + "conflicts": [""], + "takeaways": [""] +} +``` + +### Market_Research_Brief.json +```json +{ + "task_id": "", + "project_id": "", + "role": "market_intelligence_researcher", + "timestamp": "", + "status": "done", + "input_version": "", + "sources": [ + { + "title": "", + "url": "", + "canonical_url": "", + "published_at": "", + "source_type": "", + "summary": "", + "confidence": "", + "freshness_bucket": "", + "dedupe_key": "" + } + ], + "pain_points": [""], + "competitor_patterns": [""], + "conflicts": [""], + "takeaways": [""] +} +``` + +### Market_Structure_Report.json +```json +{ + "task_id": "", + "project_id": "", + "role": "market_structure_researcher", + "timestamp": "", + "status": "done", + "input_version": "", + "timeframes_used": [""], + "structure_summary": [""], + "liquidity_zones": [""], + "poi_candidates": [""], + "mss_signals": [""], + "notes": [""] +} +``` + +### Bullish_Research_Report.json +```json +{ + "task_id": "", + "project_id": "", + "role": "bullish_researcher", + "timestamp": "", + "status": "done", + "input_version": "", + "bull_case": [""], + "supporting_evidence": [""], + "expected_edge": [""], + "invalidations": [""] +} +``` + +### Bearish_Research_Report.json +```json +{ + "task_id": "", + "project_id": "", + "role": "bearish_researcher", + "timestamp": "", + "status": "done", + "input_version": "", + "bear_case": [""], + "supporting_evidence": [""], + "risk_warnings": [""], + "trade_rejection_reasons": [""] +} +``` + +### Quant_Strategy_Spec.json +```json +{ + "task_id": "", + "project_id": "", + "role": "quant_strategy_researcher", + "timestamp": "", + "status": "done", + "input_version": "", + "strategy_hypothesis": [""], + "entry_rules": [""], + "exit_rules": [""], + "risk_rules": [""], + "bias_checks": [""] +} +``` + +### Risk_Control_Spec.json +```json +{ + "task_id": "", + "project_id": "", + "role": "risk_control_researcher", + "timestamp": "", + "status": "done", + "input_version": "", + "position_sizing": [""], + "stop_rules": [""], + "take_profit_rules": [""], + "bias_checks": [""] +} +``` + +### Backtest_Delivery.json +```json +{ + "task_id": "", + "project_id": "", + "role": "quant_engineer", + "timestamp": "", + "status": "done", + "input_version": "", + "implementation_type": "", + "rules_implemented": [""], + "data_used": [""], + "assumptions": [""], + "artifacts": [""], + "handoff_notes": [""] +} +``` + +### Data_Analysis_Report.json +```json +{ + "task_id": "", + "project_id": "", + "role": "data_analyst", + "timestamp": "", + "status": "done", + "input_version": "", + "kpi_summary": [""], + "ab_test_results": [""], + "insights": [""], + "recommendations": [""] +} +``` + +--- + +## 4. 行銷與創意層 + +### Brand_Strategy_Plan.json +```json +{ + "task_id": "", + "project_id": "", + "role": "brand_strategy_director", + "timestamp": "", + "status": "done", + "input_version": "", + "usp": [""], + "target_audience": [""], + "core_messages": [""], + "brand_story": [""] +} +``` + +### Growth_Strategy_Plan.json +```json +{ + "task_id": "", + "project_id": "", + "role": "growth_strategy_director", + "timestamp": "", + "status": "done", + "input_version": "", + "campaign_direction": [""], + "funnel_plan": [""], + "conversion_strategy": [""], + "test_plan": [""] +} +``` + +### Market_Analysis_Report.json +```json +{ + "task_id": "", + "project_id": "", + "role": "market_research_analyst", + "timestamp": "", + "status": "done", + "input_version": "", + "market_summary": [""], + "trend_signals": [""], + "recommendations": [""] +} +``` + +### Ads_Performance_Report.json +```json +{ + "task_id": "", + "project_id": "", + "role": "ads_performance_analyst", + "timestamp": "", + "status": "done", + "input_version": "", + "performance_summary": [""], + "diagnosis": [""], + "optimization_suggestions": [""], + "alerts": [""] +} +``` + +### Copywriting_Pack.json +```json +{ + "task_id": "", + "project_id": "", + "role": "ad_copywriter", + "timestamp": "", + "status": "done", + "input_version": "", + "hooks": [""], + "bodies": [""], + "ctas": [""] +} +``` + +### Video_Script_Pack.json +```json +{ + "task_id": "", + "project_id": "", + "role": "video_script_writer", + "timestamp": "", + "status": "done", + "input_version": "", + "opening_hook": "", + "sections": [ + { + "scene": "", + "message": "", + "duration_seconds": "" + } + ], + "ending_cta": "" +} +``` + +### Static_Creative_Brief.json +```json +{ + "task_id": "", + "project_id": "", + "role": "static_visual_design_director", + "timestamp": "", + "status": "done", + "input_version": "", + "visual_direction": [""], + "must_include": [""], + "asset_specs": [""], + "qa_notes": [""] +} +``` + +### Storyboard_Brief.json +```json +{ + "task_id": "", + "project_id": "", + "role": "storyboard_creative_director", + "timestamp": "", + "status": "done", + "input_version": "", + "shots": [ + { + "scene": "", + "visual": "", + "motion": "", + "caption": "" + } + ], + "style_notes": [""] +} +``` + +--- + +## 5. 工程層 + +### Frontend_Delivery.json +```json +{ + "task_id": "", + "project_id": "", + "role": "frontend_engineer", + "timestamp": "", + "status": "done", + "input_version": "", + "components_built": [""], + "tracking_added": [""], + "ui_changes": [""], + "handoff_notes": [""] +} +``` + +### Backend_Delivery.json +```json +{ + "task_id": "", + "project_id": "", + "role": "backend_engineer", + "timestamp": "", + "status": "done", + "input_version": "", + "apis_built": [""], + "schema_changes": [""], + "automations_added": [""], + "handoff_notes": [""] +} +``` diff --git a/docs/spec_v3_collaboration.md b/docs/spec_v3_collaboration.md new file mode 100644 index 0000000..0b292a0 --- /dev/null +++ b/docs/spec_v3_collaboration.md @@ -0,0 +1,203 @@ +# KingClawArmy - 第四部分：協作模式 + +--- + +## 4.1 三種協作模式 + +| 模式 | 實現方式 | 適用場景 | +|---|---|---| +| **Orchestrator（協調者）** | Paperclip 任務系統 | 大部分日常任務 | +| **Peer-to-Peer（點對點）** | Discord Thread 討論 | 辯論、腦力激盪、跨團隊對齊 | +| **Hierarchical（階層式）** | Paperclip Org Chart | 任務分派、升級、審批 | + +### 4.1.1 Orchestrator 模式（日常 80%） + +``` +董事長下達指令 + ↓ +CEO/COO 拆任務 → 建立 Paperclip Issue + ↓ +分派給對應 agent（指定 assignee） + ↓ +Agent 在 heartbeat 時接到任務 + ↓ +OpenClaw 執行任務 + ↓ +產出 JSON → 寫回 Paperclip Issue + ↓ +下一個 agent 接手（或送審） +``` + +### 4.1.2 Peer-to-Peer 模式（討論 15%） + +``` +CEO 或任一 agent 發起討論 + ↓ +建立 Discord Thread + ↓ +@mention 相關 agent 加入 + ↓ +多 agent 在 thread 中來回討論（最多 10 人、2-50 輪） + ↓ +達成結論或主持人收斂 + ↓ +秘書摘要 → 寫入 Mem0 + 回寫 Paperclip Issue +``` + +### 4.1.3 Hierarchical 模式（升級/審批 5%） + +``` +Agent 遇到超出權限的問題 + ↓ +設定 Issue 狀態為 blocked + 留言說明 + ↓ +CEO/COO 看到 → 決定： + ├── 轉派給其他 agent + ├── 發起討論 + └── 上報董事長（HITL） +``` + +--- + +## 4.2 什麼時候走任務交接 vs 開會議 + +| 情境 | 用哪種 | 理由 | +|---|---|---| +| 一個 agent 做完交給下一個 | 任務交接 | 線性流程，不需要討論 | +| 需要多方觀點碰撞 | 會議 | 例如多空辯論 | +| 審查 pass/revise 來回 | 任務交接 | 非同步 review 即可 | +| 審查 revise 超過 3 輪 | 會議 | 非同步效率太低，需要面對面對齊 | +| 跨團隊依賴 | 會議 | 需要共同理解 | +| 新 campaign 啟動 | 會議 | 需要多部門對齊方向 | +| 日常 KPI 報告 | 任務交接 | 固定格式，不需討論 | +| 回測結果異常 | 會議 | 需要多方分析原因 | + +--- + +## 4.3 預定義會議類型 + +### 4.3.1 量化研究辯論 + +| 項目 | 內容 | +|---|---| +| **會議 ID** | `meeting_quant_debate` | +| **觸發條件** | 多方/空方報告完成後，量化策略研究員覺得需要辯論 | +| **參與者** | 多方研究員、空方研究員、量化策略研究員 | +| **主持人** | 量化策略研究員 | +| **前置輸入** | Finance_Research_Brief + Market_Structure_Report + 雙方初步報告 | +| **發言規則** | LLM 動態選人，不允許連續發言 | +| **最大輪數** | 10 | +| **結束條件** | 出現 "CONSENSUS" 或達到最大輪數 | +| **輸出** | Meeting_Conclusion.json → 量化策略研究員據此產出 Quant_Strategy_Spec | + +### 4.3.2 策略審查會議 + +| 項目 | 內容 | +|---|---| +| **會議 ID** | `meeting_strategy_review` | +| **觸發條件** | 審查員 revise 超過 3 輪，或高風險產出 | +| **參與者** | 審查員 + 被審的 agent + CEO/COO | +| **主持人** | CEO/COO | +| **前置輸入** | 被審產出 + Review_Report（含 revise 歷史） | +| **發言規則** | 輪流發言 | +| **最大輪數** | 6 | +| **結束條件** | 審查員判定 PASS 或 BLOCK | +| **輸出** | Meeting_Conclusion.json + 更新後的 Review_Report | + +### 4.3.3 跨部門對齊會議 + +| 項目 | 內容 | +|---|---| +| **會議 ID** | `meeting_cross_team_sync` | +| **觸發條件** | CEO/COO 判斷需要跨團隊協調，或董事長要求 | +| **參與者** | CEO/COO + 相關團隊的 lead agent | +| **主持人** | CEO/COO | +| **前置輸入** | 各團隊最新產出摘要 | +| **發言規則** | LLM 動態選人 | +| **最大輪數** | 8 | +| **結束條件** | CEO/COO 宣布 "ALIGNED" | +| **輸出** | Meeting_Conclusion.json + 更新的 Task_Spec | + +### 4.3.4 盤前研究會議（每日） + +| 項目 | 內容 | +|---|---| +| **會議 ID** | `meeting_daily_premarket` | +| **觸發條件** | 每日定時（盤前），財經情報 + 市場結構報告完成後 | +| **參與者** | 財經情報研究員、市場結構研究員、多方研究員、空方研究員 | +| **主持人** | CEO/COO | +| **前置輸入** | 當日 Finance_Research_Brief + Market_Structure_Report | +| **發言規則** | 輪流發言 | +| **最大輪數** | 6 | +| **結束條件** | 各方表述完畢，CEO 摘要 | +| **輸出** | Meeting_Conclusion.json → 決定是否進入量化策略流程 | + +--- + +## 4.4 會議流程標準化 + +所有會議遵循以下流程： + +``` +1. 觸發 + ├── 自動觸發（排程/事件） + └── 手動觸發（CEO 或董事長建立 meeting issue） + +2. 準備 + ├── 蒐集前置資料（各參與者的最新產出） + ├── 載入會議模板（參與者、規則、最大輪數） + └── 在 Discord 建立 Thread + +3. 討論 + ├── 主持人開場（說明議題 + 目標） + ├── 各 agent 依發言規則輪流發言 + ├── 允許追問、反駁、補充 + └── 主持人在適當時機收斂 + +4. 結論 + ├── 主持人宣布結論 + ├── 秘書產出 Meeting_Summary + └── 結論寫入 Mem0 + Paperclip Issue + +5. 後續 + ├── 根據結論建立後續任務 + └── 分派給對應 agent +``` + +--- + +## 4.5 Review Gate（審查關卡） + +### 必審節點 + +| 節點 | 觸發條件 | 審查者 | +|---|---|---| +| 量化策略提交 | Quant_Strategy_Spec 完成 | 審查員 | +| 回測結果提交 | Backtest_Delivery 完成 | 審查員 | +| 工程交付 | Frontend/Backend Delivery 完成 | 審查員 | +| 文案/素材對外 | Copywriting_Pack / Creative Brief 完成 | 審查員 | +| 跨部門整合完成 | Final_Decision_Packet 組裝完成 | 審查員 | + +### HITL 節點（需要你親自批准） + +| 節點 | 原因 | +|---|---| +| 正式環境部署前 | 高風險 | +| 資料庫 schema 變更前 | 高風險 | +| 廣告正式發布前 | 涉及預算與品牌 | +| 對外正式訊息發送前 | 涉及品牌與客戶 | +| 涉及金流操作前 | 高風險 | +| 量化策略正式自動執行前 | 高風險 | +| 月預算超額 | 成本控制 | + +HITL 流程： +``` +Agent 完成任務 → 審查員 pass → 系統偵測到 HITL 節點 + ↓ +Discord #approvals 發送通知 + ↓ +你看到通知 → /clip approve 或 /clip reject + ↓ +approve → 繼續執行 +reject → 退回修改，附上你的意見 +``` diff --git a/docs/spec_v3_org_and_roles.md b/docs/spec_v3_org_and_roles.md new file mode 100644 index 0000000..ee13535 --- /dev/null +++ b/docs/spec_v3_org_and_roles.md @@ -0,0 +1,399 @@ +# KingClawArmy - 第二部分：組織架構 & 第三部分：角色定義 + +--- + +## 第二部分：組織架構 + +### 2.1 團隊結構 + +``` +董事長（你，人類） +│ +├── 管理團隊 (3 agents) +│ ├── CEO/COO +│ ├── 秘書 +│ └── 審查員 +│ +├── 量化研究團隊 (7 agents) +│ ├── 財經情報研究員 +│ ├── 市場結構研究員 +│ ├── 多方研究員 +│ ├── 空方研究員 +│ ├── 量化策略研究員（含風控） +│ ├── 回測工程師 +│ └── 資料分析員 +│ +├── 行銷策略團隊 (3 agents) +│ ├── 市場研究員 +│ ├── 策略總監 +│ └── 投放成效分析師 +│ +├── 內容創意團隊 (2 agents) +│ ├── 文案撰寫員 +│ └── 創意總監 +│ +└── 工程團隊 (0~2 agents，依需求啟用) + ├── 前端工程師 + └── 後端工程師 +``` + +**總計：15 ~ 17 agents** + +### 2.2 彙報關係（Paperclip Org Chart） + +``` + CEO/COO + ┌───┴────────────────────┐ + │ │ + ┌───────┴───────┐ ┌─────┴─────┐ + │ 秘書 │ │ 審查員 │ + └───────────────┘ └───────────┘ + │ + ┌────────────┼────────────┬──────────────┐ + │ │ │ │ + 量化研究團隊 行銷策略團隊 內容創意團隊 工程團隊 + ┌─────┴────┐ ┌───┴───┐ ┌──┴──┐ ┌──┴──┐ + │財經情報 │ │市場研究│ │文案 │ │前端 │ + │市場結構 │ │策略總監│ │創意 │ │後端 │ + │多方研究 │ │投放分析│ └─────┘ └─────┘ + │空方研究 │ └───────┘ + │量化策略 │ + │回測工程 │ + │資料分析 │ + └─────────┘ +``` + +所有 agent 直接向 CEO/COO 彙報。秘書和審查員是 CEO/COO 的幕僚，不直接管理其他 agent。 + +### 2.3 狀態分類 + +| 狀態 | 說明 | 角色 | +|---|---|---| +| **常駐** | 每次 heartbeat 都啟動 | CEO/COO、秘書 | +| **Warm** | 高頻喚醒，快速回應 | 審查員 | +| **喚醒** | 依排程或事件觸發才啟動 | 其餘所有 agent | + +--- + +## 第三部分：角色定義 + +> 所有 agent 使用 **OpenClaw** 作為 adapter +> 模型等級為建議值，實際部署時依可用模型選擇 + +### 3.0 模型等級分類 + +| 等級 | 說明 | 適用模型舉例 | +|---|---|---| +| **reasoning-heavy** | 需要深度推理、策略收斂、審查判斷 | Claude Opus, GPT-4o, DeepSeek-V3 | +| **general** | 通用任務管理、摘要、整理 | Claude Sonnet, GPT-4o-mini, Qwen | +| **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** | 接收董事長指令，拆解任務，分派給對應 agent，追蹤進度，收斂結果，組裝決策包 | +| **Scope** | 建立/分派任務、讀取所有 agent 產出、跨團隊協調、發起會議、組裝 Final Decision Packet | +| **Forbidden** | 不直接寫文案、不直接寫程式、不直接部署、不直接做研究 | +| **輸出** | Task_Spec.json, Final_Decision_Packet.json | +| **工具權限** | Paperclip 任務 API（建立/分派/更新）、Discord 討論發起、Mem0 讀取 | +| **Escalation** | 高風險決策、預算超額、agent 反覆 revise 超過 3 輪 → 上報董事長 | + +#### 秘書（記憶與狀態管理） + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `secretary` | +| **團隊** | 管理團隊 | +| **上級** | CEO/COO | +| **模型等級** | general | +| **狀態** | 常駐 | +| **Mission** | 記錄會議摘要、追蹤狀態變更、維護 Todo、壓縮/整理記憶 | +| **Scope** | 讀寫 Mem0 記憶、產出 State Diff、產出會議摘要、維護 Todo List | +| **Forbidden** | 不做策略決策、不分派任務 | +| **輸出** | Meeting_Summary.json, State_Diff.json, Todo_List.json | +| **工具權限** | Mem0 讀寫、Paperclip issue 讀取、Discord 訊息讀取 | +| **Escalation** | 記憶衝突、狀態不一致 → 上報 CEO/COO | + +#### 審查員（品質把關） + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `reviewer` | +| **團隊** | 管理團隊 | +| **上級** | CEO/COO | +| **模型等級** | reasoning-heavy | +| **狀態** | warm | +| **Mission** | 審查各 agent 產出品質，判定 pass / revise / block | +| **Scope** | 唯讀檢查所有 agent 輸出、提出修改建議、風險攔截 | +| **Forbidden** | 不重寫全部內容、不直接拍板決策、不直接修改他人產出 | +| **輸出** | Review_Report.json | +| **工具權限** | 所有 agent 輸出唯讀、Paperclip issue 讀取/留言 | +| **Escalation** | block 判定 → 上報 CEO/COO → 可能上報董事長 | + +--- + +### 3.2 量化研究團隊 + +#### 財經情報研究員 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `finance_researcher` | +| **團隊** | 量化研究團隊 | +| **上級** | CEO/COO | +| **模型等級** | research | +| **狀態** | 喚醒（每日定時 + 事件觸發） | +| **Mission** | 蒐集財經、總經、盤前盤後資訊，整理成結構化報告 | +| **Scope** | 網路搜尋、資料爬取、資訊清洗去重、產出研究摘要 | +| **Forbidden** | 不下交易結論、不做策略判斷 | +| **輸出** | Finance_Research_Brief.json | +| **工具權限** | 網路搜尋、爬蟲、資料清洗 | +| **Escalation** | 資料來源衝突、異常市場事件 → 上報 CEO/COO | + +#### 市場結構研究員 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `market_structure_researcher` | +| **團隊** | 量化研究團隊 | +| **上級** | CEO/COO | +| **模型等級** | reasoning-heavy | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 解析流動性、市場結構、掃單、MSS、OB、FVG、POI | +| **Scope** | 讀取行情資料、結構分析、圖表解讀、產出結構報告 | +| **Forbidden** | 不直接下最終交易結論 | +| **輸出** | Market_Structure_Report.json | +| **工具權限** | 行情資料 API、結構分析工具、圖表讀取 | +| **Escalation** | 結構不明確、多重矛盾信號 → 標註不確定度 | + +#### 多方研究員 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `bullish_researcher` | +| **團隊** | 量化研究團隊 | +| **上級** | CEO/COO | +| **模型等級** | reasoning-heavy | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 專門整理支持交易 / 做多的論點，建立完整的多方論述 | +| **Scope** | 讀取研究報告與結構報告，提出做多理由、支撐證據、預期優勢 | +| **Forbidden** | 不直接拍板、不做空方論述 | +| **輸出** | Bullish_Research_Report.json | +| **工具權限** | 唯讀研究報告、結構報告 | +| **Escalation** | 找不到足夠支持做多的證據 → 如實報告 | + +#### 空方研究員 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `bearish_researcher` | +| **團隊** | 量化研究團隊 | +| **上級** | CEO/COO | +| **模型等級** | reasoning-heavy | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 專門整理反對交易 / 做空 / 放棄交易的論點 | +| **Scope** | 讀取研究報告與結構報告，提出風險警告、做空理由、放棄交易的原因 | +| **Forbidden** | 不直接拍板、不做多方論述 | +| **輸出** | Bearish_Research_Report.json | +| **工具權限** | 唯讀研究報告、結構報告 | +| **Escalation** | 發現重大風險 → 標記 high severity | + +#### 量化策略研究員（含風控） + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `quant_strategist` | +| **團隊** | 量化研究團隊 | +| **上級** | CEO/COO | +| **模型等級** | reasoning-heavy | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 收斂多空觀點形成正式策略規則，含進場/出場規則、風控規則、position sizing、bias check | +| **Scope** | 讀取多方/空方報告，定義進場/出場條件，設計風控框架，執行 bias check | +| **Forbidden** | 不寫正式程式碼、不直接執行交易 | +| **輸出** | Quant_Strategy_Spec.json（含 Risk_Control 欄位） | +| **工具權限** | 唯讀所有研究報告、策略規格工具 | +| **Escalation** | 多空觀點嚴重衝突無法收斂 → 發起 Discord 辯論會議 | + +#### 回測工程師 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `quant_engineer` | +| **團隊** | 量化研究團隊 | +| **上級** | CEO/COO | +| **模型等級** | coder | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 將策略規則轉成 Pine Script / Python 回測，接資料，產出回測結果 | +| **Scope** | 讀取策略規格、撰寫回測程式碼、執行回測、輸出結果 | +| **Forbidden** | 不自行更改策略方向、不自行做最終績效結論 | +| **輸出** | Backtest_Delivery.json | +| **工具權限** | Git repo、回測框架、歷史資料、sandbox 執行環境 | +| **Escalation** | 策略規格不完整或有矛盾 → 回報量化策略研究員 | + +#### 資料分析員 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `data_analyst` | +| **團隊** | 量化研究團隊 | +| **上級** | CEO/COO | +| **模型等級** | reasoning-heavy（深度分析）/ general（日常） | +| **狀態** | 喚醒（每日定時 + 事件觸發） | +| **Mission** | 分析回測結果，計算 KPI（expectancy、drawdown、winrate），提供洞察與建議 | +| **Scope** | SQL 查詢、回測結果分析、KPI 計算、視覺化、週報產出 | +| **Forbidden** | 不自行定策略方向 | +| **輸出** | Data_Analysis_Report.json | +| **工具權限** | SQL、回測資料讀取、圖表工具 | +| **Escalation** | 回測結果異常（如 winrate > 90% 可能 overfitting） → 標記 bias warning | + +--- + +### 3.3 行銷策略團隊 + +#### 市場研究員（情報 + 分析） + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `market_researcher` | +| **團隊** | 行銷策略團隊 | +| **上級** | CEO/COO | +| **模型等級** | research | +| **狀態** | 喚醒（每日 + 每週定時） | +| **Mission** | 蒐集競品、消費者痛點、平台趨勢；分析市場變化與競品反應 | +| **Scope** | 網路搜尋、競品追蹤、趨勢分析、消費者洞察、週報產出 | +| **Forbidden** | 不下最終商業策略結論、不盯每日廣告 KPI | +| **輸出** | Market_Research_Brief.json, Market_Analysis_Report.json | +| **工具權限** | 網路搜尋、爬蟲、資料清洗 | +| **Escalation** | 市場劇烈變化 → 即時通報 CEO/COO | + +#### 策略總監（品牌 + 成長） + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `strategy_director` | +| **團隊** | 行銷策略團隊 | +| **上級** | CEO/COO | +| **模型等級** | reasoning-heavy | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 定義 USP、目標受眾、品牌敘事、campaign 方向、漏斗策略、轉換策略 | +| **Scope** | 品牌定位、成長策略、campaign 規劃、漏斗設計 | +| **Forbidden** | 不直接寫最終文案、不寫底層 SQL | +| **輸出** | Brand_Strategy_Plan.json, Growth_Strategy_Plan.json | +| **工具權限** | 品牌知識庫、市場研究摘要、策略知識庫 | +| **Escalation** | 品牌方向重大調整 → 上報董事長 | + +#### 投放成效分析師 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `ads_analyst` | +| **團隊** | 行銷策略團隊 | +| **上級** | CEO/COO | +| **模型等級** | general | +| **狀態** | 喚醒（每日定時） | +| **Mission** | 分析 CTR / CVR / CPL / ROAS，診斷投放問題，提出優化建議 | +| **Scope** | 廣告 KPI 監控、診斷分析、優化建議、異常警報 | +| **Forbidden** | 不做品牌定位、不定策略方向 | +| **輸出** | Ads_Performance_Report.json | +| **工具權限** | 廣告平台資料 API、KPI 儀表板 | +| **Escalation** | ROAS 急降、預算異常消耗 → 即時警報 | + +--- + +### 3.4 內容創意團隊 + +#### 文案撰寫員（廣告 + 腳本） + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `copywriter` | +| **團隊** | 內容創意團隊 | +| **上級** | CEO/COO | +| **模型等級** | creative | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 撰寫廣告文案（Hook、Body、CTA、版本矩陣）及影片腳本（旁白、節奏、鏡頭腳本） | +| **Scope** | 廣告文案撰寫、影片腳本撰寫、A/B 版本產出 | +| **Forbidden** | 不改整體策略方向 | +| **輸出** | Copywriting_Pack.json, Video_Script_Pack.json | +| **工具權限** | 品牌語氣庫、文案資料庫 | +| **Escalation** | 品牌語氣不確定 → 詢問策略總監 | + +#### 創意總監（平面 + 影片視覺方向） + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `creative_director` | +| **團隊** | 內容創意團隊 | +| **上級** | CEO/COO | +| **模型等級** | creative | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 制定平面素材 brief 與影片分鏡 brief，確保視覺一致性與品牌規範 | +| **Scope** | 圖像方向指導、平面素材 QA、分鏡結構設計、影片視覺 QA | +| **Forbidden** | 不直接做最終素材（交由人類設計師或 AI 圖像工具） | +| **輸出** | Static_Creative_Brief.json, Storyboard_Brief.json | +| **工具權限** | 素材規格庫、品牌規範、VL 任務工具（如有視覺模型） | +| **Escalation** | 視覺方向與品牌衝突 → 詢問策略總監 | + +--- + +### 3.5 工程團隊（依需求啟用） + +#### 前端工程師 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `frontend_engineer` | +| **團隊** | 工程團隊 | +| **上級** | CEO/COO | +| **模型等級** | coder | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | 前端頁面開發、UI 互動、追蹤埋點 | +| **Scope** | 前端程式碼撰寫、build、tracking 測試 | +| **Forbidden** | 不決定商業策略、不修改 DB schema | +| **輸出** | Frontend_Delivery.json | +| **工具權限** | Git repo、前端 build 工具、sandbox | +| **Escalation** | 技術選型不確定 → 討論；部署前 → 必審 | + +#### 後端工程師 + +| 項目 | 內容 | +|---|---| +| **Agent ID** | `backend_engineer` | +| **團隊** | 工程團隊 | +| **上級** | CEO/COO | +| **模型等級** | coder | +| **狀態** | 喚醒（事件觸發） | +| **Mission** | API 開發、資料庫設計、自動化整合 | +| **Scope** | API/DB 開發、sandbox 測試 | +| **Forbidden** | 不寫廣告文案、正式發布需通過 gate | +| **輸出** | Backend_Delivery.json | +| **工具權限** | Git repo、API 框架、DB sandbox | +| **Escalation** | DB schema 變更 → 必須 HITL 批准 | + +--- + +### 3.6 OpenClaw 共用 Prompt 結尾 + +所有 agent 的 system prompt 結尾附加： + +```text +You must only operate within your assigned role boundary. +Do not perform work outside your scope. +If required information is missing, explicitly return the missing_fields list. +If there is conflict, uncertainty, or high risk, escalate instead of guessing. +Your output must follow the required JSON schema exactly. +Do not add extra commentary outside the JSON payload. +When participating in Discord discussions, stay in character and contribute from your role's perspective. +``` diff --git a/docs/spec_v3_rollout_and_risks.md b/docs/spec_v3_rollout_and_risks.md new file mode 100644 index 0000000..c4ef595 --- /dev/null +++ b/docs/spec_v3_rollout_and_risks.md @@ -0,0 +1,187 @@ +# KingClawArmy - 第九部分：上線計畫 & 第十部分：風險與限制 + +--- + +## 第九部分：上線計畫 + +### 9.1 總覽 + +| Phase | 目標 | 上線角色 | 驗收標準 | +|---|---|---|---| +| 0 | 基礎設施 | 無 agent | 環境可用 | +| 1 | 管理閉環 | 3 agents | CEO 能派工、秘書能記錄、審查能審核 | +| 2 | 量化閉環 | +7 agents | 從情報到回測的完整 pipeline 跑通 | +| 3 | 行銷閉環 | +3 agents | 市場研究 → 策略 → KPI 追蹤跑通 | +| 4 | 內容閉環 | +2 agents | 文案 + 創意 brief 產出跑通 | +| 5 | 工程（依需求） | +0~2 agents | 前後端任務可執行 | +| 6 | 營運化 | 全體 | 完整排程、HITL、監控、成本控制 | + +--- + +### 9.2 Phase 0：基礎設施建置 + +**目標：** 讓所有基礎工具可用 + +| 步驟 | 動作 | 驗收 | +|---|---|---| +| 0.1 | 安裝並啟動 Paperclip（Node.js + PostgreSQL） | Dashboard 可開啟 | +| 0.2 | 安裝 OpenClaw，設定至少一個 AI model API | OpenClaw 能回應 | +| 0.3 | 建立 Discord Server，建立頻道結構 | 頻道都在 | +| 0.4 | 安裝 paperclip-plugin-discord，連接 Discord Bot | Bot 在 Discord 上線 | +| 0.5 | 安裝並設定 Mem0（self-host 或 cloud） | Mem0 API 可呼叫 | +| 0.6 | 在 Paperclip 建立公司，設定 OpenClaw adapter | 公司建立成功 | + +--- + +### 9.3 Phase 1：管理閉環 + +**目標：** CEO 派工 → Agent 執行 → 秘書記錄 → 審查員審核，完整跑通 + +**上線角色：** CEO/COO、秘書、審查員 + +| 步驟 | 動作 | 驗收 | +|---|---|---| +| 1.1 | 在 Paperclip 建立 CEO/COO agent（OpenClaw adapter） | Agent 出現在 org chart | +| 1.2 | 設定 CEO 的 system prompt + heartbeat | CEO heartbeat 正常觸發 | +| 1.3 | 手動建立一個測試任務給 CEO | CEO 能接到任務並回應 | +| 1.4 | 加入秘書 agent | 秘書能讀取 CEO 產出並做摘要 | +| 1.5 | 加入審查員 agent | 審查員能審核產出，回傳 pass/revise | +| 1.6 | 測試完整流程：任務 → CEO 拆 → 秘書記錄 → 審查 | 三個 agent 能協作完成一個任務 | +| 1.7 | 測試 Discord 通知 | 任務狀態變更推送到 Discord | +| 1.8 | 測試 HITL | #approvals 收到通知，你能 approve | + +**Phase 1 完成標準：** +- [ ] CEO 能接收指令、拆任務 +- [ ] 秘書能產出 Meeting_Summary 和 State_Diff +- [ ] 審查員能產出 Review_Report（pass/revise/block） +- [ ] Discord 通知正常 +- [ ] HITL 審批正常 +- [ ] Mem0 記憶寫入/讀取正常 + +--- + +### 9.4 Phase 2：量化研究閉環 + +**目標：** 完整量化 pipeline，從情報蒐集到回測分析 + +**上線角色：** 財經情報、市場結構、多方、空方、量化策略、回測工程、資料分析 + +| 步驟 | 動作 | 驗收 | +|---|---|---| +| 2.1 | 加入財經情報研究員，設定每日排程 | 每日自動產出 Finance_Research_Brief | +| 2.2 | 加入市場結構研究員，設定事件觸發 | 情報完成後自動觸發結構分析 | +| 2.3 | 加入多方 + 空方研究員 | 結構報告完成後，兩者平行產出報告 | +| 2.4 | 加入量化策略研究員 | 能收斂多空觀點成 Quant_Strategy_Spec | +| 2.5 | 測試 Discord 辯論功能 | 多空在 thread 中討論，量化策略主持 | +| 2.6 | 加入回測工程師 | 能讀取策略規格，產出回測結果 | +| 2.7 | 加入資料分析員 | 能分析回測結果，產出報告 | +| 2.8 | 跑一次完整 pipeline | 從盤前情報到最終分析報告完整跑通 | +| 2.9 | 審查員 review 整個 pipeline | 通過 gate 才算完成 | + +**Phase 2 完成標準：** +- [ ] 量化 pipeline 端對端跑通 +- [ ] 事件觸發鏈正常（一個完成自動觸發下一個） +- [ ] Discord 辯論能產出有意義的結論 +- [ ] 審查機制正常運作 +- [ ] 每日定時排程正常 + +--- + +### 9.5 Phase 3：行銷閉環 + +**上線角色：** 市場研究員、策略總監、投放成效分析師 + +| 步驟 | 動作 | 驗收 | +|---|---|---| +| 3.1 | 加入市場研究員 | 每日/每週自動產出市場研究 | +| 3.2 | 加入策略總監 | 能根據市場研究產出品牌/成長策略 | +| 3.3 | 加入投放成效分析師 | 每日自動產出 KPI 報告 | +| 3.4 | 測試跨部門對齊會議 | 量化 + 行銷團隊在 Discord 討論 | + +--- + +### 9.6 Phase 4：內容閉環 + +**上線角色：** 文案撰寫員、創意總監 + +| 步驟 | 動作 | 驗收 | +|---|---|---| +| 4.1 | 加入文案撰寫員 | 能根據策略產出文案 | +| 4.2 | 加入創意總監 | 能產出視覺 brief | +| 4.3 | 內容審查流程 | 審查員 review 文案與 brief | + +--- + +### 9.7 Phase 5-6：工程 & 營運化 + +**Phase 5（依需求）：** 加入前端/後端工程師 + +**Phase 6（營運化）：** +- 完整排程矩陣上線 +- 所有 HITL 節點確認 +- 預算監控啟用 +- 每日/每週自動報告穩定 +- 異常告警機制驗證 + +--- + +## 第十部分：風險與限制 + +### 10.1 已知技術限制 + +| 限制 | 影響 | 緩解方式 | +|---|---|---| +| Discord plugin 為社群開發 | 可能缺少官方支援 | 追蹤 repo 更新、準備自行 fork 維護 | +| Discord thread 最多 10 agents | 大型會議受限 | 拆成小組討論再彙總 | +| Discord 討論為 2-50 輪 | 超長辯論不適合 | 設定合理 max_rounds，分多次會議 | +| OpenClaw 曾有安全漏洞（CVE-2026-25253） | RCE 風險 | 保持更新、啟用認證、監控安全公告 | +| Mem0 記憶可能過時 | Agent 根據過時資訊決策 | 秘書每日壓縮、設定 TTL、定期清理 | +| AI 模型幻覺 | 產出不正確的資訊 | 審查員把關、交叉驗證、人類最終審核 | + +### 10.2 成本估算框架 + +| 項目 | 計算方式 | 控制手段 | +|---|---|---| +| AI API 費用 | per-agent 月預算 × agent 數 | Paperclip budget 功能 | +| 每次 heartbeat 的 token | 依模型和任務複雜度 | 選擇合適的模型等級 | +| 每次會議的 token | 參與人數 × 輪數 × 平均回覆長度 | 限制 max_rounds | +| 記憶讀寫的 token | Mem0 的 embedding + retrieval | 控制記憶大小、壓縮頻率 | + +**成本控制建議：** +- 日常研究類用 research 等級模型（便宜） +- 只有策略收斂、審查、辯論用 reasoning-heavy（貴但值得） +- 設定 per-agent 月預算上限，超額需 HITL 批准 +- 會議不要超過 10 輪，大部分 6 輪即可收斂 + +### 10.3 安全注意事項 + +| 項目 | 風險 | 措施 | +|---|---|---| +| API Key 管理 | 洩露導致費用爆增 | 使用環境變數、不進版本控制 | +| Agent 權限 | Agent 做超出範圍的事 | 嚴格的 Forbidden 規則 + 工具白名單 | +| 交易執行 | AI 自動下單造成損失 | HITL 必審 + 策略必須先通過完整 pipeline | +| 資料安全 | 敏感資訊外洩 | 不在 prompt 中放敏感資料、記憶加密 | +| Discord 安全 | 未授權存取 | Server 設為私人、Bot 只在指定頻道運作 | + +### 10.4 什麼時候該停下來 + +| 信號 | 動作 | +|---|---| +| 月費用超出預期 2 倍 | 暫停非必要 agent，分析原因 | +| Agent 反覆 revise 超過 5 輪收斂不了 | 人工介入，可能需要調整 prompt 或流程 | +| 回測結果看起來太好（winrate > 90%） | 100% 是 overfitting，停止並重新檢查 | +| Agent 產出的品質持續下降 | 檢查記憶是否過時、prompt 是否需要更新 | +| 安全漏洞通報 | 立即更新或暫停受影響元件 | + +--- + +## 附錄：文件索引 + +| 文件 | 內容 | +|---|---| +| `spec_v3_system_overview.md` | 第一部分：系統總覽 | +| `spec_v3_org_and_roles.md` | 第二部分：組織架構 + 第三部分：角色定義 | +| `spec_v3_collaboration.md` | 第四部分：協作模式 | +| `spec_v3_scheduling_memory_discord.md` | 第五部分：排程 + 第六部分：記憶 + 第七部分：Discord | +| `spec_v3_schemas.md` | 第八部分：JSON Schema | +| `spec_v3_rollout_and_risks.md` | 第九部分：上線計畫 + 第十部分：風險與限制 | diff --git a/docs/spec_v3_scheduling_memory_discord.md b/docs/spec_v3_scheduling_memory_discord.md new file mode 100644 index 0000000..f4136cf --- /dev/null +++ b/docs/spec_v3_scheduling_memory_discord.md @@ -0,0 +1,194 @@ +# KingClawArmy - 第五部分：排程與觸發 & 第六部分：記憶架構 & 第七部分：Discord Server 結構 + +--- + +## 第五部分：排程與觸發 + +### 5.1 Heartbeat 排程表（定時觸發） + +| Agent | 頻率 | 時間 | 說明 | +|---|---|---|---| +| CEO/COO | 每次 heartbeat | 依 Paperclip 設定（建議 15-30 分鐘） | 常駐，檢查新任務/回報 | +| 秘書 | 每次 heartbeat | 與 CEO 同步 | 常駐，維護狀態與記憶 | +| 財經情報研究員 | 每日 2 次 | 07:30（盤前）、18:30（盤後） | 固定蒐集財經資訊 | +| 市場研究員 | 每日 1 次 + 每週 1 次 | 每日 10:00、每週一 09:00 | 日常情報 + 週報 | +| 投放成效分析師 | 每日 1 次 | 09:30 | 日常 KPI 檢查 | +| 資料分析員 | 每日 1 次 + 每週 1 次 | 每日 20:00、每週一 10:00 | 日報 + 週報 | +| 秘書（壓縮） | 每日 1 次 | 23:00 | 每日記憶壓縮與 State Diff | + +### 5.2 事件觸發表 + +| 事件 | 觸發的 Agent | 說明 | +|---|---|---| +| 董事長下達新指令 | CEO/COO | 透過 Discord 或 Paperclip UI | +| CEO 分派任務 | 被分派的 agent | Paperclip Issue assign | +| 財經情報 + 市場數據齊備 | 市場結構研究員 | 開始結構分析 | +| 市場結構報告完成 | 多方研究員、空方研究員 | 同時觸發，平行執行 | +| 多方 + 空方報告完成 | 量化策略研究員 | 收斂觀點 | +| 量化策略完成 | 回測工程師 | 落地回測 | +| 回測完成 | 資料分析員 | 分析回測結果 | +| 資料分析完成 | 秘書 | 摘要 + State Diff | +| 任何草稿完成 | 審查員 | 審查品質 | +| 審查 revise | 被 revise 的 agent | 修改後重新提交 | +| 審查 pass（HITL 節點） | Discord #approvals | 等待董事長批准 | +| 審查 revise 超過 3 輪 | CEO/COO | 考慮發起會議 | +| 品牌策略完成 | 文案撰寫員、創意總監 | 開始內容產出 | +| 成長策略完成 | 投放成效分析師 | 準備追蹤 KPI | +| Agent 設定 blocked | CEO/COO | 處理阻塞 | +| 預算超額 | Discord #approvals | HITL 通知 | + +### 5.3 量化研究主流程（事件鏈） + +``` +[定時 07:30] + ↓ +財經情報研究員 → Finance_Research_Brief + ↓ [完成事件] +市場結構研究員 → Market_Structure_Report + ↓ [完成事件] +┌──────────────┐ +│ 多方研究員 │ → Bullish_Research_Report ─┐ +│ 空方研究員 │ → Bearish_Research_Report ─┤ [平行執行] +└──────────────┘ │ + ↓ [兩者都完成] │ +量化策略研究員 ←──────────────────────────────┘ + │ + ├── [如需辯論] → 發起 meeting_quant_debate（Discord） + │ ↓ + │ 辯論結論 + │ ↓ + └── → Quant_Strategy_Spec + ↓ [完成事件] +回測工程師 → Backtest_Delivery + ↓ [完成事件] +資料分析員 → Data_Analysis_Report + ↓ [完成事件] +秘書 → Meeting_Summary + State_Diff + ↓ +審查員 → Review_Report + ↓ + ├── pass → CEO 組 Final_Decision_Packet → HITL 董事長批准 + └── revise → 回退到被點名角色 +``` + +--- + +## 第六部分：記憶架構 + +### 6.1 Mem0 記憶分類 + +| 記憶類型 | 範圍 | 存取者 | 說明 | +|---|---|---|---| +| **共享決策記憶** | 全團隊 | 所有 agent | 董事長決策、重大方向變更、已定的策略 | +| **團隊工作記憶** | 團隊內 | 團隊成員 | 進行中的研究脈絡、累積的分析結果 | +| **會議記憶** | 參與者 | 會議參與者 + 秘書 | 會議結論、共識、待辦 | +| **個別工作記憶** | 個人 | 該 agent 本身 | 個人工作脈絡、偏好、學到的經驗 | +| **品牌知識庫** | 行銷+內容團隊 | 策略總監、文案、創意 | USP、語氣、品牌規範 | +| **策略規則庫** | 量化團隊 | 量化相關 agent | 已驗證的策略規則、回測結果 | + +### 6.2 記憶寫入規則 + +| 事件 | 寫入什麼 | 誰寫入 | +|---|---|---| +| 會議結束 | Meeting_Summary → 會議記憶 | 秘書 | +| 董事長做決策 | 決策內容 + 理由 → 共享決策記憶 | 秘書 | +| 策略規則定稿 | Quant_Strategy_Spec → 策略規則庫 | 秘書 | +| 回測完成 | 回測結果摘要 → 策略規則庫 | 秘書 | +| 品牌方向更新 | Brand_Strategy_Plan → 品牌知識庫 | 秘書 | +| 每日壓縮 | 當日所有產出摘要 → 團隊工作記憶 | 秘書 | +| Agent 學到新經驗 | 經驗描述 → 個別工作記憶 | 該 agent | + +### 6.3 記憶讀取規則 + +| Agent 做任務時 | 自動帶入的記憶 | +|---|---| +| 量化策略研究員開始收斂 | 策略規則庫（過去的策略 + 結果）+ 最近的會議記憶 | +| 文案撰寫員寫文案 | 品牌知識庫 + 策略總監最新方向 | +| CEO 拆任務 | 共享決策記憶 + 所有團隊工作記憶摘要 | +| 審查員審查 | 過去同類產出的 Review 記錄 + 改善歷史 | + +### 6.4 記憶生命週期 + +| 記憶類型 | 保留期限 | 清理方式 | +|---|---|---| +| 共享決策記憶 | 永久（除非被新決策覆蓋） | 手動或被新決策取代 | +| 團隊工作記憶 | 30 天滾動 | 秘書每日壓縮，超過 30 天自動摘要 | +| 會議記憶 | 90 天 | 超過 90 天壓縮成重點摘要 | +| 個別工作記憶 | 由 agent 自行管理 | Mem0 的遺忘曲線機制 | +| 品牌知識庫 | 永久（除非品牌重塑） | 策略總監更新時覆蓋 | +| 策略規則庫 | 永久（標記已驗證/已廢棄） | 不刪除，標記狀態 | + +--- + +## 第七部分：Discord Server 結構 + +### 7.1 頻道規劃 + +``` +KingClawArmy Discord Server +│ +├── 📋 管理區 +│ ├── #dashboard — 系統狀態總覽、每日摘要 +│ ├── #approvals — HITL 審批請求（你在這裡批准/退回） +│ ├── #commands — 管理指令操作區 +│ └── #errors — 錯誤與異常通知 +│ +├── 📊 量化研究區 +│ ├── #quant-briefing — 每日盤前/盤後情報摘要 +│ ├── #quant-discussion — 量化團隊討論（辯論在 thread 中進行） +│ └── #quant-results — 回測結果、策略定稿通知 +│ +├── 📈 行銷區 +│ ├── #marketing-intel — 市場情報、競品動態 +│ ├── #marketing-discussion — 行銷策略討論 +│ └── #ads-performance — 每日投放 KPI 報告 +│ +├── ✏️ 內容區 +│ ├── #content-briefs — 文案/創意 brief 發布 +│ └── #content-review — 內容審查與回饋 +│ +├── 🔧 工程區（依需求開啟） +│ ├── #engineering-tasks — 工程任務通知 +│ └── #engineering-review — 工程審查 +│ +└── 📝 記錄區 + ├── #meeting-logs — 所有會議紀錄存檔 + ├── #decision-log — 重大決策記錄 + └── #audit-trail — 完整操作軌跡 +``` + +### 7.2 Discord Slash Commands + +| 指令 | 功能 | 你會用到的場景 | +|---|---|---| +| `/clip agents` | 列出所有 agent 狀態 | 看誰在跑、誰閒著 | +| `/clip status` | 系統總覽 | 快速了解現況 | +| `/clip budget ` | 查看 agent 預算 | 成本控制 | +| `/clip issues` | 查看任務列表 | 追蹤進度 | +| `/clip approve ` | 批准 HITL 請求 | 高風險動作放行 | +| `/clip reject ` | 退回 HITL 請求 | 附上修改意見 | +| `/acp spawn agent: task:` | 手動啟動 agent | 臨時指派任務 | +| `/acp cancel session:` | 停止 agent | 緊急停止 | + +### 7.3 通知規則 + +| 事件 | 推送到 | 格式 | +|---|---|---| +| Agent 完成任務 | 對應區域頻道 | embed 摘要 | +| 審查 pass | #approvals（如 HITL） | embed + approve 按鈕 | +| 審查 revise | 對應區域頻道 | embed + revise 原因 | +| 審查 block | #errors + #approvals | 高優先通知 | +| 會議開始 | 對應區域頻道 | thread 自動建立 | +| 會議結束 | #meeting-logs | 會議摘要 embed | +| 每日摘要 | #dashboard | 今日完成/進行中/blocked | +| 錯誤/異常 | #errors | 錯誤詳情 + 建議處理方式 | +| 預算警告 | #approvals | 剩餘預算百分比 | + +### 7.4 Thread 使用規範 + +| 類型 | Thread 建立位置 | 參與者 | 結束後 | +|---|---|---|---| +| 量化辯論 | #quant-discussion | 多空+策略+風控 | 存檔到 #meeting-logs | +| 策略審查 | 對應區域頻道 | 審查員+被審者+CEO | 結論更新到 issue | +| 跨部門對齊 | #dashboard | CEO + 各團隊 lead | 存檔到 #meeting-logs | +| 臨時討論 | 任何頻道 | 由發起者決定 | 秘書摘要存檔 | diff --git a/docs/spec_v3_schemas.md b/docs/spec_v3_schemas.md new file mode 100644 index 0000000..4c99be7 --- /dev/null +++ b/docs/spec_v3_schemas.md @@ -0,0 +1,412 @@ +# KingClawArmy - 第八部分：JSON Schema + +> 基於 v2 schema 更新，新增會議相關 schema +> 所有 schema 只保留格式模板，不放假資料 + +--- + +## 8.1 共用欄位 + +```json +{ + "task_id": "", + "project_id": "", + "agent_id": "", + "role": "", + "timestamp": "", + "status": "", + "input_version": "" +} +``` + +--- + +## 8.2 管理層 Schema + +### Task_Spec.json（CEO/COO 產出） +```json +{ + "task_id": "", + "project_id": "", + "agent_id": "ceo_coo", + "role": "ceo_coo", + "timestamp": "", + "status": "", + "goal": "", + "success_criteria": [""], + "routes": [ + { + "agent_id": "", + "subtask": "", + "required_output": "", + "collaboration_mode": "" + } + ], + "priority": "", + "meeting_required": "", + "meeting_type": "", + "notes": [""] +} +``` + +### Final_Decision_Packet.json（CEO/COO 產出） +```json +{ + "task_id": "", + "project_id": "", + "agent_id": "ceo_coo", + "timestamp": "", + "status": "done", + "summary": "", + "options": [ + { + "name": "", + "description": "", + "pros": [""], + "cons": [""], + "risk_level": "" + } + ], + "recommended_option": "", + "review_verdict": "", + "meeting_conclusions": [""], + "decision_needed": [""] +} +``` + +### Meeting_Summary.json（秘書產出） +```json +{ + "task_id": "", + "project_id": "", + "agent_id": "secretary", + "timestamp": "", + "meeting_type": "", + "topic": "", + "participants": [""], + "key_points": [""], + "consensus": "", + "disagreements": [""], + "action_items": [ + { + "owner": "", + "task": "", + "deadline": "" + } + ], + "unresolved": [""] +} +``` + +### State_Diff.json（秘書產出） +```json +{ + "task_id": "", + "agent_id": "secretary", + "timestamp": "", + "added": [""], + "changed": [""], + "removed": [""] +} +``` + +### Review_Report.json（審查員產出） +```json +{ + "task_id": "", + "agent_id": "reviewer", + "timestamp": "", + "reviewed_agent_id": "", + "reviewed_output_type": "", + "verdict": "", + "issues": [ + { + "severity": "", + "category": "", + "evidence": "", + "required_fix": "" + } + ], + "revise_count": "", + "recommend_meeting": "", + "notes": "" +} +``` + +--- + +## 8.3 量化研究 Schema + +### Finance_Research_Brief.json +```json +{ + "task_id": "", + "agent_id": "finance_researcher", + "timestamp": "", + "sources": [ + { + "title": "", + "url": "", + "published_at": "", + "source_type": "", + "summary": "", + "confidence": "", + "dedupe_key": "" + } + ], + "macro_summary": "", + "conflicts": [""], + "takeaways": [""] +} +``` + +### Market_Structure_Report.json +```json +{ + "task_id": "", + "agent_id": "market_structure_researcher", + "timestamp": "", + "timeframes_used": [""], + "structure_summary": [""], + "liquidity_zones": [""], + "poi_candidates": [""], + "mss_signals": [""], + "bias": "", + "confidence": "", + "notes": [""] +} +``` + +### Bullish_Research_Report.json +```json +{ + "task_id": "", + "agent_id": "bullish_researcher", + "timestamp": "", + "bull_case": [""], + "supporting_evidence": [""], + "expected_edge": [""], + "invalidations": [""], + "conviction_level": "" +} +``` + +### Bearish_Research_Report.json +```json +{ + "task_id": "", + "agent_id": "bearish_researcher", + "timestamp": "", + "bear_case": [""], + "supporting_evidence": [""], + "risk_warnings": [""], + "trade_rejection_reasons": [""], + "conviction_level": "" +} +``` + +### Quant_Strategy_Spec.json（含風控） +```json +{ + "task_id": "", + "agent_id": "quant_strategist", + "timestamp": "", + "strategy_hypothesis": [""], + "entry_rules": [""], + "exit_rules": [""], + "risk_control": { + "position_sizing": [""], + "stop_rules": [""], + "take_profit_rules": [""], + "max_drawdown": "", + "max_concurrent_positions": "" + }, + "bias_checks": [""], + "meeting_based": "", + "meeting_id": "" +} +``` + +### Backtest_Delivery.json +```json +{ + "task_id": "", + "agent_id": "quant_engineer", + "timestamp": "", + "implementation_type": "", + "rules_implemented": [""], + "data_used": [""], + "assumptions": [""], + "results_summary": { + "winrate": "", + "expectancy": "", + "max_drawdown": "", + "sharpe_ratio": "", + "total_trades": "", + "period": "" + }, + "artifacts": [""], + "bias_warnings": [""], + "handoff_notes": [""] +} +``` + +### Data_Analysis_Report.json +```json +{ + "task_id": "", + "agent_id": "data_analyst", + "timestamp": "", + "report_type": "", + "kpi_summary": [""], + "insights": [""], + "anomalies": [""], + "recommendations": [""] +} +``` + +--- + +## 8.4 行銷 & 內容 Schema + +### Market_Research_Brief.json / Market_Analysis_Report.json +```json +{ + "task_id": "", + "agent_id": "market_researcher", + "timestamp": "", + "report_type": "", + "sources": [ + { + "title": "", + "url": "", + "summary": "", + "confidence": "" + } + ], + "pain_points": [""], + "competitor_patterns": [""], + "trend_signals": [""], + "takeaways": [""] +} +``` + +### Brand_Strategy_Plan.json / Growth_Strategy_Plan.json +```json +{ + "task_id": "", + "agent_id": "strategy_director", + "timestamp": "", + "plan_type": "", + "usp": [""], + "target_audience": [""], + "core_messages": [""], + "campaign_direction": [""], + "funnel_plan": [""], + "test_plan": [""] +} +``` + +### Ads_Performance_Report.json +```json +{ + "task_id": "", + "agent_id": "ads_analyst", + "timestamp": "", + "performance_summary": [""], + "diagnosis": [""], + "optimization_suggestions": [""], + "alerts": [""] +} +``` + +### Copywriting_Pack.json +```json +{ + "task_id": "", + "agent_id": "copywriter", + "timestamp": "", + "content_type": "", + "hooks": [""], + "bodies": [""], + "ctas": [""], + "video_sections": [ + { + "scene": "", + "message": "", + "duration_seconds": "" + } + ] +} +``` + +### Static_Creative_Brief.json / Storyboard_Brief.json +```json +{ + "task_id": "", + "agent_id": "creative_director", + "timestamp": "", + "brief_type": "", + "visual_direction": [""], + "must_include": [""], + "asset_specs": [""], + "shots": [ + { + "scene": "", + "visual": "", + "motion": "", + "caption": "" + } + ], + "style_notes": [""] +} +``` + +--- + +## 8.5 新增：會議相關 Schema + +### Meeting_Request.json（發起會議） +```json +{ + "meeting_id": "", + "meeting_type": "", + "topic": "", + "requested_by": "", + "participants": [""], + "moderator": "", + "input_context": [""], + "max_rounds": "", + "stop_condition": "", + "discord_channel": "" +} +``` + +### Meeting_Conclusion.json（會議結論） +```json +{ + "meeting_id": "", + "meeting_type": "", + "topic": "", + "participants": [""], + "moderator": "", + "total_rounds": "", + "conclusion": "", + "consensus_reached": "", + "key_arguments": [ + { + "agent_id": "", + "position": "", + "key_points": [""] + } + ], + "action_items": [ + { + "owner": "", + "task": "" + } + ], + "dissenting_opinions": [""], + "next_steps": [""] +} +``` diff --git a/docs/spec_v3_system_overview.md b/docs/spec_v3_system_overview.md new file mode 100644 index 0000000..ec8ce04 --- /dev/null +++ b/docs/spec_v3_system_overview.md @@ -0,0 +1,129 @@ +# KingClawArmy AI Agent Team - 系統規格書 v3 + +> 版本：v3.0 +> 日期：2026-04-09 +> 狀態：初版定稿 +> 前版差異：v2 為本地 LLM 架構，v3 改為 model-agnostic + Paperclip + Discord 架構 + +--- + +## 第一部分：系統總覽 + +### 1.1 系統目標 + +建立一個 AI Agent 團隊（代號 KingClawArmy），能夠： + +1. **量化研究**：從情報蒐集 → 市場結構分析 → 多空辯論 → 策略形成 → 風控 → 回測 → 分析，完成完整量化研究閉環 +2. **行銷策略**：從市場研究 → 品牌/成長策略 → 投放分析，完成行銷策略閉環 +3. **內容創作**：從策略 → 文案撰寫 → 視覺方向，完成內容產出閉環 +4. **工程開發**：前端/後端開發、部署（依需求啟用） +5. **自主協作**：Agent 之間能進行結構化任務交接與即時討論，產出 1+1 > 2 的協作效果 + +### 1.2 設計原則 + +| 原則 | 說明 | +|---|---| +| Model-Agnostic | 不綁定任何特定 AI 模型，可自由切換雲端或本地 | +| 漸進式上線 | 一隻一隻加入，觀察調整後再擴編 | +| 人類保留最終決策權 | 所有高風險動作必須經過董事長（你）批准 | +| 結構化溝通 | Agent 之間透過 JSON Schema 傳遞資訊，確保格式一致 | +| 討論產生價值 | 關鍵決策點安排多 Agent 討論，而非單一 Agent 獨斷 | + +### 1.3 整體架構 + +``` +┌─────────────────────────────────────────────────────┐ +│ 董事長（你） │ +│ 透過 Discord + Paperclip UI 操作 │ +└──────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────▼──────────────────────────────┐ +│ Discord（溝通 + 管理 + HITL） │ +│ │ +│ 頻道：通知、審批、量化討論、行銷討論、錯誤、日報 │ +│ 功能： │ +│ ├── Agent 群組討論（thread 內多 agent 對話） │ +│ ├── 管理指令（/clip agents, /clip approve） │ +│ ├── HITL 審批（agent 需要你批准時通知你） │ +│ └── 完整對話記錄（自動 audit trail） │ +└──────────────────────┬──────────────────────────────┘ + │ paperclip-plugin-discord +┌──────────────────────▼──────────────────────────────┐ +│ Paperclip（組織 + 調度 + 任務管理） │ +│ │ +│ ├── Org Chart：團隊結構、彙報關係 │ +│ ├── Heartbeat：排程喚醒 agent │ +│ ├── Issue System：任務建立、分派、追蹤 │ +│ ├── Budget：per-agent 預算控制 │ +│ └── Adapter：透過 OpenClaw 執行所有 agent │ +└──────────────────────┬──────────────────────────────┘ + │ OpenClaw Adapter +┌──────────────────────▼──────────────────────────────┐ +│ OpenClaw（Agent 執行層） │ +│ │ +│ ├── 每個 Agent 獨立的 system prompt │ +│ ├── 每個 Agent 獨立的工具權限 │ +│ ├── 模型自由選擇（Claude / GPT / DeepSeek / 本地） │ +│ └── A2A 通訊能力（透過 plugin） │ +└──────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────▼──────────────────────────────┐ +│ Mem0（記憶層） │ +│ │ +│ ├── 共享記憶：跨 agent 的決策記錄、研究結果 │ +│ ├── 個別記憶：每個 agent 的工作脈絡 │ +│ └── 會議記憶：討論結論與共識 │ +└──────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────▼──────────────────────────────┐ +│ AI Model API（模型層） │ +│ │ +│ 之後再決定，可能的選項： │ +│ ├── 雲端：Claude API / OpenAI API / DeepSeek API │ +│ ├── 本地：vLLM / Ollama / SGLang │ +│ └── 混合：部分雲端 + 部分本地 │ +└─────────────────────────────────────────────────────┘ +``` + +### 1.4 技術選型 + +| 層級 | 工具 | 版本/來源 | 選擇理由 | +|---|---|---|---| +| 組織管理 | Paperclip | MIT, 44K+ stars | 最成熟的 AI agent 公司框架，有 org chart、heartbeat、預算、UI | +| 溝通管理 | Discord + paperclip-plugin-discord | 社群 plugin | 補足 Paperclip 缺少的 peer-to-peer 討論，同時作為 HITL 介面 | +| Agent 執行 | OpenClaw | MIT, 257K+ stars | Model-agnostic、支援多種模型、有 A2A 能力、社群活躍 | +| 記憶 | Mem0 | Apache 2.0, 48K+ stars | 社群最大、可自建或用雲端、支援共享+個別記憶 | +| 模型 | 待定 | — | Model-agnostic 設計，之後可自由選擇 | + +### 1.5 資料流概覽 + +``` +董事長下達指令 + │ + ▼ +CEO/COO 接收 → 拆任務 → 分派給對應團隊 + │ + ├── 結構化任務 → Paperclip Issue → Agent Heartbeat 執行 + │ │ + │ ▼ + │ OpenClaw 執行 + │ │ + │ ▼ + │ 產出 JSON 結果 + │ │ + │ ▼ + │ 寫回 Paperclip + │ + ├── 需要討論的任務 → Discord Thread → 多 Agent 討論 + │ │ + │ ▼ + │ 產出會議結論 + │ │ + │ ▼ + │ 寫回 Paperclip + │ + └── 需要你批准 → Discord #approvals → 你批准/退回 + │ + ▼ + 繼續或修改 +``` diff --git a/docs/spec_v4_collaboration_scheduling_memory.md b/docs/spec_v4_collaboration_scheduling_memory.md new file mode 100644 index 0000000..de0869b --- /dev/null +++ b/docs/spec_v4_collaboration_scheduling_memory.md @@ -0,0 +1,238 @@ +# KingClawArmy - 第四部分：協作模式 & 第五部分：排程與觸發 & 第六部分：記憶 & 第七部分：Discord + +--- + +## 第四部分：協作模式 + +### 4.1 三種模式（全部在 OpenClaw 內完成） + +| 模式 | OpenClaw 實現 | 場景 | +|---|---|---| +| **Orchestrator** | CEO 用 `sessions_spawn` 派工給 sub-agent | 日常任務分派 | +| **Peer-to-Peer** | Agent 之間用 `sessions_send` 來回溝通（最多 5 輪） | 追問、澄清、交叉驗證 | +| **Coordinator 討論** | CEO 用 `sessions_send` 逐一收集觀點再收斂 | 多方意見整合、辯論替代 | + +### 4.2 協作模式詳細流程 + +#### Orchestrator（派工） + +``` +CEO 收到任務 + ↓ +sessions_spawn("finance_researcher", task="蒐集今日盤前資訊") + ↓ +財經情報研究員在獨立 session 中執行 + ↓ +完成後 push 結果回 CEO + ↓ +CEO 收到結果，spawn 下一個 agent +``` + +#### Peer-to-Peer（直接溝通） + +``` +量化策略研究員讀完多方報告後有疑問 + ↓ +sessions_send("bullish_researcher", "你提到 OB 支撐，具體是哪個價位？") + ↓ +多方研究員回覆（ping-pong 最多 5 輪） + ↓ +量化策略研究員獲得澄清，繼續工作 +``` + +#### Coordinator 討論（辯論替代方案） + +``` +CEO 需要整合多空觀點 + ↓ +step 1: sessions_send("bullish_researcher", "總結你的核心做多論點") +step 2: sessions_send("bearish_researcher", "總結你的核心做空論點") +step 3: sessions_send("bearish_researcher", "針對多方的論點 [X]，你的反駁是？") +step 4: sessions_send("bullish_researcher", "針對空方的反駁 [Y]，你的回應是？") +step 5: sessions_send("quant_strategist", "以下是雙方觀點 [全文]，請收斂成策略") + ↓ +CEO 收到策略規格 +``` + +### 4.3 什麼場景用什麼模式 + +| 場景 | 模式 | 理由 | +|---|---|---| +| 蒐集資料 | Orchestrator spawn | 獨立任務，不需互動 | +| 寫回測程式 | Orchestrator spawn | 獨立任務 | +| 多空辯論 | Coordinator 討論 | 需要多方觀點交叉 | +| 追問細節 | Peer-to-Peer send | 兩個 agent 直接對話 | +| 審查來回 | Peer-to-Peer send | 審查員與被審者 ping-pong | +| 跨團隊對齊 | Coordinator 討論 | CEO 逐一收集再收斂 | +| 你下達指令 | Discord → CEO | 你對 CEO 說話 | +| 需要你批准 | CEO → Discord @你 | HITL | + +### 4.4 Review Gate + +| 必審節點 | 觸發方式 | +|---|---| +| 量化策略提交 | CEO spawn 審查員 review | +| 回測結果提交 | CEO spawn 審查員 review | +| 工程交付 | CEO spawn 審查員 review | +| 文案對外 | CEO spawn 審查員 review | + +### 4.5 HITL 節點 + +| 需要你批准的事 | 通知方式 | +|---|---| +| 正式部署 | Discord #approvals @你 | +| DB schema 變更 | Discord #approvals @你 | +| 廣告正式發布 | Discord #approvals @你 | +| 對外訊息發送 | Discord #approvals @你 | +| 金流操作 | Discord #approvals @你 | +| 量化策略正式執行 | Discord #approvals @你 | + +--- + +## 第五部分：排程與觸發 + +### 5.1 Cron 排程 + +```bash +# 財經情報 — 每日盤前盤後 +openclaw cron add --agent finance_researcher --cron "30 7 * * 1-5" --task "盤前資訊蒐集" +openclaw cron add --agent finance_researcher --cron "30 18 * * 1-5" --task "盤後資訊整理" + +# 市場研究 — 每日 + 每週 +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） + +透過 CEO 的 Standing Orders 定義： + +``` +CEO Standing Order: 量化研究流程 + +當收到財經情報完成通知： + → spawn market_structure_researcher + +當收到市場結構報告完成通知： + → spawn bullish_researcher（平行） + → spawn bearish_researcher（平行） + +當收到多方 + 空方報告都完成： + → 執行 coordinator 討論（收集雙方觀點） + → spawn quant_strategist（帶入討論結果） + +當收到量化策略完成通知： + → spawn quant_engineer + +當收到回測完成通知： + → spawn data_analyst + +當收到資料分析完成通知： + → send secretary（做摘要） + → spawn reviewer（審查整條 pipeline） + +當收到審查 pass： + → 組裝 Final_Decision_Packet + → Discord @董事長 請求批准 + +當收到審查 revise： + → 退回被點名角色 + → 如超過 3 輪 → Discord @董事長 介入 +``` + +--- + +## 第六部分：記憶架構 + +### 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，清理冗餘 | + +--- + +## 第七部分：Discord Server 結構 + +### 7.1 頻道規劃 + +``` +KingClawArmy Discord Server +│ +├── 📋 管理 +│ ├── #dashboard — 每日摘要、系統狀態 +│ ├── #approvals — HITL 審批（你在這裡批准） +│ └── #errors — 錯誤與異常 +│ +├── 📊 量化 +│ ├── #quant-briefing — 盤前盤後情報 +│ ├── #quant-discussion — 討論區（coordinator 討論結果貼這） +│ └── #quant-results — 策略定稿、回測結果 +│ +├── 📈 行銷 +│ ├── #marketing-intel — 市場情報 +│ └── #ads-performance — 投放 KPI +│ +├── ✏️ 內容 +│ └── #content-briefs — 文案 / 創意 brief +│ +└── 📝 記錄 + ├── #meeting-logs — 所有 coordinator 討論記錄 + └── #decision-log — 重大決策 +``` + +### 7.2 Discord 互動方式 + +| 你想做的事 | 怎麼做 | +|---|---| +| 下達新指令 | 在 #dashboard 或 DM 跟 CEO agent 說 | +| 查看進度 | 問 CEO 或秘書 | +| 批准高風險動作 | 在 #approvals 回覆 approve / reject | +| 看今日摘要 | #dashboard 自動推送（秘書每日產出） | +| 看回測結果 | #quant-results | +| 手動發起討論 | @CEO 說「召集量化團隊討論 [主題]」 | +| 緊急停止 | `openclaw tasks flow cancel ` 或 Discord @CEO「停止 [任務]」 | + +### 7.3 通知規則 + +| 事件 | 推送到 | 由誰推送 | +|---|---|---| +| 任務完成 | 對應區域頻道 | CEO | +| 審查 pass（HITL） | #approvals | CEO | +| 審查 block | #errors + #approvals | CEO | +| 每日摘要 | #dashboard | 秘書 | +| 討論結論 | #meeting-logs | 秘書 | +| 錯誤/異常 | #errors | 相關 agent | diff --git a/docs/spec_v4_org_and_roles.md b/docs/spec_v4_org_and_roles.md new file mode 100644 index 0000000..cf4e3ea --- /dev/null +++ b/docs/spec_v4_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": "" } + ], + "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_v4_rollout_and_risks.md b/docs/spec_v4_rollout_and_risks.md new file mode 100644 index 0000000..0a441a0 --- /dev/null +++ b/docs/spec_v4_rollout_and_risks.md @@ -0,0 +1,138 @@ +# KingClawArmy - 第八部分：JSON Schema & 第九部分：上線計畫 & 第十部分：風險與限制 + +--- + +## 第八部分：JSON Schema + +**沿用 v3 版 schema，見 `spec_v3_schemas.md`。** + +schema 定義與系統架構無關（純資料格式），v3 版仍然適用。 + +--- + +## 第九部分：上線計畫 + +### 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` 正常 | +| 0.2 | 設定至少一個 AI model API | OpenClaw 能回應訊息 | +| 0.3 | 設定記憶引擎（QMD 建議） | `memory_search` 可用 | +| 0.4 | 建立 Discord Server + 頻道 | 頻道結構完成 | +| 0.5 | 連接 OpenClaw Discord 整合 | Bot 在 Discord 上線 | +| 0.6 | 建立 `~/.openclaw/openclaw.json` 基本結構 | config 可載入 | + +### 9.3 Phase 1：管理閉環 + +| 步驟 | 動作 | 驗收 | +|---|---|---| +| 1.1 | 建立 CEO agent（SOUL.md + workspace） | Agent 回應正常 | +| 1.2 | 設定 CEO 的 Discord binding | Discord 訊息能路由到 CEO | +| 1.3 | 手動在 Discord 下達測試任務 | CEO 能理解並回應 | +| 1.4 | 建立秘書 agent | 秘書能用 memory_search 讀取 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 的記憶（QMD extraCollections） | + +**Phase 1 完成標準：** +- [ ] 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_v4_system_overview.md` | 第一部分：系統總覽 | +| `spec_v4_org_and_roles.md` | 第二、三部分：組織架構 + 角色定義 | +| `spec_v4_collaboration_scheduling_memory.md` | 第四~七部分：協作 + 排程 + 記憶 + Discord | +| `spec_v4_rollout_and_risks.md` | 第八~十部分：Schema + 上線 + 風險 | +| `spec_v3_schemas.md` | JSON Schema（v3 版沿用） | diff --git a/docs/spec_v4_system_overview.md b/docs/spec_v4_system_overview.md new file mode 100644 index 0000000..436cf14 --- /dev/null +++ b/docs/spec_v4_system_overview.md @@ -0,0 +1,96 @@ +# KingClawArmy AI Agent Team - 系統規格書 v4 + +> 版本：v4.0 +> 日期：2026-04-09 +> 狀態：初版定稿 +> 前版差異：v3 為 Paperclip + Discord + Mem0 多系統架構，v4 簡化為純 OpenClaw 架構 + +--- + +## 第一部分：系統總覽 + +### 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 用量 |