feat(ai-code-review): 新增 AI 多角色 code review action（攻防審查、findings 保存、建問題模式）

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

action.yml

@@ -1,14 +1,53 @@
-name: 'Gitea Node Template'
-description: 'Gitea Node (JavaScript) action 範本'
+# =====================================================
+# 用途    : AI 多角色 code review：攻擊方找問題、防守方裁決誤報，結果留言到 PR 並保存 findings
+# 更新時間: 2026/07/17 16:49:21
+# =====================================================
+# Gitea / GitHub node action 的 manifest（action.yml）：
+# 定義本 action 的名稱、說明、輸入參數（inputs）與執行方式（runs），
+# 供呼叫端 workflow 以 `uses:` 引用；runner 讀取此檔後以 node24 執行 src/index.js。
+
+# action 顯示名稱：呼叫端 workflow log 與 marketplace 列表上看到的名稱
+name: 'AI Code Review'
+# action 用途說明：多角色 AI code review 流程（攻擊方找問題、防守方裁決誤報），
+# 審查結果會留言到 PR 並保存 findings（.gitea/ai-review/findings/）
+description: 'AI 多角色 code review：攻擊方找問題、防守方裁決誤報，結果留言到 PR 並保存 findings'
+# action 作者資訊（僅供辨識，不影響執行）
 author: 'Jeffery'
+# 輸入參數區塊：呼叫端 workflow 以 `with:` 傳入，
+# runner 會自動注入為 INPUT_* 環境變數（例如 INPUT_TOKEN、INPUT_MODEL、INPUT_CREATE-ISSUE）供主程式讀取
 inputs:
-  message:
-    description: '輸入訊息'
+  # Gitea API token：用於對 PR 留言審查結果、以及 push 審查結果檔回 repo
+  token:
+    # 參數用途說明：secrets/vars context 在 action 內不可用，
+    # 故由呼叫端 workflow 以 secrets.GITHUB_TOKEN 傳入
+    description: 'Gitea API token（PR 留言與 push findings 用；呼叫端以 secrets.GITHUB_TOKEN 傳入）'
+    # 必填：缺少 token 無法呼叫 Gitea API，action 無法運作
+    required: true
+  # 指定 AI 工具使用的模型名稱
+  model:
+    # 參數用途說明：留空表示使用各 AI 工具自身的預設模型
+    description: '指定 AI 工具使用的模型（空值＝各工具預設）'
+    # 選填：未指定時採用預設值
     required: false
-    default: 'Hello, World!'
-outputs:
-  message:
-    description: '輸出訊息'
+    # 預設為空字串，代表不覆寫各工具的預設模型
+    default: ''
+  # 建問題模式開關：是否把審查保留的問題另建 issue 追蹤
+  create-issue:
+    # 參數用途說明：字串 'true' 時建立 issue（標題＝PR 標題、描述＝PR 描述、AI 挑標籤）
+    # 並逐條留言問題明細，findings 檔不進版控、收尾只 commit exclusions.json；
+    # 預設 'false' 走原流程（findings 檔與 exclusions.json 一併 commit 回 PR 來源分支）
+    description: '是否將問題建到存取庫的問題追蹤（true 時建立 issue 逐條留言問題明細，最後只 commit exclusions.json；預設 false 走原流程）'
+    # 選填：未指定時採用預設值
+    required: false
+    # 預設為字串 'false'，代表不啟用建問題模式（主程式只認字串 'true' 才啟用）
+    default: 'false'
+# 執行方式區塊：宣告本 action 為 node action 及其進入點
 runs:
+  # 以 Node.js 24 runtime 直接在 runner 上執行（非 Docker 容器、非 composite）
   using: 'node24'
+  # 主程式進入點：直接指向 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）
+  # 並將 main 改指 dist/index.js、把 dist/ commit 進 repo
   main: 'src/index.js'