English | 简体中文

dsh-balance-monitor

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

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

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

功能特性

功能	说明
多厂商堆叠	单张卡片自上而下逐厂商一行，展示名称、余额、比例条与已用量
Coding Plan / API 切换	每行的模式圆点（绿 = Coding Plan，灰 = API 按量）展开浮层菜单，切换即写入配置并即时返回新快照，无需编辑文件
自动跟随 DSH	读取 `settings.yaml` 中的 `llm-pi-ai.providers`，自动补入 DSH 已接入的 provider，并通过 baseUrl 反查厂商、推断计费模式
本地实测用量	厂商未开放余额接口（智谱 API、b.ai、百炼、方舟、小米等）时，改以 DSH 会话日志中的实测 token / 请求数展示
Token 活动看板	统计条（累计、峰值、最长聊天、当前 / 最长连续）+ 52 周 token 热力图（每日 / 每周 / 累计三档）+ 近 7 日 / 近 30 日范围切换下的每日趋势图与模型用量卡（对标 ZCode 使用统计），底部保留厂商明细表
适配器类型	balance（真实余额）、quota（滚动窗口配额，多窗口分行展示）、cost（近 30 天费用）；另有 local（本地实测）
配额取紧约束	多窗口时标题展示最紧张的窗口（如 5 小时已重置而本周已满，显示 0% 并倒计时至本周重置）
当日支出	余额型平台按日记录基线（持久化到状态文件），支出 = 基线 − 当前值；充值不会导致负数
通用自定义	通过 agent 调用 `balance_monitor` 的 `addCustom` 接入任意 OpenAI 兼容网关，或直接写入 `$DSH_HOME/.credentials.yaml`
收起态圆点	侧边栏收起至 36px 后，每厂商显示一个圆点（绿 / 琥珀 / 红按剩余量着色），悬停 tooltip 列出各厂商、数值及当前模式
位置	注册于官方 `sidebar.footer.action` 槽位，位于设置上方
健壮性	60 秒轮询，切回标签页立即刷新；上游失败时保留上次数据并标记为 stale，不闪错误
双语	跟随 dsh 界面语言（`navigator.language`）自动切换中 / 英
安全	API Key 仅存于服务端，浏览器只获取数字快照

支持的平台

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

id	显示名	环境变量 key	模式
deepseek	DeepSeek	`DEEPSEEK_API_KEY`	API 按量（余额 ¥）
zhipu	智谱 GLM	`ZHIPU_API_KEY`	Coding Plan 配额（积分窗口）· API 按量（本地实测）
zai	Z.ai（GLM 国际站）	`ZAI_API_KEY`	Coding Plan 配额 · API 按量（本地实测）
moonshot	Kimi / 月之暗面	`MOONSHOT_API_KEY`	Kimi For Coding 配额（5h + 周）· API 余额 ¥
minimax	MiniMax	`MINIMAX_API_KEY`	Coding Plan 配额 · API 按量（本地实测）
stepfun	阶跃星辰	`STEPFUN_API_KEY`	API 余额 ¥
dashscope	阿里百炼 Qwen	`DASHSCOPE_API_KEY`	API 按量（本地实测）
volcengine	火山方舟 Doubao	`ARK_API_KEY`	API 按量（本地实测）
xiaomi	小米 MiMo	`XIAOMI_API_KEY`	API 按量（本地实测）
siliconflow	硅基流动	`SILICONFLOW_API_KEY`	API 余额 ¥
openrouter	OpenRouter	`OPENROUTER_API_KEY`	API credits $
xai	xAI (Grok)	`XAI_API_KEY`	API credits $
openai	OpenAI	`OPENAI_API_KEY`	API 近 30 天费用 $
anthropic	Anthropic	`ANTHROPIC_API_KEY`	API 近 30 天费用 $（需 Admin key）

计费接口实测

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

智谱：无公开余额接口（/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 按量），在浮层菜单中选择：

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

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

配置密钥

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

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 兼容网关 / 反向代理 / 小厂商（仅写入配置，字段如下）：

字段	说明
`label`	卡片上显示的名字（自动生成 id）
`baseUrl`	如 `https://gateway.example.com`
`path`	默认 `/v1/user/balance`
`auth`	`bearer`（默认）/ `raw`（原样写进 Authorization）/ `x-api-key`
`kind`	balance（余额条）/ quota（配额百分比窗口）
`currency` / `modeLabel`	显示币种 / 模式名
`keyEnv`	读取的 env / `.credentials.yaml` 条目；留空则按 `label` 自动生成 `XXX_API_KEY`
`apiKey`	直接写入 `$DSH_HOME/.credentials.yaml`（仅存服务端，不回显）
`pick`	取值映射：剩余 / 总额 / 重置时间路径，如 `data.balance`

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

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

可选配置

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

Token 活动看板

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

Token 活动看板

统计条（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，无构建步骤：

sh
dsh plugin --profile web add "github:<you>/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:模式 记账，切换模式不会污染彼此的「当日已用」：

json
{
  "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

dsh-balance-monitorDeepSeek Harness plugin

Overview

Original README