前言¶
在 DSH（DeepSeek Harness）裏接多個 Provider、多個模型跑會話時，用量往往分散在各家的控制台或賬單裏，很難在同一處按時間、模型對比「今天用了多少、哪條鏈路最喫 Token」。若還要自己寫腳本解析日誌，成本和隱私邊界也不好把握。
下面介紹社區插件 dsh-token-usage（維護者 qiz42144-web）：它只做被動觀察——讀取 DSH 本就會寫入的用量元數據，落到本地 SQLite，再用頁面做聚合與圖表。不調用模型、不聯網讀業務內容，適合想把用量留在本機的開發者。
這是什麼¶
- 名稱：
dsh-token-usage（npm 包名@aixnest/dsh-token-usage） - 分類：admin-security（SkillHub 目錄歸類）
- 許可證：MIT（© 2026 qiz42144-web）
- 定位：輕量 DSH 插件，本地記錄並按 Provider、賬號、套餐、模型拆分 Token，支持時間範圍、趨勢圖、排行與請求記錄。
插件不讀取提示詞、回覆正文、工具參數、請求體或 API Key；不產生額外模型請求，也不往上下文裏注入內容。
核心功能¶
統計範圍與指標¶
時間範圍支持：今日、本週、本月、本年、全部，以及自定義起止日期（結束日含當天全天；最後一次選擇會記住）。日曆按本地計算，不是固定 24 小時滑動窗口。
指標卡片共 7 項：總計、輸入、輸出、緩存、緩存命中率、推理、請求數。緩存命中率按 Token 加權；Provider 未上報緩存時顯示 —。推理 Token 屬於輸出的一部分，不計入總計重複加總。
趨勢圖與年度熱力圖¶
柱狀趨勢圖隨範圍自動調整粒度（例如今日按小時、本年可按日/周/月）。懸停可查看該週期的分項與請求數。選擇「本年 + 按日」時，頁面切換爲 12 月 × 31 天 的年度熱力圖，便於看使用密度。
排行、請求記錄與篩選¶
排行可在「模型 / Provider」間切換，按總量降序。請求記錄按時間倒序，每頁 50 條，可加載更多；未返回 usage 的請求標爲「未知」，不按 0 計入 Token。
「全部模型」下拉爲樹形結構：Provider → 賬號 → 套餐 → 模型，任一層級即可篩選，並支持搜索模型 id 或自定義名稱。可爲 Provider、賬號、模型設置顯示名，爲模型打套餐標籤，真實 id 仍保留。
顯示與配置¶
數字格式可在「簡寫」（如 4.25B）與「完整」（千分位）間切換，並會記住偏好。自定義日期使用自建日曆組件，支持鍵入 2026-09-06 或 2026/09/06。
可選配置（默認 config: {}）：
| 配置項 | 默認值 | 說明 |
|---|---|---|
dbPath |
$DSH_HOME/token-usage/usage.db |
SQLite 歷史文件絕對路徑 |
recordAttempts |
true |
是否記錄完全沒有返回消息的模型步驟爲未知請求 |
安裝與啓用¶
插件以當前 DSH 進程權限運行。安裝前建議查看 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的合規要求。SkillHub 目錄頁：qiz42144-web/dsh-token-usage（社區站點，與 DeepSeek / 幻方無官方從屬關係）。
從 npm 安裝（推薦）¶
在 DSH 會話中執行：
plugin_manager install_bundle target = @aixnest/dsh-token-usage
包地址：https://www.npmjs.com/package/@aixnest/dsh-token-usage（README 中 npm 版本徽章對應發佈線；package.json 標註 engines.node 爲 >=22.5.0）。
安裝成功後，側邊欄會出現 Token 用量 入口。首次打開數據庫爲空，從安裝之後的下一個請求起自動記錄，不會回溯歷史。
若安裝返回 restart-required（例如 Host 側模塊有變更），按提示重啓 DSH；僅當返回 applied 時側邊欄入口才會立即可用。
更新與卸載¶
更新：重新執行一次安裝命令即可。
plugin_manager install_bundle target = @aixnest/dsh-token-usage
卸載：
plugin_manager remove_bundle target = @aixnest/dsh-token-usage
卸載不會刪除數據庫。若要清除歷史，需手動刪除 $DSH_HOME/token-usage/（或你在 dbPath 中指定的路徑）。
可選 profile 配置示例¶
在 profile 中插入 bundle 並自定義庫路徑、是否記錄「空返回」步驟：
- insert:
- id: token-usage
name: dsh-token-usage
config:
dbPath: 'D:/dsh-data/token-usage.db'
recordAttempts: false
典型用法¶
1、完成安裝並確認側邊欄有「Token 用量」後，正常使用 DSH 發起對話或工具調用，用量會自動寫入 SQLite。
2、打開面板，先選時間範圍（或自定義日期並點「應用」），查看頂部指標卡片與趨勢圖。
3、需要對比模型成本時，用「全部模型」樹或搜索收窄到單個模型；在排行區切換「模型 / Provider」查看誰佔用最多。
4、覈對單筆請求時，下翻請求記錄；對無 usage 的條目留意「未知」提示，避免與 Token 合計混淆。
5、若數字與 Provider 後臺不一致，以 Provider 上報的 usage 爲準；插件按 總計 = 輸入 + 輸出 + 緩存讀 + 緩存寫 統一換算，各家對「輸入」是否含緩存命中定義可能不同。
數據存儲、隱私與注意¶
存儲內容：每條模型步驟一行——時間、Provider id、模型 id、輸入/輸出/緩存/推理 Token、請求數。偏好寫在同目錄 settings.json（數字格式、上次範圍等）。
默認路徑：$DSH_HOME/token-usage/usage.db。插件無出站請求；前端僅通過本機 Host 接口拉數據。
常見問題摘要：
- 頁面一直爲空：安裝前發生的請求不會入庫，需等新請求產生。
- 裝完沒有入口：確認不是
restart-required而未重啓。 - 找不到模塊
@aixnest/dsh-token-usage：檢查 profile 的node_modules與package.json依賴，必要時重裝。 - 數據不會同步雲端；卸載後本地庫仍可保留。
修改插件源碼後需重啓 DSH；官方 README 還提供 docs/使用指南.md、docs/隱私與數據說明.md 等文檔供細讀。
結尾¶
dsh-token-usage 把 DSH 已有的用量元數據收攏到本機數據庫，用同一套面板看範圍、趨勢、熱力圖和請求明細，適合在多 Provider、多模型並行開發時做本地用量觀測。它不替代各家賬單，但能在會話側快速回答「這段時間、這個模型用了多少 Token」。
- 目錄頁：https://www.skillhub.cn/plugins/qiz42144-web/dsh-token-usage
- 源碼與 README：https://github.com/qiz42144-web/dsh-token-usage
