docs(antigravity): 補齊指令檔逐行註解並重建 README

README.md

@@ -1,8 +1,8 @@
 # Antigravity CLI Composite Action
 
-更新時間：2026/06/27 23:35:00
+更新時間：2026/06/29 16:11:33
 
-此 repository 提供一個 Gitea/GitHub Actions composite action，用於安裝 Antigravity CLI、寫入 OAuth token、執行指定提示詞，並將 CLI 輸出寫入 action output。
+此 repository 提供一個 Gitea / GitHub Actions composite action，負責安裝 Antigravity CLI（`agy`）、寫入 base64 解碼後的 OAuth token、以指定提示詞與模型執行 CLI，並將 CLI 的文字輸出寫入 action output。模型名稱由 action 直接從 repository variable `ANTIGRAVITY_MODEL` 讀取。
 
 ## 專案列表
 
@@ -10,23 +10,33 @@
 
 | 專案名稱 | 專案描述 |
 | --- | --- |
-| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/ai-review-resolve/develop-20260627-142726) | 提供 Antigravity CLI composite action，讓 workflow 可透過 `oauth` 與 `prompt` 輸入執行 CLI，並從 repository variable 讀取模型名稱後取得文字輸出。 |
+| [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/ai-review-resolve/develop-20260627-142726) | 無 |
+| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/develop) | 無 |
 
 ### NuGet 套件
 
 | 專案名稱 | NuGet 套件列表 |
 | --- | --- |
-| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/ai-review-resolve/develop-20260627-142726) | 無 |
+| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/develop) | 無 |
 
 ## 功能列表
 
-此 repository 未包含可列入 README 的 public method、public constructor、public extension method 或 public operator。
+此 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`。
 
 ## 使用範例
 
@@ -49,11 +59,15 @@
 前置條件：
 
 - `secrets.ANTIGRAVITY_OAUTH` 必須是 Antigravity OAuth token 檔案內容的 base64 字串。
-- `vars.ANTIGRAVITY_MODEL` 必須是 Antigravity CLI 可用的模型名稱。
+- `vars.ANTIGRAVITY_MODEL` 必須是 Antigravity CLI 可用的模型名稱；未設定時 action 會直接失敗並提示需設定此 repository variable。
 - runner 必須可連線到 `https://antigravity.google/cli/install.sh` 以下載 CLI。
 
 預期結果：
 
-- action 會安裝 `agy` CLI。
-- action 會將 OAuth token 寫入 `$HOME/.gemini/antigravity-cli/antigravity-oauth-token` 並設定檔案權限為 `600`。
+- action 會安裝 `agy` CLI 並將 `$HOME/.local/bin` 加入 `PATH`。
+- action 會將 OAuth token 寫入 `$HOME/.gemini/antigravity-cli/antigravity-oauth-token`，並將目錄權限設為 `700`、檔案權限設為 `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 時執行版本標籤釋出流程。