前言¶

用 DSH 跑智能体，会话日志都落在 $DSH_HOME/sessions 下面，token 消耗散在一条条会话里。想回答「这个月每天用了多少 token」「哪个模型用得最多」，就得自己解压 zstd 压缩的 JSONL、逐条折算，写一次脚本不难，但每次看都要重跑。

@kelearns/dsh-token-usage 把这件事搬进了 GUI：一块 GitHub 风格的贡献图，展示每日、每周、累计的 token 消耗。DSH 的理念是「一切皆插件」，这个插件就是通过官方插件机制挂载的，不需要改 dsh 源码。下面介绍它的功能、安装方式和数据口径。

这是什么¶

@kelearns/dsh-token-usage 是 DeepSeek Harness（dsh）web GUI 的 Token 用量热力图插件，由 KeLearns 维护，当前版本 0.1.1，MIT 许可证。安装后，dsh 设置侧栏会出现 Token Activity 入口，点开就是热力图。

它解决的问题是：不写脚本、不动源码，直接在 dsh 界面里看到 token 消耗的趋势和构成。

核心功能¶

• 汇总气泡（Summary bubble）：单个圆角容器里放 5 项统计——总量、峰值日、最长会话、当前连续、最长连续，竖线分隔；
• 三种视图：Daily（按日颜色等级）、Weekly（按周堆叠单元格）、Cumulative（按周累计堆叠，最新一列恒满）；
• 时间窗切换：最近 3 / 6 / 12 个月，默认 12；12 个月视图横向滚动，自动滚到最新一周；
• 悬停详情：悬停单元格显示当日总量、当周总量或截至当日的周累计，zh / en 本地化；
• 活动洞察：最常用模型 / 推理强度 / 工具、峰值小时、日均与月均、最活跃工作日与最活跃一天；
• i18n：zh / en，实时跟随文档语言；
• 主题：浅色 / 深色调色板，跟随 dsh 应用主题；
• 自动刷新：每 60 秒及窗口聚焦时重新扫描变更的会话文件；
• 跨平台：宿主侧只用 Node 标准库（fs / path / os / zlib），支持 Windows / macOS / Linux。

安装与启用¶

前提是 PATH 里有 pnpm：

npm install -g pnpm

从 npm 安装（推荐）：

dsh plugin --profile web add @kelearns/dsh-token-usage

安装器会读取 cordis.patch.yml（dsh.bundle.patch 清单字段），自动应用插件行，不用手动改补丁文件。安装完成后重启 dsh web 生效。

本地开发时，在插件仓库根目录运行，link:. 会解析为当前目录：

dsh plugin --profile web add link:.

卸载：

dsh plugin --profile web remove @kelearns/dsh-token-usage

不走 CLI 也可以手动安装，分三步：

1、把包放进 $DSH_HOME/profiles/web/node_modules/@kelearns/dsh-token-usage；

2、向 $DSH_HOME/cordis.patch.yml 追加下面的 insert 块（可重复执行）：

- insert:
    - id: dsh-token-usage
      name: '@kelearns/dsh-token-usage'

3、重启 dsh web。

这个插件收录于 awesome-dsh-plugin 精选注册表，也可以在 dsh 设置的 Plugin Market 标签页里用 token-usage 搜索安装。

数据来源与统计口径¶

插件读取 dsh 官方会话日志：$DSH_HOME/sessions/<workspace>/<session-id>/session.jsonl.zstd，即拼接 zstd 帧的 JSONL。token 用量从 assistant/chunk 事件中 chunk.type === "usage" 的记录折算，总量 = input + output + cacheRead。活动洞察还会读取 request/header（模型 / 推理强度）和 tool/call（工具）事件。

几点口径需要先知道：

1、只统计携带 usage 事件的会话（dsh 会话日志格式，已在 0.1.0-rc.6 上验证）；
2、日期按进程本地时区归属，一周从周一开始；
3、zstd 解压需要 Node >= 22.2（包的 engines 为 ^22.19.0 || >=24.0.0，官方 dsh 运行时满足）；
4、缺失或不可读的会话目录返回空统计，不影响 GUI。

配置与 HTTP 接口¶

配置只有一项 refreshIntervalMinutes，控制后台重扫间隔（分钟），默认 5。在 cordis.patch.yml 的 insert 块里加 config 即可：

- insert:
    - id: dsh-token-usage
      name: '@kelearns/dsh-token-usage'
      config:
        refreshIntervalMinutes: 5   # 后台重扫间隔，默认 5

插件注册了三个同源 HTTP 路由：

测试¶

仓库自带三个测试脚本，分别覆盖不同层面：

node test/mock.test.mjs                            # 合成数据的完整流水线
node test/mock.test.mjs "$env:USERPROFILE\.dsh"    # 真实数据冒烟（任意 DSH_HOME）
node test/layout-algo.mjs                          # 布局算法矩阵

第二条可以指向任意 DSH_HOME，用自己的会话数据做冒烟验证。

适用场景与注意事项¶

适合已经在用 dsh web GUI、想直接在界面里看 token 消耗趋势和构成的人。如果每天开着 dsh 跑会话，这块热力图能回答「今天用了多少、最近几周趋势如何、哪个模型用得最多」这类问题。

安装前有两点务必注意：

1、插件以当前 dsh 进程的权限运行，装之前建议先过一遍源码和许可证（MIT），确认自己接受；
2、会话日志格式在 0.1.0-rc.6 上验证过，如果你的 dsh 版本差异较大，先跑一遍上面的测试脚本确认解析正常。

小结¶

@kelearns/dsh-token-usage 把散落在会话日志里的 token 数据搬进了 dsh 界面：一条安装命令，重启后就能看到每日 / 每周 / 累计的消耗热力图和活动洞察，不用自己维护解析脚本。经过上面的步骤装好重启，设置侧栏里的 Token Activity 就是入口。

项目地址与收录页：

• GitHub：https://github.com/KeLearns/dsh-token-usage
• 社区目录页：https://www.skillhub.cn/plugins/KeLearns/dsh-token-usage

社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。