前言¶
在 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。
