前言¶
同时接几家模型供应商是 DSH 用户的常态：Kimi For Coding 是订阅额度，DeepSeek 官方按量扣余额，OpenRouter 看积分。想知道「还剩多少、这个月花了多少」，通常要分别登录各家控制台，来回切换，查完一圈，手头的工作早被打断。
dsh-token-monitor 把这件事搬进了 DSH Web：会话头部常驻余量徽标，主区多一个「用量」页签，本地 SQLite 记录每次调用的 token 与估算费用。下面介绍它的功能、安装与配置。
这是什么¶
dsh-token-monitor 是 DeepSeek Harness（DSH）Web 界面的大模型余量与用量监控插件，作者 licyer，当前版本 1.0.2，MIT 许可证。它解决的问题很具体：用量与余量数据散落在各供应商控制台，在 DSH 里看不到。
插件做三件事：
1、在会话头部实时显示当前模型供应商的余量；
2、在主区提供与「对话 / 轨迹」并列的「用量」页签，统计 token、估算费用与使用趋势；
3、自动采集 DSH 会话日志，把每次调用的 token 与费用落进本地 SQLite（token-monitor.db）。
核心功能¶
余量徽标¶
徽标显示当前模型供应商的余量，形如 k3 · 5h 剩 82%。两类供应商的展示逻辑不同：
1、订阅制供应商（如 Kimi For Coding）：显示滚动窗口与周额度百分比；
2、按量付费供应商（如 DeepSeek 官方）：显示账户余额。
点击徽标弹出详情层，包含当前提供方指标、本会话 token 用量（可切换会话）、全部提供方折叠区、cc-switch 数据同步提示条、更新时间与手动刷新。
用量页签¶
「用量」页签与「对话 / 轨迹」并列。顶部是筛选（客户端 / 供应商 / 模型级联，供应商按厂商归并）和时间窗（当天 / 昨天 / 7 / 30 / 90 天 / 全部），统计卡给出总消耗、请求次数、预估费用、平均 TTFT、新增输入、缓存命中、输出、缓存命中率。往下依次是：
- 使用趋势：渐变面积图，左轴 token 构成，右轴可切换预估费用 / 请求次数；当天视图为分钟级刻度（2~60 分钟自适应、至少 12 桶，补桶不跨天），悬浮提示显示桶区间（如
15:00~15:30）； - 供应商消耗统计：X 轴供应商、柱内按模型堆叠，右侧可切换费用 / 次数；
- 年度消耗热力图：GitHub 日历风格，覆盖近 12 个整月，色深对应当日 token，首尾按周补齐；
- 使用排行：模型 / 供应商 / 客户端三个维度聚合，默认按总消耗降序；
- 请求记录：分页明细表，时间倒序，页码跳转，每页条数可选 10/20/50/100。
自动采集与存储¶
插件自动采集 $DSH_HOME/sessions 下的会话日志，增量写入本地 SQLite（token-monitor.db）。采集由后台定时器、手动刷新和打开页签时触发，页面查询直接读库。数据不出本地。
历史导入与跨设备同步¶
两处补数据的入口：
1、cc-switch 历史记录导入，重复导入不产生重复数据；
2、JSON 快照导出 / 导入（含明细与聚合），可把不同设备的使用记录合并到一台设备，幂等不重复。
两个入口都在「用量」页签底部的「数据来源」。
语言跟随¶
界面文案跟随 DSH 的中文 / 英文切换，不需要单独设置。
安装与启用¶
前置条件：Node.js ≥ 22（依赖内置的 node:sqlite），且仅支持 DSH Web 端（platform: web）。从 npm 安装（推荐方式）：
dsh plugin --profile web add dsh-token-monitor
也可以从 GitHub 安装：
dsh plugin --profile web add github:licyer/dsh-token-monitor
安装即自动注册，写入 profile 的 package.json bundles 与依赖，不需要手动改配置。经过上面的步骤，重启 dsh web 进程后生效，会话头部应出现余量徽标，主区多了「用量」页签。
凭证配置¶
余量查询读取 DSH 已有凭证，写在 ~/.dsh/.credentials.yaml，或通过环境变量提供，如 DEEPSEEK_API_KEY、KIMI_CODING_API_KEY。凭证没配时徽标会提示「未配置 API Key」，配置后自动恢复。
插件配置¶
配置文件位于 $DSH_HOME/storages/token-monitor/config.json。设置入口在 DSH 设置面板（左下角齿轮）→ Token Monitor 页，表单保存后即时写回该文件。共三个设置项：
| 字段 | 默认值 | 含义 |
|---|---|---|
defaultDays |
1 |
用量页签默认时间窗天数，0 表示全部 |
pollMs |
60 |
头部余量轮询间隔，设置页与 config.json 均存秒，需要毫秒时由前端单独 ×1000，取值 5–86400 |
retentionDays |
60 |
请求记录保留天数，超期记录定期清理但不影响聚合统计，设置页提供 30/60/90 |
设置页下方还附有已适配供应商清单，标明哪些提供方已适配、开发者是否用真实凭证验证过。
遇到端点漂移（供应商 API 地址变更，常见 404）时，可在插件配置里用 providers.<id>.url 覆盖端点地址。
供应商适配¶
| 提供方 | 类型 | 展示内容 | 验证状态 |
|---|---|---|---|
kimi-coding |
订阅额度 | 5h / 7d / 权益等级（百分比与重置倒计时） | 已验证 |
moonshotai-cn |
按量余额 | 可用余额（CNY）+ 现金 / 代金券明细 | 已验证 |
deepseek |
按量余额 | 账户余额（按币种账户显示） | 已验证 |
opencode-go |
订阅额度 | 5h / 7d / 30d（百分比与重置倒计时） | 已验证 |
openrouter |
按量余额 | 积分余额（1 积分 = $1）+ 本月 / 总消耗 | 已验证 |
minimax / minimax-cn |
订阅额度 | 5h / 7d 用量百分比（剩余%） | 待真实 key 验证 |
zai / zai-coding-cn |
订阅额度 | 5h / 7d 用量百分比（窗口自动识别，含重置时间） | 待真实 key 验证 |
后两组已通过 mock 测试，但未用真实 key 校准；若实际响应结构与参考实现有出入，可提交接口返回的 raw 原文协助校准。
常见问题¶
徽标没显示或提示「查询失败」¶
先看文案：「未配置 API Key」说明凭证没配，按上面的凭证配置补齐即可；「查询失败」说明凭证已配置但余量接口查询失败，按条排查：网络不通或超时、端点漂移（用 providers.<id>.url 覆盖）、响应字段结构异常无法解析。若提示「插件未适配该提供方」，则是适配范围问题，与以上无关。
用量页签没数据¶
用量来自会话日志采集：先确认 $DSH_HOME/sessions 下有会话日志，再点顶部「刷新」（先采集再查询）；cc-switch 数据需在「数据来源」手动导入。
费用准不准¶
费用按 pi-ai 本地刊例价估算，仅供参考、非实际账单；订阅制不产生真实扣费；未定价模型计入 token、不计入费用。
本地开发¶
克隆仓库后用本地路径挂载：
git clone https://github.com/licyer/dsh-token-monitor.git
dsh plugin --profile web add link:/path/to/dsh-token-monitor
改前端（lib/client.js）走 HMR 热替换，刷新即生效；改服务端（lib/index.js / lib/util/）需重启 dsh web 进程。
适用场景与注意事项¶
适合同时使用订阅制与按量付费供应商、想在 DSH Web 里直接看余量和用量明细的开发者，也适合需要本地留存调用记录、做跨设备合并的人。
使用前注意：
1、插件以当前 dsh 进程的权限运行，安装前建议检查源码与许可证（MIT）；
2、费用为本地刊例价估算，不要当账单对账；
3、minimax 与 zai 两组适配未经真实 key 验证，结果以实际为准；
4、仅支持 Web 端，Node.js 版本必须 ≥ 22。
相关链接¶
DSH 的理念是「一切皆插件」，dsh-token-monitor 把余量查询和用量统计收进同一个界面，数据留在本地，安装只需一条命令。
- GitHub 仓库：https://github.com/licyer/dsh-token-monitor
- 社区目录收录页：https://www.skillhub.cn/plugins/licyer/dsh-token-monitor （社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系）
