Token 方块墙 ChinRinhan/dsh-token-wall

dsh-token-wall

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

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

方块墙主面板与桌宠

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

npm 包名是 dsh-token-wall（dsh-token-usage 已被另一个同类插件占用）。
插件内部的标识（路由前缀 /dsh-token-usage、存储目录、localStorage key）都保持不变，所以升级不会丢历史数据。

安装

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

方式一：从 npm 安装（推荐）

cd ~/.dsh/profiles/<profile>
npm install dsh-token-wall

然后在 profile 的 cordis.patch.yml 里插入 bundle：

- insert:
- id: dsh-token-usage # ⚠️ 用这个 id，不是包名 name: 'dsh-token-wall' config: keepDays: 400

⚠️ id 与 name 不同是有意的：id 是插件内部标识（决定路由前缀与存储目录），必须保持 dsh-token-usage 才能沿用已有数据；name 才是 npm 包名。

方式二：从源码克隆

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

方式三：用 DSH 的插件管理

在 DSH 会话里执行：

plugin_manager install_bundle target=dsh-token-wall
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 条记录，回填耗时数秒。

从源码安装迁移到 npm 安装

如果你之前是 clone 到 node_modules/dsh-token-usage 的，改成 npm 安装后要注意目录名变了（dsh-token-usage → dsh-token-wall）：

cd ~/.dsh/profiles/<profile>
rm -rf node_modules/dsh-token-usage # 旧目录（如果不是软链）
npm install dsh-token-wall

历史数据不需要迁移：存储路径由插件内部标识决定，与包名无关，仍是 $DSH_HOME/token-usage/daily.json。

界面

方块墙（主面板）

点侧栏的方块图标进入。

总消耗 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 方块墙 ● alpha ────┐ │ 累计 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-v4.1-flash 合并了 4 个变体

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

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

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

设置页

「Token 用量」一节包含：

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

配置

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

- id: dsh-token-usage # 内部标识，不要改（决定路由前缀与存储目录） name: 'dsh-token-wall' # npm 包名 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.patch.yml | 重启 DSH | 部署期的硬开关 |
| 设置页五个开关 | $DSH_HOME/token-usage/prefs.json | 立即生效 | 日常调整 |

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

其中两个是统计口径（includeSub / includeAux，对应「含子会话」「含辅助调用」）。它们会影响所有读数——方块墙、桌宠、横幅、设置页表格共用同一份口径，改完下一拍轮询就生效。放在这里而不是 Cordis config 里，是为了能随时切换并立即看到差别。

HTTP 接口

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

| 路径 | 说明 |
| GET /dsh-token-usage/today | 今日 + 昨日 + 累计 + 本次运行平均速度 + 当前工作区/模型 + 运行时开关 + 诊断。接受 includeSub / includeAux，与 /summary 同一口径 |
| GET /dsh-token-usage/summary | 区间汇总。groupBy 可取 day week month provider model providerModel kind workspace modelNorm vendor |
| GET /dsh-token-usage/workspaces | 工作区分布，只回 top N（limit / from / to） |
| GET / PUT /dsh-token-usage/prefs | 运行时开关（statusBar / pet / wallPanel）。唯一可写的端点 |

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

数据口径

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

来源

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

| 事件 | 类型 | 说明 |
| assistant/message | 对话调用 | 主力来源 |
| compaction/summary | 辅助调用 | 压缩摘要也是真实模型调用，计入 |

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

合计口径

totalTokens = inputTokens + cacheReadTokens + cacheWriteTokens + outputTokens

也就是「这次调用实际过了一遍的 token 总量」。它跟服务商上报的 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/adapter.test.mjs # 宿主接口：新旧两代形状必须同一读数；认不出来要报 degraded
node --test test/store.retention.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"

改代码后怎么生效

| 改动 | 生效方式 |
| client.js | 约 500ms 内热更新（HMR 轮询文件），不用重启、不用构建 |
| cordis.patch.yml / package.json | 热重载 |
| index.js / lib/** | 禁用→重新启用该 bundle 即可，不用重启 DSH |

已知限制

- 标题生成的开销不可见：日志里没有 usage，无法恢复
- 两个真实进程密集并发写时，后写者可能基于陈旧快照覆盖。桌面场景通常单进程单配置档，影响面有限；根治需要文件锁
- 视觉验证的边界：tools/visual-check.mjs 用的是真实组件 + 真实 CSS + 真实数据，但宿主外壳是模拟的（侧栏、设置面板外框、composer 布局）。驱动真实页面需要 launch token，没有也不该去取
- ≤768px 时桌宠隐藏，窄屏只剩侧栏面板可用
- 保留期到期的那一天，更早的日聚合会从盘上和内存里一起消失（默认 400 天）。这是设计行为，不是 bug；不想要就设 keepDays: 0

宿主接口兼容性

历史回填依赖 ctx.sessionPersistence。这个服务在不同 DSH 版本里换过形状：

| 能力 | 旧版 | 0.1.0-rc.6 起 |
| 列举会话 | list() → {header, revision}[] | listSnapshots()；list() 改为直接返回 SessionHeader[] |
| 读事件 | open(id,'read') → 句柄 | load(id) / inspect(id) / readFrom(id, seq) |
| fork 继承前缀 | handle.inheritedEventCount | header.seedLength / session.firstLiveSeq / session/end-seed 事件 |

插件通过 lib/adapter.js 同时支持两代。认不出来时不会假装成功：设置页「诊断」区会显示 宿主接口: list=… read=…，以及红色的「回填降级」提示——看到它就说明累计数可能偏低，请把这一行连同 DSH 版本一起反馈。

文档

- CHANGELOG.md — 版本变更：每一版修了什么、为什么、怎么验证的
- docs/DESIGN.md — 架构与关键设计：数据流、水位线去重、fork 前缀、桶键、模型归并
- docs/NOTES.md — 开发笔记：踩过的坑、验证器失效的四种方式、视觉问题清单

许可证

MIT