前言¶
用 DeepSeek Harness（DSH）跑對話和智能體時，Token 消耗往往分散在多次調用、重試和緩存讀寫裏。輸入框旁雖有狀態信息，但若要在更長的時間尺度上對照「今天每小時用了多少」「各模型各佔多少」「緩存命中率是否穩定」，通常需要翻本地會話或依賴其他面板。社區插件 dsh-clear-usage（維護者 xgxx666）在 設置 → 用量統計 中集中展示已結算調用的真實 usage，並保留 DSH 原版輸入框狀態欄與詳情彈窗，不替換輸入框下方界面。
這是什麼¶
dsh-clear-usage 是 DSH 的 Web 客戶端 插件（package.json 中 dsh.client.platform 爲 web），當前版本 0.1.0，許可證 MIT。它從 DSH 本地會話記錄讀取用量，只做統計與展示：顯示 Token 與調用次數，不估算費用、不顯示金額。插件僅註冊設置頁；輸入框用量、速度和點擊詳情仍由 DSH 原版提供。
與目錄中已有的 dsh-usage-panel 類似，兩者都分析設置頁裏的本地歷史用量，功能有部分重疊。本插件側重 DSH 原生 緩存命中率、今天的小時活動 與 Token 構成（未緩存輸入、緩存讀取、輸出、緩存寫入），並保留原版輸入框狀態欄。
核心功能¶
用量統計入口¶
安裝後打開 設置 → 用量統計，可查看 今天、本月、全部 以及 自定義日期範圍 的用量。自定義範圍需選擇開始和結束日期後點擊「查詢」，包含首尾兩天。
今天：24 小時柱狀圖與構成¶
「今天」頁展示 24 小時用量柱狀圖。懸停或鍵盤聚焦可查看每小時的 Token 與調用次數；構成條展示未緩存輸入、緩存讀取、輸出，有緩存寫入時也會顯示。小時分佈按 本地時間的調用結算時刻 歸檔，不把跨小時調用的用量平均拆到多個小時。
本月、全部與自定義：熱力圖與模型分佈¶
本月、全部和自定義範圍使用 緊湊熱力圖；打開或切換時間範圍時會自動定位到最近日期。懸停顯示日期和簡寫 Token 數量的兩行深色提示。
模型用量以居中的 圓環圖 顯示：圓心爲總 Token，下方顏色圖例展示各模型的用量、類型和佔比。模型用量默認使用原模型名；在頁面底部展開 「模型類型」 可設置顯示名稱。未選擇類型的標籤可點擊跳轉到該模型的本地/API 選項。類型與顯示名稱自動保存，僅影響篩選與展示；刪除後從管理列表、模型用量列表和圓環圖隱藏，圓環總量與佔比按當前顯示的模型重新計算。頁面頂部歷史總用量和活動圖保留完整記錄，不刪除 DSH 模型配置或會話日誌；可在 「已刪除的模型」 裏恢復。
數據口徑與緩存命中率¶
Token 來自 已結算調用的真實 usage。重試單獨累計；同一次調用的更新覆蓋舊樣本；思考 Token 已含在輸出內，不重複加總。歷史統計排除會話分支的繼承前綴，防止重複計算。緩存未報告或記錄不完整時會明確提示。
緩存命中率採用官方口徑：
緩存讀取 ÷（未緩存輸入 + 緩存讀取 + 緩存寫入）
官方未提供緩存讀取時按原生零值處理；插件不根據推理引擎的 KV 內存複用猜測緩存 Token。
本地和 API 模型都只顯示 Token，不需要填寫單價。
性能與刷新¶
首次讀取歷史時最多並行處理四個會話，並按會話版本複用已有統計。再次打開頁面會立即顯示本次應用運行中緩存的快照，同時後臺更新並標記「正在更新用量」；讀取失敗時保留已有數據。切換模型類型、時間範圍或日期在界面內立即篩選，不再重複掃描歷史；點擊刷新也可獲取最新用量。
安裝與啓用¶
適用於 DSH 0.2.0-rc.2 及更高兼容版本的 Web profile。Node.js 運行範圍與插件 engines 一致：^22.19.0 || >=24.0.0。
在終端執行 README 給出的安裝命令：
dsh plugin --profile web add github:xgxx666/dsh-clear-usage
DSH 桌面版的插件頁也可以選擇本項目目錄進行 本地安裝（目錄鏈接）。保留項目目錄；移動或刪除目錄會影響 DSH 加載。本包不包含依賴安裝腳本，不需要 API 密鑰。
典型用法¶
- 按上文命令安裝並確保使用 Web profile 的 DSH 版本滿足要求。
- 打開 設置 → 用量統計，先看 今天 的小時柱狀圖與 Token 構成，對照緩存讀寫是否如預期。
- 切換到 本月 或 全部，用熱力圖瀏覽活動密度；懸停查看單日簡寫 Token。
- 需要固定區間時，在 自定義 中選擇起止日期並點擊「查詢」。
- 在頁面底部 「模型類型」 中爲模型設置顯示名稱或類型，便於圓環圖篩選；誤刪可在「已刪除的模型」恢復。
模型分類保存在 $DSH_HOME/dsh-clear-usage/models.json。已有配置的舊字段保留以兼容歷史版本，頁面不再提供單價輸入或金額顯示。
適用場景與注意¶
適合誰： 希望在 DSH 內用統一口徑查看本地 Token 消耗、緩存命中率、按小時與按模型分佈，且不需要費用估算的 Web 端用戶。
隱私與數據： 用量從 DSH 本地會話記錄讀取，消息正文不會離開 DSH。插件不讀取憑據、不調用供應商 API，也不上傳統計數據。
安全提醒： 插件以當前 DSH 進程的權限運行。安裝前應閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的環境策略。社區目錄 SkillHub 插件頁 與 DeepSeek / 幻方無官方從屬關係，DSH 生態遵循「一切皆插件」的擴展方式。
修改界面後通常可以熱更新；修改宿主統計相關代碼（如 index.js、lib/usage.js）後需要正常重啓 DSH。開發者在插件目錄可運行 npm test 與 npm run check 做基本檢查。
小結¶
dsh-clear-usage 在設置頁提供基於本地會話的真實 Token 統計、官方口徑的緩存命中率，以及今天小時級活動與模型圓環圖，且不改動輸入框原版狀態欄。若你已在用 DSH Web profile 且版本不低於 0.2.0-rc.2，可按官方命令安裝後在設置中查看。
