前言¶

在 DeepSeek Harness 中做多輪會話時，常見需求不只是得到模型輸出，還包括確認當前輪次和整個會話累計消耗了多少 token、按當前合同價格大致花費多少，以及是否接近設定的會話額度。

dsh-billing 針對這個場景提供本地計費、投影和 Web 界面展示。它適合在 DSH 開發或調試過程中查看費用參考值，但不是賬單系統，也不會自動阻止模型調用。

這是什麼¶

Wanbinyu/dsh-billing 是面向 DeepSeek Harness 的會話計費與額度插件，由 Wanbinyu 維護。這是一個獨立社區項目，不屬於 DeepSeek Harness 官方發行版。

它主要做三件事：

1. 按 provider/model 統計 token 費用。
2. 生成 billing session projection。
3. 在 Web composer dock 顯示本輪/會話費用、額度進度、未定價模型提示和模型明細。

費用是本地參考值，不是賬單，也不會自動阻止模型調用。

核心功能¶

dsh-billing 的能力集中在會話級計費和 Web 展示：

• 按 provider/model 統計 token 費用。
• 生成 billing session projection。
• 支持每會話額度。
• 在 Web composer dock 顯示本輪/會話費用、額度進度、未定價模型提示和模型明細。
• bundle 同時導出 host 與 Web client 入口。
• 價格優先使用配置，其次使用內置 USD 模型目錄。
• 相同模型 ID 在不同 provider 下會分開統計，例如 deepseek/deepseek-v4-flash 和 openrouter/deepseek-v4-flash。
• 額度達到 50%、80% 和 100% 時會逐級增強提示顏色。

host 側負責計價和 projection，瀏覽器側從 host 已計算的 projection 渲染界面。

安裝與啓用¶

作爲 bundle 安裝¶

倉庫 README 給出的安裝命令如下。這條命令安裝的是 v0.6.3 community bundle：

dsh plugin --profile web add https://github.com/Wanbinyu/dsh-billing/releases/download/v0.6.3/dsh-billing-community-bundle-0.6.3.tgz

安裝後重啓 dsh。

bundle 通過一個 billing 配置條目同時啓用 host projection 和 Web 費用條。價格優先使用配置，其次使用內置 USD 模型目錄。

手動安裝¶

如果宿主項目需要自己控制組合層，可以安裝兩個包：

npm install ./packages/dsh-billing ./packages/dsh-client-ui-billing

然後在 profile 的 cordis.patch.yml 中加入：

- insert:
    - id: billing
      name: dsh-billing
      config: {}
    - id: ui-billing
      name: dsh-client-ui-billing

這樣 host 側啓用 dsh-billing，Web 側啓用 dsh-client-ui-billing。

典型用法¶

配置價格與額度¶

配置價格時，優先使用精確的 provider/model。只寫模型 ID 仍然有效，並作爲所有 provider 的兼容回退。

示例配置如下：

- id: billing
  config:
    models:
      deepseek/deepseek-v4-flash:
        input: 1
        output: 2
        cacheRead: 0.02
        cacheWrite: 0
    currency: CNY
    quota:
      limit: 5

上面的價格只是文檔示例，實際價格按合同配置。

使用 CNY 或其他貨幣時，請爲每個模型顯式配置價格。沒有價格的模型仍會統計 token，但會進入 unpricedModels。它們不會僞造費用，quota.estimated 會變爲 true，表示額度進度只包含已知價格，不能當作完整賬單。

如果在 bundle 已插入後修改 billing 行，Harness 的 patch 會替換整段 config，因此需要保留所有希望繼續使用的配置字段。

查看投影結果¶

billing session projection 包含貨幣、總費用、分模型費用、token 明細、未定價模型和額度狀態。接口如下：

interface BillingProjection {
  currency: string
  totalCost: number
  models: {
    provider: string
    model: string
    cost: number
    uncachedInputTokens: number
    outputTokens: number
    cacheReadTokens: number
    cacheWriteTokens: number
  }[]
  unpricedModels: string[]
  latestTurn?: {
    turn: number
    cost: number
    uncachedInputTokens: number
    outputTokens: number
    cacheReadTokens: number
    cacheWriteTokens: number
    unpricedModels: string[]
  }
  quota?: {
    limit: number
    used: number
    remaining: number
    percent: number
    estimated: boolean
  }
}

latestTurn 在首次收到 usage 後出現，供客戶端顯示最近一輪的費用和 Token 明細。

投影會按 request/header 對 step 歸屬 usage。同一 (turn, step) 的後續樣本會同時替換會話累計和本輪數據中的早期樣本，避免重複計費。沒有前置 header 的 usage 會放入保留的 (unknown) bucket。

生成內置目錄與完整驗證¶

內置目錄只使用 USD，通過以下腳本從 pi-ai model catalog 生成：

node packages/dsh-billing/scripts/generate-catalog.mjs

運行完整驗證：

npm run build
npm run verify

適用場景與注意¶

適合以下場景：

• 需要在 DSH Web 會話中查看本輪和會話累計費用。
• 需要按 provider/model 查看 token 明細。
• 需要每會話額度進度提示。
• 需要在本地 DSH 項目中啓用計費與額度展示。

使用前需要明確以下限制：

• 這是獨立社區項目，不屬於 DeepSeek Harness 官方發行版。
• 費用是本地參考值，不是發票或強制限流依據。
• 額度不會自動阻止模型調用。
• quota 目前按 session 計算，部署級預算暫未實現。
• 兼容 DeepSeek Harness 0.1.0-rc.6 至 rc.8、0.1.1-rc.1 至 rc.2；開發依賴固定在 0.1.1-rc.2。
• package.json 要求 node >=22.19.0。
• 許可證爲 MIT。
• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。

結尾¶

dsh-billing 提供的是本地會話計費與額度視圖：它把費用、token 明細和額度進度放進 DSH Web 會話中，方便開發時查看和核對。使用時請把它當作本地參考值，而不是賬單或限流。

已覈實的公開入口：

• GitHub 倉庫：https://github.com/Wanbinyu/dsh-billing