dsh-antigravity-usage：反重力額度與用量監控

前言¶

DeepSeek Harness (DSH) 插件 dsh-antigravity-usage 用於監控 Antigravity（反重力）的額度消耗與使用情況。該插件由 kirigayakazima 維護，解決了一個常見痛點：反重力在本地語言服務器中運行，但 Token 消耗數據並不落盤，僅存儲會話元數據。

本插件設計了雙數據源架構：實時額度通過調用本地語言服務器 API 獲取，而離線會話用量則通過只讀掃描本地 SQLite 數據庫計算。這意味着即使反重力未運行，也能查看歷史用量。

核心功能¶

插件在 DSH 側邊欄註冊了一個「🛰️ 反重力額度」入口，點擊後在主區域打開專屬面板。面板包含以下六個標籤頁：

額度：顯示各分組/模型剩餘額度百分比、進度條、重置倒計時、credits 和賬號套餐。
趨勢：剩餘額度隨時間變化的折線圖（支持 24h / 7d / 30d / 全部）。
熱力圖：近 182 天的日曆熱力圖，指標可切換爲會話數、步數或額度消耗。
彙總：逐月及逐日的額度消耗、重置次數、會話數等統計表。
重置：顯示各額度桶的累計消耗、恢復與重置事件。
會話：本地會話清單（標題、工作區、模型、步數、生成次數），支持按工作區篩選和搜索。

數據獲取機制¶

插件將數據來源分爲兩類，互爲補充。

1. 實時額度（需要反重力運行）¶

實時額度從本地語言服務器的 HTTP 接口獲取。插件會通過日誌解析反重力啓動的隨機端口，並使用 CSRF Token 進行認證。主要接口包括：
* POST /exa.language_server_pb.LanguageServerService/GetUserStatus
* POST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary

2. 離線用量（無需反重力運行）¶

離線用量從本地會話庫的 SQLite 文件中讀取。文件路徑通常位於 ~/.gemini/antigravity/conversations/ 或 conversation_summaries.db。

插件使用 Node 內置的 node:sqlite 以只讀模式打開數據庫。Token 消耗與緩存命中率並非直接存儲，而是通過解析 gen_metadata 中的 Protobuf 數據，並與語言服務器的 GetCascadeTrajectory 返回的 modelUsage 進行字段映射計算得出。

關鍵的字段映射關係如下：

Protobuf 路徑	含義
`1.4.2`	`inputTokens` 輸入 token
`1.4.3`	`outputTokens` 輸出 token
`1.4.5`	`cacheReadTokens` 緩存命中讀取
`1.4.9`	`thinkingOutputTokens` 思考 token
`1.4.10`	`responseOutputTokens` 回覆 token

API 接口¶

插件宿主端提供了一組 HTTP 接口，可直接用於檢測狀態或獲取數據：

GET /api/antigravity-usage：獲取 { status, snapshot, lastKnown }。
GET /api/antigravity-usage/history?range=24h\|7d\|30d\|all：獲取額度時間序列。
GET /api/antigravity-usage/usage：獲取逐日/逐月彙總與重置事件。
GET /api/antigravity-usage/conversations?full=1：獲取離線會話用量。
POST /api/antigravity-usage/refresh：立即採集數據。
POST /api/antigravity-usage/diag：客戶端自診斷接口。

這些接口無需鑑權（頁面 / 除外）。可以通過 curl http://127.0.0.1:<port>/api/antigravity-usage 進行自檢。

配置與環境變量¶

插件支持通過環境變量進行配置，修改後需重啓 DSH 生效：

ANTIGRAVITY_USAGE_INTERVAL_MS：實時額度採樣間隔，默認 120000ms。
ANTIGRAVITY_USAGE_DATA_DIR：數據目錄，默認 $DSH_HOME/antigravity-usage。
ANTIGRAVITY_USAGE_RETAIN_DAYS：歷史保留天數，默認 180。
ANTIGRAVITY_USAGE_MAX_POINTS：歷史接口返回的最大采樣點數，默認 400。
ANTIGRAVITY_USAGE_PORT：語言服務器端口，默認 0（自動發現）。
ANTIGRAVITY_USAGE_TIMEOUT_MS：HTTP 請求超時時間，默認 8000ms。

開發與熱更新¶

客戶端代碼：位於 lib/client.js，無構建步驟。修改後支持 HMR（熱更新），DSH 每 500ms 輪詢檢測變更，頁面自動刷新，無需重啓。
宿主代碼：位於 lib/*.js（非 client），修改後必須重啓 DSH。
側邊欄註冊：必須使用 sidebar.panellist 和 main 槽位。不推薦註冊在 sidebar.footer.action，因爲該區域是橫向 Flex 行，插件會被擠出屏幕。

適用場景與注意¶

該插件適合需要在 DSH 環境中持續監控 Antigravity 額度及歷史消耗的開發者。由於插件以當前 DSH 進程權限運行，使用前應檢查源碼與許可證。

離線可用：即使反重力服務未啓動，也能通過掃描本地會話庫查看歷史用量。
只讀安全：所有 SQLite 讀寫均爲只讀模式，不會修改反重力目錄。
緩存版本：掃描緩存必須帶結構版本號（CACHE_VERSION），否則升級後 Token 數據可能顯示爲 0。

插件目錄結構包含 lib/index.js（宿主端）、lib/client.js（客戶端）以及 scripts 目錄下的測試腳本。