前言¶
DSH 的理念是「一切皆插件」，Web 界面的能力可以由插件按需補充。但對 dsh web 的日常使用者來說，token 用量數據散落在各個會話的事件日誌裏，想回答「今天用了多少」「這個月累計用了多少」，並沒有現成的入口。
下面介紹 @kidli1412/dsh-token-heatmap，一個 DSH Web GUI 插件：它在新會話屏幕的輸入框下方渲染一張 GitHub 風格的每日 token 用量熱力圖，同一行給出今日 / 本月 / 累計三項統計，裝完即用。
這是什麼¶
一句話定位：在新會話屏幕輸入框下方顯示當前自然年（可選年份）的每日 token 用量熱力圖與用量統計。
插件由 KIDLi1412 維護，許可證爲 MIT，當前版本 0.1.5。運行於 @deepseek-ai/dsh >= 0.1.2-alpha.4（0.1.2 版本線）。它解決的問題是：把會話日誌裏的 token 用量樣本按天聚合，變成一張一眼能讀懂的熱力圖。
核心功能¶
熱力圖卡片¶
安裝後，新會話（hero）屏幕的輸入框正下方出現統計卡。注意它只在新會話屏幕顯示，已對話的會話不顯示。
- 自然年視圖：覆蓋所選年份 1 月–12 月，通過『‹ 年份 ›』選擇器切換年份，最多到當前年。
- 佈局對齊 GitHub：列爲周（週一起），行爲星期，左側標註一~日全部 7 天；今日之後的日期顯示爲空格。
配色與分檔¶
- 六套配色：綠色 / 藍色 / 橙色 / 紅色 / 紫色 / 青色，在 設置 → 插件 → 插件配置 中切換，六個色板按鈕即時預覽。
- 顏色按絕對閾值分檔：0 / <1M / 1M–10M / 10M–100M / ≥100M 共 5 級。圖例懸停顯示各檔範圍，格子懸停顯示日期與精確 token 數。
統計行與刷新¶
- 統計行與標題同一行，顯示今日 / 本月 / 累計，懸停顯示完整數值。
- 每 5 分鐘自動刷新，窗口重新可見時也會刷新，行尾可手動刷新。
配置項¶
插件配置卡（設置 → 插件 → 插件配置）提供『顯示熱力圖』開關與配色方案選擇，修改後可保存或放棄。配置經 token-heatmap settings namespace 持久化到 <DSH_HOME>/settings.yaml；0.1.1 及更早版本的舊配置文件在啓動時自動遷移。
數據是怎麼來的¶
服務端增量摺疊全部會話事件日誌中的 token 用量樣本，按天、按模型聚合，緩存到 <DSH_HOME>/storages/token-heatmap-cache.json，並通過迴環受限端點 GET /api/token-heatmap/usage 提供。數據端點僅迴環地址可訪問，憑據不外發；插件只讀，不修改任何會話數據。
聚合與迴環端點的實現參考了 dsh-usage-stats（MIT © Ychris12138）。
安裝與啓用¶
前置條件：需要 web profile 與 pnpm。
1、從 npm 安裝：
dsh plugin --profile web add @kidli1412/dsh-token-heatmap
也可以從 GitHub 安裝：
dsh plugin --profile web add github:KIDLi1412/dsh-token-heatmap
本地開發用本地鏈接：
dsh plugin --profile web add "link:path/to/dsh-token-heatmap"
2、安裝完成後重啓正在運行的 dsh web，並在瀏覽器中硬刷新（Ctrl+Shift+R）。之所以要重啓，是因爲服務端與客戶端都隨 dsh web 啓動加載。
3、側邊欄沒有新增入口。打開新會話，統計卡直接出現在輸入框下方。
卸載：
dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
兼容性¶
- DSH：manifest 將 0.1.2-alpha.4 / 0.1.2-alpha.5 / 0.1.2-rc.1 逐項聲明爲 compatible；宿主要求
engines.dsh: ^0.1.2-rc.1。 - Node：
^22.19.0 || >=24.0.0。
適用場景與注意¶
適合日常使用 dsh web、想直觀掌握每日 token 用量的用戶：裝完不改變任何交互流程，打開新會話就能看到用量分佈。
使用前注意：
1、插件以當前 dsh 進程權限運行，安裝前建議檢查源碼與許可證。
2、無會話或無工作區時統計卡不渲染（input.dock 需要會話上下文）。
3、修改配置後在設置頁保存或放棄；配置持久化在 <DSH_HOME>/settings.yaml。
4、新增或更新插件後需要重啓 dsh web。
結尾¶
dsh-token-heatmap 把散落在會話日誌裏的 token 用量聚合成了熟悉的 GitHub 熱力圖視圖，配合今日 / 本月 / 累計統計和可切換配色，屬於裝完就能長期掛着的 Web 插件。
- 社區目錄頁：https://www.skillhub.cn/plugins/KIDLi1412/dsh-token-heatmap
- GitHub 倉庫：https://github.com/KIDLi1412/dsh-token-heatmap
社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek、幻方無官方從屬關係。
