From 253f38a75e1282dde38a445893c01463311654cc Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 10 Apr 2026 15:32:07 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=A7=BB=E9=99=A4=20v4=20=E7=89=88?= =?UTF-8?q?=E8=99=9F=E5=91=BD=E5=90=8D=EF=BC=8C=E6=96=B0=E5=A2=9E=20Paperc?= =?UTF-8?q?lip=20=E9=81=B7=E7=A7=BB=E8=A6=8F=E5=8A=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - spec 檔案重新命名去除 v4 前綴 - 更新所有內部交叉引用 - 新增 migration_to_paperclip.md：概念對照、目標結構、Agent 定義、排程轉換 - INDEX.md 標記 OpenClaw 時期文檔為遷移參考用 Co-Authored-By: Claude Opus 4.6 --- docs/INDEX.md | 69 +++-- docs/agent_roster.md | 3 +- docs/migration_to_paperclip.md | 250 ++++++++++++++++++ ...ocol.md => spec_collaboration_protocol.md} | 4 +- ...org_and_roles.md => spec_org_and_roles.md} | 0 ...and_risks.md => spec_rollout_and_risks.md} | 10 +- ...ng_memory.md => spec_scheduling_memory.md} | 7 +- ...em_overview.md => spec_system_overview.md} | 7 +- 8 files changed, 295 insertions(+), 55 deletions(-) create mode 100644 docs/migration_to_paperclip.md rename docs/spec/{spec_v4_collaboration_protocol.md => spec_collaboration_protocol.md} (98%) rename docs/spec/{spec_v4_org_and_roles.md => spec_org_and_roles.md} (100%) rename docs/spec/{spec_v4_rollout_and_risks.md => spec_rollout_and_risks.md} (93%) rename docs/spec/{spec_v4_collaboration_scheduling_memory.md => spec_scheduling_memory.md} (92%) rename docs/spec/{spec_v4_system_overview.md => spec_system_overview.md} (96%) diff --git a/docs/INDEX.md b/docs/INDEX.md index a1ed65f..b93dac5 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -1,34 +1,45 @@ # KingClawArmy 文件索引 -> 版本：v4.1 | 更新日期：2026-04-10 +> 更新日期：2026-04-10 --- -## 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_protocol.md](spec/spec_v4_collaboration_protocol.md) | **協作協定**：Message Envelope、Intent 類型、Pipeline 架構（策略師主導）、spawn/send 規則、輸出 Schema、Review Gate、HITL、錯誤處理 | -| [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）、風險限制、成本控制、停損信號 | +| [migration_to_paperclip.md](migration_to_paperclip.md) | **OpenClaw → Paperclip 遷移規劃**：概念對照、目標結構、Agent 定義、排程轉換、待確認事項 | --- -## guides/ — 實作指南 - -實際操作時的參考手冊，涵蓋 OpenClaw 設定方式與工具使用。 +## spec/ — 系統規格（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 行為**：maxSpawnDepth 工具權限、判斷規則、常見錯誤 | -| [guide_tools_skills.md](guides/guide_tools_skills.md) | **MCP Tools & Skills 配置**：每個角色的外部工具/技能、安裝方式、安全注意事項 | -| [agent_roster.md](agent_roster.md) | 全體 Agent 花名冊：職稱、代號、模型、狀態、輸出格式、工具/技能配置 | +| [spec_system_overview.md](spec/spec_system_overview.md) | 系統目標、設計原則、整體架構 | +| [spec_org_and_roles.md](spec/spec_org_and_roles.md) | 組織架構、Agent 清單（15~17 agents）、各角色定義 | +| [spec_collaboration_protocol.md](spec/spec_collaboration_protocol.md) | 協作協定：Message Envelope、Pipeline 架構、輸出 Schema、Review Gate、HITL | +| [spec_scheduling_memory.md](spec/spec_scheduling_memory.md) | 排程觸發、記憶架構、Discord Server 結構 | +| [spec_rollout_and_risks.md](spec/spec_rollout_and_risks.md) | 上線計畫、風險限制、成本控制 | + +--- + +## guides/ — 實作指南（OpenClaw 時期，遷移參考用） + +| 文件 | 內容 | +|---|---| +| [guide_openclaw_config.md](guides/guide_openclaw_config.md) | openclaw.json 結構、Discord 接入、Gateway 管理 | +| [guide_workspace_files.md](guides/guide_workspace_files.md) | 8 個 Workspace 設定檔用途 | +| [guide_sessions_tools.md](guides/guide_sessions_tools.md) | sessions_spawn / sessions_send 行為與規則 | +| [guide_tools_skills.md](guides/guide_tools_skills.md) | MCP Tools & Skills 配置 | + +--- + +## 花名冊 + +| 文件 | 內容 | +|---|---| +| [agent_roster.md](agent_roster.md) | 全體 Agent 花名冊：職稱、代號、模型、狀態、輸出格式、工具配置 | --- @@ -36,22 +47,8 @@ | Phase | 說明 | 狀態 | |---|---|---| -| Phase 0 | 基礎設施（OpenClaw + Discord） | ✅ 完成 | -| Phase 1 | 管理閉環（執行長 + 秘書 + 審查員） | ✅ 完成 | -| Phase 2 | 量化閉環（7 agents） | ✅ 完成 | -| Phase 3 | 行銷閉環（3 agents） | 待開始 | -| Phase 4 | 內容閉環（2 agents） | 待開始 | -| Phase 5 | 工程團隊（依需求） | 待開始 | - ---- - -## v4.0 → v4.1 主要變更 - -| 變更 | 說明 | -|---|---| -| 新增協作協定 | Message Envelope + Intent 取代自由文字溝通 | -| Pipeline 改由策略師主導 | CEO 只管啟動和例外，策略師 own 量化 pipeline | -| 修正 spawn/send 行為 | 釐清 maxSpawnDepth、sessions_send 不授權給子 agent | -| 新增輸出 Schema | 每個 agent 的 JSON 輸出格式定義 | -| 新增工具/技能配置 | 每個角色的 MCP Tools + Skills 對照表 | -| Standing Orders → Lobster DSL | Pipeline 流程改用結構化定義 | +| 遷移至 Paperclip | 建立 company package、匯入 agent 定義 | 規劃中 | +| 管理團隊上線 | 執行長 + 秘書 + 審查員 | 待開始 | +| 量化團隊上線 | 7 agents | 待開始 | +| 行銷團隊上線 | 3 agents | 待開始 | +| 內容團隊上線 | 2 agents | 待開始 | diff --git a/docs/agent_roster.md b/docs/agent_roster.md index 30d5452..7390990 100644 --- a/docs/agent_roster.md +++ b/docs/agent_roster.md @@ -1,7 +1,6 @@ # KingClawArmy Agent 花名冊 -> 更新日期：2026-04-10 -> 版本：v4.1（新增工具/技能配置、修正 pipeline 流程） +> 更新日期：2026-04-10 --- diff --git a/docs/migration_to_paperclip.md b/docs/migration_to_paperclip.md new file mode 100644 index 0000000..2067215 --- /dev/null +++ b/docs/migration_to_paperclip.md @@ -0,0 +1,250 @@ +# KingClawArmy - OpenClaw 到 Paperclip 遷移規劃 + +> 日期：2026-04-10 +> 狀態：規劃中（尚未執行） + +--- + +## 1. 為什麼遷移 + +OpenClaw 在架構流程管理上的不足已成為瓶頸。Paperclip 提供： + +- **結構化公司組織**：Company → Team → Agent 層級清晰 +- **標準化資料格式**：Agent Companies Spec（agentcompanies/v1），可攜式 markdown package +- **內建任務管理**：Issues、Projects、Goals 三層架構，支援 atomic checkout +- **排程系統**：Routines + cron，取代手動 cron 設定 +- **匯入匯出**：`paperclipai company import/export`，支援 GitHub URL + +--- + +## 2. 概念對照表 + +| OpenClaw 概念 | Paperclip 對應 | 說明 | +|---|---|---| +| `openclaw.json` agents 陣列 | `COMPANY.md` + `agents/*/AGENTS.md` | Agent 定義從集中式 JSON 變成分散式 markdown | +| `SOUL.md` + `IDENTITY.md` | `AGENTS.md` body | 人格、角色、行為規範合併到 AGENTS.md 內文 | +| `AGENTS.md`（OpenClaw 版） | `AGENTS.md` body | 操作程序、輸出格式定義放在 body | +| Agent 分組（管理/量化/行銷/內容） | `teams/*/TEAM.md` | 正式的 team 結構 | +| Agent 間上下級（CEO → 策略師 → 研究員） | `reportsTo` 欄位 | 形成嚴格的回報樹 | +| `cron add --agent` | `.paperclip.yaml` routines | 帶 timezone 的結構化排程 | +| MCP Tools / Skills | `skills/*/SKILL.md` | 遵循 Agent Skills spec | +| Standing Orders / Lobster DSL | Projects + Tasks | 用 project 定義流程，task 定義步驟 | +| `MEMORY.md` + daily notes | 從頭開始 | 不遷移舊記憶 | +| Discord bindings | `.paperclip.yaml` adapter config | 待確認 Paperclip Discord 整合方式 | +| `HEARTBEAT.md` | routines（recurring tasks） | 轉為排程任務 | +| `USER.md` | 不需要 | Paperclip 有自己的 user context | +| `TOOLS.md` | skills 引用 | 工具指南整合到 skills 或 agent instructions | +| Message Envelope / Intent | Paperclip 內建任務流 | 不需要自訂 envelope，用 issue 流轉 | +| Review Gate | Approval Requests | Paperclip 內建審批機制 | +| HITL Discord @mention | Paperclip approval + 外部通知 | 待確認整合方式 | + +--- + +## 3. 目標 Paperclip Package 結構 + +``` +kingclawarmy/ +├── COMPANY.md +├── .paperclip.yaml +│ +├── agents/ +│ ├── ceo/AGENTS.md +│ ├── secretary/AGENTS.md +│ ├── reviewer/AGENTS.md +│ ├── finance-researcher/AGENTS.md +│ ├── market-structure-researcher/AGENTS.md +│ ├── bullish-researcher/AGENTS.md +│ ├── bearish-researcher/AGENTS.md +│ ├── quant-strategist/AGENTS.md +│ ├── quant-engineer/AGENTS.md +│ ├── data-analyst/AGENTS.md +│ ├── market-researcher/AGENTS.md +│ ├── strategy-director/AGENTS.md +│ ├── ads-analyst/AGENTS.md +│ ├── copywriter/AGENTS.md +│ ├── creative-director/AGENTS.md +│ └── xiao-an/AGENTS.md +│ +├── teams/ +│ ├── management/TEAM.md +│ ├── quant-research/TEAM.md +│ ├── marketing/TEAM.md +│ └── content/TEAM.md +│ +├── projects/ +│ ├── daily-quant-pipeline/PROJECT.md +│ ├── market-intel/PROJECT.md +│ └── ads-tracking/PROJECT.md +│ +├── skills/ +│ ├── deep-research/SKILL.md +│ ├── code-reviewer/SKILL.md +│ └── seo-blog-writer/SKILL.md +│ +└── tasks/ + └── (依 project 建立初始 seed tasks) +``` + +--- + +## 4. Agent 定義對照（16 agents） + +### 4.1 管理團隊 + +| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | +|---|---|---|---|---|---| +| `ceo` | 執行長 | CEO/COO | `null` | reasoning-heavy | — | +| `secretary` | 秘書 | Secretary | `ceo` | general | — | +| `reviewer` | 審查員 | Reviewer | `ceo` | reasoning-heavy | — | + +### 4.2 量化研究團隊 + +| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | +|---|---|---|---|---|---| +| `finance-researcher` | 財經情報研究員 | Finance Intelligence Researcher | `quant-strategist` | research | deep-research | +| `market-structure-researcher` | 市場結構研究員 | Market Structure Researcher | `quant-strategist` | reasoning-heavy | deep-research | +| `bullish-researcher` | 多方研究員 | Bullish Researcher | `quant-strategist` | reasoning-heavy | — | +| `bearish-researcher` | 空方研究員 | Bearish Researcher | `quant-strategist` | reasoning-heavy | — | +| `quant-strategist` | 量化策略師 | Quant Strategist | `ceo` | reasoning-heavy | — | +| `quant-engineer` | 回測工程師 | Quant Engineer | `quant-strategist` | coder | code-reviewer | +| `data-analyst` | 資料分析師 | Data Analyst | `quant-strategist` | general | deep-research | + +### 4.3 行銷策略團隊 + +| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | +|---|---|---|---|---|---| +| `market-researcher` | 市場研究員 | Market Researcher | `strategy-director` | research | deep-research | +| `strategy-director` | 策略總監 | Strategy Director | `ceo` | reasoning-heavy | — | +| `ads-analyst` | 投放分析師 | Ads Performance Analyst | `strategy-director` | general | — | + +### 4.4 內容創意團隊 + +| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | +|---|---|---|---|---|---| +| `copywriter` | 文案撰寫員 | Copywriter | `creative-director` | creative | seo-blog-writer | +| `creative-director` | 創意總監 | Creative Director | `ceo` | creative | — | + +### 4.5 閒聊 + +| Agent Slug | 名稱 | Title | reportsTo | Model Tier | Skills | +|---|---|---|---|---|---| +| `xiao-an` | 小安 | — | `ceo` | general | — | + +--- + +## 5. Team 定義 + +| Team Slug | 名稱 | Manager | 成員 | +|---|---|---|---| +| `management` | 管理團隊 | `ceo` | secretary, reviewer | +| `quant-research` | 量化研究團隊 | `quant-strategist` | finance-researcher, market-structure-researcher, bullish-researcher, bearish-researcher, quant-engineer, data-analyst | +| `marketing` | 行銷策略團隊 | `strategy-director` | market-researcher, ads-analyst | +| `content` | 內容創意團隊 | `creative-director` | copywriter | + +--- + +## 6. 排程（Routines）轉換 + +以下 OpenClaw cron 轉為 `.paperclip.yaml` routines： + +| Routine Slug | 原 OpenClaw cron | Paperclip cron | Agent | 說明 | +|---|---|---|---|---| +| `daily-quant-pipeline` | `30 7 * * 1-5` | `30 7 * * 1-5` | ceo | 盤前啟動量化 pipeline | +| `daily-post-market` | `30 18 * * 1-5` | `30 18 * * 1-5` | ceo | 盤後情報整理 | +| `daily-market-intel` | `0 10 * * *` | `0 10 * * *` | market-researcher | 每日市場情報 | +| `weekly-market-report` | `0 9 * * 1` | `0 9 * * 1` | market-researcher | 每週市場分析 | +| `daily-ads-check` | `30 9 * * *` | `30 9 * * *` | ads-analyst | 每日投放 KPI | +| `daily-data-summary` | `0 20 * * *` | `0 20 * * *` | data-analyst | 每日資料摘要 | +| `weekly-data-report` | `0 10 * * 1` | `0 10 * * 1` | data-analyst | 每週數據報告 | + +時區統一使用 `Asia/Taipei`。 + +--- + +## 7. AGENTS.md 內容結構規劃 + +每個 agent 的 `AGENTS.md` 將包含： + +```markdown +--- +name: 執行長 +title: CEO/COO +reportsTo: null +skills: [] +role: manager +--- + +## Mission + +接收董事長指令，拆解任務，分派給 sub-agent，追蹤進度，收斂結果。 + +## Scope + +- 派工、溝通、讀取所有 agent 產出 +- 發起審批流程 +- 組裝決策包 + +## Forbidden + +- 不直接寫文案 / 程式 / 部署 / 做研究 + +## 輸出格式 + +### Task_Spec.json +（schema 定義） + +### Final_Decision_Packet.json +（schema 定義） + +## 行為規範 + +- 只在職權範圍內行動 +- 缺少必要資訊時，回傳 missing_fields 清單 +- 遇到衝突、不確定、高風險時，上報而非猜測 +- 輸出必須遵循指定的 JSON schema +``` + +來源合併方式： +- `IDENTITY.md` 的 name, emoji, role → frontmatter +- `SOUL.md` 的 personality, mission, forbidden → body +- `AGENTS.md`（OpenClaw 版）的操作程序、輸出格式 → body + +--- + +## 8. 待確認事項 + +| 項目 | 問題 | 影響 | +|---|---|---| +| Discord 整合 | Paperclip 是否支援 Discord adapter？或需要用 http/process adapter 串接？ | 影響 .paperclip.yaml 的 adapter 設定 | +| Pipeline 流程 | Paperclip 的 project/task 能否表達 sequential + parallel 的 pipeline？ | 可能需要用 agent instructions 搭配 task 依賴關係 | +| 審批機制 | Paperclip 的 approval request 能否對接 Discord 通知？ | HITL 流程設計 | +| 模型設定 | Paperclip adapter 支援哪些 model provider？ | 影響 adapter type 選擇 | +| 跨 agent 記憶 | Paperclip 是否有跨 agent 記憶搜尋？ | 影響秘書和策略師的運作方式 | +| 工程團隊 | 是否要在初始 package 中包含？ | 可以先不建，之後 import 追加 | + +--- + +## 9. 執行步驟 + +### Phase A：建立 Package（本次目標） + +1. 完成 Paperclip onboard +2. 用 `company-creator` 或手動建立 company package 目錄 +3. 寫 COMPANY.md + .paperclip.yaml +4. 建立 4 個 team +5. 建立 16 個 agent（先建管理團隊 → 量化 → 行銷 → 內容） +6. 建立 skills +7. 用 `paperclipai company import` 匯入 + +### Phase B：驗證 + +1. 確認組織架構正確（reportsTo 樹） +2. 測試每個 agent 能正常回應 +3. 設定排程 +4. 跑一次量化 pipeline 端對端測試 + +### Phase C：調整 + +1. 根據測試結果調整 agent instructions +2. 補充 project + task seed +3. 視需要新增 skills diff --git a/docs/spec/spec_v4_collaboration_protocol.md b/docs/spec/spec_collaboration_protocol.md similarity index 98% rename from docs/spec/spec_v4_collaboration_protocol.md rename to docs/spec/spec_collaboration_protocol.md index 145baf6..d8d3f6f 100644 --- a/docs/spec/spec_v4_collaboration_protocol.md +++ b/docs/spec/spec_collaboration_protocol.md @@ -1,9 +1,7 @@ # KingClawArmy - 第四部分：Agent 協作協定 -> 版本：v4.1 > 日期：2026-04-10 -> 狀態：取代 v4.0 協作章節 -> 變更：重新定義協作模式、新增 Message Envelope、修正 spawn/send 行為、Pipeline 改由策略師主導 +> 狀態：定稿（遷移至 Paperclip 前的參考版本） --- diff --git a/docs/spec/spec_v4_org_and_roles.md b/docs/spec/spec_org_and_roles.md similarity index 100% rename from docs/spec/spec_v4_org_and_roles.md rename to docs/spec/spec_org_and_roles.md diff --git a/docs/spec/spec_v4_rollout_and_risks.md b/docs/spec/spec_rollout_and_risks.md similarity index 93% rename from docs/spec/spec_v4_rollout_and_risks.md rename to docs/spec/spec_rollout_and_risks.md index 79190a6..e18478a 100644 --- a/docs/spec/spec_v4_rollout_and_risks.md +++ b/docs/spec/spec_rollout_and_risks.md @@ -135,8 +135,8 @@ JSON Schema 定義各 agent 產出格式，與系統架構無關（純資料格 | 文件 | 內容 | |---|---| -| `spec_v4_system_overview.md` | 第一部分：系統總覽 | -| `spec_v4_org_and_roles.md` | 第二、三部分：組織架構 + 角色定義 | -| `spec_v4_collaboration_scheduling_memory.md` | 第四~七部分：協作 + 排程 + 記憶 + Discord | -| `spec_v4_rollout_and_risks.md` | 第八~十部分：Schema + 上線 + 風險 | -| `spec_v3_schemas.md` | JSON Schema（v3 版沿用） | +| `spec_system_overview.md` | 第一部分：系統總覽 | +| `spec_org_and_roles.md` | 第二、三部分：組織架構 + 角色定義 | +| `spec_collaboration_protocol.md` | 第四部分：協作協定 | +| `spec_scheduling_memory.md` | 第五~七部分：排程 + 記憶 + Discord | +| `spec_rollout_and_risks.md` | 第八~十部分：Schema + 上線 + 風險 | diff --git a/docs/spec/spec_v4_collaboration_scheduling_memory.md b/docs/spec/spec_scheduling_memory.md similarity index 92% rename from docs/spec/spec_v4_collaboration_scheduling_memory.md rename to docs/spec/spec_scheduling_memory.md index dbaad85..6a8b318 100644 --- a/docs/spec/spec_v4_collaboration_scheduling_memory.md +++ b/docs/spec/spec_scheduling_memory.md @@ -1,14 +1,11 @@ # KingClawArmy - 第五部分：排程與觸發 & 第六部分：記憶 & 第七部分：Discord -> 版本：v4.1 > 日期：2026-04-10 -> 狀態：協作模式已獨立至 [spec_v4_collaboration_protocol.md](spec_v4_collaboration_protocol.md) +> 狀態：定稿（遷移至 Paperclip 前的參考版本） --- -> **注意：** 原第四部分「協作模式」已重寫並移至獨立文件： -> **[spec_v4_collaboration_protocol.md](spec_v4_collaboration_protocol.md)** -> 包含：Message Envelope、Intent 類型、Pipeline 架構、spawn/send 規則、輸出 Schema、Review Gate、HITL 節點 +> **注意：** 協作模式已獨立至 **[spec_collaboration_protocol.md](spec_collaboration_protocol.md)** --- diff --git a/docs/spec/spec_v4_system_overview.md b/docs/spec/spec_system_overview.md similarity index 96% rename from docs/spec/spec_v4_system_overview.md rename to docs/spec/spec_system_overview.md index 436cf14..3704abd 100644 --- a/docs/spec/spec_v4_system_overview.md +++ b/docs/spec/spec_system_overview.md @@ -1,9 +1,8 @@ -# KingClawArmy AI Agent Team - 系統規格書 v4 +# KingClawArmy AI Agent Team - 系統規格書 -> 版本：v4.0 > 日期：2026-04-09 -> 狀態：初版定稿 -> 前版差異：v3 為 Paperclip + Discord + Mem0 多系統架構，v4 簡化為純 OpenClaw 架構 +> 狀態：定稿（遷移至 Paperclip 前的參考版本） +> 備註：原為純 OpenClaw 架構，現已決定遷移至 Paperclip ---