docs(指令檔與 README): 補齊 action.yml 與 CI/CD workflow 逐行註解並重建 README

.gitea/workflows/cd.yaml

@@ -1,14 +1,52 @@
+# =============================================================================
+# 檔案用途：Gitea CD（Continuous Delivery）workflow 設定檔
+#
+# 本檔定義一條名為 CD 的 Gitea Actions workflow，負責在程式碼推送到
+# master 分支時，自動執行「釋出並標註成品版本」的流程。實際的版本標註
+# 邏輯由本 repo 根目錄的 composite action（action.yml）提供，此 workflow
+# 僅負責觸發與串接該 composite action。
+#
+# 更新日期：2026/06/26 10:14:14（Asia/Taipei）
+# =============================================================================
+
+# workflow 的顯示名稱，會出現在 Gitea Actions 的執行列表中。
 name: CD
+
+# on：定義觸發本 workflow 的事件。
 on:
+  # push：當有 commit 被推送到 repository 時觸發。
   push:
+    # branches：限制只有特定分支的 push 才會觸發。
     branches:
+    # 僅限 master 分支；推送到其他分支不會啟動本 CD workflow。
+    # 這確保版本釋出只在正式主線（master）發生，避免在開發分支誤觸發發版。
     - master
+
+# jobs：本 workflow 包含的工作（job）集合。
 jobs:
+  # release-tag-version：唯一的 job，負責釋出並標註成品版本。
   release-tag-version:
+    # job 的顯示名稱，會出現在 Gitea Actions 的執行畫面上。
     name: Release Tag Version
+    # runs-on：指定執行此 job 的 runner 標籤（label）。
+    # 此處使用 ubuntu，代表會在標記為 ubuntu 的 Gitea runner 上執行。
+    # 需人工確認：通常 GitHub Actions 慣例為 ubuntu-latest；此處為 ubuntu，
+    # 請確認 Gitea runner 確實有註冊 "ubuntu" 這個 label，否則 job 不會被排程。
     runs-on: ubuntu
+    # steps：此 job 依序執行的步驟清單。
     steps:
+    # 步驟一：取得（checkout）程式碼，讓後續步驟能存取 repo 內容。
     - name: 取得程式碼
+      # uses：引用官方 actions/checkout action 來簽出原始碼。
+      # 版本號透過 Gitea 變數 vars.ACTION_CHECKOUT_VERSION 動態帶入，
+      # 便於集中管理 checkout 版本，不必逐檔硬編碼版本字串。
+      # 副作用：未取得程式碼前，下一步的本地 composite action（./）將無法被解析。
+      # 需人工確認：請確認 repository / organization 層級已設定
+      # ACTION_CHECKOUT_VERSION 這個變數，否則 uses 會解析成空版本而失敗。
       uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
+    # 步驟二：釋出並標註成品版本，為本 workflow 的核心動作。
     - name: 釋出並標註成品版本
+      # uses: ./ 代表引用「本 repo 根目錄」的 composite action（即 action.yml）。
+      # 必須先完成步驟一的 checkout，根目錄的 action.yml 才存在於 runner 上而可被引用。
+      # 此 composite action 內含實際的版本標註與發版邏輯（請見根目錄 action.yml）。
       uses: ./

.gitea/workflows/ci.yaml

@@ -1,19 +1,63 @@
+# =============================================================================
+# 檔案用途（Purpose）：
+#   這是一份 Gitea Actions 的 CI workflow 設定檔。
+#   它的主要目的是：當開發者在本 repo 對「非 master」分支發起 Pull Request 時，
+#   自動觸發一個名為「AI Code Review」的 job，呼叫共用的 composite action
+#   「opencode-code-review」對該 PR 的程式碼變更做 AI 自動審查，並把審查意見
+#   以留言（comment）方式回貼到該 PR。
+#
+# 更新日期（Last Updated）：2026/06/26 10:14:14 (Asia/Taipei)
+# =============================================================================
+
+# workflow 顯示名稱，會出現在 Gitea Actions 的執行清單上，方便辨識這條流程。
 name: CI
+
+# on：定義此 workflow 的觸發事件區塊。
 on:
+  # pull_request：當有 Pull Request 相關事件時觸發。
   pull_request:
+    # branches-ignore：被列出的「目標分支（PR base/目的分支）」不會觸發此 workflow。
     branches-ignore:
+    # 忽略目標分支為 master 的 PR；亦即合併進 master 的 PR 不跑此 AI 審查
+    # （通常 master 視為正式線上分支，審查在更早的開發分支階段完成）。
     - master
+    # types：限定只在 PR 的「opened（首次開啟）」與「synchronize（後續推送新 commit 更新 PR）」
+    # 這兩種事件時觸發；其他事件（如 closed、reopened、labeled 等）不觸發，避免重複或不必要的審查。
     types: [opened, synchronize]
+
+# jobs：定義此 workflow 包含的工作（job）集合。
 jobs:
+  # ai-code-review：job 的識別 id（在 needs、輸出引用等地方會用到此 id）。
   ai-code-review:
+    # name：job 的顯示名稱，會出現在 Gitea Actions 介面上。
     name: AI Code Review
+    # runs-on：指定此 job 執行所使用的 runner 標籤；此處為 ubuntu。
+    # 需人工確認：請確認 Gitea 上確實有註冊標籤為 "ubuntu" 的 runner，否則 job 會排不到機器而卡住。
     runs-on: ubuntu
+    # permissions：設定此 job 內 GITHUB_TOKEN/Gitea token 對 repo 的存取權限範圍。
     permissions:
+      # contents: write —— 對 repo 內容（檔案、commit 等）有寫入權限。
+      # AI 審查通常只需讀取程式碼；此處給 write，需人工確認是否確有寫入需求（最小權限原則）。
       contents: write
+      # pull-requests: write —— 對 PR 有寫入權限，用於在 PR 上建立 / 更新審查留言。
       pull-requests: write
+      # issues: write —— 對 issue 有寫入權限；Gitea/GitHub 中 PR 留言底層常走 issue comment API，故需此權限。
       issues: write
+    # steps：此 job 依序執行的步驟清單。
     steps:
+    # 第 1 個 step：呼叫外部共用 composite action 執行 AI 程式碼審查。
     - name: AI 程式碼審查 by OpenCode
+      # uses：引用要執行的 composite action 來源與版本。
+      #   來源：https://gitea.jsc.idv.tw/composite-actions/opencode-code-review
+      #   版本：@${{ vars.ACTION_OPENCODE_CODE_REVIEW_VERSION }}
+      #         版本號取自 repo/organization 設定的變數 vars.ACTION_OPENCODE_CODE_REVIEW_VERSION，
+      #         可集中管理升版，不需修改本檔。
+      # 需人工確認：請確認該 vars 變數已在 Gitea 設定且值有效（例如 v1.0.0 / 分支名 / commit），
+      #            若變數為空，action 參照會解析失敗導致 step 執行錯誤。
       uses: https://gitea.jsc.idv.tw/composite-actions/opencode-code-review@${{ vars.ACTION_OPENCODE_CODE_REVIEW_VERSION }}
+      # with：傳遞給該 composite action 的輸入參數。
       with:
+        # comment_token：提供給 action 用來回貼審查留言到 PR 的存取權杖（token）。
+        #   取自 secrets.COMMENT_TOKEN（機密，由 Gitea Secrets 管理，不應寫死在檔案中）。
+        # 需人工確認：請確認 secrets.COMMENT_TOKEN 已設定，且該 token 具有對本 repo PR/issue 留言的權限。
         comment_token: ${{ secrets.COMMENT_TOKEN }}