diff --git a/docs/paperclip_agent_skills_review_2026-04-11.md b/docs/paperclip_agent_skills_review_2026-04-11.md index e50c04a..0f01a7a 100644 --- a/docs/paperclip_agent_skills_review_2026-04-11.md +++ b/docs/paperclip_agent_skills_review_2026-04-11.md @@ -2,7 +2,8 @@ > 日期：2026-04-11 > 審查對象：`origin/dev` -> 審查 commit：`ced587c` +> 初次審查 commit：`ced587c` +> 追蹤審查 commit：`ee06e6d` > 用途：檢查 Agent 配置、Skills 完整度、Paperclip 匯入相容性與 runtime 落地程度 --- @@ -15,7 +16,16 @@ 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。 我實際用： @@ -23,18 +33,126 @@ paperclipai company import --dry-run --json ``` -驗證後，package 雖然仍可匯入，但有一批與 skills 相關的 warning，顯示： +第一次審查時，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 --dry-run --json +``` + +結果已變成： + +1. `warnings: []` +2. `errors: []` +3. 指定 skills 的 slug 都能正確進 manifest +4. Edge skills 已各自保有獨立 slug + --- -## 2. 主要問題 +## 2. 目前剩餘問題 -### P1. Agent 綁定的 skill slug 與匯入後的實際 slug 不一致 +### 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 不一致 **現況** @@ -101,14 +219,13 @@ paperclipai company import --dry-run --json 1. 在每個 `SKILL.md` frontmatter 明確補 `slug`，並與 `AGENTS.md` 內使用的 shortname 對齊 2. 反過來把所有 `AGENTS.md` 內的 skill entry 改成 importer 實際產出的 slug -**建議採用：** +**追蹤結果：** -優先採第 1 種。 -也就是讓 skill package 自己明確宣告穩定 slug，避免 agent 端追著 importer 的正規化規則跑。 +已修正。`SKILL.md` 已補 `slug` frontmatter，重新 dry-run import 後，相關 warnings 已清空。 --- -### P2. 四個 Edge skill 匯入後撞成同一個 `edge` slug +### 已修正 P2. 四個 Edge skill 匯入後撞成同一個 `edge` slug **現況** @@ -133,18 +250,13 @@ paperclipai company import --dry-run --json 2. package 內的 skill graph 會失真 3. 後續 export/import round-trip 可能再度發生重名覆蓋或綁錯 -**建議修法** +**追蹤結果：** -這四個 `SKILL.md` 必須都補明確、互不衝突的 `slug`： - -1. `edge-candidate-agent` -2. `edge-concept-synthesizer` -3. `edge-hint-extractor` -4. `edge-pipeline-orchestrator` +已修正。這四個 Edge skill 都已有獨立 slug，重新 dry-run import 後不再撞名。 --- -### P3. Skills 依賴的 runtime / MCP / env 還沒跟 package 一起落地 +### 已部分修正 P3. Skills 依賴的 runtime / MCP / env 還沒跟 package 一起落地 **現況** @@ -177,12 +289,16 @@ paperclipai company import --dry-run --json - [.paperclip.yaml](/Users/chirs/workspace/KingClawArmy_dev_review/.paperclip.yaml:1) -目前沒有： +**追蹤結果：** + +已部分修正。 + +目前已新增： 1. `.mcp.json` -2. `.paperclip.yaml` 的 `envInputs` -3. secrets / key requirement 聲明 -4. 哪些 skill 是 hard requirement、哪些是 optional fallback +2. `.paperclip.yaml` 中的 env input 提示 + +但 env input 尚未真正進 manifest，而且 runtime 仍未完整覆蓋所有 active skills，剩餘缺口已移到 P7 / P8。 **影響** @@ -190,18 +306,9 @@ paperclipai company import --dry-run --json 換句話說，package 已有知識層，但 runtime 還沒封裝完成。 -**建議修法** - -至少補以下四類資料： - -1. repo 內的 `.mcp.json` 草稿或正式版 -2. `.paperclip.yaml` 的 `envInputs` -3. 每個需要外部能力的 skill，其 required MCP / API / local runtime -4. required / optional / unavailable 的分級標記 - --- -### P4. 目前 vendored 的 skill 內容偏摘要版，和文檔宣稱的完整度不一致 +### 已修正 P4. 目前 vendored 的 skill 內容偏摘要版，和文檔宣稱的完整度不一致 **現況** @@ -237,16 +344,13 @@ paperclipai company import --dry-run --json 1. package 使用者以為 skills 已完整 vendored，其實只有摘要版 2. agent 的能力敘述看起來很強，但可重現工作流不足 -**建議修法** +**追蹤結果：** -這裡要明確選邊站： - -1. 若目標是「摘要版 skills library」：就把文檔改成摘要版，不要再寫成完整上游技能 -2. 若目標是「完整 vendored skills」：就補 `references/`、`scripts/`、關鍵工作流、必要範本 +已修正文件口徑。`agent-skill-mapping.md` 現在已明確說明目前是 `Summary Reference` 版 skills，而不是完整 vendored 版。 --- -### P5. 文檔統計已經與實際 repo 不一致 +### 已修正 P5. 文檔統計已經與實際 repo 不一致 **現況** @@ -271,14 +375,13 @@ paperclipai company import --dry-run --json 1. repo 少了 9 個 skill 2. 或某些配置還沒同步 -**建議修法** +**追蹤結果：** -把統計欄位改成和 repo 實際狀態一致。 -如果之後還會持續增減，建議不要手寫固定數字，改成描述型文字。 +已修正。文件中的 skill 數量與分配數量已更新為當前 repo 狀態。 --- -### P6. `mcp-plan.md` 仍含敏感或機器相依資訊，不適合留在 package docs +### 已修正 P6. `mcp-plan.md` 仍含敏感或機器相依資訊，不適合留在 package docs **現況** @@ -301,57 +404,34 @@ paperclipai company import --dry-run --json 2. 絕對路徑沒有可攜性 3. 違反 base package 應避免機器相依值的原則 -**建議修法** +**追蹤結果：** -1. 所有 key 一律改成 placeholder -2. 所有絕對路徑一律改成相對或說明性文字 -3. 若要保留實作版本，請移到不納入 package 的私有部署文件 +已修正。API key 已改為 placeholder，機器相依絕對路徑也已抽換。 --- -## 3. 建議補齊清單 +## 4. 建議補齊清單 請另一個 agent 依序補： -1. 為所有 `SKILL.md` 補明確 `slug` frontmatter -2. 先修正這批被 warning 的 skill slug 對齊問題： - - `canslim-screener` - - `vcp-screener` - - `pead-screener` - - `dcf-model` - - `stanley-druckenmiller-investment` - - `xlsx` - - `edge-candidate-agent` - - `edge-hint-extractor` - - `edge-concept-synthesizer` - - `edge-pipeline-orchestrator` -3. 確保四個 Edge skill 匯入後不再全部變成 `edge` -4. 補 `.mcp.json` 或等價 runtime 配置檔 -5. 在 `.paperclip.yaml` 補 `envInputs` / runtime requirements -6. 為每個依賴外部服務的 skill 標記： - - required MCP - - required API key - - required local runtime - - optional fallback -7. 決定 skills 是「摘要版」還是「完整 vendored 版」，並把文檔口徑統一 -8. 修正文檔中的技能數量與配置數量 -9. 清掉 `mcp-plan.md` 的敏感與機器相依資訊 +1. 讓 env inputs 依 Paperclip 目前支援的結構真正進 manifest +2. 補齊 active skills 的 runtime 覆蓋缺口 +3. 為尚未可直接啟用的 skill 補 `optional / unavailable / future` 狀態說明 +4. 若後續要提升為完整 vendored skills，再補 `references/` / `scripts/` --- -## 4. 修完後的驗收標準 +## 5. 修完後的驗收標準 至少要確認： -1. `paperclipai company import --dry-run --json` 不再出現 skill missing warnings -2. 所有 agent 在 manifest 中引用到的 skill slug 都能對上 -3. 四個 Edge skill 在 manifest 中是四個獨立 skill，不再撞名 -4. `docs/agent-skill-mapping.md` 的統計與 repo 實際一致 -5. package 有明確的 runtime / MCP / env requirement 定義 -6. `mcp-plan.md` 不再含敏感值與絕對路徑 +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` 三者口徑一致 --- -## 5. 一句話結論 +## 6. 一句話結論 -這版 `dev` 的 agent / skills 架構方向正確，但目前主要缺口不在「數量」，而在「skill slug 尚未穩定、runtime 尚未落地、內容完整度與文檔口徑尚未對齊」，還需要再補一輪才能稱得上完整。 +這版 `dev` 的 agent / skills 已經把最重要的 Paperclip skill 綁定問題修乾淨了；目前剩下的是 `envInputs` 尚未真正進 manifest，以及 runtime 覆蓋還沒百分之百收尾，屬於完整度問題，不是基本相容性問題。