dsh-token-bubbles

dsh-token-bubbles

中文 | English

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

A useful — or delightfully useless — plugin for DeepSeek Harness that visualizes your token usage as you go. It's just delightful watching colorful bubbles pop up while your agent is emptying your wallet, isn't it?

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