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
cf7409f164d9b25511914b60fc77fe3fbbf89dea
code-review/skills/code-review-resolve/SKILL.md
T

21 KiB
Raw Blame History

name, description, argument-hint
name description argument-hint
code-review-resolve 解決 `.gitea/ai-review/findings.json` 的 AI review findings，先同步 git（fetch → pull，必要時嘗試解衝突），再依嚴重度逐條修復或標示待人工處理，完成後清空 findings；接著可將工作區變更依 conventional commit 類型分類提交、push 當前分支，並透過 Gitea API 對指定目標分支開 PR。當使用者說解決 findings、處理 AI review 問題、修掉 `.gitea/ai-review` 問題、依嚴重度修復後分類提交，或要分類 commit 並 push/開 PR 時觸發。不適用於：產生 findings、單純 code review 不修改、只保存裁決紀錄，或只要不分類的單一 commit。 [--findings <findings.json 路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]

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

五階段 skill：先執行 git 同步（git fetch → git pull，必要時告知並嘗試解衝突），再逐條修掉 .gitea/ai-review/findings.json 裡的問題並清空該檔，接著把工作區所有變更依 conventional commit 類型分門別類 commit，然後 push 當前分支，最後透過 Gitea API 發 PR。

階段 動作
A. Git 同步 git fetch → git pull → 若有衝突則告知並嘗試解衝突
B. 解決問題 讀 findings.json → 依等級 🔴→🟠→🟡→🔵 逐條修復程式碼 → 清空 findings.json 為 []
C. 分類提交 分析工作區所有變更 → 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit
D. Push 當前分支 認證管理器 → 失敗改 token → 再失敗詢問使用者
E. 發出 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（如以 *** 取代）。階段 E 完成後依規範清除對話內文（見 E6）。

參數

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

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

階段 A：Git 同步

A1. 檢查同步前狀態

執行同步前先盤點目前分支與工作區狀態：

git rev-parse --abbrev-ref HEAD
git status --porcelain
  • 若工作區已有未提交變更：先告知使用者同步可能需要 merge / rebase 並可能與本地變更衝突；未帶 --yes 時先取得同意再繼續。
  • 若目前不在一般分支上（例如 detached HEAD）：回報狀態並停止，請使用者切到要處理的分支後再執行。

A2. Fetch 遠端更新

git fetch --all --prune
  • fetch 失敗時回報錯誤並停止，不進入 findings 修復。
  • 若錯誤訊息可能含 credential / token，輸出前必須遮蔽。

A3. Pull 當前分支

git pull
  • pull 成功後進入階段 B。
  • 若顯示需要指定 merge / rebase 策略，先回報原因；未帶 --yes 時詢問使用者要採用哪種策略，不可自行猜測。
  • 若 pull 產生衝突，立即告知使用者發生衝突，接著依階段 A4 嘗試解衝突。

A4. 必要時嘗試解衝突

當 git pull 後出現衝突：

  1. 用 git status --porcelain 與衝突標記定位衝突檔。
  2. 讀取衝突檔脈絡，依專案現有行為與遠端變更做最小合理整合。
  3. 可安全解決的衝突：編輯檔案移除衝突標記，執行 git add -- <檔案...> 標記已解決。
  4. 無法安全判斷的衝突：停止處理，列出檔案、衝突原因與需要使用者決策的點；不要硬選任一邊。
  5. 全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 git status --porcelain 沒有未解衝突，再進入階段 B。

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

B1. 讀取 findings

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

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

B2. 依嚴重等級排序

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

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

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

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

對每一條 finding：

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

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

B4. 清空 findings.json

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

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

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

C1. 盤點工作區變更

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

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

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

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

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

C3. 產出提交計畫並確認

把變更檔依 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.8 並清空 findings.json。
  • 提交順序建議：fix/feat 等核心異動在前，docs/style/chore 在後（純屬建議，可依相依性調整）。

C4. 執行分類提交

對每組依序：

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

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

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

推送前先記錄目前來源分支與其遠端基準：

source_branch="$(git rev-parse --abbrev-ref HEAD)"
git rev-parse --verify "origin/${source_branch}"
  • 若來源分支沒有對應的 origin/<source_branch>，先記錄「無遠端基準」並繼續；後續若 source/base 同名，階段 E2 仍必須以 origin/<target> 作為帶入 commit 的比較基準。
  • 若後續會建立 PR（未帶 --no-pr）且尚未知道目標分支，先依階段 E1 的規則詢問目標分支，避免把 commit 直接推進目標分支後才發現 source/base 相同。
  • 若來源分支名稱與目標分支相同，不要 push 原來源分支；記下來源分支與遠端基準，直接進入階段 E，由 E2 建立新的 PR 來源分支、帶入 commit 後再 push 新分支。

  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 成功後記下遠端分支名，進入階段 E。若因來源分支與目標分支相同而延後 push，記下原因並進入階段 E2 建立新分支。

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

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

  • 帶 --target <分支> → 直接採用。
  • 若階段 D 已為了避免 source/base 相同而詢問過目標分支，沿用該目標分支。
  • 否則必須詢問使用者目標分支（可用 git branch -r 列出輔助選擇），嚴禁臆測或預設（不可自行假設 develop／main／master）。

E2. 若來源分支與目標分支相同，改建 PR 來源分支

先取得目前 PR 來源分支：

git rev-parse --abbrev-ref HEAD

若來源分支名稱與 --target 指定（或使用者選定）的目標分支相同，不可直接建立 head=base 的 PR，也不可先把原來源分支 push 到目標分支。改用下列流程建立新的 PR 來源分支，並把原來源分支的 commit 帶入後再開 PR：

  1. 先記錄原來源分支名稱與要帶入的 commit 清單：

    source_branch="$(git rev-parse --abbrev-ref HEAD)"
git log --oneline "origin/${target}..${source_branch}"
    • 若 origin/<target> 不存在，先回報並停止，不猜測替代 base。
    • 若沒有任何 commit 可帶入，回報「來源分支沒有領先目標分支的 commit」，停止開 PR。
    • 若階段 D 已記錄來源分支的遠端基準，使用該基準判斷要帶入的 commit，避免把原來源分支直接推進目標分支。

  2. 從目標分支的遠端基準建立新分支。新分支名稱需可讀且避免覆蓋既有分支，例如：

    git switch -c "ai-review-resolve/<短時間戳>" "origin/${target}"

  3. 將原來源分支領先目標分支的 commit 依序帶入新分支：

    git cherry-pick "origin/${target}..${source_branch}"
    • cherry-pick 發生衝突時，先告知使用者，再依專案脈絡嘗試最小合理解衝突。
    • 可安全解決的衝突：移除衝突標記、git add -- <檔案...>，再繼續 git cherry-pick --continue。
    • 無法安全判斷的衝突：停止處理，列出衝突檔案與需要使用者決策的點；不要硬選任一邊。

  4. 將新分支 push 到遠端，使用階段 D 的同一套 push 憑證策略，並把後續 PR 的 head 改為這個新分支。

若來源分支與目標分支不同，直接以目前分支作為 PR 的 head。

E3. 解析 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）。

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

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

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

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

    git log --oneline "<target>..<PR 來源分支>"

    以條列呈現每行 commit 訊息。

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

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

E5. 呼叫 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":"<PR 來源分支>","base":"<target>","title":"<標題>","body":"<描述>"}'
  • 成功：取回應中的 PR 連結／編號回報使用者。
  • 失敗：顯示 API 回應的錯誤訊息供排查（先遮蔽 token）。常見錯誤：目標分支不存在、已有相同 head→base 的 PR、token 權限不足。

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

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

總結

各階段執行後輸出：

  • 階段 A：git fetch / pull 是否成功、是否發生衝突、衝突是否已解決或仍需人工處理。
  • 階段 B：已修復 N 條（依等級分佈）、待人工處理 M 條（列出原因）、findings.json 是否已清空。
  • 階段 C：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（--no-commit / 無變更）。
  • 階段 D：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名。
  • 階段 E：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