358 lines
11 KiB
Markdown
358 lines
11 KiB
Markdown
# 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。
|