新增行為清單檢查腳本，改寫相依版本準則並更新 5 支技能 #47

2026-08-31T05:38:36Z

jiantw83 commented

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

摘要

需求描述：盤點所有技能組，替每支技能整理一份行為清單，當作技能驗證的參考基準，日後技能異動要同步更新；相依技能版本不符時不得跳過更新，改為阻擋執行。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`tools/check-behaviors.sh`	新增。行為清單靠眼睛比對會漏，也擋不住漂移。這支程式比對 `references/behaviors.md` 與 `skills/`，查標題、節對技能、節序、表格、五個欄位與內容欄非空，退出碼 0 相符、1 不符、2 用法錯誤、3 找不到清單或技能。
`references/behaviors.md`	新增。記下 jsc-meta 七支技能的實際行為，一支一節，五列寫觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象，當作稽核與驗證的比對基準。
`references/guidelines.md`	四處。「Manifest 相依版本」第 5 條改成部署端照樣更新、只回報缺版，阻擋交給 version-guard；「版本前置檢查」補上相依版本落後、相等或超前、查不到相依資訊三列，並寫明由 version-guard 自己實作；新增「技能行為清單」一節，訂下格式合約與退出碼分流；審核檢查清單加上 `check-behaviors.sh` 退出 0 這一項。
`skills/skill-new/SKILL.md`	新增技能時要一併插入 `references/behaviors.md` 的節，依字典序擺位，五列填滿；自查改用 `check-behaviors.sh`，逐個退出碼分流。
`skills/skill-update/SKILL.md`	改技能行為時同一趟改寫該技能那一節，改名連節名與位置一起搬；檢查清單那一項改跑 `check-behaviors.sh`，不用眼睛比。
`skills/skill-delete/SKILL.md`	刪技能時連同該技能那一節整節移除，刪完跑 `check-behaviors.sh` 確認剩下的節對得上剩下的技能。
`skills/skillset-update/SKILL.md`	每個 domain 的 sub agent 在自己那個存取庫同一趟更新行為清單，檢查清單那一項各自跑 `check-behaviors.sh`，退出 0 才算過。
`skills/skill-check/SKILL.md`	`check-behaviors.sh` 併進第一組稽核，逐 domain 平行跑；第二組要跳過的既決項目從三項變四項，合併與重驗的完成條件跟著改。
`README.md`	檔案總表補上 `references/behaviors.md` 與 `tools/check-behaviors.sh` 兩列；`skill-check` 段落改寫成第一組跑三支腳本。
`plugin.json`	版本提升到 0.2.4。
`.claude-plugin/plugin.json`	版本同步到 0.2.4。
`.codex-plugin/plugin.json`	版本同步到 0.2.4。

設計重點

行為清單是技能驗證的參考基準。清單寫技能實際做的事，不抄 description 的行銷語；稽核與驗證拿它比對，技能異動就在同一個 PR 內更新那一節。一個 domain 一份，技能與清單才進得了同一條 PR，跨存取庫沒有原子性，拆兩邊只會自己造出漂移。
check-behaviors.sh 把六項判定交給程式：標題與無 BOM、節對技能不多不少、節序照字典序、每節恰好一張表、五個欄位依序齊全、每一列內容欄非空。退出碼分流是 0 相符、1 不符（逐項印在 stderr）、2 用法錯誤、3 找不到清單或技能。退出 3 是「什麼都沒查」，一律不算通過。
domain 名以 plugin.json 的 name 為準，讀不到才退回 checkout 目錄名。目錄名是誰 clone 誰決定的，同一個存取庫換一台機器就可能叫別的名字，拿它當唯一來源會在別人的工作區誤報一次標題不符。
相依版本阻擋從部署端移到 version-guard 呼叫當下。部署端跳過不符的 domain 會自鎖：它落後所以被跳過、被跳過所以永遠落後，更新跑幾次都一樣。要擋的是「拿舊版去跑」，不是「把舊版換成新版」，所以 deploy.sh update 照樣更新、只回報缺哪一版，阻擋改由 version-guard.sh 在技能被呼叫的當下執行。
version-guard 自己實作版本比對，不呼叫 jsc-cli/tools/check-requires.sh。hook 專屬存放於 jsc-hooks，而且 jsc-cli 已宣告相依 jsc-hooks，反過來呼叫會做出循環相依。兩支的比法要保持一致，改動任一支就回頭核對另一支。
兩道版本檢查共用同一份豁免清單，不另立一份。豁免理由完全一樣：那幾支是解除落後的唯一路徑，擋了就沒有東西能把版本補上來；分兩份只會兩邊漂移，改了一份忘了另一份，deploy 照樣被相依版本擋死。

測試結果

sh tools/check-behaviors.sh /root/plugins/meta → 退出碼 0，訊息「行為清單檢查通過：/root/plugins/meta/references/behaviors.md 對上 7 支技能，五個欄位齊全」
sh tools/lint-scripts.sh /root/plugins/meta → 退出碼 0，訊息「腳本檢查通過：12 支（語法、可執行、結束碼宣告），其中 0 支判定為函式庫」

前置 Push Request

無

## 摘要 - 需求描述：盤點所有技能組，替每支技能整理一份行為清單，當作技能驗證的參考基準，日後技能異動要同步更新；相依技能版本不符時不得跳過更新，改為阻擋執行。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/check-behaviors.sh` | 新增。行為清單靠眼睛比對會漏，也擋不住漂移。這支程式比對 `references/behaviors.md` 與 `skills/`，查標題、節對技能、節序、表格、五個欄位與內容欄非空，退出碼 0 相符、1 不符、2 用法錯誤、3 找不到清單或技能。 | | `references/behaviors.md` | 新增。記下 jsc-meta 七支技能的實際行為，一支一節，五列寫觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象，當作稽核與驗證的比對基準。 | | `references/guidelines.md` | 四處。「Manifest 相依版本」第 5 條改成部署端照樣更新、只回報缺版，阻擋交給 version-guard；「版本前置檢查」補上相依版本落後、相等或超前、查不到相依資訊三列，並寫明由 version-guard 自己實作；新增「技能行為清單」一節，訂下格式合約與退出碼分流；審核檢查清單加上 `check-behaviors.sh` 退出 0 這一項。 | | `skills/skill-new/SKILL.md` | 新增技能時要一併插入 `references/behaviors.md` 的節，依字典序擺位，五列填滿；自查改用 `check-behaviors.sh`，逐個退出碼分流。 | | `skills/skill-update/SKILL.md` | 改技能行為時同一趟改寫該技能那一節，改名連節名與位置一起搬；檢查清單那一項改跑 `check-behaviors.sh`，不用眼睛比。 | | `skills/skill-delete/SKILL.md` | 刪技能時連同該技能那一節整節移除，刪完跑 `check-behaviors.sh` 確認剩下的節對得上剩下的技能。 | | `skills/skillset-update/SKILL.md` | 每個 domain 的 sub agent 在自己那個存取庫同一趟更新行為清單，檢查清單那一項各自跑 `check-behaviors.sh`，退出 0 才算過。 | | `skills/skill-check/SKILL.md` | `check-behaviors.sh` 併進第一組稽核，逐 domain 平行跑；第二組要跳過的既決項目從三項變四項，合併與重驗的完成條件跟著改。 | | `README.md` | 檔案總表補上 `references/behaviors.md` 與 `tools/check-behaviors.sh` 兩列；`skill-check` 段落改寫成第一組跑三支腳本。 | | `plugin.json` | 版本提升到 0.2.4。 | | `.claude-plugin/plugin.json` | 版本同步到 0.2.4。 | | `.codex-plugin/plugin.json` | 版本同步到 0.2.4。 | ## 設計重點 - 行為清單是技能驗證的參考基準。清單寫技能實際做的事，不抄 `description` 的行銷語；稽核與驗證拿它比對，技能異動就在同一個 PR 內更新那一節。一個 domain 一份，技能與清單才進得了同一條 PR，跨存取庫沒有原子性，拆兩邊只會自己造出漂移。 - `check-behaviors.sh` 把六項判定交給程式：標題與無 BOM、節對技能不多不少、節序照字典序、每節恰好一張表、五個欄位依序齊全、每一列內容欄非空。退出碼分流是 0 相符、1 不符（逐項印在 stderr）、2 用法錯誤、3 找不到清單或技能。退出 3 是「什麼都沒查」，一律不算通過。 - domain 名以 `plugin.json` 的 `name` 為準，讀不到才退回 checkout 目錄名。目錄名是誰 clone 誰決定的，同一個存取庫換一台機器就可能叫別的名字，拿它當唯一來源會在別人的工作區誤報一次標題不符。 - 相依版本阻擋從部署端移到 version-guard 呼叫當下。部署端跳過不符的 domain 會自鎖：它落後所以被跳過、被跳過所以永遠落後，更新跑幾次都一樣。要擋的是「拿舊版去跑」，不是「把舊版換成新版」，所以 `deploy.sh update` 照樣更新、只回報缺哪一版，阻擋改由 `version-guard.sh` 在技能被呼叫的當下執行。 - version-guard 自己實作版本比對，不呼叫 `jsc-cli/tools/check-requires.sh`。hook 專屬存放於 `jsc-hooks`，而且 `jsc-cli` 已宣告相依 `jsc-hooks`，反過來呼叫會做出循環相依。兩支的比法要保持一致，改動任一支就回頭核對另一支。 - 兩道版本檢查共用同一份豁免清單，不另立一份。豁免理由完全一樣：那幾支是解除落後的唯一路徑，擋了就沒有東西能把版本補上來；分兩份只會兩邊漂移，改了一份忘了另一份，`deploy` 照樣被相依版本擋死。 ## 測試結果 - `sh tools/check-behaviors.sh /root/plugins/meta` → 退出碼 0，訊息「行為清單檢查通過：/root/plugins/meta/references/behaviors.md 對上 7 支技能，五個欄位齊全」 - `sh tools/lint-scripts.sh /root/plugins/meta` → 退出碼 0，訊息「腳本檢查通過：12 支（語法、可執行、結束碼宣告），其中 0 支判定為函式庫」 ## 前置 Push Request - 無

jiantw83 added 3 commits 2026-08-31 05:38:36 +00:00

feat(behaviors): 新增技能行為清單與檢查腳本 2e237b7674

What：新增 references/behaviors.md，一支技能一節，共七支技能。每節五列，記下觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象。新增 tools/check-behaviors.sh，比對 skills/ 與這份清單。skill-new、skill-update、skill-delete、skillset-update 加上同步更新清單的步驟。skill-check 把這支腳本併進第一組稽核。

Why：技能驗證原本沒有基準，稽核只能靠眼睛比對 SKILL.md。十個 domain 每輪都要重做一遍，還會漏掉。行為清單當基準，技能改了、清單沒跟著改，就是漂移。漂移交給程式判定才穩。

How：腳本檢查節數、節名、節序、每節一張表、五個欄位齊全、內容欄非空。退出碼 0 代表相符，1 代表不符，2 代表用法錯誤，3 代表找不到清單或找不到 skills 目錄。domain 名以 plugin.json 的 name 為準，checkout 目錄名只是退路。四支異動技能在同一個 PR 內改清單，並照退出碼分流。

Who：屬於「技能行為清單」這件需求，提供技能驗證的參考基準。

docs(guidelines): 改寫相依版本準則並補上技能行為清單合約 651dc19be9

What：「Manifest 相依版本」第 5 條改成部署端照樣更新，只在回報裡寫明缺哪一版。「版本前置檢查」補上相依版本檢查三列。新增「技能行為清單」一節，訂出位置、標題、節、表格、欄位與更新時機。審核檢查清單加上行為清單這一項。README 補上 behaviors.md 與 check-behaviors.sh 兩列，並把 skill-check 段落改成三組腳本。

Why：跳過更新會讓落後的 domain 永遠更新不到。它落後所以被跳過，被跳過所以永遠落後。相依版本不符要擋的是拿舊版去跑，不是把舊版換成新版。阻擋改到技能被呼叫的當下，才擋得住真正會出事的動作。行為清單要有一份格式合約，check-behaviors.sh 才有判定依據。

How：阻擋交給 jsc-hooks/hooks/version-guard.sh。版本比對由它自己實作，不呼叫 jsc-cli/tools/check-requires.sh。hook 專屬存放於 jsc-hooks，而且 jsc-cli 已宣告相依 jsc-hooks，反向呼叫會做出循環相依。兩道檢查共用同一份豁免清單。行為清單一個 domain 一份，放進該 domain 的 references/behaviors.md，技能改動與清單改動才進得了同一個 PR。

Who：涵蓋這次兩件需求的準則與說明文件，一件是相依版本不符改為阻擋執行，一件是技能行為清單。

chore(manifest): 同步三份 manifest 的版本到 0.2.4 f5f2cb05bd

What：plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 的 version 從 0.2.3 提升到 0.2.4。

Why：這次新增了行為清單與檢查腳本，也改了五支技能的內文。版本不提升，version-guard.sh 就比不出遠端已經有新版，部署端也拿不到更新提示。

How：三份 manifest 只改 version 一個欄位，三份的值保持一致，其餘欄位原樣保留。

Who：收尾這次技能行為清單與相依版本阻擋兩件需求，對應審核檢查清單的 manifest 同步項。

jiantw83 changed title from ~~feat/skill-behaviors-and-version-block/behavior-list-check-and-guidelines~~ to 新增行為清單檢查腳本，改寫相依版本準則並更新 5 支技能

2026-08-31 06:36:25 +00:00

jiantw83 referenced this pull request

2026-08-31 06:37:14 +00:00

收攏行為清單檢查腳本與準則改寫，功能主幹併回 develop #48

jiantw83 added a new dependency 2026-08-31 06:37:35 +00:00

#48 收攏行為清單檢查腳本與準則改寫，功能主幹併回 develop

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

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

Sign in to join this conversation.