dsh-usage-monitor

English | 简体中文

在 DeepSeek Harness（DSH）界面里直接显示 DeepSeek API 的官方定价、会话用量花费、累计花费和账户余额。

截图取自真实的 DSH Web 页面（用 Playwright 驱动本机 Chrome 渲染），只把插件接口替换为演示数据——界面结构、插件 DOM 与样式都是真实的；账户余额、会话用量与会话名均为演示值。

功能

• 账户余额：查询 GET https://api.deepseek.com/user/balance，显示总余额、充值余额和赠金；默认 60 秒缓存，可手动刷新。
• 本会话花费：显示宿主账本里已计价的金额——按各阶段实际使用的模型与时段分别增量计价，因此切换模型时数字不会跳变；账本尚未记录该会话时退回本地估算，并在界面上标注「估算」。
• 按模型明细：账本按模型分桶记录 token 与金额，面板分别列出 Flash 与 V4-Pro 各自用掉多少、花了多少。
• 累计花费：本地账本记录跨会话用量，采用增量计价，跨高峰/空闲时段也能准确累计；用量由常驻的 dock 条上报，不打开面板也会持续记录。
• 官方定价：内置 deepseek-flash 与 deepseek-v4-pro 单价，自动区分高峰/空闲时段。
• 两个入口：
  • 对话主视图新增「用量」Tab，展示完整面板；
  • 输入框上方 dock 条常驻显示余额、本会话花费、当前模型单价和计价时段。
• 隐私安全：不监听公网，不写密钥；详细说明见下方「安全与隐私」。

截图

完整用量面板

输入框 dock 条

安装

前置条件

• 已安装 DSH，例如 @deepseek-ai/dsh；
• 使用 web profile；
• 账户可用 DeepSeek API key，例如已经在 ~/.dsh/.credentials.yaml 中配置，或通过环境变量 DEEPSEEK_API_KEY 提供。

1. 安装插件

dsh plugin --profile web add github:liyiersan/dsh-usage-monitor

也可以从本地目录安装：

dsh plugin --profile web add /path/to/dsh-usage-monitor

本仓库声明了 dsh.bundle.patch。DSH 支持该 manifest 时会在安装时自动应用 cordis.patch.yml，把插件插入 profile 配置树，通常不需要手动改配置。

2. 手动安装 / 兜底

如果当前 DSH 版本没有自动应用 bundle patch，编辑 $DSH_HOME/profiles/web/cordis.patch.yml（默认 ~/.dsh/profiles/web/cordis.patch.yml），加入：

- insert:
    - id: usage-monitor
      name: '@local/dsh-usage-monitor'

3. 确认 API key 可用

插件不会自己保存 key，它会通过 DSH credentials 服务解析 DEEPSEEK_API_KEY，失败时回退到进程环境变量。

4. 重启 DSH

dsh web

打开任意会话，即可在顶部看到「用量」Tab，并在输入框上方看到用量 dock 条。

卸载

dsh plugin --profile web remove @local/dsh-usage-monitor

如果你之前是手动加入 insert 条目，请再从 cordis.patch.yml 中删除；自动 bundle 安装通常由 dsh plugin remove 一并处理。可选手动删除本地账本：

rm -rf "$DSH_HOME/usage-monitor"

定价口径

单位：元 / 百万 tokens。高峰时段为北京时间周一至周五 09:00-12:00、14:00-18:00；空闲时段价格为高峰的一半。

模型	时段	缓存命中	缓存未命中	输出
DeepSeek-V4.1-Flash	空闲	0.02	1	4
DeepSeek-V4.1-Flash	高峰	0.04	2	8
DeepSeek-V4-Pro	空闲	0.15	4.5	13.5
DeepSeek-V4-Pro	高峰	0.3	9	27

计费规则：

• cacheRead（缓存命中输入）按缓存命中单价；
• uncachedInput（缓存未命中输入）按未命中单价；
• output 按输出单价；
• cacheWrite（写入缓存）官方未单列，本项目按未命中单价保守计算；
• 模型名包含 pro、chat、reasoner 时归入 V4-Pro；包含 flash 归入 Flash；无法识别时按 Flash 兜底并在界面标注。

token 数量来自提供方的精确用量；金额由本地账本按增量计价得出，与官方账单口径一致，可能有极小取整差异（时段归属按上报时刻判定）。DeepSeek 价格可能调整，更新时请同时修改 lib/pricing.js 和 lib/client.js 中内联的定价副本。

工作原理

DSH Host (Node)
  lib/index.js ── GET /user/balance ──> api.deepseek.com
       │
       ├─ GET  /usage-monitor/data   ──> browser client
       └─ POST /usage-monitor/report <── browser client
                                      │
                                      ├─ conversation.view「用量」Tab
                                      └─ conversation.input.dock dock 条

• lib/index.js：宿主半。解析凭据、查询余额、维护本地账本（按会话 + 按模型分桶，增量计价）、暴露本地 HTTP 端点。
• lib/client.js：浏览器半。注册 conversation.view 和 conversation.input.dock 两个槽位；dock 条是常驻上报点，面板另外展示账本的分桶明细。
• lib/pricing.js：纯函数计费引擎，供宿主和测试使用。
• 客户端内联了一份定价副本，避免浏览器运行时无法直接 import 服务端模块；修改价格时两处都要改。

目录结构

dsh-usage-monitor/
├── lib/
│   ├── client.js      # 浏览器插件 bundle
│   ├── index.js       # 宿主插件
│   └── pricing.js     # 计费引擎
├── scripts/
│   ├── client-check.mjs
│   ├── inspect-session.mjs
│   └── smoke.mjs
├── test/
│   └── pricing.test.mjs
├── docs/screenshots/
├── package.json
├── README.md
├── README.en.md
└── LICENSE

开发与测试

npm test                 # 定价引擎单元测试
npm run test:client      # 客户端 bundle 离线校验
node scripts/smoke.mjs   # 服务端冒烟测试（会查询真实余额接口）

scripts/smoke.mjs 会使用临时 DSH_HOME，不会污染真实账本；它会从本地 DSH 凭据文件或环境变量读取 key，但只打印 key 长度，不打印 key 本身。

改动客户端后只需刷新页面（DSH 0.1.5-rc.1 实测）：/plugins/<id>/client.js 由 DSH 的客户端模块表提供，该表在 DSH 运行时监听插件文件，内容变化会重新计算 bundle 的 rev 并按新 URL 提供（dsh-client-modules 的 rebuilt() 钩子），所以刷新浏览器页面就能拿到新副本，不必重启 DSH。若你在 DSH 停止时修改了 lib/client.js，下次启动本就会读取新内容；验证时如仍看到旧行为，先确认浏览器加载的 bundle URL 里 rev= 是否已变化。

注意：本插件的服务端半（lib/index.js）不会热更新，改动它必须重启 DSH。

兼容性

当前版本在 DSH 0.1.5-rc.1 的 web profile 上验证（2026-09），同时兼容 0.1.1-rc.2（客户端槽位与模型解析接口一致）。DSH 客户端 API 仍可能变化，升级 DSH 后如发现槽位或模型解析接口变化，请提交 issue 或 PR。

安全与隐私

• 不收集、不上传遥测数据；
• 插件本身不保存 API key；key 仅由 DSH credentials 服务或进程环境变量提供；
• 余额查询只发生在宿主侧，目标为 https://api.deepseek.com/user/balance；
• 本地账本保存于 $DSH_HOME/usage-monitor/ledger.json，只记录 session id、token 用量及按模型分桶的金额，不会提交到仓库；
• /usage-monitor/* 端点随 DSH webServer 监听回环地址；/usage-monitor/report 要求 Content-Type: application/json，用于降低 CSRF 风险；
• 建议开源使用者不要把自己本地账本、凭据文件或包含个人路径的日志提交到 Git。

贡献

欢迎提交 issue 和 PR。提交前请尽量运行：

npm test
npm run test:client

License

MIT