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

feat(review): 新增 API 文件稽核技能，第 5 組擴充註解的條列、導向與標示規則 #11

Merged
admin merged 6 commits from feat/api-doc-audit/main into develop 2026-08-27 08:54:29 +00:00
Conversation 0 Commits 6 Files Changed 8
+289 -11
jiantw83 commented 2026-08-27 08:52:25 +00:00
Member
Copy Link
Copy Source

PR 描述

摘要

  • 需求描述：使用者提出的 15 條工作規則中，群二（產出物文件品質）四條落在本存取庫。R5 要求 Swagger 控制器文件完整、R6 要求 XML 註解標籤排版、R7 要求服務與存取庫的註解補全、R8 要求註解裡的專有名詞與變數用該語言的標示語法標起來。落點問過使用者才定：code-review 的 references/smells.md 第 5 組本來就是註解契約，已涵蓋 R7 的大部分，所以 R6 到 R8 擴充第 5 組而不新建技能；只有 R5 稽核的是 Swagger 文件屬性、不是原始碼註解，才獨立成 jsc-review:api-doc。決策紀錄在 wiki knowledges/QUESTION 的 QUESTION_FB8DF0B5（2026-08-27 兩節共 12 題）。本 PR 是主幹 feat/api-doc-audit/main 併回 develop 的釋出 PR，內容為已合併的子功能 PR #10。
  • 計畫名稱：無
  • 計畫頁：無
  • 分析頁：無

變更內容

檔案 為什麼改
skills/api-doc/SKILL.md 新增技能。R5 稽核 Swagger 文件三個面向：每個可回傳的 HTTP 狀態碼都宣告回應型別、每個輸入與輸出都有說明與真實資料範例、巢狀資料模型逐層遞迴。三個面向各自以 sub agent 執行，只回報不改程式碼
tools/swagger-detect.sh 新增工具。專案支不支援 Swagger 要在程式層判定，不能靠技能自己看一眼決定。同時檢查套件與掛接，退出碼 0 支援、1 不支援、2 參數或路徑有錯
references/smells.md 第 5 組從 5.1 到 5.5 擴充到 5.8：5.1 補條列式處理步驟與規則、5.3 補回傳資料模型的導向連結、新增 5.6 內含功能的導向連結、5.7 XML 註解標籤排版、5.8 專有名詞與變數標示。新增項目的嚴重度另立一表，不讓五項全壓在「註解缺漏」一句話裡
skills/code-review/SKILL.md 第 5 組的 sub agent 範圍改為 5.1 到 5.8，並寫明與 api-doc 的分工：這裡只管原始碼註解契約，Swagger 文件屬性歸 api-doc，同一個缺口不重複回報兩次
README.md 「Skills 目錄」補上 api-doc，並記下 swagger-detect.sh 的用途與退出碼
plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份 manifest 同步升版至 0.0.6

設計重點

  • R6 到 R8 不新建技能，擴充第 5 組。 這一點問過使用者才定。第 5 組本身就是註解契約，R7 要求的服務與存取庫註解補全已被 5.1 到 5.5 涵蓋大半；另開一支技能只會讓同一份註解被兩支技能各掃一次，同一行程式碼收到兩筆重複發現。
  • R5 獨立成技能，因為稽核對象不同。 api-doc 看的是 Swagger 文件屬性（ProducesResponseType、@ApiResponse、FastAPI 的 responses=、drf-spectacular 的 @extend_schema），第 5 組看的是原始碼註解。兩者的證據來源、修法與工具都不一樣，混在一支技能裡會讓「文件沒寫」與「註解沒寫」互相蓋掉。
  • 支不支援 Swagger 由程式判定，且套件與掛接兩者都要。 只看套件會誤判：專案裝了套件卻從未在啟動流程掛上，文件根本產不出來，這時稽核控制器等於稽核一份不存在的文件。swagger-detect.sh 兩者都要成立才回 0，因此「裝了但沒啟用」會回 1，技能據實回報不支援並停下。
  • 不支援時明確跳過並回報，跳過算通過。 技能第 2 步印出固定字串與偵測結果就停，不開任何 sub agent。沉默跳過會讓呼叫端誤以為稽核過了。
  • 稽核項目只寫在 api-doc 一處。 jsc-sdlc:implement 那一端只寫「呼叫這支技能」與退出碼分流，不抄項目清單。抄一份就會有兩套標準，改了一邊忘了另一邊。
  • 範例資料優先取自專案真實資料，取不到才推導並標「推導值」。 從資料庫取來的範例一律去識別化，個人資料不得寫進 Swagger 文件。
  • 5.1 與 5.6 的條列長度當肥大訊號。 條列步驟超過十項、被呼叫的功能多到列不完，代表方法本身太肥或在當協調中心，技能同時列出第 1 組或第 3 組的對應項目，而不是只叫人把註解補長。

測試結果

  • tools/ste100-lint.sh 掃本存取庫全綠。
  • 三份 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）版本一致，皆為 0.0.6。
  • tools/swagger-detect.sh 三種技術棧各驗兩種情境，共六筆：dotnet、nodejs、python 的「套件加掛接」回 0（support=、stack=、package=、config= 四行齊全），「只有套件沒掛接」回 1，四行輸出仍印出，符合技能第 2 步據實回報的前提。
  • 未測試項目：真實 Gitea 專案上的端到端 API 文件稽核沒跑過。api-doc 的三個面向都是 sub agent 逐檔判讀，需要一個真的有控制器與資料庫的專案才驗得出發現品質，本批只驗到偵測與分流這一層。技能執行結果的準確度尚未有實測證據。

前置 Push Request

  • 無。本批的跨存取庫依賴方向是別人依賴這裡：jsc-sdlc 的 implement 呼叫本存取庫的 tools/swagger-detect.sh 與 jsc-review:api-doc，因此 sdlc 那支釋出 PR 依賴本 PR，本 PR 自己沒有前置。子功能 PR #10 已合併進主幹 feat/api-doc-audit/main，本 PR 只是把主幹併回 develop，沒有未結清的前置 PR。
# PR 描述 ## 摘要 - 需求描述：使用者提出的 15 條工作規則中，群二（產出物文件品質）四條落在本存取庫。R5 要求 Swagger 控制器文件完整、R6 要求 XML 註解標籤排版、R7 要求服務與存取庫的註解補全、R8 要求註解裡的專有名詞與變數用該語言的標示語法標起來。落點問過使用者才定：`code-review` 的 `references/smells.md` 第 5 組本來就是註解契約，已涵蓋 R7 的大部分，所以 R6 到 R8 擴充第 5 組而不新建技能；只有 R5 稽核的是 Swagger 文件屬性、不是原始碼註解，才獨立成 `jsc-review:api-doc`。決策紀錄在 wiki `knowledges/QUESTION` 的 `QUESTION_FB8DF0B5`（2026-08-27 兩節共 12 題）。本 PR 是主幹 `feat/api-doc-audit/main` 併回 `develop` 的釋出 PR，內容為已合併的子功能 PR #10。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/api-doc/SKILL.md` | 新增技能。R5 稽核 Swagger 文件三個面向：每個可回傳的 HTTP 狀態碼都宣告回應型別、每個輸入與輸出都有說明與真實資料範例、巢狀資料模型逐層遞迴。三個面向各自以 sub agent 執行，只回報不改程式碼 | | `tools/swagger-detect.sh` | 新增工具。專案支不支援 Swagger 要在程式層判定，不能靠技能自己看一眼決定。同時檢查套件與掛接，退出碼 `0` 支援、`1` 不支援、`2` 參數或路徑有錯 | | `references/smells.md` | 第 5 組從 5.1 到 5.5 擴充到 5.8：5.1 補條列式處理步驟與規則、5.3 補回傳資料模型的導向連結、新增 5.6 內含功能的導向連結、5.7 XML 註解標籤排版、5.8 專有名詞與變數標示。新增項目的嚴重度另立一表，不讓五項全壓在「註解缺漏」一句話裡 | | `skills/code-review/SKILL.md` | 第 5 組的 sub agent 範圍改為 5.1 到 5.8，並寫明與 `api-doc` 的分工：這裡只管原始碼註解契約，Swagger 文件屬性歸 `api-doc`，同一個缺口不重複回報兩次 | | `README.md` | 「Skills 目錄」補上 `api-doc`，並記下 `swagger-detect.sh` 的用途與退出碼 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 三份 manifest 同步升版至 0.0.6 | ## 設計重點 - **R6 到 R8 不新建技能，擴充第 5 組。** 這一點問過使用者才定。第 5 組本身就是註解契約，R7 要求的服務與存取庫註解補全已被 5.1 到 5.5 涵蓋大半；另開一支技能只會讓同一份註解被兩支技能各掃一次，同一行程式碼收到兩筆重複發現。 - **R5 獨立成技能，因為稽核對象不同。** `api-doc` 看的是 Swagger 文件屬性（`ProducesResponseType`、`@ApiResponse`、FastAPI 的 `responses=`、drf-spectacular 的 `@extend_schema`），第 5 組看的是原始碼註解。兩者的證據來源、修法與工具都不一樣，混在一支技能裡會讓「文件沒寫」與「註解沒寫」互相蓋掉。 - **支不支援 Swagger 由程式判定，且套件與掛接兩者都要。** 只看套件會誤判：專案裝了套件卻從未在啟動流程掛上，文件根本產不出來，這時稽核控制器等於稽核一份不存在的文件。`swagger-detect.sh` 兩者都要成立才回 `0`，因此「裝了但沒啟用」會回 `1`，技能據實回報不支援並停下。 - **不支援時明確跳過並回報，跳過算通過。** 技能第 2 步印出固定字串與偵測結果就停，不開任何 sub agent。沉默跳過會讓呼叫端誤以為稽核過了。 - **稽核項目只寫在 `api-doc` 一處。** `jsc-sdlc:implement` 那一端只寫「呼叫這支技能」與退出碼分流，不抄項目清單。抄一份就會有兩套標準，改了一邊忘了另一邊。 - **範例資料優先取自專案真實資料，取不到才推導並標「推導值」。** 從資料庫取來的範例一律去識別化，個人資料不得寫進 Swagger 文件。 - **5.1 與 5.6 的條列長度當肥大訊號。** 條列步驟超過十項、被呼叫的功能多到列不完，代表方法本身太肥或在當協調中心，技能同時列出第 1 組或第 3 組的對應項目，而不是只叫人把註解補長。 ## 測試結果 - `tools/ste100-lint.sh` 掃本存取庫全綠。 - 三份 manifest（`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`）版本一致，皆為 0.0.6。 - `tools/swagger-detect.sh` 三種技術棧各驗兩種情境，共六筆：dotnet、nodejs、python 的「套件加掛接」回 `0`（`support=`、`stack=`、`package=`、`config=` 四行齊全），「只有套件沒掛接」回 `1`，四行輸出仍印出，符合技能第 2 步據實回報的前提。 - 未測試項目：真實 Gitea 專案上的端到端 API 文件稽核沒跑過。`api-doc` 的三個面向都是 sub agent 逐檔判讀，需要一個真的有控制器與資料庫的專案才驗得出發現品質，本批只驗到偵測與分流這一層。技能執行結果的準確度尚未有實測證據。 ## 前置 Push Request - 無。本批的跨存取庫依賴方向是別人依賴這裡：`jsc-sdlc` 的 `implement` 呼叫本存取庫的 `tools/swagger-detect.sh` 與 `jsc-review:api-doc`，因此 sdlc 那支釋出 PR 依賴本 PR，本 PR 自己沒有前置。子功能 PR #10 已合併進主幹 `feat/api-doc-audit/main`，本 PR 只是把主幹併回 `develop`，沒有未結清的前置 PR。
jiantw83 added 6 commits 2026-08-27 08:52:25 +00:00
feat(smells): 第 5 組擴充條列式步驟、導向連結與標示語法 dbaf81005b 
What：references/smells.md 第 5 組擴充。5.1 的方法描述後面要接條列式的處理步驟
與規則，5.3 的回傳值是自訂資料模型時要附上型別定義的導向連結；新增 5.6 內含
功能的導向連結、5.7 XML 註解標籤各占一行、5.8 註解裡的專有名詞與變數依語言
慣例標示。文末的嚴重度分級補上一張表，逐項標明這五個新項目的級別與理由。

Why：使用者提出的產出物文件品質規則裡，有三條講的都是原始碼註解要寫到什麼
程度。動手前先比對過既有內容，第 5 組已經涵蓋大部分，缺的是條列步驟、導向
連結與標示語法這三塊。另開一支技能會跟 code-review 的目標重疊，所以直接擴充
第 5 組。新項目多半屬於可讀性層級，混在原本「註解缺漏」一句話裡分不出輕重，
所以級別另外列。

How：5.1 與 5.3 在原有定義後面接上新要求，偵測訊號與建議重構手法同步補列，
原本的判準一個都不動。5.6 到 5.8 照既有小節的四段結構寫：定義、偵測訊號、
建議重構手法、注意事項。5.8 的標示語法用表格對照 XML 與 JSDoc、docstring
兩類格式。5.6 與 5.7 都寫明註解格式不支援時不適用，避免硬造連結字串，也避免
把 XML 的排版規則套到沒有結束標籤的格式上。

Who：jsc-review 的壞味道參考清單，第 5 組註解契約。
feat(swagger-detect): 新增判斷專案有沒有啟用 Swagger 的工具 57ac9cdcd9 
What：新增 tools/swagger-detect.sh，判斷一個專案有沒有真的啟用 Swagger 文件。
涵蓋 dotnet、nodejs、python 三種技術棧，輸出 support=、stack=、package=、
config= 四類欄位；結束碼 0 支援、1 不支援、2 參數個數不對或專案路徑不存在。

Why：API 文件稽核只對產得出 Swagger 文件的專案有意義。支不支援如果交給 agent
自己看程式碼判斷，同一個專案可能這次說支援、下次說不支援。判定寫成腳本，呼叫端
讀結束碼分支就好，不必自己猜。

How：雙重確認，套件與設定缺一不算支援。第一關在套件宣告檔裡找已知的 Swagger
套件，第二關在原始碼裡找真的把 Swagger 接上去的呼叫或裝飾子。設定關鍵字一律
挑接線動作，不挑 import 或 require——光是引入套件不代表文件真的掛上去了。裝了
套件卻沒啟用的專案很常見，只看套件會誤判，讓稽核跑在一個根本產不出文件的專案
上。輸出刻意做成一行一個 key=value，呼叫端逐行讀就好。

Who：jsc-review 的 api-doc 技能，以及 jsc-sdlc 實作階段的收尾稽核。
feat(api-doc): 新增 API 文件稽核技能 dfaa66feda 
What：新增 skills/api-doc/SKILL.md。六步流程：偵測 Swagger 支援、不支援就回報
並停手、列出稽核範圍、分三個面向各開一個 sub agent 稽核、彙整去重排序、回報
發現。三個面向分別是狀態碼的回覆類型、參數說明與範例、資料模型遞迴。本技能
只回報「檔案:行號」、嚴重度與建議修法，不改程式碼。

Why：支援 Swagger 的專案要把控制器文件補全：所有可能出現的狀態碼都宣告回覆
類型，輸入輸出都要有說明與真實資料範例，參數是資料模型就每個屬性都套用、內含
模型再往下遞迴。這是 code-review 六組沒碰過的領域，跟第 5 組的原始碼註解契約
也不是同一件事，所以獨立成一支技能，不塞進既有的六組裡。

How：第一步跑 tools/swagger-detect.sh，讀結束碼決定走下去還是停手，不支援時
一個 sub agent 都不開，直接回報未啟用。範例優先取專案的真實資料，資料庫、
種子資料、測試夾具都算；真的取不到才依邏輯推導，並在文件裡標上「推導值」，
讓後面讀的人知道這個值沒被觀察過。取自資料庫的範例一律去識別化，個人資料不
進 Swagger 文件。分工另立一節：本技能只管 Swagger 文件屬性，原始碼註解契約
歸 code-review 第 5 組，同一個缺失不會被回報兩次。

Who：jsc-review 新增的 api-doc 技能，由 jsc-sdlc 的 implement 收尾時呼叫。
feat(review): code-review 範圍改為 5.1 到 5.8 並補上與 api-doc 的分工 51c2705667 
What：skills/code-review/SKILL.md 的審查範圍表，第 5 組由原本一句
「smells.md group 5」改成明確的 5.1 到 5.8，並點名 5.6、5.7、5.8 三個新項目；
Notes 加一行分工，Swagger 文件稽核歸 api-doc。README.md 新增 api-doc 的技能
小節，另補一張工具表格列出 swagger-detect.sh。

Why：sub agent 讀的是 SKILL.md 的審查範圍表，範圍表沒寫清楚，新增的 5.6 到
5.8 就不會被查。使用者讀的是 README.md，新技能與新工具沒列出來就找不到。
兩支技能都碰註解與文件，界線不寫明就會對同一個缺失重複回報。

How：範圍表的第 5 組直接列出三個新項目與各自的判準重點，完整清單仍指向
references/smells.md。Notes 寫明 api-doc 負責狀態碼的回覆類型、Swagger 參數
說明與範例，第 5 組只負責原始碼註解契約。README.md 的技能小節寫明偵測先行、
只裝套件沒掛接就停手；工具表格列出 swagger-detect.sh 的用途、輸出欄位與結束碼。

Who：jsc-review 的 code-review 技能與存取庫說明文件。
chore(manifest): 三份 manifest 同步升版至 0.0.6 8b5cc602dc 
What：plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份
manifest 的 version 由 0.0.5 改為 0.0.6。

Why：這批新增了 api-doc 技能與 swagger-detect.sh，也擴充了第 5 組的審查項目，
屬於功能異動。版本沒跟著升，各 CLI 端的外掛版本護欄就分不出新舊，已安裝的
使用者也收不到更新。

How：三份 manifest 只改 version 欄位，其餘欄位維持原樣，三處版本號保持一致。

Who：jsc-review 外掛的安裝與更新流程。
Merge pull request 'feat(review): 新增 API 文件稽核技能，第 5 組擴充註解的條列、連結與標示規則' (#10) from feat/api-doc-audit/api-doc-and-comment-rules into feat/api-doc-audit/main 8eb330a62f 
Reviewed-on: #10
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
admin merged commit 5a2d5d1bab into develop 2026-08-27 08:54:29 +00:00
admin deleted branch feat/api-doc-audit/main 2026-08-27 08:54:29 +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/review#11