前言¶
用 DSH 跑 DeepSeek 会话时，有两件事总要切出去做：想确认账户还剩多少钱，得打开 DeepSeek 平台页面；想知道这段时间消耗了多少 Token、花在哪个模型上，也得另开页面翻。会话跑得越久，这种来回切换越频繁。
ds-balance 把这两件事搬进会话界面：余额以徽章形式常驻会话头部，点击可看明细和用量图表，也能直接跳官方收银台充值。下面介绍它的功能、安装方式和使用流程。
这是什么¶
ds-balance 是一个 DeepSeek Harness（DSH）插件，由 Lateautumns 维护，当前版本 1.1.0，协议 MIT。一句话定位：会话头部常驻 DeepSeek 官方余额徽章，附带余额明细、用量统计、历史回填和站内充值浮窗。
它不用小浮窗常驻卡片，而是把余额以徽章形式嵌在会话顶部右侧，点击徽章进入明细、用量与充值入口。
核心功能¶
余额徽章与自动刷新¶
徽章常驻会话头部右侧，显示状态圆点加当前余额，例如 DeepSeek ¥88.69。圆点颜色表示状态：
- 绿：正常
- 黄：低于预警线（¥10 / $2）
- 红：余额不可用或查询失败
刷新频率为代码常量：正常每 5 分钟一次，低余额时加密到 1 分钟，查询失败 30 秒后重试。
余额明细¶
点击徽章弹出明细：总余额、充值/赠送拆分、可用状态、更新时间，以及今日和近 7 天用量概览。
用量统计与图表¶
插件监听 DSH 会话事件（assistant/message 携带官方 usage 数据），按天 × 小时 × 模型聚合 API 请求次数、输入（命中缓存/未命中缓存）、输出 Tokens、轮次/步骤/工具调用。
点「用量详情」切换区间：今日是 24 小时堆叠柱状图，近 7 天 / 近 30 天是每日堆叠柱状图，悬停任意位置显示官方同款提示框。底部有三块内容：本期合计拆分行、按模型拆分（每个模型一行：彩色圆点、名称、请求/Tokens/消费及消费占比条，当前覆盖 V4 Flash / V4 Pro），以及逐日明细表（日期、请求、输入·命中、输入·未命中、输出、消费）。
消费估算¶
消费按官方价目由 Token 用量推算：内置 v4-flash / v4-pro 双价表，含 8/17 峰谷调价（北京高峰 9-12/14-18 为高峰价、其余半价，之前为平价），按事件时间自动选择价格档。界面标注「估算」，实际以官方账单为准。
历史回填¶
启动时自动回填最近 15 个会话、30 天。用量详情弹窗右上角有「回填历史」按钮，可一键深度回填最长 90 天、最多 60 个会话；数据有缺口时会提示「当前仅 X/Y 天有数据」。
回填上限 90 天，与 DSH 会话日志保留期一致，更早的旧日志通常已被压缩清理，无法恢复。
站内充值¶
点「充值」打开站内浮窗：显示当前余额，金额预设 ¥10/50/100/200/500，也支持自定义。确认后前往 DeepSeek 官方收银台，用支付宝或微信完成支付，到账后余额自动刷新。
安装与启用¶
前提：本机已在 DSH 凭证库配置 DEEPSEEK_API_KEY（如 ~/.dsh/.credentials.yaml）。未配置时徽章显示「未配置」并提示。
安装分两步：
# 1. 安装插件（web profile）
dsh plugin --profile web add <本仓库路径或 github:Lateautumns/ds-balance>
# 2. 重启 DeepSeek Harness
重启后打开任意会话，顶部右侧即出现余额徽章。本包通过 dsh.bundle.patch 挂载 Host 半端（cordis.patch.yml 注入 ds-balance 行），通过 dsh.client 加载 Client 半端（web 平台、立即生效），重启后两者自动就位，无需手动改配置。
想先临时体验的话，可以在会话内让 agent 加载仓库根 host.js + client.js（动态 Cordis 插件形态），无需安装即可试用。注意动态插件随 DSH 进程重启而失效，长期使用请走静态安装。
典型用法¶
日常操作按下面的顺序：
- 查看余额：会话顶部右侧徽章直接显示余额，圆点颜色表示健康状态。
- 余额明细：点击徽章，查看总余额 / 充值 / 赠送 / 可用状态 / 今日与近 7 天用量概览。
- 用量详情：点「用量详情」，切换今日 / 近 7 天 / 近 30 天区间查看图表与明细。
- 补齐历史：显示「当前仅 X/Y 天有数据」时，点右上角「回填历史」补全最长 90 天。
- 充值：点「充值」→ 选金额（预设或自定义）→「前往官方收银台支付」→ 支付宝/微信完成付款 → 返回后余额自动刷新。
实现与安全口径¶
评估这个插件时，有几个细节值得知道：
- RPC 通道：余额查询走官方接口
https://api.deepseek.com/user/balance；用量聚合支持区间参数 1d/7d/30d/all；深度回填参数限制 days≤90、sessions≤60。 - 密钥安全：
DEEPSEEK_API_KEY从 DSH 凭证库读取，只在 Host 进程内用于 curl，永不进入浏览器，浏览器端只收到解析后的数字。 - 查询方式：查询命令以 danger-full-access 运行（shell + curl）。原因是 Windows ACL 沙箱 runner 在部分机器不可用，且
web.fetch不支持自定义 Header、无法携带 Bearer 认证。命令为固定 curl（硬编码官方 URL），无注入面。 - 可调常量：预警阈值 ¥10 / $2（
LOW_CNY/LOW_USD）与刷新频率都是代码常量，可自行修改；价格表内置 8/17 前平价与 8/17 后峰谷价两档（PRICE_TABLES）。
卸载¶
dsh plugin --profile web rm ds-balance
执行后还需从 cordis.patch.yml 移除 ds-balance 行（若安装脚本未自动清理）。
适用场景与注意¶
ds-balance 适合通过 DSH 调用 DeepSeek API、希望在不离开会话的前提下掌握余额和 Token 消耗的开发者。如果你本来就要定期去平台页面核对用量和充值，徽章、图表和充值入口能省掉这些切换。
使用前注意几点：
- 消费为估算，实际以官方账单为准。
- 历史数据依赖会话日志，回填上限 90 天，更早日志无法恢复。
- 查询命令以当前 dsh 进程权限运行（含 danger-full-access），安装前应检查插件源码与许可证（MIT），确认可接受再装。
结尾¶
ds-balance 用一个常驻徽章把余额查询、用量分析和充值三件高频操作收进了 DSH 会话，静态安装重启后自动生效，动态加载则适合先试用再决定。
- 插件目录页：https://www.skillhub.cn/plugins/Lateautumns/ds-balance （社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系）
- GitHub 仓库：https://github.com/Lateautumns/ds-balance
