前言¶
在 DeepSeek Harness（DSH）裏跑多模型、多會話時，宿主本身沒有現成的「按模型、按天」Token 臺賬。若只靠肉眼翻會話日誌，很難回答「這週哪個模型喫掉了多少 Token」「有沒有連續高消耗日」這類問題。社區插件 @zhangyongshuai56-hub/dsh-token-usage（倉庫 zhangyongshuai56-hub/dsh-token-usage）從本地會話文件聚合用量，在設置裏提供趨勢圖與日曆熱力圖，把統計留在本機完成。
這是什麼¶
維護者爲 zhangyongshuai56-hub，分類屬於模型推理。插件一句話定位：統計 DSH 每天消耗的 Tokens，按模型分系列展示趨勢與日曆熱力圖。npm 包名爲 @zhangyongshuai56-hub/dsh-token-usage（因 dsh-token-usage 已被他人佔用而加了 scope）。當前 package.json 版本爲 0.1.0，許可證 MIT；要求 DSH >=0.2.0-rc.1、Node >=22.19.0。
數據從哪來¶
DSH 在每條模型響應裏，會把用量寫入會話文件的 assistant/message 事件，例如：
{"type":"assistant/message","time":1791555004268,
"data":{"usage":{"inputTokens":7636,"outputTokens":505,
"cacheReadTokens":0,"cacheWriteTokens":0,"totalTokens":8141}}}
模型歸屬來自同一會話的 request/header（config.provider / config.model），日期按本地時區歸日。宿主側掃描路徑爲 ~/.dsh/sessions/**/session.v4.jsonl.zstd：文件爲 zstd 多幀，每幀獨立解壓後拼接，再聚合出「天 × 模型」用量表。README 註明一次全量掃描約 0.7 秒（40 個會話文件 / 38 MB），因此不能壓在用戶點開面板的那一次請求上。
加載與性能¶
面板需要「點開即出數」，插件在服務端採用 stale-while-revalidate 與增量掃描兩層策略。
先做後臺預熱：插件裝載時預熱快照，用戶第一次打開設置裏的面板時通常已有數據。快照 TTL 爲 30 秒；過期時接口先返回舊數據，同時在後臺重掃，響應頭 x-token-usage-stale: 1 表示當前是舊快照。後臺掃描異步進行，每處理幾個文件就讓出事件循環，避免卡住宿主。
會話文件追加寫入，歷史聚合結果不變。插件按文件記錄「消費到第幾個字節 + 截至該處的聚合」，再次掃描只解壓新增幀。README 給出的對比（全量 vs 增量）如下：冷掃描約 735 ms；穩態文件未變時增量約 1–2 ms；當前會話又寫幾條時增量約 3 ms。掃描前用正則挑出 assistant/message、request/header、request/context 等相關行，其餘約 85% 行不進入 JSON.parse；預篩一行都沒命中時退回逐行全解析，降低日誌格式變化導致漏統計的風險。
瀏覽器端若收到 x-token-usage-stale: 1，約 1.2 秒後會自動再請求一次，用刷新後的數據替換，用戶無需手動等待。
界面與能力¶
安裝並在設置中打開 Token 用量 面板後，可見：
- 頂部五格 KPI：累計、峯值、日均、調用次數、當前連續天數。
- Token 活動：整年日曆熱力圖，支持每日 / 每週 / 累計三種口徑；色深表示消耗，懸停或點按可看當日各模型明細；可與表格視圖（日期 / Token / 調用 / 強度）一鍵切換。
- 每日 Token 趨勢圖：連續日曆軸，無記錄日記 0，線不斷；每模型一條系列，用量前五名單獨展示，其餘合併爲「其他」。
- 模型排行：展示範圍內全部模型，含序號列。
配色使用宿主 token（--dsw-alias-*），跟隨 DSH 深淺主題。2026-11-01 的 UI/UX 審計修復了對比度、骨架屏、空態與數字格式等問題（詳見倉庫 README）。
安裝與啓用¶
從 GitHub 倉庫地址安裝；DSH 插件市場裏也可直接搜包名。官方 README 給出的安裝來源爲：
https://github.com/zhangyongshuai56-hub/dsh-token-usage
安裝完成後，在 DSH 設置 中打開 Token 用量 面板即可使用。本地開發可用 link: 協議軟鏈，改源碼後重啓 DSH 生效；提交前可運行：
node --check lib/index.js && node --check lib/aggregate.js && node --check lib/client.js
HTTP 接口¶
需要對接或調試時，可調用：
GET /dsh-token-usage/usage
響應體形狀爲：
{
"days": { "YYYY-MM-DD": { "provider/model": { "total", "input", "output", "calls" } } },
"models": [],
"totalTokens": 0,
"totalCalls": 0,
"scannedAt": "",
"sessions": 0
}
響應頭 x-token-usage-stale 爲 0 或 1：1 表示返回的是舊快照，服務端正在後臺重掃。
適用場景與注意¶
適合長期在 DSH 本機跑會話、希望按模型觀察 Token 趨勢與日曆分佈的開發者。數據完全來自本機 ~/.dsh/sessions 下的會話文件，不涉及遠端上報；會話越多、文件越大，首次或冷掃描成本越高，但穩態下增量掃描保持在毫秒級。
DSH 生態是「一切皆插件」；社區目錄站點與 DeepSeek / 幻方無官方從屬關係，本文介紹的插件來自社區維護者，安裝前請自行閱讀倉庫源碼與 MIT 許可證。插件以當前 DSH 進程權限運行，會讀取用戶目錄下的會話文件，安裝前應確認來源可信。
結尾¶
dsh-token-usage 把分散在會話日誌裏的 assistant/message 用量聚合成「天 × 模型」視圖，並用 stale-while-revalidate 與增量掃描保證面板可即時打開。目錄頁：https://www.skillhub.cn/plugins/zhangyongshuai56-hub/dsh-token-usage；源碼與完整說明：https://github.com/zhangyongshuai56-hub/dsh-token-usage。
