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 目录下的测试脚本。