312 lines
7.3 KiB
Markdown
312 lines
7.3 KiB
Markdown
# KingClawArmy - Paperclip Package Review（dev）
|
||
|
||
> 日期：2026-04-11
|
||
> 審查對象：`origin/dev`
|
||
> 初次審查 commit：`43c1770`
|
||
> 追蹤審查 commit：`aceb1ba`
|
||
> 用途：提供另一個 agent 依此修正 Paperclip package；本文件聚焦在匯入後行為與規格一致性
|
||
|
||
---
|
||
|
||
## 1. 結論摘要
|
||
|
||
`dev` branch 已經完成第一版 Paperclip package 骨架，且可通過：
|
||
|
||
```bash
|
||
paperclipai company import <repo> --dry-run --json
|
||
```
|
||
|
||
這代表以下基礎能力已具備：
|
||
|
||
1. repo root 已有 `COMPANY.md`
|
||
2. 已有 `.paperclip.yaml`
|
||
3. 已有 `agents/`、`teams/`、`projects/`、`tasks/`、`skills/` 基本結構
|
||
4. importer 可以成功解析 package
|
||
|
||
第二輪追蹤後，原本的 P1-P4 都已修正完成，包含：
|
||
|
||
1. recurring routine 與 task slug 已對齊
|
||
2. `daily-secretary-digest` 已移到正確 project 目錄
|
||
3. `quant-strategist` 的過大權限已移除
|
||
4. project 的 Paperclip 專屬 metadata 已改由 `.paperclip.yaml` 承載，dry-run 匯入後可正確保留
|
||
|
||
目前剩下 1 個新的 Paperclip 專屬結構問題，建議修完後再視為本輪完成。
|
||
|
||
---
|
||
|
||
## 2. 必修問題
|
||
|
||
### P5. `ceo` agent 的 `role` 不是 Paperclip 預期的 `ceo`
|
||
|
||
**現況**
|
||
|
||
`agents/ceo/AGENTS.md` 目前是：
|
||
|
||
```yaml
|
||
role: manager
|
||
```
|
||
|
||
參考：
|
||
|
||
- `origin/dev:agents/ceo/AGENTS.md` 第 1-7 行
|
||
|
||
**影響**
|
||
|
||
這不是純命名風格問題。Paperclip 內部有多處行為直接依賴：
|
||
|
||
```ts
|
||
agent.role === "ceo"
|
||
```
|
||
|
||
例如：
|
||
|
||
- 公司 branding 變更權限
|
||
- company import/export 等 company portability 權限
|
||
- CEO 專屬任務分派與部分控制面能力
|
||
|
||
參考：
|
||
|
||
- `paperclip/server/src/routes/companies.ts` 第 60-75 行
|
||
- `paperclip/server/src/routes/agents.ts` 第 127-139 行
|
||
|
||
如果匯入後 `ceo` 的 role 仍然是 `manager`，那他雖然因 `.paperclip.yaml` 的 `canCreateAgents: true` 仍保有部分管理能力，但不會被系統視為真正 CEO，會失去部分 CEO-safe 路由與公司層級操作能力。
|
||
|
||
**建議修法**
|
||
|
||
把 `agents/ceo/AGENTS.md` 中的：
|
||
|
||
```yaml
|
||
role: manager
|
||
```
|
||
|
||
改為：
|
||
|
||
```yaml
|
||
role: ceo
|
||
```
|
||
|
||
**建議採用：**
|
||
|
||
直接改成 `role: ceo`
|
||
|
||
---
|
||
|
||
## 3. 已修正問題（追蹤確認）
|
||
|
||
### 已修正 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`
|
||
|
||
**建議採用：**
|
||
|
||
**追蹤結果：**
|
||
|
||
已修正。`origin/dev` 目前的 routine key 已改為 `daily-quant-run`，且 dry-run 匯入結果中 `daily-quant-run.routine` 已正確存在。
|
||
|
||
---
|
||
|
||
### 已修正 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` 的 `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` 已收斂成較乾淨的 base package 內容，project 的 `leadAgentSlug` / `status` 目前改由 `.paperclip.yaml` 承載，且 dry-run 匯入結果可正確保留。
|
||
|
||
---
|
||
|
||
### 已修正 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
|
||
```
|
||
|
||
同時保持：
|
||
|
||
**追蹤結果：**
|
||
|
||
已修正。該檔案已移到：
|
||
|
||
```text
|
||
projects/board-ops/tasks/daily-secretary-digest/TASK.md
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 建議但非阻塞問題
|
||
|
||
### 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` 沒有秘密值與機器相依路徑
|
||
|
||
---
|
||
|
||
## 5. 建議修改順序
|
||
|
||
另一個 agent 建議依照這個順序修：
|
||
|
||
1. 修 P5：把 `agents/ceo/AGENTS.md` 的 `role` 改為 `ceo`
|
||
2. 跑一次 `paperclipai company import --dry-run --json`
|
||
3. 確認匯入後 CEO 具備 company-level portability / branding 等 CEO-safe 權限
|
||
4. 若有需要，再更新 `docs/INDEX.md` 或其他說明文件
|
||
|
||
---
|
||
|
||
## 6. 修正後的驗收標準
|
||
|
||
修完後，至少要確認：
|
||
|
||
1. `agents/ceo/AGENTS.md` 的 frontmatter 為 `role: ceo`
|
||
2. `paperclipai company import --dry-run --json` 仍可成功通過
|
||
3. 匯入後 CEO 在系統中被辨識為真正的 CEO，而不是一般 manager
|
||
4. 文件敘述與 package 實際內容一致
|
||
|
||
---
|
||
|
||
## 7. 給下一位 Agent 的一句話任務說明
|
||
|
||
請修正 `origin/dev` 的 Paperclip package，將 `agents/ceo/AGENTS.md` 的 `role` 改成 `ceo`，確保匯入後 CEO 能取得 Paperclip 的 CEO-safe 行為與公司層級權限；修完後用 `paperclipai company import --dry-run --json` 驗證。
|