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

feat(meta): 新增 SKILLSET 頁型與部署後重啟閘門準則，稽核加流程檢查四項 #26

Merged
admin merged 5 commits from feat/skillset-governance/main into develop 2026-08-27 08:54:50 +00:00
Conversation 0 Commits 5 Files Changed 9
+91 -10
jiantw83 commented 2026-08-27 08:52:28 +00:00
Member
Copy Link
Copy Source

PR 描述

摘要

  • 需求描述：使用者提出的 15 條工作規則中，群三（技能組治理）的四條落在本存取庫。R12 要求 marketplace 同步列為稽核的必經步驟、R13 要求新增 SKILLSET 技能組異動報告頁型並由四支異動技能收尾寫入、R14 要求稽核清單加上流程檢查四項、R15 要求部署後強制重啟（本存取庫負責寫下準則與豁免清單）。決策紀錄在 wiki knowledges/QUESTION 的 QUESTION_FB8DF0B5（2026-08-27 兩節共 12 題）。本 PR 是主幹 feat/skillset-governance/main 併回 develop 的釋出 PR，內容為已合併的子功能 PR #25。
  • 計畫名稱：無
  • 計畫頁：無
  • 分析頁：無

變更內容

檔案 為什麼改
references/guidelines.md 環境變數表補 JSC_WIKI_REPO_SKILLSET 與 JSC_RESTART_GATE；新增「部署後重啟閘門」一節，含狀態檔、清除時機、判定位置、逃生門與九支豁免的逐項理由；Wiki 頁命名總表補 SKILLSET 一列與雜湊來源、頁內累積的約定；審核檢查清單新增流程檢查四項
skills/skill-check/SKILL.md 第 2 步的稽核要逐項涵蓋流程檢查四項、逐條列名；新增第 5 步 marketplace 同步為必經步驟並分流四個退出碼；原第 5、6 步順延為 6、7
skills/skill-new/SKILL.md、skills/skill-update/SKILL.md、skills/skill-delete/SKILL.md、skills/skillset-update/SKILL.md 四支異動技能各新增收尾一步：套用到目前工作階段、具體驗證功能、把異動報告附加寫進 SKILLSET_{HASH}。description 同步
plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份 manifest 同步升版至 0.1.4

設計重點

  • 四支異動技能的收尾原本會卡死，已改成兩條路徑。 這是實作期間攔下的第一個實質問題，也是本批最重要的修正。R13 的收尾要求跑 jsc-cli:deploy 讓 CLI 載入新版，但 marketplace 與 version-guard.sh 都讀存取庫的預設分支 master，PR 停在 develop 時 deploy 看不到任何東西，完成條件「claude plugin list 印出三份 manifest 現在帶的版本」永遠達不到——技能會一直卡在最後一步。現在分兩條：
    • PR 已合併到 master：呼叫 jsc-cli:deploy 更新模式，依提示重啟；有 CLI 更新不了就記下哪些 CLI 確實載入了新版並改用其中一支，一支都沒有就停下並回報這次異動未驗證。
    • PR 還沒到 master（等審核，或只併進 develop）：部署沒有意義、完成條件不可達，改對工作樹驗證，報告標記「工作樹驗證、尚未部署」，並明講還有哪一支釋出 PR 要合併，改動才會到得了任何 CLI。
  • 這個卡死正是同批新增的流程檢查第 4 項該抓的。 「技能自己裝的閘門不會擋掉解除那道閘門的唯一路徑（閘門不自鎖）」——收尾要求部署，而部署在那個時點不可能成功，就是自鎖。四項流程檢查裡有兩項直接寫了踩過的實例（規則搬到 references/ 後指標指向空處、工作包閘門若擋掉 implement 則結清 PR 沒有路徑），讓清單帶著證據，而不是只有一句原則。
  • 流程檢查四項是給稽核用的，所以要在稽核步驟裡逐條列名。 只寫進清單、不寫進 skill-check 第 2 步，sub agent 稽核時很容易只掃命名與語言那幾項就交差。第 2 步現在把四項逐條列出，完成條件也改成「每個 domain 的稽核結果對所有清單項目都給出判定，含四項流程檢查」。
  • 驗證要具體到能失敗。 收尾第 2 小步規定跑 tools/list-skills.sh 看到 {domain}<TAB>{name} 那一列、用真實參數跑過技能新增的每一支工具並比對退出碼與文件所寫的意義、實際叫一次 /jsc-{domain}:{name} 確認 CLI 載入 SKILL.md 內文而不是回報未知指令。任一項對不上就修因並從第 1 小步重跑。
  • 報告寫不進去不算收尾完成。 寫 SKILLSET_{HASH} 這一部分必須以 sub agent 執行；寫入失敗（解不出 {owner}/{repo}、jsc-gitea:wiki 回 API 錯誤）時把頁名與未寫入的內容交回使用者並讓這一步保持未完成，絕不在報告沒寫成的情況下收掉流程。
  • 異動報告頁內累積，不覆蓋。 每次異動附加一節（日期、異動類型、技能名、改動檔案、PR 連結、逐項驗證結果），舊紀錄全部保留。要看一支技能改過幾次，就在同一頁上翻。
  • marketplace 同步是必經步驟，不是選項。 正本在 plugins/meta，每個 domain 存取庫各帶一份位元組完全相同的副本；修好技能卻讓副本分岔，某些存取庫註冊到的就是過期的技能組清單。第 5 步規定拿現有條目自己的當前值跑一次 tools/sync-marketplace.sh（重寫同一條目是幂等的），四個退出碼各有分流，完成條件是腳本回 0 並印出動到的路徑——0 本身就代表腳本自己驗過每份副本位元組一致。
  • 豁免清單九支，且清單認的是技能名、不是呼叫鏈。 準則裡把這件事寫成獨立段落：豁免技能轉呼叫的下一層若不在清單上，那一層照樣被擋。後三支（jsc-ask:ask、jsc-git:pr、jsc-git:commit）自己不是收尾規則的主體，是為了讓前六支走得完才補進來的，並註明 version-guard.sh 的豁免清單當年也是為同一個原因收進 jsc-ask:ask。新增豁免技能時要一併想它會呼叫誰。

測試結果

  • tools/ste100-lint.sh 掃本存取庫全綠；六個 domain 存取庫（review、sdlc、hooks、gitea、cli、meta）逐一掃過也全綠。
  • 三份 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）版本一致，皆為 0.1.4；另五個 domain 存取庫的三份 manifest 也各自一致。
  • jsc-gitea 那批的 gitea.sh wiki-repo SKILLSET 四種情境（專用變數優先、退回共用變數、兩者都設時專用值優先、兩者都未設 exit 3）與 check-wiki-rules.sh 全綠，本存取庫的 SKILLSET_{HASH} 落地路徑依賴這一項。
  • jsc-hooks 那批的重啟閘門實測（擋下、九支豁免全部放行、逃生門 JSC_RESTART_GATE=off、新工作階段清除）與 wire-cli.sh smoke claude 回 status=ok、14 項判定路徑符合預期，對得上本存取庫準則裡寫的判定與豁免。
  • jsc-cli 那批的 config-spec.tsv 欄位數一致、scan-config.sh orphans 零回報，含準則新增的 JSC_WIKI_REPO_SKILLSET 與 JSC_RESTART_GATE 兩個變數。
  • 未測試項目：四支異動技能的收尾未走過已合併到 master 的那條路徑。本批自己就處在「PR 還沒到 master」的狀態，所以驗到的是工作樹那條路徑；jsc-cli:deploy 更新模式加重啟、再由 claude plugin list 比對版本這條完整鏈路，要等本批釋出 PR 合併到 master 之後才驗得到。另外真實 Gitea 站台上實際附加寫入 SKILLSET_{HASH} 並回讀的端到端流程沒跑過。

前置 Push Request

  • 無未結清的前置 PR。本存取庫的 SKILLSET_{HASH} 報告要靠 jsc-gitea 的 SKILLSET 允許清單（tools/gitea.sh 的 resolve_wiki_repo）才寫得進去，那項已隨子功能 PR plugins/gitea#25 合併進 gitea 的主幹 feat/skillset-governance/main；準則裡寫的重啟閘門判定與豁免清單對應 plugins/hooks#33，也已合併進 hooks 的主幹。跨存取庫依賴在主幹層都已結清。合併順序上建議 gitea、hooks、cli 三支釋出 PR 先進 develop，本 PR 最後進，因為本存取庫的準則描述的是那三支的行為。
# PR 描述 ## 摘要 - 需求描述：使用者提出的 15 條工作規則中，群三（技能組治理）的四條落在本存取庫。R12 要求 marketplace 同步列為稽核的必經步驟、R13 要求新增 `SKILLSET` 技能組異動報告頁型並由四支異動技能收尾寫入、R14 要求稽核清單加上流程檢查四項、R15 要求部署後強制重啟（本存取庫負責寫下準則與豁免清單）。決策紀錄在 wiki `knowledges/QUESTION` 的 `QUESTION_FB8DF0B5`（2026-08-27 兩節共 12 題）。本 PR 是主幹 `feat/skillset-governance/main` 併回 `develop` 的釋出 PR，內容為已合併的子功能 PR #25。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `references/guidelines.md` | 環境變數表補 `JSC_WIKI_REPO_SKILLSET` 與 `JSC_RESTART_GATE`；新增「部署後重啟閘門」一節，含狀態檔、清除時機、判定位置、逃生門與九支豁免的逐項理由；Wiki 頁命名總表補 `SKILLSET` 一列與雜湊來源、頁內累積的約定；審核檢查清單新增流程檢查四項 | | `skills/skill-check/SKILL.md` | 第 2 步的稽核要逐項涵蓋流程檢查四項、逐條列名；新增第 5 步 marketplace 同步為必經步驟並分流四個退出碼；原第 5、6 步順延為 6、7 | | `skills/skill-new/SKILL.md`、`skills/skill-update/SKILL.md`、`skills/skill-delete/SKILL.md`、`skills/skillset-update/SKILL.md` | 四支異動技能各新增收尾一步：套用到目前工作階段、具體驗證功能、把異動報告附加寫進 `SKILLSET_{HASH}`。description 同步 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 三份 manifest 同步升版至 0.1.4 | ## 設計重點 - **四支異動技能的收尾原本會卡死，已改成兩條路徑。** 這是實作期間攔下的第一個實質問題，也是本批最重要的修正。R13 的收尾要求跑 `jsc-cli:deploy` 讓 CLI 載入新版，但 marketplace 與 `version-guard.sh` 都讀存取庫的**預設分支** `master`，PR 停在 `develop` 時 `deploy` 看不到任何東西，完成條件「`claude plugin list` 印出三份 manifest 現在帶的版本」永遠達不到——技能會一直卡在最後一步。現在分兩條： - PR 已合併到 `master`：呼叫 `jsc-cli:deploy` 更新模式，依提示重啟；有 CLI 更新不了就記下哪些 CLI 確實載入了新版並改用其中一支，一支都沒有就停下並回報這次異動未驗證。 - PR 還沒到 `master`（等審核，或只併進 `develop`）：部署沒有意義、完成條件不可達，改對**工作樹**驗證，報告標記「工作樹驗證、尚未部署」，並明講還有哪一支釋出 PR 要合併，改動才會到得了任何 CLI。 - **這個卡死正是同批新增的流程檢查第 4 項該抓的。** 「技能自己裝的閘門不會擋掉解除那道閘門的唯一路徑（閘門不自鎖）」——收尾要求部署，而部署在那個時點不可能成功，就是自鎖。四項流程檢查裡有兩項直接寫了踩過的實例（規則搬到 `references/` 後指標指向空處、工作包閘門若擋掉 `implement` 則結清 PR 沒有路徑），讓清單帶著證據，而不是只有一句原則。 - **流程檢查四項是給稽核用的，所以要在稽核步驟裡逐條列名。** 只寫進清單、不寫進 `skill-check` 第 2 步，sub agent 稽核時很容易只掃命名與語言那幾項就交差。第 2 步現在把四項逐條列出，完成條件也改成「每個 domain 的稽核結果對所有清單項目都給出判定，含四項流程檢查」。 - **驗證要具體到能失敗。** 收尾第 2 小步規定跑 `tools/list-skills.sh` 看到 `{domain}<TAB>{name}` 那一列、用真實參數跑過技能新增的每一支工具並比對退出碼與文件所寫的意義、實際叫一次 `/jsc-{domain}:{name}` 確認 CLI 載入 SKILL.md 內文而不是回報未知指令。任一項對不上就修因並從第 1 小步重跑。 - **報告寫不進去不算收尾完成。** 寫 `SKILLSET_{HASH}` 這一部分必須以 sub agent 執行；寫入失敗（解不出 `{owner}/{repo}`、`jsc-gitea:wiki` 回 API 錯誤）時把頁名與未寫入的內容交回使用者並讓這一步保持未完成，絕不在報告沒寫成的情況下收掉流程。 - **異動報告頁內累積，不覆蓋。** 每次異動附加一節（日期、異動類型、技能名、改動檔案、PR 連結、逐項驗證結果），舊紀錄全部保留。要看一支技能改過幾次，就在同一頁上翻。 - **marketplace 同步是必經步驟，不是選項。** 正本在 `plugins/meta`，每個 domain 存取庫各帶一份位元組完全相同的副本；修好技能卻讓副本分岔，某些存取庫註冊到的就是過期的技能組清單。第 5 步規定拿現有條目自己的當前值跑一次 `tools/sync-marketplace.sh`（重寫同一條目是幂等的），四個退出碼各有分流，完成條件是腳本回 `0` 並印出動到的路徑——`0` 本身就代表腳本自己驗過每份副本位元組一致。 - **豁免清單九支，且清單認的是技能名、不是呼叫鏈。** 準則裡把這件事寫成獨立段落：豁免技能轉呼叫的下一層若不在清單上，那一層照樣被擋。後三支（`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`）自己不是收尾規則的主體，是為了讓前六支走得完才補進來的，並註明 `version-guard.sh` 的豁免清單當年也是為同一個原因收進 `jsc-ask:ask`。新增豁免技能時要一併想它會呼叫誰。 ## 測試結果 - `tools/ste100-lint.sh` 掃本存取庫全綠；六個 domain 存取庫（review、sdlc、hooks、gitea、cli、meta）逐一掃過也全綠。 - 三份 manifest（`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`）版本一致，皆為 0.1.4；另五個 domain 存取庫的三份 manifest 也各自一致。 - `jsc-gitea` 那批的 `gitea.sh wiki-repo SKILLSET` 四種情境（專用變數優先、退回共用變數、兩者都設時專用值優先、兩者都未設 exit 3）與 `check-wiki-rules.sh` 全綠，本存取庫的 `SKILLSET_{HASH}` 落地路徑依賴這一項。 - `jsc-hooks` 那批的重啟閘門實測（擋下、九支豁免全部放行、逃生門 `JSC_RESTART_GATE=off`、新工作階段清除）與 `wire-cli.sh smoke claude` 回 `status=ok`、14 項判定路徑符合預期，對得上本存取庫準則裡寫的判定與豁免。 - `jsc-cli` 那批的 `config-spec.tsv` 欄位數一致、`scan-config.sh orphans` 零回報，含準則新增的 `JSC_WIKI_REPO_SKILLSET` 與 `JSC_RESTART_GATE` 兩個變數。 - 未測試項目：四支異動技能的收尾**未走過已合併到 `master` 的那條路徑**。本批自己就處在「PR 還沒到 `master`」的狀態，所以驗到的是工作樹那條路徑；`jsc-cli:deploy` 更新模式加重啟、再由 `claude plugin list` 比對版本這條完整鏈路，要等本批釋出 PR 合併到 `master` 之後才驗得到。另外真實 Gitea 站台上實際附加寫入 `SKILLSET_{HASH}` 並回讀的端到端流程沒跑過。 ## 前置 Push Request - 無未結清的前置 PR。本存取庫的 `SKILLSET_{HASH}` 報告要靠 `jsc-gitea` 的 `SKILLSET` 允許清單（`tools/gitea.sh` 的 `resolve_wiki_repo`）才寫得進去，那項已隨子功能 PR `plugins/gitea#25` 合併進 gitea 的主幹 `feat/skillset-governance/main`；準則裡寫的重啟閘門判定與豁免清單對應 `plugins/hooks#33`，也已合併進 hooks 的主幹。跨存取庫依賴在主幹層都已結清。合併順序上建議 gitea、hooks、cli 三支釋出 PR 先進 `develop`，本 PR 最後進，因為本存取庫的準則描述的是那三支的行為。
jiantw83 added 5 commits 2026-08-27 08:52:28 +00:00
docs(guidelines): 準則新增 SKILLSET 頁型、部署後重啟閘門與流程檢查四項 6447416c7b 
What：`references/guidelines.md` 四處增修。環境變數表新增 `JSC_WIKI_REPO_SKILLSET` 與 `JSC_RESTART_GATE` 兩列；wiki 頁命名總表新增 `SKILLSET` 一列，並補上雜湊來源為被改動的 domain 存取庫 `{owner}/{repo}`、頁內累積歷次異動兩段說明；新增「部署後重啟閘門」一節，用表寫下狀態檔、清除時機、判定位置與逃生門，另附九支豁免技能的表與「清單認的是技能名，不是呼叫鏈」一段；審核檢查清單末尾新增流程檢查四項。

Why：這批規則要落到四個 domain 的腳本與技能裡，準則是它們的唯一真實來源。規則只留在各自的實作裡，改一邊忘一邊，稽核就沒有對照標準。三件事各有各的理由：`SKILLSET` 頁型讓技能組每次異動留下查得到的驗證紀錄；重啟閘門補上「部署換掉的是磁碟上的技能檔，工作階段載入的還是舊版」這段落差；流程檢查四項把過去踩過的坑寫成逐項確認得出來的項目。

How：閘門那一節刻意把每一支的「為什麼不能擋」逐支寫出來，不只列技能名——豁免清單日後要增刪，理由沒寫下來就得重新想一次。九支的理由收斂成同一件事：部署後還要寫得完技能組異動報告與工作日誌，整批擋下去「先重啟」與「先寫完報告」會互相打死，通則另外寫進流程檢查第 4 項「閘門不自鎖」。「清單認技能名不認呼叫鏈」單獨寫一段，因為後三支（`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`）自己不是收尾規則的主體，是為了讓前六支走得完才補進來的，日後增豁免時要一併想它會呼叫誰。流程檢查其中兩項附上踩過的實例，抽象敘述判不出來的，看實例就判得出來。

Who：`jsc-meta` 的技能準則，以及依準則稽核的 `skill-check` 與四支技能組異動技能。
feat(skill-check): 稽核加入 marketplace 同步必經步驟與流程檢查四項 9a0ea8e248 
What：`skills/skill-check/SKILL.md` 兩處增修。第 2 步的稽核範圍明寫要逐項涵蓋準則的流程檢查四項，四項各列一條，完成條件改成「每個 domain 的稽核結果對所有清單項目都有結論，含這四項」；新增第 5 步「同步 marketplace 正本」，四個結束碼各自寫明怎麼處理，原本的複查與開 PR 順延為第 6、7 步。

Why：`sync-marketplace.sh` 原本沒有出現在任何技能流程裡，跑不跑全憑人記得。正本在 `plugins/meta`，每個 domain 存取庫各留一份位元組完全相同的副本，稽核改完不同步，就會有存取庫註冊到過期的 plugin 清單。流程檢查四項同理：準則加了項目，稽核不點名就沒有人會查，四項等於沒加。

How：同步列為必經步驟，不是選項。呼叫時拿既有項目自己現在的值重寫一次，重寫同一筆是冪等的，所以不必先判斷哪一筆該改。四個結束碼逐一分流：3 是寫好了但有 domain 沒 clone 到本機，先跑 `sync-domains.sh` 再重跑；2 是參數個數不對；1 是缺 python3、正本讀不到或副本位元組不一致；0 才代表每份副本完全相同，而且是腳本自己驗過的。

Who：`jsc-meta:skill-check` 的例行合規稽核流程。
feat(skillset-report): 四支異動技能收尾套用到工作階段、驗證並寫異動報告 478f670d53 
What：`skill-new`、`skill-update`、`skill-delete`、`skillset-update` 四支各新增一個收尾步驟，內含三個子步驟：把改動套用到目前工作階段、逐項驗證功能真的動得起來、把驗證結果附加到 wiki 的 `SKILLSET_{HASH}`。四支的 `description` 同步補上這段收尾。

Why：原本四支都以「開了 PR」作為收尾。PR 開完技能還沒進到任何 CLI，改動到底動不動得起來沒人驗過，壞了要等下一次有人踩到才知道。技能組的異動紀錄也一樣沒有落腳處：同一支技能改過幾次、每次改了什麼，只能翻 git 紀錄。

How：套用那一步分兩條路徑，依改動走到哪裡決定。PR 已經合併到 `master` 才走 `jsc-cli:deploy` 更新模式，並依提示重新啟動；PR 還停在 `develop` 或還在等審核，就改用工作樹驗證，報告標成「工作樹驗證、尚未部署」，並點名還沒合併的發佈 PR。分兩條路徑的理由是完成條件達不到：marketplace 與 `version-guard.sh` 都讀存取庫的預設分支，停在 `develop` 的改動 `deploy` 一定看不到，硬跑就卡在永遠達不到的完成條件上。驗證那一步要求逐項比對結束碼與實際輸出，不接受「跑完沒報錯」；對不上就回到套用那一步重跑，不往下走。報告一律附加一節、不覆蓋舊節，要看一支技能改過幾次就在同一頁上翻；寫不進去就把頁名與未寫入的內容交回使用者，這一步留著不結案。

Who：`jsc-meta` 的四支技能組異動技能，以及日後查技能組異動紀錄的人。
chore(manifest): 三份 manifest 版本升到 0.1.4 816fe07fbd 
What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 的 `version` 由 0.1.3 改為 0.1.4。

Why：本次準則新增 `SKILLSET` 頁型、部署後重啟閘門與流程檢查四項，`skill-check` 多了 marketplace 同步必經步驟，四支異動技能也多了收尾步驟，屬於行為變更，版本要跟著往上走，各 CLI 才知道要更新。

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

Who：`jsc-meta` 外掛的套件描述檔。
Merge pull request 'feat(meta): 新增 SKILLSET 頁型與稽核流程檢查，四支異動技能收尾寫異動報告' (#25) from feat/skillset-governance/page-type-and-process-audit into feat/skillset-governance/main 0ce64ba392 
Reviewed-on: #25
admin merged commit a65f546911 into develop 2026-08-27 08:54:50 +00:00
admin deleted branch feat/skillset-governance/main 2026-08-27 08:54:50 +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#26