反重力额度 / 用量 · dsh-antigravity-usage
DSH 插件：把反重力（Antigravity）的额度与用量做成侧边栏竖排的一行「🛰️ 反重力额度」，
点开在右侧主区域打开一个六标签专属整页。
已安装进 ~/.dsh/profiles/desktop（当前 DSH 桌面端使用的 profile）。
一、设计要点：两个互相独立的数据源
这是本插件最重要的一条设计约束：实时额度不可用时，面板必须照样能用。
| 来源 | 需要反重力在运行吗 | 给什么 |
|---|
| A. 实时额度 | 反重力本地语言服务器的 HTTP 接口 | ✅ 需要 | 各额度桶 / 各模型的剩余额度百分比、重置倒计时、credits |
| B. 离线用量 | 反重力落在磁盘上的 SQLite（只读） | ❌ 不需要 | 会话数、步数、生成次数、用过的模型、工作区、时间 |
A 失败时：额度页显示一行「反重力当前没有运行」，并灰显最后一次成功采到的额度；
趋势 / 热力图 / 汇总 / 重置 / 会话五个标签完全不受影响。
A 是怎么拿到额度的（以及为什么只能拿到百分比）
反重力的 token 消耗不落盘 —— ~/.gemini/antigravity/conversations/*.db 里只有步数、模型 ID
和会话内容，没有任何 token 计数。真正的额度由它本地语言服务器通过 HTTP 暴露：
1. GET http://127.0.0.1:<port>/ → 页面里含 window.__APP_CONFIG__.csrfToken
2. POST http://127.0.0.1:<port>/exa.language_server_pb.LanguageServerService/GetUserStatus
3. POST http://127.0.0.1:<port>/exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary
Header: x-codeium-csrf-token: <token> ← 缺了就是 401
官方对这份额度的原话："Quota is consumed proportionally to the cost of the tokens."
所以消耗 ∝ token 成本，插件用相邻采样的差值反推消耗；但要精确 token 数，接口并不提供。
端口随机分配，写在启动日志里，插件按「最新日志优先」解析：
| 形态 | 日志位置 |
|---|
CLI（agy） | ~/.gemini/antigravity/log/cli-<ts>.log |
| IDE | %APPDATA%\Antigravity\logs\language_server.log |
B 是怎么读的
~/.gemini/antigravity/conversation_summaries.db → 会话清单（标题/步数/工作区/时间）
~/.gemini/antigravity/conversations/<id>.db → gen_metadata：模型 + 生成次数
~/.gemini/antigravity-cli/... → 同上（CLI 那一套）
~/.gemini/antigravity-ide/... → 同上（若存在）
用 Node 内置的 node:sqlite（DSH 宿主自己也在用它）以 readOnly 打开；
万一只读打开失败（库需要恢复等），退化成「复制到临时目录读副本」，绝不写反重力任何目录。
按 mtime+size 缓存，28 个会话约 130ms。
token 与缓存命中：本地其实一直有，只是 protobuf 没字段名
gen_metadata 的 blob 是 protobuf，不带字段名，所以之前只看关键词是找不到 token 的。
字段号是拿 语言服务器 GetCascadeTrajectory 返回的 modelUsage 逐项核对出来的
（同一会话、同一步，五项全等）：
gen_metadata 里的路径 | 含义 |
|---|
1.4.2 | inputTokens 输入 token |
1.4.3 | outputTokens 输出 token |
1.4.5 | cacheReadTokens 缓存命中读取 |
1.4.9 | thinkingOutputTokens 思考 token |
1.4.10 | responseOutputTokens 回复 token |
1.9.10.1 | estimatedTokensUsed 估算上下文 |
1.9.10.4 | maxContextTokens（256000） |
核对样例：本地 1.4.2=2693 / 1.4.3=110 / 1.4.9=15 / 1.4.10=95 / 1.4.5=16264
↔ 轨迹里同一步 inputTokens=2693 / outputTokens=110 / thinkingOutputTokens=15 / responseOutputTokens=95 / cacheReadTokens=16264。
所以 token 和缓存命中全部可以离线算出来，不需要反重力在运行 —— 这正是本插件「不依赖运行时」的关键。
实测本机：输入 23,648,148 / 输出 1,585,016（思考 575,452 + 回复 1,009,564）/
缓存命中读取 205,816,674 / 缓存命中率 89.7%。
想要一份「带字段名的权威对照」时，可以临时跑
node scripts/probe-usage-schema.mjs（它会调一次 GetCascadeTrajectory，只读）。
⚠️ 扫描缓存必须带结构版本号（CACHE_VERSION）：缓存条目按 mtime+size 命中，但如果新版本
往条目里加了字段（比如这次的 token），旧缓存会让新字段一律读到 undefined —— 表现就是
升级后 token 全变 0（实际踩过）。所以任何改动缓存结构的提交都必须 CACHE_VERSION += 1；
test-conversations.mjs 里有一条回归：把缓存条目里的 v 抹掉再扫，断言 token 仍然正确。
二、面板内容（六个标签）
| 标签 | 内容 | 可用性 |
|---|
| 额度 | 各分组 / 各模型剩余额度、进度条、重置倒计时、credits、账号套餐 | 需反重力运行（否则灰显上次快照） |
| 趋势 | 剩余额度随时间变化（手写 SVG 折线，24h / 7d / 30d / 全部） | ✅ 离线可用 |
| 热力图 | 近 182 天日历热力图，指标可切：会话数 / 步数 / 额度消耗 | ✅ 离线可用 |
| 汇总 | 逐月 + 逐日表：额度消耗、重置次数、会话数、步数、生成次数 | ✅ 离线可用 |
| 重置 | 各额度桶累计消耗/恢复/重置 + 重置事件列表 | ✅ 离线可用 |
| 会话 | 本地会话表（标题/工作区/模型/步数/生成/最后活动），可按工作区筛选、搜索 | ✅ 离线可用 |
三、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 | 客户端自报（诊断） |
这些路由不需要鉴权（只有页面 / 是 401），可以直接
curl http://127.0.0.1:19387/api/antigravity-usage 自检；
status.clientDiag 里能看到客户端半边有没有跑起来、有没有渲染崩溃 —— 排查客户端问题时不用猜。
四、历史是怎么算的
官方接口只给「当前剩余额度」这一个瞬时值，所以插件自己按间隔采样，把每次读数追加成 JSONL：
$DSH_HOME/antigravity-usage/history.jsonl
{"t":1760000000000,"p":2810,"c":{"pa":500,"pm":50000,"fa":100,"fm":150000},
"b":{"gemini-weekly":0.8357,"gemini-5h":1,"3p-weekly":1,"3p-5h":1}}
remainingFraction 下降 → 记入消耗- 上升 → 窗口滚动恢复或周期重置，记入恢复，不计消耗
- 上升 ≥ 5% 且间隔 < 12h 才算一次「重置」
- 间隔 < 2s 的重复采样就地合并
last-known.json 单独持久化最后一次成功快照，重启 DSH 后仍能灰显「上次已知额度」。
五、配置（环境变量，改完重启 DSH）
| 变量 | 默认 | 说明 |
|---|
ANTIGRAVITY_USAGE_INTERVAL_MS | 120000 | 实时额度采样间隔 |
ANTIGRAVITY_USAGE_DATA_DIR | $DSH_HOME/antigravity-usage | 数据目录 |
ANTIGRAVITY_USAGE_RETAIN_DAYS | 180 | 历史保留天数 |
ANTIGRAVITY_USAGE_MAX_POINTS | 400 | 历史接口一次最多返回的采样点数 |
ANTIGRAVITY_USAGE_PORT | 0（自动发现） | 手动指定语言服务器端口 |
ANTIGRAVITY_USAGE_DEEP_SCAN | false | 日志发现失败时是否全端口扫描兜底 |
ANTIGRAVITY_USAGE_TIMEOUT_MS | 8000 | 单次 HTTP 超时 |
离线会话扫描固定每 10 分钟一次，按会话库 mtime 增量。
六、目录结构
antigravity-usage/
├── package.json # dsh.bundle + dsh.client 清单、meta/icon
├── cordis.patch.yml # 插件行注册（id: antigravity-usage）
├── icon.svg
├── locale/{en,zh}.json
├── lib/
│ ├── index.js # 宿主半边：六条路由 + 两个定时器 + lastKnown + 客户端自报通道
│ ├── collector.js # A：端口发现 + csrf 握手 + 本地 API 采集
│ ├── history.js # 采样落盘、消耗反推、逐日/逐月、重置事件、lastKnown
│ ├── conversations.js # B：离线只读扫 SQLite（node:sqlite）+ token/缓存解码
│ └── client.js # 客户端 bundle：侧边栏 glyph（sidebar.panellist）+ 专属整页（main）
├── scripts/ # 开发/测试脚本，不随插件发布
│ ├── probe.mjs # 裸探针：直接打反重力本地 API
│ ├── probe-trajectory.mjs # 问语言服务器要轨迹（modelUsage 的权威来源）
│ ├── probe-usage-schema.mjs # 取 modelUsage 完整字段表 + 缓存字段
│ ├── smoke.mjs # 宿主半边六条路由冒烟（mock ctx）
│ ├── test-history.mjs # 历史算法 + 逐日/逐月 + lastKnown
│ ├── test-conversations.mjs # 离线会话扫描 + token 解码 + 缓存版本回归
│ ├── test-client.mjs # 客户端模块形状 + slot 注册回归
│ ├── test-render.mjs # 用真 React 渲染 glyph / 整页 / 六标签 + 样式防回归
│ └── dev/ # 排查 DSH 自身用的工具（asar / HMR / 槽位目录）
│ ├── asar.mjs / asarsearch.cjs / asargrep.cjs # 读 app.asar 内部
│ ├── hmr-graph.mjs / fetch-bundle.mjs # 读客户端插件 graph 与 bundle
│ ├── list-sidebar-slots.cjs / sidebar-css.cjs # 槽位目录与布局 CSS
│ └── probe-tokens.mjs / probe-token-*.mjs # 找 token 字段的排查脚本
七、开发
cd D:\CodePackage\DSPlug\antigravity-usage
npm run check # node --check 五个源文件
node scripts/test-history.mjs # 历史算法
node scripts/test-conversations.mjs # 离线扫描
node scripts/test-client.mjs # 客户端形状 + 注册
node scripts/test-render.mjs # 真 React 渲染
node scripts/smoke.mjs --temp # 宿主半边冒烟
生效方式
| 改动 | 生效方式 |
|---|
lib/client.js | 不用重启也不用刷新 —— DSH 的 @deepseek-ai/dsh-client-hmr 每 500ms stat 轮询客户端 bundle（mtime/ctime/size），变化即推 SSE /plugins/events，页面 entries.reload(id, rev) 重跑 apply |
lib/*.js 其它（宿主半边） | 必须重启 DSH |
因为本插件没有构建步骤、lib/client.js 就是最终产物，那个轮询直接看得到源码改动。
八、踩坑记录
shell.overlay 不是弹窗容器，是「frame-wide floating layer」，条目内联铺开、且整层 click-through。
所以注册进去的组件必须：关闭时返回 null（否则常驻占位、把页面撑坏），打开时自己画 position:fixed
遮罩，并给需要点击的元素加 pointer-events:auto。判定「关闭返回 null」的那一层要留在注册的组件本身
里，别包在箭头函数里，否则既容易写错也没法单独调用验证（test-render.mjs 有回归断言）。- 不要往
sidebar.footer.action 里挤：它是不换行的横向 flex 行（width:100%、无 wrap）。
实测它已经有 4 个条目（DSH 自带的 cordis-panel、usage-vendor-stats-entry(10)、
gemini-web2api-monitor-entry(11)、以及本插件）。排最后的那个会被挤出侧边栏、被主面板盖住 ——
DOM 里在、getBoundingClientRect() 也正常，但肉眼看就是没有。 本插件一度栽在这里。
正解是换到 DSH 原生的竖排槽位，见下条。
- 侧边栏竖排一行 =
sidebar.panellist（list，用 id）+ main（keyed，用 key）：
"Global panel icons"，DSH 侧边栏的 PanelRow 自己画按钮和文字、自己处理点击
（selectPanel(id)），插件只提供那个 glyph 组件，拿到 {size, active}。
点这一行会切到 main 里 key 与 id 相同的那个面板 —— 两者必须一致，否则点了没反应。
另外 label 是每次投影都重读的 thunk，所以可以把实时百分比写进那一行的文字里。
- 客户端半边改完不用重启：
@deepseek-ai/dsh-client-hmr 每 500ms stat 轮询客户端 bundle
（mtime/ctime/size），变化即推 SSE /plugins/events，页面 entries.reload(id, rev) 会重新执行
apply（实测确认）。只有宿主半边改动才需要重启 DSH。
- 排查客户端问题的正确姿势：
POST /api/antigravity-usage/diag + GET /api/antigravity-usage
读 status.clientDiag。客户端在 apply / 注册 / 渲染 / 渲染崩溃时自报；组件还会在挂载后用
getBoundingClientRect() 把自己的真实几何量出来上报 —— 「注册了但看不见」就是这么定位的，
不用靠猜、也不用麻烦用户截图。
for HTTPS (gRPC) 也含 for HTTP：解析端口必须用 for HTTP(?!S)。- 不要直接访问未 inject 的服务属性（
ctx.timer）：未声明会被 cordis 拒绝并抛错；
ctx.get('timer') 是安全查找。
- Windows PowerShell 5.1 按 GBK 读 UTF-8：
ConvertFrom-Json 校验含中文的 package.json 会误报，要用 Node。
九、验证状态
| 项 | 状态 |
|---|
| A 路：端口发现 + csrf + 真实额度采集 | ✅ 反重力在运行时实测通过（真实账号/套餐/4 桶/14 模型） |
| B 路：离线会话扫描 | ✅ 实测 28 会话 / 3894 步 / 1867 次生成 / 9 个模型，180ms |
| 历史：消耗反推 / 逐日逐月 / 重置事件 / lastKnown | ✅ 合成数据全项断言通过 |
| 宿主六条路由 | ✅ mock ctx 冒烟通过 |
| 客户端模块形状 + slot 注册 | ✅ 26 项断言通过（含 main.key 必须等于 panellist.id） |
| 用真 React 渲染 glyph / 整页 / 六标签 | ✅ 无异常 |
| 清单 / 图标 / locale + loader 按包名解析 | ✅ 通过 |
| 侧边栏那一行真的画出来且可见 | ✅ 在应用内量到：{found:true, label:"反重力额度", x:14, y:184, w:252, h:36, visible} |
| HMR 反复 apply 不产生重复注册 / 残留 | ✅ myEntries:1、rowsInDom:1；旧 sidebar.footer.action 与 shell.overlay 条目已回收 |
| 整页的视觉细节 | ⏳ 待人工确认（用户已确认侧边栏行位置可用） |
未做视觉验证的原因：DSH Web GUI 的页面路由需要带 token 的 URL（裸请求 401），也没有另起浏览器去凑截图。
客户端是否跑起来、注册进了哪个槽位、组件有没有渲染崩溃、那一行的真实几何，全部由
POST /api/antigravity-usage/diag + GET /api/antigravity-usage 的 status.clientDiag 自报
（见第三节）—— 排「注册了但看不见」这类问题时不用猜、也不用麻烦用户截图。
