chore(ci): 移除測試 job 的工具輸出 step

.gitea/workflows/cd.yaml

@@ -1,32 +1,31 @@
-# 用途：定義 CD（持續部署）工作流程，當 master 分支收到 push 時執行版本標籤釋出流程。
-# 更新日期：2026/06/29 16:11:33
+# 用途：定義 CD（持續部署）工作流程，當 master 分支收到 push 時，執行「版本標籤釋出（release tag）」流程。
+# 更新日期：2026/06/29 14:21:50
 
-# 設定此 Gitea Actions workflow 顯示名稱為 CD，方便在工作流程清單中辨識。
+# 設定此 Gitea Actions workflow 的顯示名稱為 CD，方便在 Actions 工作流程清單中辨識。
 name: CD
 
 # 定義觸發此 workflow 的事件條件。
 on:
-  # 當程式碼被 push 到指定分支時觸發部署流程。
+  # 監聽 push 事件：當有 commit 被推送到指定分支時觸發。
   push:
-    # 指定只監聽下列分支的 push 事件。
+    # 指定只針對下列分支的 push 事件生效。
     branches:
-    # 限定 master 分支被推送時才執行 CD workflow（其他分支不觸發）。
+    # 限定僅 master 分支被推送時才執行此 CD workflow（避免其他分支誤觸發釋出）。
     - master
 
 # 定義此 workflow 需要執行的所有 job。
 jobs:
-  # 建立負責釋出版本標籤的 job（job id：release-tag-version）。
+  # 建立負責釋出並標註版本標籤的 job，job id 為 release-tag-version。
   release-tag-version:
-    # 設定 job 在 Gitea Actions 介面中顯示的名稱。
+    # 設定此 job 在 Gitea Actions 介面中顯示的名稱。
     name: Release Tag Version
-    # 指定此 job 使用 ubuntu runner 執行（runner label：ubuntu）。
+    # 指定此 job 使用 ubuntu runner 執行。
     runs-on: ubuntu
     # 定義此 job 內依序執行的步驟。
     steps:
-    # 建立釋出並標註成品版本的步驟（step 顯示名稱）。
+    # 步驟：釋出並標註成品版本。
     - name: 釋出並標註成品版本
-      # 呼叫共用 composite action 來執行釋出與打標籤；
-      # 版本（ref/tag）由 repository variable ACTION_RELEASE_TAG_VERSION 動態決定，
-      # 來源為 https://gitea.jsc.idv.tw/composite-actions/release-tag-version。
-      # 副作用：依該 composite action 行為對 repo 建立 / 推送版本標籤。
+      # 呼叫共用的 composite action release-tag-version 來完成版本標籤釋出；
+      # 使用的 action 版本由 repository variable ACTION_RELEASE_TAG_VERSION 動態決定，
+      # 可在不改動本檔案的情況下集中切換所引用的 action 版本。
       uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}

.gitea/workflows/ci.yaml

@@ -1,5 +1,5 @@
 # 用途：在 pull request 更新時執行 CI，先計算測試用版本號，再用該版本呼叫 Antigravity composite action 並驗證輸出內容。
-# 更新日期：2026/06/29 16:11:33
+# 更新日期：2026/06/29 14:21:50
 
 # 定義此 Gitea Actions workflow 顯示的名稱。
 name: CI
@@ -10,9 +10,9 @@ on:
   pull_request:
     # 指定 pull request 目標分支的忽略清單，避免 master 分支觸發此 workflow。
     branches-ignore:
-    # 忽略目標分支為 master 的 pull request。
+    # 忽略目標分支為 master 的 pull request（避免正式分支誤觸 CI）。
     - master
-    # 限定只在 pull request 開啟（opened）或同步更新（synchronize）時觸發。
+    # 限定只在 pull request 開啟（opened）或同步更新（synchronize，即推新 commit）時觸發。
     types: [opened, synchronize]
 
 # 定義 workflow 內要執行的 jobs。
@@ -23,7 +23,7 @@ jobs:
     name: Release Tag Version
     # 指定此 job 在 ubuntu runner 上執行。
     runs-on: ubuntu
-    # 宣告此 job 對外提供的輸出值（outputs），供 needs 此 job 的 jobs 取用。
+    # 宣告此 job 對外提供的輸出值，讓 needs 此 job 的其他 job 可引用。
     outputs:
       # 將 release-tag-version step 計算出的 version 輸出給需要此 job 的後續 jobs。
       version: ${{ steps.release-tag-version.outputs.version }}
@@ -33,11 +33,11 @@ jobs:
     - name: 計算版本號
       # 設定 step id，讓 job outputs 可以引用此 step 的輸出。
       id: release-tag-version
-      # 使用內部 release-tag-version composite action，所用版本由 repository variable ACTION_RELEASE_TAG_VERSION 指定。
+      # 使用內部 release-tag-version action，action 版本由 repository variable ACTION_RELEASE_TAG_VERSION 指定（集中管理版本以便升級）。
       uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}
       # 傳入 release-tag-version action 的參數。
       with:
-        # 指定計算 beta 版本號（is_beta=true），讓後續測試使用預發（pre-release）版本格式。
+        # 指定計算 beta 版本號，讓後續測試使用預發（pre-release）版本格式，避免佔用正式 tag。
         is_beta: 'true'
 
   # 建立測試 Antigravity composite action 的 job。
@@ -46,25 +46,25 @@ jobs:
     name: Antigravity
     # 指定此 job 在 ubuntu runner 上執行。
     runs-on: ubuntu
-    # 宣告此 job 需要先完成 release-tag-version job（needs），才能取得其輸出版本。
+    # 宣告此 job 需要先完成 release-tag-version job，才能取得其輸出版本（建立執行順序相依）。
     needs: release-tag-version
     # 定義 Antigravity 測試 job 的執行步驟。
     steps:
     # 使用剛計算出的版本呼叫本 composite action，驗證工具可正常取得模型輸出。
     - name: 測試工具
-      # 設定 step id，讓後續步驟可以引用此 step 的輸出文字（outputs.text）。
+      # 設定 step id，讓後續步驟可以引用此 step 的輸出文字（steps.antigravity.outputs.text）。
       id: antigravity
-      # 使用本 Antigravity composite action，版本來自前一個 job 的輸出（needs.release-tag-version.outputs.version）。
+      # 使用本 Antigravity composite action，版本來自前一個 job 輸出的 version，前綴 v 組成 release tag。
       uses: https://gitea.jsc.idv.tw/composite-actions/antigravity@v${{ needs.release-tag-version.outputs.version }}
       # 傳入 Antigravity action 所需的輸入參數。
       with:
-        # 傳入 Antigravity OAuth token secret 參照；此處只保留 secret 名稱引用，不包含 secret 明文。
+        # 傳入 Antigravity OAuth token secret 參照；此處只保留 secret 名稱引用，執行時才解析，不包含 secret 明文。
         oauth: ${{ secrets.ANTIGRAVITY_OAUTH }}
-        # 傳入測試提示詞，要求工具回傳目前登入的 Google 帳號電子郵件。
+        # 傳入測試提示詞，要求工具回傳目前登入的 Google 帳號電子郵件，作為驗證輸出正確性的依據。
         prompt: "請告訴我目前登入的Google帳號，只要電子郵件不要其他任何資訊"
     # 比對 Antigravity action 的輸出與預期電子郵件，不一致時讓 workflow 失敗。
     - name: 檢查輸出
-      # 只有在輸出文字（outputs.text）不等於預期 repository variable ANTIGRAVITY_EMAIL 時才執行失敗指令。
+      # 只有在 antigravity step 的輸出文字不等於預期 repository variable（ANTIGRAVITY_EMAIL）時才執行下方失敗指令。
       if: ${{ steps.antigravity.outputs.text != vars.ANTIGRAVITY_EMAIL }}
       # 以非零結束碼（exit 1）結束此步驟，讓 CI 明確標示測試失敗。
       run: exit 1

README.md

@@ -1,8 +1,8 @@
 # Antigravity CLI Composite Action
 
-更新時間：2026/06/29 16:11:33
+更新時間：2026/06/29 14:21:50
 
-此 repository 提供一個 Gitea / GitHub Actions composite action，負責安裝 Antigravity CLI（`agy`）、寫入 base64 解碼後的 OAuth token、以指定提示詞與模型執行 CLI，並將 CLI 的文字輸出寫入 action output。模型名稱由 action 直接從 repository variable `ANTIGRAVITY_MODEL` 讀取。
+此 repository 提供一個 Gitea/GitHub Actions composite action，用於安裝 Antigravity CLI、解碼並寫入 OAuth token、以指定提示詞與模型執行 CLI，並將 CLI 的標準輸出寫入 action output。模型名稱由 action 內部直接讀取 repository variable `vars.ANTIGRAVITY_MODEL`。
 
 ## 專案列表
 
@@ -10,7 +10,7 @@
 
 | 專案名稱 | 專案描述 |
 | --- | --- |
-| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/develop) | Gitea / GitHub Actions composite action：安裝 Antigravity CLI、設定 OAuth token、依 `prompt` 與 `ANTIGRAVITY_MODEL` 執行 CLI，並輸出 `text` 文字結果。本專案不含可列入 README 的程式語言公開方法，對外能力即此 composite action 本身。 |
+| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/develop) | 提供 Antigravity CLI composite action：安裝 `agy` CLI、以 base64 解碼寫入 OAuth token，並以呼叫端的 `prompt` 輸入與 repository variable 指定的模型執行 CLI，最後將文字輸出回傳為 `text` output。 |
 
 ### 參考專案
 
@@ -26,23 +26,13 @@
 
 ## 功能列表
 
-此 repository 未包含可列入 README 的 public method、public constructor、public extension method 或 public operator。本專案為 Gitea / GitHub Actions composite action，對外能力為 action 本身（透過 `action.yml` 的 `inputs` / `outputs` 對外提供），非程式語言方法，故無功能方法可列出。
-
-對外介面摘要如下（定義於 [`action.yml`](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/develop/action.yml)）：
-
-| 介面 | 類型 | 必填 | 說明 |
-| --- | --- | --- | --- |
-| `prompt` | input | 否 | 傳給 Antigravity CLI 的提示詞，預設為「請自我介紹」。 |
-| `oauth` | input | 是 | base64 編碼的 Antigravity OAuth token 檔案內容（機敏資料，不得記錄明文）。 |
-| `text` | output | — | Antigravity CLI 回傳的文字輸出。 |
-
-> 模型名稱不由 input 傳入，而是由 action 於執行時讀取 repository variable `ANTIGRAVITY_MODEL`。
+此 repository 為 composite action（YAML + bash）專案，未包含可列入 README 的 public method、public constructor、public extension method 或 public operator。
 
 ## 使用範例
 
 ### 在 workflow 中呼叫 Antigravity CLI
 
-以下範例示範在 workflow step 中呼叫此 composite action，傳入 OAuth token 與提示詞，並在後續步驟讀取 `text` output。模型名稱由 action 直接讀取 `vars.ANTIGRAVITY_MODEL`。
+以下範例示範在 workflow step 中呼叫此 composite action，傳入 OAuth token 與提示詞，並在後續步驟讀取 `text` output。模型名稱由 action 直接讀取 `vars.ANTIGRAVITY_MODEL`，呼叫端不需傳入 model。
 
 ```yaml
 - name: 執行 Antigravity CLI
@@ -59,15 +49,11 @@
 前置條件：
 
 - `secrets.ANTIGRAVITY_OAUTH` 必須是 Antigravity OAuth token 檔案內容的 base64 字串。
-- `vars.ANTIGRAVITY_MODEL` 必須是 Antigravity CLI 可用的模型名稱；未設定時 action 會直接失敗並提示需設定此 repository variable。
+- `vars.ANTIGRAVITY_MODEL` 必須是 Antigravity CLI 可用的模型名稱（未設定時 action 會直接失敗）。
 - runner 必須可連線到 `https://antigravity.google/cli/install.sh` 以下載 CLI。
 
 預期結果：
 
-- action 會安裝 `agy` CLI 並將 `$HOME/.local/bin` 加入 `PATH`。
-- action 會將 OAuth token 寫入 `$HOME/.gemini/antigravity-cli/antigravity-oauth-token`，並將目錄權限設為 `700`、檔案權限設為 `600`。
+- action 會安裝 `agy` CLI。
+- action 會將 OAuth token 寫入 `$HOME/.gemini/antigravity-cli/antigravity-oauth-token` 並設定檔案權限為 `600`。
 - action 會執行 `agy --print "$PROMPT" --model "$MODEL"`，並把 stdout 寫入 `steps.antigravity.outputs.text`。
-
-### 搭配 CI workflow 驗證輸出
-
-`.gitea/workflows/ci.yaml` 會在 pull request（目標分支非 `master`）開啟或同步更新時，先以 `release-tag-version` action 計算 beta 版本號，再用該版本呼叫本 action 取得輸出，並比對 `vars.ANTIGRAVITY_EMAIL`，不一致時讓 CI 失敗。`.gitea/workflows/cd.yaml` 則在 `master` 收到 push 時執行版本標籤釋出流程。

action.yml

@@ -1,5 +1,8 @@
-# 用途：定義可在 GitHub Actions 中使用的 Antigravity CLI composite action，負責安裝 Antigravity CLI、設定 OAuth token、執行提示詞並輸出文字結果。
-# 更新日期：2026/06/29 16:11:33
+# 用途：定義可在 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,23 +16,23 @@ 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: '輸出的文字'
-    # 將輸出值對應到 id 為 antigravity 的步驟所寫入的 text output。
+    # 將輸出值對應到 antigravity step 寫入的 text output。
     value: ${{ steps.antigravity.outputs.text }}
 # 宣告 action 的執行方式與步驟。
 runs:
@@ -37,60 +40,72 @@ runs:
   using: 'composite'
   # 定義 composite action 的執行步驟順序。
   steps:
-  # 第一步：建立安裝 Antigravity CLI 與設定認證檔案的步驟。
+  # 建立安裝 Antigravity CLI 與設定 OAuth 認證檔案的步驟。
   - name: 安裝工具
     # 宣告此步驟需要的環境變數。
     env:
-      # 將呼叫端提供的 oauth input 放入 OAUTH 環境變數，供 run 區塊解碼寫入檔案；此值為 secret，不可記錄到日誌。
+      # 將呼叫端提供的 oauth input 放入 OAUTH 環境變數，供 run 區塊解碼寫入檔案；
+      # 透過 env 傳遞（而非直接內插到 run 字串）可避免 secret 明文出現在指令中。
       OAUTH: ${{ inputs.oauth }}
     # 執行 Antigravity CLI 安裝與 OAuth token 檔案建立流程。
     run: |
-      # 下載並執行 Antigravity CLI 安裝腳本；curl -f 在 HTTP 錯誤時會讓指令失敗，-sSL 為靜默、顯示錯誤、跟隨重導。
+      # 前置檢查：確認 OAUTH 不為空；為空代表呼叫端未提供 secrets.ANTIGRAVITY_OAUTH。
+      if [ -z "$OAUTH" ]; then
+        # 將錯誤訊息輸出到標準錯誤，提示需提供 oauth input。
+        echo 'oauth input (secrets.ANTIGRAVITY_OAUTH) is required and must not be empty.' >&2
+        # 以非零退出碼結束步驟，使整個 action 失敗，避免後續寫入空白 token。
+        exit 1
+      fi
+
+      # 下載並以 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 檔案所在目錄，並限制目錄權限為擁有者可讀寫執行（700）。
+      # 建立 OAuth token 檔案所在目錄，並限制目錄權限為擁有者可讀寫執行（700），避免他人存取。
       install -d -m 700 "$(dirname "$oauth_file")"
-      # 將 OAUTH 環境變數中的 base64 內容解碼後寫入 token 檔案；此處輸出的是 secret 明文檔案，切勿 echo 或記錄其內容。
+      # 將 OAUTH 環境變數中的 base64 內容解碼後寫入 token 檔案；
+      # 使用 printf 直寫不經 echo 額外換行，且全程不得輸出 secret 明文（勿加 set -x 或 echo "$OAUTH"）。
       printf '%s' "$OAUTH" | base64 -d > "$oauth_file"
-      # 限制 token 檔案權限為擁有者可讀寫（600），避免其他使用者讀取機敏 token。
+      # 限制 token 檔案權限為擁有者可讀寫（600），避免其他使用者讀取憑證。
       chmod 600 "$oauth_file"
     # 指定此步驟使用 bash shell 執行。
     shell: bash
-  # 第二步：建立執行 Antigravity CLI 並寫入 action output 的步驟。
+  # 建立執行 Antigravity CLI 並寫入 action output 的步驟。
   - name: 執行工具
-    # 設定步驟 id 為 antigravity，供 outputs.text 透過 steps.antigravity.outputs.text 取得結果。
+    # 設定步驟 id 為 antigravity，供上方 outputs.text 透過 steps.antigravity.outputs.text 取得結果。
     id: antigravity
     # 宣告此步驟需要的環境變數。
     env:
-      # 從 repository variable 讀取 Antigravity CLI 使用的模型名稱（ANTIGRAVITY_MODEL）。
+      # 從 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
-        # 將錯誤訊息輸出到標準錯誤，提示需設定 ANTIGRAVITY_MODEL repository variable。
         echo 'ANTIGRAVITY_MODEL repository variable is required.' >&2
-        # 以非零退出碼結束步驟，使整個 action 失敗。
         exit 1
       fi
 
-      # 使用指定提示詞與模型執行 Antigravity CLI（agy --print），並把標準輸出捕捉到 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 輸出（使用 here-string 邊界）。
+      # 以群組指令一次性將 text 寫入 $GITHUB_OUTPUT，採用 multiline output 格式以支援多行內容。
       {
-        # 寫入 multiline output 的起始標記（heredoc 邊界 ANTIGRAVITY_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 執行。