配置

全部字段都写在插件行的 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

字段	默认	说明
`apiKeyEnv`	`DEEPSEEK_API_KEY`	取 API Key 的凭据引用（环境变量名）
`apiOrigin`	`https://api.deepseek.com`	余额端点 origin；必须 https（loopback 例外）
`balancePath`	`/user/balance`	余额端点路径
`refreshIntervalMs`	`60000`	轮询平台的周期
`requestTimeoutMs`	`10000`	单次余额请求超时
`settlementLagMs`	`300000`	平台读数滞后于用量的上界；本地累计从此前移起算
`rateWindowMs`	`1800000`	瞬时消耗速率的观测窗口
`calibrationWindowMs`	`21600000`	校正系数 `k` 的学习窗口
`correctionSamples`	`9`	取中位数的近期候选数
`probeSamples`	`5`	给出日历建议所需的探针样本数
`retentionMs`	`604800000`	读数与 token 桶的保留时长（7 天）
`staleAfterMs`	`180000`	多久没有新读数就把快照标为过期
`etaCapMs`	`31536000000`	可用时长上限，超过显示 `> 1 年`
`minBurnPerHour`	`0.01`	低于此速率视为闲置，不报 ETA
`minPredictedSpend`	`0.01`	量化步长；也是「大额下降」的判定阈值
`preferredCurrency`	`auto`	钱包偏好：`auto` 优先有余额的 CNY，其次 USD
`priceCurrency`	`CNY`	价目表计价币种；与钱包不一致时退出价目表路径
`priceTable`	`deepseek-flash` `deepseek-v4-pro`	各路由的高峰价，单位「币种 / 百万 token」
`offPeakFactor`	`0.5`	空闲时段相对高峰的倍率
`peakDays`	`[1,2,3,4,5]`	承载高峰时段的 ISO 星期
`peakWindows`	`09:00-12:00` `14:00-18:00`	高峰时段
`priceTimeZone`	`Asia/Shanghai`	高峰时段所用的时区
`holidays`	`[]`	法定节假日（`YYYY-MM-DD`），优先级最高
`makeupWorkdays`	`[]`	调休补班日，同样最高优先级
`treatMakeupWorkdaysAsPeak`	`false`	调休补班日是否按高峰计价
`holidaySourceEnabled`	`false`	是否启用远程节假日源
`holidaySourceUrl`	`timor.tech`	远程源 URL 模板，必须含 `{year}`
`holidaySourceFormat`	`auto`	远程载荷结构：`auto` / `timor` / `holiday-cn`
`holidayRefreshIntervalMs`	`604800000`	远程源正常刷新周期
`holidayMissingYearRetryMs`	`86400000`	当年日历尚未发布时的重试周期
`holidayTimeoutMs`	`8000`	远程源请求超时
`weights`	`1 / 1 / 0.1 / 4`	价目表未覆盖路由的相对权重
`etaIntegratesSchedule`	`true`	ETA 是否跨峰谷切换积分
`etaWarnMs`	`86400000`	低于此可用时长状态点转橙
`etaCriticalMs`	`14400000`	低于此转红
`clientPollIntervalMs`	`15000`	浏览器读取快照的周期
`persist`	`true`	是否把读数与 token 桶落盘到 `$DSH_HOME/dsh-balance/`
`historyRoot`	`''`	落盘目录覆盖，空表示用默认目录
`allowLoopbackHttp`	`false`	是否允许 http 的 loopback 端点（本地开发用）

几条语义：

平台滞后与 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 桶，比截图清楚得多。

@zzxxxxxx/dsh-balance

安装

说明文档

配置