From e642bdc02d9a98bf6bbc4d109122ca85fd37ade7 Mon Sep 17 00:00:00 2001 From: Chris Date: Sat, 11 Apr 2026 13:57:36 +0800 Subject: [PATCH] docs: update final portability review --- ...aperclip_agent_skills_review_2026-04-11.md | 129 +++++++++--------- 1 file changed, 61 insertions(+), 68 deletions(-) diff --git a/docs/paperclip_agent_skills_review_2026-04-11.md b/docs/paperclip_agent_skills_review_2026-04-11.md index 0f01a7a..7799e12 100644 --- a/docs/paperclip_agent_skills_review_2026-04-11.md +++ b/docs/paperclip_agent_skills_review_2026-04-11.md @@ -3,7 +3,8 @@ > 日期：2026-04-11 > 審查對象：`origin/dev` > 初次審查 commit：`ced587c` -> 追蹤審查 commit：`ee06e6d` +> 第二輪追蹤 commit：`ee06e6d` +> 第三輪追蹤 commit：`e894446` > 用途：檢查 Agent 配置、Skills 完整度、Paperclip 匯入相容性與 runtime 落地程度 --- @@ -25,7 +26,7 @@ 5. 文檔已改口徑為摘要版 skills 6. skills 統計數量已更新 -目前仍有 2 個「完整度」層級的缺口，但已不是前一輪那種會直接造成 import warning 的 blocker。 +目前只剩 1 個實質問題，且已不是前一輪那種會直接造成 import warning 的 blocker。 我實際用： @@ -46,13 +47,26 @@ paperclipai company import --dry-run --json paperclipai company import --dry-run --json ``` -結果已變成： +第二輪追蹤後，結果已變成： 1. `warnings: []` 2. `errors: []` 3. 指定 skills 的 slug 都能正確進 manifest 4. Edge skills 已各自保有獨立 slug +第三輪追蹤後，我再次驗證： + +```bash +paperclipai company import --dry-run --json +``` + +結果依然是： + +1. `warnings: []` +2. `errors: []` + +但 `envInputs` / `manifest.envInputs` 仍然都是空陣列，表示環境輸入需求尚未真正進到 portability manifest。 + --- ## 2. 目前剩餘問題 @@ -61,12 +75,20 @@ paperclipai company import --dry-run --json **現況** -`.paperclip.yaml` 現在新增了： +第二輪追蹤後，`.paperclip.yaml` 已把 env input 從頂層移到 project extension 下，但目前寫法仍然沒有被 importer 吃到。 + +目前結構是： ```yaml -envInputs: - - name: FRED_API_KEY - - name: FUGLE_API_KEY +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 ``` 參考： @@ -77,7 +99,7 @@ envInputs: **影響** -這代表 package 雖然開始描述 runtime input，但在目前 Paperclip portability 規則下，這兩筆需求還沒有真的進到 import manifest。 +這代表 package 雖然開始描述 runtime input，但在目前 Paperclip portability 規則下，這些需求仍然沒有真的進到 import manifest。 也就是說： @@ -88,66 +110,36 @@ envInputs: **推測原因** -我對照 Paperclip portability 實作後，目前 importer 會從 agent / project extension 的 `inputs.env` 讀 env inputs，而不是讀 `.paperclip.yaml` 頂層的 `envInputs`。 +我對照 Paperclip portability 實作後，目前 importer 會從 agent / project extension 的 `inputs.env` 讀 env inputs，但它預期的是「以 env var 名稱為 key 的 object」，不是目前這種 list 寫法。 **建議修法** -1. 依 Paperclip 目前支援的結構，把 env input 移到 agent / project extension 的 `inputs.env` -2. 或保留現在的寫法，但補一份文件明確說明「目前僅作 repo 端提示，尚未進 manifest」 +1. 依 Paperclip 目前支援的結構，把 `inputs.env` 改成 object 形式 +2. 若暫時不改，也要在文檔明確標示「目前僅作 repo 端提示，尚未進 manifest」 **建議採用：** 優先採第 1 種，讓 import manifest 真的能帶出 env inputs。 +建議格式： + +```yaml +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 +``` + --- -### 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. 已修正問題（追蹤確認） @@ -256,7 +248,7 @@ envInputs: --- -### 已部分修正 P3. Skills 依賴的 runtime / MCP / env 還沒跟 package 一起落地 +### 已修正 P3. Skills 依賴的 runtime / MCP / env 還沒跟 package 一起落地 **現況** @@ -291,14 +283,16 @@ envInputs: **追蹤結果：** -已部分修正。 +已修正。 目前已新增： 1. `.mcp.json` -2. `.paperclip.yaml` 中的 env input 提示 +2. runtime 狀態文件 +3. `Alpaca` / `FMP` 等 MCP 依賴聲明 +4. `optional / needs-key / local-runtime` 的狀態說明 -但 env input 尚未真正進 manifest，而且 runtime 仍未完整覆蓋所有 active skills，剩餘缺口已移到 P7 / P8。 +目前剩下的唯一缺口已收斂為 P7：`envInputs` 寫法尚未真正進 manifest。 **影響** @@ -414,9 +408,9 @@ envInputs: 請另一個 agent 依序補： -1. 讓 env inputs 依 Paperclip 目前支援的結構真正進 manifest -2. 補齊 active skills 的 runtime 覆蓋缺口 -3. 為尚未可直接啟用的 skill 補 `optional / unavailable / future` 狀態說明 +1. 把 `.paperclip.yaml` 的 `inputs.env` 改成 Paperclip importer 會讀到的 object 結構 +2. 重新跑 `paperclipai company import --dry-run --json` +3. 確認 `envInputs` / `manifest.envInputs` 不再為空 4. 若後續要提升為完整 vendored skills，再補 `references/` / `scripts/` --- @@ -427,11 +421,10 @@ envInputs: 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` 三者口徑一致 +3. `mcp-plan.md`、`.mcp.json`、`.paperclip.yaml` 三者口徑一致 --- ## 6. 一句話結論 -這版 `dev` 的 agent / skills 已經把最重要的 Paperclip skill 綁定問題修乾淨了；目前剩下的是 `envInputs` 尚未真正進 manifest，以及 runtime 覆蓋還沒百分之百收尾，屬於完整度問題，不是基本相容性問題。 +這版 `dev` 的 agent / skills 已經把最重要的 Paperclip 綁定與 runtime 規劃問題修乾淨了；目前只剩 `envInputs` 的 YAML 結構尚未符合 importer 預期，屬於最後一個 portability 細節問題。