前言¶
在 DeepSeek Harness（DSH）裏跑智能體或 Web 配置時，錢包餘額顯示在 設置 → 賬號與餘額 頁面，對應的是 platform.deepseek.com 賬戶（充值額度與贈送額度），與 API key 餘額、上下文餘量不是同一套數據。若要在腳本、監控或自動化流程裏週期性覈對這筆餘額，反覆打開設置頁並不順手。社區插件 dsh-balance（維護者 EviMing）在 DSH Web 進程內註冊一條僅本機可訪問的 GET 接口，通過 DSH 自帶的 deepseekAccount 服務讀取與界面一致的錢包數字，對外用 curl 即可復現。
這是什麼¶
dsh-balance 是 DSH 的 Web 側插件：安裝後在本機迴環地址暴露 /api/balance，返回當前已登錄 DeepSeek 賬號的錢包餘額 JSON 或純文本。它不保存憑據，token 仍由 DSH 管理在 ~/.dsh/.credentials.yaml；餘額查詢走宿主已掛載的 deepseekAccount.getBalance。插件版本 1.0.0，許可證 MIT，要求 DSH 0.2.0 及以上且已在 DSH 中登錄 DeepSeek 賬號。目錄頁：SkillHub - dsh-balance；源碼：GitHub - EviMing/dsh-balance。
核心功能¶
下面能力是 README 中已寫明的行爲，可按需裁剪使用場景。
餘額數據與界面一致¶
接口返回的 recharge（充值餘額）、bonus（贈送額度）、total（兩者之和）以及 currency（示例爲 CNY），與 DSH 設置裏展示的 platform.deepseek.com 錢包一致，不是 API 計費餘額。
本機 HTTP 接口¶
- 僅接受 GET，其他方法返回 405。
- 校驗請求來源與
Host，非本機（loopback）訪問返回 403，局域網其他機器無法直接讀取。 - 端口跟隨當前 DSH Web 地址，默認
127.0.0.1:3080。 - 15 秒緩存且 single-flight：短時間內重複請求複用上次結果，併發只打一次上游。
錯誤映射¶
失敗時統一爲 {"ok": false, "error": "...", "message": "..."}，常見 error 包括：signed-out（401，未登錄）、forbidden（403）、method-not-allowed（405）、upstream-failed（502）、account-unavailable（503，宿主未掛載 deepseekAccount）。
安裝與啓用¶
DSH 生態裏插件通過 CLI 安裝；web 配置檔對應 Web 服務與上述 HTTP 路由。
- 在已安裝 DSH 的環境裏執行官方安裝命令：
dsh plugin --profile web add github:EviMing/dsh-balance
- 安裝完成後刷新 DSH Web 頁面即可，無需重啓進程。
若使用本地目錄調試，可將路徑換成你的插件目錄（README 示例爲 Windows 路徑，Linux 下改爲實際絕對路徑）：
dsh plugin --profile web add /path/to/dsh-balance
安裝前建議瀏覽倉庫中的 index.js、cordis.patch.yml 與 MIT 許可證，確認與當前 DSH 版本（engines.dsh: >=0.2.0）匹配。插件以當前 dsh 進程權限運行，與任何第三方插件一樣，應自行評估源碼後再安裝。
典型用法¶
先確認 DSH Web 已啓動且賬號已登錄，再在本機請求接口。
完整 JSON（字段含義見下文）：
curl -s http://127.0.0.1:3080/api/balance
示例響應：
{
"ok": true,
"currency": "CNY",
"recharge": 12.416959,
"bonus": 0,
"total": 12.416959,
"fetchedAt": 1794049067812
}
其中 fetchedAt 爲本次讀取時間的毫秒時間戳。若只需要一行數字，可使用文本格式：
curl -s "http://127.0.0.1:3080/api/balance?format=text"
# 12.416959 CNY
上述命令來自項目 README，在未改端口的前提下可直接復現；若你修改了 DSH Web 監聽地址，應將 URL 中的主機與端口換成實際值。
適用場景與注意¶
適合誰：需要在 shell、定時任務或自建面板裏讀取與 DSH 設置頁相同的錢包餘額，且能接受「僅本機、只讀 GET」的開發者。
前提：DSH 0.2.0+（依賴 webServer.register 與 deepseekAccount.getBalance），並已登錄 DeepSeek 賬號；未登錄時會得到 401 / signed-out。
安全與範圍：接口故意不對局域網開放；不要通過反向代理把該路徑暴露到公網。插件不接觸憑據文件，但也不改變 DSH 自身的賬號安全策略——仍應對 ~/.dsh/.credentials.yaml 做好文件權限與備份習慣。
與社區目錄的關係：SkillHub 等爲 DSH 社區的獨立插件目錄站點，與 DeepSeek / 幻方無官方從屬關係；安裝來源以你信任的 GitHub 倉庫與官方 README 爲準。
結尾¶
dsh-balance 把「設置 → 賬號與餘額」裏的平臺錢包變成一條本機 curl 可調的 HTTP 讀口，適合在自動化裏做餘額快照或告警前置檢查。進一步瞭解可打開 SkillHub 目錄頁 與 GitHub 倉庫 中的安裝說明、錯誤碼錶與源碼結構（index.js、locale/、icon.svg 等）。
