DeepSeek Harness Web 懸浮用量面板插件

在 DeepSeek Harness (DSH) 的 Web 環境下，開發者需要頻繁切換標籤頁查看餘額和 Token 消耗。dsh-deepseek-usage-panel 提供了一個 macOS 風格的懸浮用量面板，將實時官方餘額和本地測量的 Token 用量數據集成到界面中，無需打開 platform.deepseek.com/usage。

插件定位¶

這是一個由 WeiyangPro 維護的客戶端插件，基於 MIT 許可證開源。它爲 DSH Web 界面增加了毛玻璃效果的 UI 組件，用於展示官方餘額快照以及基於本地測量的 Token 消耗趨勢。

核心功能¶

官方餘額：通過輪詢 GET /user/balance 接口獲取數據，只展示官方返回的餘額字段，確保數據源的一致性。
Token 用量統計：提供今日、當前會話、近 24 小時的平滑曲線圖。統計維度包括輸入 Token、輸出 Token，並包含緩存命中/未命中的明細，以及按模型佔比的分佈。
交互設計：
- 膠囊與面板：右下角顯示膠囊，支持拖動至任意位置，位置自動記憶。
- 展開與收起：點擊膠囊展開面板，支持點擊面板任意位置、紅綠燈圖標或按 ESC 鍵收起，帶過渡動畫。
- 自動方向：面板展開方向會根據膠囊位置自動選擇（向上或向下）。
- 刷新：右上角提供刷新按鈕，點擊後圖標旋轉並反饋“已刷新”狀態。

安裝與啓用¶

安裝插件需要在終端執行以下命令。安裝完成後，重啓 dsh web 並對瀏覽器進行硬刷新（Ctrl/Cmd + Shift + R）。

dsh plugin --profile web add dsh-deepseek-usage-panel

配置 API Key¶

插件需要訪問 DeepSeek API 以獲取餘額信息。API Key 僅存儲在宿主 Node 進程中，不會注入瀏覽器，安全性較高。請在 ~/.dsh/.credentials.yaml 中配置：

version: 1
refs:
  DEEPSEEK_API_KEY: sk-你的key

也可以通過環境變量 DEEPSEEK_API_KEY 或 DSH_USAGE_HUD_API_KEY 設置。

典型用法¶

查看狀態：右下角的膠囊會實時顯示當前餘額、今日用量和會話用量。膠囊位置可拖動，下次打開會自動恢復。
展開面板：點擊膠囊，面板展開，展示餘額卡片、24 小時曲線圖、模型佔比統計以及跳轉官方 usage 頁的鏈接。
操作控制：點擊面板空白處或按下 ESC 鍵收起面板；點擊右上角的刷新箭頭立即更新數據。

配置項¶

在 DSH profile 的 cordis.patch.yml 文件中，可以通過覆蓋 id: usage-panel 的配置來調整插件行爲：

- id: usage-panel
  config:
    pollIntervalMs: 300000   # 餘額輪詢間隔（毫秒），最小 60000
    historyHours: 72         # 歷史小時桶保留數
    baseURL: https://api.deepseek.com   # 覆蓋接口地址
    apiKeyRef: DEEPSEEK_API_KEY         # 憑據引用名
    dataDir: null            # 覆蓋數據目錄（默認 $DSH_HOME/dsh-deepseek-usage-panel）

數據與隱私¶

數據存儲：API Key 僅存在於宿主（Node）進程，瀏覽器僅接收解析後的餘額快照。歷史 Token 數據保存在本地數據目錄的 state.json 中，支持原子寫入和自動裁剪。
數據口徑說明：
- 今日 / 近 24 小時 / 按模型 / 會話 的 Token 數據是本地測量值，不是 DeepSeek 平臺的官方賬目。
- 由於插件從“運行時刻”開始統計，若安裝較晚或中途重啓，安裝前產生的請求無法被統計，因此“今日”或“近 24 小時”的數據可能偏小於官方全天金額。
- 單條記錄的 Token 計算與官方計費同源，但整體總量可能因觀測窗口不完整而偏差。
- “會話”爲當前會話累計值，不等於自然日口徑。
- 建議關注數據的相對趨勢和構成，絕對總量請以官方 usage 頁爲準。

許可證與生態¶

許可證：MIT。
Node 版本：>= 20。
生態：該插件屬於 DeepSeek Harness 插件生態的一部分，社區目錄由獨立站點維護，與 DeepSeek 或幻方無官方從屬關係。

項目地址：GitHub - WeiyangPro/dsh-deepseek-usage-panel