From 1efebdfd226af8f7fe0272cb319ee45877f45112 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 31 Aug 2026 11:07:05 +0800 Subject: [PATCH] =?UTF-8?q?docs(review):=20=E8=AA=AA=E6=98=8E=E6=AA=94?= =?UTF-8?q?=E5=B0=8D=E9=BD=8A=E6=96=B0=E7=9A=84=E6=8A=80=E8=83=BD=E8=A1=8C?= =?UTF-8?q?=E7=82=BA=E8=88=87=E5=B7=A5=E5=85=B7=E6=B8=85=E5=96=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 三支技能的說明改成與技能文件一致，讀說明檔的人不會拿到舊的判準。 - 補上兩支新腳本的用途、輸入輸出與結束碼。 - 偵測腳本的結束碼說明補上缺 grep 這個原因。 - 刻意移除的那道保護另寫一段提醒：hook 關掉或沒接上時，認可前要先跑註解清理。 --- README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9c7e625..2fd1a61 100644 --- a/README.md +++ b/README.md @@ -26,15 +26,17 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 ### `code-review` -對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。第 2 組同時擋「文件編號與審查流程痕跡夾帶」：註解只寫「為什麼這樣寫」，議題編號、wiki 頁編號、工作包編號、commit hash、`@` 提及、外部文件連結、審查輪次、發現編號與審查狀態一律不進註解，清單看 `references/comment-scope.md`。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才進入彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。 +對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。步驟 1 先把 diff 落成一份快照檔，六組讀同一份，git 只算一次，六組的結論也一致。第 2 組的註解範圍只管樣式判不出來的部分：專案代號、客戶名稱與情境相關的審查痕跡；禁止清單與允許清單的唯一來源是 `references/comment-scope.md`，這裡不再抄一份。樣式判得出來的項目由 `jsc-hooks/hooks/comment-scope.sh` 擋。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才交給 `tools/merge-findings.sh` 彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。 + +> 刻意移除的保護：第 2 組本來連樣式判得出來的項目也重掃一遍，所以 `JSC_COMMENT_SCOPE=off` 或該 CLI 沒接上 `comment-scope.sh` 時，第 2 組是最後一道網。現在那道網沒有了。hook 關掉或沒接線時，議題編號、wiki 頁編號、工作包編號、commit hash 留在註解裡不會有人擋，commit 前請改跑 `/jsc-review:comment-cleanup`。 ### `api-doc` -稽核 API 專案的 Swagger 文件：每個可能回傳的 HTTP 狀態碼都要宣告回覆類型，每個輸入與輸出都要有說明與真實資料範例，並沿著巢狀資料模型逐層遞迴。控制器改完或實作完成時執行，例如由 `jsc-sdlc:implement` 呼叫，與 `jsc-review:code-review` 並列為兩關收尾稽核。先跑 `tools/swagger-detect.sh` 偵測，套件與掛接設定要雙重命中才算支援；只裝套件沒掛接就回報未啟用並停手，不開任何 sub agent。原始碼的註解契約歸 `jsc-review:code-review` 第 5 組，這支只管 Swagger 文件屬性與範例，兩支不重複回報。回報 `檔案:行號`、嚴重度與建議修法，本技能不改程式碼。 +稽核 API 專案的 Swagger 文件：每個可能回傳的 HTTP 狀態碼都要宣告回覆類型，每個輸入與輸出都要有說明；範例只掛在純量成員上，類別型成員只留說明，範例責任往下推給它的屬性，一路遞迴到最內層的純量。集合看元素型別判斷：元素是純量就比照純量，附一份列出幾個元素的範例；元素是類別就比照類別，只留說明，遞迴改走進元素型別。控制器改完或實作完成時執行，例如由 `jsc-sdlc:implement` 呼叫，與 `jsc-review:code-review` 並列為兩關收尾稽核。先跑 `tools/swagger-detect.sh` 偵測，套件與掛接設定要雙重命中才算支援；只裝套件沒掛接就回報未啟用並停手，不開任何 sub agent。稽核分兩個面向，各一個 sub agent 平行執行：狀態碼一個，說明與範例連同巢狀資料模型的遞迴合成一個，同一批資料模型檔只讀一次，兩份檢核表分段列出。兩個面向都回覆才交給 `tools/merge-findings.sh` 彙整。原始碼的註解契約歸 `jsc-review:code-review` 第 5 組，這支只管 Swagger 文件屬性與範例，兩支不重複回報。回報 `檔案:行號`、嚴重度與建議修法，本技能不改程式碼。 ### `comment-cleanup` -清理本次變更新增或修改的註解，把文件追蹤資訊與審查流程痕跡移除，只留下程式邏輯的實質理由。使用者要求「清一下註解」、「不要留 review 痕跡」，或 commit 前發現註解夾帶流程資訊時執行。判斷準則只看 `references/comment-scope.md`，本技能負責清理，`comment-scope.sh` 負責擋，`code-review` 第 2 組負責指出人工判讀案例。未明確要求時不動未變更的舊註解。 +清理本次變更新增或修改的註解，把文件追蹤資訊與審查流程痕跡移除，只留下程式邏輯的實質理由。使用者要求「清一下註解」、「不要留 review 痕跡」，或 commit 前發現註解夾帶流程資訊時執行。判斷準則只看 `references/comment-scope.md`，本技能負責清理，`comment-scope.sh` 負責擋，`code-review` 第 2 組負責指出人工判讀案例。改寫每個檔案一個 sub agent 平行跑，建置與測試留到最後統一跑一次。未明確要求時不動未變更的舊註解。 @@ -49,7 +51,9 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | 檔案 | 用途 | | --- | --- | -| `tools/swagger-detect.sh` | 判斷專案有沒有真的啟用 Swagger。套件與設定雙重確認，缺一不算支援。輸出 `support=`、`stack=`、`package=`、`config=`；結束碼 0 支援、1 不支援、2 參數或路徑錯誤 | +| `tools/swagger-detect.sh` | 判斷專案有沒有真的啟用 Swagger。套件與設定雙重確認，缺一不算支援。輸出 `support=`、`stack=`、`package=`、`config=`；結束碼 0 支援、1 不支援、2 參數個數不對、路徑不存在或環境缺 grep | +| `tools/merge-findings.sh` | 合併 `code-review` 六組與 `api-doc` 兩個面向的發現。輸入是六欄 TSV（檔案、行號、嚴重度、組別、發現名稱、說明），同一個檔案與行號的發現併成一列，再依 高 → 中 → 低 排序。結束碼 0 有發現、1 無發現、2 參數或環境錯誤、3 輸入格式錯誤 | +| `tools/changed-comments.sh` | 列出本次變更新增或修改的註解行，供 `comment-cleanup` 決定清理範圍。不給參數比對工作區與 HEAD，給基準版本則比對 `{base}...HEAD`。輸出三欄 TSV（檔案、行號、內容）；註解樣式與非程式碼副檔名清單沿用 `jsc-hooks/hooks/comment-scope.sh` 的同一份。結束碼 0 有結果、1 無結果、2 參數或環境錯誤 | ## 相關 domain