# 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