前言¶
DeepSeek Harness（DSH）通过插件生态扩展功能。对于开发者或使用者而言，在多会话场景下实时监控 Token 消耗与费用是一项基础需求。现有的日志记录往往难以直观展示单次会话的成本结构。dsh-token-usage 旨在解决这一问题，它直接嵌入到侧边栏中，提供可视化的用量卡片。
插件简介¶
本插件由 vector-sunlight 维护，采用 MIT 许可证。它作为一个 DSH Web 插件，在 dsh-better-sidebar 右侧栏注册「⚡ Token 用量」标签页，按会话独立统计当前会话的 Token 用量与费用。
核心功能¶
- 按会话独立统计：切换会话时自动复用或新建专属窗口，统计互不串扰。
- 详细 Token 统计：支持缓存命中、缓存未命中、缓存写入、输出、推理 tokens 的分别统计。
- 缓存命中率可视化：提供缓存命中率进度条，颜色从深红渐变至松石绿，直观反映缓存优化效果。
- 峰谷分时计价：基于北京时间（UTC+8）判定高峰与低谷时段。高峰时段为 9:00-12:00 和 14:00-18:00，其余为低谷。每条用量按发生时刻所在时段计价。
- 官网价格同步：Host 启动时自动抓取 DeepSeek 官网定价页，解析双币种（USD/CNY）及高峰/低谷两套价格，每 6 小时自动刷新；同步失败时会回退至内置价格并显示警告。
- 高精度计费：费用精确到两位小数，主币种随界面语言显示（中文 ¥ / 英文 $）。
安装与启用¶
安装前请确保已安装 dsh-better-sidebar 插件（版本 >= 0.12.0）。一键安装脚本会自动检测并处理依赖。
官方安装命令¶
在终端执行以下命令添加插件：
dsh plugin --profile web add github:vector-sunlight/dsh-token-usage
依赖处理¶
插件通过 peerDependencies 声明了 dsh-better-sidebar 依赖。安装脚本会自动检测该依赖，若未安装会明确提示并询问是否自动安装。
启动后操作¶
安装完成后，需重启 DSH 进程（例如 pm2 restart dsh-web 或直接重启 dsh web），并在浏览器中进行硬刷新（Ctrl+F5 或 Cmd+Shift+R），以确保插件和依赖正确加载。
功能说明¶
计量重置规则¶
为了保持数据的准确性，插件设定了重置机制：
* 上下文压缩后重置：当会话触发上下文压缩（compaction/end）时，计量数据会重置。
* 一周清零：如果距最后一条记录已满一周且无新记录，旧计量会自动清零并重新开始。
价格同步机制¶
插件在 Host 端运行时，会抓取 DeepSeek 官网的定价页。它会解析模型在不同时段（高峰/低谷）的价格，并据此计算费用。卡片顶部会实时显示当前的北京时间（含月日）。
技术实现¶
插件采用 Host 与 Client 分离的架构设计：
* Host 半 (lib/index.js)：作为 ESMod 模块运行，负责注册 /token-usage/api/usage JSON 路由，处理会话持久日志、解析官网价格及分段计价逻辑。
* Client 半 (lib/client.js)：负责向 betterSidebar 注册标签页，并每 3 秒轮询 Host 路由以获取最新数据并更新界面。
注意事项¶
- 依赖要求：必须安装并启用
dsh-better-sidebar（>= 0.12.0），否则插件无法显示。 - 权限说明：插件以当前 DSH 进程的权限运行，安装前建议检查源码与许可证。
- 数据源：价格同步依赖网络访问官网，若网络环境受限可能导致回退至内置价格。
总结¶
dsh-token-usage 提供了从缓存命中率到峰谷计费的完整成本监控方案，适合需要在 DSH 侧边栏中直观管理 Token 使用量的开发者。更多细节可参考目录页或源码仓库。
