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

action.yml

@@ -1,27 +1,68 @@
+# =============================================================================
+# 指令檔用途：Gitea composite action —「Setup Codex CLI」
+#   本檔定義一個組合式（composite）action，負責在 CI/CD runner 上：
+#     1) 下載並安裝 Codex CLI 工具，並將其執行檔目錄加入 PATH。
+#     2) 使用外部傳入、經 base64 編碼的 OAuth 驗證檔完成 Codex 登入。
+#     3) 解析登入驗證檔中的 id_token，輸出目前登入的帳號 email 以供確認。
+#   使用情境：讓後續 workflow 步驟可直接呼叫已登入的 Codex CLI。
+# 更新日期：2026/07/03 11:41:20
+# =============================================================================
+
+# action 名稱：顯示於 Gitea/GitHub Actions UI 上的識別名稱
 name: 'Setup Codex CLI'
+# action 說明：簡述此 action 的功能（安裝 Codex CLI 工具）
 description: '安裝 Codex CLI 工具'
+# 作者資訊
 author: 'Jeffery'
+# inputs：定義呼叫此 action 時可傳入的參數
 inputs:
+  # 參數 oauth：ChatGPT OAuth 登入後產生的驗證檔內容
   oauth:
+    # 參數說明：透過 OAuth 登入 ChatGPT 產生的驗證檔，內容須先經 base64 編碼再傳入
     description: '透過 OAuth 登入 ChatGPT 產生驗證檔，經過 base64 編碼'
+    # required: true 表示此參數為必填，未提供時 action 會失敗
     required: true
+# outputs：定義此 action 執行後對外輸出的值
 outputs:
+  # 輸出 message：供呼叫端取用的訊息輸出
   message:
+    # 輸出說明
     description: '輸出訊息'
+    # 【需人工確認】此 output 參照名為 `exchange` 的 step 之 outputs.message，
+    # 但本 action 的 steps 中並不存在 id 為 `exchange` 的步驟，
+    # 因此此 output 很可能取不到值（會是空字串）。此處僅標註，未修改該行內容。
     value: ${{ steps.exchange.outputs.message }}
+# runs：定義此 action 的執行方式與步驟
 runs:
+  # using: 'composite' 表示這是組合式 action，由下方多個 shell step 組成
   using: 'composite'
+  # steps：依序執行的步驟清單
   steps:
+  # 步驟一：安裝 Codex CLI
   - name: Setup Codex
+    # env：此步驟專用的環境變數
     env:
+      # CODEX_NON_INTERACTIVE=1：讓 Codex 以非互動模式執行，避免安裝過程等待輸入而卡住 CI
       CODEX_NON_INTERACTIVE: 1
+    # run：以 shell 執行的安裝指令（多行）
     run: |
+      # 從官方網址下載安裝腳本並直接以 sh 執行（-f 失敗即報錯、-s 靜默、-S 顯示錯誤、-L 跟隨轉址）
       curl -fsSL https://chatgpt.com/codex/install.sh | sh
+      # 將 Codex 執行檔安裝目錄寫入 $GITHUB_PATH，使後續步驟能直接呼叫 codex 指令
       echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+    # shell: bash 指定以 bash 執行上方 run 內容（composite step 需明確指定 shell）
     shell: bash
+  # 步驟二：使用 OAuth 驗證檔登入 Codex
   - name: Login Codex with OAuth
+    # env：此步驟專用環境變數
     env:
+      # 將呼叫端傳入的 oauth 參數（base64 字串）帶入環境變數 OAUTH
       OAUTH: ${{ inputs.oauth }}
+    # run：將 base64 字串解碼後還原成 auth.json 驗證檔，供 Codex CLI 讀取登入狀態
+    # 副作用：會在 runner 家目錄產生 ~/.codex/auth.json（含機敏憑證），請勿外洩或輸出其內容
     run: echo $OAUTH | base64 --decode > ~/.codex/auth.json
+  # 步驟三：顯示目前登入的 Codex 帳號
   - name: Show Codex Account
-    run: node -e 'console.log(JSON.parse(Buffer.from(JSON.parse(require("fs").readFileSync(process.env.HOME+"/.codex/auth.json")).tokens.id_token.split(".")[1],"base64")).email)'
+    # run：以 node 讀取 auth.json，解析 tokens.id_token（JWT）的 payload（第 2 段 base64）取出 email 並印出
+    # 副作用【重要】：此行會將登入帳號的 email 輸出到 workflow log，log 內會出現帳號 email，請留意隱私與存取權限
+    run: node -e 'console.log(JSON.parse(Buffer.from(JSON.parse(require("fs").readFileSync(process.env.HOME+"/.codex/auth.json")).tokens.id_token.split(".")[1],"base64")).email)'