前言¶

用 DeepSeek Harness（以下簡稱 DSH）跑一段時間後，常想知道兩件事：這個月 token 燒在哪些會話上、哪個模型佔了大頭。宿主自帶的界面給出的是單次請求的用量，不提供按會話、按模型、按天的聚合。自己翻日誌寫腳本能算出來，但要長期跟蹤就得反覆重來。

dsh-token-dog 解決的是「聚合這一步」。它不新記賬本，直接讀已經落盤的 Session 日誌，裝上去就能看到歷史用量，無需從安裝當天開始重新統計。下面介紹這個插件的定位、功能、安裝方式和數據口徑。

這是什麼¶

dsh-token-dog（中文名 Token 小狗）是一個 DSH 客戶端插件，維護者是 ccodeJava，分類爲客戶端。它在 DSH Web GUI 里加一個「Token 用量」面板：按會話和按模型統計 token 消耗，用每日堆疊矩形圖展示近段時間的構成，用全年日曆熱力圖展示活躍程度。插件只做展示，不改寫宿主的任何狀態。

配套的目錄頁在 skillhub.cn 上，倉庫地址見文末。

核心功能¶

概覽頁¶

頁面分五個區塊：

• 統計卡：總 Token、緩存命中率、輸出 Token、調用次數；副行顯示會話數、緩存與輸入拆分、輸出佔比、日均調用。
• 每日消耗：每天一根柱子，柱內按會話分段，單日最多 6 段，其餘合併爲「其他」；懸停看當天總量、調用次數和前 4 個會話的明細。
• 模型用量：每個模型的總量、調用次數、涉及會話數，行內帶佔比條。行可點擊，進入該模型的詳情頁。
• 會話排行：消耗最多的 8 個會話，含調用次數與最後使用日。
• 活躍日曆：近 52 周，週一開頭的格子，5 檔深淺；懸停看當天總 Token、調用次數、會話數，以及當天所有模型各自的用量與佔比。

模型詳情¶

點模型行進入詳情頁，頂部變爲「返回」加模型名，內容替換爲該模型的統計卡、每日矩形圖，以及完整的消耗過該模型的會話列表（不截斷）。頂部的區間切換對詳情頁同樣生效。

區間與外觀¶

• 區間切換：近 7 天 / 近 30 天 / 近 90 天 / 全部，作用於統計卡、矩形圖、排行與模型詳情。
• 主題：8 個低飽和預設色（霧藍、青、苔綠、麥、陶土、藕紫、豆沙、中性），外加自定義取色器；「淡 / 中 / 濃」三檔控制同一套色的濃度，只作用於柱子與熱度。配色記在 localStorage。
• 中英雙語：文案跟隨宿主語言，缺字典時回退中文。
• 側欄圖標開關：頁面右上角可關掉左側欄的小狗圖標，關閉後仍可從 設置 → Token 用量 進入。

安裝與啓用¶

插件沒有發佈到 npm，也不經過構建，安裝的是倉庫目錄本身。前提是宿主已安裝 DSH（Desktop 版或 dsh web），版本 0.2.x。

第 0 步：拿到目錄¶

git clone https://github.com/ccoderJava/dsh-token-dog.git

沒有 git 也可以在倉庫頁面點 Code → Download ZIP 解壓。

方式一：讓 DSH 裏的 Agent 裝¶

在 DSH 裏隨便開一個會話，把下面這句話發給 Agent，路徑換成 clone 下來的實際路徑：

把 /Users/you/plugins/dsh-token-dog 這個目錄裝成插件

Agent 會調用內置的 plugin_manager 完成安裝：把 dsh-token-dog 寫進當前 profile 的 package.json（以 link: 方式指向該目錄），並加入 dsh.profile.bundles。返回裏的 application 爲 applied 就表示已生效。

方式二：命令行¶

裝了 dsh CLI 的環境裏（Desktop 版通常沒有 CLI，用方式一即可）：

dsh plugin --profile desktop add link:/absolute/path/to/dsh-token-dog

desktop 是 profile 名，默認爲 desktop；CLI 用戶可能是 default。

安裝後¶

刷新頁面（Cmd/Ctrl + R）。入口兩個：左側欄最底部的小狗圖標（整頁打開），或 設置（齒輪）→ 左側導航最後一項「Token 用量」。第一次打開會掃一遍歷史會話，之後結果緩存 60 秒。

確認安裝成功：

• 設置 → 插件 → 已安裝裏能看到 Token 小狗（包名 dsh-token-dog），帶小狗圖標；
• 左側欄出現小狗圖標；
• 想從命令行確認數據鏈路：

curl -s "http://127.0.0.1:<GUI 端口>/token-dog/usage?tz=Asia/Shanghai" | head -c 300

更新與卸載¶

方式一裝的是軟鏈，改完或拉完代碼刷新頁面就生效，不需要重裝：

cd dsh-token-dog && git pull

卸載時對 DSH 說「把 dsh-token-dog 插件卸了」（走 plugin_manager 的 remove_bundle），或命令行執行：

dsh plugin --profile desktop remove dsh-token-dog

典型用法¶

看某天爲什麼突然漲了¶

打開概覽頁，在每日消耗圖上懸停對應的某一天，看當天的總量、調用次數和前 4 個會話的明細。如果想進一步知道當天各個模型各自佔了多少，切到活躍日曆懸停同一天即可。

按模型下鑽¶

在模型用量區塊點某一行，進入該模型的詳情頁，看它自己的每日曲線和全部消耗過它的會話。回到概覽用頂部的「返回」。

收縮時間範圍¶

頂部區間切換放在統計卡、矩形圖、排行和模型詳情上都會生效。看短期波動用近 7 天或近 30 天，看長期趨勢用近 90 天或全部。

調整配色¶

右上角一排色點選預設色，最後一個圓點進入自定義取色器；旁邊的「淡 / 中 / 濃」調濃度。配色會持久化，刷新後保持。

數據口徑¶

插件不另建賬本，數據只來自 Session 日誌（ctx.sessionQuery）。它回放日誌裏的幾類事件來拼出每次調用的用量：

幾個關鍵口徑：

• 單次調用按 turn:step:attempt 去重，同一 attempt 後來的採樣覆蓋先前的。
• 總 Token = input + cacheRead + cacheWrite + output，四個桶互不重疊。
• 緩存命中率 = cacheRead / (cacheRead + input)。
• 不計入：不在任何 Session 日誌裏的調用，例如標題生成、壓縮等後臺調用。這是「日誌即唯一事實來源」的取捨。

Host 側註冊了一條只讀路由，僅本機迴環可訪問：

GET /token-dog/usage?tz=Asia/Shanghai[&refresh=1]

返回體把結果聚合成 day / session / provider / model 維度的行，示例：

{
  "ok": true,
  "generatedAt": 1793860698515,
  "scanMs": 672,
  "timeZone": "Asia/Shanghai",
  "rows": [
    { "day": "2026-11-04", "session": "session-…", "provider": "deepseek-account",
      "model": "deepseek-flash", "input": 344317, "cacheRead": 8053120,
      "cacheWrite": 0, "output": 141471, "calls": 138 }
  ],
  "sessions": { "session-…": { "title": "…", "createdAt": 1793, "cwd": "…", "origin": "", "parent": "" } },
  "scanned": 26, "skipped": 0, "failures": 0, "failureSample": []
}

全量掃描結果緩存 60 秒，refresh=1 立即重掃；掃描期間複用同一次掃描，不疊併發。請求帶轉發頭（X-Forwarded-For / CF-Connecting-IP）、跨站來源或非迴環地址時返回 403。數據不過網，瀏覽器只請求本機 127.0.0.1。

適用場景與注意¶

適合已經在用 DSH、並且想搞清楚 token 花在哪些會話和模型上的人。它的價值在於「裝上即可看歷史」：因爲讀的是已有日誌，安裝之前的對話同樣計入，不需要切換到新的記賬方式。

幾點需要注意：

• 插件以當前 dsh 進程的權限運行。Host 側路由註冊在宿主進程裏，安裝前應閱讀源碼（index.js、client.js、cordis.patch.yml）並確認許可證（MIT）。
• 只統計寫進 Session 日誌的調用。標題生成、壓縮這類後臺調用不計入，所以和賬單數字對不上是正常現象，插件也不做價格換算。
• 掃描窗口是最近 400 天內創建或當前在線的會話，上限 600 個，超出時頁面會提示。
• 每日矩形圖超過 120 天只畫最近 120 天；柱子只畫當天有用量的日子，無用量的一天不佔位。
• 日曆熱度按當天 token 的分位數分級，跨主題、跨區間會重新計算，因此兩個區間之間的深淺不可直接比較。
• 插件依賴宿主的 settings.section / main / sidebar.panellist 席位與 sessionQuery 服務，DSH 大版本升級後需重新驗收席位行爲。README 標註的驗證環境是 DSH 0.2.1-rc.5（Desktop, macOS）。

結尾¶

dsh-token-dog 做得比較剋制：不新造數據源，不引外部依賴，只在宿主本地把已有的日誌整理成可下鑽的視圖，數據鏈路也是封閉在迴環接口上的。對於 DSH 0.2.x 用戶來說，它是現有 Web GUI 的一個補充，裝一個目錄就能用。

目錄頁：https://www.skillhub.cn/plugins/ccoderJava/dsh-token-dog
倉庫：https://github.com/ccoderJava/dsh-token-dog