前言¶

用 API 额度或订阅跑智能体时，常见两类麻烦：任务跑到一半才发现钱或配额用完了；同时维护 DeepSeek、Kimi、智谱等多家控制台，各家展示的维度还不一致——有的是金额，有的是周期百分比。DeepSeek Harness（DSH）把模型路由和对话界面收在一处，但若余额信息仍分散在各厂商后台，排查成本不低。

dsh-balance-meter（npm 包名 @zhujiuyi/dsh-balance）是社区维护者 zhujiuyi 发布的 DSH 联网类插件：根据当前会话实际使用的模型路由，识别背后厂商，并调用其官方或约定端点查询 API 余额或订阅配额，在输入框下方的统计行统一展示。不启子进程、不申请 exec 权限，请求只发往你已配置的网关。

这是什么¶

一句话：告诉你在当前正在用的那条路由上，还剩多少 credit 或配额；读不到时会说明原因，而不是猜一个数。

• 维护者：zhujiuyi
• 仓库：github.com/zhujiuyi/dsh-balance-meter
• 社区目录：skillhub.cn/plugins/zhujiuyi/dsh-balance-meter
• 许可证：MIT（见仓库 package.json）
• 当前资料中的版本：0.2.5

社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；安装前建议自行查看源码与许可证。插件在 DSH 进程权限下运行，会使用 DSH 凭证存储中的密钥向对应网关发起查询。

核心功能¶

统一读数逻辑¶

余额按厂商（provider）统计，同一厂商下的模型共享同一资金池或配额池，而非按单个模型拆分。

插件强调三条原则（摘自 README）：

1. 不猜测：无法解析时明确报错并解释，宁可显示不可用，也不显示看似合理却错误的数字。
2. 过期数据会标注：刷新失败后仍可能保留上次成功读数，但会标为可能过期，并在详情里给出失败原因。
3. 趋势图只用真实采样：少于两次有效读数时提示仍在收集，不画假历史曲线。

内置支持的 9 家厂商¶

「窗口百分比」表示按滚动 / 周 / 月等周期分别列出配额条与重置时间，便于区分「5 小时窗口快用完」和「月度总量见底」。

自建中转（可能可用）¶

若路由指向自建中转（New-API、Sub2API、CloseAI、claude-code-hub 等），插件会按顺序尝试一组常见端点；你在配置里指定的 endpoint 优先于预设列表。预设响应形状来自公开面板文档转录，作者未对所有线上环境逐一验证；无法识别的响应会报告「可达但不可解析」并附带原始片段，不做臆测。

预设尝试顺序（资料原文）：

/api/usage/token/  →  /v1/dashboard/billing/subscription  →  /v1/usage
→  /api/v1/me/quota  →  /dashboard/billing/credit_grants
→  /api/v1/credits  →  /api/user/self

明确不支持或会直说的情况¶

• 厂商无公开余额接口：直接说明，不虚构数据。
• 路由不在目录且未匹配预设：报告「未编入目录」并附最后一次原始响应。
• 未配置凭证：提示需要设置的环境变量名。
• 端点有响应但结构未知：报告不可解析并给出脱敏后的摘录。

可通过 balance_set_endpoint 或配置中的 endpoint 字段为某条路由指定自定义查询地址。

界面与 Agent 工具¶

• 统计行常驻简略读数：API 额度显示金额，订阅类显示百分比。
• 点击可打开完整面板：厂商、计费模式、端点、上次读取时间及各配额窗口进度条。
• 对话中可让智能体调用 balance_check 工具查询剩余配额。

自动刷新策略¶

• 每轮对话结束后刷新一次。
• 后台每 15 秒检查一次（在策略允许时刷新）。
• 读数超过 5 分钟会强制刷新（可配置）。
• 手动点击「立即刷新」始终执行。

另有默认最短间隔 30 秒与失败冷却；页面隐藏时不轮询。

OpenDesign 用户额外步骤¶

OpenDesign 的账单不在 API 网关主机上，需先登录：

vela login

也可通过 OpenDesign 桌面应用登录。凭证写入 ~/.amr/config.json，插件从此读取。资料说明：配置在 DSH 中的 sk-amr-… 推理 Key 不能用于账单查询，未登录时会提示执行 vela login，而不会把该网关当作未知中转去盲目探测。

隐私与实现约束¶

• 无 exec 权限、无子进程。
• 请求仅发往已配置的网关，无第三方遥测。
• 密钥从 DSH 凭证存储读取，仅用于该网关请求头，不写盘、不写日志；浏览器快照中只出现变量名。

安装与启用¶

官方 README 给出的安装方式如下（注意包作用域为 @zhujiuyi/dsh-balance，不要安装无作用域的 dsh-balance-meter npm 包名）。

通过 DSH 插件命令安装：

dsh plugin --profile desktop add @zhujiuyi/dsh-balance

安装后重启 DSH，读数会出现在输入框下方统计行。

也可从 Release 安装 tarball（/latest/ 指向最新版，资料中的示例对应 0.2.5）：

dsh plugin --profile desktop add https://github.com/zhujiuyi/dsh-balance-meter/releases/latest/download/zhujiuyi-dsh-balance-0.2.5.tgz

或从 GitHub 仓库安装：

dsh plugin --profile desktop add github:zhujiuyi/dsh-balance-meter

卸载：

dsh plugin --profile desktop remove @zhujiuyi/dsh-balance

典型用法¶

多数时候无需操作，安装并重启后即可在统计行查看。

1. 扫一眼：金额或百分比常驻统计行。
2. 点开面板：查看端点、刷新时间与各窗口配额条。
3. 对话询问：例如「还剩多少配额」，由 Agent 调用 balance_check。

在 DSH 插件页中，可在 @zhujiuyi/dsh-balance 卡片上调整首选路由、是否自动刷新、最短刷新间隔与「超过多久强制刷新」等项。

为某条路由固定自定义端点或密钥环境变量时，编辑 profile 中的 cordis.patch.yml，在 balance-meter 条目下增加 config，例如：

- id: balance-meter
  name: "@zhujiuyi/dsh-balance"
  config:
    primary: deepseek
    routes:
      - id: my-provider
        baseURL: https://api.example.com/v1
        apiKeyEnv: MY_PROVIDER_API_KEY
        endpoint: '{origin}/v1/balance'

模板支持 {origin}（协议 + 主机）与 {base}（完整 baseURL）；文档建议优先 {origin}，以免 baseURL 带路径段时拼接出错。

适用场景与注意¶

适合：在 DSH 中频繁切换或多厂商路由，希望在同一界面掌握当前路由对应余额/配额；使用订阅制（智谱、Kimi Coding 等）需要看清各时间窗口消耗；自建中转且愿意按文档配置 endpoint 的用户。

注意：

• 插件能力边界以 README 列出的厂商与中转探测逻辑为准；未编入目录的路由需自行配置端点。
• 中转预设的响应格式未必与你的面板完全一致，异常时会返回不可解析说明而非静默失败。
• 安装与运行依赖 DSH 桌面 profile 及 peer 依赖（如 @deepseek-ai/dsh-tools 等，见 package.json）；升级 DSH 或插件后若读数异常，可先手动刷新并查看面板中的失败原因。

结尾¶

dsh-balance-meter 把「当前路由还剩多少」收进 DSH 界面：内置九家常见厂商、可选中转探测、不猜数、不偷偷用 shell 拉数据。若你正在用 DSH 跑长任务或多家 API，在统计行留一个真实读数，能少踩「半路耗尽」的坑。

• 目录页：https://www.skillhub.cn/plugins/zhujiuyi/dsh-balance-meter
• GitHub：https://github.com/zhujiuyi/dsh-balance-meter