dsh-web-billing

简体中文 · English

DeepSeek Harness（dsh web）的人民币/美元 token 计费插件：按官方政策自动计价 （内置政策时间表，含 2026-08-17 起的峰谷定价），逐条消息记账，实时显示账号余额， 浏览器端展示费用（界面语言自动切换 ¥/$）。

混合会话（云端+本地）	纯本地会话	纯云端会话

• 记账（host 端）：订阅 session/event，对每条带 usage 的 assistant/message 按消息时刻取价计费（CNY 与 USD 双币种，官方美元价独立发布），账本持久化到 $DSH_HOME/storages/web-billing.json。
• 账号余额（host 端）：复用 provider 的 API key 调用官方 GET /user/balance （默认 60s 刷新、5s 超时、失败静默降级），CNY/USD 双币种随 /billing/state 返回。
• 本地模型节省统计：配置 localProviders 后，本地（自托管）模型的调用按官方 价格计算「名义价值」，实际成本按 localCostPerM（默认 0 = 免费），差值即 「已节省」——面板与消息角标实时显示（本地消息角标显示 省¥X）。
• 展示（浏览器端）：每条 assistant 消息动作条上的费用角标（悬停显示 token 拆分与模型）；会话头部费用角标，点击展开 本会话 / 今日 / 本月 / 累计 / 账户余额 / 已节省 / 按模型 明细与当前计价方式。中文界面显示 ¥，英文 界面显示 $，也可用 displayCurrency 强制指定。
• 查询端点（只读，默认仅回环）：GET /billing/state、GET /billing/session/<id>。

核心特性

官方政策自动计价

lib/pricing.js 内置官方价格时间表（OFFICIAL_PRICING_POLICIES），每条政策有 生效时刻（since）与单价表：

峰谷价格（¥/1M）：

计价语义：

• 按消息时刻取价：每条消息按其完成时刻所属的政策与峰谷时段计费；新政策 生效后自动切换，无需改配置。
• 政策链继承：新政策未点名的模型沿用最近一次被点名的价格（下架模型的历史 账单与平台一致）。
• 改价自愈：政策表或配置变化后，重启时按当前规则重估全部存量记录（以每条 消息记录的 token 数为准，不丢失历史）。
• 用户覆盖：prices 中模型精确条目覆盖官方价；* 只填补官方从未点名的 模型。officialPricing: off 则完全使用用户价格表。
• 可扩展时间表：官方未来调价，通过 policyOverrides 在配置里追加政策即可， 无需改代码（也欢迎向 lib/pricing.js 提交 PR）。

⚠️ 政策时间表策展自官方公告（DeepSeek API Docs）， 请以官方页面为准；发现偏差欢迎 PR 修正。

安装

插件是一个标准 DSH 组合包（bundle）（dsh.bundle.patch 指向包内 cordis.patch.yml），按官方打包与安装指南 分发。三种安装方式：

# 从 GitHub 安装（git 安装运行 prepare 构建；本包为纯 JS，无需构建，开箱即用）
dsh plugin --profile web add github:<owner>/dsh-web-billing

# 或从 npm 安装（发布后）
dsh plugin --profile web add dsh-web-billing

# 或本地开发：链接 checkout
powershell -ExecutionPolicy Bypass -File scripts/install.ps1 -Profile web

git 安装时 pnpm ≥10 可能要求构建授权：把提示的包键加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试（本包没有 prepare 构建， 通常无需授权）。

安装后重启 dsh web 生效。同一 $DSH_HOME 下请只运行一个实例（多个实例 会争写同一账本文件）。

需要覆盖默认配置时，在 $DSH_HOME/profiles/web/cordis.patch.yml 按 id 覆写整行 （覆盖会替换整份 config，需重述所有键）：

配置参考

单价字段语义：input=缓存未命中输入，cacheRead=缓存命中输入，output=输出 （¥ / 百万 tokens）。

记账正确性

• 幂等：以 (sessionId, messageId) 为主键，重复/重放事件只覆盖明细，绝不 重复累计（多进程、多次重启实测验证）。
• 按本地时区统计「今日 / 本月」。
• 落盘：1s 防抖 + 临时文件原子替换；加载失败从空账本开始并告警；进程退出 时补一次 flush。
• 审计字段：每条消息明细记录应用的单价（unitPrice）与计价模式（mode： flat / peak / offPeak）。
• 余额只读：余额查询只调用官方只读接口，不写任何数据；key 只存在于服务端 解析链路，不下发浏览器。

开发

npm run check   # 语法检查
npm test        # 定价引擎 + 余额解析单元测试（node:test，无依赖）

结构：

lib/pricing.js   定价引擎（纯函数：政策时间表 / 峰谷判定 / 覆盖合并 / 费用计算）
lib/balance.js   账号余额（响应解析纯函数 + 带缓存/容错的抓取器）
lib/index.js     host 端：记账、账本、余额轮询、/billing 路由（cordis 插件）
lib/client.js    浏览器端：费用角标与面板（手写 __ModuleLoader__ bundle，无需构建）
test/            单元测试
scripts/         安装脚本

浏览器端 bundle 为手写模块（与 DSH 官方 client 插件同格式），修改后刷新页面 + 重启 dsh web 生效；host 端修改需重启。

安全

• /billing 端点默认仅回环地址可访问（loopbackOnly: true）；需要从局域网查看 时改为 false（与 GUI 其它路由一致，未做鉴权）。
• 插件只读取 session/event 与提供只读端点，不修改任何会话数据。

贡献 / Contributing

欢迎 PR 与 Issue（中英皆可）。本仓库中英双语维护：文档改动需同步更新 README.md（中文）与 README.en.md（英文），配置注释双语；完整规范见 CONTRIBUTING.md。

License

MIT