fix/skill-check-compliance-and-flow #21

2026-08-31T03:09:15Z

jiantw83 commented

2026-08-31 03:09:15 +00:00

摘要

需求描述：對本外掛做一次規範符合度與流程效率的檢查，並修好查到的問題。規範面補齊缺漏的失敗分支、修正指錯的步驟編號、補上腳本結束碼說明、補宣告缺少的外掛相依。效率面把重複的開啟中 PR 查詢收斂成一次、抽出型別優先序腳本當唯一真實來源、移除抄寫一份的階梯表，並解開並行化造成的循環相依。另外併入基底分支上剛進來的 PR 流程確認說明，並把 jsc-gitea 的相依下限往上提。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`tools/pick-type.sh`	新檔。把 commit 型別優先序從技能內文抽成腳本，成為該優先序的唯一真實來源。參數與標準輸入都收，commit 標題整行餵進來也認得出型別，並定義三個結束碼。
`tools/base-branch.sh`	標頭原本只用一行護欄帶過，看不出每個結束碼屬於哪個模式、也看不出該怎麼處置。改寫成逐碼說明，每個碼寫明模式、成因與下一步，讓技能有可以逐碼分支的依據。
`tools/slugify.sh`	同上，標頭補齊結束碼說明，並補上原本沒寫的參數不足這一碼。
`skills/commit/SKILL.md`	解開分組步驟的循環相依，改成只有註解掃描與盤點並行、分組排在盤點之後。開啟中 PR 的查詢改成依呼叫方決定要不要查，並補上查詢各種失敗的分支。另外寫明程式層閘門只在單一 CLI 生效，其餘 CLI 仍靠技能內文守規則。
`skills/pr/SKILL.md`	刪掉抄寫一份的階梯表，改指向規範文件的正本。呼叫方傳入的基底改在最前面先驗。型別改交給新腳本挑。整條呼叫鏈的開啟中 PR 查詢收斂成一次，建立 PR、編輯 PR、留言回覆與該次查詢都補上失敗分支，步驟編號的互相引用一併校正，流程由十一步收到九步。本次另外併入基底分支上剛進來的三處確認說明，接到重排後的步驟，並改寫成英文，詳見下一節。
`README.md`	同步技能說明，補上新腳本一列，並把重複的階梯表換成指向規範正本的說明。
`plugin.json`	補宣告本外掛對 `jsc-meta` 的相依，並遞增外掛版本。另把 `jsc-gitea` 的相依下限往上提一版。
`.claude-plugin/plugin.json`	同上，維持三份資訊清單一致。
`.codex-plugin/plugin.json`	同上，維持三份資訊清單一致。

設計重點

型別優先序只留一份。順序寫在新腳本裡，技能改成呼叫腳本，不再抄一份順序表。腳本每一項只取冒號、左括號、驚嘆號之前的字，所以 git log --format=%s 的輸出可以直接用管線餵進去。
階梯規則也只留一份。技能與 README 都改成指向規範文件的「PR 分支階梯」一節，推導仍由既有腳本負責，正本與實作各一份，不再有第三份抄本。
開啟中 PR 只查一次。原本認可與開 PR 兩支技能各自查一次，整條鏈重複查詢；現在改由開 PR 這一側查一次，把號碼、標題、基底與描述一起帶下去給後續比對，其餘位置一律不再查。原本認可完再回頭呼叫開 PR 的遞迴回呼也一併移除。
解開一個並行化造成的循環相依。分組原本被拉進並行區塊，但它要吃盤點的檔案清單；而盤點的完成條件又寫成要有分組結果，兩邊互相等待。改成只有註解掃描與盤點並行，分組接在盤點之後，掃描要求的修正仍在第一個 commit 之前完成。
呼叫方傳入的基底先驗。它合不合法只看遠端有沒有這條分支，與目標分支名稱無關，所以移到最前面驗，錯的輸入不必等到命名做完才被擋下。
失敗要有出口。建立 PR、編輯 PR、回覆留言與開啟中 PR 查詢都補上逐碼分支，重點是不把查詢失敗讀成「沒有開啟中的 PR」，避免在已有 PR 的分支上再開一個。留言回覆改成單一則失敗只記錄原因，不中斷整輪。
結束碼寫在腳本標頭。腳本自己宣告幾個碼，技能就分支幾個碼，兩邊對得起來。原本有一支宣告了多個碼、技能只分支其中三個，其餘落在沒人處理的縫隙裡。

併入基底分支上的確認說明

本分支已推送且 PR 開啟中，所以用 merge 併入基底分支，不改寫已推送的歷史，正在看 PR 的人對得上。

基底分支上剛進來的那一輪，在 skills/pr/SKILL.md 加了三處「這一步會先要求確認」。本分支同時把同一份文件從十一步重排成九步，兩邊在同一段衝突。解法是兩邊的改動都留：保留九步重排，並把那三處按它們原本掛的動作接到重排後的步驟，不照行號硬接。對應如下：

原本的步驟	動作	接到的新步驟
第 7 步	建立 PR，即 `pr-create`	第 7 步
第 9 步	更新 PR 標題與描述，即 `pr-edit`	第 8 步
第 9 步	掛上前置 PR 依賴，即 `pr-depend`	第 8 步

三處都改寫成英文，寫法一律是 Ask the user to confirm before this call runs.。理由是規範的「語言」一節明訂 SKILL.md 整份英文，只有要原樣輸出的繁體中文字面才例外；這三處是給執行者看的指示，不是要輸出的字面。本 PR 本身就在做語言合規修正，留著中文會自相矛盾。三處確認的行為完全沒變，只換了語言與掛載的步驟編號。

相依下限

skills/pr/SKILL.md 與 skills/commit/SKILL.md 都已改用 gitea.sh pr-of-branch，而這個子命令只有較新的 jsc-gitea 才有。三份資訊清單的 jsc-gitea 下限因此從 >=0.1.7 提到 >=0.1.8，裝到舊版的機器才不會跑到那一步失敗。同一輪的 jsc-meta 已經因為同樣理由提過下限，兩邊一致。三份清單只動這一個鍵的值，外掛自身版號沒有動。

測試結果

本次變更是 markdown 技能文件、shell 腳本與 JSON 資訊清單，專案沒有測試框架，所以沒有測試套件可跑。
實跑 bash -n tools/base-branch.sh tools/pick-type.sh tools/slugify.sh，三支腳本語法檢查全部通過。
實跑 tools/pick-type.sh 四種輸入，涵蓋全部結束碼：多個 commit 標題當參數傳入取得 fix，結束碼 0；兩行標題從標準輸入餵入取得 docs，結束碼 0；空字串取得結束碼 2；不在階梯表內的型別取得結束碼 3。錯誤訊息都印在 stderr，內容為繁體中文。
實跑 jsc-meta/tools/ste100-lint.sh 與 jsc-meta/tools/lint-scripts.sh，兩支都結束碼 0，語言檢查無輸出，腳本檢查三支全過。
三份資訊清單以 json.load 逐份驗證，都是合法 JSON。
併入後重讀整份 skills/pr/SKILL.md：九個步驟編號連續、每個步驟以可檢核的完成條件結尾、內部與規則段的步驟指標都指得到、沒有任何步驟的輸入來自它後面的步驟。文件內沒有殘留衝突標記。
其餘為文件審閱：逐項核對步驟編號的互相引用、腳本結束碼宣告與技能分支的對應、以及重複內容是否都改成指向正本。技能文件的實際執行沒有在本次驗證，需要在安裝後的實跑中確認。

前置 Push Request

無

## 摘要 - 需求描述：對本外掛做一次規範符合度與流程效率的檢查，並修好查到的問題。規範面補齊缺漏的失敗分支、修正指錯的步驟編號、補上腳本結束碼說明、補宣告缺少的外掛相依。效率面把重複的開啟中 PR 查詢收斂成一次、抽出型別優先序腳本當唯一真實來源、移除抄寫一份的階梯表，並解開並行化造成的循環相依。另外併入基底分支上剛進來的 PR 流程確認說明，並把 `jsc-gitea` 的相依下限往上提。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/pick-type.sh` | 新檔。把 commit 型別優先序從技能內文抽成腳本，成為該優先序的唯一真實來源。參數與標準輸入都收，commit 標題整行餵進來也認得出型別，並定義三個結束碼。 | | `tools/base-branch.sh` | 標頭原本只用一行護欄帶過，看不出每個結束碼屬於哪個模式、也看不出該怎麼處置。改寫成逐碼說明，每個碼寫明模式、成因與下一步，讓技能有可以逐碼分支的依據。 | | `tools/slugify.sh` | 同上，標頭補齊結束碼說明，並補上原本沒寫的參數不足這一碼。 | | `skills/commit/SKILL.md` | 解開分組步驟的循環相依，改成只有註解掃描與盤點並行、分組排在盤點之後。開啟中 PR 的查詢改成依呼叫方決定要不要查，並補上查詢各種失敗的分支。另外寫明程式層閘門只在單一 CLI 生效，其餘 CLI 仍靠技能內文守規則。 | | `skills/pr/SKILL.md` | 刪掉抄寫一份的階梯表，改指向規範文件的正本。呼叫方傳入的基底改在最前面先驗。型別改交給新腳本挑。整條呼叫鏈的開啟中 PR 查詢收斂成一次，建立 PR、編輯 PR、留言回覆與該次查詢都補上失敗分支，步驟編號的互相引用一併校正，流程由十一步收到九步。本次另外併入基底分支上剛進來的三處確認說明，接到重排後的步驟，並改寫成英文，詳見下一節。 | | `README.md` | 同步技能說明，補上新腳本一列，並把重複的階梯表換成指向規範正本的說明。 | | `plugin.json` | 補宣告本外掛對 `jsc-meta` 的相依，並遞增外掛版本。另把 `jsc-gitea` 的相依下限往上提一版。 | | `.claude-plugin/plugin.json` | 同上，維持三份資訊清單一致。 | | `.codex-plugin/plugin.json` | 同上，維持三份資訊清單一致。 | ## 設計重點 - 型別優先序只留一份。順序寫在新腳本裡，技能改成呼叫腳本，不再抄一份順序表。腳本每一項只取冒號、左括號、驚嘆號之前的字，所以 `git log --format=%s` 的輸出可以直接用管線餵進去。 - 階梯規則也只留一份。技能與 README 都改成指向規範文件的「PR 分支階梯」一節，推導仍由既有腳本負責，正本與實作各一份，不再有第三份抄本。 - 開啟中 PR 只查一次。原本認可與開 PR 兩支技能各自查一次，整條鏈重複查詢；現在改由開 PR 這一側查一次，把號碼、標題、基底與描述一起帶下去給後續比對，其餘位置一律不再查。原本認可完再回頭呼叫開 PR 的遞迴回呼也一併移除。 - 解開一個並行化造成的循環相依。分組原本被拉進並行區塊，但它要吃盤點的檔案清單；而盤點的完成條件又寫成要有分組結果，兩邊互相等待。改成只有註解掃描與盤點並行，分組接在盤點之後，掃描要求的修正仍在第一個 commit 之前完成。 - 呼叫方傳入的基底先驗。它合不合法只看遠端有沒有這條分支，與目標分支名稱無關，所以移到最前面驗，錯的輸入不必等到命名做完才被擋下。 - 失敗要有出口。建立 PR、編輯 PR、回覆留言與開啟中 PR 查詢都補上逐碼分支，重點是不把查詢失敗讀成「沒有開啟中的 PR」，避免在已有 PR 的分支上再開一個。留言回覆改成單一則失敗只記錄原因，不中斷整輪。 - 結束碼寫在腳本標頭。腳本自己宣告幾個碼，技能就分支幾個碼，兩邊對得起來。原本有一支宣告了多個碼、技能只分支其中三個，其餘落在沒人處理的縫隙裡。 ## 併入基底分支上的確認說明本分支已推送且 PR 開啟中，所以用 merge 併入基底分支，不改寫已推送的歷史，正在看 PR 的人對得上。基底分支上剛進來的那一輪，在 `skills/pr/SKILL.md` 加了三處「這一步會先要求確認」。本分支同時把同一份文件從十一步重排成九步，兩邊在同一段衝突。解法是兩邊的改動都留：保留九步重排，並把那三處按它們原本掛的動作接到重排後的步驟，不照行號硬接。對應如下： | 原本的步驟 | 動作 | 接到的新步驟 | | --- | --- | --- | | 第 7 步 | 建立 PR，即 `pr-create` | 第 7 步 | | 第 9 步 | 更新 PR 標題與描述，即 `pr-edit` | 第 8 步 | | 第 9 步 | 掛上前置 PR 依賴，即 `pr-depend` | 第 8 步 | 三處都改寫成英文，寫法一律是 `Ask the user to confirm before this call runs.`。理由是規範的「語言」一節明訂 SKILL.md 整份英文，只有要原樣輸出的繁體中文字面才例外；這三處是給執行者看的指示，不是要輸出的字面。本 PR 本身就在做語言合規修正，留著中文會自相矛盾。三處確認的行為完全沒變，只換了語言與掛載的步驟編號。 ## 相依下限 `skills/pr/SKILL.md` 與 `skills/commit/SKILL.md` 都已改用 `gitea.sh pr-of-branch`，而這個子命令只有較新的 `jsc-gitea` 才有。三份資訊清單的 `jsc-gitea` 下限因此從 `>=0.1.7` 提到 `>=0.1.8`，裝到舊版的機器才不會跑到那一步失敗。同一輪的 `jsc-meta` 已經因為同樣理由提過下限，兩邊一致。三份清單只動這一個鍵的值，外掛自身版號沒有動。 ## 測試結果 - 本次變更是 markdown 技能文件、shell 腳本與 JSON 資訊清單，專案沒有測試框架，所以沒有測試套件可跑。 - 實跑 `bash -n tools/base-branch.sh tools/pick-type.sh tools/slugify.sh`，三支腳本語法檢查全部通過。 - 實跑 `tools/pick-type.sh` 四種輸入，涵蓋全部結束碼：多個 commit 標題當參數傳入取得 `fix`，結束碼 0；兩行標題從標準輸入餵入取得 `docs`，結束碼 0；空字串取得結束碼 2；不在階梯表內的型別取得結束碼 3。錯誤訊息都印在 stderr，內容為繁體中文。 - 實跑 `jsc-meta/tools/ste100-lint.sh` 與 `jsc-meta/tools/lint-scripts.sh`，兩支都結束碼 0，語言檢查無輸出，腳本檢查三支全過。 - 三份資訊清單以 `json.load` 逐份驗證，都是合法 JSON。 - 併入後重讀整份 `skills/pr/SKILL.md`：九個步驟編號連續、每個步驟以可檢核的完成條件結尾、內部與規則段的步驟指標都指得到、沒有任何步驟的輸入來自它後面的步驟。文件內沒有殘留衝突標記。 - 其餘為文件審閱：逐項核對步驟編號的互相引用、腳本結束碼宣告與技能分支的對應、以及重複內容是否都改成指向正本。技能文件的實際執行沒有在本次驗證，需要在安裝後的實跑中確認。 ## 前置 Push Request - 無

jiantw83 added 4 commits 2026-08-31 03:09:15 +00:00

feat(tools): 新增 commit 型別優先序腳本 bd277b6e55

型別優先序原本抄在技能內文裡。改一次要跟著改好幾份，很容易對不起來。
現在把順序收進腳本，讓它成為唯一真實來源。

- 參數與標準輸入都收，commit 標題整行餵進來也認得出型別。
- 沒收到輸入回傳 2，輸入裡沒有階梯表型別回傳 3，呼叫端據此分流。
- 錯誤訊息一律印繁體中文到 stderr。

fix(skills): 補齊失敗分支並解開分組步驟的循環相依 fcd0b3b8c0

兩支技能的步驟有幾處寫不完整。出錯時流程會走偏，步驟之間也互相卡住。

- 建立 PR、修改 PR、回覆留言、查詢開啟中的 PR，四處原本只寫成功路徑。API 失敗會被當成「沒有開啟中的 PR」，於是在同一支分支上重開一支。現在四處都補上失敗分支。
- 推導基底的腳本結束碼原本只分流三個，其餘落空。現在每個結束碼都有處置與下一步。
- 交叉引用指到收尾步驟，改指回真正做校準的那一步。
- 分組原本被拉進平行區塊，但分組要等盤點的檔案清單，盤點的完成條件又要等分組結果。現在只有註解掃描與盤點平行，分組排在盤點之後。
- 認可與開 PR 原本各查一次開啟中的 PR。改成共用單次查詢，並拿掉認可回呼開 PR 的遞迴。
- 呼叫方傳入的基底改在最前面驗證。基底不合法就當場擋下，不必等命名做完。
- 重複的階梯表從技能內文刪掉，改指向指引正本。

docs(tools): 補上腳本結束碼說明，並改指階梯規則正本 25792fd279

腳本標頭沒把每個結束碼代表什麼、該怎麼處理寫清楚，呼叫端只能用猜的。階梯表又同時抄在說明檔與技能內文，改規則時兩邊容易不同步。

- 推導基底的腳本標頭逐碼說明狀況與處置，並標明該碼屬於哪一種模式。
- 產生分支名的腳本標頭補上參數不足的結束碼。
- 說明檔刪掉重複的階梯表，改指向指引的階梯章節。
- 說明檔補上型別優先序腳本的說明，並更新兩支技能的摘要。

chore(plugin): 宣告 jsc-meta 相依 368f6c5f11

技能改成引用 jsc-meta 的指引正本。相依關係要跟著寫進外掛資訊檔，否則沒裝 jsc-meta 的機器讀不到階梯規則。

- requires 加入 jsc-meta。
- 三份外掛資訊檔一起推進，避免彼此不一致。

jiantw83 added 2 commits 2026-08-31 03:21:04 +00:00

docs(pr): 併入上游的流程確認說明並接到重排後的步驟 113b044bb6

把上游剛進來的三處確認說明接到重排後的正確步驟，並依準則改寫成英文。

chore(plugin): 提高 jsc-gitea 相依下限 b952af32b8

技能已改用只在新版才有的子命令，下限跟著提高，避免舊版環境跑到那一步失敗。

admin approved these changes 2026-08-31 03:24:23 +00:00

admin merged commit 0a66f64ea0 into develop

2026-08-31 03:24:26 +00:00

admin deleted branch fix/skill-check-compliance-and-flow

2026-08-31 03:24:26 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/git#21