From 6a440973a99cfef07db976791e9aea603abed743 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 11 Apr 2026 00:56:47 +0800 Subject: [PATCH] docs: add paperclip org planning guide --- docs/INDEX.md | 3 +- docs/paperclip_org_plans.md | 357 ++++++++++++++++++++++++++++++++++++ 2 files changed, 359 insertions(+), 1 deletion(-) create mode 100644 docs/paperclip_org_plans.md diff --git a/docs/INDEX.md b/docs/INDEX.md index a5bc97e..8da4a2e 100644 --- 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 驗收標準 | --- diff --git a/docs/paperclip_org_plans.md b/docs/paperclip_org_plans.md new file mode 100644 index 0000000..7d3fd93 --- /dev/null +++ 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//AGENTS.md +teams//TEAM.md +projects//PROJECT.md +projects//tasks//TASK.md +skills//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//AGENTS.md` | +| Team 定義 | 每個 team 必須有 `teams//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//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//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 --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。