前言¶
在 DeepSeek Harness（DSH）里做多轮会话时，token 往往分散在一条条会话事件里：今天多少、这个月累计多少、某个模型是否特别费，只能靠翻日志或凭印象猜。官方 Web GUI 侧重对话与工具链，并不自带按日、按提供商、按模型汇总的用量视图。
dsh-token-board 是社区维护的客户端插件，在侧边栏增加「使用统计」入口，把本机会话日志折成可读看板。数据只在本机读取与缓存，不联网、不上报。下面介绍它的能力边界、安装方式与使用时的口径约定。
这是什么¶
- 名称：
dsh-token-board - 维护者：HTempt
- 分类：客户端（浏览器半，
dsh.client.platform为web） - 许可证：MIT（© 2026 HTempt）
- 当前 npm 版本：
0.1.5 - 依赖宿主：
@deepseek-ai/dsh>=0.2.1-rc.2；Node^22.19.0 || >=24.0.0
插件随 DSH 宿主加载，不能单独用 node 当独立服务跑起来。它注入 webServer、sessionPersistence、sessions，通过持久层与会话内存读 usage 相关事件，并在 Web 侧注册只读路由与侧边栏入口。
适用运行方式：
| 运行方式 | profile | 说明 |
|---|---|---|
dsh web |
web |
标准用法 |
| DSH Desktop（Dataelem 第三方客户端） | web |
内部同样是 web profile，安装命令一致 |
核心功能¶
看板主要回答「花了多少 token、调了多少次、花在哪」——模块与入口如下。
顶部指标卡¶
五张卡片：今日消耗、本月消耗、所选范围消耗、累计消耗、调用次数。脚注写清每张卡覆盖的时段与调用数；范围卡会标明区间名（如「近 3 月」「近 1 年」或自选起止）。
约定：
- 本月：当前自然月 1 号到月末，由宿主单独计算，不随页面所选时间范围变化。
- 累计：始终为全量
allTime，与热力日历画了多久无关。
热力日历与区间¶
可按 近 3 月 / 近 6 月 / 近 1 年 / 全部 / 自选起止 切换（自选最长 1 年，超出会截断）。日历按 token 单色深浅编码；「全部」从最早有数据的月份画到最新，不画空白月（绘制上限 24 个月，统计与卡片仍按全量算）。
点击某一天弹出当日明细：token 与调用、缓存命中率、失败/尝试与重试；按提供商列出模型；底部有当日工作区分布（按项目，最多展示 6 条）。
分布、趋势与时段¶
- 概览 / 时段 / 分布 三个顶部页签。
- 按提供商：环形图与占比条；按模型：按 token 排名。
- 双指标趋势：token 与调用次数各一条纵轴，图例可点选隐藏曲线。
- 时段：24 个钟点柱状图，可切「按 Token / 按调用」；小时按浏览器本地时区切分，与日历日界一致。
数据从哪来¶
| 你想知道 | 页面在哪 |
|---|---|
| 今天花了多少 token、跑了几次 | 顶部「今日消耗」卡 |
| 这个月累计多少 | 「本月消耗」卡 |
| 这段时间每天都用了多少 | 热力日历 |
| 某一天具体花在哪个提供商/模型 | 点日历某天 → 当日明细 |
| 哪个提供商/模型最费 | 「按提供商」/「按模型」页签 |
| 趋势怎么走 | 底部双指标趋势图 |
| 一天里哪个时段最费 | 「时段」页签 |
插件会写自己的统计与缓存文件；读写范围见仓库 ORIGINALITY.md。
关键统计口径¶
与用户侧约定保持一致的几点：
- 调用次数 = 带 usage 样本的实际请求数，不是消息数。
- 成功/失败来自持久事件：
assistant/message（带usage）计成功；assistant/attempt计失败；llm/retry只计重试、不重复计调用。 - 全零 usage 的预热请求不计入。
- 热力图只编码 token 消耗。
- 时段图只统计带时间戳的会话记录；按天归档的
statistics.json历史不计入时段图，页底会注明覆盖窗口内消耗的百分比。
安装与启用¶
从 npm 安装（推荐）¶
dsh plugin 会把参数转发给 pnpm，并自动登记 bundle：
dsh plugin --profile web add "dsh-token-board"
升级到最新发布版本：
dsh plugin --profile web add "dsh-token-board@latest"
若 pnpm 元数据缓存导致仍装旧版，可指定精确版本或清理缓存后再装。README 示例：
dsh plugin --profile web add "dsh-token-board@0.1.5"
安装后建议用下面命令确认实际版本，不要只看命令输出：
node -e "console.log(require('./node_modules/dsh-token-board/package.json').version)"
卸载：
dsh plugin --profile web remove "dsh-token-board"
装完必做¶
- 重启对应的 DSH Host（仅刷新浏览器不会加载新的服务端插件），然后 Ctrl+F5。
- 用配置 dump 确认插件已登记（
dsh-token-board在dsh.profile.bundles中应出现一次）：
dsh --dump-config --profile web | grep -A1 dsh-token-board
不要手工在 profile 的 cordis.patch.yml 里重复 insert 注册点；add 已会写入 package.json 的 bundles 与 dependencies。
DSH Desktop 用户¶
Desktop 走应用内插件市场（推荐），或用命令行时先把 DSH_HOME 指到 Desktop 实际使用的 profiles 目录，并确认：
dsh --dump-config --profile web | head -5
装完后应完全退出应用再打开，等效于重启 Host。
其他安装途径（按需）¶
- npm 未发包时：
dsh plugin --profile web add "github:HTempt/dsh-token-board"或带 commit SHA。 - 离线：从 GitHub Releases 下载
.tgz后add "/path/to/dsh-token-board-0.1.5.tgz"。
典型用法¶
- 在
webprofile 完成安装并重启 Host。 - 打开 DSH Web GUI（浏览器或 Desktop），在侧边栏进入「使用统计」。
- 顶部切换时间范围（近 3/6/12 月、全部或自选日期），查看五张指标卡与热力日历。
- 点日历某一天，查看提供商、模型、工作区与逐小时分布（对话框底部）。
- 在「时段」页签查看 0–23 点分布；在「分布」页签切换提供商与模型排行，并对照底部双轴趋势。
插件路由为只读 HTTP 接口，由宿主 webServer 注册；前端依赖 dsh-client-locale、dsh-client-ui-layout、dsh-client-ui-sidebar 注入。
适用场景与注意¶
适合谁：长期在本地用 dsh web 或 DSH Desktop、希望用统一口径回看 token 与调用次数、又不希望用量数据离开本机的开发者。
权限与安全：插件以当前 DSH 进程的权限读取会话持久化路径并写入自身缓存；安装前应阅读源码与 ORIGINALITY.md、LICENSE，确认可接受读写范围。社区目录与 GitHub 仓库由维护者发布，与 DeepSeek / 幻方无官方从属关系，生态上 DSH 理念是「一切皆插件」，本包是其中一项客户端扩展。
可移植性：lib/ 未 import @deepseek-ai/*，纯 Node 内置模块；lib/usage.js 可在无宿主环境下单独做函数级测试，但完整看板仍需 Web GUI 宿主。
结尾¶
dsh-token-board 把本机会话日志收成日、提供商、模型三个维度的用量视图，并配上热力日历、明细弹窗、排行与双轴趋势，且默认不联网。若你已在用 web profile，一条 dsh plugin --profile web add "dsh-token-board" 即可挂上侧边栏入口。
- 目录页：https://www.skillhub.cn/plugins/HTempt/dsh-token-board
- 仓库：https://github.com/HTempt/dsh-token-board
