dsh-usage-footer：DSH Web 用量与费用监控插件

在 DSH（DeepSeek Harness）生态中，一切皆插件。对于开发者而言，实时掌握 Token 消耗与费用是日常开发中的刚需。现有的官方账单往往存在延迟或层级较深，难以快速查阅。dsh-usage-footer 插件旨在为 DSH Web 界面提供一个轻量级的监控入口，将用量统计、费用估算与峰谷时段信息浓缩于右下角的悬浮面板中。

插件简介¶

这是一个为 DeepSeek Harness Web 界面设计的用量与费用监控插件。插件在页面右下角提供一个金币样式的悬浮按钮，悬停或点击即可展开用量面板，支持查看账户余额、峰谷时段、本会话 token 统计、今日消费估算以及本地账本与官方数据的对比。同时，它在设置中提供了一键开关。由 1514100951 维护，遵循 MIT 许可证。

核心功能¶

悬浮按钮与状态指示：页面右下角显示一枚金币徽标圆钮。外环与角点颜色指示当前时段：绿色为空闲，琥珀色为高峰（伴随呼吸动画），红色表示余额查询失败。
悬停弹窗：鼠标悬停触发弹窗，延迟 120ms 出现，宽容关闭时间 260ms。内容包括：
- 账户余额：来自官方 API GET https://api.deepseek.com/user/balance，每 60 秒刷新，含充值与赠送拆分。
- 峰谷时段：按北京时间实时判定，展示 24 小时峰谷条（高峰时段为 9:00-12:00 / 14:00-18:00）。
- 本会话用量：累计 token 与输入（未缓存）、缓存命中、缓存写入、输出四项分条显示。
- 本地账本：按 DeepSeek 官方价格表记录今日/本月 token 与金额，仅记录插件启用后的用量。
- 官方对比：配置 DEEPSEEK_PLATFORM_TOKEN 后，并排显示本地账本与 platform.deepseek.com 官方汇总。
- 今日消费估算：通过余额快照差值估算，仅作兜底。
- 本机今日用量：按会话去重累计，非官方账单。
- 本月用量/费用：优先显示官方平台汇总，否则显示本地账本汇总。
设置开关：在 DSH 的「设置 → 通用」中提供「用量与费用栏」开关，实时生效。关闭后停止轮询并返回 { disabled: true }。
视觉适配：面板采用毛玻璃效果，使用宿主的 --dsw-* 设计令牌，自动适配明暗主题。

安装与前置条件¶

环境要求¶

DSH 版本：>=0.1.0-rc.8 <0.2.0
Node.js 版本：>=20 <27

安装命令¶

dsh plugin --profile web add github:1514100951/dsh-usage-footer

安装后需重启进程并运行 dsh web。

前置凭证配置¶

必须配置 DEEPSEEK_API_KEY：用于获取账户余额数据。
可选配置 DEEPSEEK_PLATFORM_TOKEN：用于获取官方平台汇总数据，便于与本地账本对比。

功能说明与限制¶

本地账本存储：本地账本数据持久化在 $DSH_HOME/storages/usage-footer-ledger.json，但仅记录插件启用后的用量，不追溯历史。
消费估算逻辑：今日消费估算采用“当日首次查询余额快照 − 当前余额”的方式，仅作兜底，受充值、赠送和余额结算延迟干扰。
本机统计：本机今日用量统计为非官方数据，存储在 localStorage（键名为 dsh-usage-footer.today.v1），每日清零，按会话去重累计。
安全与网络限制：GET /usage-status 接口仅绑定 127.0.0.1，路由内校验回环，局域网访问会被拒绝。插件仅访问 api.deepseek.com 与（可选的）platform.deepseek.com。

该插件通过 Bundle Patch 方式注册，不替换、不遮蔽、不禁用任何官方组件。