dsh-usage-ledger ( Token费用统计 )

 

中文 | [English](#english)

DeepSeek Harness 的 Token / 用量统计与成本控制插件：按对话聚合消耗、动态跟随官方定价、支持预算拦截，并内置 Web 仪表盘。

功能特性

• 按会话统计：监听 session/event，把每次 assistant/message 的 usage（输入 / 输出 / 缓存读写 Token）折算为费用，按会话、按北京日、按生命周期三个维度聚合，并持久化到账本文件。
• 动态官方定价：定期抓取官方定价页，自动解析并热更新价格，官方调价 / 上新模型时无需改代码即可生效。
• DeepSeek 峰谷分时：识别官方「高峰 / 空闲」时段表与生效日期，按调用发生的北京时间实时取价。
• 多厂商价格目录：覆盖 DeepSeek、智谱 GLM、月之暗面 Kimi、阿里通义、字节豆包、MiniMax、百度文心等主流国产模型，新模型上线官方定价页后自动导入。
• 预算控制：支持日 / 总 / 单会话三级预算，达到阈值进入告警，超限可通过 llm/stream 钩子直接拦截模型调用。
• Web 仪表盘：通过 dsh-host-webserver 注册 /usage-ledger 路由，提供用量可视化与 JSON API。
• 用户覆盖价：customPrices 设置可为任意模型（含自定义模型）覆盖或补充价格，优先级最高。

安装

一键安装

dsh plugin add beijingwahw/dsh-usage-ledger --profile web

> 常用进阶命令：升级 dsh plugin upgrade dsh-usage-ledger --profile web；卸载 dsh plugin remove dsh-usage-ledger --profile web；本地路径安装 dsh plugin add ./dsh-usage-ledger --profile web。

Harness 通过 dsh.plugin.json 与 cordis.patch.yml 自动加载插件，lib/ 随仓库分发，无需本地构建。

配置

在 Harness 的 cordis.yml 中挂载并配置：

- name: dsh-usage-ledger
  config:
    ledgerPath: ''            # 留空则使用 $DSH_HOME/usage-ledger.json
    saveIntervalMs: 5000      # 账本落盘防抖
    pricingTimeoutMs: 10000   # 单次定价抓取超时

usage-ledger 命名空间的用户设置（可在运行时热更新）：

customPrices 示例：

{
  "glm-4.6": { "inputCacheHit": 1, "inputMiss": 5, "output": 5 }
}

价格单位为 元 / 百万 tokens。

价格解析优先级

用户覆盖 > DeepSeek 实时表 > 各厂商实时抓取表 > 内置目录精确匹配 > 最长前缀匹配

各厂商抓取方式（fetchKind）：

抓取失败时沿用上一次成功的价格，网络异常不影响记账。

提供的工具

• usage_report：输出当前用量 / 费用 / 预算状态报表。

HTTP 接口

• GET /usage-ledger：仪表盘页面。
• GET /usage-ledger/api/...：用量与定价 JSON API。

开发

pnpm run build        # 编译到 lib/
pnpm run typecheck    # 仅类型检查

目录结构：

src/
  index.ts      # 插件入口：事件折叠、预算门、工具与路由注册
  ledger.ts     # 用量聚合、持久化、预算评估
  pricing.ts    # 定价抓取、解析、变更检测
  catalog.ts    # 厂商元信息与内置价格目录
  scrapers.ts   # 通用 / 专用定价页解析器
  types.ts      # 共享类型

参与贡献

欢迎提交 Issue 与 Pull Request。请保持改动聚焦，提交前运行 pnpm run typecheck。

从源码构建安装（贡献者 / 离线场景）：

git clone https://github.com/beijingwahw/dsh-usage-ledger.git
cd dsh-usage-ledger
pnpm install
pnpm run build
dsh plugin add ./dsh-usage-ledger --profile web

许可

[MIT](./LICENSE)

---

<a id="english"></a>

dsh-usage-ledger

[中文](#dsh-usage-ledger) | English

A token usage & cost ledger plugin for DeepSeek Harness: per-session cost aggregation, dynamic official pricing, budget gating, and a built-in web dashboard.

Features

• Per-session accounting: listens to session/event, prices every assistant/message usage record (input / output / cache read & write tokens), and aggregates it per session, per Beijing-time day, and per lifetime, persisting everything to a ledger file.
• Dynamic official pricing: periodically scrapes official pricing pages, parses and hot-reloads prices — official price changes and newly published models take effect without any code change.
• DeepSeek peak/off-peak: understands the official peak/off-peak schedule and its effective date, resolving the price in force at the exact Beijing time of each call.
• Multi-vendor catalog: covers DeepSeek, Zhipu GLM, Moonshot Kimi, Alibaba Qwen, ByteDance Doubao, MiniMax and Baidu ERNIE; new models are imported automatically once they appear on an official pricing page.
• Budget control: daily / total / per-session budgets with a warning threshold, optionally blocking model calls through the llm/stream gate when exceeded.
• Web dashboard: registers the /usage-ledger route via dsh-host-webserver, with usage visualization and a JSON API.
• User price overrides: the customPrices setting can override or add prices for any model (including custom ones) and takes top priority.

Installation

One-liner

dsh plugin add beijingwahw/dsh-usage-ledger --profile web

> Common follow-ups: upgrade dsh plugin upgrade dsh-usage-ledger --profile web; uninstall dsh plugin remove dsh-usage-ledger --profile web; local-path install dsh plugin add ./dsh-usage-ledger --profile web.

Harness loads it automatically through dsh.plugin.json and cordis.patch.yml. lib/ ships in the repo — no local build step needed.

Configuration

Mount and configure it in Harness's cordis.yml:

- name: dsh-usage-ledger
  config:
    ledgerPath: ''            # empty = $DSH_HOME/usage-ledger.json
    saveIntervalMs: 5000      # ledger persistence debounce
    pricingTimeoutMs: 10000   # wall-clock budget for one pricing fetch

User settings in the usage-ledger namespace (hot-reloadable at runtime):

customPrices example:

{
  "glm-4.6": { "inputCacheHit": 1, "inputMiss": 5, "output": 5 }
}

All prices are CNY per 1M tokens.

Price Resolution Priority

user overrides > DeepSeek live sheet > vendor live tables > built-in catalog exact match > longest-prefix match

Per-vendor fetch channels (fetchKind):

On fetch failure the last good prices are kept, so network issues never break accounting.

Provided Tool

• usage_report: reports current usage / cost / budget status.

HTTP Endpoints

• GET /usage-ledger: dashboard page.
• GET /usage-ledger/api/...: usage and pricing JSON API.

Development

git clone https://github.com/beijingwahw/dsh-usage-ledger.git
cd dsh-usage-ledger
pnpm install
pnpm run build        # compile to lib/
pnpm run typecheck    # type check only

Layout:

src/
  index.ts      # plugin entry: event folding, budget gate, tool & route registration
  ledger.ts     # usage aggregation, persistence, budget evaluation
  pricing.ts    # pricing fetch, parsing, change detection
  catalog.ts    # vendor metadata and built-in price catalog
  scrapers.ts   # generic / vendor-specific pricing page parsers
  types.ts      # shared types

Contributing

Issues and pull requests are welcome. Please keep changes focused and run pnpm run typecheck before submitting.

License

[MIT](./LICENSE)