發佈 jsc-hooks 0.0.8：技能版本前置檢查 #13

2026-08-25T03:53:13Z

jiantw83 commented

2026-08-25 03:53:13 +00:00

變更摘要

技能組的每一支技能在被呼叫前，先確認本機版本沒有落後遠端發佈版本；落後就擋下該次呼叫並提示更新指令。

判定在程式層——新增 hooks/version-guard.sh，掛在 PreToolUse（matcher Skill）。寫在技能內文的規則模型可以無視，只有 hook 擋得住。

判準

情況	行為
本機 < 遠端	擋下（exit 2），印出更新指令
本機 = 遠端	放行
本機 > 遠端	放行——開發技能組時本機本來就會超前 `master`，擋下去維護者自己動不了
查不到遠端版本	擋（fail-closed）。查詢失敗先重試一次，仍失敗才擋

版本取值：比對的是遠端發佈版本與本機實際載入的版本。實際載入版本要讀 installed_plugins.json 的 installPath 底下那份 plugin.json，不能只看註冊欄位——兩者可能不同，只看註冊值會放過真正被載入的舊版。

遠端站台從已註冊的 jsc marketplace 來源推導（known_marketplaces.json），其次才用 GITEA_HOST。查詢走公開 raw 路徑，不需要 token。

豁免清單

技能	為什麼不能擋
`jsc-cli:deploy`	更新整組技能的入口。擋了就沒有任何方法更新，形成死鎖
`jsc-hooks:hooks-install`	更新後要重新接線，擋了會讓更新做一半卡住
`jsc-cli:models`	SDLC 階段閘門依賴它產生 `model-tags.tsv`
`jsc-meta:*`	開發技能組本身的工具，擋了就修不了技能組

逃生門與快取

JSC_VERSION_GUARD=off 完全略過檢查（離線工作用）。fail-closed 沒有逃生門會讓離線時整組技能停擺。
JSC_VERSION_TTL 遠端查詢的快取秒數，預設 600。快取放 $JSC_HOME/version-cache/{domain}，避免每次呼叫都打網路。

驗證

實測六種情境全部符合預期：非 jsc 技能放行、四類豁免放行、逃生門放行，以及真實命中一次——本機 jsc-sdlc 0.0.8 對遠端 0.0.9，擋下並印出更新指令：

[jsc][版本檢查][ERR]：jsc-sdlc 本機版本 0.0.8 落後遠端發佈版本 0.0.9，本次技能呼叫已擋下
更新指令：claude plugin marketplace update jsc && claude plugin update jsc-sdlc@jsc
更新整組：/jsc-cli:deploy　｜　確定要略過檢查：JSC_VERSION_GUARD=off

sh -n、hooks.json JSON 格式、STE100 lint 均通過。

注意事項

沒有 pre-tool hook 的 CLI（codex、copilot、kiro、antigravity）接不上這道檢查。hooks-install 已寫明要據實回報，不得暗示每個 CLI 都有保護。

## 變更摘要技能組的每一支技能在被呼叫前，先確認本機版本沒有落後遠端發佈版本；落後就擋下該次呼叫並提示更新指令。判定在**程式層**——新增 `hooks/version-guard.sh`，掛在 `PreToolUse`（matcher `Skill`）。寫在技能內文的規則模型可以無視，只有 hook 擋得住。 ## 判準 | 情況 | 行為 | | --- | --- | | 本機 < 遠端 | **擋下**（exit 2），印出更新指令 | | 本機 = 遠端 | 放行 | | 本機 > 遠端 | 放行——開發技能組時本機本來就會超前 `master`，擋下去維護者自己動不了 | | 查不到遠端版本 | **擋**（fail-closed）。查詢失敗先重試一次，仍失敗才擋 | **版本取值**：比對的是遠端發佈版本與本機**實際載入**的版本。實際載入版本要讀 `installed_plugins.json` 的 `installPath` 底下那份 `plugin.json`，不能只看註冊欄位——兩者可能不同，只看註冊值會放過真正被載入的舊版。 **遠端站台**從已註冊的 `jsc` marketplace 來源推導（`known_marketplaces.json`），其次才用 `GITEA_HOST`。查詢走公開 raw 路徑，不需要 token。 ## 豁免清單 | 技能 | 為什麼不能擋 | | --- | --- | | `jsc-cli:deploy` | 更新整組技能的入口。擋了就沒有任何方法更新，形成死鎖 | | `jsc-hooks:hooks-install` | 更新後要重新接線，擋了會讓更新做一半卡住 | | `jsc-cli:models` | SDLC 階段閘門依賴它產生 `model-tags.tsv` | | `jsc-meta:*` | 開發技能組本身的工具，擋了就修不了技能組 | ## 逃生門與快取 - `JSC_VERSION_GUARD=off` 完全略過檢查（離線工作用）。fail-closed 沒有逃生門會讓離線時整組技能停擺。 - `JSC_VERSION_TTL` 遠端查詢的快取秒數，預設 600。快取放 `$JSC_HOME/version-cache/{domain}`，避免每次呼叫都打網路。 ## 驗證實測六種情境全部符合預期：非 jsc 技能放行、四類豁免放行、逃生門放行，以及**真實命中一次**——本機 `jsc-sdlc` 0.0.8 對遠端 0.0.9，擋下並印出更新指令： ``` [jsc][版本檢查][ERR]：jsc-sdlc 本機版本 0.0.8 落後遠端發佈版本 0.0.9，本次技能呼叫已擋下更新指令：claude plugin marketplace update jsc && claude plugin update jsc-sdlc@jsc 更新整組：/jsc-cli:deploy　｜　確定要略過檢查：JSC_VERSION_GUARD=off ``` `sh -n`、`hooks.json` JSON 格式、STE100 lint 均通過。 ## 注意事項沒有 pre-tool hook 的 CLI（codex、copilot、kiro、antigravity）接不上這道檢查。`hooks-install` 已寫明要據實回報，不得暗示每個 CLI 都有保護。

jiantw83 added 3 commits 2026-08-25 03:53:13 +00:00

feat(version-guard): 技能使用前檢查版本，落後遠端就擋下並提示更新 60b6b8fe00

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs(README): 補上 version-guard 與其環境變數說明 922a95f147

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

chore(plugin 版本): 三份 manifest 升版至 0.0.8 3b0c8f0e33

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

admin approved these changes 2026-08-25 04:56:19 +00:00

admin merged commit 8309e24a00 into master

2026-08-25 04:56:23 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/hooks#13