前言¶

在 DSH（DeepSeek Harness）里跑智能体，模型调用会不断发生，但会话界面往往只关心当下这一轮回复。想回答「这个月一共烧了多少 token」「哪个工作区、哪个模型最费」时，通常要翻日志或靠外部记账，口径还容易和 provider 面板对不上。

下面介绍社区插件 dsh-token-usage（维护者 ChinRinhan，分类：模型推理）。它从 DSH 会话日志里读取每次调用的 usage，按本机时区按日聚合，并在 Web 界面提供方块墙、桌宠和设置页汇总；装上之后还能从历史会话回填，而不是从零开始记。

这是什么¶

dsh-token-usage 是面向 DSH Web profile 的 Cordis bundle 插件：Token 用量看板。数据来自持久化的会话日志（assistant/message 等事件上的 usage），合计口径为 inputTokens + cacheReadTokens + cacheWriteTokens + outputTokens，与 provider 上报的 totalTokens 字段不是同一套定义，插件自行按上式计算。

• 目录页：skillhub.cn/plugins/ChinRinhan/dsh-token-usage
• 源码与说明：github.com/ChinRinhan/dsh-token-usage
• 许可证：MIT（见仓库 LICENSE）

核心功能¶

方块墙（主面板）¶

侧栏增加方块图标入口。每 10M tokens 填满一格，100 格一页（对应 10 亿 tokens 一页），累计只增不减；支持「累计 / 今日」切换（今日按本机时区午夜归零）。格子的已填、正在填、空白三态可区分；每 10 格一道里程碑竖线（1 亿 tokens）。

桌宠¶

右下角常驻小面板：当前块的充能进度 + 已攒整块数（池），可拖动标题栏 reposition，位置记在 localStorage。单击标题栏可折叠；视口宽度 ≤768px 时不显示桌宠。充能到 90% 以上有轻微呼吸动效，系统开启「减少动态效果」时会关闭。

消耗分布¶

同一区域可在 工作区 / 模型 / 厂商 三档切换。「模型」视角会把同一模型的不同写法归并（例如带渠道前缀、-free 后缀等），但不同代际（如 deepseek-flash 与 deepseek-v4.1-flash）不会合并。认不出的厂商归入「其他」，可通过配置 modelAliases 手动声明。

设置页与历史¶

设置页「Token 用量」一节提供：桌宠、方块墙面板、输入框上方横幅三个运行时开关（改完立即生效）；今日与累计卡片；按天 / 周 / 月 / 工作区 / 渠道 / 模型等分组的区间汇总表；诊断区（跟踪会话数、回填状态、存储路径等）。

首次启动默认开启 backfillOnStart，会扫描 $DSH_HOME/sessions 下的会话日志，把安装前的用量补进来；之后每次模型调用实时入账。

HTTP 接口¶

启用后宿主注册四条路由（默认与 Web GUI 同端口），例如：

安装与启用¶

本插件以 Cordis bundle 发布，宿主为 DSH 的 Web profile。官方 README 给出两种方式，不要自行拼接未在文档中出现的 dsh plugin add 类命令。

方式一：放进 profile 的依赖目录¶

# <profile> 通常是 ~/.dsh/profiles/<名字>
# Windows: %USERPROFILE%\.dsh\profiles\<名字>
cd ~/.dsh/profiles/<profile>/node_modules
git clone https://github.com/ChinRinhan/dsh-token-usage.git

然后在 profile 的 cordis.patch.yml 里插入本 bundle（或改用方式二由 DSH 写入）。

方式二：用 DSH 的插件管理¶

在 DSH 会话里执行：

plugin_manager  install_bundle  target=<本地路径或包名>
plugin_manager  set_bundle      target=dsh-token-usage  enabled=true

验证¶

把 <port> 换成你的 Web GUI 端口：

curl http://127.0.0.1:<port>/dsh-token-usage/today

返回形如 {"ok":true,"totals":{...},"allTime":{...},...} 即表示路由已注册。界面上应能看到：侧栏方块图标、右下角桌宠、设置页「Token 用量」一节。

配置要点¶

在 profile 的 cordis.patch.yml 中覆盖插件 config（升级插件不会冲掉 profile 里的配置），例如：

- id: dsh-token-usage
  name: 'dsh-token-usage'
  config:
    keepDays: 400              # 保留天数（落盘时淘汰更早的日键）
    includeSubagents: true     # 计入子代理 / 团队 / workflow 子会话
    includeAuxiliary: true     # 计入压缩等辅助调用
    statusBarEnabled: true     # 是否允许显示输入框上方的横幅
    statusBarRefreshMs: 1000   # 轮询间隔，最小 1000
    backfillOnStart: true      # 启动时回填历史

    modelAliases:
      dfmodel:
        vendor: deepseek
        model: deepseek-v4.1-flash

说明两层开关：config.statusBarEnabled 在 Cordis 配置里，改后需重启 DSH；设置页三个开关写在 $DSH_HOME/token-usage/prefs.json，立即生效。日聚合数据在 $DSH_HOME/token-usage/daily.json。

典型用法与数据口径¶

1. 安装并 set_bundle 启用后，等待首次回填完成（数据量大时可能数秒），打开方块墙看累计与今日。
2. 在消耗分布里切换工作区 / 模型 / 厂商，定位用量集中处；当前工作区与模型会高亮。
3. 需要脚本或监控时，轮询 GET /dsh-token-usage/today 或带 from / to / groupBy 的 /summary。
4. 开发机可用仓库内 node tools/usage-cli.mjs --sessions "$DSH_HOME/sessions" --group-by provider 等在终端查看分组用量（见 README「辅助工具」）。

已知限制（README 已写明）：session/title-llm-request 不带 usage，标题生成开销无法从日志恢复；无 usage 的失败或中断调用不入桶，覆盖率见设置页诊断；两个进程密集并发写日聚合时可能出现覆盖，桌面单进程场景影响有限。

适用场景与注意¶

适合长期在 DSH Web 里开发、需要按项目与模型复盘 token 成本、又希望数字与会话日志同一口径的开发者。方块墙适合感知「攒了多少个 10M」；区间表适合对账与周报。

安装前请自行阅读 GitHub 仓库 源码与 MIT 许可证。插件随当前 DSH 进程与 profile 运行，能读 $DSH_HOME/sessions 与会话相关路径；方式一使用 git clone 进入 profile 的 node_modules，请确认来源可信。DSH 社区插件目录（如 SkillHub）为独立生态站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-token-usage 把会话日志里的 usage 变成按日聚合的看板：方块墙、桌宠、分布与设置页汇总，并支持历史回填与四条 HTTP 接口。需要安装步骤与配置字段时，以仓库 README 为准。

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