收攏技能行為清單與版本前置檢查相依擋人改動 #55

2026-08-31T05:42:03Z

jiantw83 commented

2026-08-31 05:42:03 +00:00

摘要

需求描述：本 PR 是功能主幹的收攏層。子功能 PR 先併入 feat/skill-behaviors-and-version-block/main，再由本 PR 一次併回 develop。本輪功能涵蓋兩件事：新增 references/behaviors.md 當作技能驗證的行為基準、版本前置檢查新增相依版本落後的擋人情況。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
由子功能 PR 帶入	本 PR 自身不提交檔案。內容來自 plugins/hooks#54，該 PR 併入功能主幹後才會出現在這裡

設計重點

走完整階梯。子功能分支先併入功能主幹，功能主幹再併回 develop，中間不跳級。
功能主幹集中審查。同一輪功能的多條子功能分支併攏後，develop 只收一次。

測試結果

本 PR 不含自身提交，測試結果以子功能 PR plugins/hooks#54 為準。該 PR 已跑 sh -n、bash -n、lint-scripts.sh、check-behaviors.sh、ste100-lint.sh，全數 exit 0。
wire-cli.sh smoke 尚未跑，原因寫在 plugins/hooks#54 的測試結果那一節：前段 smoke_one 會動到真正的 $JSC_HOME，不是唯讀。請在拋棄式環境補跑。

前置 Push Request

plugins/hooks#54：#54

## 摘要 - 需求描述：本 PR 是功能主幹的收攏層。子功能 PR 先併入 `feat/skill-behaviors-and-version-block/main`，再由本 PR 一次併回 `develop`。本輪功能涵蓋兩件事：新增 `references/behaviors.md` 當作技能驗證的行為基準、版本前置檢查新增相依版本落後的擋人情況。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | 由子功能 PR 帶入 | 本 PR 自身不提交檔案。內容來自 plugins/hooks#54，該 PR 併入功能主幹後才會出現在這裡 | ## 設計重點 - 走完整階梯。子功能分支先併入功能主幹，功能主幹再併回 `develop`，中間不跳級。 - 功能主幹集中審查。同一輪功能的多條子功能分支併攏後，`develop` 只收一次。 ## 測試結果 - 本 PR 不含自身提交，測試結果以子功能 PR plugins/hooks#54 為準。該 PR 已跑 `sh -n`、`bash -n`、`lint-scripts.sh`、`check-behaviors.sh`、`ste100-lint.sh`，全數 exit 0。 - `wire-cli.sh smoke` 尚未跑，原因寫在 plugins/hooks#54 的測試結果那一節：前段 `smoke_one` 會動到真正的 `$JSC_HOME`，不是唯讀。請在拋棄式環境補跑。 ## 前置 Push Request - plugins/hooks#54：https://gitea.jsc.idv.tw/plugins/hooks/pulls/54

jiantw83 added a new dependency 2026-08-31 05:42:09 +00:00

#54 版本前置檢查新增相依落後擋人、新增技能行為清單

jiantw83 added 6 commits 2026-08-31 08:09:23 +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

jiantw83 merged commit 9ccf0d555c into develop

2026-08-31 08:10:36 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Depends on

#54 版本前置檢查新增相依落後擋人、新增技能行為清單

plugins/hooks

Reference: plugins/hooks#55