余额与用量监控 Rannist/balance-dsh

balance-dsh

DeepSeek Harness 插件：在 Web UI 里直接显示 DeepSeek 账户余额，以及当前会话的 token / 金额消耗。

只支持 DeepSeek，暂不支持其他大模型。
余额读的是 DeepSeek 官方账号（未登录时回退 DeepSeek API Key），费用按 DeepSeek 官方价表估算，模型识别也只认 DeepSeek 的模型名。如果你通过其他厂商或自建服务用 DeepSeek Harness（OpenAI、Claude、本地模型等），本插件不会给出正确的余额和费用：余额会显示为不可用，模型会回落按 Flash 价估算，数字仅供参考。

最新版本见 npm；装好之后也可以在插件设置卡片里直接检查并更新。

功能

侧边栏余额行

侧边栏展开时贴在底部，紧挨「设置」齿轮。两种样式可在配置界面切换：

- 新版（默认）：上方一行文字信息 + 下方一条扁刻度条。
- 文字分两段：今日 ¥21.42（今天累计消耗）和 空闲 剩 3h57m（当前时段 + 距切换还剩多久，高峰为红色、空闲为绿色）。
- 刻度条整条代表一整天：彩色分段标出这一天里哪些时段是高峰、哪些是空闲，一个指针标出「此刻走在今天的哪个位置」，每分钟前进一格。换日或同步到新的节假日安排时，颜色分布会交叉淡入。
- 旧版：钱包图标 + 余额 + 金额（带货币单位）的纯文字行，右侧可带时段标签。

金额按余额状态变色：充足为主题绿、低于阈值（默认 10 元）为琥珀黄、为 0 时显示红色「去充值」。金额变化时按位滚动切换（只滚变化的数位），不会整块闪一下。

收起态圆钮

侧边栏收起时，余额显示为左下角的 60px 圆形悬浮按钮（liquid glass 质感，圆内显示 ¥金额，余额耗尽时显示「充值」）。直径与距左缘距离均可调，垂直方向自动对齐聊天输入框的中心。

刷新

- 默认每 60 秒自动刷新一次，间隔可调（5~3600 秒）。
- 对话产生新消耗时会顺带刷新一次余额。
- 右键任意余额元素可立即刷新（有防抖，连续点击不会重复打 API）。

余额与使用统计

单击余额打开居中弹窗（带半透明模糊遮罩），展示：

- 账户余额、近 90 天计费 Token、估算费用、活跃天数
- Token 构成与缓存命中率
- 按模型拆分（Flash / Pro）、按高峰 / 空闲拆分
- 今日 / 近 7 天 / 近 30 天、日均与峰值日
- 按日使用热力图

点遮罩、按 Esc、点关闭按钮均可关闭。

高峰 / 空闲计费

- 高峰时段 = 工作日 09:00-12:00、14:00-18:00（北京时间）。
- 其余时段全部按空闲计费：包括周末、中国法定节假日全天。调休上班的周末也按空闲——官方原文是「其余时段，包括周末及中国法定节假日全天均为空闲时段」，并没有给调休开例外。
- 节假日与调休安排从国务院公告（公开数据源）自动同步，内置当年表作离线兜底，无需每年手动维护；配置界面里能看到上次同步时间，也能手动触发立即同步。
- 消耗金额跨时段精确计费：高峰时段的 token 按高峰价、空闲时段按目录价，按每条消息的事件时间分桶计算，不会用「当前时段」笼统估算整个会话。

会话消耗行

对话框下方实时显示当前会话消耗（数据库图标 + 本会话消耗 + ≈¥金额）。点击展开明细浮层：Token 用量、缓存命中率、模型、高峰 / 空闲拆分、子代理消耗、网页搜索 / 抓取次数与费用、图片张数与估算 token。

智能体团队（Agent Teams）

会话里开了团队（Lead + teammate）时：

- 消耗行里多一颗 团队 N 小圆片，说明这颗金额是本会话 + N 个队友的合计（队友的钱本来就按子会话算进去了）。
- 明细浮层多一块「智能体团队」，按人头列出每个队友的 名字 · 状态 与 ≈ ¥金额，右上角是团队合计。
- 队友干活时 Lead 自己的 token 不变，所以有团队时会每 15 秒补拉一次（页面不可见时跳过），团队金额不会停在旧值。
- context: "fork" 的队友会继承父会话的历史前缀，插件只算 fork 之后产生的事件，不会把父会话的钱重复算一遍。

roster 直接读会话里的 team/member 事件，不依赖 agentTeams 服务或 agentTeam 投影 —— 团队功能没启用时这些事件不存在，上面这些都不出现。

网页搜索 / 抓取按次计费

调用 web_search / web_fetch 时统计次数。官方 2026-11-01 00:00（北京）起按次收费（每千次 ¥5），此前的调用标注为「免费期内」。这笔费用不属于峰谷计价，直接叠加。

图片（vision）消耗

发图时 DeepSeek 会按图片尺寸把图折算成 token，和文字 token 一起计费，没有单独的「图片费用」。也就是说图片消耗本来就在输入里，插件要做的是把它标出来——明细浮层里多一行：

图片 12 张 · 约 4,300 tok · 已计入输入

token 数用官方文档站「图片 Token 计算器」的同一套算法估算（像素按 14 对齐 → 按 3 折成视觉网格 → 每张上限 1024），所以和官网计算器算出来的数字一致。同一张图只算一次（按附件 ID 去重，不会因为同时出现在两处事件里被重复统计）。

要注意的是：图一旦进入上下文，后面每一轮请求都会再把它计一遍输入（多数能命中缓存，单价便宜很多）。所以「图片 N 张 · 约 X tok」说的是这些图本身的体积，不是它们累计产生的费用。

查看官方用量

双击余额，或点统计面板里的「查看官方用量」/「去充值」，会按三级顺序打开官方页面：

1. DeepSeek Harness 内置平台窗口（首选）。这个窗口自带平台登录凭据，所以不需要在网页里再登录一次。
2. 应用内侧栏浏览器（内置窗口拿不到时）。
3. 系统默认浏览器（最后兜底）。

余额重置 / 充值的入口就是同一个窗口里的 top-up 页，两个页面之间可以直接切换。

设置卡片

位置：主界面左上角 「插件」 → 点 balance-dsh → 「余额与用量」卡片。包含：
- 版本与更新：显示当前版本；点「检查更新」读取 npm 上的最新版本号（只查版本，不下载）。发现新版时原地变成「检测到新版本 X，是否更新？」——点「更新」才会下载并覆盖本机插件文件（旧文件先备份到 ~/.dsh/balance-update-backup/），完成后需重启 DeepSeek Harness 才生效。
- 启动自动检查：每次打开 DeepSeek Harness 会在启动后稍等片刻自动查一次；有新版本时左侧「余额与用量」入口旁显示 「新版本！」 胶囊提示。检查失败或断网时完全静默，不打扰。
- 节假日数据：显示同步状态（已同步天数、上次同步时间、尚未公布的年份）与「立即同步」按钮。
- 侧边栏入口开关：关掉后左侧导航不再显示「余额与用量」。关闭的那一刻会弹一个官方提示窗，告诉你从哪儿可以再打开。

整张卡片可以收起（点标题一行展开 / 折叠）。没有保存按钮，改动后约 0.35 秒自动保存，左下角依次显示「修改中… → 保存中… → 已保存」；点「恢复默认」立刻写回全部默认值。设置存放在你的 .dsh 目录下的 balance-dsh.json。

/balance-dsh-rannist 命令

在对话里输入 /balance-dsh-rannist 查询余额明细和当前会话消耗。

命令名带作者后缀是刻意的：DSH 的命令名全局唯一，/balance 这类通用名会和别的余额插件撞车（先注册的赢、后来的整条命令消失），所以用全名、不设备用名。注意 DSH 只接受小写命令名，写成大写会在注册时被判非法。

使用统计口径

插件显示的所有金额都是本地估算，不是 DeepSeek 官方账单。 想要准确数字请用「查看官方用量」打开官方页面。

- 热力图按北京时间聚合最近 90 天持久化会话中的 assistant/message Token usage。
- 费用按每条消息的实际模型和峰谷时段估算：高峰时段的 token 按高峰价、空闲时段按目录价，按事件分桶计算。
- 峰谷归属按「请求发起时刻」判定（取 step/start 事件的 time；拿不到时回退消息完成时刻）。官方并未公开跨时段请求到底按发起还是按完成计费，所以这是一个合理猜测而非官方口径；如果官方实际按响应生成时间逐段计费，一次横跨边界的请求真实费用会介于「全高峰」和「全空闲」之间，本插件两种口径都算不出这个中间值。（实测影响很小：请求平均耗时约 6 秒，长请求也只到分钟级，撞上窗口边界的概率极低。）
- 其他已知误差来源：本地 token 数与官方计费口径可能不同（系统提示、工具调用的内部算法未公开）；缓存命中与否按 usage 字段判断，官方口径可能不同；官方调价后需等插件更新价表；模型靠事件里的切换点推断，同名不同版本分不清。
- 峰值倍率只乘一次：高峰桶乘以倍率，空闲桶原价，网页工具费不参与峰谷倍数。
- 图片 token 已包含在输入里，插件不会再为它算一次钱（那会让金额翻倍）。明细里的「图片约 X tok」是各张图本身的体积之和，按官方计算器算法估算；图留在上下文里每轮都会重新计一遍输入，这部分体现在「缓存读取」中。
- 为避免历史会话过多拖慢 DeepSeek Harness，默认最多扫描最近 200 个会话；服务端统计与客户端展示结果均缓存 5 分钟，重复打开菜单不会重复请求。这两个值、以及刷新间隔、各类显示开关，都能在配置界面里改。
- 账户余额优先读取 DeepSeek Harness 官方账号（登录后即可用，无需 API Key）；未登录时回退到 API Key。两者都不可用时仍可查看本地 Token 与费用统计，只是余额会显示为不可用。

安装

前提：已安装 DeepSeek Harness 桌面版，且知道自己的 profile 目录（通常是 C:\Users\<你的用户名>\.dsh\profiles\desktop\）。

方式一：通过 npm 安装（推荐）

cd C:\Users\<你的用户名>\.dsh\profiles\desktop
pnpm add balance-dsh

方式二：从 tarball 安装

cd C:\Users\<你的用户名>\.dsh\profiles\desktop
pnpm add "file:C:\path\to\balance-dsh-<版本>.tgz"

方式三：从 GitHub 安装

cd C:\Users\<你的用户名>\.dsh\profiles\desktop
dsh plugin --profile desktop add github:Rannist/balance-dsh

用 npm 安装后，插件自带 dsh.bundle.patch（cordis.patch.yml），安装即自动注册，无需手动改 profile 的 cordis.patch.yml。只有用旧版 tarball / 手动方式时才需要手动注册：

profile 目录的 cordis.patch.yml（只有手动安装时才需要）
- insert:
- id: balance
name: balance-dsh

余额来源

官方 DeepSeek Harness 桌面版：在应用内登录 DeepSeek 账号后，插件会自动读取官方余额，无需任何配置。

其他环境（或不想登录官方账号时）：改用 API Key，三选一——

1. 环境变量 DEEPSEEK_API_KEY，或
2. 在注册项的 config.apiKey 中设置，或
3. 使用 Harness 凭据存储中的 DEEPSEEK_API_KEY

重启

客户端界面改动刷新页面即生效；服务端逻辑（刷新间隔、统计范围、API Key、计费倍率等）改动需重启 DeepSeek Harness 桌面版。

配置

可视化配置（推荐）

主界面左上角 「插件」 → 点 balance-dsh → 详情页里的「余额与用量」卡片。分组从上到下：

| 分组 | 可调项 |
| 版本与更新 | 当前版本、检查更新、就地更新 |
| 节假日数据 | 同步状态、立即同步 |
| 余额 | 刷新间隔、低余额警示阈值、API Key |
| 界面显示 | 侧边栏余额行开关、余额行样式（新版 / 旧版）、侧边栏入口开关、右键刷新浪潮、会话消耗行开关、（仅旧版）高峰空闲标签开关 |
| 收起态圆钮 | 显示开关、直径、距左缘 |
| 用量统计 | 扫描会话数上限、统计缓存时长 |
| 计费 | 高峰时段倍率 |
卡片最顶部是一条固定的范围声明：「计费仅支持 DeepSeek Harness 内的 DeepSeek 官方模型与账号；其他大模型不计入金额。」

配置文件 / 注册项覆盖

也可以在插件注册项（或 cordis.patch.yml）中覆盖：

- id: balance
name: balance-dsh
config:
apiKey: sk-xxxx # 可选；缺省用 DEEPSEEK_API_KEY 环境变量/凭据 peakWindows: # 可选；默认周一至周五，如下
- {start: 9, end: 12}
- {start: 14, end: 18}
peakWeekdays: [1, 2, 3, 4, 5] # 可选；1=周一 … 5=周五，0/6=周末
price: # 可选；逐项覆盖对应模型价格（元/百万 tokens） inputCnyPerMillion: 1 cacheReadCnyPerMillion: 0.02 cacheWriteCnyPerMillion: 0 outputCnyPerMillion: 4

注意：插件已自动按高峰 / 空闲时段计费（高峰价 = 目录价 × 倍率），不要再设置 config.peak: true，否则会重复翻倍。

卸载

cd C:\Users\<你的用户名>\.dsh\profiles\desktop
pnpm remove balance-dsh

如需删除手动注册行（若你手动加过），从 profile 的 cordis.patch.yml 移除对应的 balance 条目。

权限 / 数据

- 已登录官方账号时，余额通过 DeepSeek Harness 内置账号服务读取（登录凭据由应用自身管理，插件不接触、不保存任何 token）。
- 仅当回退到 API Key 时，才会向 api.deepseek.com 的 /user/balance 端点查询余额（且只在你主动刷新或对话完成时）。
- 检查更新只请求 registry.npmjs.org 上本包的版本号，不发送任何账户信息；就地更新只下载本插件自己的发布包。
- 节假日数据来自公开的国务院公告镜像（cdn.jsdelivr.net 上的 holiday-cn），只读取、不上报。
- 插件不收集、不上传任何会话内容到第三方。
- 消费统计完全基于本地会话事件（request/header、assistant/message 的 token usage）计算，不向 DeepSeek 之外的服务发送数据。

价格表（空闲时段价，元/百万 tokens）

| 模型 | 输入（缓存未命中） | 输入（缓存命中） | 输出 |
| deepseek-flash | 1 | 0.02 | 4 |
| deepseek-v4-pro | 4.5 | 0.15 | 13.5 |
| deepseek-chat（旧） | 2 | 0.5 | 3 |
| deepseek-reasoner（旧） | 4 | 1 | 16 |

价格自 2026-09-10 12:00（北京时间） 起生效（flash 系列由 1.5 / 0.05 / 4.5 下调）；高峰时段 = 空闲价 × 倍率（默认 2）。调价前的历史消耗仍按当时的旧价计算，不会被重算。

DeepSeek 再次调价时需同步更新 lib/index.js 的 MODEL_PRICING 与 lib/client.js 的 DEFAULT_PRICING，并把被替换的旧价移入 LEGACY_MODEL_PRICING。

常见问题

金额和官方页面上的不一致 正常。本插件算的是本地估算（按事件 token × 价表），官方账单还包含插件看不到的口径差异，见上面「使用统计口径」。要准确数字就点「查看官方用量」。

为什么调休上班的周末不算高峰？ 官方定价页原话是「其余时段，包括周末及中国法定节假日全天均为空闲时段」，没有为调休留例外。插件按这个口径实现。如果你有官方另有规定的证据，改 lib/index.js 的 isPeakAt 与 lib/client.js 的 currentPeriod（两处必须同口径）。

设置里改了刷新间隔，怎么没立刻生效？ 服务端项需要重启 DeepSeek Harness；纯界面项（开关、样式、圆钮尺寸）刷新页面就生效。

点了更新，但版本号没变？ 就地更新只是替换磁盘上的插件文件。Node 不会热替换已加载的模块，所以要重启 DeepSeek Harness 才会跑新代码。

关掉了侧边栏入口，怎么找回来？ 左上角「插件」→ balance-dsh → 上面那张卡片里重新打开「侧边栏显示本插件」。

License

MIT