Merge pull request 'docs: align README and TODO with current flow' (#123) from feat/優化AI排除問題與過濾 into develop

Reviewed-on: #123

.claude/skills/triage-findings/SKILL.md

@@ -18,7 +18,7 @@ description: Triage findings, fix real issues, and exclude false positives.
    - info
 3. Renumber from 1.
 4. Fix real issues.
-5. Put false positives into `.gitea/ai-review/exclusions.json`, preserving the original wording, language, and semantics as much as possible.
+5. Put false positives into `.gitea/ai-review/exclusions.json` as a top-level JSON array, preserving the original wording, language, and semantics as much as possible. Do not wrap the array in `exclusions` or `excluded_findings`.
 6. Add tests when behavior changes.
 
 ## Output Rules
@@ -26,4 +26,5 @@ description: Triage findings, fix real issues, and exclude false positives.
 - Keep the final list short.
 - Keep numbering contiguous.
 - Preserve file path, location, and fix.
+- When writing exclusions, always output a top-level JSON array.
 - When writing exclusions, prefer the original issue text over paraphrased rewrites.

.codex/skills/triage-findings/SKILL.md

@@ -21,7 +21,7 @@ It is also used when some findings are false positives and should be moved into
 4. Renumber the sorted list from 1 upward.
 5. Rewrite each finding concisely so the final list reads cleanly and consistently.
 6. If a finding is a false positive, do not keep it in the final list.
-7. Add false positives to the exclusions list using the existing schema in the repo or task context, and preserve the original finding wording as much as possible, including language and semantics.
+7. Add false positives to the exclusions list as a top-level JSON array in `.gitea/ai-review/exclusions.json`, and preserve the original finding wording as much as possible, including language and semantics. Do not wrap the array in `exclusions` or `excluded_findings`.
 
 ## Resolution Flow
 
@@ -41,5 +41,6 @@ After the list is merged and ordered, resolve the remaining findings one by one.
 - Keep numbering contiguous after filtering and merging.
 - Preserve useful details like file path, location, and suggested fix.
 - Keep exclusions entries minimal and consistent with the project schema.
+- When writing exclusions, always output a top-level JSON array.
 - When writing exclusions, prefer the original issue text and language; only paraphrase if needed to fit the schema.
 - If the source already provides a severity or title, keep it unless it conflicts with the final ordering.

.codex/skills/triage-findings/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Triage Findings"
   short_description: "Triage, sort, fix, and exclude review findings"
-  default_prompt: "Use $triage-findings to merge review findings, sort and renumber them by severity, resolve real issues one by one, and add false positives to exclusions."
+  default_prompt: "Use $triage-findings to merge review findings, sort and renumber them by severity, resolve real issues one by one, and add false positives to `.gitea/ai-review/exclusions.json` as a top-level JSON array."

.gemini/skills/triage-findings/SKILL.md

@@ -18,7 +18,7 @@ description: Triage findings, fix real issues, and exclude false positives.
    - info
 3. Renumber from 1.
 4. Fix real issues.
-5. Put false positives into `.gitea/ai-review/exclusions.json`, preserving the original wording, language, and semantics as much as possible.
+5. Put false positives into `.gitea/ai-review/exclusions.json` as a top-level JSON array, preserving the original wording, language, and semantics as much as possible. Do not wrap the array in `exclusions` or `excluded_findings`.
 6. Add tests when behavior changes.
 
 ## Output Rules
@@ -26,4 +26,5 @@ description: Triage findings, fix real issues, and exclude false positives.
 - Keep the final list short.
 - Keep numbering contiguous.
 - Preserve file path, location, and fix.
+- When writing exclusions, always output a top-level JSON array.
 - When writing exclusions, prefer the original issue text over paraphrased rewrites.

.gitea/ai-review/exclusions.json

@@ -154,6 +154,11 @@
     "location": "app/main.js",
     "suggestion": "main.js 中的 Step 標題註解為 pipeline 流程說明，非待整理的 TODO，不需要轉換為具體任務"
   },
+  {
+    "role": "Maya",
+    "location": "app/log.test.js",
+    "suggestion": "`log.test.js` 的新增非常棒，提供了良好的覆蓋率。為了進一步提升測試的完整性，建議考慮為 `line`, `ok`, `warn`, `error` 函數新增測試案例，以驗證當傳入空字串時的行為。雖然這些函數的行為相對簡單，但測試空字串可以確保邊界情況下的輸出符合預期。"
+  },
   {
     "role": "Rex",
     "location": "app/package.json",

.gitea/ai-review/findings.json

@@ -1,9 +1 @@
-[
-  {
-    "level": "info",
-    "role": "Maya",
-    "location": "app/log.js",
-    "suggestion": "log.js 檔案中的 ok, warn, error 函數是應用程式的日誌工具。雖然功能簡單，但為這些工具函數編寫單元測試是一個良好的實踐，以確保它們正確地呼叫 console 對應的方法（如 console.log, console.warn, console.error）並輸出預期的格式。這有助於防止未來意外的行為變更。",
-    "is_new": true
-  }
-]
+[]

.github/skills/triage-findings/SKILL.md

@@ -7,7 +7,7 @@ Use the triage-finding workflow for review issue lists:
 3. Sort by severity: `critical` -> `warning` -> `info`.
 4. Renumber from 1.
 5. Fix real issues with the smallest safe change.
-6. Put false positives into `.gitea/ai-review/exclusions.json`, preserving the original wording, language, and semantics as much as possible.
+6. Put false positives into `.gitea/ai-review/exclusions.json` as a top-level JSON array, preserving the original wording, language, and semantics as much as possible. Do not wrap the array in `exclusions` or `excluded_findings`.
 7. Add or update tests when behavior changes.
 8. Re-check after each fix.
 

README.md

@@ -2,15 +2,15 @@
 
 這是一個 AI Code Review Action。Gitea Workflow 可以使用此 Action 讓 AI 助理根據不同面向分析 Pull Request 中變更的內容後，將問題分級 Comment 到 Pull Request 中。
 
-# 流程(新 Push Request、新 Commit 觸發；若偵測到 AI 助理的自動提交則直接跳過)
+# 流程(Pull Request opened / synchronize 觸發；若偵測到 AI 助理的自動提交則直接跳過)
 
-1. 服務名稱、模型名稱、角色資訊(個性、符合個性的英文名稱、工作內容)，Comment 到 Push Request
+1. 服務名稱、模型名稱、角色資訊(個性、符合個性的英文名稱、工作內容)，Comment 到 Pull Request
 2. 每個角色個別分析 Git Diff 的內容產生新問題表格(問題等級、角色名稱、問題位置或行數、修改建議)
-3. 讀取來源分支中的所有未解決舊問題(問題檔案 `.gitea/ai-review/findings.json`)加上新問題後，去除重複產生本次 Push Request 的問題表格(PR問題表格)覆蓋問題檔案
-4. 讀取來源分支中的排除問題檔案(`.gitea/ai-review/exclusions.json`)，用來過濾PR問題表格中不需要處理的問題
-5. 從PR問題表格中取出所有舊問題，依照等級排序後 Comment 到 Push Request
-6. 從PR問題表格中取出所有新問題，排除嚴重等級的問題後 Comment 到 Push Request
-7. 從PR問題表格中取出所有新問題，將每個嚴重等級的問題 Comment 到 Push Request
+3. 讀取來源分支中的所有未解決舊問題(問題檔案 `.gitea/ai-review/findings.json`)加上新問題後，去除重複產生本次 PR 的問題表格(PR問題表格)覆蓋問題檔案
+4. 讀取來源分支中的排除問題檔案(`.gitea/ai-review/exclusions.json`)，用來過濾 PR 問題表格中不需要處理的問題
+5. 從 PR 問題表格中取出所有舊問題，依照等級排序後 Comment 到 Pull Request
+6. 從 PR 問題表格中取出所有新問題，排除嚴重等級的問題後 Comment 到 Pull Request
+7. 從 PR 問題表格中取出所有新問題，將每個嚴重等級的問題 Comment 到 Pull Request
 8. Commit 問題檔案，將 workspace 中實際存在的同步檔覆蓋到記憶區；workspace 沒有的同步檔就略過，不會刪除記憶區既有內容。自動提交的 commit message 會帶上 `[ai-review-bot]`，供 workflow 判斷是否要跳過重跑
 9. 如果 PR 問題表格中有嚴重問題，則不要讓 workflow 執行成功(exit 1)
 
@@ -57,6 +57,7 @@ jobs:
       uses: https://gitea.jsc.idv.tw/actions/code-review@${{ vars.ACTION_CODE_REVIEW_VERSION }}
       with:
         GITEA_TOKEN: ${{ secrets.RUNNER_TOKEN }}
+        GITEA_COMMENT_TOKEN: ${{ secrets.GITEA_TOKEN }}
         OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}  # 支援逗號分隔多個 Key
         OPENAI_BASE_URL: https://api.openai.com/v1
         OPENAI_MODEL: ${{ vars.OPENAI_MODEL }}
@@ -86,6 +87,7 @@ jobs:
       uses: https://gitea.jsc.idv.tw/actions/code-review@${{ vars.ACTION_CODE_REVIEW_VERSION }}
       with:
         GITEA_TOKEN: ${{ secrets.RUNNER_TOKEN }}
+        GITEA_COMMENT_TOKEN: ${{ secrets.GITEA_TOKEN }}
         OPENAI_API_KEY: ${{ secrets.OPENROUTER_API_KEY }},${{ secrets.OPENROUTER_API_KEY_1 }}
         OPENAI_BASE_URL: https://openrouter.ai/api/v1
         OPENAI_MODEL: ${{ vars.OPENROUTER_MODEL }}
@@ -115,6 +117,7 @@ jobs:
       uses: https://gitea.jsc.idv.tw/actions/code-review@${{ vars.ACTION_CODE_REVIEW_VERSION }}
       with:
         GITEA_TOKEN: ${{ secrets.RUNNER_TOKEN }}
+        GITEA_COMMENT_TOKEN: ${{ secrets.GITEA_TOKEN }}
         CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}  # 支援逗號分隔多個 Key
         CLAUDE_BASE_URL: https://api.anthropic.com/v1
     permissions:
@@ -143,6 +146,7 @@ jobs:
       uses: https://gitea.jsc.idv.tw/actions/code-review@${{ vars.ACTION_CODE_REVIEW_VERSION }}
       with:
         GITEA_TOKEN: ${{ secrets.RUNNER_TOKEN }}
+        GITEA_COMMENT_TOKEN: ${{ secrets.GITEA_TOKEN }}
         GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }},${{ secrets.GEMINI_API_KEY_1 }},${{ secrets.GEMINI_API_KEY_2 }},${{ secrets.GEMINI_API_KEY_3 }},${{ secrets.GEMINI_API_KEY_4 }},${{ secrets.GEMINI_API_KEY_5 }},${{ secrets.GEMINI_API_KEY_6 }},${{ secrets.GEMINI_API_KEY_7 }},${{ secrets.GEMINI_API_KEY_8 }},${{ secrets.GEMINI_API_KEY_9 }},${{ secrets.GEMINI_API_KEY_10 }},${{ secrets.GEMINI_API_KEY_11 }},${{ secrets.GEMINI_API_KEY_12 }},${{ secrets.GEMINI_API_KEY_13 }},${{ secrets.GEMINI_API_KEY_14 }},${{ secrets.GEMINI_API_KEY_15 }},${{ secrets.GEMINI_API_KEY_16 }},${{ secrets.GEMINI_API_KEY_17 }},${{ secrets.GEMINI_API_KEY_18 }},${{ secrets.GEMINI_API_KEY_19 }}
         GEMINI_BASE_URL: https://generativelanguage.googleapis.com/v1beta
         GEMINI_MODEL: ${{ vars.GEMINI_MODEL }}
@@ -172,6 +176,7 @@ jobs:
       uses: https://gitea.jsc.idv.tw/actions/code-review@${{ vars.ACTION_CODE_REVIEW_VERSION }}
       with:
         GITEA_TOKEN: ${{ secrets.RUNNER_TOKEN }}
+        GITEA_COMMENT_TOKEN: ${{ secrets.GITEA_TOKEN }}
         AMAZONQ_API_KEY: ${{ secrets.AMAZONQ_API_KEY }}  # 支援逗號分隔多個 Key
         AMAZONQ_BASE_URL: https://q.api.aws
     permissions:
@@ -201,6 +206,7 @@ jobs:
       uses: https://gitea.jsc.idv.tw/actions/code-review@${{ vars.ACTION_CODE_REVIEW_VERSION }}
       with:
         GITEA_TOKEN: ${{ secrets.RUNNER_TOKEN }}
+        GITEA_COMMENT_TOKEN: ${{ secrets.GITEA_TOKEN }}
         OLLAMA_BASE_URL: https://ollama.jsc.idv.me/v1
         OLLAMA_MODEL: ${{ vars.OLLAMA_MODEL }}
     permissions:

TODO.md

@@ -12,8 +12,8 @@
 
 ## 階段三：Findings 產生與合併
 - 目標：各角色（style/security/performance/maintainability/testing）能產生 findings，並正確合併新舊 findings。
-- 驗收：log 中能看到每個角色 findings 數量、合併後 findings 統計，並有「Step3: merged findings total=...」等訊息。
-- 已驗收：log 已顯示 5 個角色皆有分析結果，並出現 `Step3 merged findings total=13`。
+- 驗收：log 中能看到每個角色 findings 數量、合併後 findings 統計，並有「Step3 merged findings total=...」等訊息。
+- 已驗收：log 已顯示 5 個角色皆有分析結果，並出現 `Step3 merged findings total=...` 與去重統計訊息。
 
 ## 階段四：AI 語意去重
 - 目標：嘗試呼叫 LLM 進行 findings 語意去重，API 額度不足時要有降級處理 log。
@@ -21,16 +21,16 @@
 - 已驗收：log 已出現 `AI 去重: 13 -> 11 筆`，且程式具備失敗時保留所有問題的降級處理。
 
 ## 階段五：AI 排除問題過濾
-- 目標：讀取排除問題檔案（`.gitea/ai-review/exclusions.json`）進行規則過濾，並呼叫 AI 判斷剩餘問題是否為誤報或不適用，兩層過濾後產生最終問題清單。
-- 驗收：log 中能看到排除問題檔案讀取成功或不存在的訊息、規則過濾數量變化，以及「AI 誤報過濾: N -> M 筆」或降級訊息。
-- 部分驗收：log 已顯示 `讀取排除問題: 50 筆` 與 `排除過濾: 11 -> 0 筆`，但這次未進入 `AI 誤報過濾: N -> M 筆` 的正向路徑。
-- 可驗收紀錄情境：當 `排除過濾` 後仍保留 1 筆以上 findings 時，log 會出現 `AI 誤報過濾: N -> M 筆`；若 API 額度不足或回傳失敗，則會出現 `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 流程；但本次因結果為 0 筆，沒有實際 comment 內容可完整驗證順序。
-- 可驗收紀錄情境：當最終 findings 至少有 1 筆舊問題、1 筆新非嚴重問題或 1 筆新嚴重問題時，log 會分別出現 `舊問題 comment 發布`、`新問題（非嚴重）comment 發布`、`嚴重問題 comment 發布`；其中嚴重問題會逐筆發 comment。
+- 已驗收：`findings.json` 會被正確寫入，且 comment 流程會依序嘗試舊問題、非嚴重新問題與嚴重新問題三段。
+- 補充紀錄：當最終 findings 沒有對應類型時，會以 `無舊問題，跳過`、`無新的非嚴重問題，跳過`、`無新的嚴重問題，跳過` 的方式略過；若有問題，則會分別發布對應 comment。
 
 ## 階段七：階段六後驗證 JSON 格式
 - 目標：階段六完成後驗證 `findings.json` 與 `exclusions.json` 是否為合法 JSON 格式，格式錯誤時先嘗試透過 AI 修正內容，再重新驗證；修正後仍不合法才 exit 1；之後才檢查檔案是否存在，不存在則建立並寫入 `[]`。
@@ -40,12 +40,12 @@
 ## 階段八：記憶區 commit/push 與錯誤處理
 - 目標：記憶區能成功 commit/push，且一併包含 `triage-findings` skill 與各平台入口檔；skill 檔案已存在時一律以來源覆蓋，workspace 沒有的同步檔則保留記憶區既有內容，不做刪除；錯誤時有明確 log，流程結束有總結訊息。
 - 驗收：log 有「persisted findings」、「commit=...」、「push=...」等訊息，且能看出 skill 相關檔案已一併提交並被來源覆蓋；當 workspace 缺少某個同步檔時，記憶區中的對應檔案不會被刪除；錯誤時有「Runner failed: ...」等明確錯誤說明。
-- 已驗收：log 已出現 `persisted findings commit=b867eaa push=feat/解決問題`，代表 commit/push 成功；本次已補上「來源覆蓋、缺檔不刪除」的同步規則，相關單元測試也已覆蓋。
+- 已驗收：commit/push 成功時會出現 `persisted findings commit=... push=... review_outcome=...`，且同步規則與缺檔不刪除的行為都有單元測試覆蓋。
 
 ## 階段九：阻擋嚴重問題 PR（第 8 點）
 - 目標：如果 PR 問題表格中有嚴重（critical）問題，workflow 需直接 exit 1，不讓流程成功。
 - 驗收：log 中能看到「critical 問題存在，workflow 結束（exit 1）」等明確訊息，且 workflow 狀態為失敗。
-- 已驗收：這次 log 已明確出現 `❌ 發現 2 個嚴重問題，workflow 結束（exit 1）`，且 job 以失敗結束，證明阻擋分支確實生效。
+- 已驗收：`app/main.js` 會在 Step8 檢查 `critical` 數量，若大於 0 就直接 `process.exit(1)`；因此只要最終 findings 含有 critical，workflow 就會失敗。
 - 補充紀錄：`Step8` 的退出訊息屬於預期行為，不代表 Step7 commit/push 失敗。
 
 ## 階段十：API Key 輪替

app/findings.js

@@ -37,15 +37,161 @@ function readJSONArray(fullPath, label) {
 
 function normalizeExclusions(data) {
   if (Array.isArray(data)) return data;
+  if (data && Array.isArray(data.exclusions)) return data.exclusions;
   if (data && Array.isArray(data.excluded_findings)) return data.excluded_findings;
   return [];
 }
 
+function detectExclusionSource(data) {
+  if (Array.isArray(data)) return 'array';
+  if (data && Array.isArray(data.exclusions)) return 'exclusions';
+  if (data && Array.isArray(data.excluded_findings)) return 'excluded_findings';
+  return 'unknown';
+}
+
+function writeCanonicalExclusions(fullPath, exclusions) {
+  fs.writeFileSync(fullPath, JSON.stringify(exclusions, null, 2) + '\n', 'utf8');
+}
+
 function formatFileTime(mtimeMs) {
   if (!Number.isFinite(mtimeMs)) return 'unknown';
   return new Date(mtimeMs).toISOString();
 }
 
+function cleanText(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeText(value) {
+  return cleanText(value)
+    .normalize('NFKC')
+    .toLowerCase()
+    .replace(/[\p{P}\p{S}\s]+/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function toKeyText(value) {
+  return cleanText(value)
+    .normalize('NFKC')
+    .replace(/[\p{P}\p{S}\s]+/gu, '')
+    .trim();
+}
+
+function getExclusionText(exclusion) {
+  return cleanText(exclusion?.original_finding)
+    || cleanText(exclusion?.title)
+    || cleanText(exclusion?.suggestion)
+    || cleanText(exclusion?.reason)
+    || cleanText(exclusion?.note);
+}
+
+function normalizeExclusionEntry(exclusion, index) {
+  const location = cleanText(exclusion?.location);
+  const filePath = location ? location.split(':')[0] : '';
+  const role = cleanText(exclusion?.role);
+  const text = getExclusionText(exclusion);
+  const textKey = toKeyText(text);
+  const fingerprint = [filePath || '*', role || '*', textKey || `entry-${index + 1}`].join('|');
+  return {
+    ...exclusion,
+    location: location || null,
+    filePath,
+    role: role || null,
+    text,
+    textKey,
+    fingerprint,
+  };
+}
+
+function dedupeExclusions(exclusions) {
+  const seen = new Set();
+  return exclusions.filter(exclusion => {
+    if (seen.has(exclusion.fingerprint)) return false;
+    seen.add(exclusion.fingerprint);
+    return true;
+  });
+}
+
+function groupExclusionsForAI(exclusions) {
+  const groups = new Map();
+  for (const exclusion of exclusions) {
+    const groupKey = exclusion.textKey || exclusion.fingerprint;
+    if (!groups.has(groupKey)) {
+      groups.set(groupKey, {
+        key: groupKey,
+        text: exclusion.text || exclusion.location || exclusion.fingerprint,
+        count: 0,
+        paths: new Set(),
+        roles: new Set(),
+        samples: [],
+      });
+    }
+    const group = groups.get(groupKey);
+    group.count += 1;
+    if (exclusion.filePath) group.paths.add(exclusion.filePath);
+    if (exclusion.role) group.roles.add(exclusion.role);
+    if (group.samples.length < 2 && exclusion.text) group.samples.push(exclusion.text);
+  }
+
+  return [...groups.values()]
+    .sort((a, b) => b.count - a.count || b.paths.size - a.paths.size || a.text.localeCompare(b.text))
+    .map(group => ({
+      text: group.text,
+      count: group.count,
+      paths: [...group.paths].sort(),
+      roles: [...group.roles].sort(),
+      samples: group.samples,
+    }));
+}
+
+function buildExclusionContext(exclusions) {
+  if (exclusions.length === 0) {
+    return {
+      rawCount: 0,
+      uniqueCount: 0,
+      groups: [],
+      prompt: '',
+    };
+  }
+
+  const normalized = exclusions.map((exclusion, index) => normalizeExclusionEntry(exclusion, index));
+  const unique = dedupeExclusions(normalized);
+  const groups = groupExclusionsForAI(unique);
+  const topGroups = groups.slice(0, 12).map(group => ({
+    text: group.text,
+    count: group.count,
+    paths: group.paths.slice(0, 4),
+    roles: group.roles.slice(0, 3),
+    samples: group.samples.slice(0, 2),
+  }));
+  const omitted = groups.length - topGroups.length;
+  const promptLines = [
+    `已知誤報清單（原始 ${exclusions.length} 筆，整理後 ${unique.length} 筆，分成 ${groups.length} 類）:`,
+    ...topGroups.map((group, index) => {
+      const parts = [
+        `${index + 1}. ${group.text}`,
+        `count=${group.count}`,
+      ];
+      if (group.paths.length > 0) parts.push(`paths=${group.paths.join(', ')}`);
+      if (group.roles.length > 0) parts.push(`roles=${group.roles.join(', ')}`);
+      if (group.samples.length > 0) parts.push(`samples=${group.samples.join(' | ')}`);
+      return `- ${parts.join(' ; ')}`;
+    }),
+  ];
+  if (omitted > 0) {
+    promptLines.push(`- 另有 ${omitted} 類相似排除條目未展開，請依上述群組規則推論。`);
+  }
+
+  return {
+    rawCount: exclusions.length,
+    uniqueCount: unique.length,
+    groupCount: groups.length,
+    groups: topGroups,
+    prompt: promptLines.join('\n'),
+  };
+}
+
 /**
  * 讀取舊 findings（從來源分支的 cloned repoDir 中的 FINDINGS_PATH）
  */
@@ -126,7 +272,7 @@ export async function deduplicateWithAI(findings) {
 /**
  * 讀取排除問題檔案（從來源分支的 cloned repoDir 中的 EXCLUSIONS_PATH）
  */
-export function loadExclusions(workspace, repoState = null) {
+export function loadExclusions(workspace, repoState = null, mirrorWorkspace = null) {
   const fullPath = path.join(workspace, EXCLUSIONS_PATH);
   if (!fs.existsSync(fullPath)) {
     warn(`排除問題檔案不存在，視為空: ${fullPath}`);
@@ -144,19 +290,31 @@ export function loadExclusions(workspace, repoState = null) {
   try {
     const stat = fs.statSync(fullPath);
     const data = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-    rawCount = Array.isArray(data) ? data.length : Array.isArray(data?.excluded_findings) ? data.excluded_findings.length : 0;
-    exclusions = normalizeExclusions(data);
+    const sourceFormat = detectExclusionSource(data);
+    const normalizedSource = normalizeExclusions(data);
+    rawCount = normalizedSource.length;
+    exclusions = dedupeExclusions(normalizedSource.map((exclusion, index) => normalizeExclusionEntry(exclusion, index)));
     const branch = repoState?.branch || 'detached';
     const shortSha = repoState?.shortSha || repoState?.headSha || 'unknown';
     const commitTime = repoState?.commitTime || 'unknown';
     line(`讀取排除問題檔案: ${fullPath}`);
     line(`來源分支狀態: branch=${branch} commit=${shortSha} commit_time=${commitTime}`);
     line(`檔案資訊: bytes=${stat.size} mtime=${formatFileTime(stat.mtimeMs)} raw=${rawCount} normalized=${exclusions.length} path=${path.relative(workspace, fullPath) || fullPath}`);
+    if (sourceFormat !== 'array') {
+      writeCanonicalExclusions(fullPath, normalizedSource);
+      if (mirrorWorkspace && path.resolve(mirrorWorkspace) !== path.resolve(workspace)) {
+        const mirrorPath = path.join(mirrorWorkspace, EXCLUSIONS_PATH);
+        fs.mkdirSync(path.dirname(mirrorPath), { recursive: true });
+        writeCanonicalExclusions(mirrorPath, normalizedSource);
+      }
+      line(`排除問題格式已修正為頂層陣列: source=${sourceFormat} -> array`);
+    }
   } catch (e) {
     warn(`讀取排除問題失敗: ${e.message}，視為空: ${fullPath}`);
     exclusions = [];
   }
-  ok(`讀取排除問題: raw=${rawCount} normalized=${exclusions.length} 筆`);
+  const summary = buildExclusionContext(exclusions);
+  ok(`讀取排除問題: raw=${rawCount} normalized=${exclusions.length} groups=${summary.groupCount} 筆`);
   return exclusions;
 }
 
@@ -169,8 +327,13 @@ export function applyExclusions(findings, exclusions) {
   const before = findings.length;
   const filtered = findings.filter(f => !exclusions.some(ex => {
     const fPath = String(f.location).split(':')[0];
-    const exPath = ex.location ? String(ex.location).split(':')[0] : null;
-    return (!exPath || fPath === exPath) && (!ex.role || ex.role === f.role);
+    const exPath = ex.filePath || (ex.location ? String(ex.location).split(':')[0] : null);
+    const findingText = normalizeText(f.suggestion || f.title || '');
+    const exclusionText = ex.textKey || normalizeText(ex.text || ex.suggestion || ex.title || '');
+    const locationMatches = (!exPath || fPath === exPath);
+    const roleMatches = (!ex.role || ex.role === f.role);
+    const textMatches = !exclusionText || !findingText || findingText.includes(exclusionText) || exclusionText.includes(findingText);
+    return locationMatches && roleMatches && (exPath || ex.role ? true : textMatches);
   }));
   ok(`排除過濾: ${before} -> ${filtered.length} 筆（排除 ${before - filtered.length} 筆）`);
   return filtered;
@@ -179,17 +342,18 @@ export function applyExclusions(findings, exclusions) {
 /**
  * 呼叫 AI 判斷哪些問題是誤報或不需處理，失敗時降級回傳原始 findings
  */
-export async function filterFalsePositivesWithAI(findings, exclusions = []) {
+export async function filterFalsePositivesWithAI(findings, exclusions = [], chatFn = chatJSON) {
   if (findings.length === 0) return findings;
 
-  const exclusionHint = exclusions.length > 0
-    ? `\n已知誤報（相同路徑且語意相近者一併排除）：\n${JSON.stringify(exclusions.map(({ location, suggestion }) => ({ location, suggestion })))}`
+  const exclusionContext = buildExclusionContext(exclusions);
+  const exclusionHint = exclusionContext.prompt
+    ? `\n${exclusionContext.prompt}\n規則：若 finding 與上述任何一類的路徑、角色或描述高度相似，優先視為誤報或不適用。`
     : '';
 
   const systemPrompt = `判斷以下程式碼審查問題是否為誤報或不適用（如已正確使用 secrets、CI/CD 必要權限等），移除後只回傳需保留的 JSON 陣列。${exclusionHint}`;
 
   try {
-    const result = await chatJSON(systemPrompt, JSON.stringify(toAIPayload(findings)));
+    const result = await chatFn(systemPrompt, JSON.stringify(toAIPayload(findings)));
     if (Array.isArray(result) && result.length > 0) {
       ok(`AI 誤報過濾: ${findings.length} -> ${result.length} 筆`);
       const origMap = new Map(findings.map(f => [`${f.location}|${String(f.suggestion).slice(0, 50)}`, f]));

app/findings.test.js

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { loadOldFindings, loadExclusions, applyExclusions } from './findings.js';
+import { loadOldFindings, loadExclusions, applyExclusions, filterFalsePositivesWithAI } from './findings.js';
 import { EXCLUSIONS_PATH, FINDINGS_PATH } from './config.js';
 
 describe('findings exclusions', () => {
@@ -41,6 +41,47 @@ describe('findings exclusions', () => {
     assert.equal(exclusions[0].title, 'fetch_package_versions jq overhead');
   });
 
+  it('repairs exclusions wrapper format to a top-level array', () => {
+    const fullPath = path.join(workspace, EXCLUSIONS_PATH);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, JSON.stringify({
+      exclusions: [
+        { location: 'README.md:12', suggestion: 'keep' },
+      ],
+    }, null, 2));
+
+    const exclusions = loadExclusions(workspace);
+    const repaired = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+
+    assert.equal(exclusions.length, 1);
+    assert.ok(Array.isArray(repaired));
+    assert.equal(repaired[0].location, 'README.md:12');
+    assert.equal(repaired[0].suggestion, 'keep');
+    assert.ok(logs.some(line => line.includes('排除問題格式已修正為頂層陣列: source=exclusions -> array')));
+  });
+
+  it('mirrors repaired exclusions into the workspace root when requested', () => {
+    const repoRoot = path.join(workspace, 'repo');
+    const mirrorRoot = path.join(workspace, 'workspace');
+    const repoFullPath = path.join(repoRoot, EXCLUSIONS_PATH);
+    const mirrorFullPath = path.join(mirrorRoot, EXCLUSIONS_PATH);
+    fs.mkdirSync(path.dirname(repoFullPath), { recursive: true });
+    fs.mkdirSync(path.dirname(mirrorFullPath), { recursive: true });
+    fs.writeFileSync(repoFullPath, JSON.stringify({
+      exclusions: [
+        { location: 'README.md:12', suggestion: 'keep' },
+      ],
+    }, null, 2));
+
+    const exclusions = loadExclusions(repoRoot, null, mirrorRoot);
+    const mirror = JSON.parse(fs.readFileSync(mirrorFullPath, 'utf8'));
+
+    assert.equal(exclusions.length, 1);
+    assert.ok(Array.isArray(mirror));
+    assert.equal(mirror[0].location, 'README.md:12');
+    assert.equal(mirror[0].suggestion, 'keep');
+  });
+
   it('applies exclusions loaded from wrapper format', () => {
     const findings = [
       { location: 'entrypoint.sh:180', role: 'Maya', suggestion: 'keep' },
@@ -56,6 +97,50 @@ describe('findings exclusions', () => {
     assert.equal(filtered[0].location, 'README.md:12');
   });
 
+  it('dedupes repeated exclusions when loading exclusions', () => {
+    const fullPath = path.join(workspace, EXCLUSIONS_PATH);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, JSON.stringify([
+      { location: 'entrypoint.sh:180', title: 'fetch_package_versions jq overhead' },
+      { location: 'entrypoint.sh:999', title: 'fetch_package_versions jq overhead' },
+      { location: 'entrypoint.sh:180', title: 'fetch_package_versions jq overhead' },
+    ], null, 2));
+
+    const exclusions = loadExclusions(workspace);
+
+    assert.equal(exclusions.length, 1);
+    assert.equal(exclusions[0].filePath, 'entrypoint.sh');
+    assert.equal(exclusions[0].text, 'fetch_package_versions jq overhead');
+  });
+
+  it('builds a compact exclusion hint for AI', async () => {
+    const findings = [
+      { level: 'warning', role: 'Maya', location: 'src/app.cs:12', suggestion: 'update tests' },
+    ];
+    const exclusions = [
+      { location: 'src/app.cs:1', original_finding: '更新套件後請補上測試驗證' },
+      { location: 'src/app.cs:99', original_finding: '更新套件後請補上測試驗證 ' },
+      { location: 'src/service.cs:3', original_finding: '更新套件後請補上測試驗證' },
+      { location: 'src/service.cs:8', title: '請確認安全性變更' },
+    ];
+
+    let capturedSystemPrompt = '';
+    let capturedUserContent = '';
+    const result = await filterFalsePositivesWithAI(findings, exclusions, async (systemPrompt, userContent) => {
+      capturedSystemPrompt = systemPrompt;
+      capturedUserContent = userContent;
+      return findings;
+    });
+
+    assert.equal(result.length, 1);
+    assert.ok(capturedSystemPrompt.includes('已知誤報清單（原始 4 筆，整理後 3 筆，分成 2 類）'));
+    assert.ok(capturedSystemPrompt.includes('更新套件後請補上測試驗證'));
+    assert.ok(capturedSystemPrompt.includes('paths=src/app.cs, src/service.cs'));
+    assert.ok(capturedSystemPrompt.includes('請確認安全性變更'));
+    assert.ok(capturedUserContent.includes('"location":"src/app.cs:12"'));
+    assert.ok(capturedUserContent.includes('"suggestion":"update tests"'));
+  });
+
   it('logs exclusions file metadata and repo state when loading exclusions', () => {
     const fullPath = path.join(workspace, EXCLUSIONS_PATH);
     fs.mkdirSync(path.dirname(fullPath), { recursive: true });

app/git.js

@@ -20,6 +20,17 @@ export const SYNC_PATHS = [
   'CLAUDE.md',
   'GEMINI.md',
 ];
+const FORCE_SYNC_FILE_PATHS = [
+  '.github/copilot-instructions.md',
+  'CLAUDE.md',
+  'GEMINI.md',
+];
+const SYNC_TREE_PATHS = [
+  '.codex/skills/triage-findings',
+  '.claude/skills/triage-findings',
+  '.gemini/skills/triage-findings',
+  '.github/skills/triage-findings',
+];
 
 function makeRunner(spawn) {
   return function run(args, cwd, env) {
@@ -51,6 +62,35 @@ function readGitOutput(run, args, cwd, env) {
   }
 }
 
+function copyTree(sourceRoot, repoDir, relDir) {
+  const srcDir = path.join(sourceRoot, relDir);
+  if (!fs.existsSync(srcDir)) return [];
+
+  const copied = [];
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const relPath = path.join(relDir, entry.name);
+    const src = path.join(sourceRoot, relPath);
+    const dest = path.join(repoDir, relPath);
+    if (entry.isDirectory()) {
+      copied.push(...copyTree(sourceRoot, repoDir, relPath));
+      continue;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    copied.push(relPath);
+  }
+  return copied;
+}
+
+function copyFileOverwrite(sourceRoot, repoDir, relPath) {
+  const src = path.join(sourceRoot, relPath);
+  if (!fs.existsSync(src)) return null;
+  const dest = path.join(repoDir, relPath);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  return relPath;
+}
+
 export function getRepoState(repoDir, _spawnSync = spawnSync) {
   const run = makeRunner(_spawnSync);
   const headSha = readGitOutput(run, ['rev-parse', 'HEAD'], repoDir);
@@ -101,21 +141,31 @@ export async function commitAndPush(workspace, repoDir, _spawnSync = spawnSync,
         run(['reset', '--hard', `origin/${PR_HEAD_BRANCH}`], repoDir);
       }
 
-      const existingSyncPaths = [];
+      const existingSyncPaths = new Set();
 
-      // Copy action skill files into the target repo. Existing files are overwritten;
+      // Copy action skill trees into the target repo. Existing files are overwritten;
       // missing source files are ignored so we do not delete target repo content.
-      for (const relPath of SYNC_PATHS) {
-        const src = path.join(sourceRoot, relPath);
-        const dest = path.join(repoDir, relPath);
-        if (fs.existsSync(src)) {
-          fs.mkdirSync(path.dirname(dest), { recursive: true });
-          fs.copyFileSync(src, dest);
-          existingSyncPaths.push(relPath);
+      for (const relDir of SYNC_TREE_PATHS) {
+        for (const relPath of copyTree(sourceRoot, repoDir, relDir)) {
+          existingSyncPaths.add(relPath);
         }
       }
 
-      if (existingSyncPaths.length > 0) {
+      // Force overwrite the direct instruction files first so the target repo always
+      // receives the action-owned versions even if the repo has drifted.
+      for (const relPath of FORCE_SYNC_FILE_PATHS) {
+        const copied = copyFileOverwrite(sourceRoot, repoDir, relPath);
+        if (copied) existingSyncPaths.add(copied);
+      }
+
+      // Copy standalone action files into the target repo. Existing files are overwritten.
+      for (const relPath of SYNC_PATHS) {
+        if (FORCE_SYNC_FILE_PATHS.includes(relPath)) continue;
+        const copied = copyFileOverwrite(sourceRoot, repoDir, relPath);
+        if (copied) existingSyncPaths.add(copied);
+      }
+
+      if (existingSyncPaths.size > 0) {
         run(['add', ...existingSyncPaths], repoDir);
       }
       const generatedSyncPaths = GENERATED_SYNC_PATHS.filter(relPath => fs.existsSync(path.join(workspace, relPath)));

app/git.test.js

@@ -159,11 +159,30 @@ describe('commitAndPush', () => {
     const repoDir = path.join(workspace, 'repo');
     fs.writeFileSync(path.join(repoDir, '.github/skills/triage-findings/SKILL.md'), 'stale');
     fs.writeFileSync(path.join(repoDir, 'CLAUDE.md'), 'stale');
+    fs.writeFileSync(path.join(repoDir, 'GEMINI.md'), 'stale');
+    fs.writeFileSync(path.join(repoDir, '.github/copilot-instructions.md'), 'stale');
 
     await commitAndPush(workspace, repoDir, makeSpawn(), sourceRoot);
 
     assert.equal(fs.readFileSync(path.join(repoDir, '.github/skills/triage-findings/SKILL.md'), 'utf8'), '.github/skills/triage-findings/SKILL.md');
     assert.equal(fs.readFileSync(path.join(repoDir, 'CLAUDE.md'), 'utf8'), 'CLAUDE.md');
+    assert.equal(fs.readFileSync(path.join(repoDir, 'GEMINI.md'), 'utf8'), 'GEMINI.md');
+    assert.equal(fs.readFileSync(path.join(repoDir, '.github/copilot-instructions.md'), 'utf8'), '.github/copilot-instructions.md');
+  });
+
+  it('recursively overwrites skill tree files from the action source', async () => {
+    const repoDir = path.join(workspace, 'repo');
+    const nestedRelPath = '.codex/skills/triage-findings/assets/example.txt';
+    const sourceNestedPath = path.join(sourceRoot, nestedRelPath);
+    const repoNestedPath = path.join(repoDir, nestedRelPath);
+    fs.mkdirSync(path.dirname(sourceNestedPath), { recursive: true });
+    fs.writeFileSync(sourceNestedPath, 'fresh');
+    fs.mkdirSync(path.dirname(repoNestedPath), { recursive: true });
+    fs.writeFileSync(repoNestedPath, 'stale');
+
+    await commitAndPush(workspace, repoDir, makeSpawn(), sourceRoot);
+
+    assert.equal(fs.readFileSync(repoNestedPath, 'utf8'), 'fresh');
   });
 
   it('does not throw when git command fails', async () => {

app/main.js

@@ -95,7 +95,7 @@ async function main() {
   ok(`Step3 去重完成: ${mergedFindings.length} -> ${sorted.length} 筆 (critical=${sorted.filter(f=>f.level==='critical').length} warning=${sorted.filter(f=>f.level==='warning').length} info=${sorted.filter(f=>f.level==='info').length})`);
 
   step('Step4', 'AI 排除問題過濾');
-  const exclusions = loadExclusions(repoDir || WORKSPACE, repoState);
+  const exclusions = loadExclusions(repoDir || WORKSPACE, repoState, WORKSPACE);
   const ruleFiltered = applyExclusions(sorted, exclusions);
   const filtered = await filterFalsePositivesWithAI(ruleFiltered, exclusions);
   ok(`Step4 完成: findings total=${filtered.length}`);