dsh-deepseek-usage

dsh-deepseek-usage is a DSH plugin that shows real-time DeepSeek API token usage, estimated cost, and account balance right in the DSH Web UI (wallet button next to the composer tool row).

• Per-session token breakdown (input uncached / cache-hit / cache-write / output) with estimated cost
• Today-by-model and last-7-days totals, with configurable per-model pricing (official DeepSeek prices by default)
• Account balance via the official GET /user/balance API — the API key never leaves the process
• Two accounting modes: 🟢 official platform console figures (DEEPSEEK_PLATFORM_TOKEN) or ⚪ DSH-side estimation — automatic fallback when the platform token is absent or expired

---

以下为中文文档 / Chinese documentation below:

DSH 插件：在 DSH Web 界面实时显示 DeepSeek API 的 token 消耗、估算花费 与 账户剩余金额。

• 按钮位置：输入框工具行右端，与「上下文」按钮同一行（模型选择器左侧），图标为钱包。
• UI 风格参考上下文组件：图标为主、文字从简（会话/今日/近 7 天/余额均为图标 + 短标题，数字为 tabular 主色）；模型名显示简称（deepseek-v4-flash → v4-flash，deepseek-v4-pro → v4-pro），完整模型名以 title 提示显示。
• 点击按钮弹出面板：
  • 本会话 token 分桶明细（输入未命中 / 缓存命中 / 缓存写入 / 输出）与估算费用
  • 今日消费（分模型） 与 近 7 天总消费
  • 账户余额（总余额 / 赠金 / 充值）、更新时间、手动刷新
• 「今日 / 近 7 天」金额两种口径，标题旁小圆点指示：
  • 🟢 官方口径：配置了 DEEPSEEK_PLATFORM_TOKEN 后，直接读取平台控制台用量接口，与官方账单一致（含非 DSH 的 API 消耗；官方接口不提供分模型，分模型行仍为 DSH 内估算）。
  • ⚪ 估算口径：未配置 token 时，按 DSH 会话日志 + 计价表估算（仅覆盖 DSH 内的消耗，数值会低于官方账单）。
• 数据来源：
  • 本会话 token 消耗：DSH 自带的 tokenUsage session projection（dsh-token-meter，实时推送、压缩安全）。
  • 今日 / 分模型 / 近 7 天：本插件注册 usageByModel projection 单元，按「日期 → 模型」折叠每个会话的 usage（重放/压缩安全），经变更流实时汇入全局存储；启动时从持久化会话日志全量回填历史。
  • 估算花费：每模型按其计价条目计算（计价表可配置，默认官方价）。
  • 账户余额：官方 GET https://api.deepseek.com/user/balance，服务端经 DEEPSEEK_API_KEY 凭据定时（默认 60s）拉取；API Key 不出进程。
  • 官方口径消费：平台控制台内部接口 GET https://platform.deepseek.com/api/v0/usage/cost?month=&year=（返回与官方账单一致的按日消耗），服务端经 DEEPSEEK_PLATFORM_TOKEN 凭据定时拉取；token 不出进程，未配置时自动回退估算口径。
  • 全局用量存储：$DSH_HOME/deepseek-usage/usage-store.json（防抖写盘，损坏自动回退空存储）。

安装

1. 构建：pnpm install && pnpm build

2. 挂载（web profile）：

   ~/.dsh/profiles/web/package.json：

   {
     "dependencies": {
       "dsh-deepseek-usage": "file:/Users/<you>/work/opensource/dsh-deepseek-usage"
     },
     "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deepseek-usage"] } }
   }
   

3. 在 profile 目录执行 pnpm install，重启 dsh web。

配置

键	默认	说明
balanceUrl	https://api.deepseek.com/user/balance	余额接口地址
refreshIntervalMs	60000	余额轮询间隔（毫秒）
apiKeyRef	DEEPSEEK_API_KEY	凭据引用（~/.dsh/.credentials.yaml / 环境变量）
prices	官方价（见下）	按模型 key 的计价表（每百万 tokens 人民币）
defaultPriceKey	deepseek-v4-flash	未匹配模型的兜底计价 key
storePath	$DSH_HOME/deepseek-usage/usage-store.json	全局用量存储文件
platformTokenRef	DEEPSEEK_PLATFORM_TOKEN	平台 session token 凭据引用；配置后「今日 / 近 7 天」显示官方口径金额

默认计价（DeepSeek 官方 2026-08 现行价，每百万 tokens）：

模型	输入（缓存命中）	输入（未命中）	输出
deepseek-v4-flash	¥0.02	¥1	¥2
deepseek-v4-pro	¥0.025	¥3	¥6

官方口径（可选）：获取 DEEPSEEK_PLATFORM_TOKEN

官方没有公开的用量查询 API，但平台控制台（platform.deepseek.com）登录后有一个内部用量接口，可用于查询按日消耗。取 token：

1. 浏览器登录 https://platform.deepseek.com
2. 打开 DevTools → Console，执行：JSON.parse(localStorage.getItem('userToken')).value
3. 把输出的字符串存为凭据（~/.dsh/.credentials.yaml 或环境变量）：

DEEPSEEK_PLATFORM_TOKEN: <token>

4. 重启 dsh web。面板「今日 / 近 7 天」标题旁的小圆点变绿即官方口径；token 过期时显示错误提示并自动回退估算。

注意：官方将于 2026-08-17 起改为峰谷定价（高峰 9:00-12:00、14:00-18:00，空闲时段半价）。插件按单一价目估算；届时可通过 prices 配置覆盖。

开发

• pnpm typecheck / pnpm test（vitest：计价、余额解析、用量折叠、聚合与持久化单测）
• pnpm build：tsc 编译服务端 → lib/，并复制手写客户端 bundle client/client.js → lib/client.js
• 客户端 bundle 为 loader-CJS 格式（window.__ModuleLoader__.load），零构建依赖，改 client/client.js 后重跑 pnpm build 并在 profile 重新 pnpm install、重启 dsh web。