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

2026-08-31T05:37:03Z

jiantw83 commented

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

摘要

需求描述：本 PR 是功能主幹的收攏層。子功能 PR 先併入 feat/skill-behaviors-and-version-block/main，再由本 PR 一次併回 develop。本輪功能涵蓋兩件事：新增 references/behaviors.md 當作技能驗證的行為基準、把相依版本不符的阻擋從部署層移到技能叫用層。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

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

設計重點

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

測試結果

本 PR 不含自身提交，測試結果以子功能 PR plugins/cli#44 為準。該 PR 已跑 bash -n、lint-scripts.sh、check-behaviors.sh、ste100-lint.sh，全數結束碼 0。

前置 Push Request

plugins/cli#44：#44

## 摘要 - 需求描述：本 PR 是功能主幹的收攏層。子功能 PR 先併入 `feat/skill-behaviors-and-version-block/main`，再由本 PR 一次併回 `develop`。本輪功能涵蓋兩件事：新增 `references/behaviors.md` 當作技能驗證的行為基準、把相依版本不符的阻擋從部署層移到技能叫用層。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | 由子功能 PR 帶入 | 本 PR 自身不提交檔案。內容來自 plugins/cli#44，該 PR 併入功能主幹後才會出現在這裡 | ## 設計重點 - 走完整階梯。子功能分支先併入功能主幹，功能主幹再併回 `develop`，中間不跳級。 - 功能主幹集中審查。同一輪功能的多條子功能分支併攏後，`develop` 只收一次。 ## 測試結果 - 本 PR 不含自身提交，測試結果以子功能 PR plugins/cli#44 為準。該 PR 已跑 `bash -n`、`lint-scripts.sh`、`check-behaviors.sh`、`ste100-lint.sh`，全數結束碼 0。 ## 前置 Push Request - plugins/cli#44：https://gitea.jsc.idv.tw/plugins/cli/pulls/44

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

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

jiantw83 added 6 commits 2026-08-31 08:09:20 +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：版號發布。

Merge pull request '相依版本不符改為照樣更新並提醒、新增技能行為清單' (#44 ) from feat/skill-behaviors-and-version-block/deploy-requires-warn into feat/skill-behaviors-and-version-block/main b5d72f5245

jiantw83 merged commit 7d58afa2ee into develop

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Depends on

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

plugins/cli

Reference: plugins/cli#45