前言¶

用 DeepSeek Harness（以下简称 DSH）跑一段时间后，常想知道两件事：这个月 token 烧在哪些会话上、哪个模型占了大头。宿主自带的界面给出的是单次请求的用量，不提供按会话、按模型、按天的聚合。自己翻日志写脚本能算出来，但要长期跟踪就得反复重来。

dsh-token-dog 解决的是「聚合这一步」。它不新记账本，直接读已经落盘的 Session 日志，装上去就能看到历史用量，无需从安装当天开始重新统计。下面介绍这个插件的定位、功能、安装方式和数据口径。

这是什么¶

dsh-token-dog（中文名 Token 小狗）是一个 DSH 客户端插件，维护者是 ccodeJava，分类为客户端。它在 DSH Web GUI 里加一个「Token 用量」面板：按会话和按模型统计 token 消耗，用每日堆叠矩形图展示近段时间的构成，用全年日历热力图展示活跃程度。插件只做展示，不改写宿主的任何状态。

配套的目录页在 skillhub.cn 上，仓库地址见文末。

核心功能¶

概览页¶

页面分五个区块：

• 统计卡：总 Token、缓存命中率、输出 Token、调用次数；副行显示会话数、缓存与输入拆分、输出占比、日均调用。
• 每日消耗：每天一根柱子，柱内按会话分段，单日最多 6 段，其余合并为「其他」；悬停看当天总量、调用次数和前 4 个会话的明细。
• 模型用量：每个模型的总量、调用次数、涉及会话数，行内带占比条。行可点击，进入该模型的详情页。
• 会话排行：消耗最多的 8 个会话，含调用次数与最后使用日。
• 活跃日历：近 52 周，周一开头的格子，5 档深浅；悬停看当天总 Token、调用次数、会话数，以及当天所有模型各自的用量与占比。

模型详情¶

点模型行进入详情页，顶部变为「返回」加模型名，内容替换为该模型的统计卡、每日矩形图，以及完整的消耗过该模型的会话列表（不截断）。顶部的区间切换对详情页同样生效。

区间与外观¶

• 区间切换：近 7 天 / 近 30 天 / 近 90 天 / 全部，作用于统计卡、矩形图、排行与模型详情。
• 主题：8 个低饱和预设色（雾蓝、青、苔绿、麦、陶土、藕紫、豆沙、中性），外加自定义取色器；「淡 / 中 / 浓」三档控制同一套色的浓度，只作用于柱子与热度。配色记在 localStorage。
• 中英双语：文案跟随宿主语言，缺字典时回退中文。
• 侧栏图标开关：页面右上角可关掉左侧栏的小狗图标，关闭后仍可从 设置 → Token 用量 进入。

安装与启用¶

插件没有发布到 npm，也不经过构建，安装的是仓库目录本身。前提是宿主已安装 DSH（Desktop 版或 dsh web），版本 0.2.x。

第 0 步：拿到目录¶

git clone https://github.com/ccoderJava/dsh-token-dog.git

没有 git 也可以在仓库页面点 Code → Download ZIP 解压。

方式一：让 DSH 里的 Agent 装¶

在 DSH 里随便开一个会话，把下面这句话发给 Agent，路径换成 clone 下来的实际路径：

把 /Users/you/plugins/dsh-token-dog 这个目录装成插件

Agent 会调用内置的 plugin_manager 完成安装：把 dsh-token-dog 写进当前 profile 的 package.json（以 link: 方式指向该目录），并加入 dsh.profile.bundles。返回里的 application 为 applied 就表示已生效。

方式二：命令行¶

装了 dsh CLI 的环境里（Desktop 版通常没有 CLI，用方式一即可）：

dsh plugin --profile desktop add link:/absolute/path/to/dsh-token-dog

desktop 是 profile 名，默认为 desktop；CLI 用户可能是 default。

安装后¶

刷新页面（Cmd/Ctrl + R）。入口两个：左侧栏最底部的小狗图标（整页打开），或 设置（齿轮）→ 左侧导航最后一项「Token 用量」。第一次打开会扫一遍历史会话，之后结果缓存 60 秒。

确认安装成功：

• 设置 → 插件 → 已安装里能看到 Token 小狗（包名 dsh-token-dog），带小狗图标；
• 左侧栏出现小狗图标；
• 想从命令行确认数据链路：

curl -s "http://127.0.0.1:<GUI 端口>/token-dog/usage?tz=Asia/Shanghai" | head -c 300

更新与卸载¶

方式一装的是软链，改完或拉完代码刷新页面就生效，不需要重装：

cd dsh-token-dog && git pull

卸载时对 DSH 说「把 dsh-token-dog 插件卸了」（走 plugin_manager 的 remove_bundle），或命令行执行：

dsh plugin --profile desktop remove dsh-token-dog

典型用法¶

看某天为什么突然涨了¶

打开概览页，在每日消耗图上悬停对应的某一天，看当天的总量、调用次数和前 4 个会话的明细。如果想进一步知道当天各个模型各自占了多少，切到活跃日历悬停同一天即可。

按模型下钻¶

在模型用量区块点某一行，进入该模型的详情页，看它自己的每日曲线和全部消耗过它的会话。回到概览用顶部的「返回」。

收缩时间范围¶

顶部区间切换放在统计卡、矩形图、排行和模型详情上都会生效。看短期波动用近 7 天或近 30 天，看长期趋势用近 90 天或全部。

调整配色¶

右上角一排色点选预设色，最后一个圆点进入自定义取色器；旁边的「淡 / 中 / 浓」调浓度。配色会持久化，刷新后保持。

数据口径¶

插件不另建账本，数据只来自 Session 日志（ctx.sessionQuery）。它回放日志里的几类事件来拼出每次调用的用量：

几个关键口径：

• 单次调用按 turn:step:attempt 去重，同一 attempt 后来的采样覆盖先前的。
• 总 Token = input + cacheRead + cacheWrite + output，四个桶互不重叠。
• 缓存命中率 = cacheRead / (cacheRead + input)。
• 不计入：不在任何 Session 日志里的调用，例如标题生成、压缩等后台调用。这是「日志即唯一事实来源」的取舍。

Host 侧注册了一条只读路由，仅本机回环可访问：

GET /token-dog/usage?tz=Asia/Shanghai[&refresh=1]

返回体把结果聚合成 day / session / provider / model 维度的行，示例：

{
  "ok": true,
  "generatedAt": 1793860698515,
  "scanMs": 672,
  "timeZone": "Asia/Shanghai",
  "rows": [
    { "day": "2026-11-04", "session": "session-…", "provider": "deepseek-account",
      "model": "deepseek-flash", "input": 344317, "cacheRead": 8053120,
      "cacheWrite": 0, "output": 141471, "calls": 138 }
  ],
  "sessions": { "session-…": { "title": "…", "createdAt": 1793, "cwd": "…", "origin": "", "parent": "" } },
  "scanned": 26, "skipped": 0, "failures": 0, "failureSample": []
}

全量扫描结果缓存 60 秒，refresh=1 立即重扫；扫描期间复用同一次扫描，不叠并发。请求带转发头（X-Forwarded-For / CF-Connecting-IP）、跨站来源或非回环地址时返回 403。数据不过网，浏览器只请求本机 127.0.0.1。

适用场景与注意¶

适合已经在用 DSH、并且想搞清楚 token 花在哪些会话和模型上的人。它的价值在于「装上即可看历史」：因为读的是已有日志，安装之前的对话同样计入，不需要切换到新的记账方式。

几点需要注意：

• 插件以当前 dsh 进程的权限运行。Host 侧路由注册在宿主进程里，安装前应阅读源码（index.js、client.js、cordis.patch.yml）并确认许可证（MIT）。
• 只统计写进 Session 日志的调用。标题生成、压缩这类后台调用不计入，所以和账单数字对不上是正常现象，插件也不做价格换算。
• 扫描窗口是最近 400 天内创建或当前在线的会话，上限 600 个，超出时页面会提示。
• 每日矩形图超过 120 天只画最近 120 天；柱子只画当天有用量的日子，无用量的一天不占位。
• 日历热度按当天 token 的分位数分级，跨主题、跨区间会重新计算，因此两个区间之间的深浅不可直接比较。
• 插件依赖宿主的 settings.section / main / sidebar.panellist 席位与 sessionQuery 服务，DSH 大版本升级后需重新验收席位行为。README 标注的验证环境是 DSH 0.2.1-rc.5（Desktop, macOS）。

结尾¶

dsh-token-dog 做得比较克制：不新造数据源，不引外部依赖，只在宿主本地把已有的日志整理成可下钻的视图，数据链路也是封闭在回环接口上的。对于 DSH 0.2.x 用户来说，它是现有 Web GUI 的一个补充，装一个目录就能用。

目录页：https://www.skillhub.cn/plugins/ccoderJava/dsh-token-dog
仓库：https://github.com/ccoderJava/dsh-token-dog