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

中文 | 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 设置可为任意模型（含自定义模型）覆盖或补充价格，优先级最高。

安装

将本仓库放入 DeepSeek Harness 的插件目录（或通过包管理器安装），Harness 会依据 dsh.plugin.json 与 cordis.patch.yml 自动加载。

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

配置

在 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。

许可

MIT

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

Drop this repository into the DeepSeek Harness plugin directory (or install it via a package manager). Harness loads it automatically through dsh.plugin.json and cordis.patch.yml.

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

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

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