前言¶
在 DeepSeek Harness（DSH）里跑长会话、多模型切换时，官方控制台能看账户余额，但本地很难把「这一条 assistant 消息」对应到人民币：峰谷单价不同、缓存命中与未命中通道分开计价，节假日规则还要跟时间戳对齐。常见做法是看 Token 估算或标题栏汇总，和账单对不上时只能事后手算。
dsh-precise-billing（包名 dsh-precise-billing，当前版本 0.2.2）面向桌面 Profile 的 DSH 用户：以每条响应自带的 usage 为计价单位，按 DeepSeek 官方人民币价目（含峰谷与 2025–2026 中国法定节假日）逐请求计费，并在界面提供费用条、侧栏卡片、用量看板与三段式热重启。维护者为 Sheldon Jinn，许可证为 MIT；插件类型为 DSH 本地插件（Host + Client），在 SkillHub 目录中归类为 admin-security。
下面介绍插件定位、核心能力、安装启用方式与日常使用路径。
这是什么¶
一句话：dsh-precise-billing 在 DSH 进程内读取会话与 usage 元数据，按请求时间戳判定峰谷后折算费用，不要求用户手工填单价。
计价与展示拆成几块：
- 精确计费：输入（未命中缓存）、缓存命中、缓存写入、输出分通道计价；峰时单价为闲时 × 2；未定价模型单独计数并标注「未计价」，不显示为 0 元。
- 费用条：可选出现在输入框下方、会话标题栏或隐藏。
- 侧栏卡片：常驻底部，汇总今日/累计消费、余额与峰谷进度。
- 用量看板：趋势、日历（日/周/月/年）及年视图柱状图。
- 热重启：侧栏触发，三段式确认后重启 DSH，并做环境快照。
数据索引与设置写在 $DSH_HOME/storages/precise-billing.json；会话源数据只读 $DSH_HOME/sessions/**/session.v4.jsonl.zstd。重启日志为系统临时目录下的 pb-restart-<时间戳>.log（README 中 Windows 示例为 %TEMP%\pb-restart-*.log）。
精确计费规则（与官方价目对齐）¶
每条 assistant/message 的 usage 是一条计价记录，不用 Token 总量粗估。
峰谷判定（北京时间）
- 周一至周五 09:00–12:00、14:00–18:00 为峰时；其余为闲时。
- 内置 2025–2026 中国法定节假日，节假日全天按闲时。
- 以该请求自己的时间戳判定，而不是会话开始时间。
单价示例（人民币 / 百万 token，闲时 / 峰时）
| 模型 | 输入（未命中） | 缓存命中 | 输出 |
|---|---|---|---|
| deepseek-flash（含 v4-flash） | ¥1 / ¥2 | ¥0.02 / ¥0.04 | ¥4 / ¥8 |
README 未穷尽所有模型价目；未出现在价表中的模型走「未计价」计数逻辑。
界面与核心功能¶
费用条¶
位置三选一：输入框下方、会话标题栏、隐藏（隐藏后相关设置项收起）。可勾选显示峰时/闲时、本次、今日、累计、余额；字体、字号、颜色可调，支持跟随主题。点击费用条可展开当前会话明细。
侧栏卡片¶
显示今日消费、累计消费、账户余额与峰谷进度。风格：标准 / 简约 / 紧凑 / 自定义（自定义可控制 16 个显示项）。右上角三个入口：热重启（↻）、用量看板（▦）、设置（⚙）。
用量看板¶
趋势：统计 Token、API 请求次数、消费金额、余额；各模型消费与 Token 曲线；单日按小时、多日按天，超过 120 天按月聚合。
日历：日 / 周 / 月 / 年视图；格子展示 Token、消费、峰时/闲时金额；点击格子弹出分模型明细（含输入命中/未命中、缓存写入、输出等）。年视图左侧为年度汇总，右侧 12 个月峰/闲堆叠柱状图，当前年份行高亮。
热重启¶
由侧栏卡片刷新图标触发，流程分三步：
- 检查运行中对话：若有，橙色警示框列出标题，可选「取消」或「继续重启」。
- 红色确认框：明确提示会中断进行中的操作。
- 蓝色执行中：进度条与日志路径，可「收起并复制日志」。
重启前对 DSH_* 与代理相关变量做环境快照；助手经 Explorer 派发，避免被 DSH job object 连带结束；接口带 15 秒冷却。系统开启「减少动态效果」时，警示框呼吸动画会关闭。
设置¶
选项自动保存（600 ms 防抖），保存后设置页中央有 ✓ 提示。「恢复默认」立即写回默认值；默认刷新间隔为 60 秒。侧栏卡片「进度条」关闭时，刻度线/游标/悬浮提示一并禁用。设置页底部「参考项目」提供 DeepSeek-Usage、dsh-hot-restart、dsh-meter 的地址与复制安装命令（本插件对三者均为独立实现，详见仓库 CREDITS.md）。
安装与启用¶
插件以当前 DSH 进程权限运行；安装前建议在 GitHub 查看源码与 MIT 许可证全文。package.json 要求 Node >=22。
从 npm 安装（README 推荐）：
dsh plugin --profile desktop add dsh-precise-billing
安装后在 设置 → 插件 中启用 dsh-precise-billing，并刷新页面。本地开发可用 link: 指向插件目录（README 给出 Windows 路径示例，需按本机 _plugins 实际位置修改）。
典型用法¶
安装启用并刷新后，可按 README「快速上手」路径操作：
- 看费用：输入框下方费用条，或侧栏底部计费卡片（点卡片展开本会话明细）。
- 开看板：侧栏卡片右上角 ▦，或 设置 → 精确计费 → 用量面板。
- 改设置：侧栏卡片右上角 ⚙，或 设置 → 插件 → 精确计费；修改后自动保存。
- 热重启：侧栏卡片右上角 ↻；先处理运行中对话提示，再完成红色确认与蓝色执行步骤。
需要对照历史消费时，用量看板日历/年视图适合按日或按月回看；需要与官方账单核对时，应以逐条 usage 聚合结果为准，并注意未计价模型的单独计数。
适用场景与注意¶
适合谁
- 长期在 DSH Desktop 使用 DeepSeek API，希望本地界面直接看到人民币费用、峰谷拆分与会话明细的用户。
- 需要用量趋势、日历与年视图，又不想单独装多个碎片化插件的用户（本插件集成了计费展示、看板与热重启；设计思路参考了社区中的 DeepSeek-Usage、dsh-meter、dsh-hot-restart，代码为独立实现）。
使用注意
- 计价依赖响应中的
usage与价表覆盖的模型；未定价模型不会伪装成零元。 - 峰谷与节假日规则以内置表为准，模型单价随 README 价表更新，升级插件后留意版本说明。
- 热重启会中断进行中的对话与操作，务必走完三段式确认。
- DSH 生态奉行「一切皆插件」；SkillHub 目录（https://www.skillhub.cn/plugins/SheldonJinn/dsh-precise-billing）为社区站点，与 DeepSeek / 幻方无官方从属关系，安装来源以 npm 包名与 GitHub 仓库为准。
结尾¶
dsh-precise-billing 把官方人民币价目、峰谷与节假日规则落到每一条请求的 usage 上，并在 DSH 内提供费用条、侧栏卡片、用量看板与带环境快照的三段式热重启。若你需要在本地开发环境里可核对、可回看、可配置的精确计费，可按上文命令安装后在插件设置中启用。
- 插件目录页：https://www.skillhub.cn/plugins/SheldonJinn/dsh-precise-billing
- GitHub：https://github.com/SheldonJinn/dsh-precise-billing
