diff --git a/docs/INDEX.md b/docs/INDEX.md new file mode 100644 index 0000000..25fe749 --- /dev/null +++ b/docs/INDEX.md @@ -0,0 +1,41 @@ +# KingClawArmy 文件索引 + +> 版本：v4.0 | 更新日期：2026-04-09 + +--- + +## spec/ — 系統規格 + +系統設計的完整規格，定義整個 KingClawArmy 的架構、組織、角色與上線計畫。 + +| 文件 | 內容 | +|---|---| +| [spec_v4_system_overview.md](spec/spec_v4_system_overview.md) | 系統目標、設計原則、整體架構、為什麼只用 OpenClaw | +| [spec_v4_org_and_roles.md](spec/spec_v4_org_and_roles.md) | 組織架構、Agent 清單（15~17 agents）、各角色定義 | +| [spec_v4_collaboration_scheduling_memory.md](spec/spec_v4_collaboration_scheduling_memory.md) | 協作模式、排程觸發、記憶架構、Discord Server 結構 | +| [spec_v4_rollout_and_risks.md](spec/spec_v4_rollout_and_risks.md) | 上線計畫（Phase 0~5）、風險限制、成本控制、停損信號 | + +--- + +## 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 參數、使用場景、Agents vs Sub-agent run 的區別 | + +--- + +## 進度追蹤 + +| Phase | 說明 | 狀態 | +|---|---|---| +| Phase 0 | 基礎設施（OpenClaw + Discord） | ✅ 完成 | +| Phase 1 | 管理閉環（CEO + 秘書 + 審查員） | 🔄 進行中 | +| Phase 2 | 量化閉環（7 agents） | 待開始 | +| Phase 3 | 行銷閉環（3 agents） | 待開始 | +| Phase 4 | 內容閉環（2 agents） | 待開始 | +| Phase 5 | 工程團隊（依需求） | 待開始 | diff --git a/docs/agent_company_master_overview_v2.md b/docs/agent_company_master_overview_v2.md deleted file mode 100644 index c84f1d2..0000000 --- a/docs/agent_company_master_overview_v2.md +++ /dev/null @@ -1,207 +0,0 @@ -# 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 deleted file mode 100644 index e5fcedf..0000000 --- a/docs/agent_company_runtime_config_v2.md +++ /dev/null @@ -1,221 +0,0 @@ -# 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 deleted file mode 100644 index d4b34a1..0000000 --- a/docs/agent_company_schema_templates_v2.md +++ /dev/null @@ -1,513 +0,0 @@ -# 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/guides/guide_openclaw_config.md b/docs/guides/guide_openclaw_config.md new file mode 100644 index 0000000..7426c4e --- /dev/null +++ b/docs/guides/guide_openclaw_config.md @@ -0,0 +1,182 @@ +# 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 實際設定 + +| 項目 | 值 | +|---|---| +| Guild ID | `1486353934594342924` | +| #總機 Channel ID | `1486739757957644319` | +| CEO Agent ID | `ceo_coo` | +| CEO 模型 | `openai-codex/gpt-5.4` | +| 預設模型 | `openai-codex/gpt-5.4-mini` | diff --git a/docs/guides/guide_sessions_tools.md b/docs/guides/guide_sessions_tools.md new file mode 100644 index 0000000..b927fd1 --- /dev/null +++ b/docs/guides/guide_sessions_tools.md @@ -0,0 +1,87 @@ +# sessions_spawn / sessions_send 使用指南 + +> 適用版本：OpenClaw v2026.4.x +> 更新日期：2026-04-09 + +--- + +## Agents vs Sub-agent Runs + +**Agent** = 有自己 workspace、設定檔、記憶的持久實體。在 `openclaw.json` 的 `agents.list` 裡定義。 + +**Sub-agent run** = 當一個 Agent 被 `sessions_spawn` 呼叫時，那次在隔離 session 裡的執行。Session key 格式：`agent::subagent:`。 + +兩者不是不同等級，只是存在方式不同：同一個 Agent 可以被 spawn 成 sub-agent run 來執行任務，完成後 announce 結果回去。 + +--- + +## sessions_spawn — 派工（非阻塞） + +**行為：** 立即返回 `runId` 和 `childSessionKey`，不等待結果。對方 Agent 在獨立 session 執行，完成後 announce 結果。 + +**使用場景：** 獨立任務，不需要即時來回溝通。 + +```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` | 覆蓋模型設定 | + +**限制：** +- 最多 5 層深（spawn 的 spawn 的 spawn...） +- 最多 5 個並行 +- 預設葉層 sub-agent 不具備 sessions 工具（無法再 spawn） + +--- + +## sessions_send — 同步溝通（可等待回覆） + +**行為：** 向另一個 session 傳訊，可設定是否等待回覆。支援最多 5 輪來回。 + +**使用場景：** 追問細節、審查來回、交叉確認。 + +```json +{ + "sessionKey": "agent:reviewer:subagent:xxxx", + "message": "請審查以下量化策略內容：[...]", + "timeoutSeconds": 60 +} +``` + +**操作模式：** + +| 模式 | 設定 | 用途 | +|---|---|---| +| 等待回覆 | `timeoutSeconds > 0` | 需要立即得到回應 | +| 即發即忘 | `timeoutSeconds: 0` | 不需等回覆 | +| 多輪來回 | 自動支援，最多 5 輪 | 審查、追問 | + +對方可回覆 `REPLY_SKIP` 提早結束來回。 + +--- + +## 使用情境對照 + +| 情境 | 工具 | 原因 | +|---|---|---| +| 蒐集資料 | spawn | 獨立任務，不需互動 | +| 寫回測程式 | spawn | 獨立任務 | +| 多空平行研究 | spawn（兩個） | 並行執行 | +| 追問研究員細節 | send | 兩個 agent 直接對話 | +| 審查員來回審查 | send | 需要 ping-pong | +| 請秘書做摘要 | spawn 或 send | 依是否需要等待 | +| Coordinator 討論 | send（逐一收集） | 整合多方觀點 | diff --git a/docs/guides/guide_workspace_files.md b/docs/guides/guide_workspace_files.md new file mode 100644 index 0000000..8d408bc --- /dev/null +++ b/docs/guides/guide_workspace_files.md @@ -0,0 +1,157 @@ +# 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/spec_v4_collaboration_scheduling_memory.md b/docs/spec/spec_v4_collaboration_scheduling_memory.md similarity index 100% rename from docs/spec_v4_collaboration_scheduling_memory.md rename to docs/spec/spec_v4_collaboration_scheduling_memory.md diff --git a/docs/spec_v4_org_and_roles.md b/docs/spec/spec_v4_org_and_roles.md similarity index 100% rename from docs/spec_v4_org_and_roles.md rename to docs/spec/spec_v4_org_and_roles.md diff --git a/docs/spec_v4_rollout_and_risks.md b/docs/spec/spec_v4_rollout_and_risks.md similarity index 67% rename from docs/spec_v4_rollout_and_risks.md rename to docs/spec/spec_v4_rollout_and_risks.md index 0a441a0..79190a6 100644 --- a/docs/spec_v4_rollout_and_risks.md +++ b/docs/spec/spec_v4_rollout_and_risks.md @@ -4,9 +4,8 @@ ## 第八部分：JSON Schema -**沿用 v3 版 schema，見 `spec_v3_schemas.md`。** - -schema 定義與系統架構無關（純資料格式），v3 版仍然適用。 +JSON Schema 定義各 agent 產出格式，與系統架構無關（純資料格式）。 +詳細 schema 定義請參考各 agent 的 AGENTS.md 或實際輸出範例。 --- @@ -14,42 +13,47 @@ schema 定義與系統架構無關（純資料格式），v3 版仍然適用。 ### 9.1 總覽 -| Phase | 目標 | 上線角色 | 驗收標準 | +| 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 | 基礎設施 | — | OpenClaw + Discord 可用 | -| 1 | 管理閉環 | 3 agents | CEO 派工→秘書記錄→審查審核 | -| 2 | 量化閉環 | +7 agents | 情報到回測完整 pipeline | -| 3 | 行銷閉環 | +3 agents | 研究→策略→KPI 追蹤 | -| 4 | 內容閉環 | +2 agents | 文案+創意 brief | -| 5 | 工程（依需求） | +0~2 agents | 前後端任務可執行 | +| 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 可載入 | ✅ | -### 9.2 Phase 0：基礎設施 +**實際設定筆記：** +- Discord Bot 需在 Developer Portal 開啟 Message Content Intent、Server Members Intent +- 群組頻道路由須在 `channels.discord.guilds..channels` 設定，binding 用 `peer.kind: channel + peer.id: ` +- Gateway 以 systemd user service 方式常駐執行 -| 步驟 | 動作 | 驗收 | -|---|---|---| -| 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：管理閉環 🔄 -### 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） | +| 步驟 | 動作 | 驗收 | 狀態 | +|---|---|---|---| +| 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 完成標準：** -- [ ] CEO 能接收 Discord 指令 +- [x] CEO 能接收 Discord 指令 - [ ] CEO 能 spawn/send 其他 agent - [ ] 秘書能產出摘要 - [ ] 審查員能 pass/revise diff --git a/docs/spec_v4_system_overview.md b/docs/spec/spec_v4_system_overview.md similarity index 100% rename from docs/spec_v4_system_overview.md rename to docs/spec/spec_v4_system_overview.md diff --git a/docs/spec_v3_collaboration.md b/docs/spec_v3_collaboration.md deleted file mode 100644 index 0b292a0..0000000 --- a/docs/spec_v3_collaboration.md +++ /dev/null @@ -1,203 +0,0 @@ -# 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 deleted file mode 100644 index ee13535..0000000 --- a/docs/spec_v3_org_and_roles.md +++ /dev/null @@ -1,399 +0,0 @@ -# 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 deleted file mode 100644 index c4ef595..0000000 --- a/docs/spec_v3_rollout_and_risks.md +++ /dev/null @@ -1,187 +0,0 @@ -# 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 deleted file mode 100644 index f4136cf..0000000 --- a/docs/spec_v3_scheduling_memory_discord.md +++ /dev/null @@ -1,194 +0,0 @@ -# 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 deleted file mode 100644 index 4c99be7..0000000 --- a/docs/spec_v3_schemas.md +++ /dev/null @@ -1,412 +0,0 @@ -# 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 deleted file mode 100644 index ec8ce04..0000000 --- a/docs/spec_v3_system_overview.md +++ /dev/null @@ -1,129 +0,0 @@ -# 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 → 你批准/退回 - │ - ▼ - 繼續或修改 -```