计费账本mahiro6/dsh-billing

dsh-billing

DeepSeek Harness 计费插件（界面中英双语）

持久化账本 · 精确计费（每次模型调用）· 官方余额 · 预算 · 今日/本月/累计汇总 · 会话明细与历史记录 · 峰谷计价 · 官方价格同步

version
license
dsh

功能总览

| 功能 | 位置 | 说明 |
|---|---|---|
| 本会话费用 | 会话统计行 | 实时累计 token（输入/缓存/输出）+ 按当前价格档位估算费用 |
| 今日费用 | 会话统计行 / 侧边栏 | 账本精确值 |
| 官方余额 | 会话统计行 / 侧边栏底部 / 设置页 | 总/赠送/充值；自动刷新 + 手动刷新（点击即强制查询最新余额，并显示最近更新时间） |
| 汇总卡片 | 设置页 | 今日 / 本月 / 累计费用、调用次数与 token 明细 |
| 预算 | 设置页 + 侧边栏进度条 | 额度、周期（今日/本月/累计/自定义区间）、已用百分比（≥80% 预警、≥100% 超支） |
| 今日会话明细 | 设置页 | 每个会话的调用次数、输入/缓存/输出 token 与费用 |
| 历史记录 | 设置页 | 按天汇总，按保留天数修剪（默认 180 天，固定值） |
| 价格表 | 设置页 | 每模型 基础/谷时/峰时 三档价格，只读展示：每次启动自动同步官方最新价、仅显示官方现有模型、按显示币种计价（默认人民币） |
| 峰谷计价 | 设置页 | 只读展示：峰谷时间与当前处于峰/谷时段（时间来自官方平台同步） |
| 官方价格同步 | 设置页 | 抓取解析官方定价页，一键应用；每次启动也会自动同步 |
| 数据 | 设置页 | 清除全部历史 |

计费规则

- 价格单位与官方文档一致：美元 / 1M tokens；
- 成本 = 未命中输入 × cacheMiss + 输出 × output + （缓存读 + 缓存写） × cacheHit；
- 峰谷计价按时点门控：peakEffectiveAt（默认 2026-08-16 16:00 UTC）之前一律按基础价格；之后峰时段（01:00–04:00、06:00–10:00 UTC）按峰时价、其余按谷时价；
- 账本金额恒以美元存储；展示币种固定为默认值（CNY、¥、汇率 7.2、4 位小数），不再提供界面修改；
- 计费来源为每次模型调用的 usage 块（llm/stream 瀑布链尾监听），主循环、子代理、压缩、标题等辅助调用全部入账，与账单口径一致；
- 会话统计行的本会话费用按当前价格档位估算，今日/月度/累计与预算为按调用实际时刻精确计费；
- 预算与超支提示仅提醒，不阻止调用；
- 价格表每次启动自动同步官方最新价（失败时沿用现有价格并告警）；设置环境变量 DSH_BILLING_SKIP_STARTUP_SYNC=1 可关闭自动同步（离线/测试环境）；价格不再支持手动修改。

数据存储

- 账本：$DSH_HOME/storages/dsh-billing/ledger.json（原子写入 + 2 秒防抖；按 historyDays 保留，每日最多 200 个会话明细）；
- 所有设置修改即时自动保存（客户端「保存设置」提交，服务端校验后持久化）；
- 删除账本文件即可清零，或使用设置页「清除全部历史」。

架构

dsh-billing
├── cordis.patch.yml        # bundle 补丁:向 web profile 插入 billing 行
├── package.json            # dsh.bundle 补丁声明 + dsh.client 浏览器声明
├── lib/
│   ├── index.js            # 宿主插件:llm/stream 计费包裹、costUsage 会话投影、
│   │                       #   billing 服务(手写 typertRemote 绑定)、余额查询、官方价格同步
│   ├── pricing.js          # 官方价格表、官方页面 HTML 解析、峰谷计费数学
│   ├── store.js            # 账本持久化与配置管理($DSH_HOME/storages/dsh-billing)
│   ├── typert.host.js      # ./typert 导出:Typert 清单(typert-loader 自动注册)
│   └── client.js           # ./client 导出:浏览器单文件 bundle(统计行/侧边栏/设置页)
└── test/
├── verify.mjs          # 单元验证:定价/配置/账本/投影/真实 cordis 加载/计费包裹
└── demo.mjs            # 计费演示:模拟多会话/多模型/峰谷调用,输出账本与汇总

数据通道：

- 本会话费用：宿主注册 costUsage 会话投影（纯 token 桶 + 按模型拆分），浏览器经 useProjection('costUsage') 读取并按当前价格档位计价；
- 账本 / 预算 / 余额 / 配置：billing/getState | updateConfig | refreshBalance | fetchPrices | resetHistory，经 Typert 网关 RPC（remote.billing.*）；
- 余额：调用官方 GET {baseURL}/user/balance，复用模型请求的同一把 API Key（凭证服务/环境变量），进程内缓存按 refreshMinutes 过期；「刷新余额」按钮每次点击强制重新查询（序号守卫保证只采用最新一次结果）；
- 刷新策略：宿主不使用 cordis timer mixin（ctx.interval 在未挂载 timer 服务的上下文中读取会直接抛错），全部基于「缓存时间戳 + 按需刷新」，由客户端轮询/手动刷新触发。

插件不导入 cordis/dsh 的 Service/Context 运行时类（仅 Node 内建模块、zod、dsh-home-paths、dsh-credentials 的纯函数），与宿主共享同一运行时实例，无重复依赖风险。

安装

需求：Node.js ≥ 20 + DeepSeek Harness（带 dsh plugin 命令，npm install -g @deepseek-ai/dsh）。

方式一：从 GitHub 安装（发布后）

dsh plugin --profile web add github:mahiro6/dsh-billing

或使用 GitHub tag 打包直链：

dsh plugin --profile web add https://github.com/mahiro6/dsh-billing/archive/refs/heads/main.tar.gz

方式二：本地开发安装（推荐改源码时用）

dsh plugin --profile web add link:
例：dsh plugin --profile web add link:E:\Workspace\dsh-billing

生效与卸载

安装后重启 dsh web（插件行、Typert 清单与客户端 bundle 均在启动时扫描）：

dsh web

更新：重跑安装命令并重启；卸载：dsh plugin --profile web remove dsh-billing。

开发与验证

pnpm install                                            # 依赖
node --check lib/index.js && node --check lib/pricing.js \
&& node --check lib/store.js && node --check lib/typert.host.js \
&& node --check lib/client.js                         # 语法检查
node test/verify.mjs                                    # 单元验证（定价/配置/账本/投影/真实 cordis 加载/计费包裹）
node test/demo.mjs                                      # 计费演示（模拟调用 → 账本/汇总/预算）
dsh --profile web --dump-config                         # 组合树校验（需已安装）

配置

以下为账本配置（持久化于 ledger.json）。除 budget 外均不再提供界面修改：显示相关字段固定为默认值，价格表与峰谷时间由官方同步维护；可直接编辑账本文件调整。

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| locale | auto | 界面语言：auto（跟随浏览器）/ zh / en（固定默认值） |
| statsLine | true | 会话统计行显示余额、今日费用与本会话费用（固定默认值） |
| sidebar | true | 侧边栏底部显示余额、今日费用与预算进度条（固定默认值） |
| currency | CNY | 费用显示币种（CNY/USD/EUR/GBP/JPY/HKD/TWD，固定默认值） |
| symbol | ¥ | 货币符号（固定默认值） |
| decimals | 4 | 金额小数位（固定默认值） |
| exchangeRate | 7.2 | 汇率（1 USD = ?，固定默认值） |
| peakEnabled | true | 启用峰谷计价（固定默认值） |
| peakEffectiveAt | 2026-08-16T16:00:00Z | 峰谷计价生效时间（UTC，由官方同步维护） |
| peakWindows | [{1,4},{6,10}] | 峰时段窗口（UTC 小时，由官方同步维护） |
| prices | 内置 DeepSeek 官方价 | 每模型 cacheHit/cacheMiss/output + 可选 offPeak/peak（美元 / 1M tokens，由官方同步维护） |
| budget | {enabled:false, amount:100, period:'month'} | 预算：启用/额度（显示币种）/周期（day/month/all/custom）/自定义区间（可在界面修改） |
| balance | {display:'both', refreshMinutes:5} | 余额显示位置与自动刷新间隔（固定默认值） |
| historyDays | 180 | 账本保留天数（7–3650，固定默认值） |

已知限制

- 余额是账户级数据，按 refreshMinutes 缓存；手动刷新即时生效；
- 会话统计行的本会话费用为当前档位估算值，精确费用以账本（今日/月度/累计）为准；
- 官方页面解析依赖当前页面结构；改版后「同步官方价格」会报错，价格表暂沿用旧值，可稍后重试或手动编辑 ledger.json 兜底；
- 价格同步以官方页面为准替换整个模型集：官方页面不存在的 legacy/自定义模型会被移除；
- 余额查询需要可访问 api.deepseek.com 的网络与有效 API Key；API Key 只会发往官方域名（baseURL 指向非官方域名时余额查询拒绝请求，模型请求不受影响）；
- 安装/更新插件后需重启 dsh web 生效。

贡献

欢迎提交 Issue 与 PR。开发前请先跑通 node test/verify.mjs。

License

MIT © 2026 dsh-billing contributors