前言¶
用 DeepSeek Harness（DSH）跑 dsh web 時，餘額和 token 用量通常要切到別的頁面或終端去查。多 provider、多通道（DSH 與 Claude Code）並行時，更難一眼看清「今天花了多少」「哪條通道佔大頭」。
dsh-usage 是社區維護的客戶端插件，在 Web GUI 左下角掛一個持久化 dock，並提供一個可定製的餘額 / 用量面板。數據在本地聚合，憑證由 Harness 服務端解析，不進入瀏覽器響應。
這是什麼¶
dsh-usage（GitHub：Aisland-SJL/dsh-usage，SkillHub 目錄：Aisland-SJL/dsh-usage）由 Aisland-SJL 維護，分類爲客戶端插件，MIT 許可。當前版本 0.2.0，GitHub 約 20 stars。
它面向已啓用 web profile 的 DSH 用戶，解決三件事：隨時可見的餘額與用量摘要、可拖拽排序的詳情面板、以及 DSH 通道與 Claude Code 通道的用量對比。
核心功能¶
持久化 dock¶
關鍵數字常駐界面左下角。餘額充足時顯示爲綠色，餘額耗盡時變紅；今日 / 本月 token、緩存命中率以緊湊行展示。角落有設置齒輪與一鍵刷新。側邊欄摺疊時，dock 收成一個小型餘額膠囊。
詳情面板（七個組件）¶
兩列卡片佈局，每個組件可展開詳情、摺疊、隱藏、固定（pin），並支持拖拽排序：
| 組件 | 作用 |
|---|---|
| Balance | 左側大數字，右側展示可用 / 充值 / 贈送餘額；可切換 provider |
| Today | 今日 token 總量，含 input / output / cache-read 拆分 |
| This month | 本月 token 總量，拆分同上 |
| Cache hit | 今日與全時段緩存命中率 |
| Channel share | DSH 通道與 Claude Code 通道佔比條 |
| Usage log | 近 14 天按日列表，點擊可下鑽到各模型明細 |
| Activity heatmap | 28 天 × 6 個四小時時段的點陣熱力圖 |
外觀與佈局定製¶
強調色（預設 + 取色器）、背景色、面板透明度可即時調整。組件的 pin / collapse / hide / drag-reorder 狀態寫入 localStorage，刷新後保留。
雙通道用量對比¶
DSH 側 token 來自 Harness 內置統計；Claude Code 側通過增量解析 ~/.claude/projects 下的 JSONL 日誌聚合，只保留數字，不讀取消息正文。
本地優先與安全邊界¶
插件暴露三個僅 loopback 可訪問的 GET 端點。憑證從 ~/.dsh/.credentials.yaml 經 Harness credentials seam 在服務端解析，插件不讀取、不緩存、不回顯密鑰。上游餘額查詢強制 HTTPS，DNS 預解析並拒絕私網 / 環回地址，連接綁定到已校驗 IP（防 DNS rebinding），響應上限 1 MiB，超時 15 秒。用量緩存寫在 ~/.dsh/storages/，僅存聚合數字與 fold 遊標。
支持的餘額 provider¶
| Provider | 上游端點 | 默認憑證引用 |
|---|---|---|
| DeepSeek | GET {origin}/user/balance |
DEEPSEEK_API_KEY |
| OpenRouter | GET {origin}/api/v1/credits |
OPENROUTER_MANAGEMENT_KEY |
| Moonshot / Kimi | GET {origin}/v1/users/me/balance |
pi-ai provider 的 apiKeyEnv（自動發現） |
| Z.ai / GLM | GET {origin}/api/paas/v4/balance |
ZAI_API_KEY |
沒有公開餘額接口的 provider 會顯示明確狀態，不會猜測數值。界面支持中英文。
安裝與啓用¶
前置條件：@deepseek-ai/dsh >= 0.1.0-rc.6，且使用 web profile。
下面命令來自插件 README 與 SkillHub 目錄頁：
dsh plugin --profile web add "github:Aisland-SJL/dsh-usage"
安裝後重啓 dsh web，在瀏覽器執行硬刷新，左下角應出現 dock。更新與卸載：
dsh plugin --profile web update dsh-usage
dsh plugin --profile web remove dsh-usage
典型用法¶
配置憑證¶
餘額查詢讀取 ~/.dsh/.credentials.yaml 中的引用，按實際使用的 provider 填寫：
DEEPSEEK_API_KEY: sk-your-key-here # 官方 DeepSeek 線路
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-... # OpenRouter 賬戶（Management Key，非推理 key）
ZAI_API_KEY: your-zai-key # Z.ai 開放平臺
Moonshot / Kimi 若在 llm-pi-ai 中已配置，會自動發現對應 apiKeyEnv。
面板操作¶
- 點擊 dock 角落齒輪打開詳情面板。
- 在 Balance 組件切換 provider，查看分項餘額。
- 點擊 ↻ 或等待後臺刷新（啓動時刷新一次，之後每 5 分鐘）：餘額、DSH token、Claude Code 聚合同步更新。
- 在 Usage log 點擊某一天，下鑽到 per-model 明細。
- 在定製器中調整強調色、背景、透明度，拖拽組件順序並 pin 常用項。
HTTP API（僅供本機調試）¶
| 方法 | 路徑 | 響應內容 |
|---|---|---|
GET |
/api/usage/providers |
provider 列表、餘額 scheme、狀態摘要 |
GET |
/api/usage/balance?provider=<id> |
統一餘額快照；refresh=1 強制上游查詢 |
GET |
/api/usage/usage |
按日 / 按模型 token 聚合、緩存命中率、24 小時桶（days[].hours）、Claude Code 通道（claude） |
非 GET 請求返回 405，非 loopback 調用返回 403。響應均爲 JSON，Cache-Control: no-cache。請勿通過反向代理把這些端點暴露到局域網或公網。
適用場景與注意¶
適合人羣：
- 長期開着
dsh web，需要隨時看餘額和今日 / 本月用量； - 同時使用 DSH 與 Claude Code，想對比兩條通道的 token 佔比；
- 在意隱私，希望用量在本地聚合、密鑰不進入瀏覽器。
安裝前注意：
- 插件以當前
dsh進程權限運行，安裝前應自行檢查源碼與 MIT 許可證。 - Claude Code 聚合依賴本機
~/.claude/projects日誌；無日誌時對應通道顯示爲空或零，屬預期行爲。 - OpenRouter 餘額需 Management Key，普通推理 key 無法查詢 credits。
- SkillHub 爲社區目錄站點，與 DeepSeek / 幻方無官方從屬關係；插件同樣屬於社區生態，遵循 DSH「一切皆插件」的擴展方式。
結尾¶
dsh-usage 把餘額、token 用量、緩存命中、活動熱力圖和雙通道對比收進 Web GUI 左下角，配置項與佈局可本地持久化，憑證與上游查詢留在服務端邊界內。若你已在用 DSH web profile，可按上文命令安裝，重啓後硬刷新即可驗證。
- SkillHub 目錄：https://www.skillhub.cn/plugins/Aisland-SJL/dsh-usage
- GitHub 倉庫：https://github.com/Aisland-SJL/dsh-usage
