---
site: "zyx.tw"
title: "Plugin 發版要同步更新目錄，跨 agent 才能安裝同一版本"
description: "從版本判斷、固定來源到目錄同步，串起完整發版流程。"
url: "https://www.zyx.tw/map/basics/plugin-ships-by-version"
---

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

紀錄 040，深讀 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 從來源取得內容，再存進本機快取。

```text
╭─────────────╮  list   ╭─────────────╮  copy   ╭─────────────╮
│ MARKETPLACE │ ──────> │   PLUGIN    │ ──────> │    CACHE    │
│ catalog     │         │ source repo │         │ by version  │
╰─────────────╯         ╰─────────────╯         ╰──────┬──────╯
                                                       │ load
                                                ╭──────┴──────╮
                                                │   SESSION   │
                                                ╰─────────────╯
```

Figure: A marketplace catalog lists plugins. A plugin is copied from its source repository into a local cache named by version, and a session loads it from the cache.

1. Catalog: marketplace.json 列出每個 Plugin 的名稱與來源。
2. Source: 來源是 Git 倉庫或資料夾，裡面有 plugin.json。
3. Cache: 安裝時依版本存進本機快取。
4. Session: 新對話從快取載入 Plugin。

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

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

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

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

**修改內容後的版本號 保留 1.0.0**

來源 Plugin:
- 版本號 (1.0.0)
- article 已加入新規則

另一台電腦更新後:
- 版本號 (1.0.0)
- article 仍是舊內容

版本號沒有改變，更新端保留原有內容。

**修改內容後的版本號 改成 1.0.1**

來源 Plugin:
- 版本號 (1.0.1)
- article 已加入新規則

另一台電腦更新後:
- 版本號 (1.0.1)
- 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 工具不會生效。來源與版本都一致後，若功能仍缺少，就要查安裝端支援哪些內容。

## 來源

- [Plugin manifest reference](https://code.claude.com/docs/en/plugins-reference), Claude Code docs
- [Create a marketplace](https://code.claude.com/docs/en/plugin-marketplaces), Claude Code docs
- [Semantic Versioning 2.0.0](https://semver.org/), semver.org

## 地圖

- 先讀：[Skill 保存同類任務的做法，個案細節留在專案](https://www.zyx.tw/map/basics/skill-loads-on-demand.md)
- 回到：[基礎](https://www.zyx.tw/map.md)
