docs: update agent skills follow-up review

2026-04-11 05:25:48 +08:00
parent ee06e6de6b
commit 3451ce7d77
1 changed files with 158 additions and 78 deletions
--- 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 <repo> --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 <repo> --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 <repo> --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 <repo> --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 <repo> --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 <repo> --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 <repo> --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 <repo> --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 <repo> --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 覆蓋還沒百分之百收尾，屬於完整度問題，不是基本相容性問題。