前言¶

DeepSeek Harness（dsh）把模型适配、工具、会话日志和界面都做成插件。日常用下来，token 是实打实烧掉的：今天已经用了多少、近一周哪几个模型占大头、开过多少顶层对话，默认界面并不集中展示。自己翻会话日志也能算，但事件字段散、子代理会话混在一起，数字很难一眼看完。

社区插件 dsh-token-monitor 把这件事做成侧边栏底部的「今日用量」卡片：数字一直挂着，点一下弹出完整看板。本文按社区目录页、GitHub 仓库 README、package.json 和宿主源码交叉核对后整理：它是什么、当前版本实际画什么、怎么安装，以及数据从哪来。

这是什么¶

dsh-token-monitor 是一款面向 DeepSeek Harness Web 界面的会话与消息插件，由 zhangzheng25 维护，仓库在 zhangzheng25/dsh-token-monitor，许可证为 MIT，主要语言是 JavaScript。查阅时 package.json 版本为 0.6.0，GitHub 显示 5 星；社区目录页仍显示 4 星，收录分类为「会话与消息」。

它解决的是本地用量可见性，而不是去官方计费接口拉余额。当前实现（2026-08-16 的 main 提交 a627daf）是：

• 在侧边栏底部、设置图标旁放一张「今日用量」卡片，单行显示今日 token 总量
• 点击卡片弹出「Token 用量」窗口：今日 / 近 7 天 / 近 30 天总量、近 30 天按模型堆叠柱状图、前 4 名模型排行，以及对应时段的顶层会话数
• 用量只从会话日志回填，安装之前的历史也会统计进来

需要先说明一处来源差异。社区目录页和 GitHub 仓库简介仍写着「设置 → Token 用量」以及 GitHub 风格的 90 天贡献图。那是较早版本的文案。仓库 README 与 client/bundle.js 已经改成侧边栏卡片加弹窗，不再注册设置页，图表也改成近 30 天按模型分色堆叠，而不是 90 天贡献热力图。下文以仓库当前源码为准。

DeepSeek Harness 官方仓库的定位是「一切皆插件」，社区插件目录是独立站点，和 DeepSeek / 幻方没有从属关系，不能当成官方应用商店。

核心功能¶

侧边栏「今日用量」卡片¶

客户端把卡片挂到 sidebar.footer.action 槽位，位置在会话列表下方、设置齿轮旁边。展开侧栏时显示「今日用量：」加数值；折叠成约 56px 窄栏时只留数字。

卡片每 30 秒请求一次宿主的 /token-monitor/today。这条路由只读内存里的「今天」桶，不触发全量重建，所以侧栏轮询比较轻。今日总量按输入、输出、缓存命中、缓存写入四项相加；推理 token 会写入按天桶，但不计入这张卡片和弹窗里的总量数字。

数值格式按量级切换：过万用「万」，过亿用「亿」，再大用 B / T。README 里的示例文案是「今日用量：8888万」。

弹窗里的总量和会话卡¶

点击卡片后出现固定遮罩弹窗，标题为「Token 用量」，可用 Esc、右上角 ✕ 或点击遮罩关闭，打开时锁定背景滚动。面板里先是三张总量卡：

• 今日 Tokens
• 近 7 天 Tokens
• 近 30 天 Tokens

下面再跟三张会话卡：今日 / 近 7 天 / 近 30 天开启的顶层对话数。副文字是对应时段的模型请求次数。子代理内部会话（delegationDepth !== 0）不计入对话数，避免一次委派把数字抬高。

页头还有「刷新」和「回填历史」两个按钮，并显示「统计自 … · 历史回填至 …」时间。弹窗打开后拉 /token-monitor/snapshot，之后同样每 30 秒轮询。

近 30 天按模型堆叠图¶

图表固定 30 天窗口。每一天一根柱，按模型分色堆叠；当天用量最高的模型在柱底，颜色按近 30 天总用量排名固定，用一套莫兰迪色板。横轴只标每周一的日期。悬浮或点击某天会钉住明细卡：日期、总计、各模型色块行。没有柱上数字，也没有高亮变灰。

没有数据时，界面提示：「暂无模型用量数据——插件升级后点一次「回填历史」即可。」

模型使用排行¶

排行同样锁在 30 天窗口，取前 4 名，排成 2×2 卡片。每张卡是：序号一行、模型名加 token 总数、提供商加占比。占比在浏览器端用该模型总量除以 30 天全模型总量算出。卡片不显示增长率，也不显示「总计」「新增」这类标签。

模型身份来自会话事件里 message.source 的 provider 和 model，拼成 provider:model。缺字段时记为 unknown。

会话日志回填和本地持久化¶

宿主半在 src/index.js。v3 把会话日志定为唯一数据源：通过 sessionQuery 列出会话、读事件，只折叠 assistant/message 上的 usage（输入 / 输出 / 缓存命中 / 缓存未命中 / 推理），按天、按模型分桶。sessionQuery 是 live-preferred，内存里的进行中会话和落盘日志都会算进去，所以不必再挂 llm/stream 实时钩子。README 写明旧版「瀑布流实时捕获 + 日志回填」会把同一次调用计两次，v3 已去掉实时路径，每次把窗口内数据折进新 Map 再原子替换，重复运行不会叠加。

回填在这些时机触发：启动约 3 秒后、点击「回填历史」、快照轮询带 ?backfill=1。全量折叠有 20 秒节流，同一时刻只跑一轮。

持久化文件是 $DSH_HOME/plugins/token-monitor/data.json（未设置 DSH_HOME 时为 ~/.dsh/plugins/token-monitor/data.json），schema 版本 3，按天桶保留 181 天。若仍存在旧路径 $DSH_HOME/plugins/token-usage/data.json，首次加载会尝试迁过去。

安装与启用¶

社区目录页给出的安装命令如下，在 DeepSeek Harness 终端里运行：

dsh plugin add github:zhangzheng25/dsh-token-monitor

仓库 README 额外标明这是 Web 端插件（package.json 里 dsh.client.platform 为 "web"），建议显式指定 web profile：

dsh plugin --profile web add github:zhangzheng25/dsh-token-monitor

本地目录也可以装：

dsh plugin --profile web add /path/to/dsh-token-monitor

需要可复现安装时，目录页建议固定 commit 哈希。查阅时 main 最新提交是 a627daf（2026-08-16，对应 0.6.0 侧边栏卡片改动）：

dsh plugin --profile web add github:zhangzheng25/dsh-token-monitor#a627daf46e6ac822445e882353f70a8a81c2420a

dsh plugin 会在 profile 目录里交给 pnpm，并调和 dsh.profile.bundles。包内 cordis.patch.yml 把 id 为 token-monitor 的插件行插入宿主组合，而不是某个 agent 预设——它要读宿主上的 sessionQuery、timer、webServer。

安装后需要重启 DSH。官方 Web UI 的启动方式是：

npx @deepseek-ai/dsh web

默认地址 http://127.0.0.1:3080。重启后侧边栏底部应出现「今日用量」卡片；点卡片即弹出统计窗口。package.json 要求 Node.js >= 20。DeepSeek Harness 本身仍处于开发者预览，官方 README 写明可能出现破坏兼容性的变更。

典型用法¶

1. 确认当前跑的是 Web 界面，而不是无界面的 headless 一次运行。该插件的客户端 bundle 只给 web 外壳加载。
2. 按上一节安装并重启。若卡片不出现，先看 profile 是否为 web，以及宿主组合里是否已插入 token-monitor。
3. 看侧栏数字是否在变。进行中的调用也会进会话语料，但卡片 30 秒才轮询一次，不必期待每个 token 都即时跳动。
4. 打开弹窗。若堆叠图是空的，点一次「回填历史」，等下一轮快照。升级后旧桶可能被丢弃，源码注释写明 v1/v2 迁到 v3 时会清空再从会话语料重建。
5. 用 30 天排行对照自己实际在用的模型名。占比只反映本机会话日志里的用量结构，不是官方账单。
6. 需要核对原始数字时，打开 $DSH_HOME/plugins/token-monitor/data.json。里面是按天、按模型的桶，不是计费明细。

适用场景与注意事项¶

适合这些情况：

• 长期开着 DSH Web UI，想在侧栏直接看到今日 token
• 同一套环境里切换多个模型，想看近 30 天谁占用最多
• 关心顶层对话开了多少，而不是把子代理内部会话算进去
• 插件装得比较晚，但仍希望把安装前的会话日志统计进来

使用前注意下面几条，均来自目录页、仓库说明或源码，不是额外发挥：

1. 插件以当前 dsh 进程的权限运行。 社区目录页写明：安装时可能执行代码。装之前应查看源代码仓库和许可证；需要可复现安装时固定 commit。
2. 只统计本机会话语料，不查账户余额，也不按单价折算费用。 和走 DeepSeek 官方用量接口、或专门做费用账本的插件不是同一类东西。
3. 只服务 Web 界面。 dsh.client.platform 为 "web"，headless 流程看不到这张卡片。
4. 界面总量不含推理 token。 桶里有 reasoningTokens 字段，卡片和排行用的合计是输入 + 输出 + 缓存读写。
5. 会话数只计顶层。 delegationDepth === 0 才计入；子代理内部会话被排除。
6. 仓库带有 AI 生成声明。 README 写明项目由 AI 辅助生成，仅供学习与技术交流，不构成商业保证或支持承诺。许可证是 MIT，版权页标注 Copyright (c) 2026 zhangzheng25。
7. 目录页文案可能滞后。 若仍看到「设置页 / 90 天贡献图」，以仓库 README 和当前 main 为准。

小结¶

dsh-token-monitor 把 token 用量和顶层会话统计做成 DSH Web 侧栏里的一张卡片：今日数字一直可见，点开是 7 天 / 30 天总量、按模型堆叠图和前 4 名排行。数据只从会话日志幂等回填，装插件之前的用量也能算进来，重启后落在本地 data.json。它不替代官方账单，只解决「这台机器上的 Harness 到底用了多少」这一眼能看清的问题。

目录页与仓库：

• 社区目录：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-token-monitor/
• GitHub：https://github.com/zhangzheng25/dsh-token-monitor
• DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness