余额用量面板 The-five-stooges/dsh-deepseek-usage

dsh-deepseek-usage

一个 DSH Web 插件：把 DeepSeek 账户余额显示在侧边栏脚部、设置行上方，并带一个刷新按钮。
点击该行会打开弹出层，内含余额卡、本地聚合的用量图表、按模型明细表，以及指向 platform.deepseek.com/usage 的链接。

所有元素都使用 shell 自身的主题令牌渲染，因此浅色与深色主题都正常。

| 侧边栏脚部 | 弹出层 |
| 一行：DeepSeek 余额 ¥85.66 + 刷新按钮。折叠成 56px 轨道时退化为图标，数字显示在其 Tooltip 里。 | 余额卡（总余额 / 充值余额 / 赠送余额 / 币种 / 账户状态 / 数据时间 / 数据来源）、7/30 天窗口的每日 Token 折线图与每日估算费用柱状图、按模型明细表，以及「打开用量页」按钮。 |

显示什么，以及数字从哪来

| 数字 | 来源 | 是否为权威值 |
| 余额 | GET https://api.deepseek.com/user/balance，在宿主侧请求，缓存 60 秒 | 是——这是官方接口 |
| 用量 / 费用 | 由本机 DSH 会话日志（assistant/message 与 assistant/attempt 的 usage）聚合，按官方峰谷单价表计价 | 否——这是本地估算值 |

用量一侧被明确标注为估算值，且面板上写明了它的统计范围，原因是 DeepSeek 并未提供用量 API： api.deepseek.com 只暴露了一个账户接口（/user/balance），而平台自身的用量接口需要浏览器登录令牌，API key 无法代替。该结论背后的实测记录见 docs/usage-data-sources.md。

安装前有两点值得了解：

- 估算只覆盖本机的 DSH 会话日志（本机所有工作区）。同一账号在其它电脑、网页版或任何其它工具产生的消耗都不会被计入，因此这里的数字可能低于平台账单。这一点已写在面板本身上。实测例子：某天会话日志从当地时间 15:05 才开始，估算 ¥5.02，而平台账单为 ¥13.60；另一天日志完整，估算 ¥30.55，平台 ¥31.28。
- API key 全程不会进入浏览器。 key 每次操作都通过宿主的凭据库解析，且只用于发往 api.deepseek.com 的 Authorization 请求头。浏览器半的代码里既没有密钥，也不含上游域名（由 tests/ui-row.test.mjs 断言）。

安装

dsh plugin add github:The-five-stooges/dsh-deepseek-usage

dsh plugin 会在 profile 目录内转发给 pnpm，随后对齐 dsh.profile.bundles；本包因为声明了 dsh.bundle 而被识别为插件层。

没有构建步骤：lib/client.js 与 lib/index.js 都是已提交的生成产物，且本包没有声明 prepare 脚本。因此从 git 源码安装不需要 allowBuilds 授权——pnpm 的构建脚本闸门没有东西可拦。

装好后需要重启一次宿主进程（宿主半在启动期合成），然后刷新页面。

每次发布都附带预构建 tarball，也可以直接用它安装：

dsh plugin add https://github.com/The-five-stooges/dsh-deepseek-usage/releases/latest/download/dsh-deepseek-usage.tgz

需要凭据库（或启动环境）里存在 DEEPSEEK_API_KEY。未配置 key 时，该行会显示明确的「未配置」状态，而不是报错。

可选配置

- id: dsh-deepseek-usage
config:
timeoutMs: 10000 # 上游余额请求超时（默认 10000） ttlMs: 60000 # 成功快照缓存 TTL（默认 60000；force=1 绕过）

HTTP 接口

两条路由都由宿主半在会话自身的 origin 上提供：

| 路由 | 成功响应 | 失败响应 |
| 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） | 插件名、版本、台账可用性 | — |

tests/contract.test.mjs 是这些响应形状的唯一事实来源；改响应就要同时改它。

已知限制

- 用量估算会漏掉一切未经过本机 DSH 会话日志的调用（见上文）——这是它与平台账单可能不一致的主要原因。
- 插件无法内嵌 platform.deepseek.com/usage：该页面会发送 Content-Security-Policy: frame-ancestors 'none'，因此弹出层改为外链打开。
- 柱状图显示的是依据公开单价表推算的估算费用，平台账单始终为权威。
- 引擎版本下限：dsh >= 0.1.5-rc.1。

开发

架构、冻结的内部契约、浏览器包如何由 src/client/*.mjs 合成、验收文档，以及如何跑测试套件（222 个测试）见 DEVELOPMENT.md。

lib/ 生成的浏览器半 + 宿主入口 src/host/ 余额读取、会话日志台账、路由、cordis 插件 src/client/ row、service、chart、modal —— 合成进 lib/client.js tests/ contract、host 与 UI 测试套件 tools/ UI 套件驱动的真实浏览器布局探针 docs/ 验收记录与实测设计说明

node --test # 全量测试
node scripts/compose-client.mjs --check # lib/client.js 是否与 src/client 同步

许可证

MIT —— 见 LICENSE。本项目与 DeepSeek 官方无隶属关系。