Initial commit: KingClawArmy AI Agent Team spec v4

Pure OpenClaw architecture for 15-17 agent team covering quant research,
marketing, content, and engineering. Includes org structure, role definitions,
collaboration patterns, scheduling, memory architecture, Discord integration,
rollout plan, and JSON schemas.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/spec_v3_rollout_and_risks.md

@@ -0,0 +1,187 @@
+# KingClawArmy - 第九部分：上線計畫 & 第十部分：風險與限制
+
+---
+
+## 第九部分：上線計畫
+
+### 9.1 總覽
+
+| Phase | 目標 | 上線角色 | 驗收標準 |
+|---|---|---|---|
+| 0 | 基礎設施 | 無 agent | 環境可用 |
+| 1 | 管理閉環 | 3 agents | CEO 能派工、秘書能記錄、審查能審核 |
+| 2 | 量化閉環 | +7 agents | 從情報到回測的完整 pipeline 跑通 |
+| 3 | 行銷閉環 | +3 agents | 市場研究 → 策略 → KPI 追蹤跑通 |
+| 4 | 內容閉環 | +2 agents | 文案 + 創意 brief 產出跑通 |
+| 5 | 工程（依需求） | +0~2 agents | 前後端任務可執行 |
+| 6 | 營運化 | 全體 | 完整排程、HITL、監控、成本控制 |
+
+---
+
+### 9.2 Phase 0：基礎設施建置
+
+**目標：** 讓所有基礎工具可用
+
+| 步驟 | 動作 | 驗收 |
+|---|---|---|
+| 0.1 | 安裝並啟動 Paperclip（Node.js + PostgreSQL） | Dashboard 可開啟 |
+| 0.2 | 安裝 OpenClaw，設定至少一個 AI model API | OpenClaw 能回應 |
+| 0.3 | 建立 Discord Server，建立頻道結構 | 頻道都在 |
+| 0.4 | 安裝 paperclip-plugin-discord，連接 Discord Bot | Bot 在 Discord 上線 |
+| 0.5 | 安裝並設定 Mem0（self-host 或 cloud） | Mem0 API 可呼叫 |
+| 0.6 | 在 Paperclip 建立公司，設定 OpenClaw adapter | 公司建立成功 |
+
+---
+
+### 9.3 Phase 1：管理閉環
+
+**目標：** CEO 派工 → Agent 執行 → 秘書記錄 → 審查員審核，完整跑通
+
+**上線角色：** CEO/COO、秘書、審查員
+
+| 步驟 | 動作 | 驗收 |
+|---|---|---|
+| 1.1 | 在 Paperclip 建立 CEO/COO agent（OpenClaw adapter） | Agent 出現在 org chart |
+| 1.2 | 設定 CEO 的 system prompt + heartbeat | CEO heartbeat 正常觸發 |
+| 1.3 | 手動建立一個測試任務給 CEO | CEO 能接到任務並回應 |
+| 1.4 | 加入秘書 agent | 秘書能讀取 CEO 產出並做摘要 |
+| 1.5 | 加入審查員 agent | 審查員能審核產出，回傳 pass/revise |
+| 1.6 | 測試完整流程：任務 → CEO 拆 → 秘書記錄 → 審查 | 三個 agent 能協作完成一個任務 |
+| 1.7 | 測試 Discord 通知 | 任務狀態變更推送到 Discord |
+| 1.8 | 測試 HITL | #approvals 收到通知，你能 approve |
+
+**Phase 1 完成標準：**
+- [ ] CEO 能接收指令、拆任務
+- [ ] 秘書能產出 Meeting_Summary 和 State_Diff
+- [ ] 審查員能產出 Review_Report（pass/revise/block）
+- [ ] Discord 通知正常
+- [ ] HITL 審批正常
+- [ ] Mem0 記憶寫入/讀取正常
+
+---
+
+### 9.4 Phase 2：量化研究閉環
+
+**目標：** 完整量化 pipeline，從情報蒐集到回測分析
+
+**上線角色：** 財經情報、市場結構、多方、空方、量化策略、回測工程、資料分析
+
+| 步驟 | 動作 | 驗收 |
+|---|---|---|
+| 2.1 | 加入財經情報研究員，設定每日排程 | 每日自動產出 Finance_Research_Brief |
+| 2.2 | 加入市場結構研究員，設定事件觸發 | 情報完成後自動觸發結構分析 |
+| 2.3 | 加入多方 + 空方研究員 | 結構報告完成後，兩者平行產出報告 |
+| 2.4 | 加入量化策略研究員 | 能收斂多空觀點成 Quant_Strategy_Spec |
+| 2.5 | 測試 Discord 辯論功能 | 多空在 thread 中討論，量化策略主持 |
+| 2.6 | 加入回測工程師 | 能讀取策略規格，產出回測結果 |
+| 2.7 | 加入資料分析員 | 能分析回測結果，產出報告 |
+| 2.8 | 跑一次完整 pipeline | 從盤前情報到最終分析報告完整跑通 |
+| 2.9 | 審查員 review 整個 pipeline | 通過 gate 才算完成 |
+
+**Phase 2 完成標準：**
+- [ ] 量化 pipeline 端對端跑通
+- [ ] 事件觸發鏈正常（一個完成自動觸發下一個）
+- [ ] Discord 辯論能產出有意義的結論
+- [ ] 審查機制正常運作
+- [ ] 每日定時排程正常
+
+---
+
+### 9.5 Phase 3：行銷閉環
+
+**上線角色：** 市場研究員、策略總監、投放成效分析師
+
+| 步驟 | 動作 | 驗收 |
+|---|---|---|
+| 3.1 | 加入市場研究員 | 每日/每週自動產出市場研究 |
+| 3.2 | 加入策略總監 | 能根據市場研究產出品牌/成長策略 |
+| 3.3 | 加入投放成效分析師 | 每日自動產出 KPI 報告 |
+| 3.4 | 測試跨部門對齊會議 | 量化 + 行銷團隊在 Discord 討論 |
+
+---
+
+### 9.6 Phase 4：內容閉環
+
+**上線角色：** 文案撰寫員、創意總監
+
+| 步驟 | 動作 | 驗收 |
+|---|---|---|
+| 4.1 | 加入文案撰寫員 | 能根據策略產出文案 |
+| 4.2 | 加入創意總監 | 能產出視覺 brief |
+| 4.3 | 內容審查流程 | 審查員 review 文案與 brief |
+
+---
+
+### 9.7 Phase 5-6：工程 & 營運化
+
+**Phase 5（依需求）：** 加入前端/後端工程師
+
+**Phase 6（營運化）：**
+- 完整排程矩陣上線
+- 所有 HITL 節點確認
+- 預算監控啟用
+- 每日/每週自動報告穩定
+- 異常告警機制驗證
+
+---
+
+## 第十部分：風險與限制
+
+### 10.1 已知技術限制
+
+| 限制 | 影響 | 緩解方式 |
+|---|---|---|
+| Discord plugin 為社群開發 | 可能缺少官方支援 | 追蹤 repo 更新、準備自行 fork 維護 |
+| Discord thread 最多 10 agents | 大型會議受限 | 拆成小組討論再彙總 |
+| Discord 討論為 2-50 輪 | 超長辯論不適合 | 設定合理 max_rounds，分多次會議 |
+| OpenClaw 曾有安全漏洞（CVE-2026-25253） | RCE 風險 | 保持更新、啟用認證、監控安全公告 |
+| Mem0 記憶可能過時 | Agent 根據過時資訊決策 | 秘書每日壓縮、設定 TTL、定期清理 |
+| AI 模型幻覺 | 產出不正確的資訊 | 審查員把關、交叉驗證、人類最終審核 |
+
+### 10.2 成本估算框架
+
+| 項目 | 計算方式 | 控制手段 |
+|---|---|---|
+| AI API 費用 | per-agent 月預算 × agent 數 | Paperclip budget 功能 |
+| 每次 heartbeat 的 token | 依模型和任務複雜度 | 選擇合適的模型等級 |
+| 每次會議的 token | 參與人數 × 輪數 × 平均回覆長度 | 限制 max_rounds |
+| 記憶讀寫的 token | Mem0 的 embedding + retrieval | 控制記憶大小、壓縮頻率 |
+
+**成本控制建議：**
+- 日常研究類用 research 等級模型（便宜）
+- 只有策略收斂、審查、辯論用 reasoning-heavy（貴但值得）
+- 設定 per-agent 月預算上限，超額需 HITL 批准
+- 會議不要超過 10 輪，大部分 6 輪即可收斂
+
+### 10.3 安全注意事項
+
+| 項目 | 風險 | 措施 |
+|---|---|---|
+| API Key 管理 | 洩露導致費用爆增 | 使用環境變數、不進版本控制 |
+| Agent 權限 | Agent 做超出範圍的事 | 嚴格的 Forbidden 規則 + 工具白名單 |
+| 交易執行 | AI 自動下單造成損失 | HITL 必審 + 策略必須先通過完整 pipeline |
+| 資料安全 | 敏感資訊外洩 | 不在 prompt 中放敏感資料、記憶加密 |
+| Discord 安全 | 未授權存取 | Server 設為私人、Bot 只在指定頻道運作 |
+
+### 10.4 什麼時候該停下來
+
+| 信號 | 動作 |
+|---|---|
+| 月費用超出預期 2 倍 | 暫停非必要 agent，分析原因 |
+| Agent 反覆 revise 超過 5 輪收斂不了 | 人工介入，可能需要調整 prompt 或流程 |
+| 回測結果看起來太好（winrate > 90%） | 100% 是 overfitting，停止並重新檢查 |
+| Agent 產出的品質持續下降 | 檢查記憶是否過時、prompt 是否需要更新 |
+| 安全漏洞通報 | 立即更新或暫停受影響元件 |
+
+---
+
+## 附錄：文件索引
+
+| 文件 | 內容 |
+|---|---|
+| `spec_v3_system_overview.md` | 第一部分：系統總覽 |
+| `spec_v3_org_and_roles.md` | 第二部分：組織架構 + 第三部分：角色定義 |
+| `spec_v3_collaboration.md` | 第四部分：協作模式 |
+| `spec_v3_scheduling_memory_discord.md` | 第五部分：排程 + 第六部分：記憶 + 第七部分：Discord |
+| `spec_v3_schemas.md` | 第八部分：JSON Schema |
+| `spec_v3_rollout_and_risks.md` | 第九部分：上線計畫 + 第十部分：風險與限制 |