chris/KingClawArmy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
KingClawArmy/docs/paperclip_org_plans.md
Chris 6a440973a9 docs: add paperclip org planning guide
2026-04-11 00:56:47 +08:00

11 KiB
Raw Permalink Blame History

KingClawArmy - Paperclip 組織規劃方案

日期：2026-04-11 用途：提供另一個 agent 作為修改依據；本文件定義規劃選項、推薦方案、實作範圍與 review 驗收標準

1. 目的與前提

這份文件的目的不是直接當成 Paperclip package 匯入，而是作為下一位實作 agent 的施工說明書。

Paperclip 需要的不是 docs/ 內的說明稿，而是實際可匯入的 package 結構：

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

組織樹：

董事長
└── 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

組織樹：

董事長
└── 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。

Reference in New Issue View Git Blame Copy Permalink