前言¶
用 DSH 跑长对话或调模型时，余额还剩多少、当前会话已经烧了多少 token，往往要切到 DeepSeek 控制台或自己翻日志。DeepSeek Harness 把能力拆成插件；社区目录里有不少客户端类插件，专门改 Web / Desktop 界面。下面介绍 dsh-api-balance（维护者 X-Xyy）：在会话标题栏右侧挂一颗状态 chip，点开后看余额拆分、本会话用量和上下文占用，不必离开当前对话页。
这是什么¶
dsh-api-balance 是 DSH 的客户端插件（dsh.client.platform: web），适用于 DSH Web 与 DSH Desktop。它在对话标题栏实时展示 DeepSeek API 余额与本会话 token 用量；Host 侧代查余额，浏览器侧只展示数字与计数，不把 API key 交给前端。
- 目录页：skillhub.cn/plugins/X-Xyy/dsh-api-balance
- 源码与说明：github.com/X-Xyy/dsh-api-balance
- 许可证：MIT（
package.json版本 1.0.0）
核心功能¶
标题栏 chip¶
chip 出现在会话标题栏右侧，与「在应用中打开」「下载会话日志」等按钮并列，示例形态：
● ¥88.99 · 12.3k tok
圆点含义：绿表示余额可用，黄表示余额不足，红表示查询失败，灰表示正在取数。
详情面板¶
点击 chip 后在右上角展开面板，内容包括：
- 余额：总额、可用状态，拆分为「充值余额 / 赠送余额」，并标注数据来源。
- 本会话用量：模型路由、请求次数，以及输入、输出、缓存命中、合计 tokens（数据来自会话日志里
assistant/message事件的usage字段）。 - 上下文占用：例如
263.4k / 1.0M (26%)及进度条（取自ctx.tokenMeter）。 - 「刷新」「关闭」与更新时间戳；展开时会强制拉一次最新值。
刷新节奏¶
页面每 20 秒轮询一次，且仅在会话界面打开时轮询。Host 侧余额结果另有 15 秒缓存，多开窗口不会成倍增加对 DeepSeek 的请求。
安装与启用¶
安装命令（来自仓库 README，profile 为 web）：
dsh plugin --profile web add github:X-Xyy/dsh-api-balance
包内无构建步骤，客户端为已产出的模块文件，也无第三方运行时依赖。重启 DSH 或刷新页面后，标题栏右侧应出现 chip。
卸载：
dsh plugin --profile web remove dsh-api-balance
若 profile 的 cordis.patch.yml 里仍有对应 insert 行，需手动删除。
典型用法¶
- 按上文命令安装并打开任意会话，观察标题栏右侧 chip 是否出现。
- 点击 chip 打开详情，核对余额与会话 token 是否与预期一致。
- 需要即时数据时点「刷新」，或依赖 20 秒轮询与展开时的强制刷新。
余额与凭据的读取方式（便于对照自己的 settings）：
- 余额请求：
GET {baseURL}/user/balance。 baseURL与apiKeyEnv优先读settings里llm-deepseek段；否则使用https://api.deepseek.com与环境变量DEEPSEEK_API_KEY。- API key 在每次查询时通过
ctx.credentials读取，不缓存、不落盘、不写入日志、不返回浏览器；请求由 Host 用node:http(s)发出，本插件不使用 shell 或子进程。
浏览器通过本机回环地址取快照（路由不带密钥）：
GET /dsh-api-balance/snapshot?sessionId=<id>[&force=1]
适用场景与注意¶
适合谁：日常在 DSH 里用 DeepSeek API、希望在同一界面盯余额和本会话 token 的开发者；依赖已在 DSH 中配置好的 llm-deepseek 或 DEEPSEEK_API_KEY 的用户。
权限与信任：插件以当前 dsh 进程权限在 Host 侧运行，安装前建议阅读 源码 与 MIT 许可证。快照路由不要求认证，本机其它程序同样可能读到余额与 token 计数（读不到 API key）；若回环地址环境不可信，需自行加校验或勿安装。
兼容性：仅声明 Web 客户端平台；不依赖 package.json 中的 dependencies，也不声明官方 @deepseek-ai/* 包，使用模块加载器提供的 react 种子模块与宿主服务。
结尾¶
dsh-api-balance 把 DeepSeek 余额和会话 token 用量收进对话标题栏，用颜色状态和详情面板减少切页查账的成本。社区目录与 DeepSeek / 幻方无官方从属关系，安装与升级以仓库说明为准。
