相依版本不符改為照樣更新並提醒、新增技能行為清單 #44

2026-08-31T05:36:33Z

jiantw83 commented

2026-08-31 05:36:33 +00:00

摘要

需求描述：deploy.sh update 原本遇到相依版本不符就跳過那個 domain。跳過會讓落後的 domain 永遠拿不到它在等的相依版本，兩個 domain 互相等就死鎖。這次把阻擋移到技能叫用那一層，改由 jsc-hooks 的 version-guard.sh 執行。check-requires.sh 同時把「版本落後」與「判不出結論」拆成兩個結束碼，避免環境壞掉被說成版本落後。另外新增 references/behaviors.md，當作技能驗證的行為基準。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`references/behaviors.md`	新增。逐支列出 5 支技能的觸發時機、關鍵步驟、外部呼叫、完成條件與可驗證跡象，供技能驗證比對。技能日後異動時，要在同一個 PR 內更新這一頁
`tools/deploy.sh`	改寫 `check_requires()` 的分流。相依版本不符從「印 skip 並跳過該 domain」改成「印 warn 並照樣更新」；判不出結論印 `note`，也照樣更新；只有檢查腳本自己出錯才印 `skip`、跳過該 domain 並記為失敗。檔頭補上 `warn` 與 `compat` 兩列輸出格式，以及四種結束碼的分流說明
`tools/check-requires.sh`	把原本的結束碼 1 拆成兩碼。1 只代表相依版本不符或缺相依 plugin；新增 4 代表判不出結論，也就是 manifest 讀不到、不是有效 JSON、或缺 python3。這三種情況的 `status` 一併從 `blocked` 改成 `unknown`。檔頭同步記載新的結束碼約定與拆碼理由
`skills/deploy/SKILL.md`	第 4 步寫明四種結束碼各自的處置與理由，完成條件改成「每個 skip 都要有檢查腳本失敗或本地樹的原因，每個 warn 都要點名還缺哪一版」；第 7 步的回報清單補上 `warn` 行
`README.md`	工具表的 `check-requires.sh` 那列與 `deploy` 技能段落，同步 warn 照樣更新、skip 只留給檢查腳本出錯的新行為
`plugin.json`	版本從 0.2.5 推到 0.2.6
`.claude-plugin/plugin.json`	版本從 0.2.5 推到 0.2.6，與正本 manifest 一致
`.codex-plugin/plugin.json`	版本從 0.2.5 推到 0.2.6，與正本 manifest 一致

設計重點

更新不設閘門，叫用才設閘門。相依版本不符時照樣更新，落後的 domain 才追得上版本；真正的阻擋放在技能被叫用的時候，由 jsc-hooks 的 version-guard.sh 擋下該 domain 的技能。
「沒有證據」不等於「落後」。判不出結論走 note，版本落後走 warn，兩者講不同的話。混成同一句，操作者會去補一個根本不存在的版本問題。
檢查腳本自己壞掉仍舊擋。結束碼 2 或其他碼代表用法錯誤或腳本壞掉，讀不到結論就不能當成通過，維持印 skip、跳過該 domain 並記為失敗。
結束碼拆成四路後，呼叫端才分得出誰是誰。0 照常更新、1 印 warn、4 印 note、其他印 skip，四條路各自對應一種事實。
references/behaviors.md 把技能行為寫成可比對的表，技能驗證不再靠人工讀 SKILL.md 推測。

測試結果

bash -n tools/deploy.sh 與 bash -n tools/check-requires.sh：兩支都結束碼 0，語法通過。
sh /root/plugins/meta/tools/lint-scripts.sh /root/plugins/cli：結束碼 0，輸出「腳本檢查通過：10 支（語法、可執行、結束碼宣告），其中 0 支判定為函式庫」。
sh /root/plugins/meta/tools/check-behaviors.sh /root/plugins/cli：結束碼 0，輸出「行為清單檢查通過：/root/plugins/cli/references/behaviors.md 對上 5 支技能，五個欄位齊全」。
sh /root/plugins/meta/tools/ste100-lint.sh 掃五個異動檔（references/behaviors.md、tools/deploy.sh、tools/check-requires.sh、skills/deploy/SKILL.md、README.md）：結束碼 0，沒有命中。
未測項目：沒有實跑 deploy.sh update，也沒有實跑 check-requires.sh 的四種結束碼。這兩者都會改寫本機各 CLI 的外掛安裝狀態，不是唯讀操作，本次只做唯讀檢查。shellcheck 未安裝在這台機器，因此沒有跑靜態檢查。

前置 Push Request

無

## 摘要 - 需求描述：`deploy.sh update` 原本遇到相依版本不符就跳過那個 domain。跳過會讓落後的 domain 永遠拿不到它在等的相依版本，兩個 domain 互相等就死鎖。這次把阻擋移到技能叫用那一層，改由 `jsc-hooks` 的 `version-guard.sh` 執行。`check-requires.sh` 同時把「版本落後」與「判不出結論」拆成兩個結束碼，避免環境壞掉被說成版本落後。另外新增 `references/behaviors.md`，當作技能驗證的行為基準。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `references/behaviors.md` | 新增。逐支列出 5 支技能的觸發時機、關鍵步驟、外部呼叫、完成條件與可驗證跡象，供技能驗證比對。技能日後異動時，要在同一個 PR 內更新這一頁 | | `tools/deploy.sh` | 改寫 `check_requires()` 的分流。相依版本不符從「印 skip 並跳過該 domain」改成「印 warn 並照樣更新」；判不出結論印 `note`，也照樣更新；只有檢查腳本自己出錯才印 `skip`、跳過該 domain 並記為失敗。檔頭補上 `warn` 與 `compat` 兩列輸出格式，以及四種結束碼的分流說明 | | `tools/check-requires.sh` | 把原本的結束碼 1 拆成兩碼。1 只代表相依版本不符或缺相依 plugin；新增 4 代表判不出結論，也就是 manifest 讀不到、不是有效 JSON、或缺 python3。這三種情況的 `status` 一併從 `blocked` 改成 `unknown`。檔頭同步記載新的結束碼約定與拆碼理由 | | `skills/deploy/SKILL.md` | 第 4 步寫明四種結束碼各自的處置與理由，完成條件改成「每個 skip 都要有檢查腳本失敗或本地樹的原因，每個 warn 都要點名還缺哪一版」；第 7 步的回報清單補上 `warn` 行 | | `README.md` | 工具表的 `check-requires.sh` 那列與 `deploy` 技能段落，同步 warn 照樣更新、skip 只留給檢查腳本出錯的新行為 | | `plugin.json` | 版本從 0.2.5 推到 0.2.6 | | `.claude-plugin/plugin.json` | 版本從 0.2.5 推到 0.2.6，與正本 manifest 一致 | | `.codex-plugin/plugin.json` | 版本從 0.2.5 推到 0.2.6，與正本 manifest 一致 | ## 設計重點 - 更新不設閘門，叫用才設閘門。相依版本不符時照樣更新，落後的 domain 才追得上版本；真正的阻擋放在技能被叫用的時候，由 `jsc-hooks` 的 `version-guard.sh` 擋下該 domain 的技能。 - 「沒有證據」不等於「落後」。判不出結論走 `note`，版本落後走 `warn`，兩者講不同的話。混成同一句，操作者會去補一個根本不存在的版本問題。 - 檢查腳本自己壞掉仍舊擋。結束碼 2 或其他碼代表用法錯誤或腳本壞掉，讀不到結論就不能當成通過，維持印 `skip`、跳過該 domain 並記為失敗。 - 結束碼拆成四路後，呼叫端才分得出誰是誰。0 照常更新、1 印 warn、4 印 note、其他印 skip，四條路各自對應一種事實。 - `references/behaviors.md` 把技能行為寫成可比對的表，技能驗證不再靠人工讀 SKILL.md 推測。 ## 測試結果 - `bash -n tools/deploy.sh` 與 `bash -n tools/check-requires.sh`：兩支都結束碼 0，語法通過。 - `sh /root/plugins/meta/tools/lint-scripts.sh /root/plugins/cli`：結束碼 0，輸出「腳本檢查通過：10 支（語法、可執行、結束碼宣告），其中 0 支判定為函式庫」。 - `sh /root/plugins/meta/tools/check-behaviors.sh /root/plugins/cli`：結束碼 0，輸出「行為清單檢查通過：/root/plugins/cli/references/behaviors.md 對上 5 支技能，五個欄位齊全」。 - `sh /root/plugins/meta/tools/ste100-lint.sh` 掃五個異動檔（`references/behaviors.md`、`tools/deploy.sh`、`tools/check-requires.sh`、`skills/deploy/SKILL.md`、`README.md`）：結束碼 0，沒有命中。 - 未測項目：沒有實跑 `deploy.sh update`，也沒有實跑 `check-requires.sh` 的四種結束碼。這兩者都會改寫本機各 CLI 的外掛安裝狀態，不是唯讀操作，本次只做唯讀檢查。`shellcheck` 未安裝在這台機器，因此沒有跑靜態檢查。 ## 前置 Push Request - 無

jiantw83 added 5 commits 2026-08-31 05:36:33 +00:00

docs(references): 新增五支技能的行為清單作為驗證基準 76b3f2dcb6

What：新增 references/behaviors.md。這一頁列出 delegate、deploy、doctor、models、setup 五支技能的行為。每支技能記錄觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象五個項目。

Why：技能驗證以前沒有共同基準。驗證的人只能自己讀 SKILL.md 反推該有哪些行為，兩個人推出來的結果不會一樣。有了這一頁，驗證就比對同一份基準。

How：一支技能一個章節，章節內用一張兩欄表格寫滿五個項目。外部呼叫欄位寫出腳本路徑與子命令，可驗證跡象欄位寫出實際會被改動的檔案或目錄。頁首寫明規則：技能異動時，要在同一個 PR 內一起更新這一頁。

Who：技能驗證基準。

fix(check-requires): 分開相依不符與判不出結論的結束碼 4ed0bf11a2

What：把原本的結束碼 1 拆成兩個。1 只代表相依版本不符或缺相依 plugin。新增 4 代表判不出結論，成因是 manifest 不存在、不是有效 JSON、或缺 python3。這三種成因的輸出從 status=blocked 改成 status=unknown。

Why：兩種成因共用同一個結束碼，呼叫端就只能用同一句話講兩件事。環境壞掉會被講成版本落後。操作者照著去補版本，補到最後也碰不到真正的問題點。

How：找不到 manifest、找不到 python3、JSON 解析失敗三處改回傳 4，狀態字串一併改成 unknown。檔頭的輸出格式表與結束碼表跟著改寫，並寫下 1 與 4 分開的理由。

Who：相依檢查結論分流。

fix(deploy): 相依版本不符改成照樣更新並提醒 ed4092bb3d

What：check_requires() 對 check-requires.sh 的四種結束碼重新分流。0 照常更新。1 改印一行 warn，該 domain 照樣更新，訊息寫出還缺哪一版。4 印一行 note，也照樣更新。2 或其他代碼維持印 skip、跳過該 domain，並記成失敗。

Why：跳過會讓落後的 domain 永遠等不到它要的相依版本，也就永遠更新不到，兩個 domain 互相等就形成死鎖。阻擋移到技能叫用那一層，由 jsc-hooks 的 version-guard.sh 執行，更新照跑不會壞事。判不出結論跟版本落後要講不同的話，混成一句會把環境問題誤導成版本問題。檢查腳本自己出錯是另一回事，讀不到結論就不能當成通過。

How：結束碼 1 的分支從印 skip、回傳 1 改成印 warn、回傳 0，結束碼 4 新增一個印 note、回傳 0 的分支，其餘代碼維持原本的 skip 與 FAILED。函式上方與檔頭補上這四條分流的理由。檔頭的輸出格式表補進 warn 與 compat 兩欄，結束碼說明也把 warn 列為不算失敗但要據實回報。

Who：相依版本不符的處置。

docs(deploy): 同步相依檢查改為照樣更新的行為 5f1c4cc6d7

What：SKILL.md 第 4 步改寫成四種結束碼的處置，第 7 步的回報清單補上 warn 行。README 的 check-requires.sh 表格列與 deploy 技能段落改寫成同一套說法。

Why：文件還寫著版本不符就跳過該 domain。操作者依文件預期那個 domain 不會動，實際上它已經更新，回報也對不上腳本印出來的行。

How：SKILL.md 逐一寫出 0、1、4、2 或其他四種結束碼各自的處置與理由，完成條件改成 skip 要有檢查腳本出錯或本地樹的原因、warn 要指名還缺哪一版。README 兩處改寫成同樣的四種分流，並寫明真正的阻擋在 version-guard.sh。

Who：相依版本不符的處置。

chore(plugin): 版號升到 0.2.6 99e0554995

What：plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份 manifest 的 version 從 0.2.5 改成 0.2.6。

Why：這一輪改了相依檢查的結束碼與部署時的處置，外部行為跟 0.2.5 不同。三份 manifest 是版本檢查與部署推薦的依據，版號不動，version-guard.sh 就看不出這台機器該更新。

How：三份檔案只改 version 一個欄位，其餘內容不動，三份保持同一個版號。

Who：版號發布。

jiantw83 referenced this pull request

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

收攏技能行為清單與相依版本阻擋改動 #45

jiantw83 added a new dependency 2026-08-31 05:37:11 +00:00

#45 收攏技能行為清單與相依版本阻擋改動

jiantw83 merged commit b5d72f5245 into feat/skill-behaviors-and-version-block/main

2026-08-31 08:09:20 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Blocks

#45 收攏技能行為清單與相依版本阻擋改動

plugins/cli

Reference: plugins/cli#44