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

action.yml

@@ -1,56 +1,124 @@
+# =============================================================================
+# 檔案用途：提供 Codex CLI 的 composite action（Gitea/GitHub 複合動作）
+# -----------------------------------------------------------------------------
+# 此 action 主要做三件事：
+#   1. 安裝 @openai/codex CLI 工具（透過 npm 全域安裝）。
+#   2. 將傳入的 base64 編碼 OAuth token 解碼後寫入 $HOME/.codex/auth.json，
+#      讓 codex CLI 取得登入憑證。
+#   3. 執行 inputs.prompt 指定的提示詞，並把 Codex 的輸出寫入
+#      steps.codex.outputs.text 供後續 step 使用。
+#   - 若未提供 prompt（PROMPT 為空），則改呼叫 app/codex_account.py 取得目前
+#     登入帳號的 email，寫入 text 輸出後結束（用於驗證身分）。
+# 更新日期：2026/06/29 14:18:26
+# =============================================================================
+
+# action 名稱（顯示於工作流程記錄中）
 name: 'Codex CLI'
+# action 說明文字
 description: 'Codex CLI 工具'
+# action 作者
 author: 'Jeffery'
+# 輸入參數定義區塊
 inputs:
+  # prompt：傳給 Codex CLI 的提示詞
   prompt:
+    # 參數說明
     description: '傳給 Codex CLI 的提示詞'
+    # 非必填；未提供（為空）時會走「取登入 email」分支
     required: false
+  # oauth：base64 編碼的 Codex OAuth token 檔案內容
   oauth:
+    # 參數說明
     description: 'base64 編碼的 Codex OAuth token 檔案內容'
+    # 必填；缺少時安裝步驟會直接報錯退出
     required: true
+# 輸出參數定義區塊
 outputs:
+  # text：將 Codex 執行結果（或登入 email）對外輸出
   text:
+    # 參數說明
     description: '輸出的文字'
+    # 取自 id 為 codex 的 step 所寫入的 text 輸出
     value: ${{ steps.codex.outputs.text }}
+# 執行定義區塊
 runs:
+  # 使用 composite（複合）類型，串接多個 shell step
   using: 'composite'
+  # 步驟清單
   steps:
+  # 步驟一：安裝 Codex CLI 並寫入 OAuth 憑證
   - name: 安裝工具
+    # 步驟環境變數
     env:
+      # 將 inputs.oauth 注入為 OAUTH 環境變數（base64 內容）
       OAUTH: ${{ inputs.oauth }}
+    # 執行的 shell 指令區塊
     run: |
+      # 檢查 OAUTH 是否為空；為空代表呼叫端未提供 secrets.CODEX_OAUTH
       if [ -z "$OAUTH" ]; then
+        # 輸出錯誤訊息至 stderr（>&2）
         echo 'oauth input (secrets.CODEX_OAUTH) is required and must not be empty.' >&2
+        # 以非零狀態碼退出，使工作流程失敗
         exit 1
       fi
 
+      # 全域安裝 Codex CLI 套件，安裝後可直接使用 codex 指令
       npm install -g @openai/codex
 
+      # 設定 OAuth 憑證檔的路徑（codex CLI 預期讀取此檔）
       oauth_file="$HOME/.codex/auth.json"
+      # 建立憑證檔所在目錄；-m 700 限定僅擁有者可進入（保護憑證）
       install -d -m 700 "$(dirname "$oauth_file")"
+      # 將 base64 內容解碼（base64 -d）後寫入憑證檔
       printf '%s' "$OAUTH" | base64 -d > "$oauth_file"
+      # 將憑證檔權限設為 600，僅擁有者可讀寫（避免憑證外洩）
       chmod 600 "$oauth_file"
+    # 指定以 bash 執行此 run 區塊
     shell: bash
+  # 步驟二：執行 Codex CLI 或取得登入 email
   - name: 執行工具
+    # 步驟識別碼，供 outputs.text 引用其輸出
     id: codex
+    # 步驟環境變數
     env:
+      # MODEL：取自 repository 變數 CODEX_MODEL（指定使用的模型）
       MODEL: ${{ vars.CODEX_MODEL }}
+      # PROMPT：取自 inputs.prompt（要執行的提示詞）
       PROMPT: ${{ inputs.prompt }}
+    # 執行的 shell 指令區塊
     run: |
+      # 檢查 MODEL 是否為空；未設定 CODEX_MODEL 則無法執行
       if [ -z "$MODEL" ]; then
+        # 輸出錯誤訊息至 stderr
         echo 'CODEX_MODEL repository variable is required.' >&2
+        # 以非零狀態碼退出，使工作流程失敗
         exit 1
       fi
+      # 當 PROMPT 為空時，改走「取得登入帳號 email」分支
       if [ -z "$PROMPT" ]; then
+        # 呼叫 codex_account.py 取得目前登入帳號的 email（$GITHUB_ACTION_PATH 為 action 根目錄）
         email="$(python3 "$GITHUB_ACTION_PATH/app/codex_account.py")"
+        # 將 email 寫入 text 輸出（$GITHUB_OUTPUT 為步驟輸出檔）
         echo "text=$email" >> "$GITHUB_OUTPUT"
+        # 以 0 正常退出，不再執行 codex exec
         exit 0
       fi
+      # 執行 Codex CLI：
+      #   --skip-git-repo-check 跳過 git repo 檢查（允許在非 git 目錄執行）
+      #   -s danger-full-access 沙箱模式設為完整存取（具高風險副作用，可讀寫檔案/網路）
+      #   --model "$MODEL" 指定使用的模型
+      #   "$PROMPT" 為要執行的提示詞；輸出以命令替換存入 text 變數
       text="$(codex exec --skip-git-repo-check -s danger-full-access --model "$MODEL" "$PROMPT")"
+      # 將 Codex 輸出列印到標準輸出（方便在記錄中檢視）
       printf '%s\n' "$text"
+      # 以 heredoc 方式將多行輸出寫入 $GITHUB_OUTPUT（避免換行破壞輸出格式）
       {
+        # 宣告 text 輸出，使用 CODEX_OUTPUT 作為 heredoc 結束標記
         echo 'text<<CODEX_OUTPUT'
+        # 寫入實際輸出內容
         printf '%s\n' "$text"
+        # heredoc 結束標記
         echo 'CODEX_OUTPUT'
       } >> "$GITHUB_OUTPUT"
+    # 指定以 bash 執行此 run 區塊
     shell: bash