@@ -1,16 +1,16 @@
---
name : code-review-resolve
description : 解決 `.gitea/ai-review/findings.json` 的 AI review findings，先同步 git（ ／ 若更新後目前分支名稱與遠端分支名稱相同， 建立新的工作分支；必要時嘗試解衝突），再依嚴重度逐條修復；可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json`，已解決或已登記為誤報的 finding 可自 findings 移除；接著可將工作區變更依 conventional commit 類型分類提交、push 當前分支，並透過 Gitea API 對指定目標分支開 PR。當使用者說解決 findings、處理 AI review 問題、修掉 `.gitea/ai-review` 問題、依嚴重度修復後分類提交，或要分類 commit 並 push/開 PR 時觸發。不適用於：產生 findings、單純 code review 不修改、只保存裁決紀錄，或只要不分類的單一 commit。
description : 解決 `.gitea/ai-review/findings.json` 的 AI review findings，先同步 git（ 留在目前分支 pull 更新，不存在則切換到 develop／ 只有來源分支與 PR 目標分支相同時才 建立新的工作分支；必要時嘗試解衝突），再依嚴重度逐條修復；可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json`，已解決或已登記為誤報的 finding 可自 findings 移除；接著可將工作區變更依 conventional commit 類型分類提交、push 當前分支，並透過 Gitea API 對指定目標分支開 PR。當使用者說解決 findings、處理 AI review 問題、修掉 `.gitea/ai-review` 問題、依嚴重度修復後分類提交，或要分類 commit 並 push/開 PR 時觸發。不適用於：產生 findings、單純 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：先執行 **git 同步 ** （ `git fetch` → 確認目前分支的遠端分支是否存在；存在則 `git pull` 更新，不存在則切換到 `develop` ，再退而 `master` 後 `git pull` 更新；若更新後目前分支名稱與遠端分支名稱相同， 建立新的工作分支；必要時告知並嘗試解衝突），再**逐條處理** `.gitea/ai-review/findings.json` 裡的問題；成立問題修復後自 findings 移除，可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json` 後也可自 findings 移除，接著把工作區所有變更**依 conventional commit 類型分門別類 commit**，然後 **push 當前分支 ** ，最後**透過 Gitea API 發 PR**。
五階段 skill：先執行 **git 同步 ** （ `git fetch` → 確認目前分支的遠端分支是否存在；存在則留在目前分支 `git pull` 更新，不存在則切換到 `develop` ，再退而 `master` 後 `git pull` 更新；只有來源分支與 PR 目標分支相同時才 建立新的工作分支；必要時告知並嘗試解衝突），再**逐條處理** `.gitea/ai-review/findings.json` 裡的問題；成立問題修復後自 findings 移除，可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json` 後也可自 findings 移除，接著把工作區所有變更**依 conventional commit 類型分門別類 commit**，然後 **push 當前分支 ** ，最後**透過 Gitea API 發 PR**。
| 階段 | 動作 |
| --- | --- |
| A. Git 同步 | `git fetch` → 當前分支不在遠端則切換 develop（再退而 master）→ `git pull` ／必要時解衝突 → 若目前分支與遠端同名則 建立新工作分支 |
| A. Git 同步 | `git fetch` → 當前分支不在遠端則切換 develop（再退而 master）→ `git pull` ／必要時解衝突 → 只有來源分支與 PR 目標分支相同時才 建立新工作分支 |
| B. 解決問題 | 讀 `findings.json` / `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` 移除，誤報寫入 `exclusions.json` 後也可移除；**無待處理問題則跳到階段 D** |
| C. 分類提交 | 分析工作區所有變更 → 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
| D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者；**無 commit 可 push 則跳到階段 E** |
@@ -77,7 +77,7 @@ current_branch="$(git rev-parse --abbrev-ref HEAD)"
git rev-parse --verify --quiet " origin/ ${ current_branch } "
```
- **`origin/<current_branch>` 存在** → 維持當前分支，直接進入 A4 更新到最新；此分支視為遠端同名基準分支，A5 必須從它 建立新的 工作分支，避免後續修復 commit 直接落在同名遠端 分支上 。
- **`origin/<current_branch>` 存在** → 維持當前分支，直接進入 A4 更新到最新；不要只因目前分支有遠端同名分支就 建立新工作分支，後續只有來源分支與 PR 目標分支相同時才需要開新 分支。
- **`origin/<current_branch>` 不存在**（當前分支為本地獨有，遠端無對應）→ 依序嘗試切換到後備分支：
1. 切換前先確認工作區可安全切換（承接 A1 結果）。若有未提交變更導致切換失敗，停止並回報，請使用者先處理未提交變更；不可強制丟棄。
2. 若 `origin/develop` 存在 → 切換到 `develop` ：
@@ -93,7 +93,7 @@ git rev-parse --verify --quiet "origin/${current_branch}"
` ``
4. **` develop` 與 ` master` 在遠端都不存在** → 回報「當前分支不在遠端，且找不到 develop／master 後備分支」並停止，不臆測其他分支。
- 切換完成後，A4 先更新該後備分支到最新， ；
- 切換完成後，A4 先更新該後備分支到最新；是否 建立新的工作分支交由 A5 依來源分支與 PR 目標分支是否相同判斷。 切換到後備分支屬不可忽略的狀態變更，需在輸出中明確告知使用者已從原分支切換到哪一個分支。
### A4. Pull（更新到最新）
@@ -107,27 +107,28 @@ git pull
- 若顯示需要指定 merge / rebase 策略，先回報原因；未帶 ` --yes` 時詢問使用者要採用哪種策略，不可自行猜測。
- 若 pull 產生衝突，立即告知使用者發生衝突，接著依階段 A6 嘗試解衝突。
### A5. 若目前分支與遠端同名 ，建立新的工作分支
### A5. 只有來源分支與 PR 目標分支相同時 ，建立新的工作分支
A4 更新完成後，再次確認目前分支與遠端分支的關係 ：
A4 更新完成後，取得目前來源分支與 PR 目標分支 ：
` ``bash
bas e_branch="$(git rev-parse --abbrev-ref HEAD)"
git rev-parse --verify --quiet "origin/${base_branch}"
sourc e_branch="$(git rev-parse --abbrev-ref HEAD)"
# target 來自 --target；若未提供且後續會建立 PR（未帶 --no-pr），需先依 E1 詢問目標分支。
` ``
- **若 ` origin/<base_branch> ` 存在**（目前分支名稱與遠端分支名稱相同）→ 不在該分支上直接修復／commit。從目前已更新到最新的基準分支建立新的工作分支，後續階段（ 修復、 commit、push、PR 的 ` head `）都以新分支為準 。
- **若後續會建立 PR（未帶 ` --no-pr `）且尚未知道目標分支** → 先依階段 E1 的規則詢問目標分支，避免後續 修復 commit 落在與 PR 目標同名的來源分支上才發現 source/base 相同。若帶 ` --no-pr `，此階段不因缺少目標分支而詢問 。
- **若來源分支名稱與目標分支相同** → 不在該分支上直接修復／commit，也不可後續直接建立 head=base 的 PR。從目前已更新到最新的目標分支建立新的工作分支，後續階段（修復、commit、push、PR 的 ` head`）都以新分支為準。
- **若來源分支名稱與目標分支不同** → 維持目前分支，不另開分支；即使目前分支存在 ` origin/<source_branch>`，也照常在目前分支處理。
- 新分支名稱需可讀且避免覆蓋既有分支；預設格式：
` ``bash
work_branch="ai-review-resolve/${bas e_branch}-$(date +%Y%m%d-%H%M%S)"
work_branch="ai-review-resolve/${sourc e_branch}-$(date +%Y%m%d-%H%M%S)"
git switch -c "${work_branch}"
` ``
- 建立前若本地或遠端已存在同名分支，換一個時間戳或短 hash，不可覆蓋既有分支。
- 若因未提交變更導致建立／切換新分支失敗，停止並回報，請使用者先處理未提交變更；不可強制丟棄。
- 建立新分支屬不可忽略的狀態變更，需在輸出中明確告知使用者「已從 ` <bas e_branch>` 建立並切換到 ` <work_branch>`」。
- **若 ` origin/<base_branch>` 不存在**（目前已在本地獨有工作分支）→ 維持目前分支，不另開分支。
- 建立新分支屬不可忽略的狀態變更，需在輸出中明確告知使用者「因來源分支與目標分支同名， 已從 ` <sourc e_branch>` 建立並切換到 ` <work_branch>`」。
### A6. 必要時嘗試解衝突
@@ -137,7 +138,7 @@ git rev-parse --verify --quiet "origin/${base_branch}"
2. 讀取衝突檔脈絡，依專案現有行為與遠端變更做最小合理整合。
3. 可安全解決的衝突：編輯檔案移除衝突標記，執行 ` git add -- <檔案...>` 標記已解決。
4. 無法安全判斷的衝突：停止處理，列出檔案、衝突原因與需要使用者決策的點；不要硬選任一邊。
5. 全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 ` git status --porcelain` 沒有未解衝突，再回到 A5 建立必要的 新工作分支。
5. 全部衝突解完後，依 git 當前狀態完成 merge / rebase 的必要步驟，確認 ` git status --porcelain` 沒有未解衝突，再回到 A5 判斷是否需要 建立新工作分支。
---
@@ -308,8 +309,8 @@ git log --oneline "origin/${source_branch}..${source_branch}" # 領先遠端
` ``
- **無 commit 可 push**（來源分支已存在於遠端，且相對 ` origin/<source_branch>` 沒有領先 commit）→ **跳過本階段 push，直接進入階段 E**（仍可對既有遠端分支開 PR）；若帶 ` --no-pr`，則就此結束。
- 若來源分支沒有對應的 ` origin/<source_branch>`，視為需要 push 的新分支，先記錄「無遠端基準」並繼續；後續若 source/base 同名，階段 E2 仍必須以 ` origin/<target> ` 作為帶入 commit 的比較基準 。
- 若後續會建立 PR（未帶 ` --no-pr`）且尚未知道目標分支，先依階段 E1 的規則詢問目標分支，這屬於不可忽略的必要決策，避免把 commit 直接推進目標分支後才發現 source/base 相同 。
- 若來源分支沒有對應的 ` origin/<source_branch>`，視為需要 push 的新分支，先記錄「無遠端基準」並繼續；這種情況不需要切回 develop／master，因為 A3 已在同步階段處理「當前分支不存在於遠端」的後備切換 。
- 若後續會建立 PR（未帶 ` --no-pr`）且尚未知道目標分支，先依階段 E1 的規則詢問目標分支，這屬於不可忽略的必要決策。
- 若來源分支名稱與目標分支相同，**不要 push 原來源分支**；記下來源分支與遠端基準，直接進入階段 E，由 E2 建立新的 PR 來源分支、帶入 commit 後再 push 新分支。
1. **認證管理器（優先）**：直接用 git 既有的 credential helper（如 Windows 的 ` manager-core`）：
@@ -436,7 +437,7 @@ curl -sS -X POST \
各階段執行後輸出：
- **階段 A**： 遠端 同名是否已建立新工作分支、是否發生衝突、衝突是否已解決或仍需人工處理。
- **階段 A**： 來源 分支與目標分支 同名是否已建立新工作分支、是否發生衝突、衝突是否已解決或仍需人工處理。
- **階段 B**：已解決 N 條（依等級分佈）、誤報寫入 exclusions M 條、待人工處理 K 條（列出原因）、` findings.json` 保留／移除筆數與 ` exclusions.json` 新增筆數；若無待處理問題，說明已跳過階段 C 直接進入階段 D。
- **階段 C**：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（` --no-commit` / 無變更）。
- **階段 D**：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名；若無 commit 可 push，說明已跳過 push 直接進入階段 E。