前言¶

DeepSeek Harness（dsh web）目前沒有官方的用量或賬單 API，開發者很難追蹤實際扣費。dsh-usage-calendar 插件通過採樣餘額下降來計算實際扣費，並提供日曆視圖，聚合本機全部會話的 token 用量、緩存命中率等數據。

功能¶

餘額查詢
通過官方接口查詢賬戶餘額，1 秒緩存，界面每 1 秒自動刷新，支持手動強制刷新。

日曆視圖
按天聚合本機全部會話的 token 用量。活動會話走內存日誌，已存檔會話走 ctx.sessionQuery，因此歷史日期同樣完整。支持月份切換與“今天”。

每日實際扣費
DeepSeek 沒有用量/賬單 API，插件把每次餘額讀數採樣落盤，把餘額下降計爲扣費，按天彙總。這是平臺實際扣你的錢，不區分模型。

本地估算
按官方價目逐條估算，用於對照。

緩存命中率
計算 cacheRead / (input + cacheRead + cacheWrite)（提示詞側）。

本地統計
只讀本機會話事件日誌與餘額接口，不上傳任何數據。

安裝與啓用¶

使用 npx 安裝器：

npx --yes github:xiyi123465/dsh-usage-calendar

安裝器將包複製到 $DSH_HOME/profiles/node_modules/dsh-usage-calendar，並重啓 dsh web 後生效。

典型用法¶

1. 點擊日曆面板查看歷史日期的詳細用量（活動會話走內存日誌，已存檔會話走 ctx.sessionQuery）。
2. 點擊餘額膠囊手動強制刷新余額。
3. 使用 --local-only 選項僅統計本機 key 的用量。
4. 使用 node scripts/import-actual.mjs 回填歷史數據。
5. 通過 llm-deepseek 設置命名空間配置 API Key。

注意事項¶

1. 扣費計算方式：DeepSeek 沒有用量/賬單 API，扣費通過採樣餘額下降計算。
2. 數據精度：金額用整數分累加，不隨摺疊漂移。
3. 隱私安全：只讀本機會話事件日誌與餘額接口，不上傳任何數據。
4. 對賬警告：已實測的日子若與本地估算相差 >1.5× 時標警告。
5. 結算延遲：服務端結算有延遲，跨午夜的調用可能記在後一天。

總結¶

dsh-usage-calendar 通過餘額採樣和本地日誌聚合，解決了 DeepSeek 官方無用量 API 的問題，提供了可視化的日曆視圖用於成本追蹤。