前言¶
在 DSH（DeepSeek Harness）里接多个 Provider、多个模型跑会话时，用量往往分散在各家的控制台或账单里，很难在同一处按时间、模型对比「今天用了多少、哪条链路最吃 Token」。若还要自己写脚本解析日志，成本和隐私边界也不好把握。
下面介绍社区插件 dsh-token-usage（维护者 qiz42144-web）：它只做被动观察——读取 DSH 本就会写入的用量元数据，落到本地 SQLite，再用页面做聚合与图表。不调用模型、不联网读业务内容，适合想把用量留在本机的开发者。
这是什么¶
- 名称：
dsh-token-usage（npm 包名@aixnest/dsh-token-usage） - 分类：admin-security（SkillHub 目录归类）
- 许可证：MIT（© 2026 qiz42144-web）
- 定位：轻量 DSH 插件，本地记录并按 Provider、账号、套餐、模型拆分 Token，支持时间范围、趋势图、排行与请求记录。
插件不读取提示词、回复正文、工具参数、请求体或 API Key；不产生额外模型请求，也不往上下文里注入内容。
核心功能¶
统计范围与指标¶
时间范围支持：今日、本周、本月、本年、全部，以及自定义起止日期（结束日含当天全天；最后一次选择会记住）。日历按本地计算，不是固定 24 小时滑动窗口。
指标卡片共 7 项：总计、输入、输出、缓存、缓存命中率、推理、请求数。缓存命中率按 Token 加权；Provider 未上报缓存时显示 —。推理 Token 属于输出的一部分，不计入总计重复加总。
趋势图与年度热力图¶
柱状趋势图随范围自动调整粒度（例如今日按小时、本年可按日/周/月）。悬停可查看该周期的分项与请求数。选择「本年 + 按日」时，页面切换为 12 月 × 31 天 的年度热力图，便于看使用密度。
排行、请求记录与筛选¶
排行可在「模型 / Provider」间切换，按总量降序。请求记录按时间倒序，每页 50 条，可加载更多；未返回 usage 的请求标为「未知」，不按 0 计入 Token。
「全部模型」下拉为树形结构：Provider → 账号 → 套餐 → 模型，任一层级即可筛选，并支持搜索模型 id 或自定义名称。可为 Provider、账号、模型设置显示名，为模型打套餐标签，真实 id 仍保留。
显示与配置¶
数字格式可在「简写」（如 4.25B）与「完整」（千分位）间切换，并会记住偏好。自定义日期使用自建日历组件，支持键入 2026-09-06 或 2026/09/06。
可选配置（默认 config: {}）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
dbPath |
$DSH_HOME/token-usage/usage.db |
SQLite 历史文件绝对路径 |
recordAttempts |
true |
是否记录完全没有返回消息的模型步骤为未知请求 |
安装与启用¶
插件以当前 DSH 进程权限运行。安装前建议查看 GitHub 仓库 源码与 MIT 许可证，确认符合你的合规要求。SkillHub 目录页：qiz42144-web/dsh-token-usage（社区站点，与 DeepSeek / 幻方无官方从属关系）。
从 npm 安装（推荐）¶
在 DSH 会话中执行：
plugin_manager install_bundle target = @aixnest/dsh-token-usage
包地址：https://www.npmjs.com/package/@aixnest/dsh-token-usage（README 中 npm 版本徽章对应发布线；package.json 标注 engines.node 为 >=22.5.0）。
安装成功后，侧边栏会出现 Token 用量 入口。首次打开数据库为空，从安装之后的下一个请求起自动记录，不会回溯历史。
若安装返回 restart-required（例如 Host 侧模块有变更），按提示重启 DSH；仅当返回 applied 时侧边栏入口才会立即可用。
更新与卸载¶
更新：重新执行一次安装命令即可。
plugin_manager install_bundle target = @aixnest/dsh-token-usage
卸载：
plugin_manager remove_bundle target = @aixnest/dsh-token-usage
卸载不会删除数据库。若要清除历史，需手动删除 $DSH_HOME/token-usage/（或你在 dbPath 中指定的路径）。
可选 profile 配置示例¶
在 profile 中插入 bundle 并自定义库路径、是否记录「空返回」步骤：
- insert:
- id: token-usage
name: dsh-token-usage
config:
dbPath: 'D:/dsh-data/token-usage.db'
recordAttempts: false
典型用法¶
1、完成安装并确认侧边栏有「Token 用量」后，正常使用 DSH 发起对话或工具调用，用量会自动写入 SQLite。
2、打开面板，先选时间范围（或自定义日期并点「应用」），查看顶部指标卡片与趋势图。
3、需要对比模型成本时，用「全部模型」树或搜索收窄到单个模型；在排行区切换「模型 / Provider」查看谁占用最多。
4、核对单笔请求时，下翻请求记录；对无 usage 的条目留意「未知」提示，避免与 Token 合计混淆。
5、若数字与 Provider 后台不一致，以 Provider 上报的 usage 为准；插件按 总计 = 输入 + 输出 + 缓存读 + 缓存写 统一换算，各家对「输入」是否含缓存命中定义可能不同。
数据存储、隐私与注意¶
存储内容：每条模型步骤一行——时间、Provider id、模型 id、输入/输出/缓存/推理 Token、请求数。偏好写在同目录 settings.json（数字格式、上次范围等）。
默认路径：$DSH_HOME/token-usage/usage.db。插件无出站请求；前端仅通过本机 Host 接口拉数据。
常见问题摘要：
- 页面一直为空：安装前发生的请求不会入库，需等新请求产生。
- 装完没有入口：确认不是
restart-required而未重启。 - 找不到模块
@aixnest/dsh-token-usage：检查 profile 的node_modules与package.json依赖，必要时重装。 - 数据不会同步云端；卸载后本地库仍可保留。
修改插件源码后需重启 DSH；官方 README 还提供 docs/使用指南.md、docs/隐私与数据说明.md 等文档供细读。
结尾¶
dsh-token-usage 把 DSH 已有的用量元数据收拢到本机数据库，用同一套面板看范围、趋势、热力图和请求明细，适合在多 Provider、多模型并行开发时做本地用量观测。它不替代各家账单，但能在会话侧快速回答「这段时间、这个模型用了多少 Token」。
- 目录页：https://www.skillhub.cn/plugins/qiz42144-web/dsh-token-usage
- 源码与 README：https://github.com/qiz42144-web/dsh-token-usage
