English | 简体中文

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 刚重启导致快照为空时自动触发一次探测）。服务端需自行搭建，见搭建指南
位置	注册在官方 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.7.8+ 兼容 dsh ≥ 0.1.5-rc.1（包含 0.1.7+ 架构重构，支持 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