前言¶
在 DSH 里跑 DeepSeek 模型时，账户里还剩多少钱、最近几天 token 和费用大概多少，通常要切到浏览器打开 platform.deepseek.com 才能看。官方 API 只暴露余额接口，没有对外可用的用量 API；平台用量页又依赖浏览器登录态，没法直接用 API Key 拉全量账单。
下面介绍社区插件 dsh-deepseek-usage：在 DSH Web 侧栏底部（Settings 行上方）显示 DeepSeek 余额，点开弹出层可看余额明细、基于本机 DSH 会话日志汇总的图表，以及按模型拆分的费用表。余额来自官方接口；用量与费用为本地估算，插件在界面中会标明范围与局限。
这是什么¶
dsh-deepseek-usage 由 The-five-stooges 维护，分类为客户端插件（dsh.client.platform: web）。它在 DSH shell 主题 token 下渲染，浅色与深色主题均可使用。
一句话定位：侧栏一行余额 + 刷新，点击后弹出余额卡片、7/30 日 token 折线图与估算费用柱状图、分模型表格，并提供跳转官方用量页的链接。
核心功能¶
侧栏底部一行¶
- 文案形如
DeepSeek 余额 ¥85.66，带刷新按钮。 - 侧栏收起到 56px 轨道时，仅显示图标，数字放在 tooltip 中。
弹出层内容¶
| 区域 | 内容 |
|---|---|
| 余额卡片 | 总额、充值、赠送、币种、可用性、数据时间、来源等 |
| 图表 | 按日 token 折线图；按日估算费用柱状图（7 天或 30 天窗口） |
| 表格 | 按模型拆分的用量与费用 |
| 操作 | 打开 platform.deepseek.com/usage 的按钮（无法内嵌 iframe，见下文限制） |
数字从哪里来¶
| 指标 | 来源 | 是否权威 |
|---|---|---|
| 余额 | GET https://api.deepseek.com/user/balance，服务端请求，缓存 60 秒 |
是，官方端点 |
| 用量 / 费用 | 本机 DSH 会话日志（assistant/message、assistant/attempt 中的 usage），按官方峰谷价目表计价 |
否，本地估算 |
DeepSeek 未提供公开用量 API：api.deepseek.com 仅暴露 /user/balance；平台用量页需要浏览器登录 token，而非 API Key。插件在面板上说明估算范围；更细的来源说明见仓库 docs/usage-data-sources.md。
安全与密钥¶
API Key 不会进入浏览器 bundle。密钥通过宿主 credential store 按操作解析，仅用于向 api.deepseek.com 发送 Authorization 头。未配置密钥时，侧栏显示明确的「未配置」状态，而不是直接报错崩溃。
安装与启用¶
插件以 npm 包形式接入 DSH profile，dsh plugin 会转发到 profile 目录内的 pnpm 并 reconcile dsh.profile.bundles；包内声明了 dsh.bundle，无需本地 build（lib/client.js、lib/index.js 已提交为生成物，无 prepare 脚本，git 安装一般不需要 allowBuilds）。
方式一：GitHub 源
dsh plugin add github:The-five-stooges/dsh-deepseek-usage
方式二：Release 预构建包
dsh plugin add https://github.com/The-five-stooges/dsh-deepseek-usage/releases/latest/download/dsh-deepseek-usage.tgz
安装后需重启宿主进程一次（host 半端在启动时组装），再刷新页面。
在 harness credential store 或启动环境中配置 DEEPSEEK_API_KEY；无密钥时仅显示未配置状态。
引擎要求：dsh >= 0.1.5-rc.1（见 package.json dsh.engines）。
可选配置¶
在 profile 插件条目中可写：
- id: dsh-deepseek-usage
config:
timeoutMs: 10000 # 上游余额请求超时，默认 10000
ttlMs: 60000 # 成功快照缓存 TTL，默认 60000；force=1 可 bypass
典型用法与 HTTP 接口¶
Host 半端在当前 session 同源上提供路由，便于前端拉余额与用量汇总。
| 路由 | 成功时 | 失败时 |
|---|---|---|
GET /api/dsh-deepseek-usage/balance[?force=1] |
{ ok:true, currency, totalBalance, grantedBalance, toppedUpBalance, isAvailable, fetchedAt, cached } |
{ ok:false, error:{ code, message, httpStatus? } } |
GET /api/dsh-deepseek-usage/usage[?days=N] |
{ ok:true, requestedDays, days, generatedAt, truncated, totals } |
同上 envelope |
GET /api/dsh-deepseek-usage/health（别名 /healthz） |
插件名、版本、ledger 可用性 | — |
侧栏刷新会触发余额拉取；force=1 可跳过成功缓存。弹出层图表通过 usage?days=N 拉取本地聚合结果。响应形状以仓库 tests/contract.test.mjs 为准。
日常操作无需直接调 API：安装并配置密钥后，在侧栏看余额、点行打开弹出层即可。
适用场景与注意¶
适合谁
- 主要在本机 DSH 里用 DeepSeek，希望在 IDE 内快速看官方余额。
- 需要参考本机会话日志上的 token 趋势与按官方价目表估算的费用，而不是替代平台发票。
务必知晓的限制
- 估算只覆盖本机 DSH 会话日志（含本机所有 workspace）。同一账户在其他电脑、Web UI 或其他工具上的消费不会出现在这里，数字可能低于平台账单。README 中给出了实测对比示例（部分记录时段 vs 完整记录日）。
- 不能内嵌官方用量页：
platform.deepseek.com/usage的 CSP 为frame-ancestors 'none'，弹出层只能外链打开。 - 柱状图费用为价目表估算，平台账单仍为最终依据。
- 插件在 当前 dsh 进程权限下运行，会读会话日志并代你请求余额接口。安装前请自行查看 GitHub 源码 与 MIT 许可证；插件与 DeepSeek 无隶属关系。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-deepseek-usage 把官方余额接到侧栏，并把本机 DSH 用量做成可读的图表与分模型表，在「没有用量 API」的前提下补一层本地视角。若你的消费几乎都在本机 DSH 完成，估算与账单会更接近；若多入口共用同一 API Key，请以平台用量页与发票为准。
