前言¶

用 DeepSeek Harness（DSH）做智能體或長會話開發時，Token 會分散在多次請求和多個會話裏。要看「今天用了多少、哪幾天特別費、某次會話佔了多少」，常見做法是翻服務商後臺或自己寫腳本掃 $DSH_HOME/sessions/ 下的日誌。前者要切出 DSH，後者維護成本高。

dsh-token-usage-panel 是社區維護的客戶端插件（作者 Jun-Jun-Gao，MIT 許可證），在 DSH 設置裏增加 Token 用量 一頁：每日熱力圖、近 30 天趨勢、按會話明細，以及可選的成本估算。數據只讀本機會話日誌，不聯網上傳。

這是什麼¶

插件全名 dsh-token-usage-panel，分類爲客戶端：Host 側掃描並聚合會話用量，瀏覽器側在設置面板裏渲染 UI。維護倉庫：Jun-Jun-Gao/dsh-token-usage-panel；社區目錄頁：skillhub 條目（獨立站點，與 DeepSeek / 幻方無官方從屬關係）。

核心功能¶

下面介紹面板裏已文檔化的能力，均可在安裝後於 設置 → Token 用量 中直接使用。

今日消耗：顯示當天總量，並按「輸出 / 未緩存輸入 / 緩存命中」分色；若在成本估算裏填寫單價，還會顯示當天估算金額。

指標網格：近 7 天、近 30 天、累計、活躍天數、連續使用天數、緩存命中率。

每日消耗熱力圖：最近 53 周，樣式類似 GitHub 貢獻圖；顏色越深表示當天消耗越多。懸停可看當天四類 token 明細；點擊格子可展開當天各會話佔比。

最近 30 天趨勢：輸出、未緩存輸入、緩存命中的堆疊柱狀圖，帶網格線與峯值刻度。

會話明細：支持排序與搜索；窄面板自動精簡列，寬麪板額外顯示工作區、緩存命中和 30 天迷你條。

彙總維度：按模型、按工作區彙總。

成本估算：填寫單價（元 / 百萬 token）後自動換算金額；價格僅保存在本機瀏覽器（localStorage），留空則不顯示金額。

界面使用 DSH 設計變量（--dsw-alias-*），淺色 / 深色主題自動適配；面板寬度隨設置頁變化，文檔稱約 590px 寬仍可完整顯示 53 周熱力圖。

統計口徑¶

插件從 DSH 會話日誌裏每條 assistant/message 的 usage 字段彙總。文檔對字段含義說明如下：

因多輪對話會重發上下文，「合計」往往被緩存命中主導；面板單獨列出「未緩存輸入 + 輸出」，便於看真正影響計費的部分。

熱力圖按本機時區自然日歸檔；顏色分 4 檔，按「當天消耗 / 歷史單日最大值」劃分。

安裝與啓用¶

需要已安裝 DeepSeek Harness（Web 或桌面版），且能正常使用 dsh 命令。安裝完成後 bundle 會自動啓用；若面板未出現，刷新頁面一次。

方式 A：DSH 插件頁（推薦）¶

1. 打開 DSH 側邊欄 插件（Plugins） → 安裝。
2. 填入：

github:Jun-Jun-Gao/dsh-token-usage-panel

方式 B：命令行¶

# 1) 安裝到你的 profile（desktop 爲例；Web 版通常是 web）
dsh plugin --profile desktop add github:Jun-Jun-Gao/dsh-token-usage-panel

# 2) 把它選爲 profile 的一層（bundle）
#    編輯 $DSH_HOME/profiles/desktop/package.json，在 dsh.profile.bundles 里加上：
#      "dsh-token-usage-panel"

第 2 步等價於在「插件」頁勾選該 bundle；改完後 DSH 可熱重載，或重啓應用生效。

文檔另提供方式 C（本地 link 與 cordis.patch.yml），適合開發調試；日常安裝用 A 或 B 即可。

典型用法¶

1. 打開 DSH 設置，左側選 Token 用量。
2. 查看今日消耗與指標網格；用熱力圖找高消耗日期，點格子看當天會話分佈。
3. 在「最近 30 天趨勢」和「會話明細」裏按模型、工作區或關鍵詞排查。
4. 需要金額時，在成本估算中填寫四類單價（元 / 百萬 token）；不需要則留空。點「清空」會清除本機保存的價格。
5. 面板默認每 30 秒自動刷新，也可手動點「刷新」；進行中的會話會計入統計。

Host 提供只讀接口，開發時可自檢（將 <dsh-web-port> 換成本機端口）：

curl -s http://127.0.0.1:<dsh-web-port>/token-usage/health
curl -s http://127.0.0.1:<dsh-web-port>/token-usage/data | head -c 300

工作原理（簡述）¶

Host 側 lib/index.js 掃描 $DSH_HOME/sessions/**/session*.jsonl.zstd，聚合到「每天 / 每會話」，並註冊只讀路由 GET /token-usage/data。日誌爲多幀 zstd，Host 按魔數切幀逐幀解壓，不依賴外部 zstd 命令；解析結果按文件大小與 mtime 做增量緩存。客戶端 lib/client.js 註冊 settings.section，拉取數據並渲染；成本估算寫 localStorage。插件不註冊模型可見能力，模型看不到該面板。

適用場景與注意¶

適合：長期在 DSH 裏跑會話、希望在本機統一看用量趨勢、會話佔比和粗略成本，且不想把日誌導出到第三方。

兼容性：開發與驗證環境爲 DSH 0.2.0-rc.2（Electron 44 / Node 24.18）下的 Web GUI 與桌面版。包未聲明 @deepseek-ai/dsh* 的 peerDependencies，較新版本若異常可在 GitHub 開 issue 並附上 DSH 版本。擴展點包括 settings.section、ctx.locale、ctx.webServer.register。

安全與權限：插件以當前 DSH 進程權限讀取本機會話目錄；安裝前建議瀏覽 倉庫源碼 與 MIT 許可證。社區插件非官方發行，目錄頁 skillhub 爲獨立生態站點。

卸載：

dsh plugin --profile desktop remove dsh-token-usage-panel
# 並在 profile 的 package.json 裏把 "dsh-token-usage-panel" 從 dsh.profile.bundles 移掉

結尾¶

dsh-token-usage-panel 把 Token 統計收進 DSH 設置：熱力圖、趨勢、會話明細與可選成本估算，數據不出本機。安裝標識爲 github:Jun-Jun-Gao/dsh-token-usage-panel。

• 社區目錄：https://www.skillhub.cn/plugins/Jun-Jun-Gao/dsh-token-usage-panel
• GitHub：https://github.com/Jun-Jun-Gao/dsh-token-usage-panel