前言¶
DeepSeek Harness（DSH）采用插件化架构，将功能模块化以适应不同的使用场景。在本地部署或使用 DSH 进行对话时，追踪 Token 消耗、估算费用以及管理多平台余额是基础且高频的需求。现有的做法往往分散在不同渠道，缺乏统一的视图。本插件旨在将这些数据聚合，提供可视化的仪表盘与实时读数。
插件简介¶
nigel211/dsh-token-usage 是 DSH 的一个 Token 用量与费用统计插件。它不依赖第三方服务，数据完全派生自 DSH 的持久化会话日志。安装并重启服务后，插件会自动回填历史数据，支持按模型、会话、时间范围进行聚合统计，并提供了费用估算与多平台余额查询功能。
核心功能¶
用量统计¶
插件从 DSH 日志中提取数据，支持统计输入、输出及缓存命中 tokens。用户可以按模型、按会话或按时间范围（今天、近7天、近14天、近30天）进行聚合查看。
费用估算¶
内置 DeepSeek 官方人民币价目表。计价逻辑基于生效日期分段：
* 8-17 前旧价：统一按旧价估算。
* 8-17 起峰谷价：按北京时间分段计费，9:00–12:00 与 14:00–18:00 为高峰时段，其余时间为谷段（半价）。
价目表支持增删改并持久化。对于未知模型，用户可手动添加价格，系统将立即按此计算费用。
账户余额¶
支持自动枚举已配置的模型路由（如 DeepSeek 官方、pi-ai 等）。通过模板化查询，支持 DeepSeek、OpenRouter、SiliconFlow、New-API 等平台。余额查询带有 60 秒缓存，支持 keep-last-good 策略与瞬时/确定性错误分类。DeepSeek 官方行界面中包含“充值”按钮，可直接跳转开放平台。
图表与界面¶
- 图表展示：包含趋势图（单图四曲线 + 双轴费用）、当月日历活跃热力图（蓝色深浅代表 tokens）以及模型占比环图（支持悬停联动）。
- 仪表盘：位于设置页面的「Token 用量」区块，展示费用 Hero 指标、账户余额卡片、使用趋势、活跃热力图等。
- 常驻读数：在对话输入框下方常驻显示本会话 tokens / 费用、今日费用。
安装与启用¶
本插件仅发布在 GitHub，npm registry 上存在同名冲突包，切勿使用裸包名安装。
使用 GitHub 语法安装：
dsh plugin --profile web add github:Nigel211/dsh-token-usage
（若需指定版本，可追加 #v0.1.15）
安装完成后，必须重启 dsh web 服务，插件功能才会生效。
典型用法¶
- 查看用量：重启服务后，进入「设置 → Token 用量」，仪表盘会自动加载当前范围的数据。
- 调整价格：若使用非官方模型，可在仪表盘的「价目表」区域手动添加价格，费用计算将立即更新。
- 查询余额：打开设置页时，插件会自动查询各路由余额。DeepSeek 官方行可点击充值按钮。
- 查看趋势：在「使用趋势」图表中切换时间范围（如近7天），观察输入/输出/缓存命中与费用的变化曲线。
注意事项¶
- 历史数据回填：历史回填仅统计
assistant/message中携带usage字段的调用，未上报 usage 的调用不计入。 - API Key 安全：余额查询时，API Key 通过 DSH 凭证服务解析，仅传给对应平台接口，绝不写入日志。
- 价格限制：8-17 之前的历史调价未分段，统一按旧价估算。
- 权限要求：余额查询依赖
curl（Windows 10+ 自带）或 PowerShell，需确保网络可达对应平台接口。
结语¶
该插件通过复用 DSH 日志数据，实现了从用量统计到费用估算、再到余额管理的闭环。对于需要精细控制成本或管理多平台 API Key 的用户，它提供了一个简洁、现代的集中化视图。相关代码与目录可访问 GitHub 仓库 查看。
