dsh-ui-usage-billing

中文 · English

峰谷计费规则更新（自 2026-08-23（周日）00:00 起）：DeepSeek 模型按官方新规计费——工作日（周一至周五） 继续执行原峰谷分段计费（高峰 09:00–12:00 / 14:00–18:00，×2）；周末（周六、周日） 全天不再区分峰谷时段，统一按低谷价计费。插件计费引擎、费率表与每轮费用峰谷分带均已同步生效。

演示动图

特性

• 侧边栏入口：设置按钮上方的仪表盘式触发卡——本月费用主数字（等宽字体）+ 近 7 天 sparkline 迷你趋势，副行「今日 / 本周」；折叠栏自动切为图标钮；悬停浮现速览卡。

• 计费仪表盘（分区 Tab）：概览 / 趋势 / 明细 / 统计 / 费率 / 设置 六区——Hero 大数字 + 本年/今日环比 + 本月预计 + KPI×4 + 热力图；趋势图 7/30 天；厂商计费与订阅；导出 / 费用构成 / 工作区 / 会话明细；模型单价表；预算与峰谷提醒。克制冷调、--dsw-* 令牌、深浅主题自适应。

  

• 即时代费用条：输入框下方常驻「本轮 ¥x · 会话 ¥y」+ 峰谷档位与切换倒计时 + 订阅额度预警 chips（≤20% 浮现、≤10% 红）。

• 峰/谷切换提醒：切档前弹窗 + 可选系统通知（提前量 / 位置 / 模式 / 预览可配），区分「即将进峰时 ×2 可稍等」/「即将进平价 价格减半」。

• 实时定价费率表：models.dev 抓价 + 探活模型对标——系统实际配置模型全纳入；峰谷分时（工作日 9-12 / 14-18 高峰 ×2，周末全天低谷）+ 实时汇率（USD→CNY），每 6 小时刷新。

  

• 官方 vs 三方分桶：明细费用列按官方 DeepSeek 直连 / 第三方中转分解（混合时「官 x / 三 y」），统计 Tab 有「官方/三方」汇总卡。

• 中转站归组与额度：按 provider 的 baseURL 归一化 origin 归组——同一中转站的多把 key 合并成一行，站名即域名；明细 Tab 新增「中转站分布」卡（中转站 / 直连 / 未知路由三态，未知路由 = 配置里已删 / 改名的路由，诚实标注「读不到」而非误归直连）。对配了 baseURL 的路由自动识别 New API 系（/api/status）与 Sub2API（/v1/usage）的余额与滚动额度窗口，读不出标「未读出额度」，剩余 <20% 标红；中转站识别结果有 5 分钟指纹缓存（同站多把 key 独立熔断），relay-quotas 端点附 diagnostics 供「我的中转站为什么不显示」自查。智谱 GLM / Z.ai 国内域钱包余额已接入（与订阅套餐双读）。项目归属优先用工作区标题命名。未计价的模型（目录外/无价）费用按 0 计，Hero 下会提示「N 个模型未收录计价」。

• 月度预算 + 分档提醒：预算条（开关 / 金额 / 进度，≥80% 琥珀、超支红脉）；跨 50 / 80 / 100% 各提醒一次；余额折算 CNY 低于阈值每天提醒一次。

• 订阅套餐额度：识别 llm-pi-ai 里的订阅类 provider（Kimi / Z.ai / OpenCode Go / MiniMax / OpenRouter / 小米 / 火山…），有额度 API 的实时显示剩余%与重置时间、用尽标红，无 API 标「未接入」；订阅通道模型费用记 0。档位月费与周期额度口径由内置知识库自动识别（如 OpenCode Go $10/月 + 周 $30 额度），有档位知识的标「自动识别」。MiniMax 用户注意：在国内开发者环境请使用 minimax-token-plan-cn provider id，自动对接 https://api.minimaxi.com；国际保留 minimax / minimax-token-plan，默认 https://www.minimaxi.com。需要自配中转或 staging 时可在该 provider 设置里覆盖 baseUrl。

  

• 自定义 Provider 余额：配置任意 HTTP 端点查余额（extract 支持常量 / 点路径 / add-subtract / divide，请求头 {{ENV}} 经凭据 seam）；DeepSeek / Kimi / 阶跃星辰 / 硅基流动内置官方余额，余额列按近 7 天日均折算「约可撑 N 天」。

• 真实用量聚合：服务端从会话日志实时聚合（增量缓存只重算写过的会话），单会话损坏容错、快照落盘回退；usage_stats 工具让模型自查今天 / 本月 / 当前会话 / 累计费用，还可查 bySite（按站点归组）与 relay（只看中转站）的汇总。

• 多语种 + 双币种：¥ / $ 切换随币种双语（USD→英文、CNY→中文，仅本插件生效）；费率表按所选币种换算。

• 模型健康 + 未收录标注：厂商接入状态圆点（绿 / 红 / 灰）；模型 id 不在目录时标「未收录」按兜底价估算、厂商自动推断（如 mi-mimo-2.5 → 小米）；估算价模型标注「估算价」。

• 会话明细 + 成本突增 + 热力图：按会话费用倒序（标题 / 项目 / 调用 / 费用 / 最后活跃）；每轮费用柱状图（最近 40 轮、金额贴柱顶、峰谷背景分带、超 2 倍红标归因）；月 / 年日历热力图（5 档色阶、悬停明细；年视图近 52 周、GitHub 风格），头部显示活跃天数 / 连续使用天数。

• 性能指标：每个模型首字延时（TTFT）均值 / P50 / P90、生成速度（tokens/s）、总延迟均值，另按北京时间小时聚合 TTFT 与速度曲线；请求从头到首个内容 chunk 测 TTFT，工具续写步骤无独立请求头时以 step/start 估算并标 estimated。统计 Tab 渲染为按模型性能表 + 按小时 TTFT/速度双折线。

• Token 统计洞察：独立「Token」分区——每日 token 堆叠按「输入（缓存未命中）/ 输入（缓存命中）/ 输出」三桶分色（含 reasoning 思考），模型 token 总量与占比，结构 KPI（缓存命中率 / 思考占比 / 输入输出比 / 峰值日）；按日 token CSV 与 JSON 导出。

  

• 数据导出 + 离线自包含：统计 Tab 导出按日 / 按会话 / 按站点 CSV 与全量 JSON；费用构成 / 工作区 / 会话明细分区可下钻（点项目行展开该项目的会话）；无图表库、无外部 CDN、纯设计令牌。

• 插件信息卡：设置 Tab 常驻「关于」卡——插件名、描述、作者（可跳 GitHub）、源码仓库、npm、许可证 MIT、版本号（服务端读自包 package.json，单一来源，发布自动正确）。

  

快速开始

在宿主 cordis.patch.yml 中加入：

- insert:
    - id: ui-usage-billing
      name: '@kenz1117/dsh-ui-usage-billing'

或通过包管理器安装：

npm install @kenz1117/dsh-ui-usage-billing

启动宿主后，侧边栏设置上方即出现计费入口。无需额外配置；sessionPersistence 可用时自动聚合真实用量。

工作原理

插件由服务端与浏览器端两部分组成：

浏览器端                                  服务端（Node）
  │                                        │
  ├─ GET /api/billing/usage-stats ────────▶ ├─ sessionPersistence 遍历持久化会话日志
  │                                        ├─ 按 request/header 归属模型
  │                                        ├─ token 按缓存命中 / 未命中分桶
  │                                        └─ 按实时单价表估算费用（人民币）
  ├─ GET /api/billing/pricing ────────────▶ ├─ 腾讯财经 / OpenRouter 实时汇率与模型价
  ├─ GET /api/billing/balance ────────────▶ ├─ DeepSeek 官方余额 API（凭据 seam 取 key）
  ├─ llm.models 健康探测 ─────────────────▶ └─ 返回聚合统计 JSON
  └─ 渲染仪表盘

• 服务端（src/index.ts）：注入 webServer、sessionPersistence 与 credentials，注册 GET /api/billing/usage-stats、/api/billing/pricing、/api/billing/balance、/api/billing/subscriptions、/api/billing/relay-quotas。聚合器按会话缓存折叠结果：一次 LLM 调用归属到其前置 request/header 记录的模型，token 拆分到缓存命中 / 未命中桶，日期按本机时区归天；日志文件 mtime+size 不变则直接复用缓存，只有写过的会话重新折叠，整份文档另有 5 秒 TTL 合并密集轮询。每个成功折叠的会话同时原子写入独立的持久用量账本，永久删除会话后历史费用与 token 仍保留。聚合逻辑见 src/aggregate.ts。
• 浏览器端（src/client/）：请求上述接口渲染仪表盘，通过 llm.models 探测各厂商连接状态。真实数据到达前显示全零空快照，不展示伪造样本。

主题协作

本插件不依赖任何主题包，可独立安装运行。仪表盘弹窗声明 billing.dashboard.decor 装饰孔位（head / hero / trend / models / footer 锚点），并将实时费用摘要注册为 ctx.billingMetrics 服务：主题插件（如 acid-zine）主动注入 MacDots / 胶带 / 撕角便签等装饰视觉、订阅费用数据渲染自己的贴纸层。插件与主题各自独立装卸——主题不存在时走默认视觉，billing 不存在时主题照常运行。

计费引擎

单价表（src/client/pricing.ts）采用原生币种存储：国内厂商直接录入人民币价格，国外厂商录入美元价格。费用统一以人民币计算与展示——美元模型按实时汇率折算，国内模型全程不经过汇率换算。启动时服务端拉取实时汇率与模型价（src/pricing-fetch.ts）：USD→CNY 优先腾讯财经行情（免 key、国内可达），失败依次降级 open.er-api 与内置默认值；之后每 6 小时后台刷新，单价表弹窗标注「今日汇率」与实时 / 内置徽标。金额与费率表的展示币种跟随用户所选：切 ¥ / $ 时把每条每百万 token 单价经 convertUnitPrice 按实时汇率换算到目标币种再显示（汇率缺失时回退原生币种）。

cost（CNY）= (missInput × p_input + cacheHit × p_cacheHit + output × p_output) / 10⁶
           —— 价格为原生币种；美元模型按实时 USD → CNY 汇率折算

统计中的 input 为总输入（cacheHit + cacheMiss），估算按命中 / 未命中分拆计价，避免重复计费。支持双档计费的模型按 DEFAULT_PEAK_SHARE（默认 0.5）混合高峰与低谷档；周末（北京时间周六 / 周日）全天按低谷价计费。

支持模型（2026-08-21 主流阵容，OpenAI 兼容系列）

¹ 讯飞、商汤、小米未公布按量单价，表内为估算价；这些模型走订阅通道（coding / token plan / opencode）时费用记 0，正式定价公布后自动校准。订阅通道与 pi-ai 内置提供方对齐（kimi-coding、zai-coding-cn、opencode、opencode-go、qwen/xiaomi 的 token-plan 各区域变体），可按 subscriptionProviders 配置覆盖。

新增模型：在 MODEL_CATALOG 追加条目，并在 src/client/pricing.ts 的 MODEL_KEY_ALIASES 中映射真实模型 id（聚合层与客户端渲染共用同一张表）。

HTTP API

对外 HTTP 接口与字段定义详见源码：GET /api/billing/pricing、/api/billing/balance、/api/billing/usage-stats、/api/billing/subscriptions、/api/billing/relay-quotas（见 src/index.ts、src/aggregate.ts、src/relay.ts）。其中 usage-stats 返回的 bySite 字段为按中转站归组后的用量分布（site:<origin> / direct:<provider> / unknown），unpricedModels 为未计价模型的 id 列表；relay-quotas 返回 quotas（各中转站额度）与 diagnostics（每条路由的 origin / kind 归类，供「为什么不显示」自查）。全部端点仅接受回环请求（peer socket 地址 + Host 头校验）。

配置

开发

环境要求：Node.js ^22.19 || >=24，pnpm。

pnpm install
pnpm --filter @kenz1117/dsh-ui-usage-billing bundle   # 构建 lib/index.js 与 lib/client.js
npx vitest run packages/client/ui-usage-billing/tests  # 单元测试

发布

本包为独立 npm 包，发布后即可被其他 DeepSeek Harness 宿主安装。

npm publish --access public

宿主通过 package.json 的 dsh.client 声明（platform: web）与 exports["./client"] bundle 自动发现浏览器端，无需注册中心登记。

Model Experience

无。本插件是纯 UI surface：不注册工具、不注入系统提示、不向会话日志写入模型可见事件，也不触及会话 KV 缓存；用量统计由服务端从既有会话日志聚合，日志内容由其他包各自负责。

Known Limitations and Deferred Work

• 余额查询已接入 DeepSeek / 月之暗面（Kimi）/ 阶跃星辰（StepFun）/ 硅基流动 / xAI / 智谱 GLM（Z.ai 国内域）：这些用标准 Bearer API key 即可查询。其余厂商因无公开余额接口或需非 Bearer 鉴权（小米 MiMo 走控制台 Cookie、商汤走 AccessKey 签名、MiniMax/字节豆包走额度制或 AK/SK），暂显示「未配置」；扩展点在 src/balance.ts（按厂商余额 API 增加查询器）。
• 中转站额度依赖上游私有 schema：New API / Sub2API 的接口字段未公开，读不出时标「未读出额度」而非臆造金额；若某中转站响应字段不同，需按 src/relay.ts 的解析器扩展。未知路由表示该路由在当前 provider 配置里已不存在（改过名 / 删除过），历史调用数据未丢，重新配置同名路由即可自动归位。
• 超支通知依赖浏览器 Notification：权限被拒绝或平台不支持时只有界面红色脉冲兜底，没有宿主级通知通道；通知上限为每天一次。
• 会话明细不可跳转：点击会话行不会打开对应会话（跨插件导航需要宿主会话选择通道）；会话数封顶 100 行、面板只显示前 20 行。
• 费用为目录价估算：讯飞 / 商汤 / 小米等未公布按量单价的模型使用估算价（特性表脚注 ¹），正式定价以厂商账单为准。
• 账本从首次成功聚合开始生效：升级前已经永久删除且不在旧快照中的会话无法恢复；手动删除 .dsh-usage-ledger.json 及其 .bak 会清空独立保留的历史。账本只保留本插件已经成功观测过的调用。

Contributors

• @ciphoo — MiniMax 国内域 Token Plan 订阅额度支持（PR #5）
• @fabulousyuann-tech — 会话删除后用量保留的持久 ledger 功能（PR #8）

许可证

MIT © 2026 KenZ (kenz1117)