前言¶
用 DSH 跑 DeepSeek 會話時，有兩件事總要切出去做：想確認賬戶還剩多少錢，得打開 DeepSeek 平臺頁面；想知道這段時間消耗了多少 Token、花在哪個模型上，也得另開頁面翻。會話跑得越久，這種來回切換越頻繁。
ds-balance 把這兩件事搬進會話界面：餘額以徽章形式常駐會話頭部，點擊可看明細和用量圖表，也能直接跳官方收銀臺充值。下面介紹它的功能、安裝方式和使用流程。
這是什麼¶
ds-balance 是一個 DeepSeek Harness（DSH）插件，由 Lateautumns 維護，當前版本 1.1.0，協議 MIT。一句話定位：會話頭部常駐 DeepSeek 官方餘額徽章，附帶餘額明細、用量統計、歷史回填和站內充值浮窗。
它不用小浮窗常駐卡片，而是把餘額以徽章形式嵌在會話頂部右側，點擊徽章進入明細、用量與充值入口。
核心功能¶
餘額徽章與自動刷新¶
徽章常駐會話頭部右側，顯示狀態圓點加當前餘額，例如 DeepSeek ¥88.69。圓點顏色表示狀態：
- 綠：正常
- 黃：低於預警線（¥10 / $2）
- 紅：餘額不可用或查詢失敗
刷新頻率爲代碼常量：正常每 5 分鐘一次，低餘額時加密到 1 分鐘，查詢失敗 30 秒後重試。
餘額明細¶
點擊徽章彈出明細：總餘額、充值/贈送拆分、可用狀態、更新時間，以及今日和近 7 天用量概覽。
用量統計與圖表¶
插件監聽 DSH 會話事件（assistant/message 攜帶官方 usage 數據），按天 × 小時 × 模型聚合 API 請求次數、輸入（命中緩存/未命中緩存）、輸出 Tokens、輪次/步驟/工具調用。
點「用量詳情」切換區間：今日是 24 小時堆疊柱狀圖，近 7 天 / 近 30 天是每日堆疊柱狀圖，懸停任意位置顯示官方同款提示框。底部有三塊內容：本期合計拆分行、按模型拆分（每個模型一行：彩色圓點、名稱、請求/Tokens/消費及消費佔比條，當前覆蓋 V4 Flash / V4 Pro），以及逐日明細表（日期、請求、輸入·命中、輸入·未命中、輸出、消費）。
消費估算¶
消費按官方價目由 Token 用量推算：內置 v4-flash / v4-pro 雙價表，含 8/17 峯谷調價（北京高峯 9-12/14-18 爲高峯價、其餘半價，之前爲平價），按事件時間自動選擇價格檔。界面標註「估算」，實際以官方賬單爲準。
歷史回填¶
啓動時自動回填最近 15 個會話、30 天。用量詳情彈窗右上角有「回填歷史」按鈕，可一鍵深度回填最長 90 天、最多 60 個會話；數據有缺口時會提示「當前僅 X/Y 天有數據」。
回填上限 90 天，與 DSH 會話日誌保留期一致，更早的舊日誌通常已被壓縮清理，無法恢復。
站內充值¶
點「充值」打開站內浮窗：顯示當前餘額，金額預設 ¥10/50/100/200/500，也支持自定義。確認後前往 DeepSeek 官方收銀臺，用支付寶或微信完成支付，到賬後餘額自動刷新。
安裝與啓用¶
前提：本機已在 DSH 憑證庫配置 DEEPSEEK_API_KEY（如 ~/.dsh/.credentials.yaml）。未配置時徽章顯示「未配置」並提示。
安裝分兩步：
# 1. 安裝插件（web profile）
dsh plugin --profile web add <本倉庫路徑或 github:Lateautumns/ds-balance>
# 2. 重啓 DeepSeek Harness
重啓後打開任意會話，頂部右側即出現餘額徽章。本包通過 dsh.bundle.patch 掛載 Host 半端（cordis.patch.yml 注入 ds-balance 行），通過 dsh.client 加載 Client 半端（web 平臺、立即生效），重啓後兩者自動就位，無需手動改配置。
想先臨時體驗的話，可以在會話內讓 agent 加載倉庫根 host.js + client.js（動態 Cordis 插件形態），無需安裝即可試用。注意動態插件隨 DSH 進程重啓而失效，長期使用請走靜態安裝。
典型用法¶
日常操作按下面的順序：
- 查看餘額：會話頂部右側徽章直接顯示餘額，圓點顏色表示健康狀態。
- 餘額明細：點擊徽章，查看總餘額 / 充值 / 贈送 / 可用狀態 / 今日與近 7 天用量概覽。
- 用量詳情：點「用量詳情」，切換今日 / 近 7 天 / 近 30 天區間查看圖表與明細。
- 補齊歷史：顯示「當前僅 X/Y 天有數據」時，點右上角「回填歷史」補全最長 90 天。
- 充值：點「充值」→ 選金額（預設或自定義）→「前往官方收銀臺支付」→ 支付寶/微信完成付款 → 返回後餘額自動刷新。
實現與安全口徑¶
評估這個插件時，有幾個細節值得知道：
- RPC 通道：餘額查詢走官方接口
https://api.deepseek.com/user/balance；用量聚合支持區間參數 1d/7d/30d/all；深度回填參數限制 days≤90、sessions≤60。 - 密鑰安全：
DEEPSEEK_API_KEY從 DSH 憑證庫讀取，只在 Host 進程內用於 curl，永不進入瀏覽器，瀏覽器端只收到解析後的數字。 - 查詢方式：查詢命令以 danger-full-access 運行（shell + curl）。原因是 Windows ACL 沙箱 runner 在部分機器不可用，且
web.fetch不支持自定義 Header、無法攜帶 Bearer 認證。命令爲固定 curl（硬編碼官方 URL），無注入面。 - 可調常量：預警閾值 ¥10 / $2（
LOW_CNY/LOW_USD）與刷新頻率都是代碼常量，可自行修改；價格表內置 8/17 前平價與 8/17 後峯谷價兩檔（PRICE_TABLES）。
卸載¶
dsh plugin --profile web rm ds-balance
執行後還需從 cordis.patch.yml 移除 ds-balance 行（若安裝腳本未自動清理）。
適用場景與注意¶
ds-balance 適合通過 DSH 調用 DeepSeek API、希望在不離開會話的前提下掌握餘額和 Token 消耗的開發者。如果你本來就要定期去平臺頁面覈對用量和充值，徽章、圖表和充值入口能省掉這些切換。
使用前注意幾點：
- 消費爲估算，實際以官方賬單爲準。
- 歷史數據依賴會話日誌，回填上限 90 天，更早日誌無法恢復。
- 查詢命令以當前 dsh 進程權限運行（含 danger-full-access），安裝前應檢查插件源碼與許可證（MIT），確認可接受再裝。
結尾¶
ds-balance 用一個常駐徽章把餘額查詢、用量分析和充值三件高頻操作收進了 DSH 會話，靜態安裝重啓後自動生效，動態加載則適合先試用再決定。
- 插件目錄頁：https://www.skillhub.cn/plugins/Lateautumns/ds-balance （社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係）
- GitHub 倉庫：https://github.com/Lateautumns/ds-balance
