docs(AI Code Review): 補齊 action 與 workflow 註解說明

.gitea/workflows/ci.yaml

@@ -1,49 +1,112 @@
+# 用途：CI workflow 的 command-file 草稿，保留原始流程並補上逐行說明。
+# 更新時間：2026/07/11 19:00:45
+# workflow 名稱，對應 Gitea UI 中的顯示標題。
 name: CI
+# 定義此 workflow 的觸發事件。
 on:
+  # 在 pull request 事件時執行。
   pull_request:
+    # 只在建立與同步更新 PR 時觸發。
     types: [opened, synchronize]
+# workflow 內的工作列表。
 jobs:
+  # 第一個 job：負責版本計算與 release 發佈。
   build:
+    # job 顯示名稱，用來區分執行階段。
     name: 1. BUILD
+    # 使用 Ubuntu runner 執行。
     runs-on: ubuntu
+    # job 層級環境變數。
     env:
-      VERSION: "0.0.0-beta.${{ gitea.run_number }}"
+      # 目標分支為 develop 時視為 beta。
       IS_BETA: ${{ gitea.base_ref == 'develop' }}
+    # 對外輸出供後續 job 使用。
     outputs:
+      # 輸出版本字串。
       version: ${{ env.VERSION }}
+      # 輸出是否為 beta。
       is_beta: ${{ env.IS_BETA }}
+    # build job 的執行步驟。
     steps:
-    - name: Publishing Release
-      uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
-      with:
-        name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
-        tag_name: "v${{ env.VERSION }}"
-        target_commitish: ${{ gitea.sha }}
-        prerelease: ${{ env.IS_BETA }}
+      # 先依 repo 狀態計算版本號。
+      - name: Calculate Version
+        # 供後續步驟讀取輸出用的 step id。
+        id: calculate-version
+        # 使用版本計算 action。
+        uses: https://gitea.jsc.idv.tw/actions/calculate-version@${{ vars.ACTION_CALCULATE_VERSION }}
+        # 傳入 action 參數。
+        with:
+          # 告知 action 是否為 beta 分支情境。
+          is_beta: ${{ env.IS_BETA }}
+      # 依計算出的版本建立 release。
+      - name: Publishing Release
+        # 使用 release action。
+        uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
+        # 這個 step 的環境變數。
+        env:
+          # 取前一步算出的版本號。
+          VERSION: ${{ steps.calculate-version.outputs.version }}
+        # release action 的參數。
+        with:
+          # release 名稱。
+          name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
+          # release tag 名稱。
+          tag_name: "v${{ env.VERSION }}"
+          # 指向目前提交。
+          target_commitish: ${{ gitea.sha }}
+          # beta 情境時標記為 prerelease。
+          prerelease: ${{ env.IS_BETA }}
+  # 第二個 job：在 beta 情境執行 AI Code Review。
   test:
+    # job 顯示名稱。
     name: 2. TEST
+    # 使用 Ubuntu runner。
     runs-on: ubuntu
+    # 必須等 build job 完成。
     needs: [build]
+    # 只有 beta 情境才執行。
     if: ${{ needs.build.outputs.is_beta == 'true' }}
+    # job 層級環境變數。
     env:
+      # 使用 build job 輸出的版本號。
       VERSION: ${{ needs.build.outputs.version }}
+    # test job 的步驟。
     steps:
-    - name: Setup LLM CLI
-      uses: https://gitea.jsc.idv.tw/actions/setup-${{ vars.ACTION_SETUP_LLM_CLI }}
-      with:
-        oauth: ${{ secrets.LLM_OAUTH }}
-    - name: Run AI Code Review
-      id: ai-code-review
-      uses: https://gitea.jsc.idv.tw/actions/ai-code-review@v${{ env.VERSION }}
-      with:
-        token: ${{ secrets.TOKEN }}
-        model: ${{ vars.LLM_NAME }}
+      # 安裝或設定 LLM CLI。
+      - name: Setup LLM CLI
+        # 使用對應的 setup action。
+        uses: https://gitea.jsc.idv.tw/actions/setup-${{ vars.ACTION_SETUP_LLM_CLI }}
+        # 傳入設定。
+        with:
+          # LLM CLI 的 OAuth 憑證。
+          oauth: ${{ secrets.LLM_OAUTH }}
+      # 執行 AI Code Review action。
+      - name: Run AI Code Review
+        # step id，方便追蹤。
+        id: ai-code-review
+        # 使用本 repo 發佈的 action。
+        uses: https://gitea.jsc.idv.tw/actions/ai-code-review@v${{ env.VERSION }}
+        # action 參數。
+        with:
+          # 存取 Gitea API 的 token。
+          token: ${{ secrets.TOKEN }}
+          # 指定 LLM 模型名稱。
+          model: ${{ vars.LLM_NAME }}
+  # 第三個 job：輸出最終版本資訊。
   result:
+    # job 顯示名稱。
     name: 3. RESULT
+    # 使用 Ubuntu runner。
     runs-on: ubuntu
+    # 需等待前兩個 job。
     needs: [build,test]
+    # job 層級環境變數。
     env:
+      # 延續 build 的版本號。
       VERSION: ${{ needs.build.outputs.version }}
+    # result job 的步驟。
     steps:
-    - name: Show Version
-      run: echo "$VERSION"
+      # 顯示版本號。
+      - name: Show Version
+        # 將版本輸出到 log。
+        run: echo "$VERSION"