plugins/code-review
Archived
2
0
Fork 0
Code Pull Requests Activity
This repository has been archived on 2026-07-15. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
b2066f5e6db5a1c07ce507a8b16d5b47f88a1d9b
code-review/skills/code-review-resolve/SKILL.md
T

17 KiB
Raw Blame History

name: code-review-resolve description: 讀取工作目錄 .gitea/ai-review/findings.json（Gitea AI review 產出的問題清單），依嚴重等級（🔴 嚴重→🟠 高→🟡 中→🔵 低）由高到低逐條解決程式碼問題；全部解完後把 .gitea/ai-review/findings.json 清空為空陣列 []。接著做 git 處理：分析工作區內所有檔案變更，依異動內容歸類為 feat/fix/docs/style/refactor/perf/test/chore/revert，分門別類各自 commit，commit 訊息為「type(範圍): 一句總結」格式，括號內的範圍須對應實際異動的功能／模組（例 feat(使用者登入): 新增帳密登入流程、perf(物件查詢): 改用批次查詢降低 DB 往返，而非 feat(新增功能) 這類重述 type 的詞）。提交後 push 當前分支（先用認證管理器、失敗改用 token、再失敗詢問使用者），push 成功後用 token 透過 Gitea API 對目標分支發 PR（目標分支不明必須詢問、不可猜測），PR 描述可選完整版（重新分析 git diff 總結）／簡單版（逐條列 commit 訊息）／使用者輸入；完成後因內文可能含 gitea token，提醒並清除 AI 助理對話內文。當使用者說解決 findings、處理 AI review 問題、修掉 .gitea/ai-review 的問題、依嚴重度逐條修復後分類提交、或要把工作區變更依 conventional commit 分類 commit 並 push 開 PR 時觸發。不適用於：產生 findings（那是 Gitea AI review CI 或 /jsc:code-review 的工作）、單純審查不修改、或不分類的單一 commit。 argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]"

code-review-resolve — 解決 AI review findings、分類提交、push 並開 PR

四階段 skill：先逐條修掉 .gitea/ai-review/findings.json 裡的問題並清空該檔，再把工作區所有變更依 conventional commit 類型分門別類 commit，接著 push 當前分支，最後透過 Gitea API 發 PR。

階段 動作
A. 解決問題 讀 findings.json → 依等級 🔴→🟠→🟡→🔵 逐條修復程式碼 → 清空 findings.json 為 []
B. 分類提交 分析工作區所有變更 → 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit
C. Push 當前分支 認證管理器 → 失敗改 token → 再失敗詢問使用者
D. 發出 PR 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文

輸出規範（務必遵守）

  • 語言：所有面向使用者的輸出（修復清單、提交計畫、總結、反問）與 commit 訊息 一律使用繁體中文（台灣用語）； 僅程式碼識別字、檔名、git 指令、conventional commit 的 type（feat/fix…）等技術標識保留原文，不可使用簡體字。
  • 編碼無亂碼（含繁中、全形標點、emoji）：凡輸出或寫入只要含繁體中文，一律 UTF-8（不含 BOM），不得出現問號方框（）或錯碼。涵蓋：清空後的 findings.json、commit 訊息、PR 標題／描述、終端訊息，與等級 emoji 🔴🟠🟡🔵。實作要點：
    • 寫檔：優先用助理的檔案寫入工具（預設 UTF-8 無 BOM）。若改用 shell 寫檔，避免 PowerShell 的 >／Out-File（預設可能寫成 UTF-16 或加 BOM）；需要時用 Set-Content -Encoding utf8NoBOM，或在 bash 用 printf／heredoc。
    • commit 訊息：用 git commit -m 直接帶字串，或寫進 UTF-8 無 BOM 的檔案再 git commit -F <file>；確保 git config i18n.commitEncoding utf-8。
    • PR body：以 UTF-8 JSON 經 API 送出（如 --data @body.json，該檔為 UTF-8 無 BOM）。
    • 送出前自我檢查：產生含繁中的檔案／訊息後，回頭確認沒有亂碼或 BOM 再提交／送出。
  • 修改程式碼、commit、push、開 PR 屬於更動專案／對外行為：除非帶 --yes 或使用者已明確授權，否則每階段動手前先輸出計畫（預覽）並取得同意；使用者拒絕則只輸出計畫、不動檔不提交不推送。
  • Token 機密保護（極重要）：gitea token 一律從環境變數讀取（如 $GITEA_TOKEN），絕不寫死在 skill、commit、PR 內文或任何輸出；不可 echo 含 token 的指令或 URL、不可寫進 log。所有顯示給使用者的指令／錯誤訊息都要遮蔽 token（如以 *** 取代）。階段 D 完成後依規範清除對話內文（見 D5）。

參數

格式：[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]

  • --findings <路徑>：findings 檔路徑。省略時預設 .gitea/ai-review/findings.json（相對於工作目錄根）。
  • --target <目標分支>：PR 的目標分支。省略時於階段 D 必須詢問使用者，不可猜測。
  • --pr-desc <full|simple|自訂文字>：PR 描述形式。full＝完整版（重新分析 diff 總結）、simple＝簡單版（逐條列 commit 訊息）、或直接給自訂文字；省略則於階段 D 詢問。
  • --no-commit：只做階段 A（修復 + 清空 findings），不執行階段 B/C/D（不提交、不推送、不開 PR）。
  • --no-pr：執行到階段 C（push）為止，不開 PR（階段 D 略過）。
  • --yes：略過各階段的同意確認，直接執行（修復、清空、commit、push、開 PR 一氣呵成）。未帶時每階段先預覽再確認。

階段 A：依嚴重等級逐條解決問題

A1. 讀取 findings

讀 --findings 指定（或預設 .gitea/ai-review/findings.json）的檔案，內容為 top-level JSON 陣列，每筆是一個問題物件。常見欄位（不同產生器命名略有差異，需容錯對應）：

語義 可能欄位名
嚴重等級 severity / level / 等級
檔案位置 file / path / 檔案位置
所在行數 line / lines / 所在行數
問題標題 title / message / 問題
問題描述 description / detail / 描述
修正建議 suggestion / fix / 建議
  • 檔案不存在、內容為 [] 或空白 → 視為「無問題待解決」，輸出告知並直接跳到階段 B（仍會把工作區既有變更分類提交，除非 --no-commit）。
  • JSON 解析失敗 → 回報錯誤與檔案路徑並停止，不臆測內容、不亂改檔。

A2. 依嚴重等級排序

把所有 finding 依等級由高到低排序：🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低。 英文／其他寫法對應：critical/blocker→🔴、high/major→🟠、medium/moderate→🟡、low/minor/info→🔵；無法辨識的等級排在最後並標註「等級未知」。

A3. 逐條修復（高等級先）

輸出一張「修復計畫」表並（未帶 --yes 時）請使用者確認後，依排序由上而下逐條處理：

# 等級 問題 檔案位置 行數 修復方式

對每一條 finding：

  1. 讀取對應檔案與其脈絡（依 file / line）。
  2. 依 suggestion／description 在程式碼中實作修正；建議含糊或與現況不符時，依原始碼脈絡做最小且合理的修正。
  3. 無法安全自動修復（例如需求不明、牽涉設計取捨、檔案不存在）→ 不硬改，標記為「待人工處理」並記錄原因，繼續下一條。
  4. 逐條完成後，記錄該條結果（✅ 已修復 / ⏭️ 待人工處理 + 原因）。

一次只處理一條、修完再處理下一條，避免互相干擾；同檔多條問題可合併讀取但仍逐條套用修正。

A4. 清空 findings.json

所有可修復條目處理完畢後，把 findings.json 內容覆寫為空陣列：

[]
  • 以 UTF-8（不含 BOM）寫入，結尾保留一個換行。
  • 若仍有「待人工處理」條目：先回報這些條目，詢問使用者是否仍要清空（清空代表這些問題不再留在檔案中）。未帶 --yes 且使用者未同意 → 保留這些條目於檔案、只移除已修復的條目，並在總結說明。

階段 B：分析變更並分類提交（--no-commit 時略過）

B1. 盤點工作區變更

git status --porcelain
git diff            # 已追蹤檔的未暫存變更
git diff --staged   # 已暫存變更

涵蓋所有變更：已修改、新增（未追蹤）、刪除、改名。無任何變更 → 回報「工作區無變更可提交」並結束。

B2. 依異動內容歸類 conventional commit 類型

逐一檢視每個變更檔的實際異動內容（不只看路徑），歸入下列其一：

type 適用情境
feat 新增功能／新行為／新 API／新 skill
fix 修正錯誤、修掉 bug（階段 A 的 bug 修復多半歸此）
docs 只改文件（README、註解、*.md、說明）
style 不影響邏輯的格式調整（排版、空白、分號、命名一致化）
refactor 重構：不改外部行為的內部結構調整
perf 效能優化
test 新增或修改測試
chore 雜項：建置、設定、相依套件、版本號 bump、忽略檔等
revert 還原先前的提交
  • 同一檔案橫跨多型 → 以該檔主要異動性質歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
  • 階段 A 修復產生的變更：依其性質歸類（修 bug→fix、補功能→feat、改文件→docs…）。findings.json 被清空這項異動歸 chore。

B3. 產出提交計畫並確認

把變更檔依 type 分組，每個 type 一個 commit，輸出提交計畫供確認（未帶 --yes 時）：

順序 type(範圍) commit 訊息 納入檔案
  • commit 訊息格式：type(範圍): 一句總結 —
    • type：上表英文類型。
    • 範圍（括號內）：必須是這組異動實際牽涉的功能／模組／元件名稱，而不是重述 type 的類別詞。 取名規則：優先沿用程式碼／專案中既有的識別名（檔名、模組名、skill 名、功能名，可中可英、保持與原碼一致），讓人一眼看出「改到哪個東西」。
      • ✅ 對：feat(使用者登入)、fix(結帳流程)、perf(物件查詢)、docs(README)、refactor(訂單服務)、chore(plugin 版本)、feat(code-review-resolve)。
      • ❌ 錯（只是重述 type，禁止）：feat(新增功能)、fix(修正錯誤)、perf(優化效能)、docs(文件)、chore(雜項)。
      • 一組異動橫跨多個功能而無單一主體時，才退而取最貼近的上層範圍（例如多個 manifest → plugin 設定）。
    • 一句總結：把這個 commit 內所有異動總結成一句繁體中文（簡短、聚焦做了什麼）。
    • 範例：feat(使用者登入): 新增帳密登入與 token 簽發、fix(結帳流程): 修正空購物車導致的結帳例外、perf(物件查詢): 改用批次查詢降低 DB 往返、docs(README): 補上安裝與呼叫方式說明、chore(plugin 版本): bump 至 0.0.7 並清空 findings.json。
  • 提交順序建議：fix/feat 等核心異動在前，docs/style/chore 在後（純屬建議，可依相依性調整）。

B4. 執行分類提交

對每組依序：

git add -- <該組檔案...>       # 僅暫存該組檔案，逐組精準 add
git commit -m "type(範圍): 一句總結"   # 範圍＝實際異動的功能／模組名
  • 逐組 add／commit，確保每個 commit 只含該類異動；不要一次 git add -A 再混在一起。
  • 改名／刪除檔一併納入對應組的 git add（git add -A -- <路徑> 或明確列出）。
  • commit 完成後進入階段 C（push）；--no-commit 或無新 commit 時不進入後續階段。

階段 C：Push 當前分支（--no-commit／無新 commit 時略過）

commit 完成後推送當前分支，依序嘗試三種方式，前者失敗才退到下一個：

  1. 認證管理器（優先）：直接用 git 既有的 credential helper（如 Windows 的 manager-core）：

    git push -u origin "$(git rev-parse --abbrev-ref HEAD)"

  2. 失敗 → 改用 token push：從環境變數讀 token，組帶 token 的遠端 URL 推送。整個過程不可把含 token 的指令／URL 印出來（用變數帶入、輸出時遮蔽）：

    # GITEA_TOKEN 來自環境變數；解析 origin 的 host/owner/repo
git push "https://oauth2:${GITEA_TOKEN}@<host>/<owner>/<repo>.git" \
  "$(git rev-parse --abbrev-ref HEAD)"

    （token 用完即棄，不寫進 git remote 設定、不落地。）

  3. 再失敗 → 詢問使用者要如何 push：列出失敗原因（遮蔽 token），請使用者指示推送方式，不可自行猜測其他憑證或來源。

push 成功後記下遠端分支名，進入階段 D。

階段 D：透過 Gitea API 發出 PR（--no-pr／--no-commit 時略過）

D1. 確定目標分支（不可猜想）

  • 帶 --target <分支> → 直接採用。
  • 否則必須詢問使用者目標分支（可用 git branch -r 列出輔助選擇），嚴禁臆測或預設（不可自行假設 develop／main／master）。

D2. 解析 repo 座標

從 git remote get-url origin 解析出 host／owner／repo（例：https://gitea.jsc.idv.tw/plugins/code-review.git → host=gitea.jsc.idv.tw、owner=plugins、repo=code-review）。

D3. 決定 PR 描述形式（完整版／簡單版／使用者輸入）

依 --pr-desc（或詢問）三選一：

  • 完整版（full）：重新分析並總結 git diff <target>...<當前分支>（比對 source 自分岔點以來的變更），整理成結構化繁體中文說明 —— 變更摘要、影響範圍、重點檔案／模組、風險或注意事項。不是貼原始 diff，而是「人讀得懂的總結」。

  • 簡單版（simple）：直接把本分支領先 target 的 commit 訊息逐條列出：

    git log --oneline "<target>..$(git rev-parse --abbrev-ref HEAD)"

    以條列呈現每行 commit 訊息。

  • 使用者輸入：採用使用者提供的描述文字。

PR 標題預設取一句總結（可用首個 feat/fix commit 或分支用途）；使用者另有指定則從之。

D4. 呼叫 Gitea API 建立 PR（使用 token）

token 從環境變數讀取，呼叫 Gitea 建立 PR：

# 不可 echo 含 token 的指令；body 以檔案或變數帶入，輸出時遮蔽 token
curl -sS -X POST \
  -H "Authorization: token ${GITEA_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://<host>/api/v1/repos/<owner>/<repo>/pulls" \
  -d '{"head":"<當前分支>","base":"<target>","title":"<標題>","body":"<描述>"}'
  • 成功：取回應中的 PR 連結／編號回報使用者。
  • 失敗：顯示 API 回應的錯誤訊息供排查（先遮蔽 token）。常見錯誤：目標分支不存在、已有相同 head→base 的 PR、token 權限不足。

D5. 完成通知 + 清除對話內文（重要：可能含 token）

  1. 通知使用者：push 結果、PR 連結／編號、PR 描述採用哪種形式。
  2. 清除 AI 助理對話內文：因為 push／API 過程可能使對話內文殘留 gitea token，完成後務必清除對話內文／上下文以免外洩：
    • Claude Code：提示使用者執行 /clear（或依當前助理對等指令清空對話）。
    • 其他助理：執行各自清除對話／上下文的方式。
    • 在清除前，請再次確認輸出與 log 中沒有任何明文 token。

總結

各階段執行後輸出：

  • 階段 A：已修復 N 條（依等級分佈）、待人工處理 M 條（列出原因）、findings.json 是否已清空。
  • 階段 B：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（--no-commit / 無變更）。
  • 階段 C：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名。
  • 階段 D：PR 連結／編號、目標分支、描述形式；並提醒已（或請使用者）清除對話內文以防 token 外洩。

呼叫方式

格式：[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes] — 全部可省略（findings 預設 .gitea/ai-review/findings.json；目標分支省略時必問、不猜測）。token 一律由環境變數（如 GITEA_TOKEN）提供。

助理 呼叫
Claude Code / Antigravity /jsc:code-review-resolve，或 /jsc:code-review-resolve --target develop --pr-desc full --yes、/jsc:code-review-resolve --no-pr、/jsc:code-review-resolve --no-commit
Codex $code-review-resolve，或 $code-review-resolve --target develop --pr-desc simple --yes，或用 /skills 選單
OpenCode 描述需求（如「讀 .gitea/ai-review/findings.json 依嚴重度逐條修好、清空該檔，把工作區變更依 conventional commit 分類提交，push 後對 develop 發 PR（完整版描述）」）自動觸發
View Git Blame Copy Permalink