前言¶
在 DeepSeek Harness（DSH）这类「一切皆插件」的宿主里，模型调用通常会持续产生输入、输出、缓存读写等 Token 消耗。只看单条 usage 往往不够：还需要知道一个会话花了多少、今天花了多少、是否接近预算，以及官方调价后费用是否仍然准确。
dsh-usage-ledger 是 beijingwahw 维护的一个 DSH 插件，用于统计 Token / 用量、折算费用、控制预算，并提供 Web 仪表盘。它会监听 session/event，把每次 assistant/message 的 usage 折算为费用，并按会话、北京日、生命周期聚合持久化。
定位¶
dsh-usage-ledger 是一个面向 DSH 的 Token / 用量统计与成本控制插件：按对话聚合消耗、动态跟随官方定价、支持预算拦截，并内置 Web 仪表盘。
维护者为 beijingwahw，许可证为 MIT。
核心功能¶
按会话统计¶
插件监听 session/event，将每次 assistant/message 的 usage 折算为费用，并按三个维度聚合持久化：
- 按会话
- 按北京日
- 按生命周期
动态官方定价¶
插件会定期抓取官方定价页，自动解析并热更新价格。官方调价后，价格可以随抓取结果更新，不需要手工修改插件代码。
DeepSeek 峰谷分时¶
插件会识别官方高峰 / 空闲时段表与生效日期，并按调用发生的北京时间实时取价。
多厂商价格目录¶
插件覆盖多个厂商的价格目录，包括：
- DeepSeek
- 智谱 GLM
- 月之暗面 Kimi
- 阿里通义
- 字节豆包
- MiniMax
- 百度文心等
预算控制¶
插件支持三级预算：
- 日预算
- 总预算
- 单会话预算
达到阈值时会进入告警状态；超预算时可通过 llm/stream 钩子拦截模型调用。
预算值设置 0 表示关闭对应预算。
Web 仪表盘¶
插件通过 dsh-host-webserver 注册 /usage-ledger 路由，提供用量可视化与 JSON API。
用户覆盖价¶
customPrices 可按模型 id 覆盖或补充价格，优先级最高。
安装与启用¶
先安装插件：
dsh plugin add beijingwahw/dsh-usage-ledger --profile web
安装后，Harness 会通过 dsh.plugin.json 与 cordis.patch.yml 自动加载插件。lib/ 随仓库分发，无需本地构建。
接着在 Harness 的 cordis.yml 中配置插件。已核实资料给出的配置项包括：
ledgerPathsaveIntervalMspricingTimeoutMs
典型用法¶
设置自定义价格¶
当需要为某个模型设置覆盖价或补充价时，可以配置 customPrices。价格单位为元 / 百万 tokens。
示例：
{"glm-4.6": {"inputCacheHit": 1, "inputMiss": 5, "output": 5}}
查看用量报表¶
可以使用工具 usage_report，输出当前用量、费用和预算状态报表。
访问仪表盘和 JSON API¶
访问仪表盘页面：
GET /usage-ledger
访问 JSON API：
GET /usage-ledger/api/...
预算与失败处理¶
插件的预算控制支持日、总、单会话三级预算。达到阈值后进入告警状态；超预算时可通过 llm/stream 钩子拦截模型调用。
定价抓取失败时，插件会沿用上一次成功价格，因此网络异常不影响记账。
适用场景与注意¶
适合以下场景：
- 需要按会话、按北京日、按生命周期查看 Token 消耗
- 需要把模型调用折算成费用
- 需要为日、总、单会话设置预算
- 需要在超预算时拦截模型调用
- 需要通过 Web 仪表盘查看用量和 JSON API
注意：插件以当前 dsh 进程权限运行，会注册工具与路由，并定期抓取官方定价页。安装前应检查源码与许可证。该插件许可证为 MIT。
链接¶
已确认的源码地址：
https://github.com/beijingwahw/dsh-usage-ledger
