前言¶
在 DeepSeek Harness（DSH）里跑智能体时，账户还剩多少钱、当前工作区今天和本月大概花了多少 token，往往要切到官方控制台或自己翻日志。DSH 自带的会话查询接口主要给「会话累计」用，很难直接得到「今日 / 近 7 天 / 本月」并按缓存命中、未命中、输出分段估钱。下面介绍社区客户端插件 dsh-balance-card（维护者 HerTa-st），在宿主页面挂一张可拖动的浮层：点角色图从左侧滑出卡片，再点缩回，同时拉官方余额与本机会话日志里的用量估算。
这是什么¶
dsh-balance-card（npm 包名 dsh-herta-balance-card，当前版本 0.1.1，MIT）是一张不进 DSH slot、直接挂到 document.body 的浮层 UI。简介里的能力可以概括为：可拖动位图按钮 + 左侧滑出 / 缩回（带点击回弹动画）+ 官方 DeepSeek 余额（含赠金 / 充值拆分）+ 基于本地 session.v4.jsonl.zstd 的 token 用量与人民币估算（今日 / 近 7 天 / 本月，且只统计当前工作区）。
- 目录页：https://www.skillhub.cn/plugins/HerTa-st/dsh-balance-card
- 源码与说明：https://github.com/HerTa-st/dsh-balance-card
DSH 生态主张「一切皆插件」；SkillHub 等社区目录由社区维护，与 DeepSeek / 幻方无官方从属关系。安装前请自行阅读仓库源码与许可证，插件以当前 DSH 进程权限运行。
核心功能¶
余额：官方 API 优先，DSH 账号链回退¶
- 优先请求官方
GET https://api.deepseek.com/user/balance，API 密钥由 DSH 凭据服务现读，不落盘、不出宿主。 - 若未配置 API key 或被拒（README 提到实测 DSH 内存的 key 可能 401），回退到 DSH 账号登录态：
platform.deepseek.com/api/v0/users/get_user_summary，请求头x-dsh-auth-token，令牌同样由凭据服务现读（记录deepseek-account-platform/default），只读不删，避免一次查询把用户登出。 - 回退路径下用
normal_wallets（充值）与bonus_wallets（赠金）拼出与主路径类似的拆分展示。
用量：读会话日志，三段计价 + 峰谷价¶
用量不依赖官方给第三方的 ctx.sessionQuery 按天分桶，而是直接解析 DSH 原生会话日志 session.v4.jsonl.zstd：
- 文件是拼接的 zstd 帧，需按帧解压，整文件一次解压只会得到第一帧（README 写明会静默丢掉大量事件）。
- 计价按缓存命中 / 未命中 / 输出三段分开；README 举例
deepseek-flash命中价约为未命中的 1/50，不分段会把花费估高数倍。 - 每条事件按自身时间戳判定峰谷（北京时间 UTC+8，与机器时区无关）：工作日 9:00–12:00、14:00–18:00 为高峰，周末与中国法定节假日全天为空闲，空闲价为高峰价一半；窗口左闭右开（12:00 整算空闲）。2026-08-16 16:00 UTC 起峰谷定价生效，更早事件按空闲价。
- 工作区隔离：用会话目录名（cwd 的不可逆编码）比对，只统计当前工作区，避免多目录混算。
- 性能：全量重算 README 实测约 2.5 秒（70 文件 / 45 MB 等规模）；支持 mtime+size 增量与已解析事件落盘缓存（
cachePath设为-可关闭），失败不写缓存。
无公开单价的 provider / 模型（如部分套餐或 qwen 系列）estimateCost 返回 null，避免把「未知」显示成 0 元。
交互与形态¶
- 图片按钮与余额卡片都常驻同一浮层 root；图片
z-index高于卡片，点图片从左侧滑出卡片，再点图片或卡片右上角 ✕ 缩回。 - 开合仅用
transform/opacity；支持prefers-reduced-motion。 - 按钮为位图（默认黑塔角色抠图，192×236 显示尺寸，以仓库根
button-size.json为准），经宿主白名单下发icon.png/icon@2x.png，取不到则退回内置 SVG。 - 拖动位置持久化在
localStorage；窗口 resize 时会先把按钮夹回视口，避免拖出屏外无法点击。 - 客户端不打包：
package.json中exports["./client"]指向lib/client.js源文件，宿主原样伺服，改完刷新即可。
安装与启用¶
安装命令以仓库 README 为准。从 npm 安装（预构建，免 allowBuilds 授权）示例：
$env:DSH_HOME='<你的 DSH_HOME>'
& '<DSH 安装目录>\runtime\cli\bin\dsh.cmd' plugin --profile <profile> add dsh-herta-balance-card
将 <你的 DSH_HOME>、<DSH 安装目录>、<profile> 换成你本机 DSH 的实际路径与配置档名。README 另提供从本地路径安装的方式，需自行 clone 仓库后按文档操作；本文不展开 clone 步骤。
典型用法¶
安装并启用插件后，无需额外配置文件即可在 Web 客户端看到浮层按钮：
- 拖动：按住角色图拖到不挡操作的位置；坐标会写入
localStorage，刷新后仍在该处。 - 查看余额与用量：点一下图片，卡片从图片左侧滑出，展示官方余额拆分与本工作区的 token 用量及人民币估算（今日 / 近 7 天 / 本月）。
- 收起：再点图片，或点卡片右上角关闭，卡片缩回图片背后。
若需更换按钮图或改显示尺寸，维护者文档说明改仓库根 button-size.json 后运行 scripts/build-icon.mjs 同步客户端 DOT_W/DOT_H 与出图资产；从原图重做需 extract-character.py 与 verify-icon.mjs 等脚本，属二次开发场景，见 GitHub README「按钮图标怎么换」一节。
适用场景与注意¶
适合：长期在 DSH 桌面 / Web 里开发智能体、希望不离开当前工作区就能扫一眼 DeepSeek 账户余额，并对当前项目会话做分段 token 与峰谷价花费估算的开发者。
注意：
- 余额与令牌均经 DSH 凭据服务读取，信任边界与 DSH 本体一致；请勿在不可信环境安装未审阅的插件。
- 用量为基于本地日志的估算，依赖官方计价规则与插件内节假日表（README 写明 2026 年节假日来源为国办发明电〔2025〕7 号）；与账单若有偏差应以官方为准。
- 插件主动避开 DSH slot（README 提到官方 0.2.0 曾删除第三方用过的 slot），浮层独立挂载，可能与个别全屏 UI 叠层冲突，可自行拖动按钮避让。
- GitHub 仓库当前星标为 0，属早期社区插件；问题与更新以 Issues 与仓库提交为准。
结尾¶
dsh-balance-card 把「官方余额 + 本机会话三段计价与峰谷估算」收进一张可拖动的浮层，用点击滑出 / 缩回完成日常查看。需要安装命令与交互、计价细节时，以 README 为准。
