docs(指令檔與 README): 補齊 action 與 workflow 逐行註解並新增專案 README

.gitea/workflows/ci.yaml

@@ -1,51 +1,117 @@
+# =============================================================================
+# CI Workflow（Gitea Actions）
+# 用途：在 Pull Request 開啟或更新時觸發的持續整合流程，依序執行三個 job：
+#   1. BUILD  - 發佈 Gitea Release（beta 版本號取自 run_number）。
+#   2. TEST   - checkout 原始碼，執行本 composite action（setup-codex），
+#               再用 codex exec 產生「自我介紹」文字，透過 heredoc 寫入 job output。
+#   3. RESULT - 顯示 TEST job 輸出的 message，用於驗證整條流程串接成功。
+# 更新日期：2026/07/03 11:41:20
+# =============================================================================
+
+# workflow 名稱，會顯示在 Gitea Actions 的執行清單中。
 name: CI
+# 觸發條件設定區塊。
 on:
+  # 監聽 Pull Request 事件。
   pull_request:
+    # 僅在 PR「開啟」(opened) 或「有新 commit 推送 / 更新」(synchronize) 時觸發，
+    # 避免 closed / reopened 等其他事件也啟動整條 CI。
     types: [opened, synchronize]
+# 定義本 workflow 的所有 job。
 jobs:
+  # ---- Job 1：BUILD（發佈 Release）----
   build:
+    # job 顯示名稱（前綴數字用於在 UI 中排序閱讀）。
     name: 1. BUILD
+    # 指定執行環境（runner label），使用 ubuntu runner。
     runs-on: ubuntu
+    # 此 job 專屬的環境變數。
     env:
+      # 版本號規則：固定 0.0.0-beta. 前綴 + Gitea 的執行流水號 run_number，
+      # 讓每次 CI 產生遞增且唯一的 beta 版本字串。
       VERSION: "0.0.0-beta.${{ gitea.run_number }}"
+    # 此 job 的執行步驟。
     steps:
+    # 步驟：發佈 Release。
     - name: Publishing Release
+      # 使用第三方 action 建立 Gitea Release；版本號由 repo variable 控制，
+      # 便於集中管理 action 版本、避免硬編碼。
       uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
+      # 傳入該 action 的參數。
       with:
+        # Release 顯示名稱：「儲存庫名稱 v版本號」。
         name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
+        # Release 對應的 tag 名稱，前綴 v + 版本號。
         tag_name: "v${{ env.VERSION }}"
+        # tag 指向的 commit，使用本次觸發事件的 commit SHA。
         target_commitish: ${{ gitea.sha }}
+        # 是否標記為「預發佈」(prerelease)：當 PR 目標分支 base_ref 為 develop 時為 true，
+        # 代表流向 develop 的變更視為預發佈版本。
         prerelease: ${{ gitea.base_ref == 'develop' }}
+  # ---- Job 2：TEST（執行 setup-codex 並產生自我介紹）----
   test:
+    # job 顯示名稱。
     name: 2. TEST
+    # 指定 ubuntu runner。
     runs-on: ubuntu
+    # 相依關係：需等 build job 成功後才執行。
     needs: [build]
+    # 定義此 job 對外輸出，供後續 job（result）取用。
     outputs:
+      # 將名為 execute 的步驟輸出的 message，暴露為 job 層級的 message 輸出。
       message: ${{ steps.execute.outputs.message }}
+    # 此 job 的執行步驟。
     steps:
+    # 步驟：取出原始碼。
     - name: Source Code Checkout
+      # 使用官方 checkout action 將 repo 內容拉到 runner；版本由 repo variable 控制。
       uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
+    # 步驟：執行本 repo 的 composite action（setup-codex）。
     - name: Run Setup Codex
+      # 指定步驟 id，方便後續引用其輸出。
       id: setup-codex
+      # 「./」代表使用當前 repo 根目錄的 action（即本專案自身這個 composite action）。
       uses: ./
+      # 傳入該 action 的參數。
       with:
+        # 從 secrets 帶入 CODEX_OAUTH 授權憑證，供 codex 登入 / 認證使用（機密不外顯）。
         oauth: ${{ secrets.CODEX_OAUTH }}
+    # 步驟：實際呼叫 codex 產生自我介紹並寫入 job output。
     - name: Execute Codex
+      # 指定步驟 id 為 execute，對應上方 outputs.message 的來源。
       id: execute
+      # 明確指定以 bash 執行下方 run 腳本。
       shell: bash
+      # 多行 shell 腳本（run: | 表示保留換行的區塊字面值）。
       run: |
+        # 執行 codex exec 送出提示「請你進行自我介紹」，取得回覆文字存入 MESSAGE 變數；
+        # 2>/dev/null 將 stderr 丟棄，避免非結果訊息污染輸出內容。
         MESSAGE=$(codex exec "請你進行自我介紹" 2>/dev/null)
+        # 用大括號將多個 echo 群組化，統一把整段輸出一次重導向到 $GITHUB_OUTPUT。
         {
+          # 宣告輸出鍵 message 並使用 heredoc 分隔符 CODEX_EOF，以支援「多行值」的寫法。
           echo "message<<CODEX_EOF"
+          # 寫入實際的多行自我介紹內容。
           echo "$MESSAGE"
+          # heredoc 結束分隔符，標示 message 值到此為止。
           echo "CODEX_EOF"
+        # 將上述群組化輸出「附加」(>>) 到 $GITHUB_OUTPUT 檔，登記為此步驟的 output。
         } >> "$GITHUB_OUTPUT"
+  # ---- Job 3：RESULT（顯示 TEST 的 message）----
   result:
+    # job 顯示名稱。
     name: 3. RESULT
+    # 指定 ubuntu runner。
     runs-on: ubuntu
+    # 相依關係：需等 build 與 test 兩個 job 都完成後才執行。
     needs: [build,test]
+    # 此 job 專屬的環境變數。
     env:
+      # 從 test job 的輸出取得 message，供下方步驟印出。
       MESSAGE: ${{ needs.test.outputs.message }}
+    # 此 job 的執行步驟。
     steps:
+    # 步驟：印出訊息。
     - name: Show Message
+      # 將環境變數 MESSAGE 的內容輸出到 log，用於確認整條流程串接與 codex 回覆結果。
       run: echo "$MESSAGE"

.gitea/workflows/master.yaml

@@ -1,21 +1,53 @@
+# =============================================================================
+# 用途說明：
+#   本 workflow 為「CD（持續部署）」流程，於程式碼 push 到 master 分支時觸發。
+#   主要工作為 checkout 完整原始碼、依指定 commit 反查其所屬的 git tag，
+#   並將該 tag 輸出顯示，供後續部署或版本追蹤使用。
+# 更新日期：2026/07/03 11:41:20 (Asia/Taipei)
+# =============================================================================
+
+# workflow 名稱，顯示於 Gitea Actions 介面
 name: CD
+# 觸發條件設定
 on:
+  # 監聽 push 事件
   push:
+    # 僅限定下列分支
     branches:
+    # 只有 push 到 master 分支時才會觸發本 workflow
     - master
+# 定義所有工作（jobs）
 jobs:
+  # 部署工作，job 識別鍵為 deploy
   deploy:
+    # 此 job 的顯示名稱
     name: DEPLOY
+    # 指定執行環境（runner label）為 ubuntu
     runs-on: ubuntu
+    # job 層級環境變數
     env:
+      # 取事件 commits 陣列的第二筆（索引 1）之 commit id 作為要處理的 SHA
+      # 需人工確認：使用索引 1 而非 0，取的是事件中「第二個」commit；
+      #           當一次 push 只包含單一 commit 時，索引 1 可能取不到值（為空）。
       COMMIT_SHA: ${{ gitea.event.commits[1].id }}
+    # 依序執行的步驟
     steps:
+    # 步驟一：取出原始碼
     - name: Source Code Checkout
+      # 使用 actions/checkout，版本由 repo/organization 變數 ACTION_CHECKOUT_VERSION 決定
       uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
       with:
+        # fetch-depth: 0 代表抓取完整 git 歷史（含所有 tag），
+        # 以利後續 git describe 能正確反查 tag（淺層 clone 會導致查不到）。
         fetch-depth: 0
+    # 步驟二：取得該 commit 所屬的 tag
     - name: Get Commit Tag
+      # 設定步驟 id 為 commit，供後續步驟以 steps.commit.outputs 取得輸出
       id: commit
+      # git describe --contains 會找出「包含」指定 commit 的最近 tag，
+      # 並將結果以 tag=... 寫入 $GITEA_OUTPUT，成為此步驟的輸出參數 tag。
       run: echo "tag=$(git describe --contains ${{ env.COMMIT_SHA }})" >> $GITEA_OUTPUT
+    # 步驟三：顯示取得的 tag
     - name: Show Tag
+      # 印出上一步（id=commit）輸出的 tag 值，方便於 log 確認結果
       run: echo "${{ steps.commit.outputs.tag }}"