Token 气泡可视化 Player047/dsh-token-bubbles

dsh-token-bubbles

这是一个氛围编程（Vibe Coding）项目。使用 Deepseek V4 Pro 模型，@Deepseek-Harness。

一个对 DeepSeek Harness 有用——或者令人愉悦地无用——的插件，可在你使用过程中将 token 用量可视化。看着彩色气泡在你家 agent 掏空你钱包时冒出来，难道不是很愉悦吗？

DeepSeek Harness web GUI 的 token 可视化插件：生成 token 时，右下角会冒出一个个彩色小方块，按顺序排列，每行 10/20 个，每个方块代表的 token 数可以分别设置（输入系 / 输出系各一个除数，自由调倍数）。

| 颜色 | 含义 |
| 🟪 紫红 #e446f9 | 输出 token（可见回复文本） |
| 🟣 深紫 #5524a4 | 思考 token（reasoning） |
| 🔵 浅蓝 #79c4ff | 输入 token（缓存未命中） |
| 🔵 深蓝 #2d5cf6 | 输入 token（缓存命中） |

颜色可在 COLORS 常量里改。

所有方块进入同一条 FIFO 队列，由定时器按 revealIntervalMs 的节奏逐个放出：每个方块上屏时都落在右下角最贴近角落的位置，所以无论哪种颜色，网格都从下往上生长（最新方块在最下，旧的被推向左侧和上方；换行时整块网格带 150ms 平滑上移动画）。队列不会中途清空——每一步产生的方块都排在队尾接着显示，只有切换会话时清屏。整层 pointer-events: none，不会遮挡或阻挡对话操作。

两个可选机制（都默认开启，见配置表）：

- 超时消失：每个方块显示 lifetimeMs 后，从最老的开始溶解——从顶行开始、行内从左往右、逐行向下，节奏由 expireIntervalMs 控制。溶解时其余方块原地不动，最底下一行始终保持满员，直到上方全部消完才轮到它；网格自动变成时间窗口；
- 自适应速度：等待队列越长，每 tick 放出的方块越多（积压每多 adaptiveStep 个多放 1 个，单 tick 上限 adaptiveCap 个），不会让显示等太久。

同屏数量超出 maxSquares 时仍会整行淘汰最顶上的一行（带离场动画），作为兜底。

数据来源有两个：

- 紫红（输出）/ 深紫（思考）：实时估算——直接订阅当前会话快照的流式 partial 块，按语言自适应折合（CJK ≈ 1.2 字符/token、其他 ≈ 4 字符/token，常数由真实会话的官方用量标定），把 text 与 reasoning 两类块分开计数，模型一边写、方块就一边排队；每次模型调用结束时，再用官方 outputTokens 对账（calibrateWithUsage），差额补发/回扣，把总数校准到官方真值。
- 浅蓝（输入未命中）/ 深蓝（缓存命中）：token-meter 的 tokenUsage 会话投影（uncachedInputTokens / cacheReadTokens / cacheWriteTokens），在每次模型调用上报用量时推送。

安装

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

dsh plugin --profile web add github:Player047/dsh-token-bubbles

想锁版本可以带 tag（按仓库实际 tag 替换）：

dsh plugin --profile web add github:Player047/dsh-token-bubbles#v0.4.5

方式二：本地开发（link 安装）

git clone https://github.com/Player047/dsh-token-bubbles.git
dsh plugin --profile web add .\dsh-token-bubbles

两种方式都会在 web profile 目录里执行 pnpm 安装，并把 dsh-token-bubbles 自动追加进 dsh.profile.bundles（包的 cordis.patch.yml 会插入宿主行，宿主行是 no-op，仅用于让客户端 bundle 被 /plugins/dsh-token-bubbles/client.js 提供）。

- GitHub 安装 = 拷贝进 profile，改配置请改自己 profile 里的 node_modules/dsh-token-bubbles/lib/client.js，改完重启生效；
- link 安装 = 直接指向本地源码，改源码后重启即可生效，适合开发迭代。

安装后重启 web profile 生效：

dsh web

（旧进程退出后重新启动即可；会话有持久化，对话不会丢。还没有 web profile 的用户，dsh plugin 会自动初始化。）

卸载

dsh plugin --profile web remove dsh-token-bubbles

然后重启 dsh web。

配置

客户端 bundle 顶部的 CFG 常量就是全部配置，改完重启 dsh web 生效：

| 键 | 当前值 | 说明 |
| inputTokensPerSquare | 1000 | 输入系（未缓存输入 + 缓存命中）每个方块代表的 token 数 |
| outputTokensPerSquare | 10 | 输出系（正文 + 思考）每个方块代表的 token 数；调小（如 100）让输出方块更密，与输入量级平衡 |
| columns | 20 | 每行方块数（可选 10 / 20） |
| squareSize / gap | 12 / 3 | 方块边长与间距（px） |
| maxSquares | 1100 | 屏幕上同时存在的方块数上限，超出时整行淘汰最顶上的一行（带离场动画，兜底） |
| pendingCap | 100000 | 待显示队列的软上限（防异常堆积） |
| batchCap | 100000 | 单次用量更新最多入队的方块数 |
| revealIntervalMs | 1 | 显示节奏：每多少 ms 一个 tick |
| timeoutEnable | true | 超时消失开关：开启后每个方块显示 lifetimeMs 后从最早的开始逐个消失 |
| lifetimeMs | 20000 | 方块显示时长（ms），配合 timeoutEnable |
| expireIntervalMs | 10 | 逐个消失的节奏：每多少 ms 让最老的 1 个过期方块离场 |
| adaptiveSpeed | true | 自适应速度开关：积压越多每 tick 放出越多 |
| adaptiveStep | 100 | 每积压多少方块，每 tick 多放 1 个 |
| adaptiveCap | 50 | 每 tick 最多放出的方块数 |
| cjkCharsPerToken | 1.2 | 流式估算：CJK 字符每 token 字符数（官方用量标定） |
| otherCharsPerToken | 4 | 流式估算：英文/数字/代码每 token 字符数（思考实测 ≈3.9） |
| calibrateWithUsage | true | 官方校准开关：每次调用结束用官方 outputTokens 对账补差 |
| corner | {right:16, bottom:16} | 右下角留白 |

工作原理

- 宿主侧：包被挂载为 composition 里的一行（no-op 插件），dsh-client-modules 据此把 lib/client.js 以 /plugins/dsh-token-bubbles/client.js?rev=… 注入启动清单。
- 客户端侧：bundle 通过 window.__ModuleLoader__ 注册为 Cordis 客户端插件（inject: ["slots", "sessions", "timer"]），把可视化组件注册进 shell.overlay（框架级浮层，点击穿透）。
- 组件订阅 sessions.currentProvideInfo 拿到当前会话；tokenUsage 投影的可观察面产生蓝色方块（输入/缓存增量），会话快照的流式 partial 产生深紫（思考）与紫红（输出）方块（按 CJK/其他 语言自适应折合估算 token，边写边排队，调用结束时用官方用量校准）。所有方块都进入同一条 FIFO 队列，由 timer 服务按 revealIntervalMs 逐个放出，因此所有颜色都从右下角向上生长；超出行数上限时最顶上一行播放离场动画后移除，会话切换时清屏并重新建立基线。

License

MIT