前言¶
在 DeepSeek Harness（DSH）這類「一切皆插件」的宿主裏，模型調用通常會持續產生輸入、輸出、緩存讀寫等 Token 消耗。只看單條 usage 往往不夠：還需要知道一個會話花了多少、今天花了多少、是否接近預算，以及官方調價後費用是否仍然準確。
dsh-usage-ledger 是 beijingwahw 維護的一個 DSH 插件，用於統計 Token / 用量、折算費用、控制預算，並提供 Web 儀表盤。它會監聽 session/event，把每次 assistant/message 的 usage 折算爲費用，並按會話、北京日、生命週期聚合持久化。
定位¶
dsh-usage-ledger 是一個面向 DSH 的 Token / 用量統計與成本控制插件：按對話聚合消耗、動態跟隨官方定價、支持預算攔截，並內置 Web 儀表盤。
維護者爲 beijingwahw，許可證爲 MIT。
核心功能¶
按會話統計¶
插件監聽 session/event，將每次 assistant/message 的 usage 折算爲費用，並按三個維度聚合持久化：
- 按會話
- 按北京日
- 按生命週期
動態官方定價¶
插件會定期抓取官方定價頁，自動解析並熱更新價格。官方調價後，價格可以隨抓取結果更新，不需要手工修改插件代碼。
DeepSeek 峯谷分時¶
插件會識別官方高峯 / 空閒時段表與生效日期，並按調用發生的北京時間即時取價。
多廠商價格目錄¶
插件覆蓋多個廠商的價格目錄，包括：
- DeepSeek
- 智譜 GLM
- 月之暗面 Kimi
- 阿里通義
- 字節豆包
- MiniMax
- 百度文心等
預算控制¶
插件支持三級預算：
- 日預算
- 總預算
- 單會話預算
達到閾值時會進入告警狀態；超預算時可通過 llm/stream 鉤子攔截模型調用。
預算值設置 0 表示關閉對應預算。
Web 儀表盤¶
插件通過 dsh-host-webserver 註冊 /usage-ledger 路由，提供用量可視化與 JSON API。
用戶覆蓋價¶
customPrices 可按模型 id 覆蓋或補充價格，優先級最高。
安裝與啓用¶
先安裝插件：
dsh plugin add beijingwahw/dsh-usage-ledger --profile web
安裝後，Harness 會通過 dsh.plugin.json 與 cordis.patch.yml 自動加載插件。lib/ 隨倉庫分發，無需本地構建。
接着在 Harness 的 cordis.yml 中配置插件。已覈實資料給出的配置項包括：
ledgerPathsaveIntervalMspricingTimeoutMs
典型用法¶
設置自定義價格¶
當需要爲某個模型設置覆蓋價或補充價時，可以配置 customPrices。價格單位爲元 / 百萬 tokens。
示例：
{"glm-4.6": {"inputCacheHit": 1, "inputMiss": 5, "output": 5}}
查看用量報表¶
可以使用工具 usage_report，輸出當前用量、費用和預算狀態報表。
訪問儀表盤和 JSON API¶
訪問儀表盤頁面：
GET /usage-ledger
訪問 JSON API：
GET /usage-ledger/api/...
預算與失敗處理¶
插件的預算控制支持日、總、單會話三級預算。達到閾值後進入告警狀態；超預算時可通過 llm/stream 鉤子攔截模型調用。
定價抓取失敗時，插件會沿用上一次成功價格，因此網絡異常不影響記賬。
適用場景與注意¶
適合以下場景：
- 需要按會話、按北京日、按生命週期查看 Token 消耗
- 需要把模型調用折算成費用
- 需要爲日、總、單會話設置預算
- 需要在超預算時攔截模型調用
- 需要通過 Web 儀表盤查看用量和 JSON API
注意：插件以當前 dsh 進程權限運行，會註冊工具與路由，並定期抓取官方定價頁。安裝前應檢查源碼與許可證。該插件許可證爲 MIT。
鏈接¶
已確認的源碼地址：
https://github.com/beijingwahw/dsh-usage-ledger
