前言¶

在 DeepSeek Harness（DSH）里开发智能体时，经常需要估算单次调用的成本、监控会话消耗、在长时间跑任务时检查余额是否充足。当前平台只提供「设置 → 账号」里的余额展示，切换窗口或频繁查看都会打断工作流。dsh-balance-badge 把余额胶囊直接挂在对话输入框正下方，与上下文用量指示器同一排，点击即可查看消耗曲线、本会话累计消耗和一键充值入口。

插件定位¶

• 名称：dsh-balance-badge
• 维护者：huachabobo
• 分类：客户端插件
• 功能：在 DSH 输入框下方显示 DeepSeek 账户余额、消耗曲线、本会话消耗，并提供一键充值入口

核心功能¶

余额胶囊¶

胶囊默认挂在 Composer 卡片正下方（conversation.composer.dock），新建会话的 Hero 页则放在工作区行右侧（conversation.hero.options）。显示内容取决于当前状态：

• 命中余额时显示「余额 ¥110.00」
• 赠金大于 0 时追加「＋赠金 ¥10.00」（平台常驻一个 0.00 的赠金钱包，不会显示为 0）
• 胶囊左侧显示当前模型输出价：「谷 ¥4/M」或「峰 ¥8/M」，颜色随时段切换（谷=绿、峰=琥珀），悬停可查看模型名与时段

胶囊支持悬停查看明细：充值余额、赠金余额、本会话消耗、更新时间、最近一次失败原因。

消耗曲线浮窗¶

点击胶囊会弹出一个向上展开的 292px 浮窗，与「任务列表」等按钮同一种菜单材质。浮窗内容包括：

• 头部：所选区间的净变化（−¥3.50 表示花掉，+¥3.50 表示增加）
• 充值余额、赠金余额、合计（赠金大于 0 时才显示合计）
• 本会话消耗与轮数
• 四档时间范围切换：1小时 / 6小时 / 24小时 / 3天
• 折线 + 面积图，蓝点为最近一次采样，琥珀色小圆点标出区间内最大的一次单次消耗
• 统计行：区间消耗 / 最大单次 / 最高 / 最低
• 底部：最近更新时间与采样点数
• 底部操作按钮：充值、立即刷新、清空记录

关闭方式：点击浮窗外部、再点一次胶囊或按 Esc。

后台刷新与状态¶

• 后台每 60 秒在可见页面静默刷新一次余额
• 切回窗口或恢复标签页时，若数据超过 20 秒会自动补读
• 轮次结束后（模型刚花完钱）自动补读一次
• 状态语义：同步中 / 未登录 / 读取失败；余额低于 1 时胶囊转为琥珀色警示

本会话消耗估算¶

平台不提供「某个会话花了多少钱」的接口，插件通过余额落差归因：

• 一轮开始时记录当时的余额快照，同时强制读一次余额
• 一轮结束后，若基线与最新余额的差额超过 0.0001 元，则累加到该 sessionId，轮数 +1
• 换会话时各会话独立记录，互不影响
• 数据存储在 localStorage["dsh-balance-badge:sessions:v1"]，最多保留 200 个会话（按最近更新丢弃）

这是估算而非精确账单：同一时刻若有其他窗口也在消耗，差额会被算进当前会话；刷新失败的那一轮不计。要查看精确数字仍以「设置 → 账号」的平台账单为准。点击「清空记录」可同时清空曲线与会话消耗记录。

模型价格（峰谷）¶

胶囊左侧的「谷 ¥4/M」或「峰 ¥8/M」是当前时段的输出价格（元 / 百万 tokens），悬停浮窗底部可查看完整价目与时段：

• 高峰时段：北京时间周一至周五 9:00–12:00、14:00–18:00
• 空闲时段：其余时间（包括周末与法定节假日），空闲价 = 高峰价的一半
• 当前时段那一列会加粗
• 时段判断按北京时间，与机器时区无关

价格表定义在 MODEL_PRICING 常量里（deepseek-flash 与 deepseek-v4-pro 各含高峰/空闲三档），PRICE_MODEL 决定胶囊按哪个模型报价，默认为 deepseek-flash（桌面 profile 的默认模型）。若需调整，可修改 client.js 顶部的常量区。

曲线数据采样¶

Platform 没有余额历史接口，采样由插件自己完成：

按「变化 + 心跳」记点，一天正常使用大约产生几十到一百多个点。刚装上时曲线为空，用几轮对话后就会长出来。同一浏览器里换账号会共用同一份历史，不想要则点「清空记录」。

安装与启用¶

通过插件市场安装¶

目录已收录进 DSH 1024Store（提交 PR #673 通过自动化静态检查后自动合并），可通过以下命令安装：

dsh plugin --profile <你的 profile> add github:huachabobo/dsh-balance-badge

若插件尚未发布到 npm，市场里能浏览和查看仓库与截图，但不会显示「可安装」按钮。

本地克隆安装¶

若想本地开发或调试，可按以下步骤操作：

# 1) 克隆到 profile 的插件目录
git clone https://github.com/huachabobo/dsh-balance-badge `
  "$env:USERPROFILE\.dsh-beta\plugins\dsh-balance-badge"

# 2) 让 profile 声明依赖与组合包
#    ~/.dsh-beta/profiles/desktop/package.json:
#      dependencies:        "dsh-balance-badge": "link:../../plugins/dsh-balance-badge"
#      dsh.profile.bundles: "dsh-balance-badge"   ← 追加到数组末尾

# 3) 在 profile 目录安装（只解析本地目录，不访问 registry）
cd "$env:USERPROFILE\.dsh-beta\profiles\desktop"
pnpm install

link: 会把 node_modules/dsh-balance-badge 指回源目录（Windows 上是 junction），修改 client.js 后无需重装；若想固定一份副本，可改用 file:。使用 ~/.dsh 而不是 ~/.dsh-beta 时，请相应调整路径。

安装后生效¶

1. 保存 profile 配置：启用 HMR 的 profile（随产品交付的 desktop / web 模板默认开启）会在 package.json、cordis.patch.yml 变化时重新组合，插件行即时挂载。
2. 重载客户端 bundle：Host 在组合时会快照每个 client.js，修改插件代码后，只刷新页面不一定能拿到新文件。
   - 有把握的一步：在「侧边栏 → 插件」中把 dsh-balance-badge 关再开（会重新组合并替换 bundle），然后刷新页面。
   - 或直接重启 DSH。
3. 验证挂载：在 Host 日志中搜索 [dsh-balance-badge] badge mounted; client bundle served from ./client，出现该行即表示插件已挂载。

可调参数¶

所有可调参数集中在 client.js 顶部的 constants 区：

适用场景与注意¶

适合需要实时监控 DeepSeek 账户余额、估算单次调用成本、追踪长时间任务消耗的开发者。

插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证（本项目使用 MIT 许可证）。

结语¶

dsh-balance-badge 把余额与消耗信息下沉到工作流中，减少在设置页和聊天窗口之间来回切换的次数。配合曲线图与时间范围切换，可以更直观地判断消耗趋势。更多细节可在 GitHub 仓库查看，目录页提供快速安装入口。