dsh-plugin-usage-budget

DeepSeek Harness 的用量费用与预算插件：按峰谷时段价目把 token 用量换算成金额，提供会话费用读数、每日预算守卫、账户余额、逐轮价格与每条消息的用量行。

功能特性

界面	位置	数据来源
本会话用量费用	输入框状态栏（用量图标）	Host usageCost 投影，按每轮实际时段计价
预算 / 剩余 / 下一条预估	输入框状态栏（盾牌图标）	Host usageBudget 投影 + 全局账本
账户余额	会话顶部预设栏 + 预算弹窗	remote.account.getBalance（与 设置 → 账号与余额 同源）
逐轮价格 / 缓存节省	每条消息的「本轮用量」弹窗内	用该轮 token 桶匹配 usageCost.turns
每条消息的用量行	每条助手消息底部	usageCost.turns 里该轮的 tokens + 金额

• 峰谷计价：同一段对话里，峰时产生的用量按峰时价、优惠时段按优惠价，弹窗里能看到每个 token 桶各花了多少钱、时段拆分、缓存节省与合计。
• 全局预算：今日 / 滚动 7 天 / 自然月的花费按所有会话累计，持久化到本地账本；接近/超支时控件变色。
• 发送前预估：按当前上下文大小、会话实测缓存命中率与当前时段折扣，估算下一条消息的花费。
• 不改官方 DOM：每条消息底部的用量行走官方扩展点 conversation.chat.turnTail；输入框控件通过 conversation.composer.dock 槽位注册，与内置用量控件同 id、更低 priority，从而原位替换。

工作原理

• Host 侧（lib/index.js）注册两个 session projection：
  • usageCost：对每条已结算的 assistant/message 用量事件，用事件自身的时间判断峰谷时段，按 tokens / 1e6 × 单价 × 时段折扣 计价并累加，同时按轮累计（保留最近 120 轮）。
  • usageBudget：把每笔用量折成金额写入按本地自然日聚合的账本（$DSH_HOME/usage-budget/ledger.json），输出今日 / 本周 / 本月、预算等级与下一条预估所需要的单价表。
• 一次全局回填：首次运行（或账本版本变化）时读取所有已落盘的会话日志，按每条用量事件自己的时间与价目重建账本，之后只做增量；fork 会话的继承前缀（session/end-seed 之前）会被跳过，避免重复计费。
• 价目核心（lib/pricing.js）无任何依赖，时段判定用 Intl 处理 Asia/Shanghai 与 DST；账本核心（lib/budget.js）是纯函数（48 个单测），浏览器与 Node 都能跑。

安装

方式一：插件管理页（推荐）

1. git clone https://github.com/dddfuxi/dsh-plugin-usage-budget.git
2. 打开 DSH 侧栏 插件 → 添加插件 → 安装第三方插件：
   • 包名/Git 地址：粘贴上面的仓库地址；或
   • 本地目录：填 clone 下来的绝对路径。
3. 安装完成后启用它。侧栏「插件」里会出现名为 用量费用 的卡片（自带图标与中文描述）。

方式二：手动 bundle 安装

1. 复制本目录到 %USERPROFILE%\.dsh\profiles\<profile>\node_modules\dsh-plugin-usage-budget
2. profile 的 package.json：
   - dependencies 加 "dsh-plugin-usage-budget": "link:<本目录绝对路径>"
   - dsh.profile.bundles 追加 "dsh-plugin-usage-budget"
3. HMR 会自动重组；页面未更新时刷新一次；没有 HMR 的 profile 需要重启。

profile 的 cordis.patch.yml 里只放 override（预算数字），不要手写 insert 行：

- id: usage-budget
  name: dsh-plugin-usage-budget
  config:
    dailyBudget: 30
    weeklyBudget: 100
    monthlyBudget: 200
    warnAt: 0.75

配置

键	默认	说明
dailyBudget	20	日预算（元）；0 关闭
weeklyBudget	0	滚动最近 7 天预算（元）；0 关闭
monthlyBudget	0	自然月预算（元）；0 关闭
warnAt	0.8	花费/预算 ≥ 该比例时进入告警色（0–1）
assumedOutputTokens	600	发送前预估使用的输出 token 数
assumedCacheReadRatio	null	null = 用会话实测缓存命中率；0..1 可强制
pricing	—	可选：覆盖价目（结构见下）；省略则用内置默认价目
timezone	Asia/Shanghai	账本与时段判定所用时区

预算数字也可以在 设置 → 通用设置 → 用量预算 里直接改，回车或失焦即保存、立即生效。

价目与时段

内置默认价目为 人民币元 / 100 万 token（2026-11 取自 DeepSeek 官方价格页）：

模型	缓存命中	缓存未命中	输出
deepseek-flash	0.04	2	8
deepseek-v4-pro	0.30	9	27

峰时为北京时间周一至周五 09:00–12:00、14:00–18:00，其余时间（含周末）一律 5 折；DeepSeek 不单列缓存写入价格，故 cacheWrite: 0。

pricing:
  currency: CNY
  timezone: Asia/Shanghai
  models:
    deepseek-flash: { cacheRead: 0.04, cacheWrite: 0, input: 2, output: 8 }
    deepseek-v4-pro: { cacheRead: 0.30, cacheWrite: 0, input: 9, output: 27 }
  fallback: { cacheRead: 0.04, cacheWrite: 0, input: 2, output: 8 }
  windows:
    - { id: offpeak, label: { zh: 优惠时段, en: Off-peak }, start: "00:00", end: "09:00", days: [1,2,3,4,5], factor: 0.5 }
    - { id: offpeak, label: { zh: 优惠时段, en: Off-peak }, start: "12:00", end: "14:00", days: [1,2,3,4,5], factor: 0.5 }
    - { id: offpeak, label: { zh: 优惠时段, en: Off-peak }, start: "18:00", end: "24:00", days: [1,2,3,4,5], factor: 0.5 }
    - { id: offpeak, label: { zh: 优惠时段, en: Off-peak }, start: "00:00", end: "24:00", days: [6,7], factor: 0.5 }

金额是估算，不是账单：按可配置价目换算，峰谷按事件结算时刻判定；中国法定节假日未建模（窗口只支持星期），需要精确时请按实际账单为准。

测试

npm test
# 等价于 node --test test/budget.test.mjs test/pricing.test.mjs

覆盖时段边界、跨午夜、时区与 DST、逐桶金额、缓存节省、未知模型回退、账本滚动与脏数据容错。

已知限制

• 只统计已结算的 assistant/message 用量；被中断、重试后未落盘的流式请求可能少算。
• 全局回填只发生一次、范围约最近 130 天；之后导入更早的会话日志需要删除账本让它重新回填。
• 预算只是「守卫 + 提醒」，不拦截发送（DSH 的发送路径没有对外拦截槽位）。
• 发送前预估是启发式：输入 token 取上下文压力投影，输出长度取配置假定值。

许可

MIT © 2026 fuxi

本插件合并了早期的 dsh-plugin-usage-cost（费用读数）与 dsh-plugin-account-balance（账户余额）两个自用小插件的能力，并新增了预算守卫与逐轮价格。