dsh-balance-status：DeepSeek 餘額與用量監控插件

前言¶

DeepSeek Harness (DSH) 採用插件化架構，允許開發者根據需求擴展功能。對於需要頻繁查詢 API 消耗的開發者來說，現有的監控方案往往需要瀏覽器權限或配置複雜。dsh-balance-status 插件解決了這個問題，它將 DeepSeek 賬戶的餘額與用量信息直接集成到 DSH Web 界面的底部狀態行中，無需額外的彈窗或複雜的配置，實現了輕量級的監控。

這是什麼¶

這是一個由 yknBugs 維護的輕量級插件，用於查詢 DeepSeek 賬戶餘額。它通過在 DSH Web 界面的底部狀態行追加餘額信息，並提供一個左鍵單擊彈出的詳情面板，讓用戶可以直觀地查看餘額、充值、贈送以及當前對話和進程的已用量。插件採用餘額差值記賬法，不依賴價格表。

核心功能¶

狀態行集成：在 DSH 默認狀態行（如 x 輪 xx 步 · xx tok/s xx M tok · 緩存命中 xx%）之後追加餘額顯示。
用量詳情面板：左鍵單擊餘額，彈出包含餘額、充值、贈送、當前對話已用、當前進程已用的詳情面板。
強制刷新：點擊餘額可強制立即刷新數據，繞過緩存。
自動刷新策略：默認每 5 分鐘自動刷新一次，與 DeepSeek 餘額接口的延遲對齊。
餘額差值記賬：不依賴外部價格表，通過餘額差值計算用量，調價不影響計算結果。
未配置狀態：當未配置 API Key 時，狀態行顯示“餘額未配置”。

安裝與啓用¶

插件支持通過本地打包文件或 GitHub 倉庫安裝。

本機打包安裝（推薦）¶

直接複製源碼目錄安裝會導致插件失效，建議先打包再安裝。

# 1) 在插件目錄執行打包命令
cd <插件目錄>
pnpm pack

# 2) 安裝打包後的 tarball 文件
dsh plugin --profile web add file:<插件目錄>\dsh-balance-status-1.0.2.tgz

安裝後需重啓 dsh web 進程。

從 GitHub 倉庫安裝¶

如果 pnpm 提示攔截構建腳本，需在 pnpm-workspace.yaml 的 allowBuilds 中添加本包名。

dsh plugin --profile web add github:<用戶名>/<倉庫名>

配置與用法¶

配置憑據：在 DSH 憑據頁配置 DEEPSEEK_API_KEY。這是查詢餘額的必要條件。
配置 Base URL（可選）：如需走內部網關，可配置 DEEPSEEK_BASE_URL，插件會自動跟隨 DSH 設置中的 llm-deepseek 的 baseURL。
查看與刷新：
- 刷新瀏覽器頁面，狀態行末尾應出現 餘額 ¥xx.xx。
- 左鍵單擊餘額：強制立即刷新並打開詳情面板。
- 關閉面板：點擊空白處或按 Esc 鍵。
- 自動刷新：默認每 5 分鐘自動刷新一次，點擊可打斷並強制刷新。

實現細節與限制¶

安全機制：密鑰不進入瀏覽器，餘額查詢接口僅在本地訪問。建議將 DSH 監聽在 127.0.0.1。
數據持久性：“當前對話已用”和“當前進程已用”數據存儲在宿主進程內存中，重啓進程後數據會丟失。
顯示精度：餘額接口爲 0.01 元粒度，小額消耗可能不顯示。
會話消耗：多個對話同時進行時，會話會互相包含對方的消耗，這是餘額差值記賬法的固有限制。
功能範圍：不支持畫圖、動畫或會話歷史記錄。
DSH 版本兼容：依賴 DSH 版本 0.1.7-rc.2（兼容 0.1.5-rc.x）。

許可與生態¶

本插件採用 MIT 許可證。其餘額接口與記賬思路參考了開源項目 DeepSeek-Balance-Whale-Widget。DSH 的插件生態獨立於 DeepSeek 官方，旨在構建一個靈活的擴展系統。

GitHub 倉庫: https://github.com/yknBugs/dsh-balance-status
DSH 生態目錄: https://www.skillhub.cn/plugins/yknBugs/dsh-balance-status