readme.md

@@ -38,13 +38,13 @@ jobs:
 ```mermaid
 flowchart TD
     S1[1 判斷 bot commit 標記] -->|命中| E0[直接回報 success/failure]
-    S1 -->|未命中| S2[2 偵測 AI 工具並留言]
-    S2 --> S3[3 讀 .reviewignore 整理 diff 並留言]
-    S3 --> S4[4 攻擊方登場留言]
-    S4 --> S5[5 攻擊方 sub agent 並行找問題]
-    S5 --> S6[6 防守方登場留言]
-    S6 --> S7[7 防守方裁決 → 保存 findings ＋ 誤判回寫 exclusions.json]
-    S7 --> S8[8 舊留言標記解決]
+    S1 -->|未命中| S2[2 舊留言標記解決]
+    S2 --> S3[3 偵測 AI 工具並留言]
+    S3 --> S4[4 讀 .reviewignore 整理 diff 並留言]
+    S4 --> S5[5 攻擊方登場留言]
+    S5 --> S6[6 攻擊方 sub agent 並行找問題]
+    S6 --> S7[7 防守方登場留言]
+    S7 --> S8[8 防守方裁決 → 保存 findings ＋ 誤判回寫 exclusions.json]
     S8 --> S9[9 嚴重問題逐條掛行留言]
     S9 --> S10[10 警告＋建議彙整表格留言]
     S10 --> E1[收尾 commit/push ＋ exit code]
@@ -104,9 +104,9 @@ flowchart TD
 | [roles.loadRoles](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/roles.js#L32) | [載入角色提示檔並解析 frontmatter](#rolesloadroles) |
 | [roles.attackersOf](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/roles.js#L71) | [過濾出攻擊方角色](#rolesattackersof) |
 | [roles.defendersOf](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/roles.js#L90) | [過濾出防守方角色](#rolesdefendersof) |
-| [templates.toolComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L88) | [產生步驟 2 審查工具留言](#templatestoolcomment) |
-| [templates.diffComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L132) | [產生步驟 3 變更摘要留言](#templatesdiffcomment) |
-| [templates.rolesComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L173) | [產生步驟 4／6 角色登場留言](#templatesrolescomment) |
+| [templates.toolComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L88) | [產生步驟 3 審查工具留言](#templatestoolcomment) |
+| [templates.diffComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L132) | [產生步驟 4 變更摘要留言](#templatesdiffcomment) |
+| [templates.rolesComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L173) | [產生步驟 5／7 角色登場留言](#templatesrolescomment) |
 | [templates.severeCommentBody](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L215) | [產生步驟 9 單條嚴重問題留言](#templatesseverecommentbody) |
 | [templates.severeReviewBody](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L247) | [產生步驟 9 嚴重問題 review 總覽](#templatesseverereviewbody) |
 | [templates.othersComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L277) | [產生步驟 10 警告＋建議彙整表格留言](#templatesotherscomment) |
@@ -168,8 +168,8 @@ taipeiFromIso('');                     // '—'
 
 ```js
 const { log } = require('./src/lib/log');
-log('步驟3', 'INF', '變更檔案 5 個，送審 3 個。');
-// [2026/07/17 16:46:13][步驟3][INF]: 變更檔案 5 個，送審 3 個。
+log('步驟4', 'INF', '變更檔案 5 個，送審 3 個。');
+// [2026/07/17 16:46:13][步驟4][INF]: 變更檔案 5 個，送審 3 個。
 ```
 
 <a id="contextloadcontext"></a>
@@ -246,7 +246,7 @@ const committed = gitrepo.commitAndPushFindings(cwd, {
 <a id="giteawhoami"></a>
 ### gitea.whoAmI
 
-取得 token 對應的使用者（`GET /user`），即 bot 身分；步驟 8 以 `login` 比對留言作者辨識本 action 發過的留言。
+取得 token 對應的使用者（`GET /user`），即 bot 身分；步驟 2 以 `login` 比對留言作者辨識本 action 發過的留言。
 
 ```js
 const gitea = require('./src/lib/gitea');
@@ -269,7 +269,7 @@ await gitea.createCommentOnIssue(ctx, issue.number, '🔴 嚴重｜...');
 
 ```js
 const created = await gitea.createIssueComment(ctx, '## 📋 變更摘要 ...');
-// created.id 記入本回合留言集合，步驟 8 標註過時時跳過
+// created.id 記入本回合留言集合，步驟 2 標註過時時跳過
 ```
 
 <a id="gitealistlabels"></a>
@@ -294,7 +294,7 @@ const issue = await gitea.createIssue(ctx, { title: 'PR 標題', body: '…', la
 <a id="gitealistissuecomments"></a>
 ### gitea.listIssueComments
 
-列出 PR 全部一般留言（自動分頁，每頁 50 筆）；步驟 8 據此找出 bot 舊留言標註〔已過時〕。
+列出 PR 全部一般留言（自動分頁，每頁 50 筆）；步驟 2 據此找出 bot 舊留言標註〔已過時〕。
 
 ```js
 const comments = await gitea.listIssueComments(ctx);
@@ -303,7 +303,7 @@ const comments = await gitea.listIssueComments(ctx);
 <a id="giteaeditissuecomment"></a>
 ### gitea.editIssueComment
 
-以新內容整段覆寫既有一般留言（留言 id 於 repo 層級定位）；步驟 8 用來替舊留言加上〔已過時〕前綴。
+以新內容整段覆寫既有一般留言（留言 id 於 repo 層級定位）；步驟 2 用來替舊留言加上〔已過時〕前綴。
 
 ```js
 await gitea.editIssueComment(ctx, comment.id, `> 〔已過時〕…\n\n${comment.body}`);
@@ -323,7 +323,7 @@ await gitea.createReview(ctx, '## 🔴 嚴重問題（共 2 條）…', [
 <a id="gitealistreviews"></a>
 ### gitea.listReviews
 
-列出 PR 全部 review（自動分頁）；步驟 8 據此逐一取出行內留言嘗試解決。
+列出 PR 全部 review（自動分頁）；步驟 2 據此逐一取出行內留言嘗試解決。
 
 ```js
 const reviews = await gitea.listReviews(ctx);
@@ -411,7 +411,7 @@ const defenders = defendersOf(roles); // [Paladin]
 <a id="templatestoolcomment"></a>
 ### templates.toolComment
 
-產生步驟 2 的審查工具留言：工具／版本／模型／審查 commit／Run Job 連結表格＋審查管線 mermaid 流程圖；開頭含隱藏標記供步驟 8 辨識。
+產生步驟 3 的審查工具留言：工具／版本／模型／審查 commit／Run Job 連結表格＋審查管線 mermaid 流程圖；開頭含隱藏標記供步驟 2 辨識。
 
 ```js
 const body = templates.toolComment({
@@ -424,7 +424,7 @@ const body = templates.toolComment({
 <a id="templatesdiffcomment"></a>
 ### templates.diffComment
 
-產生步驟 3 的變更摘要留言：四欄表格（檔案／用途／git diff 長度／最後更新時間），截斷送審的檔案加註，結尾統計送審與排除數。
+產生步驟 4 的變更摘要留言：四欄表格（檔案／用途／git diff 長度／最後更新時間），截斷送審的檔案加註，結尾統計送審與排除數。
 
 ```js
 const body = templates.diffComment(diffRows, ignoredCount);
@@ -433,7 +433,7 @@ const body = templates.diffComment(diffRows, ignoredCount);
 <a id="templatesrolescomment"></a>
 ### templates.rolesComment
 
-產生步驟 4／6 共用的角色登場留言：三欄表格（角色／面向／個性），面向以「中文（原文）」並列。
+產生步驟 5／7 共用的角色登場留言：三欄表格（角色／面向／個性），面向以「中文（原文）」並列。
 
 ```js
 const body = templates.rolesComment({ title: '⚔️ 攻擊方登場', roles: attackers });
@@ -534,7 +534,7 @@ await review.fillPurposes({ tool, model: ctx.model, cwd, diffRows });
 <a id="reviewrunattackers"></a>
 ### review.runAttackers
 
-步驟 5：每位攻擊方角色一個 sub agent 並行分析 diff，回覆經檢核標準化後合併為單一問題列表並編派 `F001…` 流水號；單一角色失敗只記 WRN 以空結果代替。
+步驟 6：每位攻擊方角色一個 sub agent 並行分析 diff，回覆經檢核標準化後合併為單一問題列表並編派 `F001…` 流水號；單一角色失敗只記 WRN 以空結果代替。
 
 ```js
 const findings = await review.runAttackers({ tool, model: ctx.model, cwd, attackers, diffRows });
@@ -543,7 +543,7 @@ const findings = await review.runAttackers({ tool, model: ctx.model, cwd, attack
 <a id="reviewrundefenders"></a>
 ### review.runDefenders
 
-步驟 7：每位防守方角色一個 sub agent 配合 `exclusions.json` 與歷史 findings 裁決；「全部防守方都判可排除」才移除，拿不準一律保留，每條附 `verdicts` 供追溯。
+步驟 8：每位防守方角色一個 sub agent 配合 `exclusions.json` 與歷史 findings 裁決；「全部防守方都判可排除」才移除，拿不準一律保留，每條附 `verdicts` 供追溯。
 
 ```js
 const { kept, excluded } = await review.runDefenders({ tool, model: ctx.model, cwd, defenders, findings });
@@ -600,7 +600,7 @@ if (ctx.createIssue && kept.length > 0) {
 <a id="reviewresolveoldcomments"></a>
 ### review.resolveOldComments
 
-步驟 8：bot 舊一般留言（非本回合）編輯加〔已過時〕前綴；review 行內留言盡力呼叫 resolve API，第一次失敗即判定版本不支援並停止。任何失敗只記 WRN 不阻斷。
+步驟 2：bot 舊一般留言（非本回合）編輯加〔已過時〕前綴；review 行內留言盡力呼叫 resolve API，第一次失敗即判定版本不支援並停止。任何失敗只記 WRN 不阻斷。
 
 ```js
 await review.resolveOldComments({ ctx, gitea, currentRunCommentIds });

src/lib/agents.js

@@ -47,7 +47,7 @@ const TOOLS = [
  * @returns {{ name: string, buildArgs: Function, resultFrom: string, version: string } | null}
  *   中選工具的描述物件（TOOLS 項目加上 version 欄位）；所有工具皆不可用時回傳 null。
  * @remarks
- * 使用情境：action 主流程（步驟 2）啟動審查前呼叫一次，取得工具描述後交給
+ * 使用情境：action 主流程（步驟 3）啟動審查前呼叫一次，取得工具描述後交給
  * runAgent 執行；若回傳 null，主流程會記 ERR 並以失敗收場（無工具即無法審查）。
  */
 function detectTool() {

src/lib/gitea.js

@@ -80,7 +80,7 @@ async function listAll(ctx, apiPath) {
  * @returns {Promise<object>} Gitea 使用者物件（含 `id`、`login` 等欄位，
  *   依 Gitea API 回應而定）。
  * @throws {Error} 請求失敗（非 2xx，例如 token 無效時 401）由底層 `api` 丟出。
- * @remarks 使用情境：action 步驟 8 先查出 bot 自己的帳號，
+ * @remarks 使用情境：action 步驟 2 先查出 bot 自己的帳號，
  *   之後比對 PR 留言的作者，辨識哪些留言是本 action 先前發出的
  *   （例如要將舊留言標註為已過時）。
  */
@@ -178,7 +178,7 @@ function createIssue(ctx, { title, body, labels }) {
  * @returns {Promise<Array<object>>} 留言物件陣列（含 `id`、`body`、`user` 等欄位）；
  *   無留言時為空陣列。
  * @throws {Error} 任一頁請求失敗（非 2xx）由底層 `api` 丟出，錯誤附 `status`、`data`。
- * @remarks 使用情境：步驟 8 重跑 review 前，先撈出 PR 全部留言並搭配 `whoAmI`
+ * @remarks 使用情境：步驟 2 重跑 review 前，先撈出 PR 全部留言並搭配 `whoAmI`
  *   比對作者，找出本 action（bot）先前發過的留言，以便編輯標註為已過時。
  */
 function listIssueComments(ctx) {
@@ -237,7 +237,7 @@ function createReview(ctx, body, comments) {
  * @returns {Promise<Array<object>>} review 物件陣列（含 `id`、`user`、`body` 等欄位）；
  *   無 review 時為空陣列。
  * @throws {Error} 任一頁請求失敗（非 2xx）由底層 `api` 丟出，錯誤附 `status`、`data`。
- * @remarks 使用情境：步驟 8 重跑 review 前，先找出 PR 上既有 review，
+ * @remarks 使用情境：步驟 2 重跑 review 前，先找出 PR 上既有 review，
  *   再以 `listReviewComments` 取出其行內留言做後續解決標記。
  */
 function listReviews(ctx) {
@@ -280,7 +280,7 @@ function listReviewComments(ctx, reviewId) {
  * @param {number|string} commentId - 要標記為已解決的行內留言 id。
  * @returns {Promise<boolean>} 標記成功回傳 `true`；任何失敗
  *   （版本不支援、權限不足、留言不存在等）一律回傳 `false`，不丟出例外。
- * @remarks 使用情境：步驟 8 嘗試把舊回合的行內留言標記為已解決；若回傳 `false`
+ * @remarks 使用情境：步驟 2 嘗試把舊回合的行內留言標記為已解決；若回傳 `false`
  *   （例如目標 Gitea 版本無此 API），呼叫端應停止嘗試並記 WRN
  *   （由 `resolveOldComments` 實作此降級）。
  */

src/lib/review.js

@@ -22,7 +22,7 @@ const TOTAL_DIFF_LIMIT = 160_000;
  * @param {string} workspace - 工作目錄絕對路徑（`.reviewignore` 所在的 repo 根目錄）。
  * @returns {string[]} 忽略用的路徑前綴陣列；檔案不存在時為空陣列。
  * @remarks
- * 使用情境：審查流程「步驟 3」開頭由 `src/index.js` 呼叫，
+ * 使用情境：審查流程「步驟 4」開頭由 `src/index.js` 呼叫，
  * 取得前綴清單後搭配 {@link isIgnored} 過濾 `gitrepo.changedFiles` 的結果，
  * 決定哪些變更檔案要納入送審。
  */
@@ -46,7 +46,7 @@ function loadReviewIgnore(workspace) {
  * @param {string[]} prefixes - 忽略路徑前綴清單（通常來自 {@link loadReviewIgnore}）。
  * @returns {boolean} `true` 表示忽略、不納入審查；`false` 表示送審。
  * @remarks
- * 使用情境：審查流程「步驟 3」中，`src/index.js` 以
+ * 使用情境：審查流程「步驟 4」中，`src/index.js` 以
  * `allFiles.filter((file) => !review.isIgnored(file, ignores))`
  * 過濾變更檔案清單，被排除的檔案數量會反映在變更摘要留言的排除統計。
  */
@@ -70,7 +70,7 @@ function isIgnored(file, prefixes) {
  * @returns {Array<{file: string, purpose: string, lines: number, chars: number, truncated: boolean, lastUpdated: string, diffForPrompt: string}>}
  *   每檔一列的 diff 資料列；`purpose` 初始為「—」，由 {@link fillPurposes} 補齊。
  * @remarks
- * 使用情境：審查流程「步驟 3」由 `src/index.js` 呼叫，產出的 rows 同時餵給
+ * 使用情境：審查流程「步驟 4」由 `src/index.js` 呼叫，產出的 rows 同時餵給
  * {@link fillPurposes}（補用途）、`templates.diffComment`（變更摘要留言）與
  * {@link buildAttackPrompt}（攻擊方提示的變更內容區塊）。
  */
@@ -86,12 +86,12 @@ function collectDiffRows({ cwd, files, base, gitrepo }) {
     if (diffForPrompt.length > PER_FILE_DIFF_LIMIT) {
       diffForPrompt = `${diffForPrompt.slice(0, PER_FILE_DIFF_LIMIT)}\n...（diff 過長，其餘截斷未送審）`;
       truncated = true;
-      log('步驟3', 'WRN', `${file} 的 diff 超過單檔上限（${chars} 字元），已截斷送審。`);
+      log('步驟4', 'WRN', `${file} 的 diff 超過單檔上限（${chars} 字元），已截斷送審。`);
     }
     if (totalChars + diffForPrompt.length > TOTAL_DIFF_LIMIT) {
       diffForPrompt = '（全部 diff 總量超過送審上限，本檔內容未送審，僅列出檔名）';
       truncated = true;
-      log('步驟3', 'WRN', `${file} 因總量上限未送審 diff 內容。`);
+      log('步驟4', 'WRN', `${file} 因總量上限未送審 diff 內容。`);
     } else {
       totalChars += diffForPrompt.length;
     }
@@ -121,7 +121,7 @@ function collectDiffRows({ cwd, files, base, gitrepo }) {
  * @param {Array<Object>} params.diffRows - {@link collectDiffRows} 產出的資料列；本函式會就地更新其 `purpose` 欄位。
  * @returns {Promise<void>} 無回傳值；結果反映在 `diffRows` 的 `purpose` 欄位。
  * @remarks
- * 使用情境：審查流程「步驟 3」在 `collectDiffRows` 之後、發布
+ * 使用情境：審查流程「步驟 4」在 `collectDiffRows` 之後、發布
  * `templates.diffComment` 變更摘要留言之前呼叫，讓摘要表格的「用途」欄有內容。
  */
 async function fillPurposes({ tool, model, cwd, diffRows }) {
@@ -140,12 +140,12 @@ ${sections}
 - 不得輸出個資（PII）。`;
   const res = await runAgent(tool, { model, prompt, cwd, timeoutMs: 300_000 });
   if (!res.ok) {
-    log('步驟3', 'WRN', '檔案用途摘要產生失敗，以「—」代替。');
+    log('步驟4', 'WRN', '檔案用途摘要產生失敗，以「—」代替。');
     return;
   }
   const parsed = extractJson(res.output);
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    log('步驟3', 'WRN', '檔案用途摘要回覆無法解析，以「—」代替。');
+    log('步驟4', 'WRN', '檔案用途摘要回覆無法解析，以「—」代替。');
     return;
   }
   for (const row of diffRows) {
@@ -163,7 +163,7 @@ ${sections}
  * @param {*} value - 攻擊方回覆的 severity 原始值（可能是任何型別；非字串會先轉字串）。
  * @returns {'嚴重'|'警告'|'建議'} 收斂後的等級字串。
  * @remarks
- * 使用情境：審查流程「步驟 5」中 {@link normalizeFinding} 檢核每條 finding 時呼叫，
+ * 使用情境：審查流程「步驟 6」中 {@link normalizeFinding} 檢核每條 finding 時呼叫，
  * 確保後續 {@link sortFindings} 的 `templates.SEVERITY_ORDER` 排序、
  * 「嚴重」分組（步驟 9 逐條留言 vs 步驟 10 彙整表格）都能以固定用詞比對。
  * 本函式未匯出，僅供模組內部使用。
@@ -188,7 +188,7 @@ function normalizeSeverity(value) {
  * @param {Array<Object>} diffRows - {@link collectDiffRows} 產出的送審資料列（file／purpose／lastUpdated／diffForPrompt）。
  * @returns {string} 可直接餵給 `runAgent` stdin 的完整提示字串。
  * @remarks
- * 使用情境：審查流程「步驟 5」{@link runAttackers} 為每個攻擊方角色各組一份提示，
+ * 使用情境：審查流程「步驟 6」{@link runAttackers} 為每個攻擊方角色各組一份提示，
  * 並行送入 sub agent 找問題。本函式未匯出，僅供模組內部使用。
  */
 function buildAttackPrompt(role, diffRows) {
@@ -233,7 +233,7 @@ ${sections}
  * @returns {?{reviewer: string, focus: string, badge: string, severity: string, file: string, startLine: number, endLine: number, problem: string, suggestion: string, suggestedCode: string}}
  *   標準化後的 finding；輸入不合格時為 `null`。
  * @remarks
- * 使用情境：審查流程「步驟 5」{@link runAttackers} 解析每個攻擊方的 JSON 回覆後，
+ * 使用情境：審查流程「步驟 6」{@link runAttackers} 解析每個攻擊方的 JSON 回覆後，
  * 逐條經本函式檢核，通過者才進入合併列表並編派 id，供防守方裁決與留言使用。
  * 本函式未匯出，僅供模組內部使用。
  */
@@ -256,7 +256,7 @@ function normalizeFinding(fromAgent, role) {
 }
 
 /**
- * 步驟 5：每個攻擊方角色一個 sub agent 並行分析送審 diff，合併為單一問題列表並編派 id。
+ * 步驟 6：每個攻擊方角色一個 sub agent 並行分析送審 diff，合併為單一問題列表並編派 id。
  *
  * 單一角色失敗（執行失敗或回覆無法解析為 JSON 陣列）只記 WRN 並以空結果代替，
  * 不阻斷其他角色（失敗降級行為）；每條回覆先經 {@link normalizeFinding} 檢核，
@@ -270,25 +270,25 @@ function normalizeFinding(fromAgent, role) {
  * @param {Array<Object>} params.diffRows - {@link collectDiffRows} 產出的送審資料列。
  * @returns {Promise<Array<Object>>} 合併後的標準化 finding 列表（每條含 `id`）；全部失敗或無問題時為空陣列。
  * @remarks
- * 使用情境：審查流程「步驟 5」由 `src/index.js` 在攻擊方登場留言後呼叫，
- * 結果直接交給步驟 7 的 {@link runDefenders} 裁決。
+ * 使用情境：審查流程「步驟 6」由 `src/index.js` 在攻擊方登場留言後呼叫，
+ * 結果直接交給步驟 8 的 {@link runDefenders} 裁決。
  */
 async function runAttackers({ tool, model, cwd, attackers, diffRows }) {
   const results = await Promise.all(
     attackers.map(async (role) => {
-      log('步驟5', 'INF', `攻擊方 ${role.meta.name} 開始分析。`);
+      log('步驟6', 'INF', `攻擊方 ${role.meta.name} 開始分析。`);
       const res = await runAgent(tool, { model, prompt: buildAttackPrompt(role, diffRows), cwd });
       if (!res.ok) {
-        log('步驟5', 'WRN', `攻擊方 ${role.meta.name} 執行失敗：${(res.error && res.error.message) || '未知錯誤'}。`);
+        log('步驟6', 'WRN', `攻擊方 ${role.meta.name} 執行失敗：${(res.error && res.error.message) || '未知錯誤'}。`);
         return [];
       }
       const parsed = extractJson(res.output);
       if (!Array.isArray(parsed)) {
-        log('步驟5', 'WRN', `攻擊方 ${role.meta.name} 回覆無法解析為 JSON 陣列，略過該角色結果。`);
+        log('步驟6', 'WRN', `攻擊方 ${role.meta.name} 回覆無法解析為 JSON 陣列，略過該角色結果。`);
         return [];
       }
       const list = parsed.map((f) => normalizeFinding(f, role)).filter(Boolean);
-      log('步驟5', 'INF', `攻擊方 ${role.meta.name} 完成：${list.length} 條問題。`);
+      log('步驟6', 'INF', `攻擊方 ${role.meta.name} 完成：${list.length} 條問題。`);
       return list;
     }),
   );
@@ -296,7 +296,7 @@ async function runAttackers({ tool, model, cwd, attackers, diffRows }) {
   merged.forEach((finding, index) => {
     finding.id = `F${String(index + 1).padStart(3, '0')}`;
   });
-  log('步驟5', 'INF', `全部攻擊方完成，合併後共 ${merged.length} 條問題。`);
+  log('步驟6', 'INF', `全部攻擊方完成，合併後共 ${merged.length} 條問題。`);
   return merged;
 }
 
@@ -309,7 +309,7 @@ async function runAttackers({ tool, model, cwd, attackers, diffRows }) {
  * @param {number} limit - 保留的最大字元數（超過即截斷）。
  * @returns {string} 截斷後的檔案內容；檔案不存在時為空字串。
  * @remarks
- * 使用情境：審查流程「步驟 7」{@link runDefenders} 以
+ * 使用情境：審查流程「步驟 8」{@link runDefenders} 以
  * `readCapped(<cwd>/.gitea/ai-review/exclusions.json, 20_000)`
  * 讀取已知排除事項，嵌入 {@link buildDefendPrompt} 的防守方提示，
  * 避免排除清單過長撐爆提示。本函式未匯出，僅供模組內部使用。
@@ -331,7 +331,7 @@ function readCapped(filePath, limit) {
  * @param {string} cwd - 工作目錄（repo 根目錄，findings 目錄位於其下 `.gitea/ai-review/findings`）。
  * @returns {string} 歷史 findings 摘要文字（Markdown 區段 + JSON）；無歷史時為空字串。
  * @remarks
- * 使用情境：審查流程「步驟 7」{@link runDefenders} 呼叫本函式取得歷史摘要，
+ * 使用情境：審查流程「步驟 8」{@link runDefenders} 呼叫本函式取得歷史摘要，
  * 嵌入 {@link buildDefendPrompt}，讓防守方能以「與歷史 findings 重複」為由裁決排除。
  * 本函式未匯出，僅供模組內部使用。
  */
@@ -379,7 +379,7 @@ function loadHistory(cwd) {
  * @param {string} historyText - {@link loadHistory} 產出的歷史 findings 摘要；空字串時提示顯示「（無）」。
  * @returns {string} 可直接餵給 `runAgent` stdin 的完整裁決提示字串。
  * @remarks
- * 使用情境：審查流程「步驟 7」{@link runDefenders} 為每個防守方角色各組一份提示，
+ * 使用情境：審查流程「步驟 8」{@link runDefenders} 為每個防守方角色各組一份提示，
  * 並行送入 sub agent 逐條裁決是否可排除（重複或誤判）。本函式未匯出，僅供模組內部使用。
  */
 function buildDefendPrompt(role, findings, exclusionsText, historyText) {
@@ -424,7 +424,7 @@ ${JSON.stringify(minimal, null, 2)}
 }
 
 /**
- * 步驟 7：每個防守方角色一個 sub agent 並行裁決 findings；
+ * 步驟 8：每個防守方角色一個 sub agent 並行裁決 findings；
  * 「全部防守方都判可排除」才移除該條，其餘一律保留（保守原則）。
  *
  * 失敗降級：某防守方執行失敗或回覆無法解析 → 該角色視為全部保留；
@@ -441,7 +441,7 @@ ${JSON.stringify(minimal, null, 2)}
  *   `kept`＝保留（至少一位防守方不同意排除）、`excluded`＝移除（全數防守方判可排除）；
  *   兩邊元素都已附 `verdicts`。
  * @remarks
- * 使用情境：審查流程「步驟 7」由 `src/index.js` 呼叫；`kept` 隨後經
+ * 使用情境：審查流程「步驟 8」由 `src/index.js` 呼叫；`kept` 隨後經
  * {@link sortFindings} 排序、依「嚴重」分組發留言（步驟 9／10），
  * `kept` 與 `excluded` 一併保存進 `.gitea/ai-review/findings/*.json`。
  */
@@ -451,7 +451,7 @@ async function runDefenders({ tool, model, cwd, defenders, findings }) {
   const historyText = loadHistory(cwd);
   const verdictsPerDefender = await Promise.all(
     defenders.map(async (role) => {
-      log('步驟7', 'INF', `防守方 ${role.meta.name} 開始裁決。`);
+      log('步驟8', 'INF', `防守方 ${role.meta.name} 開始裁決。`);
       const res = await runAgent(tool, {
         model,
         prompt: buildDefendPrompt(role, findings, exclusionsText, historyText),
@@ -459,7 +459,7 @@ async function runDefenders({ tool, model, cwd, defenders, findings }) {
       });
       const verdicts = new Map();
       if (!res.ok) {
-        log('步驟7', 'WRN', `防守方 ${role.meta.name} 執行失敗，該角色視為全部保留。`);
+        log('步驟8', 'WRN', `防守方 ${role.meta.name} 執行失敗，該角色視為全部保留。`);
         return { role: role.meta.name, verdicts };
       }
       const parsed = extractJson(res.output);
@@ -473,9 +473,9 @@ async function runDefenders({ tool, model, cwd, defenders, findings }) {
           }
         }
       } else {
-        log('步驟7', 'WRN', `防守方 ${role.meta.name} 回覆無法解析，該角色視為全部保留。`);
+        log('步驟8', 'WRN', `防守方 ${role.meta.name} 回覆無法解析，該角色視為全部保留。`);
       }
-      log('步驟7', 'INF', `防守方 ${role.meta.name} 完成裁決。`);
+      log('步驟8', 'INF', `防守方 ${role.meta.name} 完成裁決。`);
       return { role: role.meta.name, verdicts };
     }),
   );
@@ -493,7 +493,7 @@ async function runDefenders({ tool, model, cwd, defenders, findings }) {
     finding.verdicts = verdicts;
     (allExclude ? excluded : kept).push(finding);
   }
-  log('步驟7', 'INF', `裁決完成：保留 ${kept.length} 條、排除 ${excluded.length} 條。`);
+  log('步驟8', 'INF', `裁決完成：保留 ${kept.length} 條、排除 ${excluded.length} 條。`);
   return { kept, excluded };
 }
 
@@ -514,7 +514,7 @@ async function runDefenders({ tool, model, cwd, defenders, findings }) {
  *   false＝無排除問題、或既有檔案壞損／非陣列而略過寫入。
  * @throws {Error} 檔案系統寫入失敗（如權限不足）時由 fs 拋出，未攔截。
  * @remarks
- * 使用情境：`main()`（src/index.js）於步驟 7 防守方裁決後呼叫本函式，
+ * 使用情境：`main()`（src/index.js）於步驟 8 防守方裁決後呼叫本函式，
  * 並以回傳值決定收尾時是否把 exclusions.json 一併 commit
  * （一般模式：findings＋exclusions.json；建問題模式：只 commit exclusions.json）。
  */
@@ -527,11 +527,11 @@ function appendExclusions({ cwd, excluded, prNumber }) {
     try {
       entries = JSON.parse(fs.readFileSync(filePath, 'utf8'));
     } catch {
-      log('步驟7', 'WRN', 'exclusions.json 無法解析，為避免破壞既有內容不附加誤判紀錄（需人工確認）。');
+      log('步驟8', 'WRN', 'exclusions.json 無法解析，為避免破壞既有內容不附加誤判紀錄（需人工確認）。');
       return false;
     }
     if (!Array.isArray(entries)) {
-      log('步驟7', 'WRN', 'exclusions.json 非 JSON 陣列，為避免破壞既有內容不附加誤判紀錄（需人工確認）。');
+      log('步驟8', 'WRN', 'exclusions.json 非 JSON 陣列，為避免破壞既有內容不附加誤判紀錄（需人工確認）。');
       return false;
     }
   }
@@ -552,7 +552,7 @@ function appendExclusions({ cwd, excluded, prNumber }) {
   }
   fs.mkdirSync(dir, { recursive: true });
   fs.writeFileSync(filePath, `${JSON.stringify(entries, null, 2)}\n`, 'utf8');
-  log('步驟7', 'INF', `已將 ${excluded.length} 條誤判／重複問題附加到 exclusions.json。`);
+  log('步驟8', 'INF', `已將 ${excluded.length} 條誤判／重複問題附加到 exclusions.json。`);
   return true;
 }
 
@@ -565,7 +565,7 @@ function appendExclusions({ cwd, excluded, prNumber }) {
  * @param {Array<{severity: string, file: string, startLine: number}>} findings - 要排序的 finding 陣列（通常為 {@link runDefenders} 回傳的 `kept`）。
  * @returns {void} 無回傳值；排序結果反映在傳入陣列本身。
  * @remarks
- * 使用情境：審查流程「步驟 7」裁決完成後、保存 findings 與分組發留言之前，
+ * 使用情境：審查流程「步驟 8」裁決完成後、保存 findings 與分組發留言之前，
  * `src/index.js` 對 `kept` 呼叫本函式，確保步驟 9 逐條留言與步驟 10 彙整表格
  * 都以「嚴重度優先、同檔集中、行號遞增」的穩定順序呈現。
  */
@@ -758,7 +758,7 @@ function readSnippet(cwd, finding) {
 }
 
 /**
- * 步驟 8：將 PR 既有的 bot 留言標記為已解決，本回合剛發的留言除外。
+ * 步驟 2：將 PR 既有的 bot 留言標記為已解決，本回合剛發的留言除外。
  *
  * 兩類處理：
  * - 一般留言（bot 發、含隱藏標記、非本回合、尚未標註）→ 編輯加上「〔已過時〕」前綴。
@@ -772,15 +772,16 @@ function readSnippet(cwd, finding) {
  * @param {Set<number>} params.currentRunCommentIds - 本回合發出的一般留言 id 集合；這些留言不標註過時。
  * @returns {Promise<void>} 無回傳值；結果反映在 PR 留言狀態與日誌。
  * @remarks
- * 使用情境：審查流程「步驟 8」在防守方裁決、保存 findings 之後、
- * 發布本回合嚴重問題留言（步驟 9）之前呼叫，確保 PR 上只有最新回合的審查結果醒目可見。
+ * 使用情境：審查流程「步驟 2」在步驟 1 快速回報與前置檢查之後、偵測工具（步驟 3）
+ * 與所有本回合留言之前呼叫；此時本回合尚未發出任何留言（currentRunCommentIds 為空），
+ * 之後發出的留言自然不受影響，確保 PR 上只有最新回合的審查結果醒目可見。
  */
 async function resolveOldComments({ ctx, gitea, currentRunCommentIds }) {
   let botLogin = '';
   try {
     botLogin = (await gitea.whoAmI(ctx)).login || '';
   } catch (err) {
-    log('步驟8', 'WRN', `無法取得 bot 身分（${err.message}），略過留言解決。`);
+    log('步驟2', 'WRN', `無法取得 bot 身分（${err.message}），略過留言解決。`);
     return;
   }
 
@@ -797,9 +798,9 @@ async function resolveOldComments({ ctx, gitea, currentRunCommentIds }) {
       await gitea.editIssueComment(ctx, comment.id, `${templates.OUTDATED_PREFIX}${comment.body}`);
       outdatedCount += 1;
     }
-    log('步驟8', 'INF', `一般留言已標註〔已過時〕：${outdatedCount} 則。`);
+    log('步驟2', 'INF', `一般留言已標註〔已過時〕：${outdatedCount} 則。`);
   } catch (err) {
-    log('步驟8', 'WRN', `標註一般留言失敗：${err.message}。`);
+    log('步驟2', 'WRN', `標註一般留言失敗：${err.message}。`);
   }
 
   // review 程式碼留言：盡力 resolve；API 不支援（第一次就失敗）即停止嘗試。
@@ -825,12 +826,12 @@ async function resolveOldComments({ ctx, gitea, currentRunCommentIds }) {
       }
     }
     if (resolveSupported) {
-      log('步驟8', 'INF', `review 程式碼留言已解決：${resolvedCount} 則。`);
+      log('步驟2', 'INF', `review 程式碼留言已解決：${resolvedCount} 則。`);
     } else {
-      log('步驟8', 'WRN', 'Gitea 版本不支援 resolve API，review 程式碼留言維持原狀（已解決 ' + resolvedCount + ' 則）。');
+      log('步驟2', 'WRN', 'Gitea 版本不支援 resolve API，review 程式碼留言維持原狀（已解決 ' + resolvedCount + ' 則）。');
     }
   } catch (err) {
-    log('步驟8', 'WRN', `解決 review 留言失敗：${err.message}。`);
+    log('步驟2', 'WRN', `解決 review 留言失敗：${err.message}。`);
   }
 }
 

src/lib/roles.js

@@ -23,7 +23,7 @@ const path = require('path');
  * @throws {Error} 當 `rolesDir` 不存在、無法讀取，或個別檔案讀取失敗時，
  *   由 `fs.readdirSync` / `fs.readFileSync` 直接拋出（未在函式內捕捉）。
  * @remarks
- * 使用情境：`src/index.js` 於審查流程步驟 4 呼叫
+ * 使用情境：`src/index.js` 於審查流程步驟 5 呼叫
  * `loadRoles(path.join(ctx.actionPath, 'src', 'prompts', 'roles'))` 載入全部角色，
  * 再以 {@link attackersOf} / {@link defendersOf} 依 frontmatter 的 `side` 欄位
  * 分出攻擊方（Mage/Assassin/Rogue/Bard/Leo/Maya）與防守方（Paladin），

src/lib/templates.js

@@ -2,10 +2,10 @@
 
 // 固定留言模板：本 action 發到 PR 的留言一律由此產生（繁體中文、UTF-8、表格優先）。
 
-// 隱藏標記：辨識哪些留言是本 action 發的（步驟 8 標註過時時使用）。
+// 隱藏標記：辨識哪些留言是本 action 發的（步驟 2 標註過時時使用）。
 const MARK = '<!-- ai-code-review -->';
 
-// 舊留言標註前綴（步驟 8 的降級做法：無 resolve API 時編輯加註）。
+// 舊留言標註前綴（步驟 2 的降級做法：無 resolve API 時編輯加註）。
 const OUTDATED_PREFIX = '> 〔已過時〕本留言屬於較舊的審查回合。\n\n';
 
 // 嚴重等級對應的 emoji 與排序權重。
@@ -33,7 +33,7 @@ const FOCUS_LABEL = {
  * @param {*} text - 任意待處理內容；非字串會先以 `String()` 轉型，null／undefined 視為空字串。
  * @returns {string} 已逸出、單行化的儲存格內容；若結果為空則回傳 `'—'`。
  * @remarks
- * 使用情境：審查流程中所有表格型留言的共用防呆——例如步驟 3 的
+ * 使用情境：審查流程中所有表格型留言的共用防呆——例如步驟 4 的
  * `diffComment()` 產生變更摘要表格時，檔名與用途欄位都經本函式處理，
  * 避免檔名或 AI 產生的描述含 `|` 或換行而撐破 Markdown 表格。
  * 本函式未匯出，僅供模組內部使用。
@@ -55,7 +55,7 @@ function cell(text) {
  * @param {string} focus - 審查面向代碼（例如 `'logic'`、`'security'`）；可為 undefined。
  * @returns {string} 顯示字串：命中時如 `'邏輯（logic）'`；未命中時原樣回傳 `focus`；falsy 時回傳 `'—'`。
  * @remarks
- * 使用情境：審查流程步驟 4／6 的角色登場留言——`rolesComment()`
+ * 使用情境：審查流程步驟 5／6 的角色登場留言——`rolesComment()`
  * 產生「角色｜面向｜個性」表格時，以本函式把每位審查員
  * （攻擊方／防守方）的 focus 代碼轉成中英並列的面向欄位內容。
  * 本函式未匯出，僅供模組內部使用。
@@ -66,7 +66,7 @@ function focusLabel(focus) {
 }
 
 /**
- * 產生審查流程步驟 2 的「審查工具」PR 留言內容。
+ * 產生審查流程步驟 3 的「審查工具」PR 留言內容。
  *
  * 留言以隱藏標記 `MARK` 開頭，包含工具資訊表格（工具／版本／模型／
  * 審查 commit／Run Job 連結）與一張 mermaid 流程圖，說明整條審查管線
@@ -81,9 +81,9 @@ function focusLabel(focus) {
  * @param {string} params.runLink - CI run 的網址，直接內插為 Markdown 連結目標。
  * @returns {string} 完整留言 Markdown 字串（含 MARK 隱藏標記，結尾帶換行）。
  * @remarks
- * 使用情境：審查流程步驟 2——每回合審查開始時，先把工具身分與
+ * 使用情境：審查流程步驟 3——每回合審查開始時，先把工具身分與
  * 管線流程圖留言到 PR，讓開發者知道這回合由哪個版本／模型執行；
- * 留言開頭的 MARK 讓步驟 8 能辨識並將舊回合留言標註為過時。
+ * 留言開頭的 MARK 讓步驟 2 能辨識並將舊回合留言標註為過時。
  */
 function toolComment({ toolName, version, model, sha, runNumber, runLink }) {
   return `${MARK}
@@ -108,7 +108,7 @@ flowchart LR
 }
 
 /**
- * 產生審查流程步驟 3 的「變更摘要（送審 git diff）」PR 留言內容。
+ * 產生審查流程步驟 4 的「變更摘要（送審 git diff）」PR 留言內容。
  *
  * 以四欄表格（檔案／用途／git diff 長度／最後更新時間）列出本回合
  * 送審的每個檔案；diff 過長被截斷送審的檔案會加註「（過長截斷送審）」，
@@ -125,7 +125,7 @@ flowchart LR
  * @param {number} ignoredCount - 依 `.reviewignore` 排除的檔案數；大於 0 才顯示排除註記。
  * @returns {string} 完整留言 Markdown 字串（含 MARK 隱藏標記）。
  * @remarks
- * 使用情境：審查流程步驟 3——整理完 git diff 後，把「哪些檔案、多長、
+ * 使用情境：審查流程步驟 4——整理完 git diff 後，把「哪些檔案、多長、
  * 是否截斷、哪些被 .reviewignore 排除」留言到 PR，讓開發者確認送審範圍
  * 與 AI 實際看到的內容一致。
  */
@@ -150,10 +150,10 @@ function diffComment(rows, ignoredCount) {
 }
 
 /**
- * 產生審查流程步驟 4／6 共用的「角色登場」PR 留言內容。
+ * 產生審查流程步驟 5／6 共用的「角色登場」PR 留言內容。
  *
  * 以三欄表格（角色／面向／個性）列出本回合登場的審查員；
- * 攻擊方（步驟 4）與防守方（步驟 6）共用本模板，僅標題不同。
+ * 攻擊方（步驟 5）與防守方（步驟 7）共用本模板，僅標題不同。
  * 面向欄位經 focusLabel() 轉成「中文（原文）」並列格式。
  *
  * @param {Object} params - 留言內容（解構參數）。
@@ -166,7 +166,7 @@ function diffComment(rows, ignoredCount) {
  * @param {string} params.roles[].meta.personality - 角色個性描述；經 cell() 防呆。
  * @returns {string} 完整留言 Markdown 字串（含 MARK 隱藏標記）。
  * @remarks
- * 使用情境：審查流程步驟 4（攻擊方登場）與步驟 6（防守方登場）——
+ * 使用情境：審查流程步驟 5（攻擊方登場）與步驟 7（防守方登場）——
  * 在各階段開始審查前，把該回合參與的審查員角色、負責面向與個性
  * 留言到 PR，讓開發者理解後續 findings 是由哪些視角產出的。
  */
@@ -371,7 +371,7 @@ function issueFindingComment(finding) {
  * @param {number} ignoredCount - 依 `.reviewignore` 排除的檔案數；大於 0 才顯示「（N 個檔案被排除）」註記。
  * @returns {string} 完整留言 Markdown 字串（含 MARK 隱藏標記）。
  * @remarks
- * 使用情境：審查流程步驟 3 的替代路徑——整理 git diff 時發現
+ * 使用情境：審查流程步驟 4 的替代路徑——整理 git diff 時發現
  * 過濾後送審清單為空（例如整包變更都被 .reviewignore 排除），
  * 直接以本留言告知開發者本回合視為審查通過，不再進入
  * 攻擊方／防守方審查階段。