DeepSeek Harness Web 悬浮用量面板插件

在 DeepSeek Harness (DSH) 的 Web 环境下，开发者需要频繁切换标签页查看余额和 Token 消耗。dsh-deepseek-usage-panel 提供了一个 macOS 风格的悬浮用量面板，将实时官方余额和本地测量的 Token 用量数据集成到界面中，无需打开 platform.deepseek.com/usage。

插件定位¶

这是一个由 WeiyangPro 维护的客户端插件，基于 MIT 许可证开源。它为 DSH Web 界面增加了毛玻璃效果的 UI 组件，用于展示官方余额快照以及基于本地测量的 Token 消耗趋势。

核心功能¶

官方余额：通过轮询 GET /user/balance 接口获取数据，只展示官方返回的余额字段，确保数据源的一致性。
Token 用量统计：提供今日、当前会话、近 24 小时的平滑曲线图。统计维度包括输入 Token、输出 Token，并包含缓存命中/未命中的明细，以及按模型占比的分布。
交互设计：
- 胶囊与面板：右下角显示胶囊，支持拖动至任意位置，位置自动记忆。
- 展开与收起：点击胶囊展开面板，支持点击面板任意位置、红绿灯图标或按 ESC 键收起，带过渡动画。
- 自动方向：面板展开方向会根据胶囊位置自动选择（向上或向下）。
- 刷新：右上角提供刷新按钮，点击后图标旋转并反馈“已刷新”状态。

安装与启用¶

安装插件需要在终端执行以下命令。安装完成后，重启 dsh web 并对浏览器进行硬刷新（Ctrl/Cmd + Shift + R）。

dsh plugin --profile web add dsh-deepseek-usage-panel

配置 API Key¶

插件需要访问 DeepSeek API 以获取余额信息。API Key 仅存储在宿主 Node 进程中，不会注入浏览器，安全性较高。请在 ~/.dsh/.credentials.yaml 中配置：

version: 1
refs:
  DEEPSEEK_API_KEY: sk-你的key

也可以通过环境变量 DEEPSEEK_API_KEY 或 DSH_USAGE_HUD_API_KEY 设置。

典型用法¶

查看状态：右下角的胶囊会实时显示当前余额、今日用量和会话用量。胶囊位置可拖动，下次打开会自动恢复。
展开面板：点击胶囊，面板展开，展示余额卡片、24 小时曲线图、模型占比统计以及跳转官方 usage 页的链接。
操作控制：点击面板空白处或按下 ESC 键收起面板；点击右上角的刷新箭头立即更新数据。

配置项¶

在 DSH profile 的 cordis.patch.yml 文件中，可以通过覆盖 id: usage-panel 的配置来调整插件行为：

- 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）进程，浏览器仅接收解析后的余额快照。历史 Token 数据保存在本地数据目录的 state.json 中，支持原子写入和自动裁剪。
数据口径说明：
- 今日 / 近 24 小时 / 按模型 / 会话 的 Token 数据是本地测量值，不是 DeepSeek 平台的官方账目。
- 由于插件从“运行时刻”开始统计，若安装较晚或中途重启，安装前产生的请求无法被统计，因此“今日”或“近 24 小时”的数据可能偏小于官方全天金额。
- 单条记录的 Token 计算与官方计费同源，但整体总量可能因观测窗口不完整而偏差。
- “会话”为当前会话累计值，不等于自然日口径。
- 建议关注数据的相对趋势和构成，绝对总量请以官方 usage 页为准。

许可证与生态¶

许可证：MIT。
Node 版本：>= 20。
生态：该插件属于 DeepSeek Harness 插件生态的一部分，社区目录由独立站点维护，与 DeepSeek 或幻方无官方从属关系。

项目地址：GitHub - WeiyangPro/dsh-deepseek-usage-panel