haifeiWu/dsh-deepseek-usage

dsh-deepseek-usage

dsh-deepseek-usage 是一个 DSH 插件，可在 DSH Web UI 中实时显示 DeepSeek API 的 token 消耗、估算花费与账户余额（位于输入框工具行旁边的钱包按钮）。

- 按会话的 token 明细（输入未缓存 / 缓存命中 / 缓存写入 / 输出）及估算花费
- 今日按模型统计与近 7 天总计，支持按模型配置计价（默认使用 DeepSeek 官方价格）
- 通过官方 GET /user/balance API 获取账户余额 —— API key 永不离开进程
- 两种计费模式：🟢 官方平台控制台数据（DEEPSEEK_PLATFORM_TOKEN）或 ⚪ DSH 侧估算 —— 当平台 token 缺失或过期时自动回退

以下为中文文档 / 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//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:

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。