余额用量监控 alanzhao0128/dsh-balance-monitor

dsh-balance-monitor

DeepSeek 余额与花费窗口，直接显示在 dsh 侧边栏底部。

一个极简的 DeepSeek Harness (dsh) 插件：在侧边栏底部（设置上方）显示当前会话渠道的余额/用量。DeepSeek 官方渠道显示余额与今日/7日/30日花费窗口（支持官方用量数据）；火山方舟渠道显示 Agent Plan 套餐额度（5小时/周/月进度条）；Command Code 渠道显示 5h/周/月 用量窗口（GOAT/Pro/Max 等套餐）；Google AI Pro 渠道（Antigravity 经 CLIProxyAPI 反代）显示 5 小时/周剩余额度（Gemini 与 Claude/GPT 两个模型组）。样式完全使用官方设计令牌，克制内敛。

功能

| 功能 | 实现 |
| 实时余额 | 服务端调用 GET https://api.deepseek.com/user/balance，使用 $DSH_HOME/.credentials.yaml 中的 DEEPSEEK_API_KEY（环境变量优先） |
| 今日/7日/30日花费（官方） | 配置 DEEPSEEK_PLATFORM_TOKEN 后，服务端调用官方用量接口 platform.deepseek.com/api/v0/usage/cost（与平台用量页同一份数据），按日期窗口累加。7日 = 今天往前 6 天，30日 = 今天往前 29 天（均含今天）。不受「在其他环境使用 API」影响 |
| 余额差值回退 | 无平台 token 或官方接口失败时，今日花费回退为余额差值账本（只累计余额下降，充值不冲账）；7日/30日显示 — |
| 渠道感知 | 卡片跟随当前会话的模型渠道（provider）自动显隐：DeepSeek 官方显示余额/花费；火山方舟显示 Agent Plan 进度条；Command Code 显示用量窗口；Google AI Pro（cliproxy）显示 5h/周 剩余额度；其他渠道显示「暂不支持」占位；无会话不显示 |
| 火山方舟 Agent Plan | 配置 AK/SK 后，调用 GetAFPUsage 控制面 API（SigV4 签名），显示 5小时/周/月 三档套餐额度进度条，颜色随用量变化（绿→黄→红） |
| Command Code 用量 | 配置 COMMANDCODE_API_KEY 后，调用 api.commandcode.ai/alpha/billing/credits 等接口，显示 5h/周/月 三窗口已用百分比与重置倒计时 |
| Google AI Pro 额度 | 配置 CPA 管理地址 + Basic 认证 + 管理密钥后，读取 CPA 上 antigravity-priority 插件探测的配额快照，按 Gemini / Claude+GPT 两个模型组显示 5h 与每周剩余百分比、重置倒计时（CPA 刚重启导致快照为空时自动触发一次探测）。服务端需自行搭建，见搭建指南 |
| Claude Pro 官方额度 | 配置 CPA 管理地址后，读取 CPA 上定时任务探测的官方 OAuth 用量快照（/v0/claude/quota），按 5h 会话与 7 日周度窗口显示已用百分比、官方重置时间倒计时 |
| 位置 | 注册在官方 sidebar.footer.action 槽位 —— 设置上方，零 hack |
| 折叠态 | 收起后变为 36px 圆形，显示紧凑余额 + tooltip |
| 健壮性 | 60s 轮询 + 切回标签页时刷新；上游失败时保留上次数据（变淡标记 stale），不闪错误 |

安装

浏览器端 bundle 是手写的 classic script，无构建步骤，git 安装无需 prepare 脚本：

dsh plugin --profile web add "github:alanzhao0128/dsh-balance-monitor#main"

或从 npm：

dsh plugin --profile web add @alanzhao/dsh-balance-monitor

然后重启 Web UI（dsh --profile web）。卡片出现在展开的侧边栏底部、设置按钮上方。

版本要求：0.8.2+ 兼容 dsh ≥ 0.1.2-rc.1（完美兼容 DSH Desktop 0.2.1-rc.2 及更高版本，声明 engines.dsh 一等公民标准，全面支持 SettingsForms 与双轨设置）；dsh 0.1.2-rc.1 宿主请固定安装 0.7.1。

配置

设置面板（推荐）

打开 dsh 设置（齿轮）→ 余额监控 / Balance Monitor，可编辑卡片行为参数，保存后写入 ~/.dsh/settings.yaml 的 dsh-balance-monitor: 段，即时生效（个别参数重启后生效）：

| 分组 | 字段 | 默认 | 说明 |
| 显示 | ui.showCard | true | 关闭后不显示任何渠道卡片 |
| 显示 | ui.warnThreshold | 30 | 用量 ≥ 该百分比进度条变黄 |
| 显示 | ui.dangerThreshold | 70 | 用量 ≥ 该百分比进度条变红 |
| 刷新 | ui.pollMs | 60 秒 | 卡片刷新间隔（面板以秒显示，内部存毫秒） |
| 网络 | network.cacheMs | 40 秒 | 服务端配额缓存，建议保持低于卡片刷新间隔 |
| 网络 | network.timeoutMs | 20 秒 | 上游超时（火山方舟 / Command Code / DeepSeek 官方用量 / CPA 管理接口） |
| 网络 | network.cpaBaseUrl | 留空 | 你自己的 CLIProxyAPI 管理地址（Google AI Pro 渠道的配额来源）；留空则该渠道显示「未配置 CPA 地址」，见下文搭建指南 |
| 网络 | network.cpaStaleMs | 1200 秒 | CPA 快照超过该时长即视为过期，插件自动补一次探测（建议大于 CPA 侧的定时探测周期） |
| 凭证 | credentials.file | .credentials.yaml | 凭证文档文件名（相对 $DSH_HOME） |

渠道凭证

设置面板的 「渠道凭证」分组 显示每个渠道展示余额/用量需要的凭证及其配置状态，按是否已被 DSH 模型配置引用区分只读/可写：

| 渠道 | 凭证 | 交互 |
| DeepSeek 官方 | DEEPSEEK_API_KEY | 只读（DSH 模型配置已引用），显示 ✅/⚠️ 状态 |
| DeepSeek 官方 | DEEPSEEK_PLATFORM_TOKEN | 可写密码框（官方花费需要，会过期），带三段说明：它是什么 / 怎么取（platform.deepseek.com → F12 → Console → JSON.parse(localStorage.getItem('userToken')).value）/ 用来干什么 |
| 火山方舟 | ARK_ACCESS_KEY_ID | 可写密码框（插件专属，DSH 模型用的是 HUOSHAN_API_KEY，两套不同凭证） |
| 火山方舟 | ARK_SECRET_ACCESS_KEY | 可写密码框 |
| 火山方舟 | 区域 | 只读，自动跟随 DSH 模型配置（从 huoshan provider 的 baseURL 解析，如 cn-beijing） |
| Command Code | COMMANDCODE_API_KEY | 只读（DSH 模型配置已引用），显示 ✅/⚠️ 状态 |
| Google AI Pro | CPA_BASIC_AUTH | 可写密码框，格式 user:pass —— CPA 服务器上 nginx 的 Basic 认证（第二把锁） |
| Google AI Pro | CPA_MANAGEMENT_KEY | 可写密码框 —— CPA 的 management key（第三把锁）；插件把它放在 X-CPA-Key 头里，由 nginx 改写成上游的 Authorization: Bearer |

可写框保存时走官方 ctx.credentials.set() 写入 $DSH_HOME/.credentials.yaml（refs: 段，带锁 + 原子写），插件自身不写文件。

凭证

凭证存于 $DSH_HOME/.credentials.yaml（Web 界面 Models 页写入，或直接编辑文件；插件通过官方 ctx.credentials 服务读取，环境变量优先）：

| 凭证 | 必需 | 用途 |
| DEEPSEEK_API_KEY | ✅ | 查询余额 api.deepseek.com/user/balance |
| DEEPSEEK_PLATFORM_TOKEN | 可选 | 查询官方用量（今日/7日/30日）。获取：登录 platform.deepseek.com → DevTools Console 执行 JSON.parse(localStorage.getItem('userToken')).value，把输出写入凭证 |

⚠️ DEEPSEEK_PLATFORM_TOKEN 是网页会话 token，会过期（官方返回 code 40002/40003 即过期）。过期时卡片显示红色提示并回退余额差值估算；在设置面板凭证组粘贴新 token 即可恢复，余额查询不受影响。

| 凭证 | 必需 | 用途 |
| ARK_ACCESS_KEY_ID | 火山方舟渠道时需要 | 火山方舟控制面 API 签名（AK/SK），查询 Agent Plan 套餐额度 |
| ARK_SECRET_ACCESS_KEY | 火山方舟渠道时需要 | 同上，Secret Access Key |
| COMMANDCODE_API_KEY | Command Code 渠道时需要 | Command Code API key（user_...），查询 5h/周/月 用量 |
| CPA_BASIC_AUTH | Google AI Pro 渠道时需要 | CPA 前置 nginx 的 Basic 认证，格式 user:pass |
| CPA_MANAGEMENT_KEY | Google AI Pro 渠道时需要 | CPA management key，用于读取 antigravity-priority 插件探测到的配额快照 |

火山方舟 AK/SK 获取：登录 console.volcengine.com → 访问控制 → API 访问密钥 → 新建密钥。注意：AK/SK 是 IAM 账号级凭证，能操作所有资源，请妥善保管。

Google AI Pro（CLIProxyAPI）渠道搭建

这个渠道没有现成的公共接口可用：Google 侧不提供可查询的配额 API，CLIProxyAPI（下称 CPA）自身也不暴露配额 —— 必须由 CPA 上运行的一个配额 provider 插件去探测 Antigravity 的 5 小时 / 每周窗口，本插件再读这份探测快照。所以想看到这张卡片，需要你自己把下面这条链路搭起来：

dsh 插件 ──HTTPS:443──▶ nginx（TLS + Basic 认证 + 限流）
└──▶ CPA 127.0.0.1:8317（management key 鉴权） └──▶ antigravity-priority 插件（探测 Antigravity 配额） └──▶ Antigravity 上游

network.cpaBaseUrl 默认留空（本项目不附带任何他人地址），此时卡片显示「未配置 CPA 地址」；搭好后填入地址、再配上两条凭证即可。

1. CPA 侧

CPA config.yaml（v7.3+）：

管理 API：secret-key 必须非空，否则 /v0/management/* 不可用 remote-management: secret-key: "<随机强密钥 —— 这就是 CPA_MANAGEMENT_KEY>"

允许非本机来源访问管理接口（我们要经 nginx 转发进来） allow-remote: true

配额探测插件 plugins: enabled: true dir: "plugins" configs: antigravity-priority: enabled: true state_cache_path: "/root/.cli-proxy-api/antigravity-priority-cache.json"

【重要】声明反代来源网段，让 CPA 看到真实客户端 IP。
不配的话，经反代的所有请求都来自同一个 IP，而 CPA 对连续失败的管理鉴权会把源 IP 封禁约 30 分钟 —— 等于把你自己的整条链路封死。
trusted-proxies:
- "172.23.0.0/16"

把配额插件 antigravity-priority 装进 plugins/ 目录（Go 编译的 c-shared .so；它 supports_quota: false，不走 CPA 标准配额接口，而是提供自己的 plugins/antigravity-priority/snapshot/latest、run?mode=probe、samples、diagnostics 路由）。只放插件不启用 = 快照永远为空。

⚠️ 还要让插件真的会探测，否则卡片会"冻住"。 antigravity-priority 的后台定时调度由它自己的运行时开关 auto_apply 控制，而该开关默认关闭 —— 关闭时插件只在被显式要求时才探测一次，于是快照会永远停在最后一次探测的数字上（症状：卡片不报错、也有数，但几个小时都不动）。两条路任选：

- 开启插件原生调度：在 CPA 管理面板的「⚙️ 配置中心」打开 自动定时调度 (auto_apply)（周期默认 15 分钟）。它会周期性探测并写回凭证优先级 —— 这正是该插件的核心功能，想要它的双窗口调度与 429 熔断就应该开。
- 什么都不做：本插件会在快照超过 network.cpaStaleMs（默认 20 分钟）时自动补一次探测（只探测、不写回优先级），保证卡片不会一直停在旧数字上；此时卡片会把数字渲染成半透明以示"非最新"。

排查方法：GET .../plugins/antigravity-priority/diagnostics 看 management_api.auto_apply 与 run_history —— 若 run_history 只有一条且时间很久远，就是没人探测。

容器只监听回环，公网只暴露 443：

docker-compose.yml
ports:
- "127.0.0.1:8317:8317"
volumes:
- ./plugins:/CLIProxyAPI/plugins

2. nginx 反代（两层锁 + 路径封锁）

/v1/（推理）直通，/v0/（管理）叠一层 Basic，其余路径一律 404；再加限流防爆破：

limit_req_zone $binary_remote_addr zone=cpa_mgmt:10m rate=30r/m;

server {
listen 443 ssl http2; # nginx 1.24 及更早：http2 只能写在 listen 行上 server_name cpa.example.com; # ← 换成你自己的域名

ssl_certificate /etc/letsencrypt/live/cpa.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/cpa.example.com/privkey.pem;

推理路径：直通，靠 CPA 自己的 API key 鉴权 location /v1/ { 关键：nginx 内置默认只有 1m，而 0.5M token 的上下文光文本就 ≥2MB，超限会直接 413（请求根本到不了 CPA），大上下文必须放开 client_max_body_size 128m; 大 body 直接流给上游，不先缓冲落盘 proxy_request_buffering off;

proxy_pass http://127.0.0.1:8317;
proxy_buffering off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}

管理路径：Basic 认证 + 限流 + 认证头改写 location /v0/ { limit_req zone=cpa_mgmt burst=5 nodelay; auth_basic "CPA"; auth_basic_user_file /etc/nginx/.htpasswd-cpa;

proxy_pass http://127.0.0.1:8317;
关键：Basic 占用了 Authorization 头，而 CPA 只认 Authorization: Bearer。
所以客户端把 management key 放在 X-CPA-Key，这里为上游改写成 Bearer。
proxy_set_header Authorization "Bearer $http_x_cpa_key";
}

location / { return 404; }
}

/v0/ 只服务于本插件，暴露面越小越好；有条件可再叠一层 IP allowlist，或干脆只走内网 / WireGuard。

3. 插件侧

| 位置 | 填什么 |
| 设置面板 → 网络 → CPA 地址 | https://cpa.example.com（你的 nginx 入口，不要带 /v0 后缀） |
| 设置面板 → 渠道凭证 → Basic 认证 | CPA_BASIC_AUTH，格式 user:pass（对应 nginx 的 .htpasswd-cpa） |
| 设置面板 → 渠道凭证 → 管理密钥 | CPA_MANAGEMENT_KEY，即 CPA 的 remote-management.secret-key |

4. 自检

① 无 Basic → 401（被 nginx 拦下）
curl -s -o /dev/null -w '%{http_code}\n' https://cpa.example.com/v0/management/quota/providers

② 有 Basic、无 management key → 401（被 CPA 拦下）
curl -s -o /dev/null -w '%{http_code}\n' -u user:pass https://cpa.example.com/v0/management/quota/providers

③ 两者齐 → 200
curl -s -u user:pass -H 'X-CPA-Key: <management key>' \
https://cpa.example.com/v0/management/plugins/antigravity-priority/snapshot/latest

5. 踩坑清单

- 配额接口 501 / 快照为空：CPA 上没装或没启用配额 provider 插件。快照为空时（例如 CPA 刚重启）本插件会自动 POST 一次 .../run?mode=probe 再读一次，第二次仍空则说明插件侧没探测成功。
- 卡片有数但几小时不动：CPA 侧没人探测 —— 即上面的 auto_apply 没开。本插件会在快照过期（默认 20 分钟）后自动补探测兜底，但要让数据持续新鲜，建议直接开启插件侧调度。
- Basic 与 Bearer 抢同一个 Authorization 头：必须按上面的写法把 management key 放进 X-CPA-Key，由 nginx 改写成上游 Bearer；同时传两种 Authorization 只会互相覆盖。
- 连续鉴权失败会封源 IP：CPA 对失败的管理鉴权有暴力破解封禁（约 30 分钟）。经反代时所有请求源 IP 相同，一旦触发就是整条链路不可用 —— 所以务必配 trusted-proxies；已经触发时 docker restart <容器> 可清除封禁。
- 413 Request Entity Too Large（响应体是 nginx 的 HTML 错误页）：撞上了 nginx client_max_body_size 的内置默认值 1m。它跟 token 上限无关，请求在反代就被拒了，CPA 和模型根本没收到。0.5M token 的上下文光文本就 ≥2MB，所以只要用大上下文就必然触发 —— 按上面的示例在 location /v1/ 里加上 client_max_body_size 128m;。注意该指令不会从 /v0/ 那样的兄弟 location 继承，必须写在 /v1/ 自己（或写在上层 server/http 块里）。
- 大上下文上传慢：proxy_request_buffering off 去掉了 nginx 的落盘缓冲，但 body 仍要完整传到反代，瓶颈是客户端上行带宽（实测 3MB ≈ 15s）。这部分不是配置能解决的。
- http2 on; 在 nginx 1.24 上不支持：老版本只能写 listen 443 ssl http2;，写错会 unknown directive "http2" 导致 nginx 起不来。
- 必须走 TLS：Basic 是明文凭据，公网裸 HTTP 等于把密码广播出去。
- 推理与管理是两套密钥：/v1/ 用的 API key（DSH 模型里的 CLIPROXYAPI_KEY）和 /v0/ 用的 management key 互不通用。

本项目不含以上任何服务端组件，也不附带默认地址 —— 你需要自己部署 CPA + 配额插件 + 反代，并把地址填进 network.cpaBaseUrl。

工作原理

一个插件行同时承担两种角色（dsh.bundle patch + dsh.client 浏览器注册表声明）：

- 服务端半（lib/index.js）—— 通过 connection.fetch.register 在共享 /api 通道上注册 6 个 RPC 端点（继承官方信任围栏与浏览器认证）：balance/snapshot（DeepSeek 余额+官方用量窗口）、ark-quota/snapshot（火山方舟 Agent Plan 额度，每次调用签 AK/SK SigV4 调 GetAFPUsage，缓存 40s——严格小于浏览器端 60s 轮询，保证每次轮询都触发上游刷新）、cmdcode-quota/snapshot（Command Code 用量，Bearer 调 api.commandcode.ai/alpha/billing/credits 等，缓存 40s）、cpa-quota/snapshot（Google AI Pro 配额，读 CPA 管理接口上 antigravity-priority 插件的快照）、credential-status/snapshot（凭证状态与区域）、session-provider/snapshot（按会话解析渠道 provider）。缓存与超时时长来自设置面板（network.）。凭证统一走官方 ctx.credentials 服务读取。
- 浏览器半（lib/client.js）—— 零依赖 classic-script bundle，注册 sidebar.footer.action 条目。通过 sessions.list 订阅 + 1s 轻量轮询 /session-provider RPC（携带当前 sessionId，host 端按该会话的 modelSelection 投影解析渠道；0.7.1 起跨会话切换也会跟随）感知当前会话的 provider，再按渠道注册表分发：deepseek-official 渲染余额卡片（每 60s 轮询一次余额，标签页重新可见时立即刷新）；未注册渠道渲染「暂不支持」占位；无会话则不渲染。渠道目录变化（llm/adapters-updated 事件）会立即触发重新判定。同时注册 settings.section 设置页（余额监控），读写 dsh-balance-monitor 命名空间；credential-status 端点（凭证状态 + 区域解析，host 端从 ctx.llm/ctx.settings 判定哪些凭证被 DSH 模型配置引用）。

状态文件（$DSH_HOME/storages/balance-monitor.json）：

{
"date": "2026-08-17",
"dayStart": 100.0,
"lastTotal": 97.7,
"lastCurrency": "CNY",
"spent": 1.65,
"spent7d": 5.24,
"spent30d": 18.54,
"spentSource": "official",
"updatedAt": 1755400000000
}

spentSource 为 official（官方接口）或 estimate（余额差值估算）。

安全说明

- API key 与平台 token 永不离开服务端：浏览器半只能通过 RPC 通道看到余额/花费数字，接触不到凭证。
- 通道走 loopback 信任策略。
- 无遥测，网络请求仅官方余额接口与官方用量接口。

目录结构

dsh-balance-monitor/
├── package.json # dsh.bundle (patch) + dsh.client (浏览器注册表) ├── cordis.patch.yml # 插入这一个组合插件行 └── lib/ ├── index.js # 服务端半：6 个 /api RPC 端点（余额/方舟/Command Code/Google AI Pro/凭证状态/会话渠道）+ settings 接入 ├── config.js # 设置 schema + 默认值（与设置面板字段一一对应） ├── signature.js # 火山方舟 SigV4 签名 └── client.js # 浏览器半：侧边栏卡片 + 设置页（手写，无构建）

开发

无需工具链。直接改 lib/.js；bundle 格式与官方 tsdown 预设产物一致（window.__ModuleLoader__.load({ id, factory })）。

License

MIT