docs: add paperclip org planning guide

2026-04-11 00:56:47 +08:00
parent aae5913bf2
commit 6a440973a9
2 changed files with 359 additions and 1 deletions
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -1,6 +1,6 @@
 # KingClawArmy 文件索引

-> 更新日期：2026-04-10
+> 更新日期：2026-04-11

 ---

@@ -9,6 +9,7 @@
 | [company.md](company.md) | 公司定義、組織架構（18 agents / 5 teams）、Agent 完整規格、Skills、.paperclip.yaml 設定、Package 結構 |
 | [pipelines.md](pipelines.md) | 量化 Pipeline 流程、排程定義（8 routines）、每日/每週時間軸、審批機制、模型分級、成本控制、停損信號 |
 | [schemas.md](schemas.md) | 所有 Agent 輸出的 JSON Schema 定義（含信心指數、恐慌指數、進出場建議） |
+| [paperclip_org_plans.md](paperclip_org_plans.md) | Paperclip 導向的組織與人員配置規劃方案，含 3 種落地選項、推薦方案、修改範圍與 review 驗收標準 |

 ---

--- a/docs/paperclip_org_plans.md
+++ b/docs/paperclip_org_plans.md
@@ -0,0 +1,357 @@
+# KingClawArmy - Paperclip 組織規劃方案
+
+> 日期：2026-04-11
+> 用途：提供另一個 agent 作為修改依據；本文件定義規劃選項、推薦方案、實作範圍與 review 驗收標準
+
+---
+
+## 1. 目的與前提
+
+這份文件的目的不是直接當成 Paperclip package 匯入，而是作為下一位實作 agent 的施工說明書。
+
+Paperclip 需要的不是 `docs/` 內的說明稿，而是實際可匯入的 package 結構：
+
+```text
+COMPANY.md
+.paperclip.yaml
+agents/<slug>/AGENTS.md
+teams/<slug>/TEAM.md
+projects/<slug>/PROJECT.md
+projects/<slug>/tasks/<slug>/TASK.md
+skills/<slug>/SKILL.md
+```
+
+因此，下一位 agent 的任務應該是：
+
+1. 保留 `docs/` 作為設計說明文件
+2. 在 repo 根目錄建立真正的 Paperclip company package
+3. 依照本文件選定的組織方案，產出第一版可 `paperclipai company import --dry-run` 通過的結構
+
+---
+
+## 2. Paperclip 導向的設計約束
+
+| 項目 | 約束 |
+|---|---|
+| 公司根檔 | 必須有 repo root 的 `COMPANY.md` |
+| Agent 定義 | 每個 agent 必須有自己的 `agents/<slug>/AGENTS.md` |
+| Team 定義 | 每個 team 必須有 `teams/<slug>/TEAM.md`，且 `manager` 要能解析到真實 agent 檔案 |
+| Project 定義 | pipeline 需要對應到 `PROJECT.md`，不能只寫在說明文件 |
+| Routine 定義 | recurring work 需要 `TASK.md` 標記 `recurring: true`，排程細節再放到 `.paperclip.yaml` |
+| Skills | `AGENTS.md` 內應以 shortname 關聯 skill，`SKILL.md` 保持 Agent Skills 相容 |
+| Runtime 設定 | adapter、env inputs、budgets、permissions、routines 等放在 `.paperclip.yaml` |
+| 溝通模型 | Paperclip V1 偏 task/comment，不是 OpenClaw 那種 session-first 規劃 |
+
+---
+
+## 3. 目前文件狀態摘要
+
+| 項目 | 現況 | 結論 |
+|---|---|---|
+| `docs/company.md` | 已有完整藍圖 | 可當來源稿，但不是 import root |
+| `docs/pipelines.md` | 已有 pipeline 與 routines | 還缺 `PROJECT.md` / `TASK.md` 實體 |
+| `docs/schemas.md` | 已有多數輸出 schema | 可作為 agent instructions 的引用內容 |
+| repo root | 沒有 `COMPANY.md`、`.paperclip.yaml` | 現在不能直接 import |
+| 組織架構 | 18 agents / 5 teams | 當藍圖合理，當第一版上線偏重 |
+| review 流程 | 有定義，但 revise 上限與 review 節點不完全一致 | 修改時要先收斂口徑 |
+
+---
+
+## 4. 規劃方案
+
+### 方案 A：精實上線包
+
+**定位：** 先做出第一個可匯入、可運行、成本可控的 Paperclip package。
+
+**建議啟用角色：**
+
+| Team | Agent | 狀態 |
+|---|---|---|
+| management | `ceo` | active |
+| management | `secretary` | active |
+| management | `reviewer` | active |
+| quant-research | `quant-strategist` | active |
+| quant-research | `finance-researcher` | active |
+| quant-research | `market-structure-researcher` | active |
+| quant-research | `quant-engineer` | active |
+| quant-research | `data-analyst` | active |
+| optional | `xiao-an` | paused |
+
+**總計：** 8 active + 1 optional paused
+
+**組織樹：**
+
+```text
+董事長
+└── ceo
+    ├── secretary
+    ├── reviewer
+    └── quant-strategist
+        ├── finance-researcher
+        ├── market-structure-researcher
+        ├── quant-engineer
+        └── data-analyst
+```
+
+**應建立的 team：**
+
+1. `management`
+2. `quant-research`
+
+**應建立的 project：**
+
+1. `daily-quant-pipeline`
+2. `board-ops`
+
+**應建立的 recurring tasks：**
+
+1. `daily-quant-pipeline` -> assignee `ceo`
+2. `daily-post-market` -> assignee `ceo`
+3. `daily-data-summary` -> assignee `data-analyst`
+4. `daily-secretary-digest` -> assignee `secretary`
+
+**優點：**
+
+1. 最容易先通過 Paperclip import
+2. 組織深度夠用，管理跨度可控
+3. 成本最低，適合先驗證量化閉環
+4. 另一個 agent 修改時影響面最小
+
+**缺點：**
+
+1. 少了 bull/bear 對抗式分析
+2. 行銷與內容團隊尚未進 package
+3. 工程團隊先不落地
+
+**適用情境：**
+
+1. 你想先讓 Paperclip package 匯入成功
+2. 你想先把量化閉環跑通
+3. 你希望 review 範圍小、改動風險低
+
+---
+
+### 方案 B：平衡擴編包
+
+**定位：** 保留完整量化閉環，並放入行銷策略團隊的基礎骨架。
+
+**建議啟用角色：**
+
+| Team | Agent | 狀態 |
+|---|---|---|
+| management | `ceo` | active |
+| management | `secretary` | active |
+| management | `reviewer` | active |
+| quant-research | `quant-strategist` | active |
+| quant-research | `finance-researcher` | active |
+| quant-research | `market-structure-researcher` | active |
+| quant-research | `bullish-researcher` | active |
+| quant-research | `bearish-researcher` | active |
+| quant-research | `quant-engineer` | active |
+| quant-research | `data-analyst` | active |
+| marketing | `strategy-director` | active |
+| marketing | `market-researcher` | active |
+| marketing | `ads-analyst` | paused |
+| optional | `xiao-an` | paused |
+
+**總計：** 12 active + 2 paused
+
+**組織樹：**
+
+```text
+董事長
+└── ceo
+    ├── secretary
+    ├── reviewer
+    ├── quant-strategist
+    │   ├── finance-researcher
+    │   ├── market-structure-researcher
+    │   ├── bullish-researcher
+    │   ├── bearish-researcher
+    │   ├── quant-engineer
+    │   └── data-analyst
+    └── strategy-director
+        ├── market-researcher
+        └── ads-analyst
+```
+
+**應建立的 team：**
+
+1. `management`
+2. `quant-research`
+3. `marketing`
+
+**應建立的 project：**
+
+1. `daily-quant-pipeline`
+2. `market-intel`
+3. `board-ops`
+
+**應建立的 recurring tasks：**
+
+1. 方案 A 的全部 recurring tasks
+2. `morning-market-intel` -> assignee `market-researcher`
+3. `evening-market-intel` -> assignee `market-researcher`
+4. `weekly-market-report` -> assignee `market-researcher`
+
+**優點：**
+
+1. 量化 pipeline 比方案 A 更完整
+2. 行銷 team 先有骨架，不用之後重做 package
+3. 比 18 agent 藍圖更適合先上線
+
+**缺點：**
+
+1. package 複雜度明顯上升
+2. review 範圍變大
+3. 匯入後需要更多 paused/active 狀態管理
+
+**適用情境：**
+
+1. 你希望量化 full pipeline 一次到位
+2. 你預計很快就會接上市場研究與行銷節奏
+3. 你接受另一個 agent 需要改比較多檔案
+
+---
+
+### 方案 C：完整藍圖包
+
+**定位：** 直接把目前 `docs/company.md` 的 18 agents 全部落成 Paperclip package。
+
+**建議啟用角色：**
+
+| Team | Agent | 狀態 |
+|---|---|---|
+| management | `ceo` | active |
+| management | `secretary` | active |
+| management | `reviewer` | active |
+| quant-research | `quant-strategist` | active |
+| quant-research | `finance-researcher` | active |
+| quant-research | `market-structure-researcher` | active |
+| quant-research | `bullish-researcher` | active |
+| quant-research | `bearish-researcher` | active |
+| quant-research | `quant-engineer` | active |
+| quant-research | `data-analyst` | active |
+| marketing | `strategy-director` | active |
+| marketing | `market-researcher` | active |
+| marketing | `ads-analyst` | active |
+| content | `creative-director` | active |
+| content | `copywriter` | active |
+| engineering | `frontend-engineer` | paused |
+| engineering | `backend-engineer` | paused |
+| optional | `xiao-an` | paused |
+
+**總計：** 15 active + 3 paused
+
+**優點：**
+
+1. 與現有藍圖最一致
+2. 未來擴編時不需再補 package 結構
+3. 全公司模型一次成形
+
+**缺點：**
+
+1. 第一版 package 實作成本最高
+2. 很多 agent 只有規格，沒有第一波實際任務
+3. 工程團隊目前沒有真正的 team lead，結構上較勉強
+4. review 與驗收難度最高
+
+**適用情境：**
+
+1. 你要做的是展示型、藍圖型 package
+2. 你接受第一版不是最精實，而是最完整
+3. 另一個 agent 有足夠時間把 package 全部補齊
+
+---
+
+## 5. 推薦方案
+
+**推薦採用：方案 A 作為第一版 import package**
+
+原因：
+
+1. 這是最符合 Paperclip 第一階段匯入需求的方案
+2. 可以先驗證 `COMPANY.md + AGENTS.md + TEAM.md + PROJECT.md + TASK.md + .paperclip.yaml` 的完整鏈路
+3. 量化是目前最清楚、最成熟的閉環，先落地它最划算
+4. 另一個 agent 可以先把結構做好，再逐步擴到方案 B 或方案 C
+
+**推薦 roadmap：**
+
+1. 第一版 import package 採 `方案 A`
+2. 量化 pipeline 穩定後升級到 `方案 B`
+3. 行銷與內容成熟後再收斂成 `方案 C`
+
+---
+
+## 6. 另一個 Agent 的修改範圍
+
+### 必做
+
+| 路徑 | 動作 |
+|---|---|
+| `COMPANY.md` | 新建真正的 company root，frontmatter 採 `agentcompanies/v1` |
+| `.paperclip.yaml` | 新建 Paperclip sidecar，放 adapter、inputs、permissions、routines、status |
+| `agents/<slug>/AGENTS.md` | 為方案 A 中的每個 agent 建立真正 agent 檔 |
+| `teams/management/TEAM.md` | 新建 team package |
+| `teams/quant-research/TEAM.md` | 新建 team package |
+| `projects/daily-quant-pipeline/PROJECT.md` | 新建 project package |
+| `projects/board-ops/PROJECT.md` | 新建 project package |
+| `projects/.../tasks/<slug>/TASK.md` | 為 recurring routines 建立任務檔 |
+| `skills/deep-research/SKILL.md` | 新建相容 skill |
+| `skills/code-reviewer/SKILL.md` | 新建相容 skill |
+
+### 建議做
+
+| 路徑 | 動作 |
+|---|---|
+| `docs/company.md` | 保留為說明稿，但內容要標示「藍圖版」或「未來擴編版」 |
+| `docs/pipelines.md` | 對齊 recurring tasks 與實際 project/task 命名 |
+| `docs/schemas.md` | 對齊第一版 active agents，只保留需要的 schema 或標示 phase |
+| `docs/INDEX.md` | 明確區分「設計文件」與「可匯入 package」 |
+
+### 不建議第一輪做太多
+
+1. 不要第一輪就把 18 agents 全部做成 active
+2. 不要把 OpenClaw 的 session 協定硬塞進 Paperclip runtime 配置
+3. 不要在 `.paperclip.yaml` 複製整份 agent prompt
+4. 不要先做太多機器環境相依設定，例如本機絕對路徑與 secret 值
+
+---
+
+## 7. 具體修改原則
+
+1. `AGENTS.md` frontmatter 只放 agent identity、title、reportsTo、skills 等可攜欄位
+2. agent 的行為規範與 instructions 寫在 `AGENTS.md` body
+3. adapter、model、env inputs、permissions、status、routines 全放 `.paperclip.yaml`
+4. `skills` 在 `AGENTS.md` 內用 shortname，如 `deep-research`、`code-reviewer`
+5. recurring work 先在 `TASK.md` 標 `recurring: true`，排程再由 `.paperclip.yaml` 補
+6. team manager 路徑要用正確的相對路徑，不要沿用 `docs/company.md` 內的示意錯路徑
+7. review revise 上限統一成一個數字，建議固定為 `3`
+8. 若工程團隊暫不落地，第一版 package 不必建立 `engineering` team
+
+---
+
+## 8. Review 驗收標準
+
+未來我 review 時，至少會檢查以下項目：
+
+1. `paperclipai company import <repo> --dry-run` 不再報 `missing COMPANY.md`
+2. root `COMPANY.md` 能被解析，且 `schema`、`slug`、`name` 正確
+3. 所有 `TEAM.md` 的 `manager` 路徑都能解析
+4. 所有 `AGENTS.md` 的 `reportsTo` 與 team 結構一致
+5. recurring routines 都有對應 `TASK.md`
+6. `.paperclip.yaml` 沒有機器相依路徑與 secret 值
+7. active / paused 狀態與本文件選定方案一致
+8. `docs/` 說明稿與真正 package 內容不互相矛盾
+
+---
+
+## 9. 決策建議
+
+如果沒有特別要求一次做完整藍圖，建議直接照以下決策執行：
+
+1. 採用 `方案 A`
+2. 將 `方案 B` 寫成後續擴編計畫
+3. 將 `方案 C` 保留在 `docs/company.md` 作為最終藍圖
+
+這樣最符合 Paperclip 的第一波落地方式，也最方便之後讓我做結構與合理性 review。