前言¶

用 DSH 跑智能體，會話日誌都落在 $DSH_HOME/sessions 下面，token 消耗散在一條條會話裏。想回答「這個月每天用了多少 token」「哪個模型用得最多」，就得自己解壓 zstd 壓縮的 JSONL、逐條折算，寫一次腳本不難，但每次看都要重跑。

@kelearns/dsh-token-usage 把這件事搬進了 GUI：一塊 GitHub 風格的貢獻圖，展示每日、每週、累計的 token 消耗。DSH 的理念是「一切皆插件」，這個插件就是通過官方插件機制掛載的，不需要改 dsh 源碼。下面介紹它的功能、安裝方式和數據口徑。

這是什麼¶

@kelearns/dsh-token-usage 是 DeepSeek Harness（dsh）web GUI 的 Token 用量熱力圖插件，由 KeLearns 維護，當前版本 0.1.1，MIT 許可證。安裝後，dsh 設置側欄會出現 Token Activity 入口，點開就是熱力圖。

它解決的問題是：不寫腳本、不動源碼，直接在 dsh 界面裏看到 token 消耗的趨勢和構成。

核心功能¶

• 彙總氣泡（Summary bubble）：單個圓角容器裏放 5 項統計——總量、峯值日、最長會話、當前連續、最長連續，豎線分隔；
• 三種視圖：Daily（按日顏色等級）、Weekly（按周堆疊單元格）、Cumulative（按周累計堆疊，最新一列恆滿）；
• 時間窗切換：最近 3 / 6 / 12 個月，默認 12；12 個月視圖橫向滾動，自動滾到最新一週；
• 懸停詳情：懸停單元格顯示當日總量、當週總量或截至當日的周累計，zh / en 本地化；
• 活動洞察：最常用模型 / 推理強度 / 工具、峯值小時、日均與月均、最活躍工作日與最活躍一天；
• i18n：zh / en，即時跟隨文檔語言；
• 主題：淺色 / 深色調色板，跟隨 dsh 應用主題；
• 自動刷新：每 60 秒及窗口聚焦時重新掃描變更的會話文件；
• 跨平臺：宿主側只用 Node 標準庫（fs / path / os / zlib），支持 Windows / macOS / Linux。

安裝與啓用¶

前提是 PATH 裏有 pnpm：

npm install -g pnpm

從 npm 安裝（推薦）：

dsh plugin --profile web add @kelearns/dsh-token-usage

安裝器會讀取 cordis.patch.yml（dsh.bundle.patch 清單字段），自動應用插件行，不用手動改補丁文件。安裝完成後重啓 dsh web 生效。

本地開發時，在插件倉庫根目錄運行，link:. 會解析爲當前目錄：

dsh plugin --profile web add link:.

卸載：

dsh plugin --profile web remove @kelearns/dsh-token-usage

不走 CLI 也可以手動安裝，分三步：

1、把包放進 $DSH_HOME/profiles/web/node_modules/@kelearns/dsh-token-usage；

2、向 $DSH_HOME/cordis.patch.yml 追加下面的 insert 塊（可重複執行）：

- insert:
    - id: dsh-token-usage
      name: '@kelearns/dsh-token-usage'

3、重啓 dsh web。

這個插件收錄於 awesome-dsh-plugin 精選註冊表，也可以在 dsh 設置的 Plugin Market 標籤頁裏用 token-usage 搜索安裝。

數據來源與統計口徑¶

插件讀取 dsh 官方會話日誌：$DSH_HOME/sessions/<workspace>/<session-id>/session.jsonl.zstd，即拼接 zstd 幀的 JSONL。token 用量從 assistant/chunk 事件中 chunk.type === "usage" 的記錄折算，總量 = input + output + cacheRead。活動洞察還會讀取 request/header（模型 / 推理強度）和 tool/call（工具）事件。

幾點口徑需要先知道：

1、只統計攜帶 usage 事件的會話（dsh 會話日誌格式，已在 0.1.0-rc.6 上驗證）；
2、日期按進程本地時區歸屬，一週從週一開始；
3、zstd 解壓需要 Node >= 22.2（包的 engines 爲 ^22.19.0 || >=24.0.0，官方 dsh 運行時滿足）；
4、缺失或不可讀的會話目錄返回空統計，不影響 GUI。

配置與 HTTP 接口¶

配置只有一項 refreshIntervalMinutes，控制後臺重掃間隔（分鐘），默認 5。在 cordis.patch.yml 的 insert 塊里加 config 即可：

- insert:
    - id: dsh-token-usage
      name: '@kelearns/dsh-token-usage'
      config:
        refreshIntervalMinutes: 5   # 後臺重掃間隔，默認 5

插件註冊了三個同源 HTTP 路由：

測試¶

倉庫自帶三個測試腳本，分別覆蓋不同層面：

node test/mock.test.mjs                            # 合成數據的完整流水線
node test/mock.test.mjs "$env:USERPROFILE\.dsh"    # 真實數據冒煙（任意 DSH_HOME）
node test/layout-algo.mjs                          # 佈局算法矩陣

第二條可以指向任意 DSH_HOME，用自己的會話數據做冒煙驗證。

適用場景與注意事項¶

適合已經在用 dsh web GUI、想直接在界面裏看 token 消耗趨勢和構成的人。如果每天開着 dsh 跑會話，這塊熱力圖能回答「今天用了多少、最近幾周趨勢如何、哪個模型用得最多」這類問題。

安裝前有兩點務必注意：

1、插件以當前 dsh 進程的權限運行，裝之前建議先過一遍源碼和許可證（MIT），確認自己接受；
2、會話日誌格式在 0.1.0-rc.6 上驗證過，如果你的 dsh 版本差異較大，先跑一遍上面的測試腳本確認解析正常。

小結¶

@kelearns/dsh-token-usage 把散落在會話日誌裏的 token 數據搬進了 dsh 界面：一條安裝命令，重啓後就能看到每日 / 每週 / 累計的消耗熱力圖和活動洞察，不用自己維護解析腳本。經過上面的步驟裝好重啓，設置側欄裏的 Token Activity 就是入口。

項目地址與收錄頁：

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

社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。