前言¶
長期用 DeepSeek Harness（DSH）跑對話時，Token 會分散在多份 session*.jsonl 裏，界面本身未必給出「按天、按模型」的長期視圖。若你想在本地 GUI 裏看到一段時間內的用量趨勢，而不把日誌上傳到外部服務，需要依賴 Host 側從磁盤日誌做彙總、再只供本機 loopback 訪問的插件。
下面介紹維護者 savasana168 的 dsh-token-usage-heatmap（分類：模型推理）。它在 DSH 網頁界面中增加 Token 總用量面板：26 周熱力圖、按模型柱狀圖，以及會話標題欄左側的緊湊芯片；數據全部由本機 Host 從已有會話日誌摺疊計算，不向機器外發送。
這是什麼¶
dsh-token-usage-heatmap 是面向 DSH Web GUI 的 bundle 插件（dsh.bundle + cordis.patch.yml），當前包版本爲 0.2.1，許可證 MIT，要求 Node ≥ 22.15.0（或運行時 node:zlib 提供 zstdDecompressSync）。它不引入構建步驟和 npm 依賴，發佈物爲純 JavaScript。
插件解決的問題：把 $DSH_HOME/sessions 下已有的明文 session*.jsonl 與多幀 session*.jsonl.zstd 讀入，按日、按小時、按模型分桶，合併爲 roll-up 後通過僅 loopback 可訪問的 HTTP 路由提供給前端，用於熱力圖、柱狀圖和標題欄芯片展示。
核心功能¶
總覽（Overview）頁¶
- 26 週日歷熱力圖：每天一格，四檔藍色深淺按當前範圍內最忙的一天縮放；網格固定 26 列，僅在週日推進，避免隨日期滾動而錯位。
- 選定範圍內的六個指標：總 Token、消息數、會話數、活躍天數、峯值小時、最常用模型。
- 與書籍 Token 量的對照文案：用知名書籍的 Token 數作參照，說明當前總用量相當於多少「本」。
模型（Models）頁¶
- 按日堆疊柱狀圖，以及帶會話數的 per-model 排名。
- 縱軸固定三檔刻度（0、一半、峯值），峯值向上取整，柱形不會超出頂刻度。
時間範圍¶
範圍選項爲 全部 / 30 天 / 7 天。「全部」指磁盤上所有有記錄的天，不等於熱力圖繪製的 26 周窗口。柱狀圖在「全部」與「30 天」下使用 30 天窗口，「7 天」下使用 7 天窗口。
標題欄芯片與浮動面板¶
- Header chip：顯示緊湊的 Token 總量，位於會話標題左側；每分鐘輪詢一次，窗口聚焦時刷新，冷啓動時會短暫重試，避免一直停在頁面初次加載的值。
- 點擊打開面板：芯片即入口；點擊後在下方以浮動卡片展示完整面板。再次點擊芯片、點面板 ×、點外部或按 Escape 可關閉。卡片經 React portal 掛在
document.body，不受 composer 的 flex 擠壓；窗口較矮時僅卡片主體滾動。打開狀態會在會話之間記住。
主題¶
淺色與深色各有一套不透明色階；深色不是淺色加透明度，避免在深色卡片上讀成黑塊。
設置項¶
在 Settings → General 下增加三個開關（存於 Host 配置，對本配置檔的所有窗口生效）：
| 開關 | 作用 |
|---|---|
| Show the usage chip in the header | 隱藏標題欄芯片（同時去掉面板唯一入口） |
| Open the panel from the chip on a new session | 關閉時，新會話頁的芯片仍顯示總量但不打開面板 |
| Open the panel from the chip inside a conversation | 關閉時，對話內芯片仍顯示總量但不打開面板 |
安裝與啓用¶
DSH 桌面版由應用管理 profile，建議在應用內安裝，不必用命令行。
應用內：Settings → Plugins，安裝插件名 dsh-token-usage-heatmap。
從 GitHub 安裝到指定 profile：
dsh plugin --profile <name> add github:savasana168/dsh-token-usage-heatmap
在未發佈前從本地目錄安裝：
dsh plugin --profile <name> add "file:$PWD"
安裝後需 重啓 Host，新加載的 JavaScript bundle 纔會生效。
插件以當前 DSH Host 進程權限讀取會話目錄與寫緩存；安裝前應自行查看倉庫源碼與 MIT 許可證，確認符合你的環境策略。
典型用法¶
- 安裝並重啓 Host 後打開 DSH Web GUI。
- 在會話標題欄左側查看 Token 總量芯片；需要詳情時點擊芯片打開浮動面板。
- 在面板內切換 Overview / Models，並用 全部 / 30 天 / 7 天 切換統計範圍。
- 若只想保留數字、不想誤觸打開面板，到 Settings → General 關閉對應「從新會話/對話內芯片打開面板」開關；若完全不需要入口，可關閉「Show the usage chip in the header」。
數據不會離開本機：彙總由 Host 從本地 session 日誌計算，路由 /token-usage-heatmap/usage 要求 loopback 的 Host、拒絕 sec-fetch-site: cross-site，且 Origin 須與 Host 一致，外部網頁無法讀取完整 Token 歷史。
工作原理（簡要）¶
lib/fold.js：讀取$DSH_HOME/sessions下的日誌並摺疊到按日、按小時、按模型桶。lib/usage.js：合併會話並緩存到$DSH_HOME/cache/token-usage-heatmap/usage.<pid>.json，熱啓動避免重讀全部日誌。lib/index.js：註冊精確路由/token-usage-heatmap/usage，返回 JSON。lib/client.js：在conversation.header.leading渲染芯片與面板，在settings.general.item註冊上述開關；面板使用 popper + portal 到document.body。
若 Node 版本低於 22.15 且不支持 zstdDecompressSync，插件仍可加載並提供路由，但會跳過 .jsonl.zstd，僅統計明文 .jsonl。
適用場景與注意¶
適合：經常在 DSH Web 界面裏工作、希望用本地日誌觀察 Token 習慣（按天熱力、按模型分佈、峯值時段）的開發者；強調隱私、不希望用量統計依賴第三方雲端時也可使用。
注意：
- 需要能提供 Web GUI 且向插件暴露
webServer的 DSH Host。 - 統計範圍受磁盤上實際保留的 session 文件限制；壓縮日誌依賴較新的 Node/runtime。
- 社區目錄 SkillHub 插件頁 與 GitHub 倉庫由社區維護，與 DeepSeek / 幻方無官方從屬關係；DSH 生態一貫是「一切皆插件」，本插件是其中一類模型用量可視化擴展。
結尾¶
dsh-token-usage-heatmap 把已有會話日誌收成面板裏的 26 周熱力圖、模型柱狀圖和標題欄芯片，全程本地計算、loopback 服務。查閱說明與 issue 見倉庫 GitHub：savasana168/dsh-token-usage-heatmap；目錄索引見 SkillHub。
