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

- spec 檔案重新命名去除 v4 前綴 - 更新所有內部交叉引用 - 新增 migration_to_paperclip.md：概念對照、目標結構、Agent 定義、排程轉換 - INDEX.md 標記 OpenClaw 時期文檔為遷移參考用 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-10 15:32:07 +00:00
parent e44b959c85
commit 253f38a75e
8 changed files with 295 additions and 55 deletions
--- a/docs/migration_to_paperclip.md
+++ 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