beijingwahw/dsh-usage-ledger

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

dsh-plugin
license

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 buildmarkdown
dsh plugin add ./dsh-usage-ledger --profile web

许可

MIT

dsh-usage-ledger

一个面向 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 设置可为任意模型（包括自定义模型）覆盖或新增价格，且优先级最高。

安装

一行命令
bash
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 中挂载并配置它：
yaml
- 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 }
}

所有价格均为每 1M tokens 的人民币价格。

价格解析优先级

用户覆盖 > DeepSeek 实时表格 > 供应商实时表格 > 内置目录精确匹配 > 最长前缀匹配

各供应商的抓取渠道（fetchKind）：

| 供应商 | 渠道 |
| --- | --- |
| DeepSeek | 官方定价页面 HTML（含高峰/低谷时段表格） |
| Zhipu GLM | 嵌入在 SPA app..js 包中的价格 + 公开运营 API |
| Kimi | Next.js RSC flight payload 子页面 |
| Qwen | 官方定价页面表格 |
| Doubao | 火山文档中心服务端 Markdown |
| MiniMax | 官方定价页面表格 |
| ERNIE | 百度 CDN Gatsby 页面数据 |

抓取失败时会保留上一次的有效价格，因此网络问题绝不会破坏计费。

提供的工具

- usage_report：报告当前用量 / 成本 / 预算状态。

HTTP 端点

- GET /usage-ledger：仪表盘页面。
- GET /usage-ledger/api/...：用量与定价 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

目录结构：

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

贡献

欢迎提交 issue 和 pull request。请保持改动聚焦，并在提交前运行 pnpm run typecheck。

许可证

MIT