# pnpm 12.11 讓 npm 依賴套件攜帶 Agent Skills：核准一次之後，升級時還要檢查什麼？

> Canonical: https://vxi.me/zh-tw/posts/pnpm-agent-skills-approval-scope/
> Locale: zh-tw
> Published: 2026-10-13
> Updated: 2026-10-13
> Markdown: https://vxi.me/zh-tw/posts/pnpm-agent-skills-approval-scope.md

# pnpm 12.11.0 Skills 權限實測：批准一次，究竟意味著什麼？

**描述：**根據 pnpm v12.11.0 原始碼與固定版本文件，梳理 Skills 的探索範圍、審批與連結行為，並以獨立合成模型檢驗關鍵分支，協助開發者評估依賴升級與權限管理方式。

## 探索與權限邊界

我一開始把問題想得比較簡單：依賴中多了個 `SKILL.md`，pnpm 要嘛在安裝時就把它放進 Agent 目錄，要嘛完全不管。順著 pnpm 12.11.0 的固定版本原始碼追下去，我發現中間還隔著探索、權限判斷和連結幾個步驟；這些邊界，才是判斷「批准一次」意味著什麼的關鍵。

我當時先追查探索邏輯，以為只要依賴樹中出現 Skill 檔案，就會進入審批流程。結果發現掃描範圍更窄：pnpm 會檢查 lockfile 中各個 workspace importer 的直接依賴，而且只掃描一層 Skills 目錄。間接依賴不在這條探索路徑中，不能把「依賴樹中有檔案」和「pnpm 會探索到它」畫上等號。

接著我把安裝、連結和 Agent 載入拆開來看。套件中的檔案可以已經放在依賴目錄中；權限狀態則決定 pnpm 是否為它建立指向目標目錄的符號連結；之後 Claude Code 或其他 Agent 是否讀取、如何處理，則由各自的用戶端決定。pnpm 原始碼處理的是連結，不會解析或執行 Skill 內容。

權限分支包括待批准、拒絕和批准幾種狀態。批准由套件層級的操作處理，`pnpm approve` 同時涉及建置指令碼與 Skills 權限；這不等於逐一審閱檔案。建置指令碼權限和 `permissions.skills` 是不同的權限面，套件的建置指令碼獲准，不代表 Skill 內容經過了個別審查。

最讓我停下來確認的是批准的涵蓋範圍。v12.11.0 的官方文件說明，一次套件層級的批准涵蓋該依賴的所有 Skills，並且延續至之後的版本。升級時要留意新版本帶來的指令變動：舊的批准狀態可能仍然適用，但新版本可以新增或改寫 Skill。

workspace 中同時出現多個可用版本時，原始碼會為已安裝且符合條件的 registry 版本選擇最高版本。這會影響實際連結到哪一份內容，因此只看 `package.json` 中的版本範圍並不足夠。要判斷升級後 Agent 可能讀到什麼，還得檢查實際選中的套件版本及其包含的 Skill。

目標目錄也有明確條件。v12.11.0 會參考 `CLAUDECODE`、`CURSOR_AGENT`、`GEMINI_CLI` 環境變數，或 workspace 中已存在的 Agent Skills 目錄；`skills.dirs` 可以明確覆寫。明確設定為空會停用 Skills；批准時若未自動偵測到目標目錄，則會觸發無目標錯誤。

```yaml
# pnpm-workspace.yaml
skills:
  dirs:
    - .claude/skills
    - .cursor/skills
```

我當時還以為，撤銷權限會一併刪除相關目錄中的內容。原始碼和獨立檔案系統模型呈現的邊界更窄：模型觀察到由它建立的連結會被移除，手動建立的本機 Skill 則保持不動；目標路徑若已被真實目錄占用，也不會遭到取代。套件刪除、目標目錄不存在等分支，也要依照各自的連結清理與錯誤處理邏輯來理解。

## 合成模型與測試結果

為了具體呈現這些分支，我使用 Node 22.16.0 標準函式庫撰寫了獨立的合成檔案系統模型：建立暫存假依賴、合成 `SKILL.md` 和符號連結，再計算內容指紋。八組情境分別涵蓋待批准、拒絕、批准、升級後新增 Skill、撤銷、路徑衝突、僅有間接依賴，以及沒有自動偵測到目標目錄。

模型涵蓋的八組情境都通過了；其中升級情境觀察到內容指紋變化，並出現第二個 Skill 連結。第一次執行模型時，有一組因為我用「預期連結數量為零」來判斷是否存在已批准的 Skill 而失敗，誤把「沒有目標目錄」判錯。找出問題後，我改為單獨檢查已批准的 Skill 數量，再次執行後八組情境均通過。

## 儲存庫檢查與適用範圍

實際檢查儲存庫時，可以先用 `pnpm permissions` 或 `pnpm permissions list` 查看權限，再對照 workspace 設定。依賴升級後，檢查新版本中的 Skills 檔案及其差異；更在意指令漂移的專案，可以固定依賴版本，並在 CI 中比較 `SKILL.md`。

```sh
pnpm permissions
pnpm permissions list
```

### 邊界 / 限制

這次分析以 pnpm v12.11.0 原始碼和固定版本文件為基準，測試使用由 Node 獨立執行的合成模型，涵蓋範圍為檔案系統行為。模型沒有接入 pnpm CLI、真實安裝更新或 Agent；用戶端的探索與執行規則也會隨各自版本變動。pnpm 12.11.1 的環境識別變更不應倒推為 12.11.0 的功能。套件層級批准所帶來的後續版本信任範圍，是升級審查時需要考量的設計邊界。

**參考連結：**[pnpm v12.11.0 原始碼](https://github.com/pnpm/pnpm/tree/v12.11.0) · [pnpm v12.11.0 文件](https://github.com/pnpm/pnpm/tree/v12.11.0/docs)