Files

T

jiantw83andClaude Sonnet 5 1030f9d403 feat(shared): 新增14個共用spec、models/todo工具與樣板產生器，收斂跨repo重複規範

依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含
conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/
subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/
node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token
優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力
查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json
單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／
README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的
log／機密遮蔽三語言參考實作。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-08-11 06:02:30 +00:00

4.4 KiB

Raw Permalink Blame History

name, description

name	description
spec-plugin-version	JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、同一 PR 只以 master 版本計算一次最終升版、新 plugin 首發 0.0.1、plugin 更名（name 欄位改變）視為新 plugin 並把版號重置為 0.0.1、一般變更 patch +1 且 master patch 到 9 後才進位 minor（0.0.9 → 0.1.0）、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc-shared:spec-plugin-version、或要調整任一 JSC plugin（jsc-code／jsc-doc／jsc-shared）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

name

description

spec-plugin-version

JSC plugins 共用「plugin 版號規則」：三個 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）同步 bump 且版本一致、bump 前對照發佈分支（master）現行版本確保單調遞增、同一 PR 只以 master 版本計算一次最終升版、新 plugin 首發 0.0.1、plugin 更名（name 欄位改變）視為新 plugin 並把版號重置為 0.0.1、一般變更 patch +1 且 master patch 到 9 後才進位 minor（0.0.9 → 0.1.0）、commit 訊息用 chore(plugin 版本)。當其他 skill 內文引用 spec-plugin-version 或 /jsc-shared:spec-plugin-version、或要調整任一 JSC plugin（jsc-code／jsc-doc／jsc-shared）的版本號時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

spec-plugin-version — 共用 plugin 版號規則

調整任一 JSC plugin（jsc-code／jsc-doc／jsc-shared 等）的版本號時，一律遵守以下規則。

三個 manifest 同步 bump

版本號同時存在於三個 manifest：plugin.json（Antigravity）、.claude-plugin/plugin.json（Claude Code）、.codex-plugin/plugin.json（Codex）。
三者必須一起 bump 且版本一致，不得只改其中一個 —— 四家助理都以 git 內容／版本判斷是否有更新。
.claude-plugin/marketplace.json／.agents/plugins/marketplace.json 沒有版本欄位，不需改。

版本單調遞增（以發佈分支為準）

bump 前先確認發佈分支（master）目前的版本，不能只看目前工作分支：
```
git show origin/master:plugin.json | grep version
```
新版本必須大於 master 現行版本。工作分支（如 develop）可能落後或經過 revert，直接在其舊版本上 +1 會讓版本倒退（例：master 已 0.0.4，develop 還在 0.0.1，此時應 bump 至 0.0.5 而非 0.0.2）——已安裝 0.0.4 的助理會因版本倒退而抓不到更新。
同一 PR／同一批變更只需最終一個版本；多次修改不必逐次 bump，也不要依工作分支上的中間版本連續累加。例如 master 是 0.0.7 時，同一 PR 的最終版本是 0.0.8。
例外：plugin 更名時本節不適用 —— 更名後的 plugin 是獨立的安裝識別，與舊名沒有版本比較關係，見下節「plugin 更名」。

版號選擇

新 plugin 首發：0.0.1（即使是從 template 複製建立，也要把 template 殘留的版本改回 0.0.1）。
plugin 更名（manifest 的 name 欄位改變，例如 jsc → jsc-code）：視為新 plugin，三份 manifest 版號一律重置為 0.0.1，不沿用舊名的版本序列。

理由：各助理以 <plugin 名>@<marketplace 名> 作為安裝識別鍵（例如 jsc-code@code 與 jsc@code 是兩筆獨立條目）。更名發佈後，舊 plugin 會被移除、新 plugin 為首次安裝，兩者之間不存在版本比較，因此不會發生版本倒退，「版本單調遞增」不適用。git 歷史雖然延續，但版號描述的是該 plugin 識別的演進，而非 repo 的演進。

更名發佈的配套動作：使用者端必須先移除舊 plugin、再安裝新 plugin（不是 update），並重開工作階段；~/.claude/settings.json 的 enabledPlugins 舊鍵需一併清除。
一般變更（skill 新增／修改／移除、manifest 設定調整）：以 master 現行版本 patch +1；patch 只使用 0 到 9，只有 master 基準版 patch 已是 9 時才進位 minor 並把 patch 歸零，例如 0.0.8 → 0.0.9 → 0.1.0。
重大改版（skill 大規模重構、破壞相容的呼叫方式變更）：minor +1、patch 歸零。

何時必須 bump

任何希望四家助理拿到更新的變更都要 bump：skill 內容異動、新增／移除 skill、manifest 設定變更、README 的 Skills 目錄實質變更。
純粹不影響安裝內容的變更（如 .gitea/ CI 設定）可不 bump。

commit 與發佈

版本 bump 的 commit 訊息格式依 /jsc-shared:spec-conventional-commit，type 固定用 chore、範圍固定為 plugin 版本（例：chore(plugin 版本): 三家 manifest 升版 X.Y.Z；僅含 3 個 manifest 的版本變更，與其他設定異動混提時說明清楚）。
合併發佈後，各助理的更新方式見該 plugin README（claude plugin update／codex plugin marketplace upgrade／Antigravity 重新安裝／OpenCode 重新複製 skills/）。

4.4 KiB Raw Permalink Blame History Unescape Escape