SuLiuCanYing/dsh-billing-statistics

dsh-billing-statistics

DSH 本地计费面板：多平台、按平台/模型明细汇总调用次数、token 与花费，支持峰谷/阶梯计价、按次计费、CSV 人工导入价格（含峰时窗口）、官方账单对齐，以及 HTML/PDF/CSV 导出。

• 按 平台 / 模型 汇总调用次数、失败与中止次数、输入 / 输出 / 缓存命中 token、花费。
• 花费按 峰谷时段 与 阶梯价 计算，峰谷判断默认北京时间（UTC+8，可用 utcOffsetHours 调整）。
• 金额按 6 位小数（0.000001 元）记账；面板默认显示 1~3 位（<100 元 3 位、≥100 元 2 位、≥1000 元 1 位），金额后的眼睛按钮点一下展开 6 位完整金额、再点隐藏，HTML 报表与 CSV 导出同样按 6 位。
• 价格从 models.dev 自动检索：按平台与模型在结构化目录里匹配，美元价按 usdToCny 折成人民币；匹配不到时退回内置参考价。每种价格来源在页面上都有标记。
• DeepSeek 官方 API 自动识别：provider 为 deepseek / deepseek-official / deepseek-account，或 baseURL 的 host 是 api.deepseek.com 时，自动启用官方峰谷价并内置一份官方价表；打开「人工导入价格」前会先读官网 Markdown 最新价，失败则用上次缓存或内置表。只对官方 API 生效，第三方平台上的 DeepSeek 模型不会套用官方价。
• 目录里没有完全同平台的模型时，会显示为 models.dev 参考价 并标出实际来源平台，不会假装成平台官方价。
• 目录没收录、或价格不对时，点平台行里的 人工导入价格，在表格里直接给模型填单价（留空字段保持旧价）；也能勾选 峰时时段（如 09:00-12:00, 14:00-18:00，选每天 / 工作日 / 周末）填峰时价，峰时以外按基础价。还可以下载 CSV 模板 用 Excel 填好后导入。人工价持久化，后续目录刷新不会覆盖；DeepSeek 官方 API 默认以官方自动价为准，只有在弹窗里显式保存才会转为人工覆盖，平台行会出现 改用官方价 按钮可随时恢复。旧版遗留的官方人工价会自动收起，不参与计价。
• 中转站按 调用次数 收费时，勾选弹窗里的 纯按次计费，表格只留「每次」一列，填每次多少钱即可（token 单价与峰时价都不参与计算）。默认只对成功的调用计费，失败 / 中断不收；配置 chargeFailedCalls: true 可改成所有请求都收费。
• 还在用内置价或 models.dev 目录价（或人工价只覆盖了部分模型）时，价格条下方会用 红字 提醒：不同平台的 API 价格不同，models.dev 看不到峰时价，建议人工导入；平台都有可靠价（人工或 DeepSeek 官方自动价）后提醒自动隐藏。
• 历史按 小时桶 保存（usage.json v2），每天的明细可以下钻到小时。
• 导出支持自包含 HTML 报表与 PDF 文档：按平台 / 模型分组，模型下直接列时间明细，调用失败可能会使花费显示偏低；导出前可选格式、统计范围、是否包含时间明细。CSV 仍保留兼容入口。
• 时间范围：今天 / 近 7 天 / 近 30 天，另有「全部」与按年份切换；选中某年直接在卡片下列出该年 12 个月汇总表，「全部」则列出各年汇总表，趋势图同步按月 / 按年展示。
• 按小时明细保留 30 天（可调），超出部分在下次启动时清理；月度汇总长期保留，所以年份与「全部」视图不会随裁剪缩水。
• 官方账单对齐：页脚「官方账单对齐」可按平台 / 日期抄入官方后台的金额、调用次数（可选）与 token（可选），与插件当天记录逐项对比并显示差额；官方不提供调用次数时留空即可。官方账单需要登录对应平台，插件不保存账号、不抓取页面，也不代替你登录；它只是把官方数字和本地观测放在一起，结算仍以官方账单为准。
• 界面中英双语，跟随宿主语言切换。

说明与边界

dsh-billing-statistics 是 DSH 的本地计费账本：把经过 llm/stream 的模型调用按平台、模型和小时记下来，用价格表估算花费，并提供报表与官方账单对照。它不接管模型请求，也不替你登录任何平台。

• 统计范围有限：只记录经过 DSH llm/stream 的调用；DSH 未运行、直连 API、其他客户端的请求不在账本里。
• 金额是估算：按 models.dev、DeepSeek 官方价或你导入的人工价计算；结算以官方账单为准。官方账单对齐需要你手动抄入官方金额，调用次数与 token 可选；插件不抓取账单、不保存账号凭据。
• 不做预算拦截：没有日/月预算、超额阻断、余额查询或自动充值；它只统计和展示。
• 价格来源会标记：目录价是参考价，不保证等于平台合同价；匹配不到时用内置参考价或人工价，页面上会标出来。
• 数据只在本机：写入 $DSH_HOME/llm-usage-insights/，没有云同步或多机合并；卸载不会自动删除账本，需要清理时手动删目录。
• 平台范围：DSH Web UI，>=0.2.1-rc.5 <0.3.0，Node.js >=20；目前已在 Windows 11 + DSH 0.2.1-rc.5、0.2.2-rc.1 实机验证。
• PDF 限制：依赖 pdfkit；缺少中文字体时会直接报错，不会静默生成乱码报表。

安装

安装方式（本地目录）：

# 1. 把本目录放到工作区
# 2. 在 profile 的 package.json 里登记为依赖（link: 形式即可）
# 3. 重启应用，在侧栏看到「计费统计」入口

依赖：@deepseek-ai/schemastery（peer，可选）；PDF 另需 pdfkit（已列在 package.json 的 dependencies，安装时自动装），无需构建。

兼容性：DSH >=0.2.1-rc.5 <0.3.0，Node.js >=20；当前已在 Windows 11 + DSH 0.2.1-rc.5、0.2.2-rc.1 实机验证。完整兼容范围、权限边界与已知局限见 PLUGIN-DECLARATION.md。

从 1.12.x 升级：旧包名是 dsh-billing-insights（更早是 llm-usage-insights）。请先在 Plugin Manager 卸载旧 bundle，再安装 dsh-billing-statistics，避免两个 bundle 同时注册侧栏页面。数据目录与 API 前缀沿用旧名，账本不会丢。

配置

价格匹配顺序：自定义 pricing → 人工导入价格 → DeepSeek 官方自动价（仅官方 API）→ models.dev 目录 → 内置参考价。其中 DeepSeek 官方平台默认把官方自动价排在旧人工价之前：旧版遗留人工价不参与计价，只有你在弹窗里显式保存后才会成为人工覆盖；平台行的「改用官方价」可清除覆盖。

models.dev 目录会缓存在 $DSH_HOME/llm-usage-insights/models-dev.json（历史兼容目录），每天刷新；在线失败时自动用缓存，首次无缓存则用插件内置的目录快照。DeepSeek 官方价每小时最多读一次官网，失败时依次退回上次缓存和内置价表；官网峰时按 UTC 解释，页面会按 utcOffsetHours 显示对应本地时段。

数据与隐私

• 数据目录：$DSH_HOME/llm-usage-insights/（历史兼容目录，默认 ~/.dsh/llm-usage-insights）。
• usage.json 只含计数、token 与价格来源，不保存任何 prompt / 回复内容；manual-prices.json 只存人工导入的价格表。
• 写盘用「临时文件 + 重命名」，断电不会留下半个 JSON；写入失败会保留脏标记并在下次重试。
• 启动时若 usage.json 损坏，会先改名为 usage.json.corrupt-<时间> 备份，再按空数据启动；连备份都失败时进入只读模式，不会用空文件覆盖原数据。
• 写盘前先拿 usage.lock（短临界区），并把盘上已有的桶逐字段取大合并进来，避免多开时整段覆盖。
• 页面路由仅允许同源 / 环回地址访问，并且优先看宿主的 requestRejection 判定。

已知限制

• models.dev 收录约 200+ 平台、8000+ 模型；没收录的模型（例如某些平台上刚上线的新模型）不会自动出价，页面会明确提示，用「人工导入价格」最稳。
• 跨平台参考价来自 models.dev 里模型 id 完全相同的另一平台（页面会标出来源平台）；它不一定等于你所用平台的实际价，介意时请人工填价。
• 峰谷与分桶时区由 utcOffsetHours 决定，改它不会重排已有分桶（旧数据仍按旧口径）。
• usage.json 有 usage.lock 轻量互斥，但多实例同时写只能「逐字段取大」合并，同一小时的并发调用可能被少算；建议只开一个窗口。导出支持自包含 HTML 报表（主入口）、PDF 文档与 CSV（兼容保留）。PDF 依赖本机中文字体（Windows 默认用黑体），找不到字体时请改用 HTML。

开发与测试

node --test "test/*.test.js"

测试覆盖：峰谷 / 阶梯计价与汇率折算、DeepSeek 官方 API 识别与官方价表 / 官网解析 / UTC 峰谷、models.dev 目录匹配与参考价、人工导入价格与峰时时段、v1→v2 迁移、保留期裁剪与月汇总保留、年 / 全部视图、价格表优先级、落盘与重开一致性、损坏文件备份、中英文案键对齐。

许可

MIT，见 LICENSE。