前言¶
用 DeepSeek Harness（dsh）做開發，通常離不開 DeepSeek API。想知道賬戶餘額還剩多少，一般得離開當前環境、去平臺後臺查一下。dsh-deepseek-balance 把這件事搬進了 dsh web 界面：餘額直接顯示在側邊欄底部，鼠標懸停看明細，點擊即可強制刷新。下面介紹這個插件的用法和實現。
這是什麼¶
dsh-deepseek-balance 是一個 DeepSeek Harness（dsh）插件，由 kyya 維護，當前版本 0.1.0，採用 MIT 許可證。它在 Web 側邊欄底部（設置按鈕上方）即時展示 DeepSeek API 賬戶餘額。DSH 的理念是「一切皆插件」，這是一個小而具體的例子。
核心功能¶
- 在 Web 側邊欄底部（設置按鈕上方）即時展示 DeepSeek API 賬戶餘額。
- 餘額數據由 Node 側定時拉取，瀏覽器側每 30s 輪詢；點擊指示器可立即強制刷新。
- 狀態點顏色指示：綠 = 可用；黃 = 賬戶不可用；紅 = 拉取失敗；藍 = 加載中。
- 懸停顯示完整明細：總額 / 贈送 / 充值 / 更新時間。
- API key 每次拉取時經
credentials服務解析，永遠不會下發給瀏覽器。
安裝與啓用¶
先安裝插件，支持從 git 或本地目錄兩種方式：
# 從 git 安裝
dsh plugin --profile web add github:kyya/dsh-deepseek-balance
# 或本地目錄方式
dsh plugin --profile web add /絕對路徑/dsh-deepseek-balance
注意：dsh plugin 只會裝依賴，插件集變更需要重啓 dsh web 才生效：
dsh web
重啓後打開 http://127.0.0.1:3080，側邊欄左下角即可看到餘額指示器。
配置¶
默認讀取憑據 DEEPSEEK_API_KEY，來源有三處：~/.dsh/.credentials.yaml、DEEPSEEK_API_KEY 環境變量、或「設置 → 模型」裏保存的 key。
如需調整，在 ~/.dsh/profiles/web/cordis.patch.yml 裏覆蓋。注意這裏是覆蓋整行 config，需要寫全所有字段：
- id: deepseek-balance
config:
refreshMs: 60000 # 後臺刷新間隔（毫秒）
apiKeyEnv: DEEPSEEK_API_KEY # 憑據引用名
baseUrl: https://api.deepseek.com
endpoint: /user/balance
工作原理¶
插件分 host 和 browser 兩個半邊：
| 半邊 | 文件 | 職責 |
|---|---|---|
| host（Node） | index.js |
定時 GET <baseUrl><endpoint>（Bearer 鑑權），緩存快照；用 webServer.register 暴露 /deepseek-balance |
| browser | client.js |
向 sidebar.footer.action 插槽註冊 React 指示器；輪詢 /deepseek-balance，點擊帶 ?refresh=1 強制刷新 |
餘額接口返回形如：
{
"is_available": true,
"balance_infos": [
{
"currency": "CNY",
"total_balance": "123.45",
"granted_balance": "0.00",
"topped_up_balance": "123.45"
}
]
}
is_available 對應狀態點的綠 / 黃，balance_infos 裏的總額、贈送、充值字段對應懸停明細。
卸載¶
dsh plugin --profile web remove dsh-deepseek-balance
適用場景與注意¶
適合同時在用 dsh web 和 DeepSeek API、希望隨時掌握賬戶餘額的開發者。兩點提醒：
1、插件以當前 dsh 進程的權限運行，安裝前建議檢查源碼與許可證；
2、覆蓋配置時必須寫全 config 的所有字段，漏寫會導致該字段丟失。
結尾¶
dsh-deepseek-balance 用很小的成本解決了一個高頻問題：不離開 dsh web 就能看到 DeepSeek API 餘額，且 key 不出 Node 側。項目地址與社區目錄：
- GitHub：https://github.com/kyya/dsh-deepseek-balance
- 目錄頁：https://www.skillhub.cn/plugins/kyya/dsh-deepseek-balance
目錄爲社區獨立維護，與 DeepSeek / 幻方無官方從屬關係。
