dsh-token-usage

dsh-token-usage

Token 用量看板插件，用于 DSH（DeepSeek Harness）。

按本机时区记录每次模型调用的 token 消耗，并把「攒了多少」做成看得见的方块墙。

• 方块墙：每 10M tokens 填一格，100 格一页，累计只增不减
• 桌宠：常驻角落里的小面板，一个充能块 + 一个池，可拖动
• 消耗分布：按工作区 / 模型 / 厂商三档切换
• 设置页：区间汇总表，支持按天 / 周 / 月 / 渠道 / 模型 / 类型分组
• 历史回填：从已有会话日志补齐历史，不是装上才开始记
• 实时捕获：之后每次模型调用即时入账

---

安装

本插件以 Cordis bundle 形式发布，宿主是 DSH 的 Web profile。

方式一：放进 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 用量」一节。

首次启动会回填历史

backfillOnStart（默认开启）会扫描 $DSH_HOME/sessions 下的会话日志，把装上之前的用量补进来。

参考量级：本机 116 个会话、22 天、8,410 条记录，回填耗时数秒。

---

界面

方块墙（主面板）

点侧栏的方块图标进入。

总消耗 684,561,075 tokens   已获得 68 块 · 第 1 页
████ ████ ████ ████ ████ ████ ████ ████ ████ ████
████ ████ ████ ████ ████ ████ ████ ████ ████ ████
...
████ ████ ████ ████ ████ ██▓░ ░░░░ ░░░░ ░░░░ ░░░░
░░░░ ░░░░ ░░░░ ░░░░ ░░░░ ░░░░ ░░░░ ░░░░ ░░░░ ░░░░

• 每 10M tokens 一格：已填 / 正在填（按比例渐进）/ 空白，三态一眼分清
• 每 10 格一道里程碑竖线（= 1 亿 tokens），首末行标出该行的量级，看颜色密度就能判断这一段是 2 亿还是 200 亿
• 100 格一页（= 10 亿 tokens），自动停在第 N 页
• 累计 / 今日 可切换：累计是只增不减的历史总量，今日是午夜归零的当天量
• 页面下方是消耗分布与诊断信息

为什么是 10M：按真实数据量过，单轮对话中位 1.41M、p90 10.4M，典型活跃日 2–3 块、重度日 7–9 块。快慢都合适。

桌宠

常驻在窗口任意位置，也可以拖走。

┌─ Token 方块墙  ● dafeiyu  ─┐
│ 累计 2.98B                  │
│ ▓▓▓▓▓▓▓▓▓▓▓▓▓░░  94%       │  ← 充能块：当前这块填了多少
│ ■ 297 块                    │  ← 池：已攒下的整块数
│ 今日 31.44M 1.1% ·          │
│ 速度 4.0K/s  昨日 127.79M   │
└─────────────────────────────┘

• 拖动：按住标题栏拖，指针移出窗口也继续跟手
• 单击标题栏：折叠 / 展开（折叠后只剩一行数字，仍可拖动）
• 位置记忆：位置存在 localStorage，窗口缩放时自动钳制在可视范围内
• 窄屏隐藏：≤768px 不显示（拖拽手势会和页面滚动打架）

动效很克制：充能到 90% 以上时充能块轻微呼吸，攒到新的一块时池弹一下。系统开了「减少动态效果」时会全部关掉。

消耗分布

同一块区域，三个视角切换：

「模型」视角会自动归并同一模型的不同写法。比如这四行其实是同一个模型：

deepseek-v4.1-flash             1.54B   ← 主名
workbuddy/deepseek-v4.1-flash   25.6M   ← 带渠道前缀
deepseek-ai/deepseek-v4.1-flash   52K   ← 另一种前缀
deepseek-v4.1-flash-free        23.1M   ← 带 free 后缀

归并后合成一行：1.62B · 4 个变体。

⚠️ 但不同代际不合并。deepseek-flash、deepseek-v4-flash、deepseek-v4.1-flash 是三个版本，合并会掩盖「还在用旧模型」这件事。

⚠️ 认不出厂商的模型归入「其他」，不猜。可以用配置里的 modelAliases 显式声明，见下。

当前在用的工作区 / 模型会高亮。

设置页

「Token 用量」一节包含：

• 运行时开关：桌宠 / 方块墙面板 / 输入框上方横幅，三个独立开关，点完立即生效
• 今日与累计卡片
• 区间汇总表：按天 / 周 / 月 / 工作区 / 渠道 / 模型 / 渠道+模型 / 类型分组
• 时长预设（近 7 天 / 30 天 / 90 天）+ 自定义起止日期
• 过滤开关：含子会话、含辅助调用
• 诊断区：已跟踪会话数、实时入账数、回填状态、存储位置

---

配置

在 profile 的 cordis.patch.yml 里覆盖，插件升级不会丢：

- 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

开关有两层，分别管什么

设置页那三个开关存在独立文件里，是因为改 Cordis config 要重启，而「我想把桌宠关掉」显然不该重启。

---

HTTP 接口

启用后宿主注册四条路由，默认绑定 Web GUI 的端口。

/summary 还支持 from / to / includeSub / includeAux / workspace 参数。

---

数据口径

这一节讲清楚「数字是怎么算出来的」，因为它决定了你看到的数字意味着什么。

来源

会话日志里 assistant/message 事件的 usage 字段。它是持久化的，所以「历史回填」和「实时捕获」读的是同一份数据，不存在两套口径。

⚠️ 标题生成走的 session/title-llm-request 不带 usage，因此那部分开销无法从日志恢复。这是已知限制，不是遗漏。

合计口径

totalTokens = inputTokens + cacheReadTokens + cacheWriteTokens + outputTokens

即「这次调用实际过了一遍的 token 总量」。它与 provider 上报的 totalTokens（通常只是 input+output）不是一回事，所以本插件不读那个字段，自己按上式算。

outputTokens 已含思考 token，reasoningTokens 只作拆分展示，不重复计入。

「没测到」≠「用了 0」

没带 usage 的调用（中断、上游提前断开、失败）不写 0，而是根本不入桶。覆盖率在设置页诊断区如实展示。

时区

按本机时区切日，不是 UTC。午夜归零。

存储位置

$DSH_HOME/token-usage/daily.json（日聚合）与 $DSH_HOME/token-usage/prefs.json（开关）。

只落日聚合、不落明细；增量合并写，多实例并存不互相覆盖；默认 2 秒防抖落盘。

更多实现细节见 docs/DESIGN.md。

---

开发

npm test          # 全部不依赖本机数据的测试
npm run test:data # 需要本机会话日志：交叉校验 + 存储端到端
npm run visual    # 生成视觉验证 HTML，再用浏览器截图
npm run check     # 语法检查 + 落单反引号检查

测试文件

node --test test/fold.test.mjs          # 日界、周月归属、合计口径、水位线去重、fork 前缀
node --test test/blocks.test.mjs        # 方块换算：整除、跨页、当前块、进度、异常输入
node --test test/models.test.mjs        # 模型归并：归一化、代际不合并、别名
node --test test/prefs.test.mjs         # 运行时开关存储：缺省、原子写、脏输入、损坏回退
node test/client.smoke.mjs              # 四个 slot 注册、样式真进 DOM、主题 token
node test/odometer.text.mjs             # 桌宠可见文案逐条断言
node test/sparkline.test.mjs            # 上升曲线几何：左低右高、不除零
node test/blocks-cross.test.mjs         # 主面板/桌宠 与 lib/blocks.js 的跨端一致性
node test/distribution.test.mjs         # 消耗分布：形状守卫、列宽预算、当前项高亮
node test/host.routes.test.mjs          # 四条路由的 JSON 契约

需要本机数据的两个（不在 npm test 里）：

node test/cross-validate.mjs "$DSH_HOME/sessions"   # 与独立实现交叉校验真实日志
node test/store.e2e.mjs "$DSH_HOME/sessions"        # 回填 → 落盘 → 重开 → 幂等 → 并发

辅助工具

node tools/usage-cli.mjs --sessions "$DSH_HOME/sessions" --group-by provider
node tools/rehearse.mjs                          # 用真实 home 跑一遍完整回填
node tools/preview-blocks.mjs                    # 字符画方块墙
node tools/analyze-blocks.mjs                    # 分析「10M 一格」的填充速度
node tools/migrate-workspace.mjs --home "$DSH_HOME"   # 桶键 4 段 → 5 段（dry-run）
node tools/visual-check.mjs                      # 生成视觉验证 HTML

tools/visual-check.mjs 把真实组件装进真实 React 18，在浏览器里渲染（effect / fetch 全真），主题 token 从宿主的真实 CSS 里读。截图用 Windows 自带的 Edge 就行：

"/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" \
  --headless=new --disable-gpu --hide-scrollbars --virtual-time-budget=6000 \
  --window-size=1000,1400 --screenshot=tools/out/light.png \
  "file:///$(pwd)/tools/out/visual-check.html"

改代码后怎么生效

---

已知限制

• 标题生成的开销不可见：日志里没有 usage，无法恢复
• 两个真实进程密集并发写时，后写者可能基于陈旧快照覆盖。桌面场景通常单进程单 profile，影响面有限；根治需要文件锁
• 视觉验证的边界：tools/visual-check.mjs 用的是真实组件 + 真实 CSS + 真实数据，但宿主外壳是模拟的（侧栏、设置面板外框、composer 布局）。驱动真实页面需要 launch token，没有也不该去取
• ≤768px 时桌宠隐藏，窄屏只剩侧栏面板可用

---

文档

• docs/DESIGN.md — 架构与关键设计：数据流、水位线去重、fork 前缀、桶键、模型归并
• docs/NOTES.md — 开发笔记：踩过的坑、验证器失效的四种方式、视觉问题清单

许可证

MIT