会话余额监控lmmzss-jk/dsh-plugin-balance

dsh-plugin-balance

DeepSeek Harness Web 插件：会话头部余额按钮（位于原生 Session log 按钮左侧），
点击下拉查看 账户余额、当前会话的模型与实时 token 用量、以及按 DeepSeek 官方价目表
计算的费用估算。

功能

- 会话头部按钮：跟随会话头部布局，位于 Session log 左侧，加载后直接显示余额（如 ¥558.42）
- 点击下拉，两个区块：
- 当前会话（实时）：使用的模型、输入·未命中缓存 / 输入·命中缓存 / 缓存写入 / 输出
四项 token 明细、缓存命中率（含进度条）、按官方价目表计算的本会话费用
- 账户余额：总余额、充值余额、赠送余额、账户可用状态、更新时间，附 DeepSeek 平台链接
- 实时更新：token 用量订阅 token-meter 的 session projection，模型回答流式过程中数字实时增长
- 价格自动同步：宿主端每 6 小时以 ETag 条件请求同步
官方定价页，自动提取峰谷价与生效日期；
未联网时回退内置价目表；客户端打开面板时拉取最新价并本地缓存 12 小时
- 峰谷自适应：按北京时间自动判断高峰（9:00-12:00、14:00-18:00）/空闲时段，
并随官方调价公告的生效日期自动切换新旧价目
- 自动隐藏：打开「设置」页面时按钮自动隐藏，关闭设置后恢复
- 零配置：复用 DSH 已配置的 DEEPSEEK_API_KEY（设置 → 模型，或 ~/.dsh/.credentials.yaml）
- 状态提示：余额较低（ 插件复用 DSH 现有配置：先确保已在「设置 → 模型」中配置好 DeepSeek API Key。

卸载

dsh plugin --profile web remove dsh-plugin-balance

工作原理

- 宿主端（lib/index.js）：
- GET /api/dsh-balance：读取凭证服务中的 DEEPSEEK_API_KEY（或环境变量兜底），代理请求
https://api.deepseek.com/user/balance（遵循 DEEPSEEK_BASE_URL 覆盖），返回脱敏 JSON——
API Key 不会暴露到浏览器；
- GET /api/dsh-pricing：每 6 小时以 ETag 条件请求同步官方定价页，解析峰谷价/旧价/生效日期/
高峰窗口，失败时保留上次价格。
- 客户端（lib/client.js）：以 dsh.client 双面包加载，注册到
conversation.session.header.utilities 槽位（order: -10，位于 Session log 左侧）。
- token 明细：useProjection("tokenUsage") 订阅 token-meter 的会话投影，实时更新；
- 模型：session.models RPC 读取当前会话的 provider/model；
- 费用：按官方价目表 × token 用量计算（命中×命中价 + 未命中×未命中价 + 输出×输出价）。

费用说明（重要）

- token 数：来自 DeepSeek API 每次响应上报的 usage 字段，准确（按每次请求的完整输入计费，
与平台口径一致）；「缓存写入」恒为 0 是因为 DeepSeek API 不报告该字段，属正常现象。
- 费用：按官方价目表（v4-flash / v4-pro）实时计算，含峰谷时段与调价生效日期自动切换。
价格每 6 小时从官方页面同步，无法覆盖官方页面未及时更新的情况，费用仅供参考，
以 platform.deepseek.com/usage 实际账单为准。

开发

dsh plugin --profile web add /path/to/dsh-plugin-balance
修改 lib/client.js 后刷新页面即可生效；修改宿主端/配置需重启 dsh

npm test                # 价格计算/格式化回归测试（node:test）
node scripts/prepublish-check.mjs   # 发布前冒烟检查

发布流程（维护者）

1. 改代码并自测
npm test
2. 更新 package.json 版本号 + CHANGELOG.md
3. 发布 npm（需 npm 账号 2FA passkey 认证，走官方源）
npm publish --access public --registry=https://registry.npmjs.org/
4. 同步 GitHub（commit + tag + push）
git add -A && git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z -m "dsh-plugin-balance vX.Y.Z"
git push && git push --tags

截图

会话头部余额按钮与下拉面板（账户余额 + 实时 token 明细 + 缓存命中率 + 官方价目表费用估算）：

余额与实时会话用量面板

License

MIT