dsh-account-quota：DeepSeek Harness Web 插件，顯示真實餘額與用量

DeepSeek Harness（DSH）的 Web 插件生態允許開發者將功能注入到聊天界面中。dsh-account-quota 插件解決了在使用 Web 界面時難以直觀查看賬戶狀態的問題。它會在輸入框下方增加一行常駐顯示，展示賬戶的真實餘額、用量百分比以及今日消耗，其排版與 DSH 自帶的會話統計膠囊保持一致。

插件簡介¶

這是一個 DSH Web 插件，由開發者 shxiaooo 維護，採用 MIT 許可證。

核心功能是在輸入框下方的常駐行顯示賬戶真實餘額與用量。它與同一行的會話統計膠囊保持一致的排版和配色。該行顯示兩個膠囊：一個展示餘額與今日消耗（如 ¥12.34 · 今日 -¥0.56），另一個展示使用率與重置倒計時（如 5 小時 42% · 重置於 1小時29分）。

核心功能¶

真實數據源¶

卡片上的每個數字都直接來自提供方的 API，沒有任何本地推算。插件支持兩種適配器：

DeepSeek 官方：通過 kind: tokens 讀取 https://api.deepseek.com/user/balance，顯示總餘額與今日消耗。
OpenCode Go：通過 kind: plan 讀取 https://opencode.ai/zen/go/v1/usage，顯示滾動、每週、每月的用量百分比。

今日消耗計算¶

“今日消耗”並非簡單的“當前餘額 - 起始餘額”。插件在 Host 端保存一條餘額序列，通過計算相鄰樣本的差值來得出結果：
* 今日消耗 = Σ max(0, vᵢ₋₁ − vᵢ)
* 今日充值 = Σ max(0, vᵢ − vᵢ₋₁)

這種基於差值的累加方式，能正確處理充值操作，且數據落盤存儲，刷新頁面或重啓進程後仍可讀取。

展開面板¶

點擊膠囊可打開詳情面板，顯示所有上游字段的快照。面板使用與 DSH 統計行相同的 UI 皮膚（stat-dialog），包含重置倒計時和採樣次數信息。

佈局整合¶

插件通過 CSS 選擇器修改佈局，使其與統計行並排顯示，而不是另起一行。這涉及對 data-slot='conversation.composer.dock' 的特殊處理，以確保不破壞輸入框卡片原有的佈局。

安裝與配置¶

安裝¶

在終端執行以下命令：

pnpm dsh plugin --profile web add link:~/dsh-account-quota

安裝後必須重啓 dsh web，瀏覽器才能在啓動時組裝進 boot graph。

環境變量¶

使用前需配置環境變量：
* DEEPSEEK_API_KEY
* OPENCODEGO_API_KEY

配置示例¶

在 DSH 的配置文件中，可以調整超時、緩存時間和狀態落盤路徑等參數：

- id: account-quota
  config:
    # 單次上游請求超時（覆蓋響應體讀取）
    requestTimeoutMs: 10000
    # 上游響應體上限，邊讀邊判
    maxResponseBytes: 65536
    # 快照新鮮度下限，同時也是 Host 半的採樣週期（默認 60000ms）
    cacheMs: 60000
    # 餘額序列落盤位置
    statePath: $DSH_HOME/account-quota/state.json
    # 提供方配置
    providers:
      deepseek:
        kind: tokens
        displayName: DeepSeek 官方
        apiKeyEnv: DEEPSEEK_API_KEY
        balanceUrl: https://api.deepseek.com/user/balance
        currency: CNY
      deepseek-go:
        kind: plan
        displayName: OpenCode Go
        apiKeyEnv: OPENCODEGO_API_KEY
        usageUrl: https://opencode.ai/zen/go/v1/usage
        rollingLabel: 5 小時

工作原理¶

刷新節奏¶

Host 半：每隔 cacheMs（默認 60 秒）向上遊採樣一次，填入緩存。
Client 半：每隔 POLL_MS（默認 60 秒）重讀快照，不直接打上游。
倒計時：重置倒計時每 30 秒重算一次，顯示精度爲分鐘。

界面上的數字最多比上游舊約 60 秒（包含一次請求耗時）。

技術實現¶

依賴：依賴 @deepseek-ai/dsh-client-ui-primitives 中的 React Hooks（如 useAnchoredPosition、useDismissOnOutsidePointer）來處理面板定位與關閉。
佈局修復：利用 CSS :has() 選擇器修改 conversation.composer.dock 的 display 屬性爲 flex，並使用 !important 覆蓋宿主的 display: contents。這允許插件行與統計行共享一行，同時保持輸入框卡片（width: 100%）不受影響。
數據計算：Host 端負責摺疊餘額序列，計算差值；Client 端僅負責渲染 Host 提供的結果。

注意事項¶

Node.js 版本：要求 Node.js >= 22。
許可證：MIT。
插件權限：插件以當前 DSH 進程的權限運行，安裝前建議檢查源碼。

結語¶

dsh-account-quota 插件提供了一個乾淨、準確且與現有 UI 融合良好的方式來監控賬戶餘額與用量。通過直接讀取上游 API 和基於差值的計算邏輯，它避免了本地統計可能帶來的數據偏差。