前言¶

DeepSeek Harness (DSH) 採用插件化架構，支持 Web GUI。在開發或使用 DSH 時，開發者常需要精確掌握 API 調用的成本，包括單次會話的實時花費、分項詳情以及賬戶餘額。現有的 Web 界面缺乏這類細粒度的計費展示，這會導致成本預估困難。dsh-token-billing 插件通過在會話標題欄掛載投影和徽標，解決了這一問題，它將算錢邏輯下沉到 Host 進程，顯示端僅負責展示，從而在不觸碰密鑰的前提下提供可視化的計費與餘額查詢能力。

插件介紹¶

mrtomtao/dsh-token-billing 是一個爲 DeepSeek Harness Web GUI 設計的會話 token 計費插件。

該插件通過 Host 半註冊 tokenBilling 投影來計算費用並查詢餘額，瀏覽器半則通過只讀路由讀取數據並渲染 UI。它不依賴任何聯網抓取，價格數據直接來自官方文檔，且完全在不觸碰 DeepSeek API Key 的前提下運行。

安裝與啓用¶

安裝前請確保環境滿足要求：DSH（Web / web profile）、Node 22+、以及已安裝並在 PATH 中的 pnpm。

從 GitHub 安裝¶

這是最省事的安裝方式，插件會作爲依賴裝進 profile，且 profile 不會記錄文件路徑。

dsh plugin --profile web add github:<you>/dsh-token-billing

從 Release 安裝¶

適用於需要校驗或離線部署的場景。

dsh plugin --profile web add ./dsh-token-billing-0.2.3.tgz

從目錄安裝¶

用於本地開發調試。

dsh plugin --profile web add C:\path\to\dsh-token-billing

驗證與重啓¶

安裝後可以通過以下命令驗證掛載情況：

# 查看組合層，應能看到 # == dsh-token-billing
dsh --profile web --dump-config

# 驗證掛載且不綁定端口
dsh --profile web --help

重啓 DSH Web profile 後，打開任意會話，標題欄右側將出現花費與餘額徽標。

核心功能¶

• 實時計費徽標：在會話標題欄顯示本次會話的實時花費。尚未產生記錄時顯示 ¥--，產生後立即更新。
• 分項詳情：點擊花費徽標（28px 官方頭部控件規格），會彈出對話框，展示輸入、緩存命中、緩存寫入、輸出、推理的分項明細。
• 模型賬單：展示按模型的 Token 統計與總費用。
• 時段價展示：顯示當前使用的是高峯時段還是空閒時段，並提供一鍵切換。
• 餘額查詢：顯示賬戶餘額徽標。點擊可查看充值餘額、贈送餘額及總額。餘額查詢由 Host 半執行，瀏覽器半僅調用本地路由。

計費邏輯¶

插件內置了完整的計費邏輯，基於官方價目表進行計算。

價格來源¶

價格數據直接取自官方文檔的原文，不進行聯網抓取。支持人民幣和美元兩種幣種，且幣種在面板內可一鍵切換。

高峯與空閒時段¶

高峯判定基於 Token 的實際發生時間：
* 高峯時段：週一至週五 09:00–12:00、14:00–18:00（北京時間）。
* 空閒時段：除高峯外的所有時間。
空閒時段的單價爲高峯價的 0.5 倍。

分桶統計¶

插件將 Token 統計爲四個互不重疊的桶：
1. 輸入 · 未命中緩存
2. 輸入 · 緩存命中
3. 緩存寫入
4. 輸出（推理包含在輸出內）

注意：緩存寫入按未命中輸入價計費，因爲官方不單獨收取此項費用。

重試與未定價模型¶

• 重試邏輯：與 DSH 的 tokenUsage 投影一致，同一輪對話的重試上報採用替換而非累加策略，確保徽標顯示的 Token 數與 GUI 原生面板一致。
• 未定價模型：對於未在官方價目表中列出的模型，插件會按 deepseek-flash 的價格進行估算，並在明細中打上「估算」標籤。

餘額查詢¶

餘額顯示採用“Host 計算，瀏覽器顯示”的架構。

數據流向¶

• Host 半：負責向 DeepSeek 平臺發起查詢。查詢順序爲：優先查詢已登錄的 DeepSeek 賬號餘額（充值+贈送），其次查詢 API Key 對應的賬戶餘額。
• 瀏覽器半：不直接請求 DeepSeek 接口，而是調用 Host 提供的同源只讀路由 GET /token-billing/balance 獲取數字。

緩存策略¶

爲了減少請求頻率，餘額查詢結果會被緩存：
* 成功結果緩存 60 秒。
* 失敗結果緩存 15 秒。

禁用餘額查詢¶

如果不需要餘額顯示，可以在配置中關閉餘額查詢功能，此時 Host 半將不發起請求，瀏覽器半也會隱藏餘額徽標。

配置與注意事項¶

手工安裝¶

如果不使用 bundle 機制，可以在 profile 的 cordis.patch.yml 中手工添加：

- insert:
    - id: token-billing
      name: dsh-token-billing

價格配置¶

價格支持通過組合配置覆蓋，無需修改代碼。在 cordis.patch.yml 中覆蓋 config.prices 即可：

- id: token-billing
  config:
    prices:
      CNY:
        deepseek-flash: { hit: 0.04, miss: 2, output: 8 }
        deepseek-v4-pro: { hit: 0.3, miss: 9, output: 27 }

關鍵注意事項¶

1. lib/ 文件夾必須提交：由於 pnpm 默認拒絕執行 git 依賴的構建腳本（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED），插件無法在安裝時現場編譯。倉庫必須將編譯好的 lib/index.js 和 lib/client.js 提交進去，以支持 git 安裝。
2. 安裝 tarball 後不要刪除：Profile 記住的是文件的路徑，文件丟失會導致後續命令報 ENOENT。
3. 目錄安裝需要 node_modules：從目錄安裝時，插件目錄內必須有 node_modules（包含 zod），否則會導致插件導入失敗。

結語¶

dsh-token-billing 通過插件化的方式爲 DeepSeek Harness Web GUI 填補了計費與餘額監控的空白。它利用 DSH 的投影機制實現了精確的費用分項展示，同時通過本地路由避免了跨域和密鑰泄露的風險。對於需要精細控制 API 成本的用戶，這是一個直接可用的工具。

• 插件目錄
• GitHub 倉庫