前言¶
在 DeepSeek Harness Web 中开发智能体时，需要频繁打开 platform.deepseek.com/usage 查看余额、今日消费与 Token 使用情况。这不仅打断工作流，也无法直观看到峰谷价切换与实时用量趋势。DSH 的理念是「一切皆插件」，社区开发者因此定制了悬浮面板类插件，让用量观测融入工作流。
dsh-deepseek-usage-panel-c 是 WeiyangPro/dsh-deepseek-usage-panel 的定制分支，由 Zcc-777 维护。它沿用同一包名与 DSH 插件 ID，可直接替换原版并保留现有配置与数据目录。本分支新增峰谷价提示、今日消费金额与今日 Token 明细，其余功能（官方余额、Token 曲线、按模型统计等）与上游保持一致。
这是什么¶
DSH Web 悬浮用量面板 C 是一个运行在 dsh 进程侧的插件，通过轮询官方余额接口与监听 Harness 会话事件，在浏览器中渲染一个 macOS 风格毛玻璃用量面板。插件不注入浏览器，只读取本地配置的 API Key，在宿主进程完成网络请求，再将余额快照返回给前端展示。
它解决了「频繁打开官方 usage 页」的问题，提供胶囊与展开面板两种视图：胶囊显示当前余额、今日消费、峰谷价倒计时；展开面板展示今日消费明细、峰谷时段条、余额卡片、今日 Token 明细、近 24 小时曲线、按模型统计以及跳转到官方 usage 页的链接。
核心功能¶
官方余额轮询¶
插件按配置的轮询间隔（默认 300000 毫秒，最小 60000 毫秒）调用 DeepSeek 官方余额接口 GET /user/balance，只显示官方字段（当前余额、充值余额），不进行任何本地估算。
今日消费（余额观测口径）¶
胶囊显示余额观测口径的今日消费金额（格式为 ¥x.xx）。展开面板中保留今日 Token 明细，包括缓存命中输入、缓存未命中输入、输出（含推理）、合计，以及响应次数与缓存命中率。
峰谷价提示与倒计时¶
胶囊与展开窗显示当前「峰价 / 谷价」及距下次切换的倒计时。峰价时段为周一至周五 09:00–12:00、14:00–18:00，其余为谷价（谷价 5 折）。峰价显示为红色，谷价显示为绿色。插件内置 2026 年法定节假日表，节假日按官方价格页规则执行。
Token 用量曲线¶
提供四种口径的 Token 用量统计：今日、会话、近 24 小时平滑曲线（输入·输出，含缓存命中/未命中明细）以及按模型占比。曲线按小时桶聚合，会话为当前会话累计值（可跨天/多轮）。
交互与自动展开方向¶
胶囊与面板可拖动，位置自动记忆。点击胶囊或红绿灯、按下 ESC 可收起面板（带过渡动画）。面板根据胶囊位置自动选择展开方向。点击右上角的 ↻ 按钮可立即刷新数据（旋转动画 + 「已刷新」反馈）。
安装与启用¶
本分支与上游使用同一包名 dsh-deepseek-usage-panel，若已安装原版，建议先卸载再安装本分支，以避免冲突。
# 方式一：从本定制分支在线安装（推荐）
dsh plugin --profile web add "github:Zcc-777/dsh-deepseek-usage-panel-c"
# 方式二：从源码安装
dsh plugin --profile web add "link:/你的路径/dsh-deepseek-usage-panel-c"
安装完成后重启 dsh web 并硬刷新浏览器（Ctrl/Cmd + Shift + R）。若未自动加入 bundle，把 dsh-deepseek-usage-panel 追加到 profile 的 package.json 中 dsh.profile.bundles 字段。
API Key 配置¶
余额查询需要 DeepSeek API Key，插件在宿主进程读取配置，不注入浏览器。
在 ~/.dsh/.credentials.yaml 中配置：
version: 1
refs:
DEEPSEEK_API_KEY: "<你的 DeepSeek API Key>"
也可通过环境变量 DEEPSEEK_API_KEY 或 DSH_USAGE_HUD_API_KEY 提供。
不要把真实 Key 写入仓库或提交到 Git；只放在本机
~/.dsh/.credentials.yaml或环境变量里。
典型用法¶
安装并配置完成后，右下角会出现一个胶囊。胶囊显示当前余额、今日消费金额与峰谷价倒计时。拖动胶囊可改变位置，再次点击胶囊可展开面板。
展开面板后，可以看到：
- 今日消费金额与 Token 明细（缓存命中输入、缓存未命中输入、输出、合计、响应次数、缓存命中率）
- 峰谷时段条（红色为峰价，绿色为谷价，显示距下次切换的倒计时）
- 余额卡片（当前余额、充值余额）
- 今日 Token 明细与按小时聚合的近 24 小时曲线（输入·输出，含缓存命中/未命中明细）
- 按模型的 Token 占比
- 跳转到 platform.deepseek.com/usage 的链接
点击面板右上角的 ↻ 按钮可立即刷新数据，点击三个 MAC 圆点或按下 ESC 可收起面板。
配置项¶
在 profile 的 cordis.patch.yml 中按行 id 覆盖：
- id: usage-panel
config:
pollIntervalMs: 300000 # 余额轮询间隔（毫秒，最小 60000）
historyHours: 72 # 历史小时桶保留数
baseURL: https://api.deepseek.com # 覆盖接口地址
apiKeyRef: DEEPSEEK_API_KEY # 凭据引用名
dataDir: null # 覆盖数据目录（默认 $DSH_HOME/dsh-deepseek-usage-panel）
数据与隐私¶
- API Key 仅存在于宿主（Node）进程，浏览器只收到解析后的余额快照。
- 用量历史写入数据目录
state.json（原子写入、自动裁剪），更换安装方式会自动迁移旧数据。 - 网络请求：每轮询周期一次官方余额接口；无其它外发流量。
数据口径说明¶
「今日 / 近 24 小时 / 按模型 / 会话」的 Token 数据是插件对 Harness 会话的本地测量，不是 DeepSeek 平台的官方账目，因此可能与 platform.deepseek.com/usage 的数字存在差异。
主要原因：
1. 观测窗口：插件从「它运行起来之后的时刻」开始统计；当天若安装较晚、中途重装/重启过 dsh web，在这些时间点之前产生的请求本地拿不到（DeepSeek 未提供官方用量 API，无法补齐）。
2. 口径单条一致：每条响应使用 DeepSeek 返回的 usage（未命中输入 + 缓存命中输入 + 输出含推理），与官方计费同源；所以单条记录的 token 计算是准的，偏差主要来自「统计时间窗口不完整」。
3. 模型占比可能失真：如果某段时间未被插件覆盖，而那段恰好以某个模型/缓存命中为主，会让「按模型」占比与实际全天不同。
4. 「会话」≠「今日」：会话是当前会话的累计值（可跨天/多轮），不是自然日口径。
5. 按本地时区零点切分「今日」：若你与官方账单的时区口径不同，临近午夜会差一截。
结论：数字可信的方向是「相对趋势/构成」，绝对总量请以官方 usage 页为准。后续版本计划加入「统计自插件启用时间 / 完整性提示 / 手动重置」，让口径更透明。
适用场景与注意¶
本插件适合频繁使用 DeepSeek Harness Web 进行智能体开发的用户，希望在不离开工作流的情况下实时观测余额、今日消费与 Token 使用情况。对于需要精确账单核对的用户，建议仍以 platform.deepseek.com/usage 为准。
插件以 dsh 进程的权限运行，安装前应检查源码与许可证。本插件基于 MIT License，源码位于 GitHub。
结尾¶
DSH Web 悬浮用量面板 C 通过本地测量与官方接口轮询，在浏览器中提供了一个轻量级的用量观测入口。它保留了原版的所有核心能力，并在此基础上增加了峰谷价提示与今日消费金额，让用量观测更贴近实际计费场景。若你在使用中遇到数据差异，可按「统计窗口不完整」理解，而非视为错误。
