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

.gitea/workflows/cd.yaml

@@ -1,29 +1,31 @@
-# 用途：定義 CD 工作流程，在 master 分支收到 push 時執行版本標籤釋出流程。
-# 更新日期：2026/06/27 23:21:07
+# 用途：定義 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，job id 為 release-tag-version。
   release-tag-version:
-    # 設定 job 在 Gitea Actions 介面中顯示的名稱。
+    # 設定此 job 在 Gitea Actions 介面中顯示的名稱。
     name: Release Tag Version
     # 指定此 job 使用 ubuntu runner 執行。
     runs-on: ubuntu
     # 定義此 job 內依序執行的步驟。
     steps:
-    # 建立釋出並標註成品版本的步驟。
+    # 步驟：釋出並標註成品版本。
     - name: 釋出並標註成品版本
-      # 呼叫共用 composite action，版本由 ACTION_RELEASE_TAG_VERSION 變數決定。
+      # 呼叫共用的 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/27 23:21:07
+# 更新日期：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 開啟或同步更新時觸發。
+    # 限定只在 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 對外提供的輸出值。
+    # 宣告此 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 action，版本由 repository variable 指定。
+      # 使用內部 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 版本號，讓後續測試使用預發版本格式。
+        # 指定計算 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 需要先完成版本號 job，才能取得其輸出版本。
+    # 宣告此 job 需要先完成 release-tag-version job，才能取得其輸出版本（建立執行順序相依）。
     needs: release-tag-version
     # 定義 Antigravity 測試 job 的執行步驟。
     steps:
     # 使用剛計算出的版本呼叫本 composite action，驗證工具可正常取得模型輸出。
     - name: 測試工具
-      # 設定 step id，讓後續步驟可以引用此 step 的輸出文字。
+      # 設定 step id，讓後續步驟可以引用此 step 的輸出文字（steps.antigravity.outputs.text）。
       id: antigravity
-      # 使用本 Antigravity composite action，版本來自前一個 job 的輸出。
+      # 使用本 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: 檢查輸出
-      # 只有在輸出文字不等於預期 repository variable 時才執行失敗指令。
+      # 只有在 antigravity step 的輸出文字不等於預期 repository variable（ANTIGRAVITY_EMAIL）時才執行下方失敗指令。
       if: ${{ steps.antigravity.outputs.text != vars.ANTIGRAVITY_EMAIL }}
-      # 以非零結束碼結束此步驟，讓 CI 明確標示測試失敗。
+      # 以非零結束碼（exit 1）結束此步驟，讓 CI 明確標示測試失敗。
       run: exit 1