dsh-usage-ledger
DSH token 使用与成本台账：按会话聚合、官方多供应商定价（支持峰时/非峰时）、预算控制、成本智能洞察（预测、异常检测、健康评分、归因）、Prometheus 指标、SSE 仪表板
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:beijingwahw/dsh-usage-ledger#9c2636212fdef73a6ea68522b4a195c533aefad2Usage Ledger 以 dsh-usage-ledger 发布，当前版本为 0.9.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
中文 | English
DeepSeek Harness 的 Token / 用量统计与成本控制插件：按对话聚合消耗、动态跟随官方定价、支持预算拦截，并内置 Web 仪表盘。
session/event，把每次 assistant/message 的 usage（输入 / 输出 / 缓存读写 Token）折算为费用，按会话、按北京日、按生命周期三个维度聚合，并持久化到账本文件。llm/stream 钩子直接拦截模型调用。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：输出当前用量 / 费用 / 预算状态报表。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
中文 | 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.
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.llm/stream gate when exceeded./usage-ledger route via dsh-host-webserver, with usage visualization and a JSON API.customPrices setting can override or add prices for any model (including custom ones) and takes top priority.dsh plugin add beijingwahw/dsh-usage-ledger --profile web
Common follow-ups: upgrade
dsh plugin upgrade dsh-usage-ledger --profile web; uninstalldsh plugin remove dsh-usage-ledger --profile web; local-path installdsh 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.
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.
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.
usage_report: reports current usage / cost / budget status.GET /usage-ledger: dashboard page.GET /usage-ledger/api/...: usage and pricing JSON API.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
Issues and pull requests are welcome. Please keep changes focused and run pnpm run typecheck before submitting.