438 lines
14 KiB
Markdown
438 lines
14 KiB
Markdown
# KingClawArmy - Agent / Skills Review（dev）
|
||
|
||
> 日期：2026-04-11
|
||
> 審查對象：`origin/dev`
|
||
> 初次審查 commit：`ced587c`
|
||
> 追蹤審查 commit：`ee06e6d`
|
||
> 用途：檢查 Agent 配置、Skills 完整度、Paperclip 匯入相容性與 runtime 落地程度
|
||
|
||
---
|
||
|
||
## 1. 結論摘要
|
||
|
||
這一輪 `dev` branch 在 agent / skills 層有明顯進展：
|
||
|
||
1. agent 的 `skills:` 配置已大幅補齊
|
||
2. `skills/` 目錄已有大量實體 `SKILL.md`
|
||
3. `docs/agent-skill-mapping.md`、`docs/skills-inventory.md`、`docs/mcp-plan.md` 已開始補文檔
|
||
|
||
第二輪追蹤後，前一輪的 P1-P6 已大多修正完成：
|
||
|
||
1. skills 已補明確 `slug`
|
||
2. `AGENTS.md` 的 skill 參照已與匯入後 slug 對齊
|
||
3. Edge skills 不再撞成單一 `edge`
|
||
4. `.mcp.json` 已進 repo
|
||
5. 文檔已改口徑為摘要版 skills
|
||
6. skills 統計數量已更新
|
||
|
||
目前仍有 2 個「完整度」層級的缺口，但已不是前一輪那種會直接造成 import warning 的 blocker。
|
||
|
||
我實際用：
|
||
|
||
```bash
|
||
paperclipai company import <repo> --dry-run --json
|
||
```
|
||
|
||
第一次審查時，package 雖然仍可匯入，但有一批與 skills 相關的 warning，顯示：
|
||
|
||
1. 多個 `AGENTS.md` 內填的 skill slug 匯入後對不到實際 skill
|
||
2. 有 4 個不同的 Edge skill 在 manifest 中撞成同一個 slug
|
||
3. skills 依賴的 MCP / API / runtime 還停在規劃，沒有跟 package 一起落地
|
||
4. skills 內容多半是摘要版，和文檔宣稱的「完整上游技能」仍有落差
|
||
|
||
第二次追蹤審查時，我重新跑了：
|
||
|
||
```bash
|
||
paperclipai company import <repo> --dry-run --json
|
||
```
|
||
|
||
結果已變成：
|
||
|
||
1. `warnings: []`
|
||
2. `errors: []`
|
||
3. 指定 skills 的 slug 都能正確進 manifest
|
||
4. Edge skills 已各自保有獨立 slug
|
||
|
||
---
|
||
|
||
## 2. 目前剩餘問題
|
||
|
||
### P7. `.paperclip.yaml` 的 `envInputs` 寫了，但 importer 目前沒有真正吃到
|
||
|
||
**現況**
|
||
|
||
`.paperclip.yaml` 現在新增了：
|
||
|
||
```yaml
|
||
envInputs:
|
||
- name: FRED_API_KEY
|
||
- name: FUGLE_API_KEY
|
||
```
|
||
|
||
參考：
|
||
|
||
- [.paperclip.yaml](/Users/chirs/workspace/KingClawArmy_dev_review/.paperclip.yaml:83)
|
||
|
||
但我重新跑 dry-run import 後，`manifest.envInputs` 仍然是空陣列。
|
||
|
||
**影響**
|
||
|
||
這代表 package 雖然開始描述 runtime input，但在目前 Paperclip portability 規則下，這兩筆需求還沒有真的進到 import manifest。
|
||
|
||
也就是說：
|
||
|
||
1. repo 端已寫
|
||
2. importer preview 端尚未保留
|
||
|
||
若目標是讓 package 自帶可攜的環境需求聲明，這一塊還沒真正落地。
|
||
|
||
**推測原因**
|
||
|
||
我對照 Paperclip portability 實作後，目前 importer 會從 agent / project extension 的 `inputs.env` 讀 env inputs，而不是讀 `.paperclip.yaml` 頂層的 `envInputs`。
|
||
|
||
**建議修法**
|
||
|
||
1. 依 Paperclip 目前支援的結構，把 env input 移到 agent / project extension 的 `inputs.env`
|
||
2. 或保留現在的寫法，但補一份文件明確說明「目前僅作 repo 端提示，尚未進 manifest」
|
||
|
||
**建議採用：**
|
||
|
||
優先採第 1 種，讓 import manifest 真的能帶出 env inputs。
|
||
|
||
---
|
||
|
||
### P8. Runtime 配置已有進展，但還沒有完整覆蓋 active skills 的所有依賴
|
||
|
||
**現況**
|
||
|
||
現在 repo 已新增：
|
||
|
||
- `.mcp.json`
|
||
- `.paperclip.yaml` 內的基本 env input 提示
|
||
|
||
參考：
|
||
|
||
- [.mcp.json](/Users/chirs/workspace/KingClawArmy_dev_review/.mcp.json:1)
|
||
- [.paperclip.yaml](/Users/chirs/workspace/KingClawArmy_dev_review/.paperclip.yaml:83)
|
||
|
||
這代表 runtime 不再是純規劃，這點是好的。
|
||
|
||
但目前仍有幾類依賴沒有完整落地：
|
||
|
||
1. `portfolio-manager` 需要的 `Alpaca MCP`
|
||
2. `earnings-calendar` / `economic-calendar-fetcher` 這類技能實際依賴的 FMP 路徑
|
||
3. `pair-trade-screener` 需要的本地 Python/scipy/statsmodels
|
||
4. `trader-memory-core` 需要的持久化檔案系統策略
|
||
|
||
參考：
|
||
|
||
- [earnings-calendar/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/earnings-calendar/SKILL.md:26)
|
||
- [portfolio-manager/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/portfolio-manager/SKILL.md:45)
|
||
- [pair-trade-screener/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/pair-trade-screener/SKILL.md:47)
|
||
- [trader-memory-core/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/trader-memory-core/SKILL.md:51)
|
||
|
||
**影響**
|
||
|
||
目前 package 已可被正確匯入，但若標準是：
|
||
|
||
`skills 不只存在，而且 active agents 可在既定 runtime 下直接使用`
|
||
|
||
那這一層還差最後一段 ops / runtime 補完。
|
||
|
||
**建議修法**
|
||
|
||
至少補這些資訊中的一種：
|
||
|
||
1. `.mcp.json` 補齊缺少的 server
|
||
2. README / docs 補明哪些 skill 是 optional / unavailable / future
|
||
3. 對需要本地依賴的 skill 補 runtime prerequisites
|
||
4. 對暫時無法啟用的 skill，在 mapping 文件裡加狀態標記
|
||
|
||
---
|
||
|
||
## 3. 已修正問題（追蹤確認）
|
||
|
||
### 已修正 P1. Agent 綁定的 skill slug 與匯入後的實際 slug 不一致
|
||
|
||
**現況**
|
||
|
||
多個 agent 使用了如下 skill 參照：
|
||
|
||
- `canslim-screener`
|
||
- `vcp-screener`
|
||
- `pead-screener`
|
||
- `dcf-model`
|
||
- `stanley-druckenmiller-investment`
|
||
- `edge-candidate-agent`
|
||
- `edge-hint-extractor`
|
||
- `edge-concept-synthesizer`
|
||
- `edge-pipeline-orchestrator`
|
||
- `xlsx`
|
||
|
||
參考：
|
||
|
||
- [agents/bullish-researcher/AGENTS.md](/Users/chirs/workspace/KingClawArmy_dev_review/agents/bullish-researcher/AGENTS.md:5)
|
||
- [agents/data-analyst/AGENTS.md](/Users/chirs/workspace/KingClawArmy_dev_review/agents/data-analyst/AGENTS.md:5)
|
||
- [agents/ceo/AGENTS.md](/Users/chirs/workspace/KingClawArmy_dev_review/agents/ceo/AGENTS.md:5)
|
||
- [agents/quant-strategist/AGENTS.md](/Users/chirs/workspace/KingClawArmy_dev_review/agents/quant-strategist/AGENTS.md:5)
|
||
|
||
但 dry-run 匯入結果顯示，Paperclip 最後辨識出的 slug 其實是：
|
||
|
||
- `canslim`
|
||
- `vcp`
|
||
- `pead`
|
||
- `dcf`
|
||
- `druckenmiller`
|
||
- `excel`
|
||
- `edge`
|
||
|
||
參考：
|
||
|
||
- [skills/canslim-screener/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/canslim-screener/SKILL.md:1)
|
||
- [skills/dcf-model/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/dcf-model/SKILL.md:1)
|
||
- [skills/edge-candidate-agent/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/edge-candidate-agent/SKILL.md:1)
|
||
- [skills/stanley-druckenmiller-investment/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/stanley-druckenmiller-investment/SKILL.md:1)
|
||
- [skills/xlsx/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/xlsx/SKILL.md:1)
|
||
|
||
**影響**
|
||
|
||
這不是單純命名風格問題，而是實際綁定會失效。
|
||
|
||
我實測匯入 warning 包含：
|
||
|
||
1. `Agent bullish-researcher references skill canslim-screener, but that skill is not present in the package.`
|
||
2. `Agent bullish-researcher references skill vcp-screener, but that skill is not present in the package.`
|
||
3. `Agent bullish-researcher references skill pead-screener, but that skill is not present in the package.`
|
||
4. `Agent bullish-researcher references skill dcf-model, but that skill is not present in the package.`
|
||
5. `Agent ceo references skill stanley-druckenmiller-investment, but that skill is not present in the package.`
|
||
6. `Agent data-analyst references skill edge-candidate-agent, but that skill is not present in the package.`
|
||
7. `Agent data-analyst references skill xlsx, but that skill is not present in the package.`
|
||
8. `Agent data-analyst references skill edge-hint-extractor, but that skill is not present in the package.`
|
||
9. `Agent data-analyst references skill edge-concept-synthesizer, but that skill is not present in the package.`
|
||
10. `Agent quant-strategist references skill edge-pipeline-orchestrator, but that skill is not present in the package.`
|
||
11. `Agent quant-strategist references skill stanley-druckenmiller-investment, but that skill is not present in the package.`
|
||
|
||
**建議修法**
|
||
|
||
二選一，選一種統一：
|
||
|
||
1. 在每個 `SKILL.md` frontmatter 明確補 `slug`，並與 `AGENTS.md` 內使用的 shortname 對齊
|
||
2. 反過來把所有 `AGENTS.md` 內的 skill entry 改成 importer 實際產出的 slug
|
||
|
||
**追蹤結果：**
|
||
|
||
已修正。`SKILL.md` 已補 `slug` frontmatter，重新 dry-run import 後，相關 warnings 已清空。
|
||
|
||
---
|
||
|
||
### 已修正 P2. 四個 Edge skill 匯入後撞成同一個 `edge` slug
|
||
|
||
**現況**
|
||
|
||
以下四個 skill 路徑在 dry-run manifest 內全部被辨識成 `edge`：
|
||
|
||
1. `skills/edge-candidate-agent/SKILL.md`
|
||
2. `skills/edge-concept-synthesizer/SKILL.md`
|
||
3. `skills/edge-hint-extractor/SKILL.md`
|
||
4. `skills/edge-pipeline-orchestrator/SKILL.md`
|
||
|
||
參考：
|
||
|
||
- [skills/edge-candidate-agent/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/edge-candidate-agent/SKILL.md:1)
|
||
|
||
**影響**
|
||
|
||
這代表 importer 沒有把這四個技能視為四個可獨立引用的 shortname。
|
||
|
||
後果是：
|
||
|
||
1. agent 端無法穩定引用特定 Edge skill
|
||
2. package 內的 skill graph 會失真
|
||
3. 後續 export/import round-trip 可能再度發生重名覆蓋或綁錯
|
||
|
||
**追蹤結果：**
|
||
|
||
已修正。這四個 Edge skill 都已有獨立 slug，重新 dry-run import 後不再撞名。
|
||
|
||
---
|
||
|
||
### 已部分修正 P3. Skills 依賴的 runtime / MCP / env 還沒跟 package 一起落地
|
||
|
||
**現況**
|
||
|
||
許多 skill 已經在內容中假設有：
|
||
|
||
- `yfinance`
|
||
- `fred`
|
||
- `casual-market`
|
||
- `tradingview`
|
||
- `FMP API`
|
||
- `Alpaca MCP`
|
||
- Python 科學計算環境
|
||
- 檔案系統持久化能力
|
||
|
||
參考：
|
||
|
||
- [mcp-plan.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/mcp-plan.md:1)
|
||
- [canslim-screener/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/canslim-screener/SKILL.md:32)
|
||
- [earnings-calendar/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/earnings-calendar/SKILL.md:23)
|
||
- [portfolio-manager/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/portfolio-manager/SKILL.md:1)
|
||
- [trader-memory-core/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/trader-memory-core/SKILL.md:33)
|
||
|
||
但 package 端目前只有：
|
||
|
||
- agent adapter
|
||
- project metadata
|
||
- routine schedule
|
||
|
||
參考：
|
||
|
||
- [.paperclip.yaml](/Users/chirs/workspace/KingClawArmy_dev_review/.paperclip.yaml:1)
|
||
|
||
**追蹤結果：**
|
||
|
||
已部分修正。
|
||
|
||
目前已新增：
|
||
|
||
1. `.mcp.json`
|
||
2. `.paperclip.yaml` 中的 env input 提示
|
||
|
||
但 env input 尚未真正進 manifest，而且 runtime 仍未完整覆蓋所有 active skills，剩餘缺口已移到 P7 / P8。
|
||
|
||
**影響**
|
||
|
||
這代表目前是「skill 文檔存在」，不是「skill 能實際跑起來」。
|
||
|
||
換句話說，package 已有知識層，但 runtime 還沒封裝完成。
|
||
|
||
---
|
||
|
||
### 已修正 P4. 目前 vendored 的 skill 內容偏摘要版，和文檔宣稱的完整度不一致
|
||
|
||
**現況**
|
||
|
||
文檔目前宣稱：
|
||
|
||
- 來自真實開源 repo
|
||
- 很多技能是數百到上千行
|
||
- 詳細內容可用 `references/` 或 `scripts/` 補齊
|
||
|
||
參考：
|
||
|
||
- [agent-skill-mapping.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/agent-skill-mapping.md:5)
|
||
- [skills-inventory.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/skills-inventory.md:18)
|
||
- [skills-inventory.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/skills-inventory.md:46)
|
||
|
||
但實際 repo 目前：
|
||
|
||
1. 幾乎所有 `SKILL.md` 都小於 80 行
|
||
2. 多數只有摘要說明與大綱
|
||
3. `skills/` 下沒有 `reference/`、`references/`、`scripts/`
|
||
|
||
舉例：
|
||
|
||
- [market-news-analyst/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/market-news-analyst/SKILL.md:1)
|
||
- [canslim-screener/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/canslim-screener/SKILL.md:1)
|
||
- [portfolio-manager/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/portfolio-manager/SKILL.md:1)
|
||
- [xlsx/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/xlsx/SKILL.md:1)
|
||
|
||
**影響**
|
||
|
||
這會造成兩個問題：
|
||
|
||
1. package 使用者以為 skills 已完整 vendored，其實只有摘要版
|
||
2. agent 的能力敘述看起來很強，但可重現工作流不足
|
||
|
||
**追蹤結果：**
|
||
|
||
已修正文件口徑。`agent-skill-mapping.md` 現在已明確說明目前是 `Summary Reference` 版 skills，而不是完整 vendored 版。
|
||
|
||
---
|
||
|
||
### 已修正 P5. 文檔統計已經與實際 repo 不一致
|
||
|
||
**現況**
|
||
|
||
目前 `docs/agent-skill-mapping.md` 寫：
|
||
|
||
- `62 個 SKILL.md`
|
||
- `71 個分配`
|
||
|
||
參考：
|
||
|
||
- [agent-skill-mapping.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/agent-skill-mapping.md:26)
|
||
|
||
但我實際掃 repo：
|
||
|
||
1. `skills/` 目錄共 53 個 skill
|
||
2. agents 的 `skills:` 總分配數是 72
|
||
|
||
**影響**
|
||
|
||
這會誤導下一位 agent，以為：
|
||
|
||
1. repo 少了 9 個 skill
|
||
2. 或某些配置還沒同步
|
||
|
||
**追蹤結果：**
|
||
|
||
已修正。文件中的 skill 數量與分配數量已更新為當前 repo 狀態。
|
||
|
||
---
|
||
|
||
### 已修正 P6. `mcp-plan.md` 仍含敏感或機器相依資訊，不適合留在 package docs
|
||
|
||
**現況**
|
||
|
||
這份文件目前包含：
|
||
|
||
1. 明文 `FRED_API_KEY`
|
||
2. 機器相依的絕對路徑 `/home/chris/workspace/...`
|
||
|
||
參考：
|
||
|
||
- [mcp-plan.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/mcp-plan.md:141)
|
||
- [mcp-plan.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/mcp-plan.md:152)
|
||
- [mcp-plan.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/mcp-plan.md:195)
|
||
|
||
**影響**
|
||
|
||
即使這裡只是示意值，這種寫法仍然不適合進 canonical package docs，原因是：
|
||
|
||
1. 容易讓人誤把示意值當真 key
|
||
2. 絕對路徑沒有可攜性
|
||
3. 違反 base package 應避免機器相依值的原則
|
||
|
||
**追蹤結果：**
|
||
|
||
已修正。API key 已改為 placeholder，機器相依絕對路徑也已抽換。
|
||
|
||
---
|
||
|
||
## 4. 建議補齊清單
|
||
|
||
請另一個 agent 依序補：
|
||
|
||
1. 讓 env inputs 依 Paperclip 目前支援的結構真正進 manifest
|
||
2. 補齊 active skills 的 runtime 覆蓋缺口
|
||
3. 為尚未可直接啟用的 skill 補 `optional / unavailable / future` 狀態說明
|
||
4. 若後續要提升為完整 vendored skills，再補 `references/` / `scripts/`
|
||
|
||
---
|
||
|
||
## 5. 修完後的驗收標準
|
||
|
||
至少要確認：
|
||
|
||
1. `paperclipai company import --dry-run --json` 仍保持 `warnings: []`、`errors: []`
|
||
2. `manifest.envInputs` 不再為空，且能反映 package 真正需要的環境輸入
|
||
3. active skills 的 runtime 依賴都有對應配置或明確狀態標記
|
||
4. `mcp-plan.md`、`.mcp.json`、`.paperclip.yaml` 三者口徑一致
|
||
|
||
---
|
||
|
||
## 6. 一句話結論
|
||
|
||
這版 `dev` 的 agent / skills 已經把最重要的 Paperclip skill 綁定問題修乾淨了；目前剩下的是 `envInputs` 尚未真正進 manifest，以及 runtime 覆蓋還沒百分之百收尾，屬於完整度問題，不是基本相容性問題。
|