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 两个模型组）。样式完全使用官方设计令牌，克制内敛。

功能

安装

浏览器端 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: 段，即时生效（个别参数重启后生效）：

渠道凭证

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

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

凭证

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

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

> 火山方舟 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. 插件侧

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: ' \
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