今天要做什麼外掛（Plugins）

1. 名稱：antigravity-cli-statusline
2. GitHub：https://github.com/AndyAWD/antigravity-cli-statusline

這個是 Agy CLI 的底部狀態列外掛，他提供 26 個功能顯示，和多國語言，目前 96 顆星，是 Agy CLI 底部狀態列星星最多的專案

為什麼要做這個外掛（Plugins）和過程

因為是 GDG 的關係，Google 送我一年份的 GDP 訂閱，簡單說就是有一萬五台幣的 GCP 額度可以用，所以我以前用 Gemini CLI 是用高貴的 API 實現 Token 自由，不用管什麼五小時額度

題外話，就算用 API 也是用每日用量上限的，去年做畫面截圖轉 Compose 的 Skills 時就撞到 API 的每日上限

但今年 Google I/O 後主推 Agy CLI，那時候想要留一點額度測試 Gemini 3.5 Pro，所以改用帳號額度，結果一下子就達到五小時上限，但每次還要輸入 /usage 看即時用量真的很煩，所以就動起修改底部狀態列的念頭

但 Agy CLI 1.0.0 的時候真的很血尿，問 Gemini 3.1 Pro 和 3.5 Flash，他們都說無法即時拿到用量額度，這是很反直覺的，沒道理輸入指令就能看到，但沒辦法顯示在底部狀態列

後來還是用傳統技術「Google」一下，沒想到已經有一位 60ke 的大大寫出有額度顯示的狀態列 antigravity-statusline
，請 Gemini 把專案 Clone 下來後終於知道做法，但他的腳本是用 Python 寫的，這在跨作業系統是個大坑（別問我為什麼知道，只要知道我很會寫跨平台 Skillsㄐ就好），所以用 JS 改寫完第一版

第一版下了很多功夫讓 Agy CLI 自己完成底部狀態欄的安裝，所以你看其他的專案還要自己設定 setting.json 之類的，但我的都不用，所以拿去 Reddit 宣傳後星星開始多起來，後來保哥也 Clone 一份過去，他給我一個很好的想法，就是「用一個命令就可以自動安裝好工具」

所以我想到 Gemini CLI 有 Extended，Agy CLI 應該也有，然後又繼續忍受 Gemini 3.6 Flash 的口胡，終於把這個專案 Plugins 化，從此一個指令完成安裝，一個指令完成設定，真是太感動了

另外這個專案完全使用 Agy CLI 的 Gemini，沒有用任何他牌 AI，專案的 Contributors
出現 Claude 的原因是使用 Claude 做這個專案的簡報

目錄結構

專案採用 Antigravity CLI 標準外掛目錄配置，根目錄與各子模組職責劃分明確：

antigravity-cli-statusline/
├── plugin.json                              # 外掛中介資料與設定宣告
├── README.md                                # 英文說明文件
├── README.zh-TW.md                          # 繁體中文說明文件
├── CONTRIBUTING.md                          # 貢獻與開發指南
├── LICENSE                                  # MIT 授權條款
├── PROJECT.md                               # 安全性修復與里程碑紀錄
├── ORIGINAL_REQUEST.md                      # 需求追蹤與歷程檔案
├── docs/                                    # 文件與靜態資產
│   ├── images/                              # 跨平台實際執行畫面截圖
│   └── workshop/                            # GDG 工作坊 reveal.js 簡報與教材
└── skills/
    └── antigravity-cli-statusline/          # 狀態列核心技能目錄
        ├── SKILL.md                         # 技能行為指引與工作流程定義
        ├── resources/
        │   └── questions.json               # 三語系靜態指標選單定義
        ├── references/
        │   ├── config-files.md              # 三層設定檔結構與權限規範
        │   ├── pitfalls.md                  # 跨平台常見陷阱對照表
        │   └── windows.md                   # Windows 專屬 BOM 與編譯指南
        └── scripts/
            ├── statusline-quota.mjs         # 狀態列前台即時渲染腳本
            ├── fetch-local-quota.mjs        # 背景定期額度快取抓取腳本
            ├── configure-statusline.mjs     # 互動式設定與多層寫檔腳本
            ├── diagnose-statusline.mjs      # 狀態列健康檢查與診斷腳本
            ├── sh_hidden.cs                 # Windows 靜默無窗體 C# 橋接器原始碼
            ├── statusline-quota.test.mjs    # 狀態列渲染測試腳本
            ├── fetch-local-quota.test.mjs   # 快取邏輯測試腳本
            ├── configure-statusline.test.mjs# 設定安全性整合測試腳本
            └── test-counters.mjs            # 指標計算與計數器測試腳本

各核心檔案詳細職責如下：

• plugin.json：向 Antigravity CLI 宣告外掛名稱、版本號、作者及授權，作為外掛載入時的識別進入點。
• SKILL.md：定義給人工智慧代理讀取的操作手冊，明確規範如何執行預檢、如何引導使用者選擇語系與指標，以及部署腳本時必須遵守的安全鐵則。
• questions.json：將 26 項指標在繁體中文、英文、日文中的名稱、說明與識別碼預先定義為靜態檔案，杜絕人工智慧生成時的陣列截斷與隨機翻譯問題。
• statusline-quota.mjs：由 CLI 的 statusLine 掛鉤在每次刷新介面時執行的主腳本。負責讀取快取檔案、查詢 Git 狀態、計算全形與半形字元寬度、執行自動折行，並格式化輸出帶 ANSI 真彩色的文字。
• fetch-local-quota.mjs：於背景非同步定期運行的快取腳本。負責取得 agy 行程與 CSRF 權杖，透過本地端點拉取最新額度與脈絡資訊並寫入暫存檔，確保前台不被網路或行程 I/O 阻塞。
• configure-statusline.mjs：自動化部署腳本。依據使用者所選的語系與排序字串，將掛鉤腳本複製到使用者家目錄，並同步寫入三層設定檔與信任白名單。
• sh_hidden.cs：提供給 Windows 系統編譯的橋接程式，用以攔截 sh -c 指令並以無窗體方式執行，徹底根除黑視窗閃爍。

這外掛怎麼用

環境需求

1. Node.js（必要）：狀態列渲染與快取程式均為原生 JavaScript（.mjs）撰寫。若作業系統缺少 Node.js 執行檔，狀態列腳本將無法執行，且在多次失敗後會被 agy CLI 自動關閉。在執行設定前請確認終端機輸入 node -v 能正常回傳版本號。
2. Git（選用）：若需要顯示目前 Git 分支名稱與工作區變更狀態（vcs-dirty），系統需具備 Git 執行環境。

安裝方式

在任何終端機視窗中執行以下外掛安裝指令：

agy plugin install https://github.com/andyawd/antigravity-cli-statusline

執行後，Antigravity CLI 會自動將外掛程式碼複製並部署至全域外掛目錄：~/.gemini/antigravity-cli/plugins/antigravity-cli-statusline/。

啟用與設定流程

安裝完成後，開啟 Antigravity CLI 並在提示字元中輸入：

/antigravity-cli-statusline

此時會觸發互動式精靈，依序引導完成以下設定：

1. 選擇介面語言：提供繁體中文（zh-tw）、英文（us）與日文（jp）三種語系。
2. 勾選欲顯示的狀態列指標：從 26 項指標中自由複選（預設已勾選常用組合）。
3. 自訂排序與換行：
   • 留白或選擇略過：維持勾選時的預設順序顯示。
   • 自訂順序：在輸入框中以逗號分隔填入指標代號或序號（例如 2,5,1），未列出的指標將不會顯示。
   • 強制換行：在排序字串中加入 n 或 newline 代號（例如 1,2,n,3,4），即可將指標明確分行顯示。
4. 自動化配置部署：確認後，腳本會將狀態列渲染主程式部署至 ~/.gemini/antigravity-cli/hooks/，並自動完成設定檔寫入。狀態列支援熱更新，設定完成後立即於底部呈現，不需重新啟動 CLI。

背後運作機制：三層設定檔與安全信任清單

為確保狀態列設定在所有情境下皆能穩定生效，外掛會在背後自動維護三層設定檔與安全白名單：

1. 三層設定檔架構（Settings Hierarchy）：
   Antigravity CLI 依據層級由高至低依序套用設定，外掛會同步寫入三層設定檔，避免高優先級設定無聲覆蓋全域設定：

   • CLI 專屬設定檔（最高優先級）：~/.gemini/antigravity-cli/settings.json
   • 全域設定檔（中優先級）：~/.gemini/settings.json
   • 專案設定檔（特定專案優先級）：<workspace>/.gemini/settings.json

   寫入的 statusLine 物件結構範例：

   {
     "statusLine": {
       "enabled": true,
       "type": "command",
       "command": "node /Users/使用者名稱/.gemini/antigravity-cli/hooks/statusline-quota.mjs"
     },
     "ui": {
       "language": "zh-tw",
       "footer": {
         "items": [
           "model-name",
           "quota",
           "quota-reset-countdown",
           "context-used"
         ]
       }
     }
   }
   

   特別注意：command 欄位必須使用解析後的絕對路徑，不可使用環境變數（如 $HOME 或 %USERPROFILE%），因為背景掛鉤執行時不會經過 Shell 展開。

2. 安全白名單註冊（trusted_hooks.json）：
   Antigravity CLI 預設拒絕執行未列管的外部腳本。外掛會自動更新 ~/.gemini/trusted_hooks.json，在萬用字元鍵（"*"）、家目錄絕對路徑鍵以及當前工作區絕對路徑鍵中同步註冊信任字串：

   {
     "*": [
       "statusLine:node /Users/使用者名稱/.gemini/antigravity-cli/hooks/statusline-quota.mjs"
     ]
   }
   

   Windows 系統中會同時註冊雙反斜線與正斜線兩種路徑變體，確保安全性驗證順利通過。

支援指標總覽

外掛目前支援 26 種狀態指標，涵蓋五大維度：

1. AI 模型與代理

   • model-name：目前使用的 AI 模型名稱（例如 Gemini 3.5 Flash、Claude Sonnet 4.6）
   • agent-profile：目前使用的代理設定檔名稱
   • agent-state：代理目前的狀態（idle、thinking、working、tool_use、initializing）
   • mode：目前 CLI 運作模式（default、code-only、plan、interactive、accept-edits）

2. 額度與權杖

   • quota：五小時短期 API 可用額度剩餘百分比
   • quota-reset-countdown：五小時額度重置剩餘倒數時間（格式為 Xh Ym）
   • quota-weekly：每週 API 可用額度剩餘百分比
   • quota-weekly-countdown：每週額度重置剩餘倒數時間
   • context-used：目前對話已消耗的脈絡用量百分比
   • token-count：目前工作階段累積消耗的精確 Token 數量
   • artifacts：本次對話累計產出的檔案數量
   • plan-tier：目前的訂閱方案等級（例如 Pro、Ultra、Team）

3. 互動狀態

   • tool-confirmation：是否有等待使用者確認的工具執行對話方塊
   • pending-input：佇列中等待處理的使用者輸入訊息數量
   • background-tasks：背景正在執行的任務數量
   • subagents：目前活躍的子代理數量

4. 專案與版控

   • project-path：目前工作區專案的精簡目錄名稱
   • project-full-path：目前工作區專案的完整絕對路徑
   • vcs-type：版本控制系統類型（git、jj、fig）
   • git-branch：目前所在的 Git 分支名稱
   • vcs-dirty：工作區是否有尚未提交的修改（dirty 或 clean）

5. 系統與帳號

   • memory-usage：CLI 主行程所消耗的隨機存取記憶體用量（以 MB 為單位）
   • cli-version：Antigravity CLI 的版本號
   • conversation-id：目前對話識別碼前 8 碼（除錯使用）
   • sandbox-status：沙盒隔離模式狀態（off、on (net)、on (no-net)）
   • account-email：目前登入的帳號電子郵件地址

排序、自動折行與自訂換行機制

狀態列在終端機寬度受限時具備高度彈性：

1. 自動智慧折行：渲染腳本會在輸出前動態取得終端機目前的視窗欄寬（columns），逐一累加指標寬度（包含全形中文字與半形英數的寬度差異計算）。當下一個指標會超出當前行寬時，腳本會自動折行顯示，防止文字被終端機邊界硬性截斷。
2. 強制換行 Token：若希望將特定指標分組（例如第一行只顯示模型與額度，第二行顯示 Git 分支與專案路徑），可在設定順序時插入 n 識別碼：

   model-name,quota,quota-reset-countdown,n,git-branch,vcs-dirty,project-path
   

   此設定會精確在指定位置產生分行，滿足複雜資訊版面的排版需求。