philmingdao/dsh-meter

dsh-meter

DeepSeek 用量与余额计量插件 — 在 DSH（DeepSeek Harness）桌面端的设置菜单中展示 DeepSeek 开放平台的账户余额与使用量，并支持配置 API Key 与平台 Token。

DSH 插件（#dsh-plugin），基于 DSH 动态 Cordis 插件机制（cordis_define + cordis_run）开发，分为 Host / Client 两个半区。

功能

- 账户余额：调用 https://api.deepseek.com/user/balance，展示充值余额、赠送余额与可用状态（多币种账户自动汇总）。
- 今日用量：配置平台 Token 后展示官方统计（今日 / 本月消费）；未配置 Token 时自动降级为余额变化估算。
- 用量热力图：按日 / 按周两种视图的日历热力图（GitHub contributions 风格）：
- 按日：以周为列、周一至周日为行，每格一天，颜色深浅表示当日消耗金额；
- 按周：每周一格，聚合当周消耗；
- hover 悬浮提示：显示日期 / 周范围、消耗金额、Token 总量（输入 / 输出，含缓存命中明细）。
- 数据来自平台官方接口（近 12 个月，按月拉取、内存缓存 5 分钟）。
- 凭据管理：页面内直接保存 / 清除 API Key 与平台 Token（存储于 DSH 凭据服务）。
- 自动刷新：每 5 分钟自动刷新，设置菜单项实时显示余额摘要（如 DeepSeek 用量 · ¥12.34）。

工作原理

| 半区 | 文件 | 职责 |
| --- | --- | --- |
| Host | host.js | 解析凭据（credentials）、通过 shell 服务 curl 调用 DeepSeek 接口、注册 6 个 RPC handler（dsusage.overview / range / setKey / clearKey / setToken / clearToken） |
| Client | client.js | 通过 slots 注册设置页 settings.section（deepseek-usage），渲染余额卡片、用量卡片与按日/按周热力图，定时刷新 |

Client (React UI)    Host (RPC handlers)  --curl-->  DeepSeek API / Platform

数据接口

| 接口 | 用途 |
| --- | --- |
| https://api.deepseek.com/user/balance | 账户余额（API Key） |
| https://platform.deepseek.com/api/v0/usage/cost?month=&year= | 每日消耗金额（平台 Token） |
| https://platform.deepseek.com/api/v0/usage/amount?month=&year= | 每日 Token 用量（PROMPT_TOKEN / PROMPT_CACHE_HIT_TOKEN / PROMPT_CACHE_MISS_TOKEN / RESPONSE_TOKEN） |

dsusage.range 按近 12 个月逐月拉取 cost + amount，合并为连续的每日序列；未配置平台 Token 时返回明确提示。

配置

密钥优先级：DEEPSEEK_USAGE_KEY（自定义） → DEEPSEEK_API_KEY（DSH 已配置）。

| 变量 | 必填 | 说明 |
| --- | --- | --- |
| DEEPSEEK_API_KEY | 余额必需 | DSH 环境中已有的 Key，用于余额接口 |
| DEEPSEEK_USAGE_KEY | 可选 | 自定义 Key，优先级更高，覆盖 DSH 配置 |
| DEEPSEEK_PLATFORM_TOKEN | 官方用量可选 | platform.deepseek.com 的 userToken，用于官方用量统计 |

获取平台 Token：浏览器登录 platform.deepseek.com → 开发者工具 → Application → Local Storage → https://platform.deepseek.com → 复制 userToken 的值。

安装 / 运行

方式 A：动态插件（会话级）

在 DSH Desktop 会话中说：

读取本仓库的 host.js 和 client.js，用 cordis_define + cordis_run 重建 DeepSeek 用量与余额插件（插件名 dsqu-1，idPrefix dsqu）。

方式 B：持久化插件

将本插件注册到 desktop profile（cordis.patch.yml），每次启动 DSH Desktop 自动加载。

文件

dsh-meter/
├── host.js      # Host 半区：凭据解析、curl 请求、RPC handlers（含按月批量拉取）
├── client.js    # Client 半区：设置菜单页面 UI、按日/按周热力图、自动刷新
└── define.json  # 完整的 cordis_define 定义（由 host.js/client.js 生成，可直接重新提交）

许可证

MIT