diff --git a/docs/INDEX.md b/docs/INDEX.md index 875503f..f9f699e 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -30,6 +30,7 @@ skills/*/SKILL.md ← 2 個 skills | [pipelines.md](pipelines.md) | 所有 Pipeline 流程、排程定義、審批機制、模型分級、成本控制 | | [schemas.md](schemas.md) | 所有 Agent 輸出的 JSON Schema 定義(含信心指數、恐慌指數、進出場建議) | | [paperclip_org_plans.md](paperclip_org_plans.md) | 組織規劃方案(A/B/C)、推薦方案、修改範圍與 review 驗收標準 | +| [paperclip_dev_review_2026-04-11.md](paperclip_dev_review_2026-04-11.md) | 第一版 Paperclip package 審查備忘錄,列出必修問題、建議修法與驗收標準 | --- diff --git a/docs/paperclip_dev_review_2026-04-11.md b/docs/paperclip_dev_review_2026-04-11.md new file mode 100644 index 0000000..a5bde01 --- /dev/null +++ b/docs/paperclip_dev_review_2026-04-11.md @@ -0,0 +1,240 @@ +# KingClawArmy - Paperclip Package Review(dev) + +> 日期:2026-04-11 +> 審查對象:`origin/dev` +> 審查 commit:`43c1770` +> 用途:提供另一個 agent 依此修正 Paperclip package;本文件聚焦在匯入後行為與規格一致性 + +--- + +## 1. 結論摘要 + +`dev` branch 已經完成第一版 Paperclip package 骨架,且可通過: + +```bash +paperclipai company import --dry-run --json +``` + +這代表以下基礎能力已具備: + +1. repo root 已有 `COMPANY.md` +2. 已有 `.paperclip.yaml` +3. 已有 `agents/`、`teams/`、`projects/`、`tasks/`、`skills/` 基本結構 +4. importer 可以成功解析 package + +但目前仍有幾個會影響「匯入後是否符合設計意圖」的問題,需要先修再進下一步。 + +--- + +## 2. 必修問題 + +### P1. 07:30 主排程沒有綁到真正的 recurring task + +**現況** + +- `.paperclip.yaml` 的 routine key:`daily-quant-pipeline` +- recurring task slug:`daily-quant-run` + +參考: + +- `origin/dev:.paperclip.yaml` 第 85-91 行 +- `origin/dev:projects/daily-quant-pipeline/tasks/daily-quant-run/TASK.md` + +**影響** + +`paperclipai company import --dry-run --json` 的結果顯示: + +- `daily-quant-run` 的 `routine` 是 `null` + +也就是說,這個每日量化啟動任務匯入後不會自動被排程觸發。 + +**建議修法** + +二選一,選一種即可: + +1. 把 routine key 改成 `daily-quant-run` +2. 把 task slug 改成 `daily-quant-pipeline` + +**建議採用:** + +保留 task 檔案語義,將 `.paperclip.yaml` 的 routine key 改成 `daily-quant-run`,與 `TASK.md` slug 對齊。 + +--- + +### P2. `quant-strategist` 權限過大 + +**現況** + +在 `.paperclip.yaml` 中: + +```yaml +agents: + quant-strategist: + permissions: + canCreateAgents: true +``` + +**影響** + +在 Paperclip 中,`canCreateAgents` 比「可分派工作」更高,是接近 agent creator / manager 級別的權限。 + +目前設計目標只是讓策略師主導量化 pipeline,不是讓他具備建立 agent 的高權限。 + +**建議修法** + +1. 若只是要策略師能主導任務分配,先移除 `canCreateAgents: true` +2. 若未來真的需要額外委派能力,再由 Paperclip 的顯式 permission / grant 機制處理 + +**建議採用:** + +先移除 `quant-strategist.permissions.canCreateAgents` + +--- + +### P3. `PROJECT.md` 的 owner / status 意圖沒有被保留下來 + +**現況** + +兩個 project 使用了: + +```yaml +leadAgentSlug: ... +status: active +``` + +參考: + +- `origin/dev:projects/daily-quant-pipeline/PROJECT.md` +- `origin/dev:projects/board-ops/PROJECT.md` + +**影響** + +實際 dry-run 匯入結果顯示: + +- `leadAgentSlug: null` +- `status: null` + +也就是說,這兩個欄位現在雖然寫在檔案裡,但 importer 沒有保留成有效 project metadata。 + +**建議修法** + +1. 先把 `PROJECT.md` 保持為 vendor-neutral、最小可攜欄位 +2. 若需要 Paperclip 專屬 fidelity,改放到 `.paperclip.yaml` 或 `metadata.paperclip` +3. project owner 可優先改成 base spec 較接近的欄位,例如 `owner` + +**建議採用:** + +- `PROJECT.md` 只保留:`name`、`description`、`slug` +- project owner / runtime 狀態改放進 `.paperclip.yaml` + +--- + +### P4. `daily-secretary-digest` 放在錯的 project 資料夾底下 + +**現況** + +檔案位置: + +```text +projects/daily-quant-pipeline/tasks/daily-secretary-digest/TASK.md +``` + +但 frontmatter 內容是: + +```yaml +project: board-ops +``` + +**影響** + +雖然 importer 目前會依 frontmatter 匯入成功,但這違反 package 本身的資料夾慣例,之後非常容易造成: + +1. 維護時誤判任務歸屬 +2. reviewer 看目錄就被誤導 +3. 後續 agent 做批次修改時把任務放錯地方 + +**建議修法** + +將該檔案移到: + +```text +projects/board-ops/tasks/daily-secretary-digest/TASK.md +``` + +同時保持: + +```yaml +project: board-ops +``` + +--- + +## 3. 建議但非阻塞問題 + +### S1. 第一版 package 已經不是方案 A,而是接近量化完整版 + +目前 `dev` branch 實際包含: + +1. 管理團隊 3 位 +2. 量化團隊 7 位 +3. `xiao-an` 1 位 paused + +也就是: + +- 10 active +- 1 paused + +這已經比原規劃文件的方案 A 更接近「完整量化版」。 + +**建議** + +1. 更新 `docs/INDEX.md` 與相關說明,明確寫成「第一版 package = 管理 + 完整量化團隊」 +2. 不要再沿用「精實版 8 active」的敘述,避免文檔口徑不一致 + +--- + +### S2. 可以補一份簡短的 import 驗收說明 + +建議在 `docs/` 追加一段簡單說明,讓之後的人知道該怎麼驗: + +```bash +paperclipai company import . --dry-run --json +``` + +最低驗收應包含: + +1. 沒有 `missing COMPANY.md` +2. 所有 recurring task 都有對應 routine +3. projects 與 tasks 的目錄與 frontmatter 一致 +4. `.paperclip.yaml` 沒有秘密值與機器相依路徑 + +--- + +## 4. 建議修改順序 + +另一個 agent 建議依照這個順序修: + +1. 修 P1:對齊 routine key 與 recurring task slug +2. 修 P4:把 `daily-secretary-digest` 移到正確目錄 +3. 修 P2:收斂 `quant-strategist` 權限 +4. 修 P3:整理 `PROJECT.md` 與 `.paperclip.yaml` 的 project metadata 分工 +5. 跑一次 `paperclipai company import --dry-run --json` +6. 更新 `docs/INDEX.md` 或其他說明文件,讓口徑一致 + +--- + +## 5. 修正後的驗收標準 + +修完後,至少要確認: + +1. `daily-quant-run` 在 dry-run 結果中不再是 `routine: null` +2. `daily-secretary-digest` 檔案實體位於 `projects/board-ops/tasks/` +3. `quant-strategist` 不再持有不必要的高權限 +4. `PROJECT.md` 中不再放 importer 會直接吃掉卻不保留的欄位,或已明確改為 `.paperclip.yaml` 承載 +5. 文件敘述與 package 實際內容一致 + +--- + +## 6. 給下一位 Agent 的一句話任務說明 + +請修正 `origin/dev` 的 Paperclip package,使 recurring routines 能正確綁定到任務、project 與 task 的目錄/metadata 一致、並移除不必要的高權限設定;修完後用 `paperclipai company import --dry-run --json` 驗證。