code-review/TODO.md

開發階段 TODO

階段一：基本流程串接

• 目標：確保 action 可以被觸發，pipeline 各步驟依序執行，log 出每個主要階段的進入與完成。
• 驗收：log 中能看到每個階段（如「Step1: Pipeline 啟動」、「Step2: Findings 產生」、「Step3: Findings 合併」等）明確訊息，且流程能走完（即使還沒產生 findings）。
• 已驗收：code-review job 的 log 已完整出現 Step1 到 Step8，並以 Pipeline 完成 結束。

階段二：Git Diff 排除 .gitea/ 資料夾

• 目標：讀取 Git Diff 時排除 .gitea/ 資料夾內的所有檔案，以及 .amazonq/、.antigravity/、.claude/、.codex/、.gemini/、.github/、ANTIGRAVITY.md、CLAUDE.md、GEMINI.md、TODO.md、README.md，避免 AI 分析 workflow 設定、skill 入口與文件等非業務程式碼。
• 驗收：PR 中有上述路徑或檔案的變更時，diff 內容不包含該區塊，AI 分析結果不含這些路徑相關問題。
• 已驗收：app/gitea.js 已在取得 diff 時過濾 .gitea/ 區塊，且相關單元測試已覆蓋。

階段三：Findings 產生與合併

• 目標：各角色（style/security/performance/maintainability/testing）能產生 findings，並正確合併新舊 findings。
• 驗收：log 中能看到每個角色 findings 數量、合併後 findings 統計，並有「Step3 merged findings total=...」等訊息。
• 已驗收：log 已顯示 5 個角色皆有分析結果，並出現 Step3 merged findings total=... 與去重統計訊息。

階段四：AI 語意去重

• 目標：嘗試呼叫 LLM 進行 findings 語意去重，API 額度不足時要有降級處理 log。
• 驗收：log 中能看到 AI 去重: N -> M 筆 的成功訊息，或在失敗時出現 AI 去重失敗（...），降級：保留所有問題 之類的明確訊息。
• 已驗收：log 已出現 AI 去重: 13 -> 11 筆，且程式具備失敗時保留所有問題的降級處理。

階段五：AI 排除問題過濾

• 目標：讀取排除問題檔案（.gitea/ai-review/exclusions.json）時先去除重複條目、整理成語意群組摘要；若檔案不是頂層陣列格式，需主動修正成正確格式，再進行規則過濾並呼叫 AI 判斷剩餘問題是否為誤報或不適用，兩層過濾後產生最終問題清單。
• 驗收：log 中能看到排除問題檔案讀取成功或不存在的訊息、重複排除條目的整理摘要、格式修正訊息、規則過濾數量變化，以及「AI 誤報過濾: N -> M 筆」或降級訊息。
• 已驗收：app/findings.js 會先整理與去重 exclusions，再進行規則過濾與 AI 誤報過濾；若格式不是頂層陣列，會先修正為陣列後再繼續流程。
• 補充紀錄：當 排除過濾 後仍保留 findings 時，log 會出現 AI 誤報過濾: N -> M 筆；若 API 額度不足或回傳失敗，則會出現 AI 誤報過濾失敗（...），降級：保留所有問題。

階段六：findings 寫入與 comment 發布

• 目標：.gitea/ai-review/findings.json 正確寫入，comment 發布順序正確（舊問題→非嚴重→嚴重），每步有 log。
• 驗收：log 中能看到 .gitea/ai-review/findings.json 寫入、comment sync 的詳細訊息與順序。
• 已驗收：findings.json 會被正確寫入，且 comment 流程會依序嘗試舊問題、非嚴重新問題與嚴重新問題三段。
• 補充紀錄：當最終 findings 沒有對應類型時，會以 無舊問題，跳過、無新的非嚴重問題，跳過、無新的嚴重問題，跳過 的方式略過；若有問題，則會分別發布對應 comment。

階段七：階段六後驗證 JSON 格式

• 目標：階段六完成後驗證 findings.json 與 exclusions.json 是否為合法 JSON 格式，格式錯誤時先嘗試透過 AI 修正內容，再重新驗證；修正後仍不合法才 exit 1；之後才檢查檔案是否存在，不存在則建立並寫入 []。
• 驗收：log 中能看到兩個檔案的驗證結果（成功或失敗），格式錯誤時有 AI 修正嘗試與修正後再次驗證的訊息；若檔案不存在，會在驗證完成後看到建立並寫入 [] 的訊息；修正失敗時 workflow 狀態為失敗。
• 已驗收：log 已明確顯示 .gitea/ai-review/findings.json 與 .gitea/ai-review/exclusions.json 都是 JSON 格式正確。

階段八：記憶區 commit/push 與錯誤處理

• 目標：記憶區能成功 commit/push，且一併包含 triage-findings skill 與各平台入口檔；AGENTS.md、ANTIGRAVITY.md、CLAUDE.md、GEMINI.md 在目標專案已存在時會先做規則化合併，並在可用 LLM 時再做 AI 輔助檢查以避免遺失 skill、command 或規則；其餘同步檔則以來源覆蓋；workspace 沒有的同步檔則保留記憶區既有內容，不做刪除；錯誤時有明確 log，流程結束有總結訊息。
• 驗收：log 有「persisted findings」、「commit=...」、「push=...」等訊息，且能看出四個入口檔會先規則合併、再由 AI 輔助檢查，其他同步檔會被來源覆蓋；當 workspace 缺少某個同步檔時，記憶區中的對應檔案不會被刪除；錯誤時有「Runner failed: ...」等明確錯誤說明。
• 已驗收：commit/push 成功時會出現 persisted findings commit=... push=... review_outcome=...，且同步規則與缺檔不刪除的行為都有單元測試覆蓋。

階段九：阻擋嚴重問題 PR（第 8 點）

• 目標：如果 PR 問題表格中有嚴重（critical）問題，workflow 需直接 exit 1，不讓流程成功。
• 驗收：log 中能看到「critical 問題存在，workflow 結束（exit 1）」等明確訊息，且 workflow 狀態為失敗。
• 已驗收：app/main.js 會在 Step8 檢查 critical 數量，若大於 0 就直接 process.exit(1)；因此只要最終 findings 含有 critical，workflow 就會失敗。
• 補充紀錄：Step8 的退出訊息屬於預期行為，不代表 Step7 commit/push 失敗。

階段十：API Key 輪替

• 目標：所有平台的 API Key 支援逗號分隔傳入多個，隨機順序各嘗試一次，單一 Key 失敗時自動換下一個，全部失敗則 exit 1。
• 驗收：log 中能看到「key[N/M] 失敗」等訊息，換 key 後繼續執行；傳入單一 Key 時行為與原本相同；全部 Key 失敗時 log「所有 API Key 均失敗，終止流程」且 workflow 狀態為失敗。
• 已驗收：review.yaml 已以逗號串接多把 Gemini key，且 app/llm.js 與單元測試已覆蓋輪替與失敗退出行為。

階段十一：壓縮 AI 傳入內容減少 token 用量

• 目標：傳給 AI 的 findings 只保留必要欄位（level、role、location、suggestion）；system prompt 精簡為指令核心；exclusions hint 只傳 location 與 suggestion；AI 回傳後補回原始完整欄位（含 is_new）。
• 驗收：AI 呼叫的 payload 不含 is_new 等內部欄位，去重與誤報過濾後的 findings 仍保有完整欄位供後續流程使用。
• 已驗收：app/findings.js 已只傳必要欄位給 AI，並在回傳後補回原始 findings 的完整欄位。