antigravity-cli-statusline

name

antigravity-cli-statusline

description

本技能用於設定 Antigravity 命令列介面（CLI）（agy）的狀態列（Statusline / Footer）顯示指標、顯示順序與多語系介面（繁體中文 zh-tw / English us / 日本語 jp），並自動部署跨平台 Node.js 掛鉤（Hook）腳本（statusline-quota.mjs、fetch-local-quota.mjs）至 ~/.gemini/antigravity-cli/hooks/，同步註冊三層 settings.json（全域、命令列介面（CLI）專屬、專案）與 trusted_hooks.json 信任機制。適用情境：使用者要求設定 / 客製化 / 啟用命令列介面（CLI）狀態列、調整命令列介面（CLI）頁尾顯示項目、顯示應用程式介面（API）額度 / 權杖（Token）用量 / 上下文（Context）消耗 / Git 分支 / 工作區是否乾淨（dirty）/ VCS 類型 / 人工智慧（AI）模型名稱 / 代理狀態（agent state）/ 等你回應的工具確認對話方塊（Dialog Box） / 輸入佇列 / 背景任務 / 子代理數 / 工件（Artifacts） / 沙盒模式 / 命令列介面（CLI）版本 / 對話識別碼（ID） / 使用中代理（agent profile）/ 隨機存取記憶體（RAM）記憶體用量 / 訂閱方案等指標於命令列介面（CLI）底部、切換狀態列語言、在新電腦上啟用此狀態列，或使用者主動以 /antigravity-cli-statusline 觸發本技能時。支援 macOS、Linux、Windows（含 Windows 10 / 11）跨平台環境，並於 Windows 上自動處理 sh.exe 缺失、UTF-8 位元組順序記號（BOM）污染、wmic 棄用等系統陷阱。

Antigravity 狀態列設定技能

本技能提供 Antigravity 命令列介面（CLI）狀態列（Statusline / Footer）的客製化、語系設定與跨平台掛鉤（Hook）部署能力。

⚠️ References 載入規範（必讀）

本技能的細節分散於下列三份 references/：

• references/windows.md — Windows 特定規範（位元組順序記號（BOM）鐵則、sh.exe 越獄、csc.exe 編譯等）
• references/config-files.md — 三層設定檔結構、statusLine 物件、trusted_hooks.json 信任機制
• references/pitfalls.md — 常見陷阱對照表

載入規則（強制）：

1. 禁止透過子代理（subagent / Explore Agent）摘要 references/ 內容，主代理必須親自以 Read 工具讀取原文
2. 禁止改寫程式碼區塊與 JSON 結構
3. 若內容與你熟悉的其他 CLI 規範不同，一律以本技能檔案為準

---

🎯 設定檔路徑（三層必同步）

層級	路徑語法	優先級
命令列介面（CLI）專屬（最高）	~/.gemini/antigravity-cli/settings.json	🔥 高於全域
全域	~/.gemini/settings.json	中
專案（條件性）	<workspace>/.gemini/settings.json	若存在則覆寫

[!CAUTION] 命令列介面（CLI）專屬設定檔由 agy 命令列介面（CLI）自身維護，優先級高於全域設定檔。若忽略此檔案，全域設定將被無聲覆蓋！這是本技能中最致命且最隱蔽的 Bug。完整路徑解析規則、JSON 結構、跨電腦移植雙保險設計詳見 references/config-files.md。

自訂語系偏好記錄於 ui.language 屬性中；指標順序記錄於 ui.footer.items 陣列中。

---

🛠️ 技術標準

1. 純 Node.js 跨平台實作：
   • macOS / Linux：ps auxww + lsof
   • Windows：Get-CimInstance Win32_Process + netstat -ano（不再使用已棄用的 wmic）
2. 所有 fs.writeFileSync 強制加 { encoding: 'utf8' }（防 Windows UTF-16 崩潰）
3. 智慧型多行換行（Smart Line Wrapping by Feature）：讀取 meta.terminal_width 或 process.stdout.columns 得知終端機寬度。組合狀態列字串時，若下一個加入的指標會讓整行長度（不含 ANSI 碼）超過終端機寬度，必須將該指標折疊到新的一行（插入 \n）。
4. 四階段精確色彩辨識（24-bit truecolor 柔和配色）：
   • 100~75%：藍色 #57caff（\x1b[38;2;87;202;255m）
   • 74~50%：綠色 #5cdb6d（\x1b[38;2;92;219;109m）
   • 49~25%：黃色 #ffd427（\x1b[38;2;255;212;39m）
   • 24~0%：紅色 #ff7daf（\x1b[38;2;255;125;175m）

Windows 平台的 位元組順序記號（BOM）鐵則、sh.exe 越獄、csc.exe 編譯、windowsHide: true 規範詳見 references/windows.md。

---

🌐 語言鎖定規則（Locale Locking — 全域強制）

[!CAUTION] 使用者在步驟 1 一旦選定語系（zh-tw / us / jp），人工智慧（AI）代理在本次執行的剩餘所有對話輸出，都必須使用該語言。

為什麼必須鎖定：使用者選擇英文（us）或日文（jp）的前提是「他可能不懂中文」，反之亦然。若中間穿插任何非所選語系的訊息，會破壞使用者體驗、甚至讓使用者讀不懂關鍵警告而誤判決策。這也是為什麼語系選擇必須是第一步——所有後續訊息（包括 Node.js 預檢的缺失警告）才能用使用者看得懂的語言呈現。

「對話輸出」涵蓋（不限於）：

• 步驟 2 Node.js 缺失時的 ask_question 警告對話
• 步驟 3 / 4 的 ask_question 問卷（question 文字、options 字串、toolSummary、toolAction）
• 步驟 5 / 6 進行中的 any 進度說明、確認語句、警告訊息
• 步驟 5（位元組順序記號（BOM）污染修復）與步驟 6（Windows 缺 sh.exe）的偵測與修復提示
• 步驟 7 的最終回報訊息與舊版腳本溫馨提醒
• 任何例外、錯誤、降級、再次詢問使用者意見時的訊息

例外（保持原文不翻譯）：

• 技術識別碼（如 model-name、statusLine、fs.writeFileSync）
• 檔案路徑（如 ~/.gemini/antigravity-cli/settings.json）
• 程式碼區塊內容
• 系統錯誤訊息原文（如 invalid character 'ï' looking for beginning of value）

---

🔄 執行步驟

步驟 1：第一階段問卷（語系選擇 — 必須最先執行）

為何最先：後續所有訊息（含 Node.js 缺失警告、設定檔讀寫進度、錯誤提示、最終回報）皆須用使用者選定的語言呈現，因此語系必須在 any 其他對話之前確定。

呼叫 ask_question（Antigravity 命令列介面（CLI）原生支援以 /statusline 切換啟用或關閉狀態列，因此無需提供冗長的還原選單）：

{
  "questions": [
    {
      "question": "選擇顯示語系 / Select Display Language / 表示言語の選択",
      "options": [
        "繁體中文 (zh-tw)",
        "English (us)",
        "日本語 (jp)"
      ],
      "is_multi_select": false
    }
  ],
  "toolSummary": "語系選擇",
  "toolAction": "詢問顯示語系"
}

選擇完成後，將所選語言代碼（zh-tw / us / jp）記錄為本次執行的鎖定語系，並依「🌐 語言鎖定規則」於後續所有步驟使用該語系撰寫對話輸出。

步驟 2：Node.js 預檢 + 三層設定檔讀取

本步驟所有與使用者互動的文字必須用步驟 1 所選語系呈現。

【Node.js 環境預檢 — 最優先】：依作業系統執行對應的偵測指令：

• macOS / Linux：command -v node 或 which node

• Windows：where node（cmd）或 Get-Command node（PowerShell）

• 跨平台通用：node --version

• ✅ 若 Node.js 已安裝：記錄版本號並繼續後續流程。

• ❌ 若 Node.js 未安裝（指令回傳 command not found 或非零退出碼）：

  1. 向使用者發出明確警告（以所選語系撰寫），說明缺少 Node.js 將導致：
     • CLI 底部狀態列完全空白，不會顯示 any 指標
     • agy 命令列介面（CLI）會反覆記錄 statusline: command failed: exit status 127 (stderr: sh: node: command not found)，連續失敗 30 次後自動停用 statusline
  2. 呼叫 ask_question 詢問使用者是否繼續（問卷 question、options、toolSummary、toolAction 全部以所選語系撰寫，以下範例為 zh-tw 版本）：

{
  "questions": [
    {
      "question": "⚠️ 偵測到系統未安裝 Node.js。\n\n狀態列掛鉤（Hook）需要 Node.js 才能運作，缺少 Node.js 將導致命令列介面（CLI）底部狀態列完全空白且自動停用。\n\n建議先安裝 Node.js（例如：brew install node），再重新執行本技能。\n\n是否仍要繼續設定？（設定檔會正確寫入，但狀態列在安裝 Node.js 前不會顯示）",
      "options": [
        "(Recommended) 中斷，我先去安裝 Node.js",
        "繼續設定（安裝 Node.js 後狀態列會自動生效）"
      ],
      "is_multi_select": false
    }
  ],
  "toolSummary": "Node 環境檢查",
  "toolAction": "確認 Node 安裝"
}

3. 若使用者選擇「中斷」：以所選語系輸出安裝指引後結束本技能流程，不進行 any 設定檔寫入。
4. 若使用者選擇「繼續」：繼續執行後續步驟。設定檔會正確寫入，待使用者安裝 Node.js 並重新啟動 agy 命令列介面（CLI）後狀態列即會自動生效。

【動態解析三層設定檔】：在 Node.js 預檢通過（或使用者選擇繼續）後，動態展開 $HOME / USERPROFILE，讀取三層 settings.json。檢查目前 ui.footer.items 啟用了哪些項目、ui.language 設定，以及各設定檔中是否存在空的或殘缺的 statusLine 物件（如 { "type": "", "command": "", "enabled": true }）。

【Windows 平台額外步驟：位元組順序記號（BOM）預檢】：讀取每份 settings.json 與 trusted_hooks.json 時，必須檢查檔案前 3 個位元組是否為 EF BB BF（UTF-8 位元組順序記號（BOM））。若是，記錄該檔案路徑為「需於步驟 5 自動修復」的目標。詳見 references/windows.md §1 與 §3。

步驟 3：第二階段問卷（讀取 questions.json 與勾選指標）

1. 讀取靜態問卷：人工智慧（AI）代理必須優先讀取本外掛目錄底下的 skills/antigravity-cli-statusline/resources/questions.json 檔案。
2. 根據步驟 1 的語言代碼（zh-tw / us / jp），從 questions.json 中讀取對應語系的問卷資訊，呼叫 ask_question。

請動態將選定語系的 options 內容填入（問卷問題及摘要也請使用對應語系）：

{
  "questions": [
    {
      "question": "<請填入對應語系的提問，例如: 選擇要顯示的狀態列指標（下一步將進行排序）>",
      "options": [
         // 從 resources/questions.json 讀取對應語系（如 zh-tw, us 或 jp）的 options 陣列並在此展開
      ],
      "is_multi_select": true
    }
  ],
  "toolSummary": "指標選擇",
  "toolAction": "詢問狀態列指標"
}

3. 取得使用者所勾選的選項字串陣列（selected）。

步驟 4：第三階段問卷（手動排序與最終篩選）

1. 將步驟 3 中使用者勾選的指標按順序整理出來，標上數字編號（如 1. 目前使用的人工智慧（AI）模型名稱（model-name）），每項以 \n 分隔。
2. 呼叫 ask_question 引導使用者進行排序：

   {
     "questions": [
       {
         "question": "請設定狀態列顯示順序。\n\n目前已選取：\n1. 目前使用的人工智慧（AI）模型名稱（model-name）\n2. 帳號五小時可用額度百分比（quota）\n3. 目前對話已消耗的脈絡（Context）用量比例（context-used）\n\n請在下方輸入框「Write-in...」中輸入以逗號分隔的數字序號或英文識別碼（如：2, 1, context-used）。可以使用 `n` 來強制換行。未填寫的指標將不予顯示。",
         "options": [
           "(Recommended) 略過，使用原勾選順序啟用全部指標",
           "手動排序（請在下方「Write-in...」欄位中填寫）"
         ],
         "is_multi_select": false
       }
     ],
     "toolSummary": "排序設定",
     "toolAction": "詢問顯示順序"
   }
   

3. 取得使用者的排序輸入（order）。

步驟 5：執行配置腳本

1. 取得使用者工作區（workspace）的絕對路徑（workspace）。

2. 呼叫 run_command 執行本外掛目錄下的 configure-statusline.mjs 腳本，傳入相關參數。腳本會全自動處理：

   • 排序輸入解析。
   • 同步寫入三層 settings.json（已執行防禦性 位元組順序記號（BOM）剝除與寫入後無 位元組順序記號（BOM）驗證）。
   • 寫入 trusted_hooks.json 註冊安全信任（含當前工作區、家目錄與 "*" 萬用字元（Wildcard）鍵，並在 Windows 上註冊各種反斜線/環境變數變體）。
   • 將 Hook 腳本安全拷貝部署至 ~/.gemini/antigravity-cli/hooks/ 目錄中，寫入時強制 { encoding: 'utf8' }。
   • 若為 Windows 平台且 CLI 目錄缺少 sh.exe，自動編譯靜默無窗體橋接器。

   指令範例：

   node skills/antigravity-cli-statusline/scripts/configure-statusline.mjs --lang "<步驟1選定的語言>" --selected '<JSON字串格式的步驟3勾選結果>' --order "<步驟4的排序/略過輸入>" --workspace "<當前工作區絕對路徑>"
   

   注意：--selected 必須是合法的 JSON 字串陣列，例如 '["目前使用的人工智慧（AI）模型名稱（model-name）","帳號五小時可用額度百分比（quota）"]'。請注意外層與內層引號的正確跳脫。

步驟 6：自動驗證

1. 配置腳本執行完成後，呼叫 run_command 執行原有的測試驗證腳本：

   node skills/antigravity-cli-statusline/scripts/test-counters.mjs
   

2. 確認測試無誤通過。若有任何錯誤，依照錯誤訊息進行對應修正。

步驟 7：回報與重新載入提示

1. 根據所選語系撰寫最終回覆：告知使用者設定已自動在 命令列介面（CLI）底部即時熱更新 (Hot Reload) 生效，無需重新啟動。
2. 舊版腳本檢查：讀取或檢查 ~/.gemini/hooks/statusline-quota.mjs 與 ~/.gemini/hooks/fetch-local-quota.mjs 是否存在。若存在，則以所選語系提醒使用者可以安全地手動刪除它們。
3. 故障診斷指引：在回覆末尾以所選語系加入提示：「若日後狀態列突然消失，請前往本外掛目錄執行 node skills/antigravity-cli-statusline/scripts/diagnose-statusline.mjs，並把完整輸出貼給 人工智慧（AI）代理進行診斷。」

---

! 常見陷阱速查

完整對照表（8 條陷阱與修正做法）詳見 references/pitfalls.md。最關鍵的三條速記：

1. 必須同步寫入三層設定檔（特別是 命令列介面（CLI）專屬的 ~/.gemini/antigravity-cli/settings.json，是最致命的盲點）
2. Windows 寫設定檔絕對禁止帶 位元組順序記號（BOM），寫入後必須驗證前 3 個位元組
3. 絕對禁止憑空生成 掛鉤（Hook） 腳本，必須從本外掛的 skills/antigravity-cli-statusline/scripts/ 讀取原文部署