前言¶

在 DeepSeek Harness（DSH）裏開發智能體時，經常需要估算單次調用的成本、監控會話消耗、在長時間跑任務時檢查餘額是否充足。當前平臺只提供「設置 → 賬號」裏的餘額展示，切換窗口或頻繁查看都會打斷工作流。dsh-balance-badge 把餘額膠囊直接掛在對話輸入框正下方，與上下文用量指示器同一排，點擊即可查看消耗曲線、本會話累計消耗和一鍵充值入口。

插件定位¶

• 名稱：dsh-balance-badge
• 維護者：huachabobo
• 分類：客戶端插件
• 功能：在 DSH 輸入框下方顯示 DeepSeek 賬戶餘額、消耗曲線、本會話消耗，並提供一鍵充值入口

核心功能¶

餘額膠囊¶

膠囊默認掛在 Composer 卡片正下方（conversation.composer.dock），新建會話的 Hero 頁則放在工作區行右側（conversation.hero.options）。顯示內容取決於當前狀態：

• 命中餘額時顯示「餘額 ¥110.00」
• 贈金大於 0 時追加「＋贈金 ¥10.00」（平臺常駐一個 0.00 的贈金錢包，不會顯示爲 0）
• 膠囊左側顯示當前模型輸出價：「谷 ¥4/M」或「峯 ¥8/M」，顏色隨時段切換（谷=綠、峯=琥珀），懸停可查看模型名與時段

膠囊支持懸停查看明細：充值餘額、贈金餘額、本會話消耗、更新時間、最近一次失敗原因。

消耗曲線浮窗¶

點擊膠囊會彈出一個向上展開的 292px 浮窗，與「任務列表」等按鈕同一種菜單材質。浮窗內容包括：

• 頭部：所選區間的淨變化（−¥3.50 表示花掉，+¥3.50 表示增加）
• 充值餘額、贈金餘額、合計（贈金大於 0 時才顯示合計）
• 本會話消耗與輪數
• 四檔時間範圍切換：1小時 / 6小時 / 24小時 / 3天
• 折線 + 面積圖，藍點爲最近一次採樣，琥珀色小圓點標出區間內最大的一次單次消耗
• 統計行：區間消耗 / 最大單次 / 最高 / 最低
• 底部：最近更新時間與採樣點數
• 底部操作按鈕：充值、立即刷新、清空記錄

關閉方式：點擊浮窗外部、再點一次膠囊或按 Esc。

後臺刷新與狀態¶

• 後臺每 60 秒在可見頁面靜默刷新一次餘額
• 切回窗口或恢復標籤頁時，若數據超過 20 秒會自動補讀
• 輪次結束後（模型剛花完錢）自動補讀一次
• 狀態語義：同步中 / 未登錄 / 讀取失敗；餘額低於 1 時膠囊轉爲琥珀色警示

本會話消耗估算¶

平臺不提供「某個會話花了多少錢」的接口，插件通過餘額落差歸因：

• 一輪開始時記錄當時的餘額快照，同時強制讀一次餘額
• 一輪結束後，若基線與最新余額的差額超過 0.0001 元，則累加到該 sessionId，輪數 +1
• 換會話時各會話獨立記錄，互不影響
• 數據存儲在 localStorage["dsh-balance-badge:sessions:v1"]，最多保留 200 個會話（按最近更新丟棄）

這是估算而非精確賬單：同一時刻若有其他窗口也在消耗，差額會被算進當前會話；刷新失敗的那一輪不計。要查看精確數字仍以「設置 → 賬號」的平臺賬單爲準。點擊「清空記錄」可同時清空曲線與會話消耗記錄。

模型價格（峯谷）¶

膠囊左側的「谷 ¥4/M」或「峯 ¥8/M」是當前時段的輸出價格（元 / 百萬 tokens），懸停浮窗底部可查看完整價目與時段：

• 高峯時段：北京時間週一至週五 9:00–12:00、14:00–18:00
• 空閒時段：其餘時間（包括週末與法定節假日），空閒價 = 高峯價的一半
• 當前時段那一列會加粗
• 時段判斷按北京時間，與機器時區無關

價格表定義在 MODEL_PRICING 常量裏（deepseek-flash 與 deepseek-v4-pro 各含高峯/空閒三檔），PRICE_MODEL 決定膠囊按哪個模型報價，默認爲 deepseek-flash（桌面 profile 的默認模型）。若需調整，可修改 client.js 頂部的常量區。

曲線數據採樣¶

Platform 沒有餘額歷史接口，採樣由插件自己完成：

按「變化 + 心跳」記點，一天正常使用大約產生幾十到一百多個點。剛裝上時曲線爲空，用幾輪對話後就會長出來。同一瀏覽器裏換賬號會共用同一份歷史，不想要則點「清空記錄」。

安裝與啓用¶

通過插件市場安裝¶

目錄已收錄進 DSH 1024Store（提交 PR #673 通過自動化靜態檢查後自動合併），可通過以下命令安裝：

dsh plugin --profile <你的 profile> add github:huachabobo/dsh-balance-badge

若插件尚未發佈到 npm，市場裏能瀏覽和查看倉庫與截圖，但不會顯示「可安裝」按鈕。

本地克隆安裝¶

若想本地開發或調試，可按以下步驟操作：

# 1) 克隆到 profile 的插件目錄
git clone https://github.com/huachabobo/dsh-balance-badge `
  "$env:USERPROFILE\.dsh-beta\plugins\dsh-balance-badge"

# 2) 讓 profile 聲明依賴與組合包
#    ~/.dsh-beta/profiles/desktop/package.json:
#      dependencies:        "dsh-balance-badge": "link:../../plugins/dsh-balance-badge"
#      dsh.profile.bundles: "dsh-balance-badge"   ← 追加到數組末尾

# 3) 在 profile 目錄安裝（只解析本地目錄，不訪問 registry）
cd "$env:USERPROFILE\.dsh-beta\profiles\desktop"
pnpm install

link: 會把 node_modules/dsh-balance-badge 指回源目錄（Windows 上是 junction），修改 client.js 後無需重裝；若想固定一份副本，可改用 file:。使用 ~/.dsh 而不是 ~/.dsh-beta 時，請相應調整路徑。

安裝後生效¶

1. 保存 profile 配置：啓用 HMR 的 profile（隨產品交付的 desktop / web 模板默認開啓）會在 package.json、cordis.patch.yml 變化時重新組合，插件行即時掛載。
2. 重載客戶端 bundle：Host 在組合時會快照每個 client.js，修改插件代碼後，只刷新頁面不一定能拿到新文件。
   - 有把握的一步：在「側邊欄 → 插件」中把 dsh-balance-badge 關再開（會重新組合並替換 bundle），然後刷新頁面。
   - 或直接重啓 DSH。
3. 驗證掛載：在 Host 日誌中搜索 [dsh-balance-badge] badge mounted; client bundle served from ./client，出現該行即表示插件已掛載。

可調參數¶

所有可調參數集中在 client.js 頂部的 constants 區：

適用場景與注意¶

適合需要實時監控 DeepSeek 賬戶餘額、估算單次調用成本、追蹤長時間任務消耗的開發者。

插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證（本項目使用 MIT 許可證）。

結語¶

dsh-balance-badge 把餘額與消耗信息下沉到工作流中，減少在設置頁和聊天窗口之間來回切換的次數。配合曲線圖與時間範圍切換，可以更直觀地判斷消耗趨勢。更多細節可在 GitHub 倉庫查看，目錄頁提供快速安裝入口。