DSH 余额与消耗面板（dsh-balance-stats）


一个给 DeepSeek Harness（DSH）用的插件：在左侧边栏和设置页里，实时显示 DeepSeek 账户余额与本机所有会话的 token 消耗，并且把每一分钱是怎么算出来的摊开给你看。

用一句话说：官方账单收了多少、你花在哪了、还能用多久，一个面板讲清楚。

---

✨ 功能一览

1. KPI 盘头（两处常显）

四个数字的含义：

• 余额：来自 DeepSeek 官方接口，旁边红/黄/绿状态灯（余额告急自动变红）
• 续航：余额 ÷ 近 7 天日均花费 = 按现在的用法还能用多少天
• 今日 / 本月：真实逐日统计，和官方账单同口径（含峰谷计价）

侧边栏收起（窄轨）时自动变成只显示状态灯，悬停可看完整数字。

2. 🚦 预算制动

设置一个每日预算上限（如 ¥20），"今日"卡片会出现进度条：

• 用掉 80% → 变黄提示"注意控制"
• 超预算 → 变红提示"已超 ¥X"

跑长任务前扫一眼，比看余额有用得多——余额 97 元不等于可以一天烧 50。

3. 🩺 缓存命中率健康提示

命中率 = 缓存命中 ÷（命中+未命中+缓存写入）。低于 50% 自动弹提示：

> 未命中单价是命中的 20~60 倍（如 pro 空闲期 ¥4.5/M vs ¥0.15/M），低命中率意味着大量重复计费。

会按工作区单独体检：比如「E:\乐乐课堂」命中率 41% 会被单独点名。这是省钱的第一个杠杆。

4. 🧮 计算步骤明细（与官方对账）

每一分钱都按官方口径逐条列出：

费用 = Σ [ (未命中输入 + 缓存写入) × 未命中价
       + 缓存命中 × 命中价 + 输出 × 输出价 ] ÷ 1,000,000

deepseek-v4-pro
  [高峰时段] 计费 ¥0.0032
    输入·未命中  700 × ¥3.0/M  = ¥0.00210
    输入·缓存写入 60 × ¥3.0/M  = ¥0.00018
    ...

• 按每个请求发生的时刻区分高峰/空闲/旧价三档计价（凌晨 2 点的请求按空闲价，上午 10 点的按高峰价）
• 压缩摘要调用也计入（长对话自动压缩历史时的那次模型调用，官方账单收钱，本插件补上了官方统计条漏掉的这块）
• 整卡、逐模型都可点击折叠

5. 📄 官方定价与扣费规则

内置官方价格表（旧价/空闲/高峰三档）、官方定价说明与扣费规则原文，附直达官方定价页和用量账单页的链接，对账时点开即查。

6. 📋 会话明细（带筛选与工作区）

• 每个会话显示所属工作区（C:\Users\hhy99、E:\乐乐课堂……）和标题（与 Web 界面完全一致）
• 筛选：工作区 下拉 + 时间（全部/今天/昨天/本周/本月）+ 标题或 ID 搜索
• 选时间后，每个会话显示的是它在该时段内花的钱（不是从出生到现在的累计），汇总行同步——比如选"今天"，就能看到"今天每个会话各花了多少、合计多少"，与 KPI 的"今日"一致
• 会话改名实时热更新（订阅了 Web 界面的推送流，无需刷新）

7. 🗂️ 历史会话完整统计

磁盘上已持久化、但没有打开过的旧会话同样纳入统计——KPI、计算明细、筛选列表覆盖完整历史，而不是只有最近打开过的几个。

8. 🔍 差额说明（和官方账单差几分钱？）

插件会自动统计两类"官方计费但本地无法计价"的调用：

> 另有辅助调用未计入：标题生成 N 次 · 网页搜索 M 次 —— 与官方账单的差值通常来源于此

原因详见下方「数据准确性说明」。

---

🚀 安装（手把手，零基础也能装）

整个过程约 5 分钟，一共五步。以 Windows 为例，macOS/Linux 把路径写法换一下即可。

第一步：确认你已经有 DSH

打开终端（PowerShell），运行：

dsh web

能看到浏览器打开 DeepSeek Harness 的网页界面（默认 http://127.0.0.1:3080），说明环境就绪。

• 如果提示 dsh 不是命令：先安装 DSH 本体

``powershell npm install -g @deepseek-ai/dsh dsh web ``

• 另外确认 pnpm 存在（安装插件会用到）：

``powershell pnpm --version # 没有输出版本号就运行: npm install -g pnpm ``

> 先把这个终端窗口里的 dsh web 停掉（按 Ctrl+C），等装完插件再重新启动。

第二步：拿到插件代码（二选一）

方式 A：会 git 的人

git clone https://github.com/hhy66/dsh-balance-stats.git

方式 B：不会 git 的人（推荐）

1. 浏览器打开本仓库页面 2. 点绿色 Code 按钮 → Download ZIP 3. 把下载的压缩包解压到任意一个你找得到的地方，例如 C:\dsh-plugins\dsh-balance-stats

> 国内网络如果 clone 失败，先给 git 配代理（把端口换成你自己的代理端口）： > ``powershell > git config --global http.https://github.com.proxy http://127.0.0.1:7897 > ``

第三步：安装插件

在终端里运行下面这条命令（把路径换成你实际的插件目录）：

dsh plugin --profile web add "C:\dsh-plugins\dsh-balance-stats"

看到类似 + dsh-balance-stats link:... 的输出就是安装成功了。这条命令做了两件事：把插件登记到你的 DSH 配置里，并自动装好它需要的依赖。

第四步：重启并刷新

1. 终端里重新运行 dsh web 2. 浏览器里按 Ctrl+Shift+R 强制刷新页面

第五步：验证是否装好

• 左侧边栏底部（"设置"一行的上方）出现一行余额数字 ✅
• 打开 设置 → 余额与消耗，能看到完整面板 ✅
• 如果余额位置显示"未配置 DEEPSEEK_API_KEY"：你的密钥还没放进 DSH。把密钥加到 C:\Users\你的用户名\.dsh\.credentials.yaml 里（DEEPSEEK_API_KEY: sk-...），保存后重启 dsh web 即可

---

🆘 安装常见问题

Q：面板打不开 / 提示找不到 zod？

个别安装方式下依赖 zod 不会被自动装进插件目录。把 DSH 自带的 zod 拷一份过去即可：

# 先看 DSH 装在哪个全局目录
npm root -g
# 例如输出 C:\Program Files\nodejs\node_modules，那么执行：
Copy-Item -Recurse "C:\Program Files\nodejs\node_modules\@deepseek-ai\dsh\node_modules\zod" "你的插件目录\node_modules\zod"

拷贝后重启 dsh web + 硬刷新。

Q：dsh plugin 提示找不到 pnpm？

npm install -g pnpm

Q：安装依赖时网络很慢 / 失败？

换国内 npm 镜像再试：

npm config set registry https://registry.npmmirror.com
dsh plugin --profile web add "你的插件目录"

Q：面板是空白的？

先 Ctrl+Shift+R 硬刷新；还不行就重启 dsh web；仍不行按 F12 打开控制台，把红色报错发到 GitHub Issues。

🔄 以后怎么更新插件

普通用户：重新下载最新代码（git pull 或重新 Download ZIP 覆盖旧目录），然后重跑第三步和第四步即可。

插件作者本人：本机有一份不公开的《维护红线》文档（在插件目录的 REDLINE.md，已排除出版本库），按它执行。

🗑️ 卸载

dsh plugin --profile web remove dsh-balance-stats

重启 dsh web 生效。

---

⚙️ 配置

编辑 ~/.dsh/profiles/web/cordis.patch.yml（也可直接改插件自带的 cordis.patch.yml 默认值）：

- id: dsh-balance-stats
  config:
    refreshIntervalMs: 300000   # 余额查询间隔(毫秒)，默认 5 分钟
    warningThreshold: 10        # 余额低于此值 → 黄灯(元)
    dangerThreshold: 5          # 余额低于此值 → 红灯(元)
    dailyBudget: 20             # 单日预算上限(元)；0 = 关闭预算制动
    currency: CNY
    prices:                     # 非 V4 模型的静态单价(元/百万 token)
      deepseek-chat: { cacheHit: 0.5, cacheMiss: 2, output: 8 }

改完重启 dsh web 生效。

---

🧾 数据是怎么算的（实现方式，通俗版）

1. 余额：调用官方接口 GET /user/balance，用你 ~/.dsh/.credentials.yaml 里的 DEEPSEEK_API_KEY 鉴权。密钥只在你电脑上使用，浏览器全程接触不到，请求只发往 api.deepseek.com。 2. 单价：内置官方定价页的完整价格表——2026-08-17 起实行峰谷计价（高峰 9:00-12:00 / 14:00-18:00 全价，其余时段半价），之前的请求按旧价。 3. 用量：读取 DSH 每个会话的本地日志，按"事件发生时刻"逐个请求计价（含缓存命中/未命中/写入/输出的分桶）；压缩摘要调用也计入（官方账单计费，官方自己的统计条反而漏了它）。 4. 历史会话：通过 DSH 的持久化接口枚举磁盘上的全部会话，逐个折叠统计并按修订号缓存（不会重复算）；扫描在启动后延迟 2 秒后台进行，不影响打开速度。 5. 会话标题/工作区：与 Web 界面同一数据源，你改名会实时同步。 6. 实时性：30 秒轮询 + 会话推送流触发的防抖刷新（约 1 秒内响应变化）；页面从后台切回立即刷新。

⚠️ 数据准确性说明（和官方账单的已知差值）

本插件统计的是能本地重建的全部用量：主请求 + 压缩摘要，约占官方账单的 99.6%。剩下两类调用官方账单计费、但 DSH 的本地日志不记录其用量（源码如此，官方统计条也看不到）：

• 标题生成：DSH 给每个会话自动起标题时的一次小模型调用
• 网页搜索：搜索工具直连 DeepSeek API 的调用

因此插件只能精确计数这两类调用（消耗卡里显示次数），无法算出它们的精确金额——这是官方账单与本地统计之间最后几毛钱差值的来源，属于 DSH 自身的记录缺口。若 DeepSeek 官方将来开放用量 API，即可完全对齐。

另外两点口径说明：

• 峰谷时段归属按本地记录的事件时间判断，跨时段边界的极少数请求（如 11:59:59 发起）可能与官方归账差几秒
• 金额为本地估算，一切以 platform.deepseek.com/usage 的官方账单为准

---

❓ 常见问题

Q：和官方账单差几分钱？ 见上方「数据准确性说明」——差值来自标题生成和网页搜索这两类"计费但不落用量"的调用，插件里已显示它们的次数，可在官方账单里逐条核对。

Q：为什么时间筛选后，旧会话显示 ¥0.00？ 因为筛选问的是"这个时段花了多少"，而不是"它累计花了多少"。今天没花它的钱，就诚实显示 0（灰色弱化）。想看累计就选"全部"。

Q：打开面板第一次要等几秒？ 首次会扫描磁盘上的历史会话（后台进行），面板会显示"扫描历史会话中…"；之后每次打开都是瞬时。

Q：会话标题和侧边栏不一致？ 不会——两者读的是同一份数据，且改名实时同步。如果出现不一致，硬刷新浏览器（Ctrl+Shift+R）。

Q：会泄露我的 API 密钥吗？ 不会。密钥只存在于宿主进程内存和你的凭据文件里，插件只在宿主机端用它请求 api.deepseek.com，浏览器端、日志、界面中都不出现。

---

📦 技术栈与许可

• 基于 DSH 的 Cordis 插件体系：宿主端（Node.js）+ 浏览器端（React），通过官方插槽（设置页 settings.section、侧边栏 sidebar.footer.action）接入，不侵入界面
• 依赖：zod（数据校验）
• 许可：[MIT](./LICENSE)

---

本插件为个人使用而写，按 MIT 协议开放；官方账单始终是最终依据。