npm Stage-only Token 能直接給 AI Agent 發包嗎？2026 驗收

這篇文章適合三類團隊：允許 AI Coding Agent 修改程式碼、打包或準備 npm 版本，但必須限制最終發布權限的開源維護者；正在重整長期令牌、OIDC 與人工審批流程的平台工程團隊；以及需要用遠端 Mac 建置原生依賴、跨平台二進位檔或 Apple 工具鏈的交付團隊。

最後更新於 2026 年 9 月 19 日；資料核實自 GitHub 官方 Stage-only Token 變更記錄、npm staged publishing 文件及 npm Trusted Publishing 文件。npm 將 2027 年 1 月列為移除 bypass-2FA 令牌直接發布能力的目標時間，但這是官方規劃，不是不可變更的承諾。

1先把「寫程式」與「公開發布」拆成不同責任

Stage-only Token 的價值，在於把 AI Agent 從正式公開發布的最後一步移開；它不是把 Agent 變成唯讀使用者，也不是自動證明暫存包沒有問題。依 npm 對存取令牌的說明，Read and write（stage only）令牌可以提交待審核版本，但直接執行 npm publish 會被拒絕，最後仍要由維護者完成 2FA 批准。相關權限名稱與行為應以 npm 存取令牌文件為準。

因此，一個可追責的發布時間線應該長這樣：

你不能把「已進入暫存區」寫成「版本已安全」。維護者仍要獨立檢查版本號、套件內檔案、安裝腳本、來源提交、產物差異與變更範圍；如果這些項目只由產生該版本的 Agent 自己報告，流程仍然缺少獨立驗證。

2對 AI Coding 團隊而言，Stage-only 不是完整權限邊界

AI Agent 的任務應限於修改程式碼、執行測試、產生 tarball、整理變更摘要及發起暫存發布。它不應持有維護者 2FA，也不應取得可以在另一個步驟完成正式批准的身份。更重要的是，團隊要檢查提示詞、Shell 腳本、MCP 工具或子 Agent 是否仍能執行超出「準備版本」的操作。

Stage-only Token 仍可能保留部分寫入權限，官方已確認的例子包括移動 dist-tag 與棄用版本。這代表一次驗收不能只執行一個被拒絕的 npm publish；安全團隊還要測試 Agent 是否能改變 latest 或其他標籤、標記某個版本為 deprecated，以及令牌是否能接觸目標套件以外的資源。

每次任務至少要綁定以下邊界：

• 一個獨立工作區，不與其他發布任務共用未清理的檔案。
• 一個可追蹤的 Git 提交，暫存版本必須能回到該提交。
• 一筆獨立的暫存紀錄，包含執行時間、套件名稱、版本和產物摘要。
• 一個短時或可快速撤銷的憑據上下文，避免令牌流入快取、日誌、工作區快照或子 Agent 對話。
• 一個明確的失敗路徑：測試失敗、產物不一致或權限測試異常時，不能自動進入 2FA 批准。

你也可以參考 vpstix 的 AI Agent 憑據隔離指南，把 Agent 的工具權限、工作區和憑據注入方式分開檢查；但不要把任何建置主機的隔離能力當成 npm 帳戶權限控制的替代品。

3Stage-only 與 Trusted Publishing 的選擇條件

兩條路徑解決的問題並不完全相同。Stage-only Token 主要是把自動化流程限制在暫存發布，保留維護者作為最後批准者；Trusted Publishing 則透過 OIDC 工作流身份取得發布授權，目標是減少長期保存寫入令牌的需要。npm 的支援範圍、CI/CD 類型與必要前提，應直接對照 Trusted Publishing 官方文件，不能簡化為「OIDC 等於免審批」。

GitHub 已公布 npm Trusted Publishing 可用多個配置的更新，但這不代表所有自託管 Runner、分支策略或工作流都自然符合條件；你仍要驗證工作流身份、套件級授權、分支保護和失敗後的撤銷程序。若目前 CI/CD 不符合條件，Stage-only 可以作為過渡方案，但要設定遷移期限與重新驗收條件。

4各角色的驗收清單與保存證據

這份清單不是「勾完就安全」，而是每一項都應該能由另一位工程師重現或抽查。若任何一項無法保存證據，發布負責人應把結果標示為暫緩，而不是以口頭確認取代測試。

開源維護者：確認暫存版本值得批准

• [ ] 對照來源提交檢查版本號、變更檔案與套件內檔案。
• [ ] 解開暫存 tarball，確認沒有意外納入憑據、工作區設定或未追蹤檔案。
• [ ] 用獨立環境執行安裝與測試，不只閱讀 Agent 產生的摘要。
• [ ] 由維護者本人使用 2FA 批准，不把批准密鑰交給 Agent 或建置主機。
• [ ] 保存批准者、批准時間、版本和提交雜湊的對照記錄。

AI Coding 團隊：確認 Agent 沒有越權

• [ ] 將提示詞、工具清單和 Shell 腳本列入審查範圍。
• [ ] 測試直接 npm publish 是否被拒絕。
• [ ] 另外測試 dist-tag 移動、版本棄用及非目標套件存取是否被限制。
• [ ] 讓每次任務使用獨立工作區，任務結束後刪除產物與憑據痕跡。
• [ ] 將提交、測試、暫存與批准事件串成同一條可追溯記錄。

平台工程團隊：確認 CI/CD 身份可控

• [ ] 核對 Runner 類型、工作流來源、分支條件與 OIDC 支援範圍。
• [ ] 記錄令牌存放位置、注入步驟、遮罩方式和撤銷流程。
• [ ] 將 Trusted Publishing 與 Stage-only 流程分開命名，避免誤把一條流程的權限套到另一條。
• [ ] 在低影響套件完成成功、失敗、取消和重試測試後，才擴大套件範圍。
• [ ] 設定令牌輪換和事件調查的責任人，而不是只依賴平台預設保留期。

建立令牌時，應以 npm 建立與檢視存取令牌文件核對目前介面與權限名稱；不要把舊版 CLI 行為、社群文章或 Agent 的自動提示當作權限事實。

5遠端 Mac 建置與批准身份必須分離

如果 npm 套件包含 macOS 原生依賴、跨平台二進位檔或 Apple 工具鏈，遠端 Mac 可以負責建置與驗證，但不應同時保存維護者 2FA 或正式發布憑據。遠端主機的角色是產生可核驗的暫存產物，不是把「能完成建置」延伸成「能代表維護者公開發布」。

你可以參考 vpstix 的遠端 Mac 建置環境隔離方案，把建置工作區、任務身份和批准身份分開規劃，然後把以下證據加入交付包：

交付前應實際解開暫存 tarball，將它與來源提交和測試結果對照；不能只因 Agent 回報「建置成功」就放行。任務結束後要清理令牌、Shell 歷史、工作區快照、暫存檔和可能包含環境變數的記錄。這也是為什麼遠端 Mac 隔離方案要同時處理建置主機與批准身份，而不是只開一台獨立伺服器。

6發布負責人用四類證據決定是否擴大

對低風險、可快速回復的套件，你可以先採用 Agent 暫存加人工批准；對高影響套件，則應加入獨立復測和雙人審核。若團隊無法還原產物來源、隔離憑據或確認剩餘寫入權限，就不要因為 Stage-only 名稱看起來收窄而啟用。

最後可形成三種決策：低風險套件採取有限開放；CI/CD 條件逐步成熟的團隊採用 Stage-only 與 Trusted Publishing 雙軌遷移；無法隔離身份或產物來源的團隊繼續人工發布。這比單純比較「Token 是否能 publish」更接近真正的供應鏈風險。

7常見驗收問題

上述 FAQ 的重點，是把長尾搜尋意圖轉換成可執行的權限與責任判斷，而不是把 npm staged publishing、Trusted Publishing 或 GitHub Actions 當成互相替代的關鍵字。尤其在使用 GitHub Actions 時，工作流身份與套件授權仍需逐項核對；在使用遠端 Mac 時，建置方便也不能改變批准身份必須獨立的原則。

如果你現在的方案是「Agent 在同一台主機修改、建置、保存長期令牌，再由腳本自動發布」，它至少有三個實際缺點：程式碼來源與公開動作難以分段取證、長期憑據可能進入日誌或快取，而且建置失敗時缺少獨立的人工作止點。相較之下，租用 vpstix 的 Mac 建置環境可把原生建置與維護者批准身份分開，讓你先完成暫存、驗收和清理，再決定是否公開發布；若你只是需要臨時的 macOS 原生建置或隔離測試，這通常比把正式憑據長期放在現有工作主機更容易控制。