前言¶

用 DeepSeek Harness 做日常对话或 Agent 开发时，余额会在计费调用后变化，但桌面端并没有一个始终可见的「还剩多少钱、今天花了多少」入口。去官网或设置里查，要打断当前工作；若只靠记忆或偶尔打开网页，低余额往往在接口报错前才被发现。

社区插件 dsh-balance-hud（仓库 poliucode/dsh-balance，维护者 poliucode，分类为客户端）把余额、今日消费和低余额提示放在侧边栏底部动作区，由宿主统一向 DeepSeek 取数，浏览器侧只读快照并展示浮层明细。下面介绍它的定位、能力与安装方式。

包名注意： npm 上的 dsh-balance 是另一位作者的包（资料中提及 0.2.7 与新版 DSH 兼容性预检不通过），与本插件无关。请安装 dsh-balance-hud。

这是什么¶

dsh-balance-hud 是 DeepSeek Harness 的 Cordis 插件（当前资料中版本 0.4.1，许可证 MIT）。它在桌面端 侧边栏底部（挂载点 sidebar.footer.action，紧挨「设置」上方）常驻两行：第一行余额，第二行今日消费；点击可展开明细浮层。侧边栏折叠时收成 36×36 图标，仍可在图标上显示状态与流速扫光（可通过配置关闭折叠态展示）。

取数在 宿主进程 完成，多窗口/标签页共享同一份快照，避免每个界面各自轮询官方接口。

核心功能¶

界面与交互¶

• 常驻双行：余额 + 金额；第二行为今日消费（无数据时不占位）。
• 低余额（默认 CNY ¥2、USD $0.3）：整行变红、警示图标、金额加粗；浮层顶部横幅与「去充值」路由。
• 明细浮层：大号余额、今日消费/充值、各币种明细（含赠送/充值拆分）、数据来源徽标、更新时间、手动刷新。
• 状态点（仅异常时出现）：黄 = 显示旧数据；红 = 读取失败；灰 = 未登录/未配置。
• 取数失败时 保留最后一次成功数字，并标注「显示的是上次成功读取的余额」，不把余额显示成 0。

「实时」刷新策略¶

余额只在计费发生后变化，插件用三种方式刷新，而不是单纯缩短轮询：

1. 装配时读一次；
2. 每个对话回合结束（session/event 的 turn/end）后 1.2 秒 防抖再读一次，便于平台账本落账；
3. 宿主后台定时器（默认 60 秒）、浏览器每 5 秒 轮询宿主快照（本地内存，不打上游）、页面重新可见/获焦时补读、用户点「刷新」走 POST /refresh。

余额流速扫光¶

在数据状态为 ready 时，按最近窗口内的消费速率在行表面显示蓝色光带（低余额时改为告警红）；prefers-reduced-motion: reduce 下关闭动画。速率档位与 flow 配置见仓库 README，界面上不显示具体速率数值。

数据来源与今日消费¶

凭据经 DSH credentials 服务解析（默认引用名 DEEPSEEK_API_KEY），不读配置文件、不进日志。

今日消费由 相邻两次余额读数的变动 推算（非逐笔账单接口）；账本落在 $DSH_HOME/dsh-balance/ledger.json，跨天按配置的 dayTimeZone（默认 Asia/Shanghai）重置。资料中说明了充值与消费在同一读数间隔内无法区分方向的边界。

安装与启用¶

装完后需 重启 DeepSeek Harness（宿主侧在启动时装配）。

桌面端搜索安装（推荐）¶

1. 打开 DSH 桌面端 → 左侧「插件」；
2. 「安装插件」中输入 dsh-balance-hud（勿选无 -hud 的 dsh-balance）；
3. 安装并按提示重启。

也可使用：github:poliucode/dsh-balance，或 Releases 中的 dsh-balance-hud-x.y.z.tgz。

命令行（web profile）¶

桌面端 profile 为 desktop 时 CLI 会拒绝，请用界面安装或开发脚本。

dsh plugin --profile web add dsh-balance-hud

dsh plugin --profile web add github:poliucode/dsh-balance

dsh plugin --profile web add ./dsh-balance-hud-0.4.0.tgz

<profile> 一般为 web。

典型配置¶

在 profile 的 cordis.patch.yml 中按 id: dsh-balance-hud 覆盖。示例（资料原文）：

- id: dsh-balance-hud
  name: 'dsh-balance-hud'
  config:
    source: api-key
    displayCurrency: USD
    refreshIntervalSeconds: 30

常用项（均可省略，bundle 自带默认值）：

package.json 中声明与 DSH 0.2.0-rc.2、0.2.1-rc.3 兼容。

适用场景与注意¶

适合长期在 DSH 桌面端对话、调试 Agent、频繁调用计费 API 的用户：余额与今日消费在侧边栏可见，低余额有视觉告警，回合结束自动刷新比固定短轮询更贴近实际扣费节奏。

安装前请注意：

• 插件以 当前 DSH 进程权限 运行，会访问账号/API 余额接口并在本地写入 ledger；安装前应阅读 源码与 LICENSE，确认符合你的安全与合规要求。
• 社区目录 skillhub.cn 上的 poliucode/dsh-balance 条目 与 GitHub 仓库为社区维护信息，与 DeepSeek / 幻方无官方从属关系；DSH 生态本身是「一切皆插件」，目录站是独立站点。

结尾¶

dsh-balance-hud 把 DeepSeek 账号余额做成侧边栏底部的常驻 HUD：宿主统一取数、浏览器展示明细与告警，并配合回合结束刷新与可选流速扫光。若你已在用 DSH 桌面端，用包名 dsh-balance-hud 安装即可避免与第三方 dsh-balance 混淆。

• 目录页：https://www.skillhub.cn/plugins/poliucode/dsh-balance
• 仓库：https://github.com/poliucode/dsh-balance