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.call-->  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