chris/KingClawArmy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 重整文件結構，移除 v2/v3 舊文檔，新增實作指南

Browse Source 
- 刪除 v2/v3 所有舊規格文件
- 將 v4 規格文件移至 spec/ 目錄
- 新增 guides/ 目錄，包含：
  - guide_openclaw_config.md：openclaw.json 設定、Discord 接入、Gateway 管理
  - guide_workspace_files.md：8 個 Workspace 設定檔正確用途
  - guide_sessions_tools.md：sessions_spawn/send 參數與 Agents vs Sub-agent run 說明
- 更新 spec_v4_rollout_and_risks.md：加入 Phase 0/1 實際進度
- 新增 INDEX.md 文件索引

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Chris
2026-04-09 07:23:17 +00:00
parent 8d97610634
commit edc1036435
17 changed files with 504 additions and 2498 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/INDEX.md Normal file
View File

@@ -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 | 工程團隊（依需求） | 待開始 |

207
docs/agent_company_master_overview_v2.md
View File

@@ -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 | 升級到可營運版 |

221
docs/agent_company_runtime_config_v2.md
View File

@@ -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 | 董事長批准或退回 |

513
docs/agent_company_schema_templates_v2.md
View File

@@ -1,513 +0,0 @@
# AI Agent Company - Schema 模板檔（JSON 規格專用）
> 用途：只放 JSON schema template
> 原則：只保留格式，不放假資料
---
## 1. 共用欄位
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "<string>",
"timestamp": "<ISO-8601 string>",
"status": "<pending|running|pass|revise|block|done|cancelled>",
"input_version": "<string>"
}
```
---
## 2. 核心管理層
### Chairman_Request_Packet.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "chairman",
"timestamp": "<ISO-8601 string>",
"status": "pending",
"input_version": "<string>",
"request": "<string>",
"constraints": ["<string>"],
"priority": "<low|medium|high>",
"attachments": ["<string>"]
}
```
### Task_Spec.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "ceo_coo",
"timestamp": "<ISO-8601 string>",
"status": "<pending|running|done>",
"input_version": "<string>",
"goal": "<string>",
"success_criteria": ["<string>"],
"routes": [
{
"role": "<string>",
"subtask": "<string>",
"required_output": "<string>"
}
],
"priority": "<low|medium|high>",
"notes": ["<string>"]
}
```
### Meeting_Summary.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "secretary",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"topic": "<string>",
"participants": ["<string>"],
"key_points": ["<string>"],
"decision": "<string>",
"unresolved": ["<string>"]
}
```
### State_Diff.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "secretary",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"added": ["<string>"],
"changed": ["<string>"],
"removed": ["<string>"]
}
```
### Todo_List.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "secretary",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"items": [
{
"owner": "<string>",
"task": "<string>",
"deadline": "<ISO-8601 string>"
}
]
}
```
### Review_Report.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "reviewer",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"verdict": "<pass|revise|block>",
"issues": [
{
"severity": "<low|medium|high>",
"category": "<string>",
"evidence": "<string>",
"required_fix": "<string>"
}
],
"notes": "<string>"
}
```
### Final_Decision_Packet.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "ceo_coo",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"summary": "<string>",
"options": [
{
"name": "<string>",
"description": "<string>",
"pros": ["<string>"],
"cons": ["<string>"],
"risk_level": "<low|medium|high>"
}
],
"recommended_option": "<string>",
"review_verdict": "<pass|revise|block>",
"decision_needed": ["<string>"]
}
```
---
## 3. 情報與量化線
### Finance_Research_Brief.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "finance_intelligence_researcher",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"sources": [
{
"title": "<string>",
"url": "<string>",
"canonical_url": "<string>",
"published_at": "<ISO-8601 string>",
"source_type": "<news|blog|forum|official>",
"summary": "<string>",
"confidence": "<number>",
"freshness_bucket": "<string>",
"dedupe_key": "<string>"
}
],
"conflicts": ["<string>"],
"takeaways": ["<string>"]
}
```
### Market_Research_Brief.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "market_intelligence_researcher",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"sources": [
{
"title": "<string>",
"url": "<string>",
"canonical_url": "<string>",
"published_at": "<ISO-8601 string>",
"source_type": "<news|blog|forum|official>",
"summary": "<string>",
"confidence": "<number>",
"freshness_bucket": "<string>",
"dedupe_key": "<string>"
}
],
"pain_points": ["<string>"],
"competitor_patterns": ["<string>"],
"conflicts": ["<string>"],
"takeaways": ["<string>"]
}
```
### Market_Structure_Report.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "market_structure_researcher",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"timeframes_used": ["<string>"],
"structure_summary": ["<string>"],
"liquidity_zones": ["<string>"],
"poi_candidates": ["<string>"],
"mss_signals": ["<string>"],
"notes": ["<string>"]
}
```
### Bullish_Research_Report.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "bullish_researcher",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"bull_case": ["<string>"],
"supporting_evidence": ["<string>"],
"expected_edge": ["<string>"],
"invalidations": ["<string>"]
}
```
### Bearish_Research_Report.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "bearish_researcher",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"bear_case": ["<string>"],
"supporting_evidence": ["<string>"],
"risk_warnings": ["<string>"],
"trade_rejection_reasons": ["<string>"]
}
```
### Quant_Strategy_Spec.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "quant_strategy_researcher",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"strategy_hypothesis": ["<string>"],
"entry_rules": ["<string>"],
"exit_rules": ["<string>"],
"risk_rules": ["<string>"],
"bias_checks": ["<string>"]
}
```
### Risk_Control_Spec.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "risk_control_researcher",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"position_sizing": ["<string>"],
"stop_rules": ["<string>"],
"take_profit_rules": ["<string>"],
"bias_checks": ["<string>"]
}
```
### Backtest_Delivery.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "quant_engineer",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"implementation_type": "<pine|python|both>",
"rules_implemented": ["<string>"],
"data_used": ["<string>"],
"assumptions": ["<string>"],
"artifacts": ["<string>"],
"handoff_notes": ["<string>"]
}
```
### Data_Analysis_Report.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "data_analyst",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"kpi_summary": ["<string>"],
"ab_test_results": ["<string>"],
"insights": ["<string>"],
"recommendations": ["<string>"]
}
```
---
## 4. 行銷與創意層
### Brand_Strategy_Plan.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "brand_strategy_director",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"usp": ["<string>"],
"target_audience": ["<string>"],
"core_messages": ["<string>"],
"brand_story": ["<string>"]
}
```
### Growth_Strategy_Plan.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "growth_strategy_director",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"campaign_direction": ["<string>"],
"funnel_plan": ["<string>"],
"conversion_strategy": ["<string>"],
"test_plan": ["<string>"]
}
```
### Market_Analysis_Report.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "market_research_analyst",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"market_summary": ["<string>"],
"trend_signals": ["<string>"],
"recommendations": ["<string>"]
}
```
### Ads_Performance_Report.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "ads_performance_analyst",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"performance_summary": ["<string>"],
"diagnosis": ["<string>"],
"optimization_suggestions": ["<string>"],
"alerts": ["<string>"]
}
```
### Copywriting_Pack.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "ad_copywriter",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"hooks": ["<string>"],
"bodies": ["<string>"],
"ctas": ["<string>"]
}
```
### Video_Script_Pack.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "video_script_writer",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"opening_hook": "<string>",
"sections": [
{
"scene": "<number>",
"message": "<string>",
"duration_seconds": "<number>"
}
],
"ending_cta": "<string>"
}
```
### Static_Creative_Brief.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "static_visual_design_director",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"visual_direction": ["<string>"],
"must_include": ["<string>"],
"asset_specs": ["<string>"],
"qa_notes": ["<string>"]
}
```
### Storyboard_Brief.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "storyboard_creative_director",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"shots": [
{
"scene": "<number>",
"visual": "<string>",
"motion": "<string>",
"caption": "<string>"
}
],
"style_notes": ["<string>"]
}
```
---
## 5. 工程層
### Frontend_Delivery.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "frontend_engineer",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"components_built": ["<string>"],
"tracking_added": ["<string>"],
"ui_changes": ["<string>"],
"handoff_notes": ["<string>"]
}
```
### Backend_Delivery.json
```json
{
"task_id": "<string>",
"project_id": "<string>",
"role": "backend_engineer",
"timestamp": "<ISO-8601 string>",
"status": "done",
"input_version": "<string>",
"apis_built": ["<string>"],
"schema_changes": ["<string>"],
"automations_added": ["<string>"],
"handoff_notes": ["<string>"]
}
```

182
docs/guides/guide_openclaw_config.md Normal file
View File

@@ -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": "<BOT_TOKEN>",
"guilds": {
"<GUILD_ID>": {
"channels": {
"<CHANNEL_ID>": {}
}
}
}
}
},
"bindings": [
{
"type": "route",
"agentId": "ceo_coo",
"match": {
"channel": "discord",
"peer": {
"kind": "channel",
"id": "<CHANNEL_ID>"
}
}
}
]
}
```
---
## 新增 Agent
```bash
openclaw agents add <agent_id> \
--workspace ~/.openclaw/workspaces/<agent_id> \
--model <model_id> \
--non-interactive
```
---
## Discord 設定
### 1. 接入 Discord Bot
```bash
openclaw channels add --channel discord --token <BOT_TOKEN>
```
### 2. Discord Developer Portal 必開設定
Bot → Privileged Gateway Intents：
- Message Content Intent ✅
- Server Members Intent ✅
### 3. 設定 Guild 頻道白名單
在 `openclaw.json` 的 `channels.discord.guilds` 下新增：
```json
"guilds": {
"<GUILD_ID>": {
"channels": {
"<CHANNEL_ID>": {}
}
}
}
```
### 4. 設定 Agent 路由 Binding
```json
"bindings": [
{
"type": "route",
"agentId": "<agent_id>",
"match": {
"channel": "discord",
"peer": {
"kind": "channel",
"id": "<CHANNEL_ID>"
}
}
}
]
```
### 5. 授權 Discord 用戶
Bot 初次收到 DM 時會顯示 pairing code：
```bash
openclaw pairing approve discord <PAIRING_CODE>
```
---
## 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 <id> --bind "discord:<channel_id>"
# 移除 binding
openclaw agents unbind --agent <id> --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` |

87
docs/guides/guide_sessions_tools.md Normal file
View File

@@ -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:<agentId>:subagent:<uuid>`。
兩者不是不同等級，只是存在方式不同：同一個 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（逐一收集） | 整合多方觀點 |

157
docs/guides/guide_workspace_files.md Normal file
View File

@@ -0,0 +1,157 @@
# OpenClaw Workspace 設定檔指南
> 適用版本：OpenClaw v2026.4.x
> 更新日期：2026-04-09
---
## 總覽
每個 Agent 的 workspace 資料夾下有固定的 8 個設定檔，OpenClaw 在 session 啟動時自動讀取並組合成 Agent 的身份、行為規則、記憶與任務排程。
```
~/.openclaw/workspaces/<agent_id>/
├── 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` 自動讀取今日+昨日

0
docs/spec_v4_collaboration_scheduling_memory.md → docs/spec/spec_v4_collaboration_scheduling_memory.md
View File

0
docs/spec_v4_org_and_roles.md → docs/spec/spec_v4_org_and_roles.md
View File

70
docs/spec_v4_rollout_and_risks.md → docs/spec/spec_v4_rollout_and_risks.md
View File

@@ -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.<guildId>.channels` 設定，binding 用 `peer.kind: channel + peer.id: <channelId>`
- 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

0
docs/spec_v4_system_overview.md → docs/spec/spec_v4_system_overview.md
View File

203
docs/spec_v3_collaboration.md
View File

@@ -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 <id> 或 /clip reject <id>
↓
approve → 繼續執行
reject → 退回修改，附上你的意見
```

399
docs/spec_v3_org_and_roles.md
View File

@@ -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.
```

187
docs/spec_v3_rollout_and_risks.md
View File

@@ -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` | 第九部分：上線計畫 + 第十部分：風險與限制 |

194
docs/spec_v3_scheduling_memory_discord.md
View File

@@ -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>` | 查看 agent 預算 | 成本控制 |
| `/clip issues` | 查看任務列表 | 追蹤進度 |
| `/clip approve <id>` | 批准 HITL 請求 | 高風險動作放行 |
| `/clip reject <id>` | 退回 HITL 請求 | 附上修改意見 |
| `/acp spawn agent:<name> task:<desc>` | 手動啟動 agent | 臨時指派任務 |
| `/acp cancel session:<id>` | 停止 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 |
| 臨時討論 | 任何頻道 | 由發起者決定 | 秘書摘要存檔 |

412
docs/spec_v3_schemas.md
View File

@@ -1,412 +0,0 @@
# KingClawArmy - 第八部分：JSON Schema
> 基於 v2 schema 更新，新增會議相關 schema
> 所有 schema 只保留格式模板，不放假資料
---
## 8.1 共用欄位
```json
{
"task_id": "<string>",
"project_id": "<string>",
"agent_id": "<string>",
"role": "<string>",
"timestamp": "<ISO-8601 string>",
"status": "<pending|running|pass|revise|block|done|cancelled>",
"input_version": "<string>"
}
```
---
## 8.2 管理層 Schema
### Task_Spec.json（CEO/COO 產出）
```json
{
"task_id": "<string>",
"project_id": "<string>",
"agent_id": "ceo_coo",
"role": "ceo_coo",
"timestamp": "<ISO-8601>",
"status": "<pending|running|done>",
"goal": "<string>",
"success_criteria": ["<string>"],
"routes": [
{
"agent_id": "<string>",
"subtask": "<string>",
"required_output": "<string>",
"collaboration_mode": "<task_handoff|meeting>"
}
],
"priority": "<low|medium|high>",
"meeting_required": "<boolean>",
"meeting_type": "<meeting_quant_debate|meeting_strategy_review|meeting_cross_team_sync|null>",
"notes": ["<string>"]
}
```
### Final_Decision_Packet.json（CEO/COO 產出）
```json
{
"task_id": "<string>",
"project_id": "<string>",
"agent_id": "ceo_coo",
"timestamp": "<ISO-8601>",
"status": "done",
"summary": "<string>",
"options": [
{
"name": "<string>",
"description": "<string>",
"pros": ["<string>"],
"cons": ["<string>"],
"risk_level": "<low|medium|high>"
}
],
"recommended_option": "<string>",
"review_verdict": "<pass|revise|block>",
"meeting_conclusions": ["<string>"],
"decision_needed": ["<string>"]
}
```
### Meeting_Summary.json（秘書產出）
```json
{
"task_id": "<string>",
"project_id": "<string>",
"agent_id": "secretary",
"timestamp": "<ISO-8601>",
"meeting_type": "<string>",
"topic": "<string>",
"participants": ["<agent_id>"],
"key_points": ["<string>"],
"consensus": "<string>",
"disagreements": ["<string>"],
"action_items": [
{
"owner": "<agent_id>",
"task": "<string>",
"deadline": "<ISO-8601|null>"
}
],
"unresolved": ["<string>"]
}
```
### State_Diff.json（秘書產出）
```json
{
"task_id": "<string>",
"agent_id": "secretary",
"timestamp": "<ISO-8601>",
"added": ["<string>"],
"changed": ["<string>"],
"removed": ["<string>"]
}
```
### Review_Report.json（審查員產出）
```json
{
"task_id": "<string>",
"agent_id": "reviewer",
"timestamp": "<ISO-8601>",
"reviewed_agent_id": "<string>",
"reviewed_output_type": "<string>",
"verdict": "<pass|revise|block>",
"issues": [
{
"severity": "<low|medium|high>",
"category": "<string>",
"evidence": "<string>",
"required_fix": "<string>"
}
],
"revise_count": "<number>",
"recommend_meeting": "<boolean>",
"notes": "<string>"
}
```
---
## 8.3 量化研究 Schema
### Finance_Research_Brief.json
```json
{
"task_id": "<string>",
"agent_id": "finance_researcher",
"timestamp": "<ISO-8601>",
"sources": [
{
"title": "<string>",
"url": "<string>",
"published_at": "<ISO-8601>",
"source_type": "<news|blog|forum|official>",
"summary": "<string>",
"confidence": "<number 0-1>",
"dedupe_key": "<string>"
}
],
"macro_summary": "<string>",
"conflicts": ["<string>"],
"takeaways": ["<string>"]
}
```
### Market_Structure_Report.json
```json
{
"task_id": "<string>",
"agent_id": "market_structure_researcher",
"timestamp": "<ISO-8601>",
"timeframes_used": ["<string>"],
"structure_summary": ["<string>"],
"liquidity_zones": ["<string>"],
"poi_candidates": ["<string>"],
"mss_signals": ["<string>"],
"bias": "<bullish|bearish|neutral|unclear>",
"confidence": "<number 0-1>",
"notes": ["<string>"]
}
```
### Bullish_Research_Report.json
```json
{
"task_id": "<string>",
"agent_id": "bullish_researcher",
"timestamp": "<ISO-8601>",
"bull_case": ["<string>"],
"supporting_evidence": ["<string>"],
"expected_edge": ["<string>"],
"invalidations": ["<string>"],
"conviction_level": "<low|medium|high>"
}
```
### Bearish_Research_Report.json
```json
{
"task_id": "<string>",
"agent_id": "bearish_researcher",
"timestamp": "<ISO-8601>",
"bear_case": ["<string>"],
"supporting_evidence": ["<string>"],
"risk_warnings": ["<string>"],
"trade_rejection_reasons": ["<string>"],
"conviction_level": "<low|medium|high>"
}
```
### Quant_Strategy_Spec.json（含風控）
```json
{
"task_id": "<string>",
"agent_id": "quant_strategist",
"timestamp": "<ISO-8601>",
"strategy_hypothesis": ["<string>"],
"entry_rules": ["<string>"],
"exit_rules": ["<string>"],
"risk_control": {
"position_sizing": ["<string>"],
"stop_rules": ["<string>"],
"take_profit_rules": ["<string>"],
"max_drawdown": "<string>",
"max_concurrent_positions": "<number>"
},
"bias_checks": ["<string>"],
"meeting_based": "<boolean>",
"meeting_id": "<string|null>"
}
```
### Backtest_Delivery.json
```json
{
"task_id": "<string>",
"agent_id": "quant_engineer",
"timestamp": "<ISO-8601>",
"implementation_type": "<pine|python|both>",
"rules_implemented": ["<string>"],
"data_used": ["<string>"],
"assumptions": ["<string>"],
"results_summary": {
"winrate": "<number>",
"expectancy": "<number>",
"max_drawdown": "<number>",
"sharpe_ratio": "<number>",
"total_trades": "<number>",
"period": "<string>"
},
"artifacts": ["<string>"],
"bias_warnings": ["<string>"],
"handoff_notes": ["<string>"]
}
```
### Data_Analysis_Report.json
```json
{
"task_id": "<string>",
"agent_id": "data_analyst",
"timestamp": "<ISO-8601>",
"report_type": "<daily|weekly|backtest_analysis|ad_hoc>",
"kpi_summary": ["<string>"],
"insights": ["<string>"],
"anomalies": ["<string>"],
"recommendations": ["<string>"]
}
```
---
## 8.4 行銷 & 內容 Schema
### Market_Research_Brief.json / Market_Analysis_Report.json
```json
{
"task_id": "<string>",
"agent_id": "market_researcher",
"timestamp": "<ISO-8601>",
"report_type": "<brief|analysis>",
"sources": [
{
"title": "<string>",
"url": "<string>",
"summary": "<string>",
"confidence": "<number 0-1>"
}
],
"pain_points": ["<string>"],
"competitor_patterns": ["<string>"],
"trend_signals": ["<string>"],
"takeaways": ["<string>"]
}
```
### Brand_Strategy_Plan.json / Growth_Strategy_Plan.json
```json
{
"task_id": "<string>",
"agent_id": "strategy_director",
"timestamp": "<ISO-8601>",
"plan_type": "<brand|growth>",
"usp": ["<string>"],
"target_audience": ["<string>"],
"core_messages": ["<string>"],
"campaign_direction": ["<string>"],
"funnel_plan": ["<string>"],
"test_plan": ["<string>"]
}
```
### Ads_Performance_Report.json
```json
{
"task_id": "<string>",
"agent_id": "ads_analyst",
"timestamp": "<ISO-8601>",
"performance_summary": ["<string>"],
"diagnosis": ["<string>"],
"optimization_suggestions": ["<string>"],
"alerts": ["<string>"]
}
```
### Copywriting_Pack.json
```json
{
"task_id": "<string>",
"agent_id": "copywriter",
"timestamp": "<ISO-8601>",
"content_type": "<ad_copy|video_script|both>",
"hooks": ["<string>"],
"bodies": ["<string>"],
"ctas": ["<string>"],
"video_sections": [
{
"scene": "<number>",
"message": "<string>",
"duration_seconds": "<number>"
}
]
}
```
### Static_Creative_Brief.json / Storyboard_Brief.json
```json
{
"task_id": "<string>",
"agent_id": "creative_director",
"timestamp": "<ISO-8601>",
"brief_type": "<static|storyboard>",
"visual_direction": ["<string>"],
"must_include": ["<string>"],
"asset_specs": ["<string>"],
"shots": [
{
"scene": "<number>",
"visual": "<string>",
"motion": "<string>",
"caption": "<string>"
}
],
"style_notes": ["<string>"]
}
```
---
## 8.5 新增：會議相關 Schema
### Meeting_Request.json（發起會議）
```json
{
"meeting_id": "<string>",
"meeting_type": "<meeting_quant_debate|meeting_strategy_review|meeting_cross_team_sync|meeting_daily_premarket|custom>",
"topic": "<string>",
"requested_by": "<agent_id>",
"participants": ["<agent_id>"],
"moderator": "<agent_id>",
"input_context": ["<schema_name>"],
"max_rounds": "<number>",
"stop_condition": "<string>",
"discord_channel": "<string>"
}
```
### Meeting_Conclusion.json（會議結論）
```json
{
"meeting_id": "<string>",
"meeting_type": "<string>",
"topic": "<string>",
"participants": ["<agent_id>"],
"moderator": "<agent_id>",
"total_rounds": "<number>",
"conclusion": "<string>",
"consensus_reached": "<boolean>",
"key_arguments": [
{
"agent_id": "<string>",
"position": "<string>",
"key_points": ["<string>"]
}
],
"action_items": [
{
"owner": "<agent_id>",
"task": "<string>"
}
],
"dissenting_opinions": ["<string>"],
"next_steps": ["<string>"]
}
```

129
docs/spec_v3_system_overview.md
View File

@@ -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 → 你批准/退回
│
▼
繼續或修改
```