dsh-balance

DeepSeek Harness 的余额读数 —— 用本机 token 消耗实时推算 API 余额，并估算还能用多久（不过估不准确）。

English | 中文

简介

• 锚点而非读数：平台结算滞后 1~5 分钟，照抄读数会出现「干活时数字不动」。每次读数只当周期锚点，显示的是 锚点 − k × 本机已消耗，所以数字随 token 实时递减。
• 用量时钟：在 T 取得的读数只反映 T − settlementLagMs 之前的用量，因此本地累计从那个截止时刻起算；不做这个位移，最后几分钟会被重复扣除。
• 分档计价 + 单一校正系数：按官方高峰价分档（缓存命中 / 未命中 / 输出），再用近期余额下降的中位数学一个标量 k，把过期价目表、未收录的模型、统一折扣一并吸收。
• 只累加下降：充值抬高钱包但不贡献任何数，所以不污染 k、不作废校准窗口；成块结算只计一次。没有本地用量的大额下降单列为「非用量调整」，不算你的花费。
• 峰谷按发生时刻判：高峰 = 北京时间周一至周五 09:00–12:00、14:00–18:00（不含法定节假日），其余时段半价；ETA 跨时段积分，否则 17:50 起算会漏掉 18:00 开始的半价，偏小最多 2×。
• 可被数据推翻的日历假设：调休补班日按官方字面口径算空闲；跨越它的样本进独立探针，与主系数稳定相差约两倍时面板给出提示，不自动改配置。
• 输入框下方的读数 pill：紧跟宿主自带的 token 统计，显示预估余额与可用时长，点开是明细面板。

host 半独占凭据与出网，只把一份快照经两条精确路由交给浏览器半：凭据从不进入浏览器，两条路由也都参与宿主的 Host/Origin 与 cookie 信任围栏。出网只有两个目标——余额端点，以及你显式启用时的节假日源。

安装

要求：DeepSeek Harness ≥ 0.2.0-rc.1，Node ^22.19.0 || >=24.0.0。

从 npm 装（推荐）：

dsh plugin --profile  add @zzxxxxxx/dsh-balance

从源码装 / 本地开发：

git clone https://github.com/zzzxxxxxxxxxx/dsh-balance && cd dsh-balance
npm install        # 构建依赖，首次需要网络
npm run build      # 产出 lib/（插件入口；仓库里不提交构建产物）

dsh plugin --profile  add "$PWD"

从打好的 tarball 装（npm pack 的产物已含 lib/，无需构建）：

dsh plugin --profile  add ./zzxxxxxx-dsh-balance-0.1.0.tgz

装完后重启 dsh（profile 在启动时组合）。

• API Key 取自凭据引用 DEEPSEEK_API_KEY，与内置 deepseek-official provider 是同一个引用——模型能用就说明它已配好；也可在 设置 → 模型、$DSH_HOME/.credentials.yaml 或导出环境变量里设置。
• 更新：源码装则 git pull && npm install && npm run build，tarball 装则重新 add 一次。之后都要重启。
• 卸载：dsh plugin --profile remove @zzxxxxxx/dsh-balance，再重启。
• 浏览器半边（读数 pill）只在带 Web 界面的 profile 里出现；其他 profile 下 host 半照常轮询，只是没人看。
• ⚠️ npm 上无 scope 的 dsh-balance 是另一个同类插件，请按 scope 安装。
• 开发：npm run typecheck、npm test（87 个用例，不访问网络）、npm run build、npm run gen:holidays（重新生成节假日种子，唯一会真实出网的一步）。

用法

• pill：显示 ¥36.35 · 2 天 4 小时——预估余额与估算可用时长。状态点平时绿，低于 etaWarnMs 转橙，低于 etaCriticalMs 或余额耗尽转红，未标定或连不上时灰。
• 面板：点 pill 向上展开，把三个数字分开呈现——平台读数、本机推算已消耗、当前预估余额——另有当前时段与下次切换、消耗速率及其来源、今日与最近一小时、非用量调整、校正系数与候选数、节假日日历来源。
• 立即刷新：面板右下角的按钮请 host 立刻轮询平台一次，再重读快照。
• 没有斜杠命令，也没有设置页：本插件只做读数，配置见下节。
• 服务端只有两条路径：GET /dsh-balance/state（快照）与 POST /dsh-balance/refresh（请求一次轮询）。

配置

全部字段都写在插件行的 config: 里（本插件没有设置页），改完需重启。下面是完整的默认值：

- insert:
- id: dsh-balance
name: '@zzxxxxxx/dsh-balance'
config:
apiKeyEnv: DEEPSEEK_API_KEY
apiOrigin: https://api.deepseek.com
balancePath: /user/balance
refreshIntervalMs: 60000          # 轮询平台的周期
requestTimeoutMs: 10000
settlementLagMs: 300000           # 平台读数滞后于用量的上界
rateWindowMs: 1800000             # 瞬时消耗速率的观测窗口
calibrationWindowMs: 21600000     # 校正系数 k 的学习窗口
correctionSamples: 9              # k 取中位数的近期候选数
probeSamples: 5                   # 给出日历建议所需的探针数
retentionMs: 604800000
staleAfterMs: 180000
etaCapMs: 31536000000
minBurnPerHour: 0.01
minPredictedSpend: 0.01           # 量化步长，也是「大额下降」阈值
preferredCurrency: auto           # auto | CNY | USD
priceCurrency: CNY
priceTable:                       # 高峰价，单位「币种 / 百万 token」
deepseek-flash: { input: 1, cacheRead: 0.02, output: 4 }
deepseek-v4-pro: { input: 4.5, cacheRead: 0.15, output: 13.5 }
offPeakFactor: 0.5
peakDays: [1, 2, 3, 4, 5]
peakWindows: ['09:00-12:00', '14:00-18:00']
priceTimeZone: Asia/Shanghai
holidays: []                      # ['2027-01-01', ...]
makeupWorkdays: []                # ['2027-02-20', ...]
treatMakeupWorkdaysAsPeak: false
holidaySourceEnabled: false       # 第二个出网目标，默认关闭
holidaySourceUrl: https://timor.tech/api/holiday/year/{year}
holidaySourceFormat: auto         # auto | timor | holiday-cn
holidayRefreshIntervalMs: 604800000
holidayMissingYearRetryMs: 86400000
holidayTimeoutMs: 8000
weights: { uncachedInput: 1, cacheWrite: 1, cacheRead: 0.1, output: 4 }
etaIntegratesSchedule: true
etaWarnMs: 86400000
etaCriticalMs: 14400000
clientPollIntervalMs: 15000
persist: true
historyRoot: ''
allowLoopbackHttp: false

几条语义：

• 平台滞后与 ETA：ETA 的分子来自锚点，唯一残差是分子本身滞后，所以它恰好偏小 settlementLagMs（默认 5 分钟以内），不会随滞后漂移。
• 充值与用量撞在同一个轮询间隔：那一对读数净上升，隐藏的用量看不见——有界（≤ 一个间隔的花费），并被中位数摊薄。面板上的「非用量调整」只统计没有本地用量解释的大额下降。
• 校正系数需要几笔下降才稳定：在此之前速率退化为按余额差（6 小时窗口）估算，状态点转灰、面板标注「未标定」。价目表准的时候 k 会在 1.0 附近——它本身就是最好的自检。
• 每个会话的第一轮不计入：首次观测只用来播种基线，否则恢复会话会把整段历史重新计费。
• 路由来自投影，不是会话事件：session/event 按 scope 过滤，挂在 profile 层的插件收不到 request/context，所以模型是从 modelSelection 投影主动拉取的（对加载前就已固定的选择，变化事件永远不会触发）。
• 价目表币种必须与钱包一致（默认 CNY）：不一致时退出价目表路径、按 weights 计价，并在面板标出。
• 节假日日历需要年度维护：开 holidaySourceEnabled，或在新一年公布后重跑 npm run gen:holidays 重新生成种子。未发布的年份按未知处理（绝不记成「无节假日」——那会把整年工作日按高峰计价且不再重试），重试周期缩短为每天，并在面板提示。
• 调休日口径是对官方散文的解读：高峰的前置条件是「周一至周五」，而调休日按构造就是周六/周日，故默认算空闲；因为这是解读而非实测，才用探针把它变成可被数据推翻的假设，且提示不会自动改配置。
• 两条路由参与宿主信任围栏：自定义 host 路由不会自动进入闸门，所以本插件主动请求裁决（Host/Origin + cookie）；connection 是必需注入，缺了插件就不加载，围栏不会静默失效——代价是服务短暂不可用时返回 503，而不是不带围栏地照常作答。
• 本插件仍在早期，可能还有 bug。遇到问题请到 Issues 反馈，并附上面板上的读数与 $DSH_HOME/dsh-balance/history.json——它记录了读数与 token 桶，比截图清楚得多。