前言¶
在 DSH（DeepSeek Harness）裏談不上用量統計：插件跑了多少 token、最近哪天用得最勤、幾種模型各自的佔比，都得自己翻會話日誌去翻。DSH 的理念是「一切皆插件」，這類缺口通常由社區插件來補。下面介紹 ailawu0409 維護的 dsh-usage-stats，它往 Settings 里加一個 Usage Statistics 分區，把本地會話的 token 彙總、活躍熱力圖、按模型的日趨勢和模型佔比一次給出。
需要先說明：這是社區插件，不是 DeepSeek 官方出品，未獲 DeepSeek 背書；插件的目錄頁分類爲 admin-security，GitHub 上星標數爲 0，倉庫創建於 2026-11-05。安裝前建議先讀源碼與許可證（MIT）。
這是什麼¶
dsh-usage-stats 是一個 DSH 插件，包版本 0.2.1，執行環境要求 Node.js 22 及以上，無第三方運行時依賴。它把統計結果渲染在 Settings → Usage Statistics（位於 Archived sessions 下方），數據全部來自本地會話日誌，只讀、不聯網、不上傳任何內容。
目標宿主版本爲 DeepSeek Harness 0.2.2-rc.1。導航圖標依賴 0.2.2 才引入的 settings.section.icon 插槽；更舊的宿主會直接回退到默認齒輪圖標，不會報錯。
核心功能¶
下面介紹的功能均可在 README 中核對。
-
概覽指標（3 項）：總 token、單日峯值 token、最長一次會話時長。
-
Token 活躍熱力圖：GitHub 風格的按周網格，支持 Daily / Weekly / Cumulative 三種配色模式；懸停單元格顯示日期、token 數與輪數，例如
Oct 27, 2026/506K tokens · 2 turns。單元格固定 11px，週數隨面板寬度自適應（最多 53 周、最少 13 周），彙總區間的表述會寫明實際範圍，例如 “Active 2 days over the last 8 months”。 -
每日 token 趨勢：平滑曲線按模型着色，可選 Last 7 days / Last 30 days；懸停出現豎向光標、高亮點以及當日的分模型明細。
-
模型用量：環形圖配一份佔比列表（前 5 個模型加 Other），懸停扇形顯示該模型的 token 與佔比。
-
其他：跟隨宿主淺色/深色主題與官方字體，界面爲中英雙語，右下角有 Refresh 按鈕；頁面頭部只保留標題（沿用宿主設置標題字號，16px）。刷新失敗時保留原有數據，只在頂部顯示一條可重試的橫幅。
數據口徑¶
這部分決定了數字爲什麼長這樣，值得先看清楚。
- 總 token：每個
assistant/message的usage之和，優先取totalTokens，沒有則用inputTokens + outputTokens。 - 峯值 token：單日用量的最大值，按本地時區的日曆天計算。
- 最長會話：單個會話內
turn/start → turn/end時長之和的最大值，跨夜的空閒時間不計入。 - 輪數：按
turn/start的開始日歸集，跨零點的輪次算在開頭那一天。 - 熱力圖彙總：只統計網格實際繪製的區間，不包含窗口外的歷史。
- 去重：fork 出的會話跳過繼承的前綴（
seq < inheritedEventCount），不與父會話重複計數。 - 刪除不減少歷史：會話歸檔、移出存儲或永久刪除後，已經計入的用量仍保留在總量、峯值、熱力圖與模型佔比裏，頁腳會標註 “N of the counted sessions are no longer listed”。這是有意設計，避免「刪掉一條數字就變小」的反直覺行爲。
- 失敗保留：讀取失敗或處於
migration-required的會話不會讓累計值回縮，沿用上一次結果；只有從未計數的會話被記爲 skipped。失敗會話冷卻 5 分鐘後才重試，不會每次掃描都重讀。 - 會話數上限：最多統計 20,000 個會話，超出時頁面會給出提示。
有一點要提醒：本插件的口徑與 ZCode 不同。ZCode 的 computedTotalTokens 是 input + cache + output，本插件優先取 usage.totalTokens，其次 input + output，因此兩者的數值可能不一致。另外 ZCode 默認保留 30 天原始用量明細，本插件保留終身總量，僅把「最近 400 天」的日粒度明細用於熱力圖和趨勢圖。
緩存與性能¶
-
每個會話的摺疊結果緩存在
<profile>/plugin-state/usage-stats-cache.json；已刪除會話的條目以retiredAt保留，所以刪會話後緩存不會立即膨脹，只會緩慢增長。 -
後續掃描按持久化的
revision增量進行，只有發生變化的會話會重讀；revision是 DSH 爲派生緩存提供的官方變更標記。 -
插件啓動 5 秒後預熱一次緩存，因此正常打開頁面時多爲緩存命中。
-
緩存遷移自動完成：v2 緩存原地升級到 v3，不需要全量重讀；只有更舊或未知版本的緩存會被丟棄重建。
-
想全部清零，刪除上面那個緩存文件再刷新即可，插件會從仍然存在的會話日誌裏重建。
安裝與啓用¶
官方給出的安裝命令如下：
dsh plugin --profile desktop add https://github.com/ailawu0409/dsh-usage-stats
也支持本地包路徑或自己的分支地址，把 URL 替換掉即可：
dsh plugin --profile desktop add <package-path-or-repo-url>
本地開發時可以把包目錄直接鏈接進 profile：
dsh plugin --profile desktop add /path/to/dsh-usage-stats
裝完重啓 DeepSeek Harness，進入 Settings → Usage Statistics。要使用插件自定義的導航圖標，建議 DSH 0.2.2-rc.1 或更新版本；舊宿主回退默認齒輪圖標。
典型用法¶
裝好後一般不用再動配置，日常使用就兩件事。
- 打開 Settings → Usage Statistics，看總 token、單日峯值和最長會話。
- 用右下角的 Refresh 按鈕手動刷新；失敗時頂部會出現可重試的橫幅，已有數據不受影響。
如果數字看起來有問題，先按下面的順序排查：確認緩存文件所在 profile 的路徑正確 → 看頁腳提示的 counted / no longer listed / skipped 會話數 → 刪除緩存文件後刷新重建。注意「會話數 counted 大於當前存儲的會話數」是正常現象，因爲它包含了仍留在賬上的已刪除會話。
想從零開始（比如換機器後不想帶上舊賬），刪除 <profile>/plugin-state/usage-stats-cache.json 再刷新，插件只從仍然存在的會話日誌重建。
適用場景與注意¶
適合想回頭看自己 token 開銷分佈、區分不同模型用量的本地 DSH 使用者，尤其是用多模型跑長鏈路、需要判斷哪個模型佔大頭的場景。
幾點需要留意：
- 插件以當前 DSH 進程的權限運行，安裝前應自行檢查源碼與許可證（MIT），不要把它當作官方組件。
- 這是非官方插件，DSH 擴展 API 在不同版本間可能變化，升級宿主後需要重新驗證。
- 刪除會話不會讓歷史總量下降，如果需要真正的「當前狀態」視圖，這個插件給的不是。
- 統計上限 20,000 個會話；窄的面板上熱力圖減少週數而非縮放單元格，窄面板看不全一年。
- 「Last 7 days」趨勢實際繪製 8 個點（今天加此前 7 天），與參考設計一致。
- DSH 0.2.2 新增了德語、西班牙語、法語、日語、葡萄牙語、俄語界面；本插件文案仍爲中英雙語，其他語言回退到英文。
目錄頁與源碼¶
目錄頁：https://www.skillhub.cn/plugins/ailawu0409/dsh-usage-stats
源碼：https://github.com/ailawu0409/dsh-usage-stats
需要說明的是，目錄頁是獨立社區站點，與 DeepSeek / 幻方沒有官方從屬關係，不是官方應用商店。
