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

2026-08-31T03:10:34Z

jiantw83 commented

2026-08-31 03:10:34 +00:00

摘要

需求描述：這批變更做四件事。第一，依使用者提出的規則改掉 api-doc 的範例掛法：類別型參數與中間層的類別屬性只留說明，範例責任往下推給屬性，一路遞迴到最內層的純量；同時把 references/smells.md 裡相牴觸的舊要求一併改掉。第二，新增兩支共用腳本，一支合併與去重審查發現，一支列出本次變更的註解行。第三，補上合規缺口：腳本路徑少一層目錄、結束碼少一種原因、建置測試少一條失敗分支、禁止清單抄了兩份。第四，調整流程效率：差異只算一次、資料模型檔只讀一次、註解清理改成平行跑。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`skills/api-doc/SKILL.md`	範例改成只掛在純量成員上，類別型成員只留說明並往下遞迴；集合看元素型別，字典看值型別。稽核面向由三個併成兩個，發現改回六欄 TSV 並交給共用腳本合併。偵測腳本的結束碼補上第三種原因，並各自寫明下一步
`references/smells.md`	「輸入與輸出範例」與「巢狀結構註解」兩節原本要求輸入與輸出一律附範例，與新規則直接牴觸。改成與 api-doc 同一套型別判準，並註明分工不變，同一個標的不重複回報
`skills/code-review/SKILL.md`	差異落成一份快照檔，六組讀同一份。發現改回六欄 TSV 並交給共用腳本合併。負責模糊性的那一組不再重抄禁止清單，也不再重掃樣式判得出來的項目，並把被移除的保護寫進說明
`skills/comment-cleanup/SKILL.md`	清理範圍改用新腳本計算，不再靠人眼判斷哪幾行是註解。改寫改成一個檔案一個 sub agent 平行跑。建置測試補上「跑完卻失敗」的分支。hook 路徑補上缺的那一層目錄
`tools/merge-findings.sh`	新檔。合併多組審查發現，依檔案與行號去重，再依嚴重度排序，並定下六欄 TSV 的回報契約，兩支技能不再各自描述合併規則
`tools/changed-comments.sh`	新檔。列出本次變更新增或修改的註解行，註解樣式與跳過的非程式碼副檔名清單沿用 hook 的正本，不另立第二套判準
`README.md`	說明對齊新的技能行為，工具清單補上兩支新腳本與修正後的結束碼，並把刻意移除的保護寫成明顯的提醒
`plugin.json`	外掛版號隨這批行為變更提升
`.claude-plugin/plugin.json`	同上，三份清單一起改，避免各 CLI 讀到不一致的版號
`.codex-plugin/plugin.json`	同上，三份清單一起改，避免各 CLI 讀到不一致的版號

設計重點

消除兩支技能互相牴觸的標準。壞味道清單裡的「輸入與輸出範例」與「巢狀結構註解」兩節，原本寫的是輸入與輸出參數都必須有範例。新規則說類別型成員不掛範例。同一段程式碼跑 code-review 會被要求補範例，跑 api-doc 卻會被要求把範例往下搬，兩邊給的答案相反。這次把兩節改成同一套型別判準，兩支技能對同一個成員判出來的結果一致。這是這批變更裡最重要的一點。
範例責任往下推到純量。純量成員自己附範例，類別型成員只留說明，範例由它的屬性各自負責，一路遞迴到最內層。集合看元素型別，不看外層容器，字串清單與單一字串判準相同，類別清單與單一類別判準也相同；字典看值型別，判準一樣。理由是一個字面值只能有一個負責人，掛在上層的整包範例會在屬性一改動就過期。
刻意移除的保護，這裡照實寫。code-review 負責模糊性的那一組，原本會把 hook 已經擋得住的樣式項目再掃一遍，所以在 hook 沒有作用時它是最後一道網。現在那道網拿掉了。註解範圍的開關關掉，或某個 CLI 根本沒接上這支 hook 時，議題編號、wiki 頁編號、工作包編號、commit hash 留在註解裡沒有人會擋，會直接進到 commit。這種情況下請在 commit 前自己跑一次註解清理技能。
共用腳本定下六欄 TSV 的回報契約。欄位是檔案、行號、嚴重度、組別、發現名稱、說明。格式不符的列一律擋下並指出是第幾列，不猜也不自行補欄，因為放行一列格式錯誤的發現，等於讓那筆發現安靜地消失在報告外。腳本用四種結束碼分開「有發現」、「無發現」、「環境或參數錯誤」與「輸入格式錯誤」，呼叫端才不會把環境問題講成沒有東西要審。
流程效率。差異只算一次，落成一份快照檔給六組共讀，檔名帶執行代號，同一台機器上平行跑的兩次審查不會互相覆蓋。api-doc 的兩份檢核表併進同一個面向，同一批資料模型檔只讀一次，兩份檢核表仍分段列出，檢查不會變模糊。註解清理改成一個檔案一個 sub agent 平行跑，建置與測試留到最後統一跑一次。
合規缺口修正。註解範圍腳本的路徑少一層目錄，照著寫會找不到檔案。偵測腳本的結束碼原本只寫參數與路徑兩種原因，漏掉「環境缺 grep」，照舊的說明去換一個路徑重跑，這一種永遠清不掉，所以補上原因與對應的下一步。建置測試原本只寫得出「通過」，現在補上跑完卻失敗的分支，要指出指令、結束碼，並判斷失敗是不是本次改動造成的。禁止清單原本抄了兩份，改成只指向正本，兩份不會各自演化。

測試結果

對 tools/ 底下三支腳本各跑一次 bash -n：changed-comments.sh、merge-findings.sh、swagger-detect.sh，三支語法檢查全部通過，結束碼皆為 0。
其餘變更是 markdown 技能文件與說明檔，本存取庫沒有測試套件可跑，改以人工逐檔複核：確認新舊規則沒有互相牴觸、結束碼與說明一致、路徑指向存在的檔案。
除上述兩項外沒有執行其他測試。

前置 Push Request

無

## 摘要 - 需求描述：這批變更做四件事。第一，依使用者提出的規則改掉 api-doc 的範例掛法：類別型參數與中間層的類別屬性只留說明，範例責任往下推給屬性，一路遞迴到最內層的純量；同時把 `references/smells.md` 裡相牴觸的舊要求一併改掉。第二，新增兩支共用腳本，一支合併與去重審查發現，一支列出本次變更的註解行。第三，補上合規缺口：腳本路徑少一層目錄、結束碼少一種原因、建置測試少一條失敗分支、禁止清單抄了兩份。第四，調整流程效率：差異只算一次、資料模型檔只讀一次、註解清理改成平行跑。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/api-doc/SKILL.md` | 範例改成只掛在純量成員上，類別型成員只留說明並往下遞迴；集合看元素型別，字典看值型別。稽核面向由三個併成兩個，發現改回六欄 TSV 並交給共用腳本合併。偵測腳本的結束碼補上第三種原因，並各自寫明下一步 | | `references/smells.md` | 「輸入與輸出範例」與「巢狀結構註解」兩節原本要求輸入與輸出一律附範例，與新規則直接牴觸。改成與 api-doc 同一套型別判準，並註明分工不變，同一個標的不重複回報 | | `skills/code-review/SKILL.md` | 差異落成一份快照檔，六組讀同一份。發現改回六欄 TSV 並交給共用腳本合併。負責模糊性的那一組不再重抄禁止清單，也不再重掃樣式判得出來的項目，並把被移除的保護寫進說明 | | `skills/comment-cleanup/SKILL.md` | 清理範圍改用新腳本計算，不再靠人眼判斷哪幾行是註解。改寫改成一個檔案一個 sub agent 平行跑。建置測試補上「跑完卻失敗」的分支。hook 路徑補上缺的那一層目錄 | | `tools/merge-findings.sh` | 新檔。合併多組審查發現，依檔案與行號去重，再依嚴重度排序，並定下六欄 TSV 的回報契約，兩支技能不再各自描述合併規則 | | `tools/changed-comments.sh` | 新檔。列出本次變更新增或修改的註解行，註解樣式與跳過的非程式碼副檔名清單沿用 hook 的正本，不另立第二套判準 | | `README.md` | 說明對齊新的技能行為，工具清單補上兩支新腳本與修正後的結束碼，並把刻意移除的保護寫成明顯的提醒 | | `plugin.json` | 外掛版號隨這批行為變更提升 | | `.claude-plugin/plugin.json` | 同上，三份清單一起改，避免各 CLI 讀到不一致的版號 | | `.codex-plugin/plugin.json` | 同上，三份清單一起改，避免各 CLI 讀到不一致的版號 | ## 設計重點 - 消除兩支技能互相牴觸的標準。壞味道清單裡的「輸入與輸出範例」與「巢狀結構註解」兩節，原本寫的是輸入與輸出參數都必須有範例。新規則說類別型成員不掛範例。同一段程式碼跑 code-review 會被要求補範例，跑 api-doc 卻會被要求把範例往下搬，兩邊給的答案相反。這次把兩節改成同一套型別判準，兩支技能對同一個成員判出來的結果一致。這是這批變更裡最重要的一點。 - 範例責任往下推到純量。純量成員自己附範例，類別型成員只留說明，範例由它的屬性各自負責，一路遞迴到最內層。集合看元素型別，不看外層容器，字串清單與單一字串判準相同，類別清單與單一類別判準也相同；字典看值型別，判準一樣。理由是一個字面值只能有一個負責人，掛在上層的整包範例會在屬性一改動就過期。 - 刻意移除的保護，這裡照實寫。code-review 負責模糊性的那一組，原本會把 hook 已經擋得住的樣式項目再掃一遍，所以在 hook 沒有作用時它是最後一道網。現在那道網拿掉了。註解範圍的開關關掉，或某個 CLI 根本沒接上這支 hook 時，議題編號、wiki 頁編號、工作包編號、commit hash 留在註解裡沒有人會擋，會直接進到 commit。這種情況下請在 commit 前自己跑一次註解清理技能。 - 共用腳本定下六欄 TSV 的回報契約。欄位是檔案、行號、嚴重度、組別、發現名稱、說明。格式不符的列一律擋下並指出是第幾列，不猜也不自行補欄，因為放行一列格式錯誤的發現，等於讓那筆發現安靜地消失在報告外。腳本用四種結束碼分開「有發現」、「無發現」、「環境或參數錯誤」與「輸入格式錯誤」，呼叫端才不會把環境問題講成沒有東西要審。 - 流程效率。差異只算一次，落成一份快照檔給六組共讀，檔名帶執行代號，同一台機器上平行跑的兩次審查不會互相覆蓋。api-doc 的兩份檢核表併進同一個面向，同一批資料模型檔只讀一次，兩份檢核表仍分段列出，檢查不會變模糊。註解清理改成一個檔案一個 sub agent 平行跑，建置與測試留到最後統一跑一次。 - 合規缺口修正。註解範圍腳本的路徑少一層目錄，照著寫會找不到檔案。偵測腳本的結束碼原本只寫參數與路徑兩種原因，漏掉「環境缺 grep」，照舊的說明去換一個路徑重跑，這一種永遠清不掉，所以補上原因與對應的下一步。建置測試原本只寫得出「通過」，現在補上跑完卻失敗的分支，要指出指令、結束碼，並判斷失敗是不是本次改動造成的。禁止清單原本抄了兩份，改成只指向正本，兩份不會各自演化。 ## 測試結果 - 對 `tools/` 底下三支腳本各跑一次 `bash -n`：`changed-comments.sh`、`merge-findings.sh`、`swagger-detect.sh`，三支語法檢查全部通過，結束碼皆為 0。 - 其餘變更是 markdown 技能文件與說明檔，本存取庫沒有測試套件可跑，改以人工逐檔複核：確認新舊規則沒有互相牴觸、結束碼與說明一致、路徑指向存在的檔案。 - 除上述兩項外沒有執行其他測試。 ## 前置 Push Request - 無

jiantw83 added 5 commits 2026-08-31 03:10:34 +00:00

feat(tools): 新增發現合併與變更註解兩支腳本 a0bd488ac8

- 合併、去重、排序原本寫在兩支技能的步驟文字裡，各寫一份就會各自演化。改由腳本執行，並定下六欄 TSV 的回報格式。格式不對就擋下並指出是第幾列，不猜、不放行、不自行補欄。
- 另一支腳本列出本次改到的註解行，清理範圍不再靠肉眼判讀。
- 註解樣式與非程式碼副檔名清單沿用註解範圍腳本的同一份，不另立第二套判準。markdown 的標題行開頭就是井字號，判準不一致就會把整份文件當成註解。

feat(api-doc): 範例只掛純量成員，類別型往下遞迴 f6cd1f9ef7

- 使用者要求改判準。類別型參數與中間層的類別屬性只留說明，範例責任往下推給屬性，一路走到最內層的純量。
- 一個值只有一個出處。範例掛在父層，屬性一改就過期，讀的人拿到的是沒有屬性定義背書的一份資料。
- 集合看元素型別，不看外殼；字典看值型別。字串集合與字串判出來一樣，位址集合與位址判出來也一樣。
- 壞味道清單原本寫「輸入與輸出參數都必須有範例」，與新判準衝突，兩支技能會對同一段程式碼給出不同標準。一併改成同一套。
- 說明與範例的兩份檢核表併成一個 sub agent，同一批資料模型檔只讀一次。
- 順帶補上偵測腳本結束碼二漏掉的一個原因：環境缺 grep。原本只寫參數與路徑，遇到這個原因換路徑重跑永遠清不掉。

fix(review): 補上註解腳本路徑與缺漏的失敗分支 ced541faa5

- 註解範圍腳本的路徑少一層目錄，照著寫會找不到檔案，補上 hooks 那一層。
- 建置測試跑完卻失敗時沒有分支可走，只寫得出「通過」。現在要指出指令、結束碼，並判斷失敗是不是本次改動造成的。
- 取得差異失敗時原本會安靜跳過，現在原樣帶出錯誤並停手。判不出範圍不等於沒有東西要審。
- 禁止清單原本抄了兩份，改成只指向註解範圍的正本，兩份不會各自演化。
- 第二組不再重掃樣式判得出來的項目。hook 關掉或沒接上時就沒有最後一道網，這件事寫進技能文件，不讓它默默消失。
- 差異只算一次，落成一份快照檔給六組共讀；檔名帶執行代號，同一台機器平行跑不會互相覆蓋。註解清理改成一個檔案一個 sub agent 平行跑。

docs(review): 說明檔對齊新的技能行為與工具清單 1efebdfd22

- 三支技能的說明改成與技能文件一致，讀說明檔的人不會拿到舊的判準。
- 補上兩支新腳本的用途、輸入輸出與結束碼。
- 偵測腳本的結束碼說明補上缺 grep 這個原因。
- 刻意移除的那道保護另寫一段提醒：hook 關掉或沒接上時，認可前要先跑註解清理。

chore(plugin): 提升外掛版號以帶出這批行為變更 4d15b618c7

- 這批改動含判準變更與兩支新腳本，屬於行為變更，不是純文件修飾。
- claude、codex 與共用的三份描述檔一起帶。版號不一致會讓安裝端拿到舊的技能。

admin merged commit 7c8712963f into develop

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

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

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/review#19