docs(ai-code-review): 補齊各模組 JSDoc、指令檔逐行註解並重建 README

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -1,19 +1,43 @@
+# ============================================================
+# 用途：Gitea CI，在 pull request 上執行 AI 程式碼審查（AI code review on pull requests）
+# 更新日期：2026/06/26 11:34:46
+# ============================================================
+
+# workflow 名稱，會顯示在 Gitea Actions 介面上
 name: CI
+# 觸發條件設定
 on:
+  # 針對 pull request 事件觸發
   pull_request:
+    # 忽略指定目標分支：當 PR 目標分支為 master 時不觸發此 workflow
     branches-ignore:
     - master
+    # 觸發的 PR 事件類型：opened（PR 開啟）、synchronize（PR 有新 commit 推送）
     types: [opened, synchronize]
+# 定義此 workflow 的 jobs
 jobs:
+  # job 識別碼：ai-code-review
   ai-code-review:
+    # job 顯示名稱
     name: AI Code Review
+    # 指定執行環境的 runner 標籤：ubuntu
     runs-on: ubuntu
+    # 此 job 所需的權限設定
     permissions:
+      # 對 repository 內容的寫入權限（讀寫程式碼/檔案）
       contents: write
+      # 對 pull request 的寫入權限（讓 AI 可在 PR 上留言/審查）
       pull-requests: write
+      # 對 issues 的寫入權限（建立/更新 issue 留言所需）
       issues: write
+    # job 的執行步驟
     steps:
+      # 步驟名稱：呼叫 OpenCode 進行 AI 程式碼審查
     - name: AI 程式碼審查 by OpenCode
+      # 使用外部 composite action 執行審查邏輯
+      # 版本由 repository variable ACTION_OPENCODE_CODE_REVIEW_VERSION 決定，便於集中管理版本
       uses: https://gitea.jsc.idv.tw/composite-actions/opencode-code-review@${{ vars.ACTION_OPENCODE_CODE_REVIEW_VERSION }}
+      # 傳遞給 composite action 的輸入參數
       with:
+        # 留言用 token：取自 secret COMMENT_TOKEN，供 action 在 PR 上發布審查留言
         comment_token: ${{ secrets.COMMENT_TOKEN }}