釋出 jsc-hooks 0.3.3：版本前置檢查新增相依落後擋人，新增技能行為清單 #56

2026-08-31T08:14:07Z

jiantw83 commented

2026-08-31 08:14:07 +00:00

摘要

需求描述：盤點所有技能組，整理出所有技能的行為清單作為技能驗證的參考基準；相依技能版本不符時不得跳過更新，改為阻擋執行。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`references/behaviors.md`	新增。2 支技能的行為清單，作為技能驗證的參考基準
`hooks/version-guard.sh`	新增第二種擋人情況：技能所屬 plugin 宣告的相依版本落後就 exit 2 擋下該次呼叫
`tools/wire-cli.sh`	smoke 新增 13 條逐路徑斷言，守住新判定
`README.md`	對照表同步成擋兩種情況
三份 manifest	版本同步到 0.3.3

設計重點

相依比對自己實作，不呼叫 jsc-cli/tools/check-requires.sh：hook 專屬存放於 jsc-hooks，而且 jsc-cli 已宣告相依 jsc-hooks，反向呼叫會做出循環相依。
沿用同一份 7 項豁免清單，判定排在豁免與逃生門之後，閘門才不會擋掉解除自己的唯一路徑。
fail-open 四種：解不出安裝路徑、讀不到 manifest、manifest 沒有 jsc.requires、讀不到相依 plugin 的本機載入版本。五支 CLI 只有 claude 讀得到本機載入版本，fail-closed 會把另外四支整批鎖死。
修掉一個坑：tr -d '\n' 之後串流結尾沒有換行，while read 讀進最後一筆卻回非零，迴圈本體一次都跑不到，落後的相依會靜靜被漏掉。修法是在源頭補一個換行，並用回歸斷言守著。

測試結果

wire-cli.sh smoke codex 退出 0，lines 由腳本自印，13 條相依斷言全過。
反證兩次：把落後判定改壞、把補換行的修法拿掉，smoke 都抓到並回非零。
獨立 fixture 複驗五條路徑：相依落後 exit 2、豁免放行、資訊不全 exit 0、逃生門 exit 0。fixture 刻意讓註冊欄位寫 0.3.2、installPath 底下寫 0.2.9，擋的是 0.2.9，證實不拿註冊欄位當備援。
check-behaviors.sh、lint-scripts.sh、ste100-lint.sh 皆退出 0。

已知限制

version-guard.sh 是 PreToolUse hook。wire-cli.sh status 實測五支 CLI，只有 claude 是 wired，codex、copilot、antigravity、kiro 都是 degraded、沒有 pre-tool hook。相依版本阻擋只在 Claude Code 生效，另外四支只剩 deploy.sh 的 warn 提醒。

前置 Push Request

無

## 摘要 - 需求描述：盤點所有技能組，整理出所有技能的行為清單作為技能驗證的參考基準；相依技能版本不符時不得跳過更新，改為阻擋執行。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `references/behaviors.md` | 新增。2 支技能的行為清單，作為技能驗證的參考基準 | | `hooks/version-guard.sh` | 新增第二種擋人情況：技能所屬 plugin 宣告的相依版本落後就 exit 2 擋下該次呼叫 | | `tools/wire-cli.sh` | smoke 新增 13 條逐路徑斷言，守住新判定 | | `README.md` | 對照表同步成擋兩種情況 | | 三份 manifest | 版本同步到 0.3.3 | ## 設計重點 - 相依比對自己實作，不呼叫 `jsc-cli/tools/check-requires.sh`：hook 專屬存放於 `jsc-hooks`，而且 `jsc-cli` 已宣告相依 `jsc-hooks`，反向呼叫會做出循環相依。 - 沿用同一份 7 項豁免清單，判定排在豁免與逃生門之後，閘門才不會擋掉解除自己的唯一路徑。 - fail-open 四種：解不出安裝路徑、讀不到 manifest、manifest 沒有 `jsc.requires`、讀不到相依 plugin 的本機載入版本。五支 CLI 只有 claude 讀得到本機載入版本，fail-closed 會把另外四支整批鎖死。 - 修掉一個坑：`tr -d '\n'` 之後串流結尾沒有換行，`while read` 讀進最後一筆卻回非零，迴圈本體一次都跑不到，落後的相依會靜靜被漏掉。修法是在源頭補一個換行，並用回歸斷言守著。 ## 測試結果 - `wire-cli.sh smoke codex` 退出 0，`lines` 由腳本自印，13 條相依斷言全過。 - 反證兩次：把落後判定改壞、把補換行的修法拿掉，smoke 都抓到並回非零。 - 獨立 fixture 複驗五條路徑：相依落後 exit 2、豁免放行、資訊不全 exit 0、逃生門 exit 0。fixture 刻意讓註冊欄位寫 0.3.2、`installPath` 底下寫 0.2.9，擋的是 0.2.9，證實不拿註冊欄位當備援。 - `check-behaviors.sh`、`lint-scripts.sh`、`ste100-lint.sh` 皆退出 0。 ## 已知限制 `version-guard.sh` 是 PreToolUse hook。`wire-cli.sh status` 實測五支 CLI，只有 claude 是 wired，codex、copilot、antigravity、kiro 都是 degraded、沒有 pre-tool hook。**相依版本阻擋只在 Claude Code 生效**，另外四支只剩 `deploy.sh` 的 warn 提醒。 ## 前置 Push Request - 無

jiantw83 added 7 commits 2026-08-31 08:14:07 +00:00

feat(version-guard): 版本前置檢查新增相依版本落後的擋人情況 5c2727bf56

版本前置檢查多一種擋人情況。技能所屬 plugin 的 manifest 在 jsc.requires
宣告的相依 plugin，只要有一項的本機實際載入版本落後宣告的最低版本，
就以 exit 2 擋下這一次技能呼叫。訊息逐項講明哪一個 plugin、需要哪一版、
目前哪一版、怎麼補。

相依宣告原本只有部署那一端會回報，沒有任何一道閘門擋。機器上因此會出現
版本互相搭不起來的 plugin 組合，技能跑到一半才失敗，使用者也看不出要更新
哪一個 plugin。

判定邏輯自己實作，不呼叫 jsc-cli 的 check-requires.sh。hook 一律專屬存放在
jsc-hooks，不可散落到別的 domain；jsc-cli 也已經宣告相依 jsc-hooks，
反向呼叫會做出循環相依。安裝路徑解析抽成 install_path()，與本機載入版本
共用同一條規則，各寫一份就會漂移。相依檢查排在豁免清單與逃生門之後、
遠端比對之前，全部讀本機檔案，離線的機器也判得動。豁免沿用同一份 7 項清單，
相依落後不另立短清單：這幾支同樣是更新與修復的唯一路徑，用哪一個理由擋
都是死鎖。四種情況一律安靜放行：解不出安裝路徑、讀不到 manifest、
manifest 沒有 jsc.requires、讀不到相依 plugin 的本機載入版本。五支 CLI
只有 claude 讀得到本機載入版本，fail-closed 會把另外四支整批鎖死。

所屬功能：版本前置檢查的相依版本閘門。

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

test(smoke): 接線腳本冒煙補上相依版本檢查的十三條判定斷言 15f7dcc5fb

接線腳本的 smoke 多一個沙箱，逐條跑相依版本檢查的判定路徑並比對結束碼：
相依落後的擋人與訊息內容、相依相等與超前的放行、豁免技能在相依落後時
照樣放行、同一個 plugin 底下非豁免技能照樣被擋、四種 fail-open、
逃生門蓋過相依落後，另加一條回歸——多行縮排的 manifest，jsc.requires
的最後一個鍵也要解得到。

原本的 hook 模式只驗那支腳本跑得完，相依版本這一段一條判定路徑都沒走到。
新的擋人情況判錯方向，不是把每一次技能呼叫鎖死，就是整道護欄形同虛設，
沒有斷言就看不出來。多行縮排是真實 manifest 的樣子，解析漏掉最後一個鍵
會讓落後的相依靜靜被放行，那一條非釘住不可。

沙箱自備一份暫時的 HOME，註冊檔路徑由 $HOME 決定，不覆寫就會讀到使用者
真正的安裝清單。假的 installed_plugins.json 與各 plugin 的 manifest 都放進
那份 HOME，註冊欄位故意寫成很新的版本、installPath 底下的 manifest 寫舊版，
把「只認 installPath 底下那份檔案」的規則一起釘住。GITEA_HOST 一律清空，
放行的案例才不會往下走到遠端比對真的連網。擋人的兩條另外比訊息字串，
比的是同一次執行留下的輸出。新增計數器 smoke_n_vg 與預期值
SMOKE_EXPECT_VG，一併納入總數、逐類比對訊息與結果摘要，判定路徑增減時
只改腳本裡的預期值。

所屬功能：版本前置檢查的相依版本閘門。

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

docs(readme): 說明文件同步版本閘門的兩種擋人情況與冒煙沙箱 3485213145

比較表的 version-guard.sh 那一列改寫成擋兩種情況，逐項寫明相依版本檢查
讀哪一份 manifest、比哪一個版本、訊息講到什麼程度，也把新增的四種
fail-open 併進原本的放行清單，並註明兩種擋人情況共用同一份 7 項豁免清單。
wire-cli.sh 那一列補一句新的冒煙沙箱與它涵蓋的判定路徑。

文件停在只擋一種情況的舊敘述，讀的人會以為相依落後照樣放行，被擋下來時
找不到規則的出處。冒煙那一列不提新沙箱，維護者也看不出相依版本這一段
已經有斷言守著。

兩種擋人情況、fail-open 清單與共用的豁免清單都寫進表格，清單的唯一真實
來源仍然指向 hooks/version-guard.sh 的檔頭。冒煙那一句只講沙箱與涵蓋範圍，
不抄斷言條數；條數以腳本自己印出來的 lines 那一行為準，散文不另記一份數字。

所屬功能：版本前置檢查的相依版本閘門。

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

docs(references): 新增技能行為清單，作為技能驗證的比對基準 63c8073be1

新增 references/behaviors.md，逐支列出本存取庫 hooks-install 與 repair
兩支技能的行為：觸發時機、關鍵步驟、外部呼叫、完成條件與可驗證跡象。

技能驗證原本沒有一份基準可比。驗的人只能回頭讀技能內文，讀到的是當下的
寫法，不是講好的行為；技能改壞了、少走一道關卡，比對不出來。

一支技能一張表，一項一列，內容寫成看得出對錯的敘述，可驗證跡象逐條指到
磁碟上真的留得下的東西。技能異動時，在同一個 PR 內一起更新這一頁。

所屬功能：技能驗證基準。

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

chore(plugin): 三份外掛設定檔版本推進到 0.3.3 6870975e08

plugin.json、.claude-plugin/plugin.json 與 .codex-plugin/plugin.json
的版本一起從 0.3.2 推到 0.3.3。

這一輪改了版本前置檢查的行為，多擋一種情況。版本不推上去，版本前置檢查
就看不出機器上載入的是舊版，使用者會拿舊的閘門跑新的流程，相依落後
一樣不會被擋下來。

三份設定檔改成同一個版本，避免不同 CLI 讀到不一樣的宣告。

所屬功能：版本前置檢查的相依版本閘門。

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

Merge pull request '版本前置檢查新增相依落後擋人、新增技能行為清單' (#54 ) from feat/skill-behaviors-and-version-block/version-guard-requires-block into feat/skill-behaviors-and-version-block/main 30c395b4d0

Merge pull request '收攏技能行為清單與版本前置檢查相依擋人改動' (#55 ) from feat/skill-behaviors-and-version-block/main into develop 9ccf0d555c

admin approved these changes 2026-08-31 08:18:49 +00:00

admin merged commit 510142c3f6 into master

2026-08-31 08:18:51 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/hooks#56