chore(ai-review 狀態): 回寫本輪已處理 findings

.gitea/ai-review/findings/2026-07-21-14:42:39.json

@@ -8,63 +8,6 @@
     "model": "gpt-5.5"
   },
   "findings": [
-    {
-      "reviewer": "Assassin",
-      "focus": "security",
-      "badge": "🗡️",
-      "severity": "嚴重",
-      "file": "src/index.js",
-      "startLine": 344,
-      "endLine": 348,
-      "problem": "建問題模式在 `addIssueDependency` 失敗時只記錄警告，接著本輪仍會回傳 0；若 `commitFindings` 後續因沒有實際 diff 可提交而沒有產生 `[failure]` 結果 commit，攻擊者只要讓嚴重 finding 被搬到追蹤 issue，且目標 Gitea 未啟用 issue dependencies 或 token 權限不足，就會 fail-open：PR 既沒有相依阻擋，也沒有失敗檢查阻擋合併。",
-      "suggestion": "有嚴重問題時，相依關係設定失敗應視為阻擋條件：要嘛直接回傳 1，要嘛確認 failure 結果 commit 已成功產生後才允許本輪回傳 0。不要把阻擋機制失效降級成純警告。",
-      "suggestedCode": "",
-      "id": "F001",
-      "verdicts": {
-        "Paladin": {
-          "exclude": false,
-          "reason": "保留。此條不是單純重複既有「相依 API 失敗降級缺測試」，而是指控嚴重 finding 搬到 issue 後，dependency 失敗可能使阻擋機制失效；已知排除事項未涵蓋此安全語義。"
-        }
-      }
-    },
-    {
-      "reviewer": "Mage",
-      "focus": "logic",
-      "badge": "🔮",
-      "severity": "警告",
-      "file": "src/index.js",
-      "startLine": 330,
-      "endLine": 338,
-      "problem": "在建問題模式下，這段新增的 PR 回貼 issue 連結會在每次審查有保留問題時都新增一則 PR 留言，但同一流程前面明確跳過 `resolveOldComments`（建問題模式不清理 PR 舊留言）。最小重現：PR 第一次審查建立 issue #10 並在 PR 留連結；後續推新 commit 再跑一次，建立 issue #11 並再留一則連結。PR 上會同時存在 #10 與 #11，舊 issue 可能已過時，讀者無法判斷哪個才是目前審查結果。",
-      "suggestion": "建問題模式也應對本 action 先前的 PR 連結留言做過時標記，或在新增連結前查找並更新既有連結留言。若要避免碰觸 issue 內的審查內容，清理範圍可限制在 PR 上含 `MARK` 且標題為「已建立追蹤問題」的留言。",
-      "suggestedCode": "",
-      "id": "F009",
-      "verdicts": {
-        "Paladin": {
-          "exclude": false,
-          "reason": "保留。已知排除事項只裁示舊審查留言在本輪結果前標過時的時機；本條指控建問題模式跳過 PR 舊連結留言清理，導致多個追蹤 issue 連結並存，未被既有排除涵蓋。"
-        }
-      }
-    },
-    {
-      "reviewer": "Bard",
-      "focus": "style",
-      "badge": "🎼",
-      "severity": "建議",
-      "file": "src/lib/diagnostics.js",
-      "startLine": 55,
-      "endLine": 63,
-      "problem": "`agentFailureDetail` 裡的 `stderr` 與 `stdout` 區塊幾乎同譜重奏：取值、slice、redact、判斷、push 只差欄位名。這種重複雖小，卻讓後續若要調整遮罩或長度時容易改一半走調。",
-      "suggestion": "建議抽出小 helper，例如 `appendRedactedOutput(parts, label, value)`，讓 stderr/stdout 共用同一段處理節奏。",
-      "suggestedCode": "",
-      "id": "F005",
-      "verdicts": {
-        "Paladin": {
-          "exclude": false,
-          "reason": "保留。此條針對 diagnostics.js 中 stderr/stdout 處理重複的維護性問題，歷史 findings 主要是安全診斷缺測試與外洩風險，並非同一指控。"
-        }
-      }
-    },
     {
       "reviewer": "Bard",
       "focus": "style",
@@ -83,25 +26,6 @@
           "reason": "保留。歷史 findings 主要涵蓋 resolveMergeBase 缺測試與診斷不足，本條指向函式內策略編排、診斷組裝與錯誤包裝混雜的可維護性問題，未被既有排除事項完整涵蓋。"
         }
       }
-    },
-    {
-      "reviewer": "Bard",
-      "focus": "style",
-      "badge": "🎼",
-      "severity": "建議",
-      "file": "src/lib/gitrepo.js",
-      "startLine": 317,
-      "endLine": 346,
-      "problem": "`pushWithCredential` 的 JSDoc 已經很完整，但正文註解再次長篇解釋 checkout token、PAT、extraheader 清空等細節；文件與程式內註解重複奏同一段旋律，反而稀釋真正需要看的程式碼。",
-      "suggestion": "保留 JSDoc 的背景說明，函式內註解縮成操作提示即可，例如只說明「先清空 checkout extraheader，再注入本次 PAT header」。",
-      "suggestedCode": "",
-      "id": "F004",
-      "verdicts": {
-        "Paladin": {
-          "exclude": false,
-          "reason": "保留。既有排除事項雖有 push-token manifest 說明重複，但未涵蓋 pushWithCredential 函式內 JSDoc 與正文註解重複；證據不足以判定為重複或誤報。"
-        }
-      }
     }
   ],
   "excluded": [

src/index.js

@@ -72,7 +72,7 @@ function saveFindings({ cwd, ctx, tool, kept, excluded }) {
  * 供下一回合 `main()` 步驟 1 比對辨識、直接回報結果而不重複審查。
  * 依 `commitAndPushFindings` 的回傳值記錄不同日誌：true＝已 commit/push；
  * false＝檔案無實際變更（空 commit 防護），記「略過 commit/push」。
- * commit/push 失敗（例如與開發者新 commit 競態）時僅記 WRN log，不拋出例外、不改變審查結果。
+ * commit/push 失敗（例如與開發者新 commit 競態）時僅記 WRN log，不拋出例外；呼叫端可依回傳值決定是否阻擋。
  *
  * @param {Object} params - 解構參數。
  * @param {string} params.cwd - repo 根目錄（workspace）絕對路徑，git 操作在此目錄執行。
@@ -84,7 +84,7 @@ function saveFindings({ cwd, ctx, tool, kept, excluded }) {
  * @param {string} params.ctx.repository - `owner/repo` 形式的 repo 名稱。
  * @param {string[]} params.files - 要 commit 的檔案 repo 相對路徑陣列（如 findings 檔、`.gitea/ai-review/exclusions.json`）；全數無變更時只記 INF 略過。
  * @param {'success'|'failure'} params.result - 本回合審查結果：success＝無嚴重問題、failure＝有嚴重問題；會拼進 commit 訊息尾端。
- * @returns {void} 無回傳值；成敗僅反映在 log 上。
+ * @returns {boolean} true＝已 commit/push；false＝無變更或 commit/push 失敗。
  * @remarks
  * 使用情境：`main()` 於流程尾端依 `severe.length === 0 ? 'success' : 'failure'` 決定 result、
  * 依模式組出 filesToCommit（一般模式：findings 檔＋有變更時的 exclusions.json；
@@ -107,12 +107,15 @@ function commitFindings({ cwd, ctx, files, result }) {
     });
     if (committed) {
       log('收尾', 'INF', `審查結果檔已 commit 並 push 回 ${ctx.headRef}（結果：${result}）。`);
+      return true;
     } else {
       log('收尾', 'INF', '審查結果檔無實際變更，略過 commit/push。');
+      return false;
     }
   } catch (err) {
-    // push 失敗（例如與開發者新 commit 競態）時只記錄，不改變審查結果。
+    // push 失敗（例如與開發者新 commit 競態）時只記錄，交由呼叫端依嚴重度決定是否阻擋。
     log('收尾', 'WRN', `commit/push 審查結果檔失敗：${err.message}。`);
+    return false;
   }
 }
 
@@ -165,6 +168,7 @@ async function main() {
   // 建問題模式：追蹤 issue 於「確定有保留問題」後才建立；在那之前的情境留言（工具／diff／角色）
   // 先暫存於 pendingIssueCommentBodies，建立 issue 後一次寫入。
   const pendingIssueCommentBodies = [];
+  let issueModeActive = ctx.createIssue;
   let trackingIssue = null;
   /**
    * 發布一則審查留言。依模式決定去向：
@@ -179,7 +183,7 @@ async function main() {
    * 警告／建議彙整等留言。若 Gitea API 失敗，例外會往上拋出並由主流程頂層 catch 收斂。
    */
   const queueOrPostComment = async (body) => {
-    if (ctx.createIssue) {
+    if (issueModeActive) {
       if (trackingIssue) return gitea.createCommentOnIssue(ctx, trackingIssue.number, body);
       pendingIssueCommentBodies.push(body);
       return null;
@@ -210,13 +214,27 @@ async function main() {
     }
     pendingIssueCommentBodies.length = 0;
   };
+  /**
+   * 建問題模式降級：追蹤 issue 無法建立或寫入時，改把已暫存的情境留言發回 PR，後續沿用一般模式。
+   *
+   * @returns {Promise<void>} 無回傳值；會關閉建問題模式並把 PR 留言 id 登錄到 `currentRunCommentIds`。
+   */
+  const fallbackToPrComments = async () => {
+    issueModeActive = false;
+    trackingIssue = null;
+    for (const body of pendingIssueCommentBodies) {
+      const created = await gitea.createIssueComment(ctx, body);
+      currentRunCommentIds.add(created.id);
+    }
+    pendingIssueCommentBodies.length = 0;
+  };
 
   // ── 步驟 2：延後執行 ───────────────────────────────────────────────────
   // 「將 PR 既有留言標記為解決」原本在此執行，但若工具偵測／diff／攻防裁決任一失敗，
   // 舊結果會先被清掉卻沒有新結果。故延後到「本回合審查已成功產生結果、發布問題留言前」
   // 才呼叫 review.resolveOldComments（見下方步驟 4 空變更路徑與步驟 9 前）；
   // 屆時本回合的工具／diff／角色留言已登錄於 currentRunCommentIds，不會被誤標為過時。
-  // 建問題模式全程不觸碰 PR 既有留言（審查內容改發到 issue）。
+  // 建問題模式不清理 PR 既有審查內容，只在收束時標記舊追蹤 issue 連結。
 
   // ── 步驟 3：偵測 AI agent 工具並留言 ──────────────────────────────────
   const tool = agents.detectTool();
@@ -248,7 +266,7 @@ async function main() {
   if (files.length === 0) {
     // 沒有可審查的變更：保存空 findings、以 success 收場。
     // 一般模式在 PR 留言告知；建問題模式靜默通過（不建 issue、PR 也不留言，暫存的情境留言捨棄）。
-    if (ctx.createIssue) {
+    if (issueModeActive) {
       log('步驟4', 'INF', '建問題模式且無可審查變更：靜默通過（不建 issue、PR 不留言）。');
     } else {
       await queueOrPostComment(templates.nothingToReviewComment(ignoredCount));
@@ -256,7 +274,7 @@ async function main() {
       await review.resolveOldComments({ ctx, gitea, currentRunCommentIds });
     }
     const relativePath = saveFindings({ cwd, ctx, tool, kept: [], excluded: [] });
-    if (ctx.createIssue) {
+    if (issueModeActive) {
       // 建問題模式下 findings 不進版控，且 exclusions.json 無變更 → 沒東西可提交。
       log('收尾', 'INF', '建問題模式且無可審查變更，略過 commit/push。');
     } else {
@@ -299,7 +317,7 @@ async function main() {
 
   // ── 建問題模式：確定有保留問題才建立 issue，並把暫存的情境留言一次寫入；
   //    無保留問題則不建 issue、PR 也完全不留言（靜默通過，暫存的情境留言捨棄）。 ──────
-  if (ctx.createIssue) {
+  if (issueModeActive) {
     if (kept.length > 0) {
       // 先依保留問題挑好標籤，於建立 issue 時一次帶入（省去「先建空標籤 issue 再補掛」的多餘 API 往返）；
       // 標籤挑選失敗一律降級為不掛標籤，不阻斷建 issue 流程。
@@ -318,7 +336,12 @@ async function main() {
       } catch (err) {
         log('建問題', 'WRN', `標籤挑選失敗（${err.message}），issue 不掛標籤。`);
       }
-      await createIssueAndFlushBufferedComments(labelIds);
+      try {
+        await createIssueAndFlushBufferedComments(labelIds);
+      } catch (err) {
+        log('建問題', 'WRN', `建立或寫入追蹤 issue 失敗（${err.message}），改用 PR 留言與 findings 檔流程。`);
+        await fallbackToPrComments();
+      }
     } else {
       // 無保留問題 → 不建 issue、PR 也不留言（靜默通過，暫存的情境留言捨棄）。
       log('建問題', 'INF', '沒有保留的問題：靜默通過（不建 issue、PR 不留言）。');
@@ -329,13 +352,13 @@ async function main() {
   //    延後到此可避免工具偵測／diff／攻防裁決任一失敗時舊結果先被清掉卻無新結果；
   //    本回合的工具／diff／角色留言已登錄於 currentRunCommentIds，不會被誤標為過時；
   //    嚴重／其他問題留言於本步驟之後才發布，同樣不受影響。
-  if (!ctx.createIssue) {
+  if (!issueModeActive) {
     await review.resolveOldComments({ ctx, gitea, currentRunCommentIds });
   }
 
   // ── 步驟 9：嚴重問題留言（一般模式掛在 PR 程式碼行上；建問題模式逐條發到 issue）─
   if (severe.length > 0) {
-    if (ctx.createIssue) {
+    if (issueModeActive && trackingIssue) {
       await review.postSevereToIssue({ ctx, gitea, issueNumber: trackingIssue.number, severe });
     } else {
       await review.postSevereComments({ ctx, gitea, severe, cwd });
@@ -345,7 +368,7 @@ async function main() {
   // ── 步驟 10：警告＋建議——一般模式彙整為單一表格留言到 PR；
   //    建問題模式逐條發到 issue，讓每條問題都能被個別回覆。 ──
   if (others.length > 0) {
-    if (ctx.createIssue) {
+    if (issueModeActive && trackingIssue) {
       await review.postOthersToIssue({ ctx, gitea, issueNumber: trackingIssue.number, others });
     } else {
       await queueOrPostComment(templates.othersComment(others));
@@ -355,7 +378,8 @@ async function main() {
 
   // ── 建問題模式收束：在 PR 回貼 issue 連結（雙向關聯）；僅在有嚴重問題時才讓 PR 相依於該 issue ─
   //    標籤已於建立 issue 時一次帶入（見上方 selectLabels → createIssueAndFlushBufferedComments），此處不再補掛。
-  if (ctx.createIssue && trackingIssue) {
+  if (issueModeActive && trackingIssue) {
+    await review.resolveOldIssueLinkComments({ ctx, gitea });
     await gitea.createIssueComment(
       ctx,
       templates.prIssueLinkComment({
@@ -385,13 +409,14 @@ async function main() {
   // 若有嚴重問題，仍 commit findings 檔產生 [failure] 結果 commit，避免相依 API 不支援時 fail-open。
   const result = severe.length === 0 ? 'success' : 'failure';
   const filesToCommit = review.resultFilesToCommit({
-    createIssue: ctx.createIssue,
+    createIssue: issueModeActive,
     severeCount: severe.length,
     relativePath,
     exclusionsChanged,
   });
+  let resultCommitted = false;
   if (filesToCommit.length > 0) {
-    commitFindings({ cwd, ctx, files: filesToCommit, result });
+    resultCommitted = commitFindings({ cwd, ctx, files: filesToCommit, result });
   } else {
     log('收尾', 'INF', '建問題模式且 exclusions.json 無變更，略過 commit/push。');
   }
@@ -399,6 +424,10 @@ async function main() {
   // 由它再觸發的下一輪在步驟 1 讀 commit 訊息時才回報失敗（exit 1）。如此失敗檢查落在帶有結果
   // 標記的最新 head 上，與合併判定一致。（result 僅用於上方 commit 訊息的結果標記。）
   if (result === 'failure') {
+    if (!resultCommitted) {
+      log('收尾', 'ERR', '本輪有嚴重問題，但未成功產生 [failure] 結果 commit；直接回報失敗避免 fail-open。');
+      return 1;
+    }
     log('收尾', 'INF', '本輪有嚴重問題：已標記結果 commit 為 [failure]，失敗檢查由下一輪步驟 1 讀 commit 訊息回報。');
   }
   return 0;

src/lib/diagnostics.js

@@ -29,6 +29,19 @@ function redactSecrets(text) {
     .trim();
 }
 
+/**
+ * 將 AI CLI 失敗輸出整理成單行、遮罩且限長的診斷片段。
+ *
+ * @param {string[]} parts - 要附加診斷片段的陣列。
+ * @param {string} label - 診斷欄位名稱（如 stderr／stdout）。
+ * @param {*} value - 原始診斷輸出。
+ * @returns {void}
+ */
+function appendRedactedOutput(parts, label, value) {
+  const redacted = redactSecrets(String(value || '').slice(0, AGENT_DIAGNOSTIC_INPUT_LIMIT));
+  if (redacted) parts.push(`${label}：${redacted.slice(0, AGENT_DIAGNOSTIC_OUTPUT_LIMIT)}`);
+}
+
 /**
  * 從 `runAgent` 的失敗結果組出可診斷的一行摘要：退出碼／訊號為主，原始輸出預設隱藏。
  *
@@ -52,10 +65,8 @@ function agentFailureDetail(agentResult) {
   }
   // 失敗輸出可能含 token 或 PII，預設不寫入長期 CI log；debug 模式才輸出遮罩後片段。
   if (process.env.ACTIONS_STEP_DEBUG === 'true') {
-    const stderr = redactSecrets(String((agentResult && agentResult.stderr) || '').slice(0, AGENT_DIAGNOSTIC_INPUT_LIMIT));
-    if (stderr) parts.push(`stderr：${stderr.slice(0, AGENT_DIAGNOSTIC_OUTPUT_LIMIT)}`);
-    const stdout = redactSecrets(String((agentResult && agentResult.output) || '').slice(0, AGENT_DIAGNOSTIC_INPUT_LIMIT));
-    if (stdout) parts.push(`stdout：${stdout.slice(0, AGENT_DIAGNOSTIC_OUTPUT_LIMIT)}`);
+    appendRedactedOutput(parts, 'stderr', agentResult && agentResult.stderr);
+    appendRedactedOutput(parts, 'stdout', agentResult && agentResult.output);
   }
   if (parts.length === 0) {
     parts.push((err && err.message && redactSecrets(err.message)) || 'AI CLI 執行失敗（無診斷輸出）');

src/lib/gitrepo.js

@@ -300,8 +300,7 @@ function commitAndPushFindings(cwd, { headRef, headSha, message, files, token, s
   );
   const refspec = `HEAD:refs/heads/${headRef}`;
   const remoteUrl = `${serverUrl}/${repository}.git`;
-  // 一律以 token 的身分明確認證推送（不走 origin 的自動 token）——只要 token 是能觸發 CI 的 PAT，
-  // 結果 commit 就會讓 PR 的 synchronize 事件再觸發 CI，由步驟 1 快速回報把結果蓋到新 head。
+  // 一律以 token 的身分明確認證推送，不沿用 origin 的自動 token。
   pushWithCredential(cwd, remoteUrl, token, refspec, serverUrl);
   return true;
 }
@@ -348,7 +347,7 @@ function pushWithCredential(cwd, remoteUrl, token, refspec, serverUrl) {
       env: {
         ...process.env,
         GIT_TERMINAL_PROMPT: '0',
-        // 兩筆同 scope 設定：先空值清掉 checkout 的自動 token，再注入 PAT 的 Authorization。
+        // 先清空 checkout extraheader，再注入本次 PAT header。
         GIT_CONFIG_COUNT: '2',
         GIT_CONFIG_KEY_0: headerScope,
         GIT_CONFIG_VALUE_0: '',

src/lib/review.js

@@ -832,6 +832,40 @@ async function resolveOldComments({ ctx, gitea, currentRunCommentIds }) {
   }
 }
 
+/**
+ * 建問題模式：只將 PR 上舊的「追蹤問題連結」留言標註為過時，不觸碰 issue 內審查內容。
+ *
+ * @param {Object} params - 解構參數。
+ * @param {Object} params.ctx - 執行環境 context（`loadContext()` 產出）。
+ * @param {Object} params.gitea - Gitea API 模組，需提供 `whoAmI`、`listIssueComments`、`editIssueComment`。
+ * @returns {Promise<void>} 無回傳值；失敗時只記 WRN，不阻斷主流程。
+ */
+async function resolveOldIssueLinkComments({ ctx, gitea }) {
+  let botLogin = '';
+  try {
+    botLogin = (await gitea.whoAmI(ctx)).login || '';
+  } catch (err) {
+    log('建問題', 'WRN', `無法取得 bot 身分（${err.message}），略過舊追蹤連結標註。`);
+    return;
+  }
+
+  try {
+    const comments = await gitea.listIssueComments(ctx);
+    let outdatedCount = 0;
+    for (const comment of comments) {
+      const isBot = comment.user && comment.user.login === botLogin;
+      const body = typeof comment.body === 'string' ? comment.body : '';
+      const isIssueLink = body.includes(templates.MARK) && body.includes('## 🔍 AI Code Review｜已建立追蹤問題');
+      if (!isBot || !isIssueLink || body.startsWith(templates.OUTDATED_PREFIX)) continue;
+      await gitea.editIssueComment(ctx, comment.id, `${templates.OUTDATED_PREFIX}${body}`);
+      outdatedCount += 1;
+    }
+    log('建問題', 'INF', `舊追蹤 issue 連結已標註〔已過時〕：${outdatedCount} 則。`);
+  } catch (err) {
+    log('建問題', 'WRN', `標註舊追蹤 issue 連結失敗：${err.message}。`);
+  }
+}
+
 /**
  * 步驟 9：嚴重問題逐條掛在 PR 程式碼行上留言（建立 code review）；
  * 建立 review 失敗時降級為一般留言逐條發布（留言內補上檔案與行號位置）。
@@ -884,5 +918,6 @@ module.exports = {
   postSevereToIssue,
   postOthersToIssue,
   resolveOldComments,
+  resolveOldIssueLinkComments,
   postSevereComments,
 };

test/review.test.js

@@ -97,3 +97,40 @@ test('resultFilesToCommit 在建問題模式無嚴重問題時只提交 exclusio
     ['.gitea/ai-review/exclusions.json'],
   );
 });
+
+test('resolveOldIssueLinkComments 只標註舊追蹤 issue 連結', async () => {
+  const edited = [];
+  const fakeGitea = {
+    async whoAmI() {
+      return { login: 'bot' };
+    },
+    async listIssueComments() {
+      return [
+        {
+          id: 1,
+          user: { login: 'bot' },
+          body: '<!-- ai-code-review -->\n## 🔍 AI Code Review｜已建立追蹤問題\nold',
+        },
+        {
+          id: 2,
+          user: { login: 'bot' },
+          body: '<!-- ai-code-review -->\n## 📋 變更摘要（送審 git diff）\nkeep',
+        },
+        {
+          id: 3,
+          user: { login: 'someone' },
+          body: '<!-- ai-code-review -->\n## 🔍 AI Code Review｜已建立追蹤問題\nkeep',
+        },
+      ];
+    },
+    async editIssueComment(ctx, commentId, body) {
+      edited.push({ ctx, commentId, body });
+    },
+  };
+
+  await review.resolveOldIssueLinkComments({ ctx: { token: 'hidden' }, gitea: fakeGitea });
+
+  assert.equal(edited.length, 1);
+  assert.equal(edited[0].commentId, 1);
+  assert.match(edited[0].body, /^> 〔已過時〕/);
+});