Plugin 發版要同步更新目錄,跨 agent 才能安裝同一版本
深讀 L2 902 字 2 分鐘 v2.0.0 更新 2026-11-16
Plugin 把擴充包成一組,安裝端依版本號判斷是否更新。目錄稱為 marketplace,負責登記 Plugin 的名稱、來源與版本;Git 則保存檔案修改紀錄,每次修改都有對應的 commit 編號。發佈 Plugin 後,還要同步目錄的版本號與 Git 編號,從目錄安裝的使用者才能取得指定內容。
先分清內容與安裝來源
這個流程把 Plugin 與目錄放在不同的倉庫。
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 倉庫的發版,只會影響直接從該倉庫安裝的使用者。
版本相同,還要確認支援哪些擴充
例如,自製的 zyx Plugin 在 Codex 只啟用 Skill,其中的子 agent 與 MCP 工具不會生效。來源與版本都一致後,若功能仍缺少,就要查安裝端支援哪些內容。
來源
- Plugin manifest reference Claude Code docs
- Create a marketplace Claude Code docs
- Semantic Versioning 2.0.0 semver.org