docs(審查步驟編號): 依新順序重編步驟編號與說明

refactor(審查流程): 將舊留言標記移到偵測 AI 工具之前
chore: update ai-review findings [ai-review-bot][success]
2026-07-20 09:46:12 +08:00 · 2026-07-20 09:46:12 +08:00 · 2026-07-17 11:03:14 +00:00 · 2026-07-17 19:02:42 +08:00 · 2026-07-17 18:54:00 +08:00 · 2026-07-17 18:26:49 +08:00
12 changed files with 370 additions and 199 deletions
@@ -0,0 +1,12 @@
 {
  "generatedAt": "2026/07/17 19:03:13",
  "commitSha": "c4c23d45314bb260d7ec350db4f968021076ee17",
  "prNumber": 4,
  "tool": {
    "name": "codex",
    "version": "codex-cli 0.144.5",
    "model": "（工具預設）"
  },
  "findings": [],
  "excluded": []
 }
@@ -1,19 +1,92 @@
 # ============================================================================
 # 用途：在 pull request 針對 develop 分支開啟或同步時，分別以 Antigravity、Codex、Claude 環境執行本機 AI Code Review action。
 # 更新時間：2026/07/17 18:49:58
 # ============================================================================
 # Workflow 顯示名稱。
 name: CI
 # Workflow 觸發條件區塊。
 on:
  # 以 pull request 事件觸發。
  pull_request:
    # 限定 pull request 目標分支。
    branches:
    # 僅在目標分支為 develop 時執行。
    - develop
    # 限定 pull request 開啟與同步更新時執行。
    types: [opened, synchronize]
 # Job 定義區塊。
 jobs:
-  test:
+  # Antigravity 工具環境測試 job。
-    name: TEST
+  test-antigravity:
    # Job 在 workflow UI 顯示的名稱。
    name: TEST (Antigravity)
    # 指定執行 runner 標籤；需人工確認本 Gitea runner 是否使用 ubuntu 標籤。
    runs-on: ubuntu
    # Job 執行步驟。
    steps:
    # 取得存取庫內容供後續 action 使用。
    - name: 取得存取庫資訊
      # 使用呼叫端 vars 指定的 checkout action 版本。
      uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
    # 安裝 Antigravity 工具環境。
    - name: 安裝工具
      # 使用 Gitea composite action 安裝 Antigravity，版本由 vars 指定。
      uses: https://gitea.jsc.idv.tw/composite-actions/setup-antigravity@${{ vars.ACTION_SETUP_ANTIGRAVITY_VERSION }}
    # 執行目前存取庫的 AI Code Review action。
    - name: 程式碼審查
      # 以目前存取庫根目錄的 action.yml 作為 action 來源。
      uses: ./
-    - name: 取得工具版本號
+      # 傳入 action inputs。
-      run: agy --version
+      with:
        # Gitea / GitHub token，用於 PR 留言與 findings 寫回。
        token: ${{ secrets.GITHUB_TOKEN }}
  # Codex 工具環境測試 job。
  test-codex:
    # Job 在 workflow UI 顯示的名稱。
    name: TEST (Codex)
    # 指定執行 runner 標籤；需人工確認本 Gitea runner 是否使用 ubuntu 標籤。
    runs-on: ubuntu
    # Job 執行步驟。
    steps:
    # 取得存取庫內容供後續 action 使用。
    - name: 取得存取庫資訊
      # 使用呼叫端 vars 指定的 checkout action 版本。
      uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
    # 安裝 Codex 工具環境。
    - name: 安裝工具
      # 使用 Gitea composite action 安裝 Codex，版本由 vars 指定。
      uses: https://gitea.jsc.idv.tw/composite-actions/setup-codex@${{ vars.ACTION_SETUP_CODEX_VERSION }}
    # 執行目前存取庫的 AI Code Review action。
    - name: 程式碼審查
      # 以目前存取庫根目錄的 action.yml 作為 action 來源。
      uses: ./
      # 傳入 action inputs。
      with:
        # Gitea / GitHub token，用於 PR 留言與 findings 寫回。
        token: ${{ secrets.GITHUB_TOKEN }}
  # Claude 工具環境測試 job。
  test-claude:
    # Job 在 workflow UI 顯示的名稱。
    name: TEST (Claude)
    # 指定執行 runner 標籤；需人工確認本 Gitea runner 是否使用 ubuntu 標籤。
    runs-on: ubuntu
    # Job 執行步驟。
    steps:
    # 取得存取庫內容供後續 action 使用。
    - name: 取得存取庫資訊
      # 使用呼叫端 vars 指定的 checkout action 版本。
      uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
    # 安裝 Claude 工具環境。
    - name: 安裝工具
      # 使用 Gitea composite action 安裝 Claude，版本由 vars 指定。
      uses: https://gitea.jsc.idv.tw/composite-actions/setup-claude@${{ vars.ACTION_SETUP_CLAUDE_VERSION }}
    # 執行目前存取庫的 AI Code Review action。
    - name: 程式碼審查
      # 以目前存取庫根目錄的 action.yml 作為 action 來源。
      uses: ./
      # 傳入 action inputs。
      with:
        # Gitea / GitHub token，用於 PR 留言與 findings 寫回。
        token: ${{ secrets.GITHUB_TOKEN }}
@@ -0,0 +1,41 @@
 # Workflow 文件草稿
 更新時間：2026/07/17 18:49:58
 ## Workflow 總覽
 | 名稱 | 檔案位置 | 用途 | 觸發條件 |
 | --- | --- | --- | --- |
 | CI | `.gitea/workflows/ci.yaml` | 在 PR 事件中分別以 Antigravity、Codex、Claude 工具環境執行本存取庫的 AI Code Review action，驗證 action 可在不同 AI 工具環境下運作。 | `pull_request` 目標分支為 `develop`，事件類型為 `opened` 或 `synchronize`。 |
 ## CI
 - Workflow 名稱：`CI`
 - 檔案位置：`.gitea/workflows/ci.yaml`
 - 用途：針對送往 `develop` 的 pull request 執行三組測試 job，分別安裝 Antigravity、Codex、Claude 環境後呼叫 `uses: ./` 執行目前 action。
 - 觸發條件：`pull_request.branches` 為 `develop`；`pull_request.types` 為 `opened`、`synchronize`。
 ## Job
 | Job ID | 顯示名稱 | Runner | 主要流程 |
 | --- | --- | --- | --- |
 | `test-antigravity` | `TEST (Antigravity)` | `ubuntu` | checkout 存取庫、安裝 Antigravity、執行本地 action。 |
 | `test-codex` | `TEST (Codex)` | `ubuntu` | checkout 存取庫、安裝 Codex、執行本地 action。 |
 | `test-claude` | `TEST (Claude)` | `ubuntu` | checkout 存取庫、安裝 Claude、執行本地 action。 |
 ## 主要輸入 / 環境參數
 | 名稱 | 來源 | 使用位置 | 說明 |
 | --- | --- | --- | --- |
 | `vars.ACTION_CHECKOUT_VERSION` | Gitea / GitHub repository 或 organization vars | `actions/checkout@...` | 指定 checkout action 版本。 |
 | `vars.ACTION_SETUP_ANTIGRAVITY_VERSION` | Gitea / GitHub vars | `setup-antigravity@...` | 指定 Antigravity 安裝 action 版本。 |
 | `vars.ACTION_SETUP_CODEX_VERSION` | Gitea / GitHub vars | `setup-codex@...` | 指定 Codex 安裝 action 版本。 |
 | `vars.ACTION_SETUP_CLAUDE_VERSION` | Gitea / GitHub vars | `setup-claude@...` | 指定 Claude 安裝 action 版本。 |
 | `secrets.GITHUB_TOKEN` | Gitea / GitHub secrets | 本地 action input `token` | 提供 action 呼叫 Gitea API 留言與寫回 findings 所需 token。 |
 ## 注意事項
 - `.gitea/workflows/readme.md` 目前不存在；本檔為新增 workflow README 的草稿。
 - `runs-on: ubuntu` 是否符合實際 Gitea runner 標籤需人工確認。
 - `vars.*` 與 `secrets.GITHUB_TOKEN` 必須由呼叫端環境提供，否則 checkout、工具安裝或程式碼審查步驟可能失敗。
 - 三個 job 均以 `uses: ./` 呼叫目前存取庫根目錄的 `action.yml`；因此 `action.yml` 的 `runs.main` 需保持可被 runner 直接執行。
@@ -1,53 +1,53 @@
-# =====================================================
+# ============================================================================
-# 用途    : AI 多角色 code review：攻擊方找問題、防守方裁決誤報，結果留言到 PR 並保存 findings
+# 用途：定義 AI Code Review Node action 的名稱、輸入參數與 Node.js 24 進入點，供 Gitea / GitHub workflow 以 uses 引用。
-# 更新時間: 2026/07/17 16:49:21
+# 更新時間：2026/07/17 18:49:58
-# =====================================================
+# ============================================================================
 # Gitea / GitHub node action 的 manifest（action.yml）：
 # 定義本 action 的名稱、說明、輸入參數（inputs）與執行方式（runs），
 # 供呼叫端 workflow 以 `uses:` 引用；runner 讀取此檔後以 node24 執行 src/index.js。
-# action 顯示名稱：呼叫端 workflow log 與 marketplace 列表上看到的名稱
+# action 顯示名稱：呼叫端 workflow log 與 marketplace 列表上看到的名稱。
 name: 'AI Code Review'
 # action 用途說明：多角色 AI code review 流程（攻擊方找問題、防守方裁決誤報），
-# 審查結果會留言到 PR 並保存 findings（.gitea/ai-review/findings/）
+# 審查結果會留言到 PR 並保存 findings（.gitea/ai-review/findings/）。
 description: 'AI 多角色 code review：攻擊方找問題、防守方裁決誤報，結果留言到 PR 並保存 findings'
-# action 作者資訊（僅供辨識，不影響執行）
+# action 作者資訊（僅供辨識，不影響執行）。
 author: 'Jeffery'
 # 輸入參數區塊：呼叫端 workflow 以 `with:` 傳入，
-# runner 會自動注入為 INPUT_* 環境變數（例如 INPUT_TOKEN、INPUT_MODEL、INPUT_CREATE-ISSUE）供主程式讀取
+# runner 會自動注入為 INPUT_* 環境變數（例如 INPUT_TOKEN、INPUT_MODEL、INPUT_CREATE-ISSUE）供主程式讀取。
 inputs:
-  # Gitea API token：用於對 PR 留言審查結果、以及 push 審查結果檔回 repo
+  # Gitea API token：用於對 PR 留言審查結果、以及 push 審查結果檔回 repo。
  token:
    # 參數用途說明：secrets/vars context 在 action 內不可用，
-    # 故由呼叫端 workflow 以 secrets.GITHUB_TOKEN 傳入
+    # 故由呼叫端 workflow 以 secrets.GITHUB_TOKEN 傳入。
    description: 'Gitea API token（PR 留言與 push findings 用；呼叫端以 secrets.GITHUB_TOKEN 傳入）'
-    # 必填：缺少 token 無法呼叫 Gitea API，action 無法運作
+    # 必填：缺少 token 無法呼叫 Gitea API，action 無法運作。
    required: true
-  # 指定 AI 工具使用的模型名稱
+  # 指定 AI 工具使用的模型名稱。
  model:
-    # 參數用途說明：留空表示使用各 AI 工具自身的預設模型
+    # 參數用途說明：留空表示使用各 AI 工具自身的預設模型。
    description: '指定 AI 工具使用的模型（空值＝各工具預設）'
-    # 選填：未指定時採用預設值
+    # 選填：未指定時採用預設值。
    required: false
-    # 預設為空字串，代表不覆寫各工具的預設模型
+    # 預設為空字串，代表不覆寫各工具的預設模型。
    default: ''
-  # 建問題模式開關：是否把審查保留的問題另建 issue 追蹤
+  # 建問題模式開關：是否把審查保留的問題另建 issue 追蹤。
  create-issue:
-    # 參數用途說明：字串 'true' 時建立 issue（標題＝PR 標題、描述＝PR 描述、AI 挑標籤）
+    # 參數用途說明：字串 'true' 時建立 issue（標題＝PR 標題、描述＝PR 描述、AI 挑標籤），
    # 並逐條留言問題明細，findings 檔不進版控、收尾只 commit exclusions.json；
-    # 預設 'false' 走原流程（findings 檔與 exclusions.json 一併 commit 回 PR 來源分支）
+    # 預設 'false' 走原流程（findings 檔與 exclusions.json 一併 commit 回 PR 來源分支）。
    description: '是否將問題建到存取庫的問題追蹤（true 時建立 issue 逐條留言問題明細，最後只 commit exclusions.json；預設 false 走原流程）'
-    # 選填：未指定時採用預設值
+    # 選填：未指定時採用預設值。
    required: false
-    # 預設為字串 'false'，代表不啟用建問題模式（主程式只認字串 'true' 才啟用）
+    # 預設為字串 'false'，代表不啟用建問題模式（主程式只認字串 'true' 才啟用）。
    default: 'false'
-# 執行方式區塊：宣告本 action 為 node action 及其進入點
+# 執行方式區塊：宣告本 action 為 node action 及其進入點。
 runs:
-  # 以 Node.js 24 runtime 直接在 runner 上執行（非 Docker 容器、非 composite）
+  # 以 Node.js 24 runtime 直接在 runner 上執行（非 Docker 容器、非 composite）。
  using: 'node24'
-  # 主程式進入點：直接指向 src/index.js（entry point）
+  # 主程式進入點：直接指向 src/index.js（entry point）。
  # 主程式為零外部相依（package.json 無 dependencies，src 僅 require Node 內建模組與本地 lib），
  # runner 不會自動 npm install，零相依時依 node action 慣例 main 直接指向 src/index.js 即正確；
-  # 日後若新增外部相依，需改以 @vercel/ncc 打包（package.json 已備有 build script）
+  # 日後若新增外部相依，需改以 @vercel/ncc 打包（package.json 已備有 build script），
-  # 並將 main 改指 dist/index.js、把 dist/ commit 進 repo
+  # 並將 main 改指 dist/index.js、把 dist/ commit 進 repo。
  main: 'src/index.js'
@@ -1,6 +1,6 @@
 # AI Code Review
-> 更新時間：2026/07/17 16:49:21
+> 更新時間：2026/07/17 18:49:58
 AI 多角色 code review 的 Gitea **node action**（`node24`、零外部相依）：以攻擊方六角色（🔮 Mage 邏輯、🗡️ Assassin 安全、⚡ Rogue 效率、🎼 Bard 風格、🧪 Maya 測試、🧰 Leo 可維護性）並行找問題、防守方（🛡️ Paladin）裁決誤報，結果留言到 PR、保存 findings，並以 bot commit 標記審查結果（`[success]`／`[failure]`）供下次觸發快速回報。
@@ -38,13 +38,13 @@ jobs:
 ```mermaid
 flowchart TD
    S1[1 判斷 bot commit 標記] -->|命中| E0[直接回報 success/failure]
-    S1 -->|未命中| S2[2 偵測 AI 工具並留言]
+    S1 -->|未命中| S2[2 舊留言標記解決]
-    S2 --> S3[3 讀 .reviewignore 整理 diff 並留言]
+    S2 --> S3[3 偵測 AI 工具並留言]
-    S3 --> S4[4 攻擊方登場留言]
+    S3 --> S4[4 讀 .reviewignore 整理 diff 並留言]
-    S4 --> S5[5 攻擊方 sub agent 並行找問題]
+    S4 --> S5[5 攻擊方登場留言]
-    S5 --> S6[6 防守方登場留言]
+    S5 --> S6[6 攻擊方 sub agent 並行找問題]
-    S6 --> S7[7 防守方裁決 → 保存 findings ＋ 誤判回寫 exclusions.json]
+    S6 --> S7[7 防守方登場留言]
-    S7 --> S8[8 舊留言標記解決]
+    S7 --> S8[8 防守方裁決 → 保存 findings ＋ 誤判回寫 exclusions.json]
    S8 --> S9[9 嚴重問題逐條掛行留言]
    S9 --> S10[10 警告＋建議彙整表格留言]
    S10 --> E1[收尾 commit/push ＋ exit code]
@@ -56,19 +56,19 @@ flowchart TD
 | 專案名稱 | 專案描述 |
 | --- | --- |
-| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/) | Gitea node action：提供台北時區日誌工具、runner 上下文載入、git diff／commit 操作、Gitea REST API 客戶端（留言／review／issue／標籤）、AI CLI 工具偵測與 sub agent 執行、角色提示載入、固定留言模板，以及多角色審查編排（攻擊方找問題、防守方裁決、findings 保存、誤判回寫、建問題模式） |
+| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/) | Gitea node action：提供台北時區日誌工具、runner 上下文載入、git diff／commit 操作、Gitea REST API 客戶端（留言／review／issue／標籤）、AI CLI 工具偵測與 sub agent 執行、角色提示載入、固定留言模板，以及多角色審查編排（攻擊方找問題、防守方裁決、findings 保存、誤判回寫、建問題模式） |
 ### 參考專案表
 | 專案名稱 | 參考專案列表 |
 | --- | --- |
-| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/) | 無 |
+| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/) | 無 |
 ### NuGet 套件表
 | 專案名稱 | NuGet 套件列表 |
 | --- | --- |
-| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/) | 無 |
+| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/) | 無 |
 ## 功能列表
@@ -76,56 +76,56 @@ flowchart TD
 | 功能名稱 | 功能描述 |
 | --- | --- |
-| [log.taipeiNow](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/log.js#L20) | [取得台北時區 yyyy/MM/dd HH:mm:ss 時間字串](#logtaipeinow) |
+| [log.taipeiNow](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/log.js#L20) | [取得台北時區 yyyy/MM/dd HH:mm:ss 時間字串](#logtaipeinow) |
-| [log.taipeiFileStamp](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/log.js#L41) | [取得檔名用時間戳 yyyy-MM-dd-HH:mm:ss](#logtaipeifilestamp) |
+| [log.taipeiFileStamp](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/log.js#L41) | [取得檔名用時間戳 yyyy-MM-dd-HH:mm:ss](#logtaipeifilestamp) |
-| [log.taipeiFromIso](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/log.js#L60) | [將 ISO 時間字串轉為台北時區顯示字串](#logtaipeifromiso) |
+| [log.taipeiFromIso](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/log.js#L60) | [將 ISO 時間字串轉為台北時區顯示字串](#logtaipeifromiso) |
-| [log.log](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/log.js#L83) | [以統一格式輸出一行日誌](#loglog) |
+| [log.log](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/log.js#L83) | [以統一格式輸出一行日誌](#loglog) |
-| [context.loadContext](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/context.js#L64) | [彙整 runner 環境變數與事件 payload 為執行上下文](#contextloadcontext) |
+| [context.loadContext](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/context.js#L64) | [彙整 runner 環境變數與事件 payload 為執行上下文](#contextloadcontext) |
-| [gitrepo.latestCommitSubject](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitrepo.js#L60) | [取得最新 commit 的訊息標題](#gitrepolatestcommitsubject) |
+| [gitrepo.latestCommitSubject](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js#L79) | [取得最新 commit 的訊息標題](#gitrepolatestcommitsubject) |
-| [gitrepo.resolveMergeBase](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitrepo.js#L81) | [解析 base 分支與 HEAD 的 merge-base](#gitreporesolvemergebase) |
+| [gitrepo.resolveMergeBase](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js#L100) | [解析 base 分支與 HEAD 的 merge-base](#gitreporesolvemergebase) |
-| [gitrepo.changedFiles](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitrepo.js#L104) | [列出 base 與 HEAD 之間有變更的檔案](#gitrepochangedfiles) |
+| [gitrepo.changedFiles](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js#L136) | [列出 base 與 HEAD 之間有變更的檔案](#gitrepochangedfiles) |
-| [gitrepo.fileDiff](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitrepo.js#L125) | [取得單一檔案的 git diff 內容](#gitrepofilediff) |
+| [gitrepo.fileDiff](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js#L157) | [取得單一檔案的 git diff 內容](#gitrepofilediff) |
-| [gitrepo.fileLastUpdatedIso](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitrepo.js#L143) | [取得檔案最後一次 commit 的 ISO 時間](#gitrepofilelastupdatediso) |
+| [gitrepo.fileLastUpdatedIso](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js#L175) | [取得檔案最後一次 commit 的 ISO 時間](#gitrepofilelastupdatediso) |
-| [gitrepo.commitAndPushFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitrepo.js#L181) | [以 bot 身分 commit 結果檔並 push 回 PR 來源分支](#gitrepocommitandpushfindings) |
+| [gitrepo.commitAndPushFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js#L213) | [以 bot 身分 commit 結果檔並 push 回 PR 來源分支](#gitrepocommitandpushfindings) |
-| [gitea.whoAmI](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L87) | [取得 token 對應的使用者（bot 身分）](#giteawhoami) |
+| [gitea.whoAmI](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L87) | [取得 token 對應的使用者（bot 身分）](#giteawhoami) |
-| [gitea.createCommentOnIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L106) | [對指定編號 issue／PR 新增一般留言](#giteacreatecommentonissue) |
+| [gitea.createCommentOnIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L106) | [對指定編號 issue／PR 新增一般留言](#giteacreatecommentonissue) |
-| [gitea.createIssueComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L124) | [對本次 PR 新增一般留言](#giteacreateissuecomment) |
+| [gitea.createIssueComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L124) | [對本次 PR 新增一般留言](#giteacreateissuecomment) |
-| [gitea.listLabels](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L141) | [列出存取庫可用標籤](#gitealistlabels) |
+| [gitea.listLabels](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L141) | [列出存取庫可用標籤](#gitealistlabels) |
-| [gitea.createIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L164) | [在存取庫建立 issue（可掛標籤）](#giteacreateissue) |
+| [gitea.createIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L164) | [在存取庫建立 issue（可掛標籤）](#giteacreateissue) |
-| [gitea.listIssueComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L184) | [列出 PR 全部一般留言（自動分頁）](#gitealistissuecomments) |
+| [gitea.listIssueComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L184) | [列出 PR 全部一般留言（自動分頁）](#gitealistissuecomments) |
-| [gitea.editIssueComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L202) | [編輯既有一般留言](#giteaeditissuecomment) |
+| [gitea.editIssueComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L202) | [編輯既有一般留言](#giteaeditissuecomment) |
-| [gitea.createReview](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L223) | [建立 code review 並掛行內留言](#giteacreatereview) |
+| [gitea.createReview](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L223) | [建立 code review 並掛行內留言](#giteacreatereview) |
-| [gitea.listReviews](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L243) | [列出 PR 全部 review（自動分頁）](#gitealistreviews) |
+| [gitea.listReviews](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L243) | [列出 PR 全部 review（自動分頁）](#gitealistreviews) |
-| [gitea.listReviewComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L264) | [列出某 review 的全部行內留言](#gitealistreviewcomments) |
+| [gitea.listReviewComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L264) | [列出某 review 的全部行內留言](#gitealistreviewcomments) |
-| [gitea.tryResolveReviewComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/gitea.js#L287) | [盡力將行內留言標記為已解決](#giteatryresolvereviewcomment) |
+| [gitea.tryResolveReviewComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js#L287) | [盡力將行內留言標記為已解決](#giteatryresolvereviewcomment) |
-| [agents.detectTool](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/agents.js#L53) | [依優先序偵測可用的 AI CLI 工具](#agentsdetecttool) |
+| [agents.detectTool](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/agents.js#L53) | [依優先序偵測可用的 AI CLI 工具](#agentsdetecttool) |
-| [agents.runAgent](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/agents.js#L98) | [非互動執行一次 sub agent 並取回回覆](#agentsrunagent) |
+| [agents.runAgent](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/agents.js#L98) | [非互動執行一次 sub agent 並取回回覆](#agentsrunagent) |
-| [agents.extractJson](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/agents.js#L144) | [從 agent 回覆萃取 JSON（容忍雜訊）](#agentsextractjson) |
+| [agents.extractJson](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/agents.js#L144) | [從 agent 回覆萃取 JSON（容忍雜訊）](#agentsextractjson) |
-| [roles.loadRoles](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/roles.js#L32) | [載入角色提示檔並解析 frontmatter](#rolesloadroles) |
+| [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/master/src/lib/roles.js#L71) | [過濾出攻擊方角色](#rolesattackersof) |
+| [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/master/src/lib/roles.js#L90) | [過濾出防守方角色](#rolesdefendersof) |
+| [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/master/src/lib/templates.js#L88) | [產生步驟 2 審查工具留言](#templatestoolcomment) |
+| [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/master/src/lib/templates.js#L132) | [產生步驟 3 變更摘要留言](#templatesdiffcomment) |
+| [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/master/src/lib/templates.js#L173) | [產生步驟 4／6 角色登場留言](#templatesrolescomment) |
+| [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/master/src/lib/templates.js#L215) | [產生步驟 9 單條嚴重問題留言](#templatesseverecommentbody) |
+| [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/master/src/lib/templates.js#L247) | [產生步驟 9 嚴重問題 review 總覽](#templatesseverereviewbody) |
+| [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/master/src/lib/templates.js#L277) | [產生步驟 10 警告＋建議彙整表格留言](#templatesotherscomment) |
+| [templates.othersComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L277) | [產生步驟 10 警告＋建議彙整表格留言](#templatesotherscomment) |
-| [templates.issueBody](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/templates.js#L309) | [產生建問題模式的 issue 本文](#templatesissuebody) |
+| [templates.issueBody](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L309) | [產生建問題模式的 issue 本文](#templatesissuebody) |
-| [templates.issueFindingComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/templates.js#L341) | [產生建問題模式單條問題的 issue 留言](#templatesissuefindingcomment) |
+| [templates.issueFindingComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L341) | [產生建問題模式單條問題的 issue 留言](#templatesissuefindingcomment) |
-| [templates.nothingToReviewComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/templates.js#L379) | [產生無可審查變更留言](#templatesnothingtoreviewcomment) |
+| [templates.nothingToReviewComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js#L379) | [產生無可審查變更留言](#templatesnothingtoreviewcomment) |
-| [review.loadReviewIgnore](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L29) | [讀取 .reviewignore 忽略前綴清單](#reviewloadreviewignore) |
+| [review.loadReviewIgnore](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L29) | [讀取 .reviewignore 忽略前綴清單](#reviewloadreviewignore) |
-| [review.isIgnored](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L53) | [判斷檔案是否忽略不送審](#reviewisignored) |
+| [review.isIgnored](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L53) | [判斷檔案是否忽略不送審](#reviewisignored) |
-| [review.collectDiffRows](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L77) | [整理送審 diff 資料列（含長度上限）](#reviewcollectdiffrows) |
+| [review.collectDiffRows](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L77) | [整理送審 diff 資料列（含長度上限）](#reviewcollectdiffrows) |
-| [review.fillPurposes](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L127) | [以 AI 補齊每個檔案的一行用途描述](#reviewfillpurposes) |
+| [review.fillPurposes](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L127) | [以 AI 補齊每個檔案的一行用途描述](#reviewfillpurposes) |
-| [review.runAttackers](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L276) | [攻擊方 sub agent 並行找問題並合併列表](#reviewrunattackers) |
+| [review.runAttackers](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L276) | [攻擊方 sub agent 並行找問題並合併列表](#reviewrunattackers) |
-| [review.runDefenders](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L448) | [防守方 sub agent 裁決保留或排除](#reviewrundefenders) |
+| [review.runDefenders](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L448) | [防守方 sub agent 裁決保留或排除](#reviewrundefenders) |
-| [review.sortFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L572) | [依嚴重度→檔案→行號排序 findings](#reviewsortfindings) |
+| [review.sortFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L572) | [依嚴重度→檔案→行號排序 findings](#reviewsortfindings) |
-| [review.appendExclusions](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L521) | [誤判問題附加到 exclusions.json](#reviewappendexclusions) |
+| [review.appendExclusions](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L521) | [誤判問題附加到 exclusions.json](#reviewappendexclusions) |
-| [review.sortFindingsForIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L596) | [依檔案→嚴重度→行號排序（建問題模式）](#reviewsortfindingsforissue) |
+| [review.sortFindingsForIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L596) | [依檔案→嚴重度→行號排序（建問題模式）](#reviewsortfindingsforissue) |
-| [review.selectLabels](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L627) | [以 AI 從可用標籤挑選 issue 標籤](#reviewselectlabels) |
+| [review.selectLabels](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L627) | [以 AI 從可用標籤挑選 issue 標籤](#reviewselectlabels) |
-| [review.createIssueWithFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L694) | [建 issue 並逐條留言問題明細](#reviewcreateissuewithfindings) |
+| [review.createIssueWithFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L694) | [建 issue 並逐條留言問題明細](#reviewcreateissuewithfindings) |
-| [review.resolveOldComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L778) | [將 PR 舊留言標記為解決／過時](#reviewresolveoldcomments) |
+| [review.resolveOldComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L778) | [將 PR 舊留言標記為解決／過時](#reviewresolveoldcomments) |
-| [review.postSevereComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/master/src/lib/review.js#L855) | [嚴重問題逐條掛行留言（含降級）](#reviewpostseverecomments) |
+| [review.postSevereComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js#L855) | [嚴重問題逐條掛行留言（含降級）](#reviewpostseverecomments) |
 ## 使用範例
@@ -168,8 +168,8 @@ taipeiFromIso('');                     // '—'
 ```js
 const { log } = require('./src/lib/log');
-log('步驟3', 'INF', '變更檔案 5 個，送審 3 個。');
+log('步驟4', 'INF', '變更檔案 5 個，送審 3 個。');
-// [2026/07/17 16:46:13][步驟3][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 });
@@ -4,7 +4,7 @@
 console.log('================================================');
 console.log('Action  : AI Code Review');
 console.log('用途    : AI 多角色 code review：攻擊方找問題、防守方裁決誤報，結果留言到 PR 並保存 findings');
-console.log('更新時間: 2026/07/17 16:49:21');
+console.log('更新時間: 2026/07/17 18:49:58');
 console.log('================================================');
 const fs = require('fs');
@@ -42,9 +42,9 @@ const BOT_COMMIT_PREFIX = 'chore: update ai-review findings [ai-review-bot]';
 * @param {Array<Object>} params.excluded - 被裁決為誤報而排除的問題清單。
 * @returns {string} findings JSON 檔相對於 repo 根目錄的路徑（例如 `.gitea/ai-review/findings/xxx.json`）。
 * @remarks
- * 使用情境：`main()` 步驟 7 於防守方裁決、`review.sortFindings(kept)` 排序後呼叫本函式保存結果，
+ * 使用情境：`main()` 步驟 8 於防守方裁決、`review.sortFindings(kept)` 排序後呼叫本函式保存結果，
 * 再將回傳的相對路徑交給 `commitFindings` commit 並 push 回 PR 來源分支；
- * 另在步驟 3 判定無可審查變更時，也會以空清單保存一份空 findings 後以 success 收場。
+ * 另在步驟 4 判定無可審查變更時，也會以空清單保存一份空 findings 後以 success 收場。
 * 本函式無 try/catch，檔案系統錯誤會往上拋出，由 `main().catch` 以 exit code 1 收場。
 */
 function saveFindings({ cwd, ctx, tool, kept, excluded }) {
@@ -61,7 +61,7 @@ function saveFindings({ cwd, ctx, tool, kept, excluded }) {
  };
  fs.writeFileSync(findingsPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
  const relativePath = path.relative(cwd, findingsPath);
-  log('步驟7', 'INF', `findings 已保存：${relativePath}（保留 ${kept.length} 條、排除 ${excluded.length} 條）。`);
+  log('步驟8', 'INF', `findings 已保存：${relativePath}（保留 ${kept.length} 條、排除 ${excluded.length} 條）。`);
  return relativePath;
 }
@@ -88,7 +88,7 @@ function saveFindings({ cwd, ctx, tool, kept, excluded }) {
 * @remarks
 * 使用情境：`main()` 於流程尾端依 `severe.length === 0 ? 'success' : 'failure'` 決定 result、
 * 依模式組出 filesToCommit（一般模式：findings 檔＋有變更時的 exclusions.json；
- * 建問題模式：只有 exclusions.json）後呼叫本函式；另在步驟 3 判定無可審查變更且非建問題模式時，
+ * 建問題模式：只有 exclusions.json）後呼叫本函式；另在步驟 4 判定無可審查變更且非建問題模式時，
 * 也會以 result: 'success' 提交空 findings。
 * 注意 commit 訊息與模組常數 `BOT_COMMIT_PREFIX` 耦合，修改前綴會使步驟 1 的快速回報失效。
 */
@@ -119,13 +119,13 @@ function commitFindings({ cwd, ctx, files, result }) {
 *
 * 流程概要：
 * 1. 快速回報 — 最新 commit 若為 ai-review-bot 的結果 commit（[success]/[failure]），直接回報 0/1 不重審；
- * 2. 偵測 AI 工具（antigravity／codex／claude）並留言；
+ * 2. 將 PR 既有舊留言標記為解決（跳過本回合留言）；
- * 3. 讀 .reviewignore、整理 git diff 並留言（無可審查變更時：留言＋保存空 findings，
+ * 3. 偵測 AI 工具（antigravity／codex／claude）並留言；
 * 4. 讀 .reviewignore、整理 git diff 並留言（無可審查變更時：留言＋保存空 findings，
 *    一般模式 commit success、建問題模式略過 commit，回傳 0）；
- * 4–5. 攻擊方登場留言、每位攻擊方一個 sub agent 並行找問題；
+ * 5–6. 攻擊方登場留言、每位攻擊方一個 sub agent 並行找問題；
- * 6–7. 防守方登場留言、裁決誤報後排序並保存 findings JSON，
+ * 7–8. 防守方登場留言、裁決誤報後排序並保存 findings JSON，
 *    並以 appendExclusions 把誤判／重複問題回寫 .gitea/ai-review/exclusions.json；
 * 8. 將 PR 既有舊留言標記為解決（跳過本回合留言）；
 * 9. 嚴重問題逐條掛在程式碼行上留言；
 * 10. 警告＋建議彙整為單一表格留言；
 * 建問題模式（input: create-issue）：保留問題另建 issue（createIssueWithFindings）逐條留言明細；
@@ -167,21 +167,36 @@ async function main() {
    return 1;
  }
-  // 本回合發出的一般留言 id：步驟 8 標註過時時要跳過這些。
+  // 本回合發出的一般留言 id：步驟 2 標註過時時要跳過這些。
  const currentRunCommentIds = new Set();
  /**
   * 建立本回合 PR 一般留言並記錄留言 id，供後續舊留言處理排除。
   *
   * @param {string} body 要發布到 PR 的 Markdown 留言內容。
   * @returns {Promise<Object>} Gitea API 建立的留言物件；至少預期包含 `id`。
   * @remarks
   * 使用情境：只在 `main()` 內部使用，處理工具資訊、diff 摘要、角色登場與
   * 警告／建議彙整等一般留言。若 Gitea API 失敗，例外會往上拋出並由
   * 主流程頂層 catch 收斂。
   */
  const postComment = async (body) => {
    const created = await gitea.createIssueComment(ctx, body);
    currentRunCommentIds.add(created.id);
    return created;
  };
-  // ── 步驟 2：偵測 AI agent 工具並留言 ──────────────────────────────────
+  // ── 步驟 2：將 PR 既有留言標記為解決（本回合留言除外）───────────────────
  // 早於偵測工具與所有本回合留言：先把上一回合的 bot 留言標為過時；
  // 此時本回合尚未發出任何留言（currentRunCommentIds 為空），之後發出的留言自然不受影響。
  await review.resolveOldComments({ ctx, gitea, currentRunCommentIds });
  // ── 步驟 3：偵測 AI agent 工具並留言 ──────────────────────────────────
  const tool = agents.detectTool();
  if (!tool) {
-    log('步驟2', 'ERR', '找不到可用的 AI 工具（antigravity／codex／claude）。');
+    log('步驟3', 'ERR', '找不到可用的 AI 工具（antigravity／codex／claude）。');
    return 1;
  }
-  log('步驟2', 'INF', `選用工具：${tool.name}（${tool.version}）。`);
+  log('步驟3', 'INF', `選用工具：${tool.name}（${tool.version}）。`);
  const runLink = `${ctx.serverUrl}/${ctx.repository}/actions/runs/${ctx.runId}`;
  await postComment(
    templates.toolComment({
@@ -194,13 +209,13 @@ async function main() {
    }),
  );
-  // ── 步驟 3：讀取 .reviewignore、整理 git diff 並留言 ───────────────────
+  // ── 步驟 4：讀取 .reviewignore、整理 git diff 並留言 ───────────────────
  const ignores = review.loadReviewIgnore(cwd);
  const base = gitrepo.resolveMergeBase(cwd, ctx.baseRef);
  const allFiles = gitrepo.changedFiles(cwd, base);
  const files = allFiles.filter((file) => !review.isIgnored(file, ignores));
  const ignoredCount = allFiles.length - files.length;
-  log('步驟3', 'INF', `變更檔案 ${allFiles.length} 個，套用 .reviewignore 後送審 ${files.length} 個（排除 ${ignoredCount} 個）。`);
+  log('步驟4', 'INF', `變更檔案 ${allFiles.length} 個，套用 .reviewignore 後送審 ${files.length} 個（排除 ${ignoredCount} 個）。`);
  if (files.length === 0) {
    // 沒有可審查的變更：留言說明、保存空 findings、以 success 收場。
@@ -219,20 +234,20 @@ async function main() {
  await review.fillPurposes({ tool, model: ctx.model, cwd, diffRows });
  await postComment(templates.diffComment(diffRows, ignoredCount));
-  // ── 步驟 4：攻擊方角色登場留言 ─────────────────────────────────────────
+  // ── 步驟 5：攻擊方角色登場留言 ─────────────────────────────────────────
  const roles = loadRoles(path.join(ctx.actionPath, 'src', 'prompts', 'roles'));
  const attackers = attackersOf(roles);
  const defenders = defendersOf(roles);
-  log('步驟4', 'INF', `攻擊方 ${attackers.length} 位、防守方 ${defenders.length} 位。`);
+  log('步驟5', 'INF', `攻擊方 ${attackers.length} 位、防守方 ${defenders.length} 位。`);
  await postComment(templates.rolesComment({ title: '⚔️ 攻擊方登場', roles: attackers }));
-  // ── 步驟 5：每個攻擊方一個 sub agent 並行分析，合併問題列表 ────────────
+  // ── 步驟 6：每個攻擊方一個 sub agent 並行分析，合併問題列表 ────────────
  const findings = await review.runAttackers({ tool, model: ctx.model, cwd, attackers, diffRows });
-  // ── 步驟 6：防守方角色登場留言 ─────────────────────────────────────────
+  // ── 步驟 7：防守方角色登場留言 ─────────────────────────────────────────
  await postComment(templates.rolesComment({ title: '🛡️ 防守方登場', roles: defenders }));
-  // ── 步驟 7：防守方裁決 → 排除 → 排序 → 保存 findings ──────────────────
+  // ── 步驟 8：防守方裁決 → 排除 → 排序 → 保存 findings ──────────────────
  const { kept, excluded } = await review.runDefenders({ tool, model: ctx.model, cwd, defenders, findings });
  review.sortFindings(kept);
  const relativePath = saveFindings({ cwd, ctx, tool, kept, excluded });
@@ -240,13 +255,10 @@ async function main() {
  // 誤判／重複的問題附加到 exclusions.json（之後與審查結果一起 commit）。
  const exclusionsChanged = review.appendExclusions({ cwd, excluded, prNumber: ctx.prNumber });
-  // ── 步驟 7（分組）：依嚴重等級分組（嚴重／警告＋建議），組內已依檔案與行數排序 ─
+  // ── 步驟 8（分組）：依嚴重等級分組（嚴重／警告＋建議），組內已依檔案與行數排序 ─
  const severe = kept.filter((finding) => finding.severity === '嚴重');
  const others = kept.filter((finding) => finding.severity !== '嚴重');
-  log('步驟7', 'INF', `分組結果：嚴重 ${severe.length} 條、警告＋建議 ${others.length} 條。`);
+  log('步驟8', 'INF', `分組結果：嚴重 ${severe.length} 條、警告＋建議 ${others.length} 條。`);
  // ── 步驟 8：將 PR 既有留言標記為解決（本回合留言除外）───────────────────
  await review.resolveOldComments({ ctx, gitea, currentRunCommentIds });
  // ── 步驟 9：嚴重問題逐條掛在程式碼行上留言（開發者可回覆）──────────────
  if (severe.length > 0) {
@@ -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() {
@@ -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` 實作此降級）。
 */
@@ -44,6 +44,25 @@ function gitTrim(cwd, ...args) {
  return git(cwd, ...args).trim();
 }
 /**
 * 嘗試同步執行 git 指令，失敗時回傳 false，成功時回傳 true。
 *
 * @param {string} cwd - git 工作目錄（repo 的 checkout 路徑）。
 * @param {...string} args - 傳給 git 的參數。
 * @returns {boolean} git 指令是否成功結束。
 * @remarks
 * 使用情境：修復淺層 checkout 的歷史不足時，部分 fetch 策略可能因 runner
 * 或遠端版本不同而失敗；呼叫端可依序嘗試多種策略，不讓第一個失敗中斷流程。
 */
 function tryGit(cwd, ...args) {
  try {
    git(cwd, ...args);
    return true;
  } catch {
    return false;
  }
 }
 /**
 * 取得目前 HEAD 最新一筆 commit 的訊息標題（commit message 第一行）。
 *
@@ -64,14 +83,14 @@ function latestCommitSubject(cwd) {
 /**
 * 解析 PR base 分支與目前 HEAD 的 merge-base commit SHA。
 *
- * 先嘗試 `git fetch origin <baseRef>` 更新 base 分支資料（失敗時靜默忽略，
+ * 先以 refspec 明確更新 `origin/<baseRef>`，再以 `git merge-base origin/<baseRef> HEAD`
- * 因 fetch-depth: 0 的 checkout 通常已含 base 分支，可直接沿用本地資料），
+ * 取得共同祖先。若 checkout 是淺層歷史而導致 merge-base 失敗，會補抓完整或更深的
- * 再以 `git merge-base origin/<baseRef> HEAD` 取得共同祖先。
+ * base/head 歷史後重試，避免 PR workflow 因 checkout 預設深度不足而中斷。
 *
 * @param {string} cwd - git 工作目錄（repo 的 checkout 路徑）。
 * @param {string} baseRef - PR 目標（base）分支名稱，例如 'master' 或 'develop'；不含 'origin/' 前綴。
 * @returns {string} merge-base 的 commit SHA（40 碼十六進位字串）。
- * @throws {Error} 本地不存在 origin/<baseRef>、或兩者無共同祖先時，`git merge-base` 失敗並拋出（fetch 失敗不會拋出）。
+ * @throws {Error} 補抓歷史後仍無法取得共同祖先時，丟出含 baseRef 的明確錯誤。
 * @remarks
 * 使用情境：AI code review 以此結果作為 diff 比較基準——
 * 先 `resolveMergeBase(cwd, pr.base.ref)` 取得基準 SHA，
@@ -79,12 +98,25 @@ function latestCommitSubject(cwd) {
 * 避免把 base 分支後續演進誤算進 diff。
 */
 function resolveMergeBase(cwd, baseRef) {
  const remoteBase = `origin/${baseRef}`;
  tryGit(cwd, 'fetch', '--no-tags', 'origin', `+refs/heads/${baseRef}:refs/remotes/${remoteBase}`);
  try {
-    git(cwd, 'fetch', 'origin', baseRef);
+    return gitTrim(cwd, 'merge-base', remoteBase, 'HEAD');
-  } catch {
+  } catch (firstError) {
-    // fetch-depth: 0 的 checkout 通常已含 base 分支，抓不到時直接沿用本地資料。
+    const isShallow = gitTrim(cwd, 'rev-parse', '--is-shallow-repository') === 'true';
    if (isShallow) {
      tryGit(cwd, 'fetch', '--no-tags', '--unshallow', 'origin');
    }
    tryGit(cwd, 'fetch', '--no-tags', '--deepen=1000', 'origin', `+refs/heads/${baseRef}:refs/remotes/${remoteBase}`);
    tryGit(cwd, 'fetch', '--no-tags', '--deepen=1000', 'origin', 'HEAD');
    try {
      return gitTrim(cwd, 'merge-base', remoteBase, 'HEAD');
    } catch {
      const error = new Error(`無法解析 origin/${baseRef} 與 HEAD 的 merge-base；請確認 checkout 有足夠歷史，或設定 checkout fetch-depth: 0。`);
      error.cause = firstError;
      throw error;
    }
  }
  return gitTrim(cwd, 'merge-base', `origin/${baseRef}`, 'HEAD');
 }
 /**
@@ -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` 在攻擊方登場留言後呼叫，
+ * 使用情境：審查流程「步驟 6」由 `src/index.js` 在攻擊方登場留言後呼叫，
- * 結果直接交給步驟 7 的 {@link runDefenders} 裁決。
+ * 結果直接交給步驟 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 之後、
+ * 使用情境：審查流程「步驟 2」在步驟 1 快速回報與前置檢查之後、偵測工具（步驟 3）
- * 發布本回合嚴重問題留言（步驟 9）之前呼叫，確保 PR 上只有最新回合的審查結果醒目可見。
+ * 與所有本回合留言之前呼叫；此時本回合尚未發出任何留言（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}。`);
  }
 }
@@ -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），
@@ -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 排除），
 * 直接以本留言告知開發者本回合視為審查通過，不再進入
 * 攻擊方／防守方審查階段。
Author	SHA1	Message	Date
Jeffery	8662e8ca80	docs(審查步驟編號): 依新順序重編步驟編號與說明 node-actions/template: CI / BUILD (pull_request) Successful in 5s Details CI / TEST (Claude) (pull_request) Successful in 27s Details CI / TEST (Codex) (pull_request) Successful in 31s Details CI / TEST (Antigravity) (pull_request) Failing after 36s Details	2026-07-20 09:46:12 +08:00
Jeffery	d751cee69d	refactor(審查流程): 將舊留言標記移到偵測 AI 工具之前	2026-07-20 09:46:12 +08:00
ai-review-bot	ccbe615c2a	chore: update ai-review findings [ai-review-bot][success]	2026-07-17 11:03:14 +00:00
Jeffery	c4c23d4531	fix(gitrepo): 補抓淺層 checkout 的 base 歷史 node-actions/template: CI / BUILD (pull_request) Successful in 4s Details CI / TEST (Codex) (pull_request) Successful in 31s Details CI / TEST (Claude) (pull_request) Successful in 30s Details CI / TEST (Antigravity) (pull_request) Failing after 33s Details	2026-07-17 19:02:42 +08:00
Jeffery	3fe643c003	docs(doc-funcs): 補齊 action 與 workflow 文件 node-actions/template: CI / BUILD (pull_request) Successful in 5s Details CI / TEST (Codex) (pull_request) Failing after 28s Details CI / TEST (Claude) (pull_request) Failing after 27s Details CI / TEST (Antigravity) (pull_request) Failing after 34s Details	2026-07-17 18:54:00 +08:00
Jeffery	3fea48472f	chore(ci.yaml): 增加多工具 code review 驗證工作 node-actions/template: CI / BUILD (pull_request) Successful in 4s Details	2026-07-17 18:26:49 +08:00