docs: update final portability review

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 <repo> --dry-run --json
 paperclipai company import <repo> --dry-run --json
 ```
 
-結果已變成：
+第二輪追蹤後，結果已變成：
 
 1. `warnings: []`
 2. `errors: []`
 3. 指定 skills 的 slug 都能正確進 manifest
 4. Edge skills 已各自保有獨立 slug
 
+第三輪追蹤後，我再次驗證：
+
+```bash
+paperclipai company import <repo> --dry-run --json
+```
+
+結果依然是：
+
+1. `warnings: []`
+2. `errors: []`
+
+但 `envInputs` / `manifest.envInputs` 仍然都是空陣列，表示環境輸入需求尚未真正進到 portability manifest。
+
 ---
 
 ## 2. 目前剩餘問題
@@ -61,12 +75,20 @@ paperclipai company import <repo> --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 細節問題。