前言¶
DSH 的插件化思路是把 Web GUI 的擴展能力拆成可安裝、可移除的包。使用 DSH 做模型調用時，本機用量、餘額和費用估算往往分散在不同地方。dsh-billing 把這部分監控集中到 DSH Web GUI：側邊欄顯示餘額，設置頁管理單價與賬本，Agent 可以查詢餘額和用量。
這是什麼¶
dsh-billing 是 DSH Web GUI 的即時計費監控插件。它統計本機模型調用用量與費用，按供應商和模型單價計費，支持 DeepSeek v4 峯谷價、官方餘額同步、官方單價同步和賬本持久化。倉庫地址中的賬號爲 nianpangzhi233，許可證爲 MIT。插件通過官方接口與客戶端 slots 系統實現，不修改 DSH 源碼。
核心功能¶
即時餘額¶
側邊欄底部會出現餘額 pill，刷新週期爲 2 秒。餘額狀態點會區分“充足 / 不足 / 耗盡”，告警時會閃爍。
概覽面板¶
點擊餘額 pill 後，會在側邊欄內展開面板，顯示已消費、調用次數、輸入 token、輸出 token 和最近流水。流水帶有峯谷標籤。收起側邊欄時，面板也會自動收起。
供應商與峯谷單價¶
單價匹配順序爲：
供應商+模型 → 同名模型 → 供應商默認 → 全局默認
DeepSeek v4 自 08-17 起採用峯谷定價：高峯爲北京 9–12、14–18，空閒時按半價計；命中緩存輸入按低單價計。
官方餘額與單價同步¶
填入 DeepSeek API Key 後，可以調用官方接口：
GET /user/balance
拉取總餘額、贈金和充值，並自動錨定到插件餘額；也支持手動粘貼校準。
官方單價同步可以一鍵拉取 DeepSeek 官方模型單價，按內置基礎價與持久化覆蓋合併。該能力僅在官方價目頁可達時生效，需要平臺 web provider。
設置頁與 Agent 工具¶
DSH 設置中會出現「計費」分段，內容覆蓋：
餘額、閾值、默認單價、供應商單價表格、數據管理
Agent 提示詞中會自動出現工具說明：
billing_balance
它用於查詢餘額、費用、token 用量和按模型明細。
持久化¶
賬本 JSON 原子寫入工作區。DSH 重啓後會自動恢復餘額、單價和流水。
安裝與啓用¶
先確認本機環境滿足以下要求：
Node: ^22.19.0 || >=24.0.0
peerDependencies:
- @deepseek-ai/cordis ^4.0.1
- @deepseek-ai/dsh-tools ^0.1.0-rc.6
- react ^18.2.0
- react-dom ^18.2.0
本包爲純 JS，無構建步驟，lib/ 即發佈產物，git 安裝即可用，無需 prepare 腳本，也無需構建授權。
從倉庫安裝：
dsh plugin --profile web add github:nianpangzhi233/dsh-billing
本地 checkout 或 tarball 安裝也可以：
dsh plugin --profile web add ./dsh-billing
dsh plugin --profile web add ./dsh-billing-0.1.0.tgz
經過上面的步驟，重啓 dsh web。之後側邊欄底部會出現餘額 pill，DSH 設置中會出現「計費」分段，Agent 提示詞中會自動出現 billing_balance 工具說明。
典型用法¶
1、進入配置入口：
DSH 設置 → 「計費」分段
也可以點擊側邊欄底部餘額 pill 展開面板。
2、配置餘額：使用 DeepSeek API Key 自動同步官方餘額，或手動粘貼錨定；也可以設置初始餘額和低餘額告警閾值，默認閾值爲 ¥20。
3、配置單價：設置未知供應商默認單價，單位爲 ¥ / 1M tokens；維護按供應商/模型的單價表，可增刪行；需要時點擊「同步官方單價」拉取 DeepSeek 官方價目。
4、管理數據：查看賬本路徑與保存時間、保存配置、重置用量；重置用量需要兩次點擊確認。
5、查詢用量：在 Agent 中使用 billing_balance 工具，查詢餘額、費用、token 用量與按模型明細。
數據與環境¶
賬本文件爲：
.dsh-billing-ledger.json
查找順序是工作區目錄優先，spRoot 兜底。v2 結構包含：
config / usage / ledger / startedAt
token 用量按分離計數：
inputTokens
cacheReadTokens
outputTokens
路由限制爲：
/api/dsh-billing/*
僅限 loopback，並做同源校驗。
適用場景與注意¶
- 只統計本機 DSH 的模型調用；官方餘額包含其他渠道消費，建議定期同步校準。
- API Key 以明文存於本機賬本文件，與
~/.dsh/dsh-ssh.json使用同一信任模型，文件權限爲0600；同步請求僅發給api.deepseek.com，響應只取餘額字段。 - 計費結果爲估算，單價與費率以 DeepSeek 官方爲準。
- 插件以當前
dsh進程權限運行。安裝前建議檢查源碼、許可證（MIT）和依賴要求。 - DSH 插件生態強調可插拔，社區目錄是獨立站點，不等同於官方應用商店。
結尾¶
dsh-billing 的價值在於把本機 DSH 的用量、餘額和費用估算放進 Web GUI 和 Agent 工具裏，方便日常使用時查看。
GitHub：
https://github.com/nianpangzhi233/dsh-billing
如果通過 DSH 插件目錄安裝，可按插件名 dsh-billing 查找具體條目。
