docs(antigravity): 補齊 action 與 workflow 逐行註解並重建 README

action.yml

@@ -1,5 +1,8 @@
-# 用途：定義可在 GitHub Actions 中使用的 Antigravity CLI composite action，負責安裝 Antigravity CLI、設定 OAuth token、執行提示詞並輸出文字結果。
-# 更新日期：2026/06/27 23:35:00
+# 用途：定義可在 GitHub/Gitea Actions 中使用的 Antigravity CLI composite action，
+#       負責安裝 Antigravity CLI、解碼並寫入 OAuth token、以指定提示詞與模型執行 CLI，
+#       並把標準輸出回傳為 action 的 text output。模型名稱由 action 內部讀取
+#       repository variable（vars.ANTIGRAVITY_MODEL），不再透過 input 傳入。
+# 更新日期：2026/06/29 14:21:50
 
 # 設定 action 顯示名稱，供 workflow 引用與介面顯示。
 name: 'Antigravity CLI'
@@ -13,19 +16,19 @@ inputs:
   prompt:
     # 說明 prompt 輸入會被傳遞給 Antigravity CLI。
     description: '傳給 Antigravity CLI 的提示詞'
-    # 允許呼叫端不提供 prompt，未提供時使用預設值。
+    # 允許呼叫端不提供 prompt，未提供時使用下方預設值。
     required: false
-    # 設定 prompt 的預設提示詞。
+    # 設定 prompt 的預設提示詞，避免呼叫端未帶 prompt 時 CLI 缺少輸入。
     default: "請自我介紹"
-  # 定義 base64 編碼後的 OAuth token 檔案內容輸入。
+  # 定義 base64 編碼後的 OAuth token 檔案內容輸入（屬於 secret，請以 secrets 傳入）。
   oauth:
-    # 說明 oauth 輸入需提供 base64 編碼的 Antigravity OAuth token 檔案內容；不得在註解或日誌中輸出明文。
+    # 說明 oauth 輸入需提供 base64 編碼的 Antigravity OAuth token 檔案內容；此為敏感憑證，不得在註解、echo 或日誌中輸出明文。
     description: 'base64 編碼的 Antigravity OAuth token 檔案內容'
-    # 要求呼叫端必須提供 OAuth token 內容。
+    # 要求呼叫端必須提供 OAuth token 內容，缺少時 action 無法通過認證。
     required: true
 # 宣告此 action 會輸出的資料。
 outputs:
-  # 定義文字輸出欄位，供後續 workflow step 使用。
+  # 定義文字輸出欄位，供後續 workflow step 透過 steps.<id>.outputs.text 使用。
   text:
     # 說明 text 輸出為 Antigravity CLI 回傳的文字。
     description: '輸出的文字'
@@ -33,62 +36,68 @@ outputs:
     value: ${{ steps.antigravity.outputs.text }}
 # 宣告 action 的執行方式與步驟。
 runs:
-  # 指定此 action 使用 composite 執行模式。
+  # 指定此 action 使用 composite 執行模式（由多個 step 組成）。
   using: 'composite'
   # 定義 composite action 的執行步驟順序。
   steps:
-  # 建立安裝 Antigravity CLI 與設定認證檔案的步驟。
+  # 建立安裝 Antigravity CLI 與設定 OAuth 認證檔案的步驟。
   - name: 安裝工具
     # 宣告此步驟需要的環境變數。
     env:
-      # 將呼叫端提供的 oauth input 放入 OAUTH 環境變數，供 run 區塊解碼寫入檔案。
+      # 將呼叫端提供的 oauth input 放入 OAUTH 環境變數，供 run 區塊解碼寫入檔案；
+      # 透過 env 傳遞（而非直接內插到 run 字串）可避免 secret 明文出現在指令中。
       OAUTH: ${{ inputs.oauth }}
     # 執行 Antigravity CLI 安裝與 OAuth token 檔案建立流程。
     run: |
-      # 下載並執行 Antigravity CLI 安裝腳本，curl 失敗時會因 -f 參數讓指令失敗。
+      # 下載並以 bash 執行 Antigravity CLI 官方安裝腳本；
+      # curl -f 在 HTTP 錯誤時回傳非零，-sSL 為安靜模式並跟隨重導向，下載失敗時 pipeline 會中止。
       curl -fsSL https://antigravity.google/cli/install.sh | bash
-      # 將使用者本機安裝路徑加入 GitHub Actions 後續步驟的 PATH。
+      # 將安裝後 CLI 所在的使用者本機路徑寫入 $GITHUB_PATH，
+      # 使後續步驟的 PATH 能找到 agy 指令。
       echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
       # 設定 Antigravity CLI 預期讀取的 OAuth token 檔案路徑。
       oauth_file="$HOME/.gemini/antigravity-cli/antigravity-oauth-token"
-      # 建立 OAuth token 檔案所在目錄，並限制目錄權限為擁有者可讀寫執行。
+      # 建立 OAuth token 檔案所在目錄，並限制目錄權限為擁有者可讀寫執行（700），避免他人存取。
       install -d -m 700 "$(dirname "$oauth_file")"
-      # 將 OAUTH 環境變數中的 base64 內容解碼後寫入 token 檔案；此處不輸出 secret 明文。
+      # 將 OAUTH 環境變數中的 base64 內容解碼後寫入 token 檔案；
+      # 使用 printf 直寫不經 echo 額外換行，且全程不得輸出 secret 明文（勿加 set -x 或 echo "$OAUTH"）。
       printf '%s' "$OAUTH" | base64 -d > "$oauth_file"
-      # 限制 token 檔案權限為擁有者可讀寫，避免其他使用者讀取。
+      # 限制 token 檔案權限為擁有者可讀寫（600），避免其他使用者讀取憑證。
       chmod 600 "$oauth_file"
     # 指定此步驟使用 bash shell 執行。
     shell: bash
   # 建立執行 Antigravity CLI 並寫入 action output 的步驟。
   - name: 執行工具
-    # 設定步驟 id，供 outputs.text 透過 steps.antigravity.outputs.text 取得結果。
+    # 設定步驟 id 為 antigravity，供上方 outputs.text 透過 steps.antigravity.outputs.text 取得結果。
     id: antigravity
     # 宣告此步驟需要的環境變數。
     env:
-      # 從 repository variable 讀取 Antigravity CLI 使用的模型名稱。
+      # 從 repository variable 讀取 Antigravity CLI 使用的模型名稱（取代舊有的 model input）。
       MODEL: ${{ vars.ANTIGRAVITY_MODEL }}
-      # 將呼叫端提供的 prompt input 放入 PROMPT 環境變數。
+      # 將呼叫端提供的 prompt input 放入 PROMPT 環境變數，避免直接內插造成的引號/注入問題。
       PROMPT: ${{ inputs.prompt }}
     # 執行 Antigravity CLI，列印結果並寫入 GitHub Actions output。
     run: |
-      # 確認呼叫端 repository 已設定 ANTIGRAVITY_MODEL variable。
+      # 前置檢查：確認呼叫端 repository 已設定 ANTIGRAVITY_MODEL variable，未設定則明確報錯並中止，
+      # 避免以空模型名稱呼叫 CLI 而產生不明確的失敗。
       if [ -z "$MODEL" ]; then
         echo 'ANTIGRAVITY_MODEL repository variable is required.' >&2
         exit 1
       fi
 
-      # 使用指定提示詞與模型執行 Antigravity CLI，並把標準輸出捕捉到 text 變數。
+      # 使用指定提示詞與模型執行 Antigravity CLI（agy --print 為一次性輸出模式），
+      # 並以命令替換把標準輸出捕捉到 text 變數。
       text="$(agy --print "$PROMPT" --model "$MODEL")"
-      # 將 Antigravity CLI 回傳文字輸出到目前步驟日誌。
+      # 將 Antigravity CLI 回傳文字輸出到目前步驟日誌，方便檢視結果。
       printf '%s\n' "$text"
-      # 開始以 GitHub Actions multiline output 格式寫入 text 輸出。
+      # 以群組指令一次性將 text 寫入 $GITHUB_OUTPUT，採用 multiline output 格式以支援多行內容。
       {
-        # 寫入 multiline output 的起始標記。
+        # 寫入 multiline output 的起始標記（heredoc 風格的結束符為 ANTIGRAVITY_OUTPUT）。
         echo 'text<<ANTIGRAVITY_OUTPUT'
         # 寫入 Antigravity CLI 回傳文字內容。
         printf '%s\n' "$text"
-        # 寫入 multiline output 的結束標記。
+        # 寫入 multiline output 的結束標記，需與起始標記一致。
         echo 'ANTIGRAVITY_OUTPUT'
       } >> "$GITHUB_OUTPUT"
     # 指定此步驟使用 bash shell 執行。