前言¶

DeepSeek Harness（dsh web）目前没有官方的用量或账单 API，开发者很难追踪实际扣费。dsh-usage-calendar 插件通过采样余额下降来计算实际扣费，并提供日历视图，聚合本机全部会话的 token 用量、缓存命中率等数据。

功能¶

余额查询
通过官方接口查询账户余额，1 秒缓存，界面每 1 秒自动刷新，支持手动强制刷新。

日历视图
按天聚合本机全部会话的 token 用量。活动会话走内存日志，已存档会话走 ctx.sessionQuery，因此历史日期同样完整。支持月份切换与“今天”。

每日实际扣费
DeepSeek 没有用量/账单 API，插件把每次余额读数采样落盘，把余额下降计为扣费，按天汇总。这是平台实际扣你的钱，不区分模型。

本地估算
按官方价目逐条估算，用于对照。

缓存命中率
计算 cacheRead / (input + cacheRead + cacheWrite)（提示词侧）。

本地统计
只读本机会话事件日志与余额接口，不上传任何数据。

安装与启用¶

使用 npx 安装器：

npx --yes github:xiyi123465/dsh-usage-calendar

安装器将包复制到 $DSH_HOME/profiles/node_modules/dsh-usage-calendar，并重启 dsh web 后生效。

典型用法¶

1. 点击日历面板查看历史日期的详细用量（活动会话走内存日志，已存档会话走 ctx.sessionQuery）。
2. 点击余额胶囊手动强制刷新余额。
3. 使用 --local-only 选项仅统计本机 key 的用量。
4. 使用 node scripts/import-actual.mjs 回填历史数据。
5. 通过 llm-deepseek 设置命名空间配置 API Key。

注意事项¶

1. 扣费计算方式：DeepSeek 没有用量/账单 API，扣费通过采样余额下降计算。
2. 数据精度：金额用整数分累加，不随折叠漂移。
3. 隐私安全：只读本机会话事件日志与余额接口，不上传任何数据。
4. 对账警告：已实测的日子若与本地估算相差 >1.5× 时标警告。
5. 结算延迟：服务端结算有延迟，跨午夜的调用可能记在后一天。

总结¶

dsh-usage-calendar 通过余额采样和本地日志聚合，解决了 DeepSeek 官方无用量 API 的问题，提供了可视化的日历视图用于成本追踪。