dsh-balance-inquiry

English ｜ 简体中文

已发布到 npm：dsh-balance-inquiry
（npm i dsh-balance-inquiry / pnpm add dsh-balance-inquiry）。

在 DSH 左侧边栏底部、「上下文洞察」的上面加一行按钮：

💰 剩余额度：12.34 ￥

• 多套餐：一个套餐一条配置，侧边栏显示所有套餐里最紧急的那条；左键点这一行打开余额看板，
  每个套餐一张圆角长方形卡片（套餐名称 / 剩余额度 / 上次查询时间）。
• 看板里：左键点卡片打开这个套餐的官网地址，另有「添加套餐」「立即查询」按钮，
  按 Esc 或点遮罩关闭；要看/改某个套餐就去 设置 → 余额查询 里点它的长条按钮。
• 设置页分两级：一级是「添加套餐」+ 已添加套餐的长条按钮列表 + 通用设置；点「添加套餐」弹窗先选
  按量计费（API Key）还是 Token Plan / Coding Plan，再选厂商；点长条按钮进入二级编辑页
  （改名称 / 厂商 / 令牌 / 接口地址 / 官网地址，或删除套餐）。
• 支持 New API（one-api / new-api 系）、DeepSeek 官方、StepFun、SiliconFlow（国内 / 国际）、
  OpenRouter、Novita AI 六类原生余额接口，以及自定义用量脚本
  （({ request: {…}, extractor: function (response) {…} })，支持
  {{baseUrl}} / {{apiKey}} / {{accessToken}} / {{userId}} 占位符）。
• 支持 8 家编程套餐（Token Plan / Coding Plan）的用量查询：Kimi For Coding、智谱 GLM、
  智谱 GLM 团队版、MiniMax、ZenMux、火山方舟（Agent / Coding Plan）、OpenCode Go、Command Code；
  显示每个时间窗口（5 小时 / 周 / 月）的已用百分比与剩余百分比，剩余不足 10% 时变黄。
• New API 默认 GET {baseUrl}/api/user/self，显示值 = data.quota ÷ 换算比例
  （默认 500000，也就是 1 ￥ = 500000 quota）；按积分 / credits 计的套餐不显示换算比例。
• 没有「自动识别」：厂商由套餐显式指定，接口地址不再参与判断。
• 切换模型供应商自动联动：套餐的「供应商ID」可以同时绑定多个 DSH provider：
  官方登录 deepseek-official、账号登录 deepseek-account，以及 cordis.patch.yml
  里 llm-pi-ai 配置的自定义路由（如 cotton-api）。
  绑定通过一个独立弹窗完成：列出所有已添加的供应商，支持搜索、全选与逐个勾选，可多选。
  当您在 DSH 中切换到其中任意一个供应商时，左下角自动感知并显示该套餐的余额；未匹配或未绑定时回退展示所有套餐中最紧急的一项。
• 多套餐 / 多币种支持：侧边栏默认显示额度最少（最紧急）或当前激活供应商的那一项，鼠标悬停的 tooltip 里列出所有套餐
  （含每个套餐的各档位名称与重置时间）。
• keep-last-good：瞬时失败（网络错误 / 超时 / 5xx / 429）时，10 分钟内继续展示上次成功的余额，
  tooltip 标注「上次成功：…」；鉴权失败等确定性失败立即透出并清掉旧值，避免显示过期额度。
• 余额只在为 0 时变红；只有按百分比的档位才做「剩余 < 10%」的黄色预警。
• 请求默认由 DSH 宿主进程发出，不受浏览器跨域限制；宿主通道不可用时自动回落浏览器直连。
• 安全边界：取消向宿主获取 baseURL 等敏感网络信息的行为；仅通过受约束的本机路由读取 provider id 用于匹配。

安装

dsh plugin --profile desktop add dsh-balance-inquiry

> profile 的依赖列表和 bundles 是启动时读取的，所以装好后要重启 DSH 桌面端
> （Web 版则重启 dsh web）。重启后侧边栏底部就会多出这一行。

配置

打开 设置 → 余额查询（一级页）：

> 插件不预设任何站点：接口地址与官网地址都是空的，也不会自动去查任何第三方服务。
> 第一次使用请点「添加套餐」自己填；两个地址都为空时，看板卡片不会跳转。

配置存在 DSH 主目录下的两个 YAML 文件里（默认 $DSH_HOME/dsh-balance-inquiry/，
没设置 DSH_HOME 时退回 ~/.dsh/dsh-balance-inquiry/）：

拆成两个文件是为了让 config.yml 可以放心分享或提交到仓库，密钥单独收好即可。
两个文件都是普通 YAML，可以直接用编辑器改；插件每次写入都是「先写 .tmp 再改名」的原子写，
不会因为中途崩溃留下半个文件。目录里只有这两个文件，没有别的。

老版本（0.6.0 及以前）把配置放在渲染进程的 localStorage（dsh-balance-inquiry:accounts /
:settings / :results），升级后第一次打开会自动搬到 config.yml，之后 localStorage
只在宿主路由不可用（纯浏览器环境）时作为兜底。设置页底部会显示当前实际使用的目录。

各供应商的端点

响应解析、错误文案（Network error: … / Authentication failed (HTTP 401) /
Failed to parse response: …）、脚本引擎的字段校验与 200 字符错误体预览，都由插件自己实现，
可以在「设置 → 余额查询」里看到每次查询的具体原因。

编程套餐（Token Plan / Coding Plan）

在「添加套餐」弹窗里选 Token Plan / Coding Plan，再选厂商（不再有自动识别）。
编程套餐没有"余额"这个概念，所以显示的是每个时间窗口的用量百分比：看板卡片取最紧急的一项
（已用最多 / 剩余最少），tooltip 与编辑页列出全部窗口。

• 时间窗口统一归一为 5 小时 / 周 / 月：Kimi 的 limits[]（5 小时）与 usage（周），
  智谱的 TOKENS_LIMIT / CREDIT_LIMIT（按 unit 3 = 5 小时、6 = 周），MiniMax 的
  model_remains[]（general 模型的区间 / 周），ZenMux 的 quota_5_hour / quota_7_day，
  火山的 AFPFiveHour / AFPWeekly / AFPMonthly + QuotaUsage[]，OpenCode Go 的
  rolling / weekly / monthly，Command Code 的 windowLimits + 月度池。
• 火山方舟会先查 Agent Plan，没有活跃订阅时自动回落查 Coding Plan，
  两者都没有时才报「没有找到活跃订阅」。
• 所有编程套餐请求超时统一 15 秒；鉴权失败（401 / 403 / 签名错误）会把令牌标为失效，
  并在提示里带上服务端返回的原因。
• 有一项套餐同时返回美元金额时（ZenMux、Command Code），改用美元金额显示，而不是百分比。

自定义用量脚本

「厂商」选「自定义脚本」后，可以粘贴一段求值后返回对象的脚本，用来适配任何站点：

({
request: {
url: "{{baseUrl}}/api/user/self",
method: "GET",
headers: { "Authorization": "Bearer {{accessToken}}", "New-Api-User": "{{userId}}" }
},
extractor: function (response) {
return {
planName: response.data.group || "默认套餐",
remaining: response.data.quota / {{rate}},
used: response.data.used_quota / {{rate}},
total: (response.data.quota + response.data.used_quota) / {{rate}},
unit: "CNY"
};
}
})

• 占位符：{{baseUrl}}、{{apiKey}} / {{accessToken}}（当前令牌）、{{userId}}、{{rate}}（换算比例）。
• extractor 可以返回一项或一项数组（多套餐 / 多币种），字段：
  { planName, remaining, used, total, unit, isValid, invalidMessage }。
• 只允许 HTTPS（本机 http://localhost 除外）；脚本语法错误、extractor 抛错、返回数字等原始值，
  都会在设置页给出中文原因；extractor 返回 isValid: false 时按钮上显示为「无效」而不是硬错误。
• 旁边两个按钮可以一键填入 New API 模板 / 通用模板。

查询可能失败的原因

插件默认把请求交给宿主进程发出（Node，不受浏览器同源策略约束），但仍可能遇到这些情况：

宿主通道的原理：

渲染进程                                   宿主进程（Node，不受 CORS 限制）
POST /plugins/dsh-balance-inquiry/proxy   ───────►  dsh-balance-inquiry/lib/index.js
{ url, method, headers, body,             │  fetch(url, …)
timeoutSeconds }                        ▼
◄─────── { ok:true, status, body }     目标站点
（同源请求，不经网络，也没有 CORS 问题）

• 路由由宿主半边的 lib/index.js 用 dsh-host-webserver 注册成 exact 路由
  /plugins/dsh-balance-inquiry/proxy（exact 表优先于 dsh-client-modules 的 /plugins// 前缀路由）。
• 桌面端里 dsh-app://app/plugins/... 会被 Electron 主进程的 protocol.handle
  原样转发给宿主 webserver（方法、自定义头、请求体都会保留，并注入会话 cookie），
  所以渲染进程只要用相对路径 fetch 即可；Web 版是普通的 http 同源请求。
• 路由只服务带会话 cookie 的本机调用，并拒绝：非 HTTPS 目标（本机 http://localhost 除外）、
  URL 里带用户名密码、内网 / 回环 IP。它不是开放代理。
• 请求头原样转发，所以浏览器禁止设置的头（User-Agent 等）写在自定义脚本里也能真的发出去。
• 宿主路由不存在时（旧宿主、webserver 被禁用），客户端记住并回落浏览器直连，
  功能不会因为宿主侧缺失而不可用。
• 设置 → 余额查询 底部会显示当前用的通道：查询通道：DSH 宿主进程代理（不经过浏览器，无跨域限制）
  或 查询通道：浏览器直连（目标站必须允许跨域，否则会被拦）。

目录

dsh-balance-inquiry/
├── package.json        # dsh.bundle.patch + dsh.client.platform = web
├── cordis.patch.yml    # 插入 Loader 条目
├── CHANGELOG.md        # 中文更新日志
├── CHANGELOG_en.md     # 英文更新日志
├── docs/               # README 顶部的截图
├── icon.svg
├── LICENSE             # MIT
├── locale/{zh,en}.json # 文案（同一份也内联在 client.js 里）
├── README.md           # 中文说明
├── README_en.md        # 英文说明
├── NOTICE.md           # 许可证与版权说明
├── scripts/            # 维护脚本（不会随安装复制进 profile）
│   ├── publish.mjs              # 发布前检查 + npm publish
│   └── sync-locale.mjs          # 把 client.js 里的文案同步到 locale/*.json
├── *.mjs               # 自测（npm test 依次跑这五个）
│   ├── selftest.mjs             # 文案键一致性 + 字段归一化 + 匹配逻辑
│   ├── dialog_test.mjs          # 弹窗行为
│   ├── render_test.mjs          # 侧边栏 / 看板渲染结构
│   ├── form_test.mjs            # 设置页表单
│   └── config_test.mjs          # 配置文件路径、读写、迁移与 /config 路由
└── lib/
├── index.js        # 宿主半边：proxy / whoami / providers / config 四个路由
├── index.d.ts
├── yaml.js         # 极简 YAML 读写（零依赖）
└── client.js       # 全部界面与查询逻辑：侧边栏条目 + 设置页 + 查询引擎 + 代理优先 / 直连回落

版本变更见 CHANGELOG.md（中文）· CHANGELOG_en.md（English）。