English | 简体中文

dsh-balance-monitor

dsh-balance-monitor 是一个 DeepSeek Harness (dsh) 插件，在侧边栏底部集中展示多个 AI 平台的余额、配额与用量，并提供基于本地会话日志的 Token 热力图看板。

插件按厂商逐行堆叠，每行展示剩余额度、剩余比例条、已用量与当日支出。同一厂商同时提供 Coding Plan（订阅套餐）与 API 按量两种计费方式时，可通过行内的模式圆点在两种口径之间切换；厂商未开放余额或计费接口时，自动退化为 DSH 本地实测用量。界面样式基于官方设计令牌，力求克制内敛。

> 背景：DeepSeek 调价后，用户可能需要切换至智谱等平台，而原插件仅支持 DeepSeek 单一平台。本插件以平台适配器注册表为骨架，动态对接已配置密钥的厂商，并自动纳入 DSH 已接入的 provider。

功能特性

支持的平台

内置 14 家厂商，各家声明所支持的计费模式；同一密钥的两种模式共用，切换仅改变展示口径：

计费接口实测

以下为各厂商计费接口的实测情况，供配置时参考：

• 智谱：无公开余额接口（/api/biz/balance/query 拒绝访问，其余返回 404），API 模式走本地实测；Coding Plan 模式走 /api/monitor/usage/quota/limit，按 unit 识别窗口（3 = 5 小时、2 = 日、1 = 月、6 = 周），支持 TOKENS_LIMIT / CREDIT_LIMIT / TIME_LIMIT 三种限额。
• b.ai：无计费接口（一律返回 403 HTTP node only allows access to inference API paths），自动注册为 dsh:b-ai 本地实测行。
• MiniMax：/coding_plan/remains 需要 cookie，/v1/token_plan/remains 接受 Bearer，插件内置后者。
• 负余额：余额为负（欠费）时不绘制进度条，数值照常展示。

Coding Plan / API 切换

点击每行右侧的模式圆点（绿 = Coding Plan，灰 = API 按量），在浮层菜单中选择：

1. 浏览器向 /balances 发送 {action:'setMode', id, mode}；
2. 服务端写入 $DSH_HOME/balance-monitor.config.json 的 platforms..mode；
3. 接口即时返回新快照，卡片原地更新，无需重启或刷新。

模式优先级：手动覆盖 > 按 DSH baseUrl 推断（/coding、/paas/coding、anthropic 判为套餐，其余为按量）> 该厂商首个已配置密钥的非本地模式。

配置密钥

无需额外配置文件：配置了密钥的厂商会被自动展示，DSH 已接入的 provider 也会自动补入。密钥先读取环境变量，否则读取 $DSH_HOME/.credentials.yaml：

# `$DSH_HOME/.credentials.yaml`
DEEPSEEK_API_KEY: sk-xxxx
ZHIPU_API_KEY: xxxx
MOONSHOT_API_KEY: sk-yyyy

环境变量优先：ZHIPU_API_KEY=xxxx dsh --profile web ...。

通用自定义平台

通过 agent 调用 balance_monitor 的 addCustom 接入任意 OpenAI 兼容网关 / 反向代理 / 小厂商（仅写入配置，字段如下）：

若映射取不到数值，会明确提示「按映射取不到数值，检查字段路径（如 data.balance）」，不会静默显示 0。

配置前建议先用 curl -H "Authorization: Bearer $KEY" 查看真实响应：不同厂商的前缀不统一，例如 DeepSeek 的返回不含 data 包装，正确路径为 balance_infos.0.total_balance（路径以 . 分段，数组下标可直接写作数字）。

可选配置

{
"platforms": {
"zhipu": { "label": "智谱GLM", "enabled": true, "mode": "coding" },
"deepseek": { "enabled": false }
},
"custom": [
{ "id": "custom-mygateway", "label": "我的网关", "baseUrl": "https://gw.example.com",
"path": "/v1/user/balance", "auth": "bearer", "kind": "balance", "currency": "CNY",
"pick": { "remaining": "balance", "total": "total_balance", "resetAt": "" } }
]
}

Token 活动看板

点击 ▦ Token 活动 打开看板。数据全部来自本地 $DSH_HOME/sessions/*/*/session.jsonl[.zstd]，不调用任何厂商接口，因此「本地实测」型厂商同样有数据。看板布局对标 ZCode 桌面端「使用统计 · 应用用量」，并适配 dsh 的双主题设计令牌。

• 统计条（5 格）：累计 Token 数（所有会话的 in + out 之和，缓存读取仅计入 tooltip 与脚注；采用 亿 / 万 中文计数）、峰值 Token 数、最长聊天时长（相邻事件间隔超过 30 分钟即断开，避免将跨天挂机计为会话）、当前 / 最长连续天数
• Token 活动热力图：52 周（约一年）贡献墙样式，周一对齐，月份轴置于图下方，颜色按 sqrt 分 5 档；支持每日 / 每周 / 累计切换，单元格 tooltip 展示日期、tokens、请求、轮次、时长与缓存读
• 时间范围：近 7 日 / 近 30 日 切换，作用于下方趋势图与模型用量
• 每日 Token 趋势图：手写 SVG 平滑曲线（单调三次插值，不过冲）+ 渐变面积填充，展示范围内 Top 3 模型的每日用量曲线，悬停显示各模型当日 tokens
• 模型用量：Top 1 模型占比描述 + Cache 命中率；输入 / 输出 / 缓存 / 其他模型四色构成堆叠条；Top 3 模型明细行（由服务端下发的模型×日矩阵按范围切片聚合）
• 平台表：各厂商 Token / 请求 / 活跃天数（本插件特色，保留在面板底部）
• 脚注：最近刷新时间、口径说明（活跃天数 / 轮次 / 会话数 / 聊天总时长 / 缓存读未计入）

解析说明：dsh 的 .zstd 文件为多帧拼接流，zstdDecompressSync 仅解出第一帧；插件按 magic 28 B5 2F FD 切帧逐帧解压再拼接（实测 32621 帧，0 失败）。按 size + mtimeMs 生成指纹缓存（$DSH_HOME/storages/balance-monitor-usage.json），冷扫约 2 秒、命中约 300 毫秒；重启后先以缓存摘要秒开，再于后台重扫。缓存版本 v4 起模型维度携带 in/out/cache 拆分与模型×日矩阵，供前端按时间范围切片。

安装

浏览器端 bundle 为手写 classic script，无构建步骤：

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

完成后重启 Web UI（dsh --profile web）。修改 lib/client.js 后刷新页面即可生效；修改 lib/index.js / providers.js / usage.js 需重启 dsh。

工作原理

• 服务端 lib/index.js：注册 /balances RPC 通道（loopback 信任围栏），动作含 snapshot / setMode / setEnabled / setLabel / saveCustom / removeCustom / usage；所有写操作即时返回新快照。
• 适配器注册表 lib/providers.js：厂商 × 模式 × 解析器，含 matchVendor(baseUrl) 与 inferMode(baseUrl)。
• 用量扫描 lib/usage.js：扫描会话日志，按日 / 厂商 / 模型聚合，并产出连续天数与热力图数据。
• 浏览器端 lib/client.js：侧边栏卡片（展开 / 收起两态）+ Token 活动看板浮层，面板开合状态存于 sessionStorage，刷新不丢失。

每日基线账本（$DSH_HOME/storages/balance-monitor.json）按 平台id:模式 记账，切换模式不会污染彼此的「当日已用」：

{
"deepseek:api": { "date": "2026-08-27", "dayStart": 100.0, "lastTotal": 99.5, "spent": 0.5, "updatedAt": 1755200000000 },
"zhipu:coding": { "date": "2026-08-27", "dayStart": 500, "lastTotal": 372, "spent": 128, "updatedAt": 1755200000000 }
}

安全说明

• API Key 永不离开服务端，浏览器仅通过 RPC 获取数字快照。
• 通道采用 loopback 信任策略。
• 无遥测；网络请求仅面向各平台官方余额 / 配额 / 用量接口，以及本地会话日志读取。

目录结构

dsh-balance-monitor/
├── package.json        # dsh.bundle (patch) + dsh.client (浏览器注册表)
├── cordis.patch.yml    # 插入这一个组合插件行
└── lib/
├── index.js        # 服务端半：/balances 通道、config/账本读写、行装配
├── providers.js    # 厂商适配器注册表（模式、鉴权、解析器、baseUrl 反查）
├── usage.js        # 会话日志扫描 → 每日 token / 时长 / 连续天数
└── client.js       # 浏览器半：卡片 + 模式小圆点/浮层 + 热力图看板（手写，无构建）

开发

无需工具链。修改后执行 node --check lib/*.js 校验语法（client.js 为 classic script，请勿引入 ESM 语法）。

License

MIT