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 设置可为任意模型（含自定义模型）覆盖或补充价格，优先级最高。
安装
一键安装
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 命名空间的用户设置（可在运行时热更新）：
| 设置 | 默认 | 说明 |
|---|
dailyBudget | 0 | 日预算（元），0 关闭 |
totalBudget | 0 | 总预算（元），0 关闭 |
sessionBudget | 0 | 单会话预算（元），0 关闭 |
warnRatio | 0.8 | 进入告警的预算占比 |
enforceBudget | true | 超预算时拦截模型调用 |
pricingUrl | DeepSeek 官方页 | 定价刷新来源 |
refreshIntervalMin | 60 | 定价刷新间隔（分钟） |
customPrices | {} | 按模型 id 覆盖价格（最长前缀匹配） |
customPrices 示例：
{
"glm-4.6": { "inputCacheHit": 1, "inputMiss": 5, "output": 5 }
}
价格单位为 元 / 百万 tokens。
价格解析优先级
用户覆盖 > DeepSeek 实时表 > 各厂商实时抓取表 > 内置目录精确匹配 > 最长前缀匹配
各厂商抓取方式（fetchKind）：
| 厂商 | 通道 |
|---|
| DeepSeek | 官方定价页 HTML（含峰谷表） |
| 智谱 GLM | SPA app.*.js 内嵌价格 + 公开运营位接口 |
| Kimi | Next.js RSC flight payload 子页 |
| 通义千问 | 官方定价页表格 |
| 豆包 | 火山文档中心服务端 Markdown |
| MiniMax | 官方定价页表格 |
| 文心 | 百度 CDN Gatsby page-data |
抓取失败时沿用上一次成功的价格，网络异常不影响记账。
提供的工具
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
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):
| Setting | Default | Description |
|---|
dailyBudget | 0 | Daily cost budget (CNY); 0 disables |
totalBudget | 0 | Lifetime cost budget (CNY); 0 disables |
sessionBudget | 0 | Per-session cost budget (CNY); 0 disables |
warnRatio | 0.8 | Ratio at which budgets enter the warning state |
enforceBudget | true | Block model calls once any budget is exceeded |
pricingUrl | DeepSeek official page | Pricing refresh source |
refreshIntervalMin | 60 | Pricing refresh interval (minutes) |
customPrices | {} | Price overrides by model id (longest-prefix match) |
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):
| Vendor | Channel |
|---|
| DeepSeek | Official pricing page HTML (incl. peak/off-peak table) |
| Zhipu GLM | Prices embedded in the SPA app.*.js bundle + public operation API |
| Kimi | Next.js RSC flight payload subpages |
| Qwen | Official pricing page tables |
| Doubao | Volcano doc-center server-side Markdown |
| MiniMax | Official pricing page tables |
| ERNIE | Baidu CDN Gatsby page-data |
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
