plugins/meta
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(skillset): 技能組稽核修正與技能盤點頁型 #45

Merged
admin merged 4 commits from fix/skill-check-compliance-and-flow into develop 2026-08-31 03:54:02 +00:00
Conversation 0 Commits 4 Files Changed 26
+785 -177
jiantw83 commented 2026-08-31 03:49:55 +00:00
Member
Copy Link
Copy Source

摘要

  • 需求描述：例行技能組稽核的修正回合。修掉根目錄推導這個一定會錯的預設值，補齊腳本結束碼宣告與呼叫端分流，改正準則裡三處與實作不符的記載，解掉四支異動技能部署後自鎖的死結，新增技能盤點的 wiki 頁類型，並把流程併行化與合併步驟。技能組版本推進到 0.2.3。
  • 計畫名稱：無
  • 計畫頁：無
  • 分析頁：無

變更內容

檔案 為什麼改
tools/plugins-root.sh 新增。六支腳本原本各自取「腳本位置上兩層」當根目錄，以 plugin 形式安裝時會落在快取目錄，一定推錯。抽成共用推導，推不出來就指名要設 JSC_PLUGINS_ROOT 並列出試過的候選
tools/find-skill-refs.sh 改用共用推導取根目錄；結束碼說明補上「推導不出根目錄」與「建不了暫存檔」，並補環境變數欄
tools/inventory-tooling.sh 改用共用推導取根目錄；檔頭寫明同一趟已經跑過技能清單、CLI 偵測與 hook 接線查詢，呼叫端沿用即可
tools/list-skills.sh 改用共用推導取根目錄；結束碼說明納入推導失敗
tools/sync-domains.sh 改用共用推導取根目錄；結束碼一號的意思補上推導失敗與找不到 gitea.sh
tools/sync-marketplace.sh 改用共用推導取根目錄；結束碼一號補上推導失敗與暫存目錄建立失敗，並補環境變數欄
tools/verify-skill-removed.sh 改用共用推導取根目錄；補根目錄說明與環境變數欄，並重申結束碼三號不等於乾淨
tools/ste100-lint.sh 補結束碼宣告：沒給檢查對象要回二號。空跑會回零號，看起來像通過，會讓稽核誤判
tools/sync-skill-manifest.sh 補結束碼宣告與 set -e 的說明，呼叫端才有辦法逐碼分流，不把環境故障當同步成功
tools/lint-scripts.sh 新增。把散在技能說明裡的語法、執行權限、結束碼宣告三項檢查合成一支，避免每個 domain 各做一次又跟實況漂移；沒有腳本可掃回三號，明寫不等於通過
tools/deploy-route.sh 新增。四支異動技能各抄一段「改動有沒有進預設分支」的散文，四份會各自漂移，下放成同一支腳本；判不出來回一號，明寫不等於工作樹路線
references/deploy-verify.md 新增。四支異動技能的部署與驗證流程共用一份：判路線、部署或工作樹、在新的 CLI 行程裡驗證、失敗分流
templates/tooling-contents.md 新增。技能盤點目錄頁樣板。一列代表一組「機器、CLI、帳號」，只准更新自己那一列，禁止整頁覆蓋
templates/tooling-page.md 新增。技能盤點內容頁樣板。每次盤點覆寫整頁，只留現況；與目錄頁語意相反，所以分成兩份
skills/tooling-guide/SKILL.md 新增寫入技能盤點兩頁的步驟，整步規定必須開 sub agent；改用共用推導取根目錄；不再重跑 inventory-tooling.sh 內部已經跑過的三支腳本；步驟由十步併成六步；三處模糊描述改成查得出來的條件；被拿掉的獨立交叉檢查寫進 Notes
skills/skill-new/SKILL.md 技能清單與 domain 同步改為併行預跑；部署與驗證改指共用說明，驗證移到新的 CLI 行程；中文段落抽走、指標改英文；補 manifest 同步與根目錄推導的結束碼分流
skills/skill-update/SKILL.md 部署與驗證改指共用說明並改在新行程驗證；補結束碼分流；相對路徑指標修正
skills/skill-delete/SKILL.md 深層刪除檢查移到部署之後，部署前查一定乾淨、證明不了任何事；修檔的 sub agent 改為併行；補結束碼分流；中文段落抽走
skills/skillset-update/SKILL.md 同步存取庫與決策樹改為併行起跑；改檔、審核、寫報告的 sub agent 改為併行；部署與驗證改指共用說明；補結束碼分流
skills/skill-check/SKILL.md 腳本檢查改用 lint-scripts.sh；三組審查改為併行並在合併時去掉重複項；步驟由九步併成七步；hook 冒煙的行數改讀腳本自己印的那一行，不寫死數字；唯讀稽核帶唯讀旗標
skills/ste100-sync/SKILL.md 先只讀上游 frontmatter 的版本再決定要不要 clone，沒新版就不白 clone；全庫重掃改為併行；簡體字改動要同時落在 hook 的字表，不能只改 lint
references/guidelines.md 版本閘門豁免表補到七項、重啟閘門豁免表補到十項並與實作逐項對齊；維護類型改成只有目錄頁；新增技能盤點頁的類型、環境變數與雜湊規則；補唯讀旗標與「行數不得寫死」兩項檢查
README.md 檔案一覽補上新增的共用說明、兩份樣板與三支工具，並更新七支技能的敘述
plugin.json 版本推進到 0.2.3；補 jsc-hooks 相依下限、拉高 jsc-gitea 相依下限
.claude-plugin/plugin.json 同上，三份 manifest 版本與相依範圍必須一致
.codex-plugin/plugin.json 同上

設計重點

  • 根目錄推導只留一份。依序試環境變數、從目前目錄往上找、腳本位置上兩層、家目錄底下的 plugins，並以 gitea.sh 在不在當判準。marketplace 每個 domain 存取庫都帶一份，單看它會把 domain 誤判成根。
  • 推導保留逃生門。只 clone 單一存取庫的環境本來就沒有 jsc-gitea，這時硬擋會讓「請設環境變數」變成解不開的死路，所以環境變數有設且是目錄就照用，並在錯誤輸出提醒。
  • 部署後自鎖不靠豁免解。豁免只擋得住閘門，擋不住「行程還載著舊版」這個事實，硬過關驗到的是舊版行為。改成一律另開 CLI 行程驗證，新行程自己會清掉狀態檔，載到的也是新版。
  • 技能盤點的雜湊帶工具名稱。每支 CLI 各有自己的 plugin 集合與 hook 接線，少了那一段，同一台機器上五支 CLI 會算出同一個雜湊，互相覆蓋還看不出被蓋掉。
  • 兩份樣板分開。內容頁覆寫整頁、目錄頁只更新自己那一列，語意相反；合成一份遲早有人把別台機器的紀錄刪掉。
  • 準則表格寫明唯一真實來源。兩張豁免表各自指向對應的 hook 腳本檔頭，以後兩邊要一起改，才不會再漂移。
  • 拿掉保護要留下紀錄。技能盤點不再重跑那三支腳本，等於少了一次獨立交叉檢查，所以把少掉的是什麼、剩下哪兩件事擋住風險，明白寫進 Notes。
  • 「什麼都沒查」與「查過沒問題」一律分開。lint-scripts.sh 沒腳本可掃回三號、deploy-route.sh 判不出來回一號、ste100-lint.sh 沒給對象回二號，三支都在檔頭寫明不等於通過。
  • 函式庫豁免不靜默。lint-scripts.sh 每豁免一支就在錯誤輸出記一行，摘要也帶函式庫支數，看得出誰被跳過。

測試結果

實際跑過、結果如下：

  • bash -n 與 dash -n：tools/ 底下十一支腳本全部通過，包含三支新增腳本。
  • tools/lint-scripts.sh .：結束碼 0，印出「腳本檢查通過：11 支（語法、可執行、結束碼宣告），其中 0 支判定為函式庫」。
  • tools/ste100-lint.sh：對 README.md、references/guidelines.md、references/deploy-verify.md、兩份樣板與七支 SKILL.md 全掃，結束碼 0，無命中。
  • tools/plugins-root.sh：直接執行，結束碼 0，印出 /root/plugins，與預期的根目錄相同。
  • tools/deploy-route.sh .：結束碼 0，印出 route deploy 與 default-branch master。這是對提交前的分支 HEAD 判的，只證明腳本跑得動、欄位齊全，不代表本次改動已在預設分支上。
  • 提交訊息簡體字檢查：四則訊息逐字比對 jsc-hooks 的簡體字表（1006 字），零命中。

沒有執行、據實列出：

  • sync-domains.sh、sync-marketplace.sh、list-skills.sh、inventory-tooling.sh、find-skill-refs.sh、verify-skill-removed.sh、sync-skill-manifest.sh 都沒有實跑，這些需要連 Gitea 正本，或需要其他 domain 存取庫在本機。
  • hook 冒煙測試、jsc-cli:deploy、新行程的技能驗證，以及技能盤點兩頁的 wiki 實寫都沒有執行。共用部署驗證流程與技能盤點步驟目前只有文件與腳本層的檢查，端到端還沒跑過。
  • 其他 domain 存取庫的重掃與 manifest 同步沒有執行。本次改動只落在本存取庫。

前置 Push Request

  • 無
## 摘要 - 需求描述：例行技能組稽核的修正回合。修掉根目錄推導這個一定會錯的預設值，補齊腳本結束碼宣告與呼叫端分流，改正準則裡三處與實作不符的記載，解掉四支異動技能部署後自鎖的死結，新增技能盤點的 wiki 頁類型，並把流程併行化與合併步驟。技能組版本推進到 0.2.3。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/plugins-root.sh` | 新增。六支腳本原本各自取「腳本位置上兩層」當根目錄，以 plugin 形式安裝時會落在快取目錄，一定推錯。抽成共用推導，推不出來就指名要設 `JSC_PLUGINS_ROOT` 並列出試過的候選 | | `tools/find-skill-refs.sh` | 改用共用推導取根目錄；結束碼說明補上「推導不出根目錄」與「建不了暫存檔」，並補環境變數欄 | | `tools/inventory-tooling.sh` | 改用共用推導取根目錄；檔頭寫明同一趟已經跑過技能清單、CLI 偵測與 hook 接線查詢，呼叫端沿用即可 | | `tools/list-skills.sh` | 改用共用推導取根目錄；結束碼說明納入推導失敗 | | `tools/sync-domains.sh` | 改用共用推導取根目錄；結束碼一號的意思補上推導失敗與找不到 `gitea.sh` | | `tools/sync-marketplace.sh` | 改用共用推導取根目錄；結束碼一號補上推導失敗與暫存目錄建立失敗，並補環境變數欄 | | `tools/verify-skill-removed.sh` | 改用共用推導取根目錄；補根目錄說明與環境變數欄，並重申結束碼三號不等於乾淨 | | `tools/ste100-lint.sh` | 補結束碼宣告：沒給檢查對象要回二號。空跑會回零號，看起來像通過，會讓稽核誤判 | | `tools/sync-skill-manifest.sh` | 補結束碼宣告與 `set -e` 的說明，呼叫端才有辦法逐碼分流，不把環境故障當同步成功 | | `tools/lint-scripts.sh` | 新增。把散在技能說明裡的語法、執行權限、結束碼宣告三項檢查合成一支，避免每個 domain 各做一次又跟實況漂移；沒有腳本可掃回三號，明寫不等於通過 | | `tools/deploy-route.sh` | 新增。四支異動技能各抄一段「改動有沒有進預設分支」的散文，四份會各自漂移，下放成同一支腳本；判不出來回一號，明寫不等於工作樹路線 | | `references/deploy-verify.md` | 新增。四支異動技能的部署與驗證流程共用一份：判路線、部署或工作樹、在新的 CLI 行程裡驗證、失敗分流 | | `templates/tooling-contents.md` | 新增。技能盤點目錄頁樣板。一列代表一組「機器、CLI、帳號」，只准更新自己那一列，禁止整頁覆蓋 | | `templates/tooling-page.md` | 新增。技能盤點內容頁樣板。每次盤點覆寫整頁，只留現況；與目錄頁語意相反，所以分成兩份 | | `skills/tooling-guide/SKILL.md` | 新增寫入技能盤點兩頁的步驟，整步規定必須開 sub agent；改用共用推導取根目錄；不再重跑 `inventory-tooling.sh` 內部已經跑過的三支腳本；步驟由十步併成六步；三處模糊描述改成查得出來的條件；被拿掉的獨立交叉檢查寫進 Notes | | `skills/skill-new/SKILL.md` | 技能清單與 domain 同步改為併行預跑；部署與驗證改指共用說明，驗證移到新的 CLI 行程；中文段落抽走、指標改英文；補 manifest 同步與根目錄推導的結束碼分流 | | `skills/skill-update/SKILL.md` | 部署與驗證改指共用說明並改在新行程驗證；補結束碼分流；相對路徑指標修正 | | `skills/skill-delete/SKILL.md` | 深層刪除檢查移到部署之後，部署前查一定乾淨、證明不了任何事；修檔的 sub agent 改為併行；補結束碼分流；中文段落抽走 | | `skills/skillset-update/SKILL.md` | 同步存取庫與決策樹改為併行起跑；改檔、審核、寫報告的 sub agent 改為併行；部署與驗證改指共用說明；補結束碼分流 | | `skills/skill-check/SKILL.md` | 腳本檢查改用 `lint-scripts.sh`；三組審查改為併行並在合併時去掉重複項；步驟由九步併成七步；hook 冒煙的行數改讀腳本自己印的那一行，不寫死數字；唯讀稽核帶唯讀旗標 | | `skills/ste100-sync/SKILL.md` | 先只讀上游 frontmatter 的版本再決定要不要 clone，沒新版就不白 clone；全庫重掃改為併行；簡體字改動要同時落在 hook 的字表，不能只改 lint | | `references/guidelines.md` | 版本閘門豁免表補到七項、重啟閘門豁免表補到十項並與實作逐項對齊；維護類型改成只有目錄頁；新增技能盤點頁的類型、環境變數與雜湊規則；補唯讀旗標與「行數不得寫死」兩項檢查 | | `README.md` | 檔案一覽補上新增的共用說明、兩份樣板與三支工具，並更新七支技能的敘述 | | `plugin.json` | 版本推進到 0.2.3；補 `jsc-hooks` 相依下限、拉高 `jsc-gitea` 相依下限 | | `.claude-plugin/plugin.json` | 同上，三份 manifest 版本與相依範圍必須一致 | | `.codex-plugin/plugin.json` | 同上 | ## 設計重點 - 根目錄推導只留一份。依序試環境變數、從目前目錄往上找、腳本位置上兩層、家目錄底下的 plugins，並以 `gitea.sh` 在不在當判準。marketplace 每個 domain 存取庫都帶一份，單看它會把 domain 誤判成根。 - 推導保留逃生門。只 clone 單一存取庫的環境本來就沒有 `jsc-gitea`，這時硬擋會讓「請設環境變數」變成解不開的死路，所以環境變數有設且是目錄就照用，並在錯誤輸出提醒。 - 部署後自鎖不靠豁免解。豁免只擋得住閘門，擋不住「行程還載著舊版」這個事實，硬過關驗到的是舊版行為。改成一律另開 CLI 行程驗證，新行程自己會清掉狀態檔，載到的也是新版。 - 技能盤點的雜湊帶工具名稱。每支 CLI 各有自己的 plugin 集合與 hook 接線，少了那一段，同一台機器上五支 CLI 會算出同一個雜湊，互相覆蓋還看不出被蓋掉。 - 兩份樣板分開。內容頁覆寫整頁、目錄頁只更新自己那一列，語意相反；合成一份遲早有人把別台機器的紀錄刪掉。 - 準則表格寫明唯一真實來源。兩張豁免表各自指向對應的 hook 腳本檔頭，以後兩邊要一起改，才不會再漂移。 - 拿掉保護要留下紀錄。技能盤點不再重跑那三支腳本，等於少了一次獨立交叉檢查，所以把少掉的是什麼、剩下哪兩件事擋住風險，明白寫進 Notes。 - 「什麼都沒查」與「查過沒問題」一律分開。`lint-scripts.sh` 沒腳本可掃回三號、`deploy-route.sh` 判不出來回一號、`ste100-lint.sh` 沒給對象回二號，三支都在檔頭寫明不等於通過。 - 函式庫豁免不靜默。`lint-scripts.sh` 每豁免一支就在錯誤輸出記一行，摘要也帶函式庫支數，看得出誰被跳過。 ## 測試結果 實際跑過、結果如下： - `bash -n` 與 `dash -n`：`tools/` 底下十一支腳本全部通過，包含三支新增腳本。 - `tools/lint-scripts.sh .`：結束碼 0，印出「腳本檢查通過：11 支（語法、可執行、結束碼宣告），其中 0 支判定為函式庫」。 - `tools/ste100-lint.sh`：對 `README.md`、`references/guidelines.md`、`references/deploy-verify.md`、兩份樣板與七支 `SKILL.md` 全掃，結束碼 0，無命中。 - `tools/plugins-root.sh`：直接執行，結束碼 0，印出 `/root/plugins`，與預期的根目錄相同。 - `tools/deploy-route.sh .`：結束碼 0，印出 `route deploy` 與 `default-branch master`。這是對提交前的分支 HEAD 判的，只證明腳本跑得動、欄位齊全，不代表本次改動已在預設分支上。 - 提交訊息簡體字檢查：四則訊息逐字比對 `jsc-hooks` 的簡體字表（1006 字），零命中。 沒有執行、據實列出： - `sync-domains.sh`、`sync-marketplace.sh`、`list-skills.sh`、`inventory-tooling.sh`、`find-skill-refs.sh`、`verify-skill-removed.sh`、`sync-skill-manifest.sh` 都沒有實跑，這些需要連 Gitea 正本，或需要其他 domain 存取庫在本機。 - hook 冒煙測試、`jsc-cli:deploy`、新行程的技能驗證，以及技能盤點兩頁的 wiki 實寫都沒有執行。共用部署驗證流程與技能盤點步驟目前只有文件與腳本層的檢查，端到端還沒跑過。 - 其他 domain 存取庫的重掃與 manifest 同步沒有執行。本次改動只落在本存取庫。 ## 前置 Push Request - 無
jiantw83 added 4 commits 2026-08-31 03:49:56 +00:00
fix(tools): 改用共用推導取得技能組根目錄，並補齊結束碼宣告 7dc5c32de3 
以 plugin 形式安裝時，腳本會落在 CLI 的 plugin 快取目錄。
六支腳本原本一律取「腳本位置的上兩層」當技能組根目錄，這時一定推錯。
這一輪例行稽核的第一步就實際踩到：不先手動設環境變數，腳本根本跑不動，
而叫用它們的技能說明也沒提要設，等於留了一個必炸的預設值。

把推導規則抽成共用腳本，依序試環境變數、從目前目錄往上找、
腳本位置的上兩層、家目錄底下的 plugins，並以 gitea.sh 在不在當判準。
marketplace 每個 domain 存取庫都帶一份，單看它會把 domain 誤判成根。
推不出來就結束並指名要設環境變數，同時列出試過的每一個候選，
呼叫端一眼看得出要設什麼。只 clone 單一存取庫的環境留了逃生門：
環境變數有設且是目錄就照用，並在錯誤輸出提醒。

順手補上語言檢查與 manifest 同步兩支腳本的結束碼宣告與環境變數說明。
沒有宣告，呼叫端只能猜；猜錯就把失敗當成功。
feat(skills): 新增技能盤點頁與共用部署驗證流程，並把技能驗證移到新行程 5aa4a3da57 
技能盤點以前只回到對話裡，換一台機器就得重跑才知道裝了什麼。
現在新增技能盤點這個 wiki 頁類型，雜湊取「主機、工具名稱、登入帳號」三段。
每支 CLI 各有自己的 plugin 集合，也各有自己的 hook 接線，那是互相獨立的事實。
少了工具名稱那一段，同一台機器上五支 CLI 會算出同一個雜湊，五份盤點互相覆蓋，
讀的人還看不出被蓋掉。技能盤點新增寫入這兩頁的步驟，整步規定必須開 sub agent。
兩份樣板刻意分開：內容頁每次盤點覆寫整頁，目錄頁只更新自己那一列，
兩者的寫入語意剛好相反，合成一份遲早有人把別台機器的紀錄刪掉。

四支異動技能原本在部署完的同一個工作階段，就叫用剛做好的技能。
部署收尾自己立起重啟閘門，那支技能必被擋下，驗證做不完。
解法不是把它加進豁免清單。豁免擋得住閘門，擋不住「行程還載著舊版」這件事，
硬過關驗到的是舊版行為，等於假通過。所以把判路線、部署、驗證、失敗分流
抽成一份共用說明，驗證一律另開 CLI 行程執行，四支技能只留一行指標指過去。

新增腳本檢查工具，一次做完語法、執行權限與結束碼宣告三項檢查，
只被 source 的函式庫豁免後兩項，而且逐支記在錯誤輸出，不靜默略過。
新增部署路線判定工具，判定改動有沒有進存取庫的預設分支，
取代四支技能各抄一段、各自漂移的散文；判不出來就回報停下，不自己挑路線走。

同時把四支技能裡的中文段落抽到共用說明、指標改回英文，
修正六處相對路徑，把技能盤點的模糊描述改成查得出來的條件，
並讓 manifest 同步的每一個呼叫端逐碼分流。

七支技能改為併行執行：例行稽核從九步併成七步，技能盤點併成六步。
技能盤點不再重跑盤點腳本內部已經跑過的三支腳本，
而那三支原本兼作獨立交叉檢查，拿掉就少一層保護，
所以把少掉的是什麼、風險由誰擋住，明白寫進 Notes，不當作沒發生。
docs(guidelines): 修正版本閘門、重啟閘門與維護頁的準則記載 6d28e207c7 
版本前置檢查的豁免表只列了四項，重啟閘門的豁免表少了 hook 修復技能。
照著這兩張表設定，hook 壞掉時唯一的修復路徑會被自己擋住，修不好也繞不過。
兩張表逐項對齊三方實作與腳本現況，補成七項與十項，
並寫明各自的唯一真實來源是哪一支 hook 腳本，兩邊以後要一起改。

Wiki 頁命名總表原本替維護類型列了內容頁。
技能與樣板都沒有產生那一頁的步驟，照著總表找，只會找到一個不存在的頁。
改成只列目錄頁，並寫清楚維護登記全寫在目錄頁的表格裡；
要補內容頁就先補技能步驟與樣板，不能只在總表上寫著。

另外登記技能盤點頁的類型、環境變數與雜湊來源，說明為什麼雜湊要帶工具名稱，
補上唯讀稽核要帶唯讀旗標、行數一律讀腳本自己印的那一行兩項檢查，
並把新增的共用說明、兩份樣板與三支工具寫進 README 的檔案一覽。
chore(manifest): 同步三份 manifest 的版本與相依範圍 66b865456c 
這次異動用到 hook 的重啟閘門豁免清單，也用到 hook 那份簡體字表。
相依範圍沒跟著調，裝到舊版 hook 的機器會在部署之後被自己的閘門鎖住，
而且語言檢查與 hook 會各自認一份字表，判定不一致。

三份 manifest 一起把版本往上帶一號，補上 hook domain 的相依下限，
並拉高 gitea domain 的相依下限，讓版本前置檢查擋得住不相容的組合。
admin merged commit 29e9800da8 into develop 2026-08-31 03:54:02 +00:00
admin deleted branch fix/skill-check-compliance-and-flow 2026-08-31 03:54:02 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: plugins/meta#45