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

release: v0.0.6 develop 到 master #12

Merged
admin merged 7 commits from develop into master 2026-08-27 09:01:20 +00:00
Conversation 1 Commits 7 Files Changed 8
+289 -11
jiantw83 commented 2026-08-27 09:00:08 +00:00
Member
Copy Link
Copy Source

摘要

  • 需求描述：把 jsc-review 0.0.6 從 develop 放行到 master，共 7 個 commit。內容是使用者 15 條工作規則的第二群「產出物文件品質」在本存取庫的落地：新增 jsc-review:api-doc 技能做 Swagger 文件稽核、新增 tools/swagger-detect.sh 判斷專案有沒有啟用 Swagger、references/smells.md 第 5 組從 5.5 擴充到 5.8。
  • 計畫名稱：無
  • 計畫頁：無
  • 分析頁：無

變更內容

檔案 為什麼改
skills/api-doc/SKILL.md 新增 API 文件稽核技能。三個檢查面向各自開一支 sub agent，只回報不改程式碼，要不要修由呼叫者決定。
tools/swagger-detect.sh 新增判斷工具。套件與掛接雙重確認，結束碼 0 是支援、1 是不支援、2 是參數或路徑錯，讓上游技能能照結束碼分流而不是靠猜。
references/smells.md 第 5 組擴充到 5.8：新增 5.6 內含功能的導向連結、5.7 XML 註解標籤排版、5.8 專有名詞與變數標示。
skills/code-review/SKILL.md 第 5 組範圍從 5.1 到 5.5 改成 5.1 到 5.8，並寫明與 api-doc 的分工，避免兩支技能重複審同一件事。
README.md 補上新技能與新工具的用法。
plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份 manifest 同步升版到 0.0.6。

設計重點

  • 這一段才是讓已安裝的 CLI 抓到新內容的那一段。develop 併了不等於生效：marketplace 與 jsc-hooks/hooks/version-guard.sh 讀的都是存取庫的預設分支 master。version-guard.sh 取 raw plugin.json 時刻意不指定 ref，Gitea 就回預設分支那一份，所以只有這個 PR 合進 master，五支 CLI 才看得到 0.0.6。
  • swagger-detect.sh 不只看有沒有裝套件。只裝了套件卻沒在程式裡掛接，等於沒啟用，判定要回不支援，這樣上游才不會對著沒有 Swagger 的專案硬要求文件。
  • api-doc 與 code-review 分工寫在技能裡：控制器與端點的文件完整度歸 api-doc，程式碼本身的註解品質歸 code-review 第 5 組。
  • 三個新增的註解規則都是可指認的：XML 標籤排版看的是版面、專有名詞標示看的是有沒有標、導向連結看的是內含功能有沒有指得到。不是主觀好壞。

升級後使用者會立刻感受到的差異

  • code-review 多三項檢查：XML 註解標籤排版、專有名詞與變數標示、內含功能的導向連結。原本會過的註解，這版可能被指出來。
  • 多一支可以單獨呼叫的 jsc-review:api-doc，也會被 jsc-sdlc:implement 的收尾自動叫到（見 jsc-sdlc 0.2.0 的放行 PR）。

測試結果

  • ste100-lint.sh 掃本存取庫全綠。
  • 三份 manifest 版本一致為 0.0.6。
  • swagger-detect.sh 對 dotnet、nodejs、python 三種技術棧各測兩種情境：「套件加掛接」回 exit 0、「只有套件沒掛接」回 exit 1，六組判定都與預期相同。
  • swagger-detect.sh 另測 fastify、drf-spectacular、什麼都沒有這三種情境，以及參數過多與路徑不存在兩種錯誤情境（exit 2）。
  • 沒跑的部分據實說明：真實 Gitea 端對端的 API 文件稽核沒跑，要跑需要一個實際啟用 Swagger 的專案，目前手上沒有。
  • 本次放行本身沒有重跑腳本測試。上列測試是在子功能 PR（#10）與主幹 PR（#11）階段跑的，這個 PR 只是把已驗證的 develop 內容推到預設分支。

前置 Push Request

  • 無
## 摘要 - 需求描述：把 jsc-review 0.0.6 從 `develop` 放行到 `master`，共 7 個 commit。內容是使用者 15 條工作規則的第二群「產出物文件品質」在本存取庫的落地：新增 `jsc-review:api-doc` 技能做 Swagger 文件稽核、新增 `tools/swagger-detect.sh` 判斷專案有沒有啟用 Swagger、`references/smells.md` 第 5 組從 5.5 擴充到 5.8。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/api-doc/SKILL.md` | 新增 API 文件稽核技能。三個檢查面向各自開一支 sub agent，只回報不改程式碼，要不要修由呼叫者決定。 | | `tools/swagger-detect.sh` | 新增判斷工具。套件與掛接雙重確認，結束碼 0 是支援、1 是不支援、2 是參數或路徑錯，讓上游技能能照結束碼分流而不是靠猜。 | | `references/smells.md` | 第 5 組擴充到 5.8：新增 5.6 內含功能的導向連結、5.7 XML 註解標籤排版、5.8 專有名詞與變數標示。 | | `skills/code-review/SKILL.md` | 第 5 組範圍從 5.1 到 5.5 改成 5.1 到 5.8，並寫明與 `api-doc` 的分工，避免兩支技能重複審同一件事。 | | `README.md` | 補上新技能與新工具的用法。 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 三份 manifest 同步升版到 0.0.6。 | ## 設計重點 - 這一段才是讓已安裝的 CLI 抓到新內容的那一段。`develop` 併了不等於生效：marketplace 與 `jsc-hooks/hooks/version-guard.sh` 讀的都是存取庫的**預設分支** `master`。`version-guard.sh` 取 raw `plugin.json` 時刻意不指定 ref，Gitea 就回預設分支那一份，所以只有這個 PR 合進 `master`，五支 CLI 才看得到 0.0.6。 - `swagger-detect.sh` 不只看有沒有裝套件。只裝了套件卻沒在程式裡掛接，等於沒啟用，判定要回不支援，這樣上游才不會對著沒有 Swagger 的專案硬要求文件。 - `api-doc` 與 `code-review` 分工寫在技能裡：控制器與端點的文件完整度歸 `api-doc`，程式碼本身的註解品質歸 `code-review` 第 5 組。 - 三個新增的註解規則都是可指認的：XML 標籤排版看的是版面、專有名詞標示看的是有沒有標、導向連結看的是內含功能有沒有指得到。不是主觀好壞。 ## 升級後使用者會立刻感受到的差異 - `code-review` 多三項檢查：XML 註解標籤排版、專有名詞與變數標示、內含功能的導向連結。原本會過的註解，這版可能被指出來。 - 多一支可以單獨呼叫的 `jsc-review:api-doc`，也會被 `jsc-sdlc:implement` 的收尾自動叫到（見 jsc-sdlc 0.2.0 的放行 PR）。 ## 測試結果 - `ste100-lint.sh` 掃本存取庫全綠。 - 三份 manifest 版本一致為 0.0.6。 - `swagger-detect.sh` 對 dotnet、nodejs、python 三種技術棧各測兩種情境：「套件加掛接」回 exit 0、「只有套件沒掛接」回 exit 1，六組判定都與預期相同。 - `swagger-detect.sh` 另測 fastify、drf-spectacular、什麼都沒有這三種情境，以及參數過多與路徑不存在兩種錯誤情境（exit 2）。 - 沒跑的部分據實說明：**真實 Gitea 端對端的 API 文件稽核沒跑**，要跑需要一個實際啟用 Swagger 的專案，目前手上沒有。 - 本次放行本身沒有重跑腳本測試。上列測試是在子功能 PR（#10）與主幹 PR（#11）階段跑的，這個 PR 只是把已驗證的 `develop` 內容推到預設分支。 ## 前置 Push Request - 無
jiantw83 added 7 commits 2026-08-27 09:00:08 +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>
Merge pull request 'feat(review): 新增 API 文件稽核技能，第 5 組擴充註解的條列、導向與標示規則' (#11) from feat/api-doc-audit/main into develop 5a2d5d1bab 
Reviewed-on: #11
admin approved these changes 2026-08-27 09:01:18 +00:00
admin merged commit f2b45100bd into master 2026-08-27 09:01:20 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
admin
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: plugins/review#12