@@ -1,17 +1,17 @@
---
name : code-review-resolve
description : 解決 `.gitea/ai-review/findings.json` 的 AI review findings，先同步 git（ ／
description : 解決 `.gitea/ai-review/findings.json`（不存在或空時 fallback 讀 `.gitea/ai-review/findings/` 目錄下 `*.json`） 的 AI review findings，先同步 git（ ／
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` 更新；只有來源分支與 PR 目標分支相同時才建立新的工作分支；必要時告知並嘗試解衝突），再**逐條處理** `.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` （不存在或空時 fallback 讀 `.gitea/ai-review/findings/` 目錄下所有 `*.json` ） `.gitea/ai-review/exclusions.json` 後也可自 findings 移除，接著**必須盤點並處理工作區的所有變更**，再依 conventional commit 類型分門別類 commit，然後 **push 當前分支 ** ，最後**透過 Gitea API 發 PR**。
| 階段 | 動作 |
| --- | --- |
| A. Git 同步 | `git fetch` → 當前分支不在遠端則切換 develop（再退而 master）→ `git pull` ／必要時解衝突 → 只有來源分支與 PR 目標分支相同時才建立新工作分支 |
| B. 解決問題 | 讀 `findings.json` / `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` 移除，誤報寫入 `exclusions.json` 後也可移除；**無待處理問題則跳到階段 D** |
| B. 解決問題 | 讀 `findings.json` （不存在或空則 fallback `findings/*.json` ） `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` 移除，誤報寫入 `exclusions.json` 後也可移除；**無待處理問題則跳到階段 D** |
| C. 分類提交 | 必須分析並涵蓋工作區所有變更（已修改／新增／刪除／改名，含已暫存與未暫存、未追蹤檔、findings/exclusions 更新）→ 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
| D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者；**無 commit 可 push 則跳到階段 E** |
| E. 發出 PR | 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文 |
@@ -39,7 +39,7 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
格式：`[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]`
- `--findings <路徑>` ： `.gitea/ai-review/findings.json` **（相對於工作目錄根） 。
- `--findings <路徑>` ： 先讀 `.gitea/ai-review/findings.json` ；該檔不存在或為空時，fallback 改讀目錄 `.gitea/ai-review/findings/` 下所有 `*.json` 並合併**（相對於工作目錄根）。指定路徑（檔案或目錄）時直接採用，不套用 fallback 。
- `--target <目標分支>` ：PR 的目標分支。**省略時必須詢問使用者，不可猜測**；若需要避免把同名來源分支誤推到目標分支，可能會在階段 D 先詢問並於階段 E 沿用。
- `--pr-desc <full|simple|自訂文字>` ： `full` ＝完整版（重新分析 diff 總結）、`simple` ＝簡單版（逐條列 commit 訊息）、或直接給自訂文字；省略時預設 `full` ，不要為描述形式中斷詢問。
- `--no-commit` ：只做階段 A/B（git 同步 + 修復 + 更新 findings/exclusions），**不**執行階段 C/D/E（不提交、不推送、不開 PR）。
@@ -143,7 +143,14 @@ source_branch="$(git rev-parse --abbrev-ref HEAD)"
### B1. 讀取 findings 與 exclusions
讀 ` --findings ` 指定（或預設 ` .gitea/ai-review/findings.json `）的檔案，內容為 **top-level JSON 陣列**，每筆是一個問題物件。常見欄位（不同產生器命名略有差異，需容錯對應 ）：
**B1-0. 定位 findings 來源**（依序判斷，決定要讀哪些 finding 檔 ）：
1. **省略 ` --findings` 時**：先讀預設 ` .gitea/ai-review/findings.json`。
2. **若 ` findings.json` 不存在，或內容為 ` []`／空白／僅空白字元** → fallback 到目錄 ` .gitea/ai-review/findings/`：讀取該目錄（含子目錄）下所有 ` *.json`，依檔名排序後合併；每個檔各自為 **top-level JSON 陣列**（若為單一 finding 物件則容錯包成單元素陣列）。
3. **合併時逐筆記住各 finding 的來源檔路徑**，供階段 B4 逐檔就地寫回；此步驟不得更動任何來源檔。
4. **指定 ` --findings <路徑>` 時**：直接採用該路徑，不套用上述 fallback。指定的是檔案就讀該檔；指定的是目錄則比照第 2 點合併該目錄下所有 ` *.json`。
無論來源是單一 ` findings.json` 或目錄下多個 ` *.json`，內容皆為 **top-level JSON 陣列**，每筆是一個問題物件。常見欄位（不同產生器命名略有差異，需容錯對應）：
| 語義 | 可能欄位名 |
| --- | --- |
@@ -181,7 +188,7 @@ source_branch="$(git rev-parse --abbrev-ref HEAD)"
若既有 exclusions 使用 ` suggestion`、` title`、` note` 等欄位，讀取時可容錯；寫回時仍要維持 top-level array，並盡量採用上述 canonical 欄位。
- **檔案不存在、內容為 ` [] ` 或空白** → 視為「無問題待解決」，輸出告知。`` 時就此結束；否則**跳過階段 C 直接進入階段 D**（無待處理問題代表本 skill 未產生需要分類提交的修復變更）。
- **` findings.json ` 與 ` .gitea/ai-review/findings/ ` 目錄皆無可處理的 finding**（依 B1-0 判定：檔案不存在、內容為 ` [] ` 或空白，且 fallback 目錄不存在／無 ` *.json `／全部為空陣列） → 視為「無問題待解決」，輸出告知。`` 時就此結束；否則**跳過階段 C 直接進入階段 D**（無待處理問題代表本 skill 未產生需要分類提交的修復變更）。
- **JSON 解析失敗** → 回報錯誤與檔案路徑並停止，不臆測內容、不亂改檔。
- ` exclusions.json` 不存在時視為空陣列，必要時建立 ` .gitea/ai-review/exclusions.json` 並寫入 ` []` 或新增後的排除項目。
- 若 ` exclusions.json` 是舊 wrapper 格式（例如 ` { "exclusions": [...] }` 或 ` { "excluded_findings": [...] }`），先正規化為 top-level array 再寫回。
@@ -224,6 +231,8 @@ canonical 等級為 `critical` / `warning` / `info`；其他寫法容錯對應
` ``
- 寫回 ` findings.json` 時保留未解決 finding 的 canonical 欄位（` level`、` role`、` location`、` suggestion`）與有用原欄位；依嚴重度排序。
- **來源為目錄 ` .gitea/ai-review/findings/` 時（逐檔就地更新）**：依 B1-0 記錄的來源檔，把尚未解決且尚未登記為誤報的 finding 寫回**其原本所屬檔案**，不得合併到單一 ` findings.json`；某來源檔的 finding 全部已解決／誤報時，將**該檔**寫成空陣列 ` []`（保留檔案、維持目錄結構，不刪檔）。上述保留欄位、排序、UTF-8 規範對每個來源檔一體適用。
- 誤報一律統一寫入 ` .gitea/ai-review/exclusions.json`（不因來源是目錄而分檔）。
- 寫回 ` exclusions.json` 時使用 top-level JSON array；新增項目 append 後依既有順序保留並去重。
- 兩個檔案都以 UTF-8（不含 BOM）寫入，結尾保留一個換行。
@@ -259,7 +268,7 @@ git ls-files --others --exclude-standard # 未追蹤檔
| ` revert` | 還原先前的提交 |
- **同一檔案橫跨多型** → 以該檔**主要異動性質**歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
- **階段 B 修復產生的變更**：依其性質歸類（修 bug→` fix`、補功能→` feat`、改文件→` docs`…）。` findings.json` / ` exclusions.json` 的問題狀態更新歸 ` chore`。
- **階段 B 修復產生的變更**：依其性質歸類（修 bug→` fix`、補功能→` feat`、改文件→` docs`…）。` findings.json`（或 ` findings/ ` 目錄下 ` *.json `）／ `` 的問題狀態更新歸 ` chore`。
- **未追蹤新檔**：必須照實際內容歸入對應 type，必要時在提交前明確 ` git add -- <path>`，不可因為是新檔就略過。
### C3. 產出提交計畫
@@ -450,7 +459,7 @@ curl -sS -X POST \
## 呼叫方式
格式：` [--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]` —
全部可省略（findings 預設 ` .gitea/ai-review/findings.json`；目標分支省略時必問、不猜測）。token 一律由環境變數（如 ` GITEA_TOKEN`）提供。
全部可省略（findings 預設 ` .gitea/ai-review/findings.json`，不存在或空時 fallback 目錄 ` .gitea/ai-review/findings/ ` ；目標分支省略時必問、不猜測）。token 一律由環境變數（如 ``）提供。
| 助理 | 呼叫 |
| --- | --- |