@@ -1,17 +1,17 @@
---
---
name : code-review-resolve
name : code-review-resolve
description : 解決 `.gitea/ai-r eview/ findings.json`（不存在或空時 fallback 讀 `.gitea/ai-review/findings/` 目錄下 `*.json`）的 AI review findings， ／ 可自 findings 移除 ；接著可將工作區變更依 conventional commit 類型分類提交、push 當前分支，並透過 Gitea API 對指定目標分支開 PR。當使用者說解決 findings、處理 AI review 問題、修掉 `.gitea/ai-review` 問題、依嚴重度修復後分類提交，或要分類 commit 並 push/開 PR 時觸發。不適用於：產生 findings、單純 code review 不修改、只保存裁決紀錄，或只要不分類的單一 commit。
description : 解決新版 AI Code R eview 的 findings（ 每次 review 一個 wrapper 物件 JSON，含 `findings`/`excluded` 陣列、中文 severity），或指定 Gitea 議題編號（建問題模式，從議題標題/描述/留言解析嚴重問題為 findings）； 先同步 git（fetch → 檢查目前分支的遠端分支是否存在；存在則留在目前分支 pull 更新，不存在則切換到 develop／ （嚴重/警告/建議） 逐條修復；可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json`，已解決或已登記為誤報的 finding 逐檔就地自來源 wrapper 移除；議題模式修復後於議題留言進度、全解決時關閉議題 ；接著可將工作區變更依 conventional commit 類型分類提交、push 當前分支，並透過 Gitea API 對指定目標分支開 PR。當使用者說解決 findings、處理 AI review 問題、依議題編號修 code 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]"
argument-hint : "[--issue <議題編號>] [--findings <findings 檔或目錄 路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]"
---
---
# code-review-resolve — 解決 AI review findings、分類提交、push 並開 PR
# code-review-resolve — 解決 AI review findings、分類提交、push 並開 PR
五階段 skill：先執行 **git 同步 ** （ `git fetch` → 確認目前分支的遠端分支是否存在；存在則留在目前分支 `git pull` 更新，不存在則切換到 `develop` ，再退而 `master` 後 `git pull` 更新；只有來源分支與 PR 目標分支相同時才建立新的工作分支；必要時告知並嘗試解衝突），再**逐條處理** `.gitea/ai-review/findings.json` （不存在或空時 fallback 讀 `.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/` 目錄下每次 review 產生的 wrapper 物件 JSON（取其 ` findings`陣列），或帶 `--issue <議題編號>` 時從 Gitea 議題標題／描述／留言解析嚴重問題；成立問題修復後自來源 wrapper 逐檔就地 移除，可判斷為誤報者寫入 `.gitea/ai-review/exclusions.json` 後也可移除（議題模式改在議題留言進度、全解決時關閉議題） ，接著**必須盤點並處理工作區的所有變更**，再依 conventional commit 類型分門別類 commit，然後 **push 當前分支 ** ，最後**透過 Gitea API 發 PR**。
| 階段 | 動作 |
| 階段 | 動作 |
| --- | --- |
| --- | --- |
| A. Git 同步 | `git fetch` → 當前分支不在遠端則切換 develop（再退而 master）→ `git pull` ／必要時解衝突 → 只有來源分支與 PR 目標分支相同時才建立新工作分支 |
| A. Git 同步 | `git fetch` → 當前分支不在遠端則切換 develop（再退而 master）→ `git pull` ／必要時解衝突 → 只有來源分支與 PR 目標分支相同時才建立新工作分支 |
| B. 解決問題 | 讀 `findings.json` （ 不存在或空則 fallback `findings/*.json` ） `exclusions.json` → 依等級 🔴→🟠→🟡→🔵 逐條修復或判斷誤報 → 已解決者自 `findings.json` `exclusions.json` 後也可移除 ；**無待處理問題則跳到階段 D** |
| B. 解決問題 | 讀 `.gitea/ai-review/ findings/* .json` （ wrapper 物件，取 `findings` ）或 `--issue` 議題留言 / `exclusions.json` → 依等級 🔴嚴重→🟠警告→🔵建議 逐條修復或判斷誤報 → 已解決者逐檔就地自來源 wrapper 移除，誤報寫入 `exclusions.json` ；議題模式回寫議題（留言＋全解決關閉） ；**無待處理問題則跳到階段 D** |
| C. 分類提交 | 必須分析並涵蓋工作區所有變更（已修改／新增／刪除／改名，含已暫存與未暫存、未追蹤檔、findings/exclusions 更新）→ 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
| C. 分類提交 | 必須分析並涵蓋工作區所有變更（已修改／新增／刪除／改名，含已暫存與未暫存、未追蹤檔、findings/exclusions 更新）→ 依 feat/fix/docs/style/refactor/perf/test/chore/revert 分組 → 各組一個 commit |
| D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者；**無 commit 可 push 則跳到階段 E** |
| D. Push 當前分支 | 認證管理器 → 失敗改 token → 再失敗詢問使用者；**無 commit 可 push 則跳到階段 E** |
| E. 發出 PR | 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文 |
| E. 發出 PR | 確定目標分支（不明必問）→ 選 PR 描述（完整／簡單／自訂）→ token 呼叫 Gitea API 建 PR → 通知並清除內文 |
@@ -30,16 +30,17 @@ argument-hint: "[--findings <findings.json 路徑>] [--target <目標分支>] [-
本 skill 特有補充：
本 skill 特有補充：
- **必要決策**（會中斷詢問）：目標分支缺失、pull 策略不明、無法安全解衝突、需人工判斷的設計取捨、push 憑證皆失敗。
- **必要決策**（會中斷詢問）：目標分支缺失、pull 策略不明、無法安全解衝突、需人工判斷的設計取捨、push 憑證皆失敗。
- 涵蓋範圍：更新後的 `findings.json` / `exclusions.json` 、commit 訊息、PR 標題／描述、終端訊息，與等級 emoji 🔴🟠🟡 🔵。
- 涵蓋範圍：更新後的 `findings/* .json` （ ） `exclusions.json` 、議題留言、 commit 訊息、PR 標題／描述、終端訊息，與等級 emoji 🔴🟠🔵。
- 階段 E 完成後依規範清除對話內文（見 E6）。
- 階段 E 完成後依規範清除對話內文（見 E6）。
---
---
## 參數
## 參數
格式：`[--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]`
格式：`[--issue <議題編號>] [--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]`
- `--findings <路徑>` ： `.gitea/ai-review/findings.json` ；該檔不存在或為空時，fallback 改讀目錄 `.gitea/ai-review/findings/` 下所有 `*.json` 並合併**（相對於工作目錄根）。指定路徑（檔案或目錄）時直接採用，不套用 fallback 。
- `--issue <議題編號>` ：**議題模式**——問題來源改為指定的 Gitea 議題（對應 code-review 的建問題模式）。帶此參數時走階段 B0：讀議題標題／描述／全部留言，把符合嚴重問題留言格式的內容解析成 findings，逐條修復；修復後於階段 B5 在議題留言進度、全部解決時關閉議題。此模式**不讀 `findings/` 目錄**（除非同時明確帶 `--findings` ）。需要 `GITEA_TOKEN` 與可解析的 `origin` repo 座標 。
- `--findings <路徑>` ： `.gitea/ai-review/findings/` 下所有 `*.json` （每個檔為新版 wrapper 物件，取其 `findings` 陣列合併）**（相對於工作目錄根）。指定路徑時：目錄則讀該目錄所有 `*.json` ；單一檔則讀該檔（同為 wrapper 物件）。與 `--issue` 併用時，兩者的問題都納入處理。
- `--target <目標分支>` ：PR 的目標分支。**省略時必須詢問使用者，不可猜測**；若需要避免把同名來源分支誤推到目標分支，可能會在階段 D 先詢問並於階段 E 沿用。
- `--target <目標分支>` ：PR 的目標分支。**省略時必須詢問使用者，不可猜測**；若需要避免把同名來源分支誤推到目標分支，可能會在階段 D 先詢問並於階段 E 沿用。
- `--pr-desc <full|simple|自訂文字>` ： `full` ＝完整版（重新分析 diff 總結）、`simple` ＝簡單版（逐條列 commit 訊息）、或直接給自訂文字；省略時預設 `full` ，不要為描述形式中斷詢問。
- `--pr-desc <full|simple|自訂文字>` ： `full` ＝完整版（重新分析 diff 總結）、`simple` ＝簡單版（逐條列 commit 訊息）、或直接給自訂文字；省略時預設 `full` ，不要為描述形式中斷詢問。
- `--no-commit` ：只做階段 A/B（git 同步 + 修復 + 更新 findings/exclusions），**不**執行階段 C/D/E（不提交、不推送、不開 PR）。
- `--no-commit` ：只做階段 A/B（git 同步 + 修復 + 更新 findings/exclusions），**不**執行階段 C/D/E（不提交、不推送、不開 PR）。
@@ -139,102 +140,151 @@ source_branch="$(git rev-parse --abbrev-ref HEAD)"
---
---
## 階段 B：依嚴重等級 逐條解決問題 或登記誤報
## 階段 B： 讀取問題（findings 檔或 Gitea 議題）、 依嚴重度 逐條解決或登記誤報
### B1. 讀取 findings 與 exclusions
新版 AI Code Review 的產出格式（對齊 ` https://gitea.jsc.idv.tw/actions/code-review`， src/index.js` / ` src/lib/review.js`）：
**B1-0. 定位 findings 來源**（依序判斷，決定要讀哪些 finding 檔） ： - **findings**：每次 review 在目錄 ` .gitea/ai-review/findings/ ` 產生一個**新檔**（檔名為台北時間戳，如 ` 2026-07-20-14:30:15.json `），內容是**頂層物件（wrapper）**，不是陣列 ：
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 陣列**，每筆是一個問題物件。常見欄位（不同產生器命名略有差異，需容錯對應）：
| 語義 | 可能欄位名 |
| --- | --- |
| 嚴重等級 | ` severity` / ` level` / ` 等級` |
| 檔案位置 | ` file` / ` path` / ` 檔案位置` |
| 所在行數 | ` line` / ` lines` / ` 所在行數` |
| 問題標題 | ` title` / ` message` / ` 問題` |
| 問題描述 | ` description` / ` detail` / ` 描述` |
| 修正建議 | ` suggestion` / ` fix` / ` 建議` |
` findings.json` 與 ` .gitea/ai-review/exclusions.json` 的 canonical 格式須對齊 ` https://gitea.jsc.idv.tw/actions/code-review`：
- 兩者都使用 **top-level JSON array**，不得包在 ` { "findings": [...] }`、` { "exclusions": [...] }` 或 ` { "excluded_findings": [...] }`。
- ` findings.json` 每筆至少保留 action 使用的必要欄位：
` ``json
` ``json
{
{
"level": "critical|warning|info ",
"generatedAt": "<台北時間> ",
"role": "審查角色名稱 ",
"commitSha": "<head sha> ",
"location": "檔案路徑:行號 或 檔案路徑" ,
"prNumber": 9 ,
"suggestion": "繁體中文（台灣用語）的具體修改建議"
"tool": { "name": "...", "version": "...", "model": "..." },
"findings": [ { "<finding>": "..." } ],
"excluded": [ { "<finding>": "..." } ]
}
}
` ``
` ``
- ` exclusions.json ` 每筆以最小且穩定的排除條目為主，優先保留原始問題文字、語言與語意；建議 欄位：
每個 ` <finding> ` 欄位：
| 欄位 | 語義 |
| --- | --- |
| ` id` | 流水號（` F001`…） |
| ` reviewer` | 審查角色名稱 |
| ` focus` | 審查面向代碼（如 ` logic`）
| ` badge` | 角色徽章（emoji，可空） |
| ` severity` | 嚴重等級（**中文**： 嚴重` / ` 警告` / ` 建議`）
| ` file` | 問題所在檔案（repo 相對路徑） |
| ` startLine` / ` endLine` | 問題起訖行號 |
| ` problem` | 問題描述 |
| ` suggestion` | 修改建議 |
| ` suggestedCode` | 建議寫法（程式碼，可空） |
- **exclusions**：固定 ` .gitea/ai-review/exclusions.json`，
` ``json
` ``json
{
{
"location": "檔案路徑:行號 或 檔案路徑 ",
"addedAt": "<台北時間> ",
"role": "審查角色名稱" ,
"prNumber": 9 ,
"original_finding": "原 finding 的 suggestion 或完整問題文字 ",
"reviewer": "<審查角色> ",
"reason": "判斷為誤報或不適用的原因"
"severity": "嚴重|警告|建議",
"file": "<檔案路徑>",
"startLine": 10,
"endLine": 12,
"problem": "<問題描述>",
"reason": "<判定誤報／重複的理由>"
}
}
` ``
` ``
若既有 exclusions 使用 ` suggestion `、` title `、` note ` 等欄位，讀取時可容錯；寫回時仍要維持 top-level array，並盡量採用上述 canonical 欄位 。
- **建問題模式**：某些 review 不寫 findings 檔，改開 Gitea 議題、把嚴重問題**逐則發成議題留言**（見 B0） 。
- **` findings.json ` 與 ` .gitea/ai-review/findings/ ` 目錄皆無可處理的 finding**（依 B1-0 判定：檔案不存在、內容為 ` [] ` 或空白，且 fallback 目錄不存在／無 ` *.json `／全部為空陣列）→ 視為「無問題待解決」，輸出告知。` --no-commit ` 時就此結束；否則**跳過階段 C 直接進入階段 D**（無待處理問題代表本 skill 未產生需要分類提交的修復變更） 。
> 本 skill 只支援上述**新版格式**；讀到非 wrapper 物件（例如舊版頂層陣列 findings）時，回報格式不符並停止，不臆測欄位 。
- **JSON 解析失敗** → 回報錯誤與檔案路徑並停止，不臆測內容、不亂改檔。
- ` exclusions.json` 不存在時視為空陣列，必要時建立 ` .gitea/ai-review/exclusions.json` 並寫入 ` []` 或新增後的排除項目。
### B0. 議題模式：從 Gitea 議題讀取問題（帶 ` --issue` 時）
- 若 ` exclusions.json` 是舊 wrapper 格式（例如 ` { "exclusions": [...] }` 或 ` { "excluded_findings": [...] }`），先正規化為 top-level array 再寫回。
帶 ` --issue <議題編號>` 時，**問題來源為該議題**（不讀 ` findings/` 目錄，除非同時明確帶 ` --findings`）：
1. 解析 repo 座標（同 E3，從 ` git remote get-url origin` 取 host／ ／ GITEA_TOKEN` 提供。
2. 讀議題本文與全部留言（分頁全取；輸出時遮蔽 token）：
` ``bash
curl -sS -H "Authorization: token ${GITEA_TOKEN}" \
"https://<host>/api/v1/repos/<owner>/<repo>/issues/<議題編號>"
curl -sS -H "Authorization: token ${GITEA_TOKEN}" \
"https://<host>/api/v1/repos/<owner>/<repo>/issues/<議題編號>/comments"
` ``
3. 解析每則符合「嚴重問題留言」格式（action ` severeCommentBody` 產出）的留言為一條 finding：
` ``
### <emoji> <severity>｜
**位置**： <file>` 第 <startLine>–
**問題**
<problem>
**修改建議**
<suggestion>
**建議寫法**（可選）
<suggestedCode>
` ``
逐則映射為 ` { reviewer, severity, file, startLine, endLine, problem, suggestion, suggestedCode }`，並記住來源留言 id（供 B5 回報）；議題標題／描述作為整體背景脈絡納入判斷。
4. 解析不到任何嚴重問題留言 → 回報並停止議題模式，不臆測。
5. 議題模式下沒有 findings 檔可更新；解析出的問題直接進入 B2/B3，處理結果於 B5 回寫議題（留言＋全解決時關閉），誤報仍寫入 ` exclusions.json`。
### B1. 讀取 findings 與 exclusions（檔案／目錄來源）
**未帶 ` --issue` 時**，依序定位 findings 來源：
1. **省略 ` --findings`**：讀目錄 ` .gitea/ai-review/findings/` 下所有 ` *.json`（含子目錄、依檔名排序）；每個檔皆為上述 **wrapper 物件**，取其 ` findings` 陣列合併為待處理清單。
2. **指定 ` --findings <路徑>`**：路徑為目錄則比照第 1 點；為單一檔則讀該檔（同為 wrapper 物件），取其 ` findings`。
3. **合併時逐筆記住各 finding 的來源檔路徑與其所屬 wrapper**，供 B4 逐檔就地寫回；此步不得更動任何來源檔。
4. **目錄不存在／無 ` *.json`／各檔 ` findings` 皆空** → 視為「無問題待解決」，輸出告知。` --no-commit` 時就此結束；否則**跳過階段 C 直接進入階段 D**。
5. **JSON 解析失敗或非 wrapper 物件** → 回報錯誤與檔案路徑並停止，不臆測、不亂改檔。
` exclusions.json` 不存在時視為空陣列（頂層陣列）；解析失敗或非陣列時回報，並在本次不寫入誤報（避免破壞既有內容、需人工確認）。
### B2. 依嚴重等級排序
### B2. 依嚴重等級排序
把所有 finding 依等級由高到低排序：**🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低 **。
把所有 finding 依等級由高到低排序：**🔴 嚴重 → 🟠 警告 → 🔵 建議 **。
canonical 等級為 ` critical ` / ` warning ` / ` info `；其他寫法容錯對應： ``/` blocker`→🔴、` high `/` major `/` warning `→🟠、` medium `/` moderate `→🟡、 ``/` minor`/` info ` →🔵；無法辨識的等級 **排在最後**並標註 「等級未知」。寫回 ` findings.json ` 時盡量保留原欄位值，除非需要修正成 canonical 格式 。
` severity ` 為中文 ` 嚴重 ` / ` 警告 ` / ` 建議 `；容錯對應：` 嚴重 `/ ``/` high `/` `→🔴、` 警告 `/` warning `/` major `→🟠、` 建議 `/` info `/ ``/` minor`→🔵；無法辨識者 **排在最後**並標「等級未知」。排序後先處理高等級 。
### B3. 逐條處理（高等級先）
### B3. 逐條處理（高等級先）
輸出一張「處理計畫」表，除非使用者要求確認或遇到必要決策，否則**依排序由上而下逐條**處理：
輸出一張「處理計畫」表，除非使用者要求確認或遇到必要決策，否則**依排序由上而下逐條**處理：
| # | 等級 | 問題 | 檔案位置 | 行數 | 處理方式 |
| # | 等級 | 審查員 | 問題 | 檔案 | 行數 | 處理方式 |
| --- | --- | --- | --- | --- | --- |
| --- | --- | --- | --- | --- | --- | --- |
對每一條 finding： 對每一條 finding：
1. 讀取對應檔案與其脈絡（依 ` file` / ` l ine`）。
1. 讀取對應檔案與其脈絡（依 ` file` 與 ` startLine `– endL ine`）。
2. 先判斷是否為誤報或不適用：例如程式碼脈絡證明指控不成立、已有等價防護、問題來自 action 已知排除規則 、CI/CD 必要權限、或 finding 對非本次變更做不合理要求。
2. 先判斷是否為誤報或不適用：例如程式碼脈絡證明指控不成立、已有等價防護、命中 ` exclusions.json ` 已知排除、CI/CD 必要權限、或 finding 對非本次變更做不合理要求。
3. **可判斷為誤報** → 不改程式碼；將排除條目 append 到 ` .gitea/ai-review/exclusions.json`，保留原始 finding 的語言與語意，避免過度改寫；若已有等價 exclusion（同檔案路徑、角色、原始文字或 suggestion 高度相似）則不要 重複新增。
3. **可判斷為誤報** → 不改程式碼；將排除條目 append 到 ` .gitea/ai-review/exclusions.json`（新版欄位，見 B4），保留原始問題文字與語意；若已有等價 exclusion（同 ` file `＋ reviewer `＋ problem ` 高度相似）則不重複新增。
4. **確認為真問題且可安全修復** → 依 ` suggestion`／ description ` 在程式碼中實作最小合理修正；建議含糊或與現況不符時，依原始碼脈絡做最小且合理的修正。
4. **確認為真問題且可安全修復** → 依 ` suggestion`／ suggestedCode `／ problem ` 在程式碼中實作最小合理修正；建議含糊或與現況不符時，依原始碼脈絡做最小且合理的修正。
5. **無法安全自動修復或無法確認真偽**（例如需求不明、牽涉設計取捨、檔案不存在）→ **不硬改**，標記為「待人工處理」並記錄原因，繼續下一條。
5. **無法安全自動修復或無法確認真偽**（例如需求不明、牽涉設計取捨、檔案不存在）→ **不硬改**，標記為「待人工處理」並記錄原因，繼續下一條。
6. 逐條完成後，記錄該條結果（✅ 已解決 / 🚫 誤報已寫入 exclusions / ⏭️ 待人工處理 + 原因）。
6. 逐條完成後，記錄該條結果（✅ 已解決 / 🚫 誤報已寫入 exclusions / ⏭️ 待人工處理 + 原因）；議題模式另記來源留言 id 。
> 一次只處理一條、修完再處理下一條，避免互相干擾；同檔多條問題可合併讀取但仍逐條套用修正。
> 一次只處理一條、修完再處理下一條，避免互相干擾；同檔多條問題可合併讀取但仍逐條套用修正。
### B4. 更新 findings.json 與 exclusions.json
### B4. 更新 findings 檔 與 exclusions.json（檔案／目錄來源）
**所有條目處理完畢後**， ` findings.json ` 與 ` exclusions.json ` ： **所有條目處理完畢後**依結果更新（ ） ：
- **只有確認已解決，或已確認為誤報並成功寫入 ` exclusions.json` 的 finding，才可從 ` findings.json ` 移除** 。
- **只有確認已解決，或已確認為誤報並成功寫入 ` exclusions.json` 的 finding，才可從來源 findings 檔移除**；待人工處理、無法確認真偽、修復未驗證成功者一律保留 。
- 誤報移出 ` findings.json ` 前，必須先確認 ` exclusions.json ` 已存在、格式合法、且該排除條目已寫入或已有等價條目；若 exclusions 寫入失敗，該 finding 必須保留 。
- **逐檔就地更新（wrapper 物件）**：依 B1 記錄的來源檔，把該檔 ` findings ` 陣列中要保留的 finding 留下、其餘移除，**只改該檔的 ` findings ` 陣列**； generatedAt `、` commitSha `、` prNumber `、` tool `、` excluded `）原樣保留，**不得**把多個來源檔合併成單一檔。某檔 ` findings ` 全數已解決／誤報時，把該檔的 ` findings ` 寫成 ` [] `（保留檔案與 wrapper、維持目錄結構，不刪檔） 。
- 待人工處理、無法確認真偽、或修復未驗證成功的 finding 必須保留在 ` fi ndings.json ` 。
- 保留的 finding 維持其原 wrapper 內欄位（` id `、` reviewer `、` severity `、` file `、` startLine `、` e ndL ine `、` problem `、` suggestion `、` suggestedCode `…）與排序 。
- 寫回 ` findings.json ` 時只保留尚未解決且尚未登記為誤報的 fi nding；已解決或已登記為誤報的 finding 逐項移除，不需要等待其他問題也處理完 。
- **誤報一律 append 到 ` .gitea/ai-review/exclusions.json `（頂層陣列）**，欄位對齊新版：` addedAt `（當下台北時間，` date ` 取得）、` prNumber `（已知則帶、未知可省略）、` reviewer `、` severity `、` file `、` startLine `、` e ndL ine `、` problem `、` reason `（誤報理由）；append 後去重 。
- 如果移除後沒有任何 finding 需要保留，將 ` findings.json ` 寫成空陣列：
- 誤報移出 findings 前，必須先確認 ` exclusions.json ` 已成功寫入該條或已有等價條目；寫入失敗則該 finding 保留於來源檔。
- 所有寫檔以 UTF-8（不含 BOM）寫入，結尾保留一個換行。
` ``json
### B5. 議題模式收尾：回寫議題（帶 ` --issue` 時）
[]
` ``
- 寫回 ` 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 `（不因來源是目錄而分檔 ）。
1. **在議題留言回報進度**（ POST /repos/<owner>/<repo>/issues/<編號>/comments `， ）。
- 寫回 ` exclusions.json` 時使用 top-level JSON array；新增項目 append 後依既有順序保留並去重。
2. **全部問題都已解決或已登記誤報**（無 ⏭️ 待人工處理）→ 關閉議題：
- 兩個檔案都以 UTF-8（不含 BOM）寫入，結尾保留一個換行。
` ``bash
curl -sS -X PATCH -H "Authorization: token ${GITEA_TOKEN}" \
-H "Content-Type: application/json" \
"https://<host>/api/v1/repos/<owner>/<repo>/issues/<議題編號>" \
--data '{"state":"closed"}'
` ``
3. **尚有待人工處理** → 只留言不關閉，於留言標明待處理項與原因。
4. 誤報仍寫入 ` exclusions.json`（同 B4），讓後續 review 沿用。
---
---
@@ -268,7 +318,7 @@ git ls-files --others --exclude-standard # 未追蹤檔
| ` revert` | 還原先前的提交 |
| ` revert` | 還原先前的提交 |
- **同一檔案橫跨多型** → 以該檔**主要異動性質**歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
- **同一檔案橫跨多型** → 以該檔**主要異動性質**歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
- **階段 B 修復產生的變更**：依其性質歸類（修 bug→` fix`、補功能→` feat`、改文件→` docs`…）。` findings.json `（或 ` ` 目錄下 ` *.json`）／ ` exclusions.json` 的問題狀態更新歸 ` chore`。
- **階段 B 修復產生的變更**：依其性質歸類（修 bug→` fix`、補功能→` feat`、改文件→` docs`…）。` .gitea/ai-review/ findings/` 目錄下 ` *.json`（ exclusions.json` 的問題狀態更新歸 ` chore`。
- **未追蹤新檔**：必須照實際內容歸入對應 type，必要時在提交前明確 ` git add -- <path>`，不可因為是新檔就略過。
- **未追蹤新檔**：必須照實際內容歸入對應 type，必要時在提交前明確 ` git add -- <path>`，不可因為是新檔就略過。
### C3. 產出提交計畫
### C3. 產出提交計畫
@@ -286,7 +336,7 @@ git ls-files --others --exclude-standard # 未追蹤檔
- ❌ 錯（只是重述 type，禁止）：` feat(新增功能)`、` fix(修正錯誤)`、` perf(優化效能)`、` docs(文件)`、` chore(雜項)`。
- ❌ 錯（只是重述 type，禁止）：` feat(新增功能)`、` fix(修正錯誤)`、` perf(優化效能)`、` docs(文件)`、` chore(雜項)`。
- 一組異動橫跨多個功能而無單一主體時，才退而取最貼近的上層範圍（例如多個 manifest → ` plugin 設定`）。
- 一組異動橫跨多個功能而無單一主體時，才退而取最貼近的上層範圍（例如多個 manifest → ` plugin 設定`）。
- ` 一句總結`：把這個 commit 內所有異動**總結成一句**繁體中文（簡短、聚焦做了什麼）。
- ` 一句總結`：把這個 commit 內所有異動**總結成一句**繁體中文（簡短、聚焦做了什麼）。
- 範例：` feat(使用者登入): 新增帳密登入與 token 簽發`、` fix(結帳流程): 修正空購物車導致的結帳例外`、` perf(物件查詢): 改用批次查詢降低 DB 往返`、` docs(README): 補上安裝與呼叫方式說明`、` chore(ai-review 狀態): 更新 findings.json 與 exclusions.json`。
- 範例：` feat(使用者登入): 新增帳密登入與 token 簽發`、` fix(結帳流程): 修正空購物車導致的結帳例外`、` perf(物件查詢): 改用批次查詢降低 DB 往返`、` docs(README): 補上安裝與呼叫方式說明`、` chore(ai-review 狀態): 更新 findings 與 exclusions.json`。
- **提交順序建議**： fix`/` feat` 等核心異動在前，` docs`/` style`/` chore` 在後（純屬建議，可依相依性調整）。
- **提交順序建議**： fix`/` feat` 等核心異動在前，` docs`/` style`/` chore` 在後（純屬建議，可依相依性調整）。
- **盤點要求**：提交計畫必須完整對應 C1 盤點出的所有變更項目，若有新檔或未追蹤檔，必須明確列入對應 commit，不能只根據 ` git diff` 下結論。
- **盤點要求**：提交計畫必須完整對應 C1 盤點出的所有變更項目，若有新檔或未追蹤檔，必須明確列入對應 commit，不能只根據 ` git diff` 下結論。
@@ -449,7 +499,7 @@ curl -sS -X POST \
各階段執行後輸出：
各階段執行後輸出：
- **階段 A**： - **階段 A**：
- **階段 B**：已解決 N 條（依等級分佈）、誤報寫入 exclusions M 條、待人工處理 K 條（列出原因）、` findings.json ` 保留／移除筆數與 `` 新增筆數；若無待處理問題，說明已跳過階段 C 直接進入階段 D。
- **階段 B**： 問題來源（findings 目錄或議題 ` #N `）、 已解決 N 條（依等級分佈）、誤報寫入 exclusions M 條、待人工處理 K 條（列出原因）、來源 findings 檔 保留／移除筆數與 `` 新增筆數；議題模式另報已在議題留言、是否關閉議題； 若無待處理問題，說明已跳過階段 C 直接進入階段 D。
- **階段 C**：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（` --no-commit` / 無變更）。
- **階段 C**：建立了哪幾個 commit（type＋訊息＋檔數），或為何略過（` --no-commit` / 無變更）。
- **階段 D**：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名；若無 commit 可 push，說明已跳過 push 直接進入階段 E。
- **階段 D**：push 成功與否、用了哪種方式（認證管理器／token／使用者指定），遠端分支名；若無 commit 可 push，說明已跳過 push 直接進入階段 E。
- **階段 E**：PR 連結／編號、目標分支、描述形式；並提醒已（或請使用者）清除對話內文以防 token 外洩。
- **階段 E**：PR 連結／編號、目標分支、描述形式；並提醒已（或請使用者）清除對話內文以防 token 外洩。
@@ -459,10 +509,10 @@ curl -sS -X POST \
## 呼叫方式
## 呼叫方式
格式：` [--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]` —
格式：` [--findings <路徑>] [--target <目標分支>] [--pr-desc <full|simple|自訂文字>] [--no-commit] [--no-pr] [--yes]` —
全部可省略（findings 預設 ` .gitea/ai-review/findings.json `，不存在或空時 fallback 目錄 ` .gitea/ai-review/findings/ ` ；目標分支省略時必問、不猜測）。token 一律由環境變數（如 ``）提供。
全部可省略（findings 預設讀目錄 ` .gitea/ai-review/findings/ ` 下所有 wrapper ` *.json `；帶 ` --issue <編號> ` 改由 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` |
| Claude Code / Antigravity | ` /jsc:code-review-resolve`，或 ` /jsc:code-review-resolve --target develop --pr-desc full --yes`、` /jsc:code-review-resolve --issue 12 --target master `、` /jsc:code-review-resolve --no-pr`、` /jsc:code-review-resolve --no-commit` |
| Codex | ` $code-review-resolve`，或 ` $code-review-resolve --target develop --pr-desc full --yes`，或用 ` /skills` 選單 |
| Codex | ` $code-review-resolve`，或 ` $code-review-resolve --target develop --pr-desc full --yes`、` $code-review-resolve --issue 12 --target master ` ，或用 `
| OpenCode | 描述需求（如「讀 .gitea/ai-review/findings.json 依嚴重度逐條處理，更新 findings/exclusions，把工作區變更依 conventional commit 分類提交，push 後對 develop 發 PR（完整版描述）」）自動觸發 |
| OpenCode | 描述需求（如「讀 .gitea/ai-review/findings/ 目錄下的 wrapper findings 依嚴重度逐條處理，更新 findings/exclusions，把工作區變更依 conventional commit 分類提交，push 後對 develop 發 PR（完整版描述）」；或「處理議題 #12 的 code review 問題」 ）自動觸發 |