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

docs: 移除 v4 版號命名，新增 Paperclip 遷移規劃

Browse Source 
- spec 檔案重新命名去除 v4 前綴
- 更新所有內部交叉引用
- 新增 migration_to_paperclip.md：概念對照、目標結構、Agent 定義、排程轉換
- INDEX.md 標記 OpenClaw 時期文檔為遷移參考用

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Chris
2026-04-10 15:32:07 +00:00
parent e44b959c85
commit 253f38a75e
8 changed files with 295 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/INDEX.md
View File

@@ -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 | 待開始 |

1
docs/agent_roster.md
View File

@@ -1,7 +1,6 @@
# KingClawArmy Agent 花名冊
> 更新日期：2026-04-10
> 版本：v4.1（新增工具/技能配置、修正 pipeline 流程）
---

250
docs/migration_to_paperclip.md Normal file
View File

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

4
docs/spec/spec_v4_collaboration_protocol.md → docs/spec/spec_collaboration_protocol.md
View File

@@ -1,9 +1,7 @@
# KingClawArmy - 第四部分：Agent 協作協定
> 版本：v4.1
> 日期：2026-04-10
> 狀態：取代 v4.0 協作章節
> 變更：重新定義協作模式、新增 Message Envelope、修正 spawn/send 行為、Pipeline 改由策略師主導
> 狀態：定稿（遷移至 Paperclip 前的參考版本）
---

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

10
docs/spec/spec_v4_rollout_and_risks.md → docs/spec/spec_rollout_and_risks.md
View File

@@ -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 + 上線 + 風險 |

7
docs/spec/spec_v4_collaboration_scheduling_memory.md → docs/spec/spec_scheduling_memory.md
View File

@@ -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)**
---

7
docs/spec/spec_v4_system_overview.md → docs/spec/spec_system_overview.md
View File

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