Plugin 發版要同步更新目錄,跨 agent 才能安裝同一版本

深讀 L2 902 字 2 分鐘 v2.0.0 更新 2026-11-16

Plugin 把擴充包成一組,安裝端依版本號判斷是否更新。目錄稱為 marketplace,負責登記 Plugin 的名稱、來源與版本;Git 則保存檔案修改紀錄,每次修改都有對應的 commit 編號。發佈 Plugin 後,還要同步目錄的版本號與 Git 編號,從目錄安裝的使用者才能取得指定內容。

先分清內容與安裝來源

這個流程把 Plugin 與目錄放在不同的倉庫。

Plugin 可以打包 Skill,也就是寫給 agent 的任務做法。使用者加入目錄後,再安裝需要的 Plugin,不必逐一複製擴充檔案。

跨 agent 安裝時,Claude Code 與 OpenAI 的 coding agent Codex 都先加入相同目錄。目錄必須同時記錄版本號與對應的 Git commit 編號,才能固定安裝內容。

圖中的安裝路徑從目錄開始:目錄列出 Plugin 來源,Claude Code 從來源取得內容,再存進本機快取。

marketplace.json 列出每個 Plugin 的名稱與來源。

更新時,安裝端先判斷版本字串

更新時,安裝端只比對版本字串;字串沒有改變,就不會取得新內容。

版本判斷先讀 plugin.json 的 version,再讀目錄檔的 version。兩處都沒有版本號時,才使用 Git commit 編號。

查更新問題時,應先確認安裝端採用哪一處版本資訊。例如,article 加入新規則並推送到倉庫後,若 plugin.json 的 version 沒變,另一台電腦執行更新仍會保留舊內容;圖中的另一個選項改變版本字串,更新端才取得新規則。

修改內容後的版本號

來源 Plugin

  • 版本號1.0.0
  • article 已加入新規則

另一台電腦更新後

  • 版本號1.0.0
  • article 仍是舊內容
版本號沒有改變,更新端保留原有內容。

先發佈內容,再讓目錄指向新版

修改 Plugin 後,先在 Plugin 倉庫更新版本號並發版。版本採用 SemVer,也就是用 3 個數字表示修改類型的版本格式:不相容修改增加第 1 個數字,新增功能增加第 2 個,錯誤修正增加第 3 個;已發佈版本的內容不能再修改。

接著到目錄倉庫提出 pull request,也就是修改合併前的審查。這次修改要同步更新版本號與 Git 編號。

每次修改目錄時,自動檢查名稱是否重複、版本號與 Git 編號的格式,以及說明中的版本是否一致。目錄說明也要列出新增 Plugin 與更新版本的方式,讓 Claude Code 能依說明完成操作。

目錄合併後,再到另一台電腦執行更新,從目錄安裝的使用者才取得新版。

內容不同時,沿著來源查回去

若 Plugin 已發版,目錄使用者卻拿不到新版,先查目錄是否仍指向舊版本。只完成 Plugin 倉庫的發版,只會影響直接從該倉庫安裝的使用者。

版本相同,還要確認支援哪些擴充

Plugin 也能包含 子 agent,也就是 Claude Code 另外派出的 agent,以及 MCP server,透過 MCP 標準提供一組可呼叫的工具。安裝同一版本,不代表每個 agent 都會啟用全部內容。

例如,自製的 zyx Plugin 在 Codex 只啟用 Skill,其中的子 agent 與 MCP 工具不會生效。來源與版本都一致後,若功能仍缺少,就要查安裝端支援哪些內容。

來源

基礎入門家目錄擴充MCPSkillPluginCLAUDE.md載入