dsh-usage-footer：DSH Web 用量與費用監控插件

在 DSH（DeepSeek Harness）生態中，一切皆插件。對於開發者而言，實時掌握 Token 消耗與費用是日常開發中的剛需。現有的官方賬單往往存在延遲或層級較深，難以快速查閱。dsh-usage-footer 插件旨在爲 DSH Web 界面提供一個輕量級的監控入口，將用量統計、費用估算與峯谷時段信息濃縮於右下角的懸浮面板中。

插件簡介¶

這是一個爲 DeepSeek Harness Web 界面設計的用量與費用監控插件。插件在頁面右下角提供一個金幣樣式的懸浮按鈕，懸停或點擊即可展開用量面板，支持查看賬戶餘額、峯谷時段、本會話 token 統計、今日消費估算以及本地賬本與官方數據的對比。同時，它在設置中提供了一鍵開關。由 1514100951 維護，遵循 MIT 許可證。

核心功能¶

懸浮按鈕與狀態指示：頁面右下角顯示一枚金幣徽標圓鈕。外環與角點顏色指示當前時段：綠色爲空閒，琥珀色爲高峯（伴隨呼吸動畫），紅色表示餘額查詢失敗。
懸停彈窗：鼠標懸停觸發彈窗，延遲 120ms 出現，寬容關閉時間 260ms。內容包括：
- 賬戶餘額：來自官方 API GET https://api.deepseek.com/user/balance，每 60 秒刷新，含充值與贈送拆分。
- 峯谷時段：按北京時間實時判定，展示 24 小時峯谷條（高峯時段爲 9:00-12:00 / 14:00-18:00）。
- 本會話用量：累計 token 與輸入（未緩存）、緩存命中、緩存寫入、輸出四項分條顯示。
- 本地賬本：按 DeepSeek 官方價格表記錄今日/本月 token 與金額，僅記錄插件啓用後的用量。
- 官方對比：配置 DEEPSEEK_PLATFORM_TOKEN 後，並排顯示本地賬本與 platform.deepseek.com 官方彙總。
- 今日消費估算：通過餘額快照差值估算，僅作兜底。
- 本機今日用量：按會話去重累計，非官方賬單。
- 本月用量/費用：優先顯示官方平臺彙總，否則顯示本地賬本彙總。
設置開關：在 DSH 的「設置 → 通用」中提供「用量與費用欄」開關，實時生效。關閉後停止輪詢並返回 { disabled: true }。
視覺適配：面板採用毛玻璃效果，使用宿主的 --dsw-* 設計令牌，自動適配明暗主題。

安裝與前置條件¶

環境要求¶

DSH 版本：>=0.1.0-rc.8 <0.2.0
Node.js 版本：>=20 <27

安裝命令¶

dsh plugin --profile web add github:1514100951/dsh-usage-footer

安裝後需重啓進程並運行 dsh web。

前置憑證配置¶

必須配置 DEEPSEEK_API_KEY：用於獲取賬戶餘額數據。
可選配置 DEEPSEEK_PLATFORM_TOKEN：用於獲取官方平臺彙總數據，便於與本地賬本對比。

功能說明與限制¶

本地賬本存儲：本地賬本數據持久化在 $DSH_HOME/storages/usage-footer-ledger.json，但僅記錄插件啓用後的用量，不追溯歷史。
消費估算邏輯：今日消費估算採用“當日首次查詢餘額快照 − 當前餘額”的方式，僅作兜底，受充值、贈送和餘額結算延遲干擾。
本機統計：本機今日用量統計爲非官方數據，存儲在 localStorage（鍵名爲 dsh-usage-footer.today.v1），每日清零，按會話去重累計。
安全與網絡限制：GET /usage-status 接口僅綁定 127.0.0.1，路由內校驗迴環，局域網訪問會被拒絕。插件僅訪問 api.deepseek.com 與（可選的）platform.deepseek.com。

該插件通過 Bundle Patch 方式註冊，不替換、不遮蔽、不禁用任何官方組件。