前言¶
在 DeepSeek Harness（DSH）里跑多个工作区、多段会话时，token 往往分散在各会话的投影缓存里。想核对「一共烧了多少」，常见做法是打开某个会话面板或对照 dsh-context 一类的用量展示——都要先找到对的地方。维护者 Friade 的 dsh-token-bubble（仓库 README 亦称 dsh-token-meter）把同一口径的累计数字放到 GUI 右下角：一颗可拖动的胶囊，点开可看会话级明细，数值再点可看到精确读数。插件归类为「模型推理」，当前 GitHub 星标为 0，许可证 MIT（package.json 版本 0.1.0，要求 dsh 引擎 >=0.2.2-rc.1）。
这是什么¶
dsh-token-bubble 是 DSH 的 bundle 插件：在宿主 Web GUI 注入悬浮挂件，只读扫描会话投影，通过 HTTP 路由把聚合结果交给浏览器端渲染。它不修改会话数据，也不替代 DSH 自带的计费或限流逻辑，只是把「全部工作区、全部会话」的累计 token 摆在随手可见的角落。
统计口径与数据范围¶
先做数据从哪来，再谈界面上显示什么。
- 宿主读取 DSH 会话投影目录下的 JSON：默认路径为
$DSH_HOME/storages/session_projcache/sessions/*.json。 - 对每个文件取
tokenUsage.totals，把四类相加：未命中输入、输出、缓存读、缓存写，作为该会话的累计值（整条会话日志的累计，不重算、不回填）。 - 对所有会话求和，得到胶囊上的总额；已归档会话、子代理会话只要投影里有非零用量，一并计入。
口径参考 dsh-context 的用法，展示位置从对话框挪到了右下角挂件。
核心功能¶
悬浮胶囊与会话明细¶
GUI 右下角起点放置可拖动胶囊，显示全部工作区累计 token。单击展开面板：按会话列出名称、工作区路径、用量与时间等；需要精确数字时再点数值。面板根据胶囊在屏幕上下半区自动向上或向下展开，左右靠边或居中对齐，空间不足时面板内滚动。
刷新与主题¶
浏览器端每 10 秒轮询一次 data.json；窗口从不可见变为可见时立即刷新。宿主端对聚合结果有约 2 秒内存快照缓存（常量 SNAPSHOT_TTL_MS，默认 2000）。挂件跟随页面实际深浅色（根据 body 背景亮度，而非仅 prefers-color-scheme）。
持久化的仅有 UI 状态¶
胶囊位置与面板开合记在浏览器 localStorage（键名 dsh-token-meter:pos、dsh-token-meter:open）。插件在宿主侧注册两个 HTTP 路由并注入一段脚本，不写入任何会话存储。
安装与启用¶
官方安装命令以 README 为准（包名注册为 dsh-token-meter）：
dsh plugin --profile <你的profile> add dsh-token-meter
package.json 中声明了 dsh.bundle，执行 dsh plugin add 后会把 bundle 自动追加进 profile 的 dsh.profile.bundles。README 说明：重启 GUI 后生效；桌面端挂件经 webserver/index-inject 注入，热加载后通常无需重启宿主。
本地源码可用 link 方式安装（路径改为你本机目录）：
dsh plugin --profile desktop add "link:D:\path\to\dsh-token-meter"
卸载：
dsh plugin --profile <你的profile> remove dsh-token-meter
验证接口¶
安装并启动 DSH 后，可用 curl 确认宿主是否在提供数据（<端口> 换成你当前 GUI/Web 服务端口）：
curl -s http://127.0.0.1:<端口>/dsh-token-meter/data.json | head -c 300
正常时应看到形如 {"ok":true,"total":…,"sessionCount":…,"sessions":[…]} 的 JSON。
数据流概括为：投影 JSON → 宿主 totalsOf() 四类求和 → /dsh-token-meter/data.json → 挂件 fetch 渲染。
配置与代码结构¶
无需用户配置。 常用常量写在 lib/index.js 顶部，例如：
| 常量 | 默认 | 说明 |
|---|---|---|
SESSIONS_DIR |
$DSH_HOME/storages/session_projcache/sessions |
投影缓存目录 |
ROUTE_BASE |
/dsh-token-meter |
路由前缀 |
SNAPSHOT_TTL_MS |
2000 |
快照缓存时间 |
MARGIN / GAP / PAD / PANEL_W |
18 / 8 / 8 / 300 |
挂件布局（assets/widget.js） |
仓库主要文件：lib/index.js（Cordis 宿主插件：扫描、聚合、路由、index 注入）、assets/widget.js（浏览器端 IIFE 挂件）、cordis.patch.yml（bundle patch）。
适用场景与注意¶
适合需要在 DSH 桌面或多工作区并行开发时，快速扫一眼全库累计 token、再下钻到单会话的开发者。数字完全依赖本地投影缓存：若投影未更新或某会话无 tokenUsage，界面上就不会反映该部分消耗。
插件以当前 dsh 进程权限 读取 $DSH_HOME 下的会话投影并对外提供 HTTP 路由。安装前建议在 GitHub 仓库 阅读源码与 MIT 许可证，确认与你的工作区安全策略一致。DSH 社区插件目录（如 SkillHub）由社区维护，与 DeepSeek / 幻方无官方从属关系；选型时以仓库 README 与 package.json 为准。
结尾¶
经过上面的步骤，你应在 GUI 右下角看到可拖动的 token 胶囊，并可从 /dsh-token-meter/data.json 核对聚合结果。dsh-token-bubble 的价值在于：用与 dsh-context 相近的累计口径，把「全部工作区、全部会话」的用量留在视野里，只读、无配置。更多信息见 目录页 与 GitHub。
