前言¶
在 DeepSeek Harness（DSH）里跑长会话或智能体时，token 会一路累加，账户余额也会跟着变。客户端自带的 usage 信息往往分散在 composer 区域，且不一定同时给出「本轮 / 整会话」的 token、按官方价目估算的费用，以及本轮真实扣费（余额差值）。若你希望在标题栏或输入区附近常驻看到这几项，并在悬停时展开分项与价目来源，社区插件 dsh-plugin-usage-cost（维护者 worldconfig，当前包版本 1.3.0，MIT 许可证）提供了一套会话头部 HUD 方案。
这是什么¶
dsh-plugin-usage-cost 是 DSH 的客户端插件：在 Web GUI 里注入 HUD，实时展示本轮与会话的 token 消耗、账户余额、按 DeepSeek 官方价目表估算的费用、本轮真实花掉的钱（余额差值）以及今日累计扣费。宿主侧（lib/index.js）负责抓取并解析官网价目，经同源路由 /usage-cost-hud/prices 提供给页面；浏览器侧（lib/client.js）负责 HUD 渲染、悬停浮层、峰谷时段判定与显示偏好。包同时声明 dsh.bundle.patch，通过 cordis.patch.yml 向 Cordis 插入 usage-cost-hud 加载项。
目录页：SkillHub - worldconfig/dsh-plugin-usage-cost
源码与说明：GitHub - worldconfig/dsh-plugin-usage-cost
核心功能¶
HUD 上能看到什么¶
默认挂在会话标题栏右侧工具区（也可改到输入框下方或右下角），一行示例形态如下：
本轮 3.0M · 估 ￥0.72 会话 11.4M · 估 ￥3.04 余额 ￥12.07 ↓￥0.42 今日 ￥0.83 ⟳ ● 运行中 ▴
各段含义与数据来源（摘自 README 说明）：
| 段 | 含义 | 数据来源 |
|---|---|---|
| 本轮 | 当前这一轮的 token | tokenUsage 投影差量 |
| 本轮 · 估 | 本轮金额（估算） | 单价表或实测均价 |
| 会话 | 整份会话日志累计 token | host 回放整份日志的 tokenUsage |
| 会话 · 估 | 会话金额（估算） | 同上 |
| 余额 | 充值 + 赠金合计 | account.getBalance |
| ↓ | 本轮真实扣费 | 余额差值 |
| 今日 | 今日累计真实扣费 | 本机观察到的余额下降累加 |
| ● 运行中 | 会话正在执行 | useSession(s => s.running) |
| ⟳ | 重新抓取官网价目 | 宿主同源路由 |
没有本轮基线时不显示「本轮」：页面在一轮中途打开不会显示「本轮 0」，等下一轮真正开始才起算。行尾箭头可折叠 HUD；折叠后默认仍显示会话 token 与会话金额。
悬停浮层与价目¶
鼠标悬停 HUD 会弹出浮层（非系统 tooltip），包含会话模型信息、TOKEN 分项（未缓存输入 / 缓存读取 / 缓存写入 / 输出及单价）、金额汇总、账户明细、价目来源与核对日期、以及插件版本与 GitHub Release 检查。浮层打开时，宿主路由 /usage-cost-hud/update-check 最多每小时向 GitHub 查一次新版本（结果缓存 10 分钟）。
金额估算优先级：官方单价表（可按桶计价）→ 实测均价（每轮用余额差 ÷ token 学习，存 localStorage）→ 都没有则只显示 token。仅当 provider 以 deepseek 开头时按官方路由计价；第三方路由不显示金额。价目来自 DeepSeek 定价文档，高峰为北京时间工作日 09:00–12:00、14:00–18:00（不含 HOLIDAYS 中配置的法定节假日），其余为空闲价（约为高峰一半）。因官网文档无 CORS，价目抓取必须在宿主侧完成，浏览器通过 fetch("/usage-cost-hud/prices") 获取 JSON。
位置、配色与窄屏¶
浮层底部可切换 HUD 位置（localStorage["dsh-usage-cost:position"]）：顶部 conversation.session.header.utilities（默认）、输入框下 conversation.composer.dock、或右下角固定胶囊（可拖动，坐标存 dsh-usage-cost:spot）。配色在「跟随主题」与「纯黑」间切换（dsh-usage-cost:color-mode）。标题栏座位在容器宽度不足时会用 CSS 容器查询自动隐藏部分字段（如今日、本轮、余额等），输入框下与右下角不受该规则影响。展开 / 折叠各自有一套显示开关，保存在 localStorage["dsh-usage-cost:fields"]。
安装与启用¶
插件以 bundle 形式安装，会更新 profile 的 dependencies 与 dsh.profile.bundles，并由包内 patch 插入 Loader。从 GitHub 发布版安装（README 标明最新标签 v1.3.0）可用以下两种方式之一。
在 Harness 内通过插件管理（plugin_manager 的 install_bundle，或设置 → 插件从目录 / git 规格安装）：
plugin_manager install_bundle target: github:worldconfig/dsh-plugin-usage-cost#v1.3.0
或使用 CLI（README 要求先完全退出 DSH 应用）：
dsh plugin --profile desktop add github:worldconfig/dsh-plugin-usage-cost#v1.3.0
包为纯 JavaScript，无 prepare 构建步骤；安装后刷新页面即可加载客户端部分。若只改了 lib/client.js，刷新即可；若改了 lib/index.js（宿主），需完全退出应用再打开。卸载使用 remove_bundle 或在设置 → 插件中禁用。
注意：README 明确不建议在 profiles\desktop\cordis.patch.yml 里手写 usage-cost-hud 的 insert，桌面打包运行时可能导致装载器静默跳过。
典型用法¶
安装并刷新后，打开任意 DeepSeek 官方路由的会话即可在 HUD 上看到 token 与费用相关字段，无需额外配置文件。
- 核对价目是否最新：点击行内
⟳，成功会短暂提示「价目已更新」并写入localStorage["dsh-usage-cost:price-override"]；价目超过 7 天也会静默刷新一次。 - 看清本轮真实花了多少：关注
↓后的金额（余额差值），与「估」并列对比；「今日」为本地时区当日观察到的余额下降累加，充值不会冲抵当日统计。 - 调整显示：悬停打开浮层，在「位置」「配色」「显示 → 编辑」里按习惯配置；顶部栏过窄时可依赖自动降级或手动关掉不需要的段。
- 升级插件：DSH 不会自动更新插件；将安装命令中的标签改为新版本后再执行一次安装，刷新页面；宿主改动仍需完全重启应用。
开发者可在插件仓库根目录运行离线测试：
npm test
README 写明共 118 项断言，覆盖宿主解析与客户端行为 fixture。
适用场景与注意¶
适合长期在 DSH 桌面端使用 DeepSeek 官方模型、希望在一眼可见的位置跟踪 token 与费用的开发者。HUD 的「今日」与实测均价依赖本机、本插件运行期间对余额的采样，其他会话、子代理或赠金变动可能污染均价学习；浮层在样本异常时会标注「可能含其它会话消耗」。
DSH 生态奉行「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。插件与宿主代码在同一 DSH 进程权限下运行，安装前请自行阅读 源码 与 MIT 许可证，确认接受其网络行为（例如向 api-docs.deepseek.com 与 GitHub 发起请求）。
结尾¶
dsh-plugin-usage-cost 把本轮与会话的 token、余额、估算费用与真实扣费收到会话 HUD 里，并尽量跟官方价目与峰谷规则对齐。若你需要这类常驻统计，可从目录页了解分类与简介，并按 README 中的 git 规格安装 v1.3.0（或你选定的 Release 标签）。
- 目录页：https://www.skillhub.cn/plugins/worldconfig/dsh-plugin-usage-cost
- GitHub：https://github.com/worldconfig/dsh-plugin-usage-cost
