docs(codex): 補齊 read_account_email docstring 與指令檔註解並重建 README

.gitea/workflows/cd.yaml

@@ -1,12 +1,35 @@
+# =============================================================================
+# 用途：CD（Continuous Delivery）持續交付 workflow。
+#       當有 commit push 到 master 分支時觸發，呼叫 release-tag-version
+#       composite action 進行「釋出並標註正式成品版本」（建立 release / 打 tag），
+#       將 master 上的成果標記為一個正式可發布的版本。
+# 更新日期：2026/06/29 14:18:26
+# =============================================================================
+
+# workflow 顯示名稱，會出現在 Gitea Actions 的 workflow 清單與執行紀錄中，方便辨識。
 name: CD
+# 觸發條件：監聽 push 事件。
 on:
   push:
+    # 只在指定分支發生 push 時觸發，避免其他分支誤觸發正式釋出流程。
     branches:
+    # 僅限 master 分支：master 視為正式（穩定）分支，push 進來代表要正式釋出成品版本。
     - master
+# 此 workflow 包含的 job 清單。
 jobs:
+  # job 識別碼：release-tag-version，負責釋出並標註成品版本。
   release-tag-version:
+    # job 顯示名稱，呈現於 Actions 執行畫面，便於辨識此 job 的職責。
     name: Release Tag Version
+    # 指定執行此 job 的 runner 標籤；使用 ubuntu runner 執行後續步驟。
     runs-on: ubuntu
+    # 此 job 的執行步驟序列。
     steps:
+    # 步驟名稱：釋出並標註成品版本（建立 release / 打版本 tag）。
     - name: 釋出並標註成品版本
+      # 呼叫外部 composite action「release-tag-version」執行實際的釋出與 tag 標註邏輯。
+      # 版本以變數 vars.ACTION_RELEASE_TAG_VERSION 釘選，確保使用指定版本的 action，
+      # 避免上游 action 變動造成釋出行為不可預期。
+      # 副作用：此步驟會在遠端建立 release 或推送版本 tag（正式釋出動作）。
+      # 需人工確認：vars.ACTION_RELEASE_TAG_VERSION 變數需在 repo / org 層級正確設定，否則 action 解析會失敗。
       uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}

.gitea/workflows/ci.yaml

@@ -1,34 +1,77 @@
+# =============================================================================
+# 用途：PR（非 master 分支、opened/synchronize）觸發的 CI。
+#   流程：先用 release-tag-version composite action 算出 beta 版本號，再用該版本號
+#         叫 codex composite action 執行（未帶 prompt，走取登入 email 分支），
+#         最後以「檢查輸出」step 驗證輸出的登入帳號 email 是否等於 vars.CODEX_EMAIL。
+# 更新日期：2026/06/29 14:18:26
+# =============================================================================
+
+# workflow 顯示名稱，於 Gitea Actions 列表中辨識此工作流程。
 name: CI
 
+# 觸發條件設定區塊。
 on:
+  # 針對 pull_request 事件觸發。
   pull_request:
+    # 略過目標分支為 master 的 PR（亦即只在「非 master 分支」的 PR 上跑），
+    # 避免對 master 的合併 PR 重複執行 CI。
     branches-ignore:
     - master
+    # 僅在 PR 被開啟（opened）或有新 commit 推入（synchronize）時觸發，
+    # 其他事件（如 reopened、labeled）不觸發以節省資源。
     types: [opened, synchronize]
 
+# 工作（jobs）定義區塊。
 jobs:
+  # 第一個 job：計算 beta 版本號，供後續 codex job 取用。
   release-tag-version:
+    # job 顯示名稱。
     name: Release Tag Version
+    # 指定執行的 runner 標籤（ubuntu）。
     runs-on: ubuntu
+    # 對外輸出值，讓相依此 job 的其他 job 可引用。
     outputs:
+      # 將 release-tag-version step 算出的 version 輸出，鍵名為 version。
       version: ${{ steps.release-tag-version.outputs.version }}
+    # 步驟清單。
     steps:
+    # 呼叫 release-tag-version composite action 計算版本號。
     - name: 計算版本號
+      # 此 step 的 id，供 outputs 透過 steps.release-tag-version 引用其輸出。
       id: release-tag-version
+      # 使用外部 composite action；版本由 repo 變數 ACTION_RELEASE_TAG_VERSION 決定，
+      # 便於集中管理所引用 action 的版本。
       uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}
       with:
+        # 指定產生 beta 版本號（而非正式版），用於 CI 測試情境。
         is_beta: 'true'
 
+  # 第二個 job：用前一 job 算出的版本號叫 codex action，再驗證其輸出。
   codex:
+    # job 顯示名稱。
     name: Codex
+    # 指定執行的 runner 標籤（ubuntu）。
     runs-on: ubuntu
+    # 相依 release-tag-version job，需等其成功後才執行，
+    # 以取得其輸出的版本號。
     needs: release-tag-version
+    # 步驟清單。
     steps:
+    # 步驟一：呼叫 codex composite action（未帶 prompt，走「取登入 email」分支）。
     - name: 測試工具
+      # 此 step 的 id，供後續「檢查輸出」step 引用其 outputs.text。
       id: codex
+      # 使用 codex composite action；版本標籤由前一 job 輸出的 version 組成
+      # （前綴 v），確保測試所用 codex action 與本次算出的 beta 版本一致。
       uses: https://gitea.jsc.idv.tw/composite-actions/codex@v${{ needs.release-tag-version.outputs.version }}
       with:
+        # 由 secrets 注入 codex 登入用 OAuth 憑證，避免明文外洩。
+        # 注意：未提供 prompt，codex action 會回傳目前登入帳號的 email。
         oauth: ${{ secrets.CODEX_OAUTH }}
+    # 步驟二：驗證登入身分。
     - name: 檢查輸出
+      # 當 codex 輸出的登入 email 與 repo 變數 CODEX_EMAIL 不符時條件成立，
+      # 代表登入帳號不是預期帳號。
       if: ${{ steps.codex.outputs.text != vars.CODEX_EMAIL }}
+      # 條件成立即以非零狀態碼退出，使 CI 失敗（擋下非預期登入帳號）。
       run: exit 1