一个把「官方定价 / 本会话花费 / 累计花费 / 账户余额」直接嵌进 DeepSeek Harness（DSH）界面的开源插件，麻雀虽小，工程细节却相当讲究。
一、痛点：API 账单是个黑盒
用 DeepSeek API 做开发、跑 Agent、写长文，最让人心里没底的一件事就是——钱到底花在哪了。
官方控制台能查到余额和账单，但那是「事后结算」：你得切出去、登录、等刷新，才能知道刚才那一轮对话消耗了多少。而在 DSH 这种把模型当「工作台」用的界面里，你一天可能开十几个会话、来回切 Flash 和 V4-Pro，烧钱的速度和模型档位强相关——这时候「边聊边看花费」就成了一件很刚需的事。
dsh-usage-monitor（作者 liyiersan，MIT 协议）就是为了解决这个问题而生的：它把 DeepSeek 的官方定价、本会话花费、累计花费、账户余额直接显示在 DSH 的 Web 界面里，全程本地计算，不依赖任何第三方服务。
二、项目是什么：一个 DSH 用量监控插件
一句话总结它的定位：
在 DeepSeek Harness（DSH）界面里直接显示 DeepSeek API 的官方定价、会话用量花费、累计花费和账户余额。
它的运行前提是你已经用上了 DSH（@deepseek-ai/dsh），并且以 web profile 启动。插件本体通过一条命令即可安装：
dsh plugin --profile web add github:liyiersan/dsh-usage-monitor
仓库还声明了 dsh.bundle.patch，在支持 manifest 的 DSH 版本上会自动把插件插入 profile 配置树，多数情况下你不需要手动改任何 YAML。
三、四大核心能力
插件在界面上开了两个入口：对话主视图新增的「用量」Tab（完整面板），以及输入框上方常驻的 dock 条（一眼可见的关键数字）。具体能看什么：
1. 账户余额
直接查询 DeepSeek 官方余额接口 GET https://api.deepseek.com/user/balance，展示总余额、充值余额和赠金，默认 60 秒缓存，可手动刷新。
2. 本会话花费
这是设计上最见功力的点。它显示的不是「按当前模型重算整段历史」，而是账本里已计价的金额——按各阶段实际使用的模型与时段分别增量计价。因此你中途从 Flash 切到 V4-Pro，数字不会跳变。账本还没记录该会话时，退回本地估算并在界面标注「估算」。
3. 按模型明细
账本按模型分桶记录 token 与金额，面板会分别列出 Flash 和 V4-Pro 各自「用掉多少、花了多少」。
4. 累计花费 + 官方定价
本地账本跨会话累计，采用增量计价，跨高峰/空闲时段也能准确累加；用量由常驻的 dock 条上报，哪怕你不打开面板也在持续记账。内置 deepseek-flash 与 deepseek-v4-pro 单价，并自动区分峰/闲时段。
四、架构：宿主半 + 浏览器半
整个插件是经典的「一分为二」结构，通过本地 HTTP 端点通信：
DSH Host (Node)
lib/index.js ── GET /user/balance ──> api.deepseek.com
│
├─ GET /usage-monitor/data ──> 浏览器客户端
└─ POST /usage-monitor/report <── 浏览器客户端
│
├─ conversation.view「用量」Tab
└─ conversation.input.dock dock 条
-
• lib/index.js（宿主半）：Cordis 插件。负责解析凭据、查询余额、维护本地账本（按会话 + 按模型分桶、增量计价），并暴露GET /usage-monitor/data和POST /usage-monitor/report两个本地端点。 -
• lib/client.js（浏览器半）：注册conversation.view和conversation.input.dock两个槽位，分别渲染完整面板和常驻 dock 条。 -
• lib/pricing.js（计费引擎）：纯函数、无副作用、可独立测试，服务端和测试共用同一份逻辑。
这里有个值得注意的细节：浏览器运行时无法直接 import 服务端模块，所以客户端内联了一份定价副本。作者的处理很诚实——在文件头注明「改价格两处都要改」，并让测试只覆盖服务端那份引擎，靠人工纪律保证同步。
五、计费引擎的巧思（最值得看的部分）
lib/pricing.js 是整个项目的技术灵魂。它把计费抽象成几个干净的纯函数，我挑几个最能体现设计取舍的点讲。
1. 四桶 token 计价，而不是「一刀切」
DeepSeek 的 token-meter 给出的是互不重叠的四个桶：uncachedInput（缓存未命中输入）、cacheRead（缓存命中输入）、cacheWrite（写入缓存）、output（输出，含推理）。计费规则是：
-
• 缓存命中输入按 cacheHit单价（最便宜，是省钱关键）； -
• 未命中输入按 cacheMiss单价； -
• 输出按 output单价； -
• cacheWrite官方未单列，本项目按未命中单价保守计。
价格口径（单位：元 / 百万 tokens）：
|
|
|
|
|
|
|---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
注意 V4-Pro 高峰输出 27 元 / 百万 tokens，是 Flash 的 3 倍以上——模型档位选错，账单差距巨大。
2. 峰/闲时段用「北京时间」判断
官方口径：高峰 = 北京时间周一至周五 09:00–12:00、14:00–18:00，其余为空闲，且空闲价为高峰的一半。isPeak() 把任意 Date 偏移到北京时间再判定，并且区间是右开的（18:00 整算空闲）。这个边界在测试里专门覆盖：
assert.equal(isPeak(WED_6PM_BJ), false, '18:00 整应为空闲（右开区间）');
3. 增量计价：跨会话、跨时段精确累加
这是整个账本能「不跳变」的根本原因。核心函数是 usageDelta(prev, next)——每次客户端上报的是「本会话累计用量」，服务端只计算相对上次的增量，再按「上报那一刻的模型 + 时段」为增量计价。
这样做有两个好处：
-
• 用量只增不减，负值归零，避免流式投影回退导致重复计价； -
• 一次会话中途跨过 12:00（空闲切高峰），前后两段各自按当时单价算，累计金额天然准确。
4. 模型名归一化
DSH 里模型名五花八门（DeepSeek-V4-Flash High、deepseek-v4-flash-vision-exp…）。normalizeModel() 用「含 pro/chat/reasoner 归 V4-Pro，含 flash 归 Flash」的简单规则归一化，识别不了按 Flash 兜底并在界面标注。
一个可感的真实例子（来自测试）：200 万输入（97% 缓存命中）+ 4.17 万输出、Flash 空闲时段，整轮只花 ¥0.2656。缓存命中率对成本的影响，肉眼可见。
六、工程细节：一个「小而美」开源项目该有的样子
读懂了计费引擎，更让我欣赏的是它在工程落地上的一系列克制与讲究。
面板与 dock 状态同步。 早期版本（commit bda14b532）有个真实 bug：面板和 dock 是两个挂载点，各自维护 useState，导致按下刷新只更新面板、dock 还显示旧余额，两个界面数字互相矛盾。作者引入了模块级 dashboardStore（缓存 + 订阅者 + 进行中请求合并）和 useDashboard() Hook，让面板刷新写穿 store，所有挂载点一起更新；并发请求也被合并成一次。
上报去重 + 防抖。useUsageReporter 维护一个 reportedSignatures Map，用「四桶 token 数 + 模型」拼签名去重；首次挂载立即上报（延迟 0ms）取回账本金额，后续用量变化延迟 1.2 秒发送以合并流式更新。
原子落盘 + 节流。 账本写入先写 .tmp 再 rename，避免写一半崩溃损坏数据；写入有 5 秒节流，定时器 unref，释放时强制刷盘。任何网络/磁盘异常都被捕获降级，绝不影响 DSH 本体。
安全与隐私。 这几点在如今的开源项目里很加分：
-
• 端点随 DSH webServer 只监听回环地址； -
• POST /usage-monitor/report要求Content-Type: application/json，从而挡掉跨站「简单请求」（与 DSH 自身/api做法一致）——典型的 CSRF 防护； -
• 插件本身不保存 API key，只通过 DSH credentials 服务或进程环境变量取用； -
• 本地账本只记 session id、token 用量、按模型分桶金额，不传任何遥测。
热更新体验。 作者实测：改 client.js 只需浏览器刷新即可（DSH 会重算 bundle 的 rev 按新 URL 提供）；只有改服务端 index.js 才需重启 DSH。这种对开发者体验的细心，体现在 README 专门写了一节提醒。
测试覆盖。test/pricing.test.mjs 用 node --test 跑，覆盖峰/闲判定（含周末、午休、右开边界）、模型归一化、四种价格的官方手算对照、增量计价负值归零、格式化等；还有 scripts/smoke.mjs 服务端冒烟测试（用临时 DSH_HOME，只打印 key 长度不打印 key 本身）。
七、怎么装（极简版）
# 1. 安装插件（自动应用 bundle patch）
dsh plugin --profile web add github:liyiersan/dsh-usage-monitor
# 2. 确认 API key 可用（DSH credentials 或环境变量 DEEPSEEK_API_KEY）
# 3. 重启并打开 web
dsh web
打开任意会话，顶部出现「用量」Tab，输入框上方出现 dock 条，即大功告成。
八、小结与延伸
dsh-usage-monitor 是个典型的「小而准」工具：它没造轮子，只是把 DeepSeek 官方定价 + 官方余额接口 + DSH 的插件机制，用一种克制、安全、可测试的方式拼了起来。真正值钱的不是「能显示数字」，而是那套增量计价账本的设计——它让跨模型、跨时段的累计花费始终对得上账，不会在切模型时凭空跳变。
从工程角度看，它也几乎是一份「如何写一个靠谱 DSH 插件」的范本：宿主/浏览器二分、纯函数计费引擎、模块级共享 store 解决多挂载同步、原子落盘、回环 + JSON 媒体类型防 CSRF、热更新提示、测试先行。
如果你也在重度使用 DeepSeek API，尤其是用 DSH 把模型当工作台，这个插件值得一试。更进一步的想象空间也有：比如把账本导出成周报、按项目维度分账、或接入成本异常告警——这些都建立在它那套干净的本地账本之上，扩展成本很低。
项目地址：https://github.com/liyiersan/dsh-usage-monitor ｜ License：MIT
END
#agent #deepseek #harness #dsh #dsh-usage-monitor
如果这篇文章对你有帮助，欢迎点赞、在看、转发