前言¶
DeepSeek Harness（DSH）为本地 LLM 开发提供了运行环境，但开发者在使用过程中需要实时掌握模型调用的成本与用量。dsh-token-usage-panel 插件在 DSH 对话区下方提供了一个状态条和明细面板，用于展示逐次调用的 token 与花费、峰谷计价信息、余额查询以及日历热力图。
核心功能¶
状态条¶
状态条固定在输入卡下方，用于展示核心数据。无论屏幕宽度如何变化，会话、今日、余额三项始终常驻。当空间不足时，次要数字会被压缩，峰谷倒计时在任何档位下都保持完整显示。
状态条示例：
会话 ¥0.561 · 15.9M 今日 ¥0.561 · 15.9M ............ 余额 ¥3.44 谷价 · 21h02m 明细 ▴
点击“明细”按钮会在输入卡上方展开一个面板，包含四个页签：
- 逐次调用：展示每一次模型调用的详情，包括时间、模型、未命中/缓存命中/输出 token、峰谷时段及花费。支持按本会话、今日、近 30 天或全部切换，并附合计行与分页加载。
- 日历热力图：提供 13/26/39/53 周的滚动格子，按当日花费分色。鼠标悬停可查看日期、花费、调用次数及 token 数量。
- 余额：显示充值余额、赠送余额及最近观测时间。支持手动刷新，并提供“今日余额实扣”与“今日表价估算”的对比。
- 设置：配置状态条开关、热力图默认周数、缓存写入计价口径、余额刷新间隔、单价表、峰时段及法定节假日。
峰谷计价¶
插件支持峰谷计价功能。默认规则如下：
* 峰时段：工作日 09:00-12:00 和 14:00-18:00（北京时间）。
* 谷时段：其余时段，包括周末全天与中国法定节假日全天。
* 单价表：默认从本地已装的 dsh-whale-widget 读取，也可在设置中手动维护。
数据持久化¶
所有用量数据会持久化存储至 $DSH_HOME/usage-panel/ledger.json，账本默认保留 400 天，上限 5 万条。
HTTP 路由¶
插件提供了只读的 HTTP 路由，可用于排查数据来源：
* GET /dsh-usage-panel/snapshot.json?sessionId=：获取状态条所需的所有数据。
* GET /dsh-usage-panel/calls.json?scope=&sessionId=&limit=&offset=：获取逐次调用明细。
* GET /dsh-usage-panel/heatmap.json?weeks=：获取日历热力图数据。
* GET/POST /dsh-usage-panel/config.json：读取或修改配置。
* GET/POST /dsh-usage-panel/balance.json：读取或强制刷新余额。
安装与启用¶
使用 DSH CLI 进行安装：
dsh plugin --profile desktop add dsh-token-usage-panel
如果需要进行本地开发或修改代码即时生效，可使用 link 安装方式：
dsh plugin --profile desktop add link:<本目录绝对路径>
安装后，可在 设置 → 插件 中开关该插件。关闭后状态条会立即消失，但已有的账本数据会保留。
注意事项¶
- 估算 ≠ 账单：面板显示的表价估算受缓存命中判定、赠送额度及优惠活动影响，不替代平台官方账单。
- 余额可用性：余额功能仅在账号登录模式下可用。使用 API Key 直连时，账号服务返回空，面板将显示不可用。
- 历史数据：账本只从插件安装之后开始记录，不会回填历史数据。
- 契约依赖：插件依赖未公开的 DSH 契约（如
__ModuleLoader__、slot props 等），DSH 升级后若失效需要配合修复。 - 节假日维护：节假日表默认内置 2026 年数据，次年公布后需在设置中手动补充。
- 数据来源：余额观测值仅在有余额可读且面板打开时存在。
许可证¶
MIT
