chris/KingClawArmy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3deef700b47246097d42b0048624d985d87d0813
KingClawArmy/docs/paperclip_agent_skills_review_2026-04-11.md
Chris e642bdc02d docs: update final portability review
2026-04-11 13:57:36 +08:00

13 KiB
Raw Blame History

KingClawArmy - Agent / Skills Review（dev）

日期：2026-04-11 審查對象：origin/dev 初次審查 commit：ced587c 第二輪追蹤 commit：ee06e6d 第三輪追蹤 commit：e894446 用途：檢查 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 統計數量已更新

目前只剩 1 個實質問題，且已不是前一輪那種會直接造成 import warning 的 blocker。

我實際用：

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 內容多半是摘要版，和文檔宣稱的「完整上游技能」仍有落差

第二次追蹤審查時，我重新跑了：

paperclipai company import <repo> --dry-run --json

第二輪追蹤後，結果已變成：

  1. warnings: []
  2. errors: []
  3. 指定 skills 的 slug 都能正確進 manifest
  4. Edge skills 已各自保有獨立 slug

第三輪追蹤後，我再次驗證：

paperclipai company import <repo> --dry-run --json

結果依然是：

  1. warnings: []
  2. errors: []

但 envInputs / manifest.envInputs 仍然都是空陣列，表示環境輸入需求尚未真正進到 portability manifest。

2. 目前剩餘問題

P7. .paperclip.yaml 的 envInputs 寫了，但 importer 目前沒有真正吃到

現況

第二輪追蹤後，.paperclip.yaml 已把 env input 從頂層移到 project extension 下，但目前寫法仍然沒有被 importer 吃到。

目前結構是：

projects:
  daily-quant-pipeline:
    inputs:
      env:
        - name: FRED_API_KEY
        - name: FUGLE_API_KEY
        - name: ALPACA_API_KEY
        - name: ALPACA_API_SECRET
        - name: FMP_API_KEY

參考：

但我重新跑 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，但它預期的是「以 env var 名稱為 key 的 object」，不是目前這種 list 寫法。

建議修法

  1. 依 Paperclip 目前支援的結構，把 inputs.env 改成 object 形式
  2. 若暫時不改，也要在文檔明確標示「目前僅作 repo 端提示，尚未進 manifest」

建議採用：

優先採第 1 種，讓 import manifest 真的能帶出 env inputs。

建議格式：

projects:
  daily-quant-pipeline:
    inputs:
      env:
        FRED_API_KEY:
          description: FRED API key
          kind: secret
          requirement: optional
        FUGLE_API_KEY:
          description: Fugle MarketData API key
          kind: secret
          requirement: optional

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

參考：

但 dry-run 匯入結果顯示，Paperclip 最後辨識出的 slug 其實是：

  • canslim
  • vcp
  • pead
  • dcf
  • druckenmiller
  • excel
  • edge

參考：

影響

這不是單純命名風格問題，而是實際綁定會失效。

我實測匯入 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

參考：

影響

這代表 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 科學計算環境
  • 檔案系統持久化能力

參考：

但 package 端目前只有：

  • agent adapter
  • project metadata
  • routine schedule

參考：

追蹤結果：

已修正。

目前已新增：

  1. .mcp.json
  2. runtime 狀態文件
  3. Alpaca / FMP 等 MCP 依賴聲明
  4. optional / needs-key / local-runtime 的狀態說明

目前剩下的唯一缺口已收斂為 P7：envInputs 寫法尚未真正進 manifest。

影響

這代表目前是「skill 文檔存在」，不是「skill 能實際跑起來」。

換句話說，package 已有知識層，但 runtime 還沒封裝完成。

已修正 P4. 目前 vendored 的 skill 內容偏摘要版，和文檔宣稱的完整度不一致

現況

文檔目前宣稱：

  • 來自真實開源 repo
  • 很多技能是數百到上千行
  • 詳細內容可用 references/ 或 scripts/ 補齊

參考：

但實際 repo 目前：

  1. 幾乎所有 SKILL.md 都小於 80 行
  2. 多數只有摘要說明與大綱
  3. skills/ 下沒有 reference/、references/、scripts/

舉例：

影響

這會造成兩個問題：

  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 個分配

參考：

但我實際掃 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/...

參考：

影響

即使這裡只是示意值，這種寫法仍然不適合進 canonical package docs，原因是：

  1. 容易讓人誤把示意值當真 key
  2. 絕對路徑沒有可攜性
  3. 違反 base package 應避免機器相依值的原則

追蹤結果：

已修正。API key 已改為 placeholder，機器相依絕對路徑也已抽換。

4. 建議補齊清單

請另一個 agent 依序補：

  1. 把 .paperclip.yaml 的 inputs.env 改成 Paperclip importer 會讀到的 object 結構
  2. 重新跑 paperclipai company import --dry-run --json
  3. 確認 envInputs / manifest.envInputs 不再為空
  4. 若後續要提升為完整 vendored skills，再補 references/ / scripts/

5. 修完後的驗收標準

至少要確認：

  1. paperclipai company import --dry-run --json 仍保持 warnings: []、errors: []
  2. manifest.envInputs 不再為空，且能反映 package 真正需要的環境輸入
  3. mcp-plan.md、.mcp.json、.paperclip.yaml 三者口徑一致

6. 一句話結論

這版 dev 的 agent / skills 已經把最重要的 Paperclip 綁定與 runtime 規劃問題修乾淨了；目前只剩 envInputs 的 YAML 結構尚未符合 importer 預期，屬於最後一個 portability 細節問題。

Reference in New Issue View Git Blame Copy Permalink