前言¶
DeepSeek Harness (DSH) 的理念是“一切皆插件”。在使用 DSH 進行智能體開發或運行時，追蹤 API 調用的實際成本是一個常見需求。通常的日誌記錄往往不夠精確，或者依賴估算，容易導致計費偏差。
爲了解決這個問題，需要一種機制，能夠將使用情況報告轉換爲可引用的、僅追加的 JSONL 費用收據。dsh-spend-receipt 插件正是爲此設計，它解決了傳統計費方式中缺乏透明度和浮點數精度問題。
插件簡介¶
這是一個 DeepSeek Harness 函數插件，由用戶 jwilson411 維護。它的核心作用是將 Harness 的使用情況報告轉化爲一個可引用的、僅追加的 JSONL 費用收據，並提供一個 spend_receipt 工具來讀取回這些數據（包括最後 N 行、總計和緩存命中率）。
核心功能¶
該插件主要解決以下問題：
-
可驗證的計費記錄
每一條記錄都包含實際報告的 token 數、定價信息、時間窗口以及來源。閱讀者可以獨立重新計算成本，無需信任此包。它不進行任何文本分詞或估算，缺失的定價不會填補爲零，而是記錄爲usd: null。 -
僅追加的 JSONL 格式
收據文件採用 JSONL 格式，且只追加不修改。即使發生崩潰，也不會導致數據損壞。 -
精確的定價與計算
使用nano_usd整數進行總計計算，避免浮點漂移。定價基於 2026-08-29 的 DeepSeek 公開價格表，並區分高峯（Peak）和低谷（Off-peak）窗口。 -
會話日誌同步
支持從會話日誌同步使用情況，讀取 JSONL 日誌並提取其中的 usage 事件。
安裝與配置¶
在安裝之前，請確保環境滿足依賴要求：Node.js >= 22.14.0。
1. 安裝插件
執行以下命令將插件添加到 web 配置文件中：
dsh plugin --profile web add github:jwilson411/dsh-spend-receipt
dsh plugin 命令會將插件包 manifest 中的 dsh.bundle.patch 追加到配置中，並應用 cordis.patch.yml 層。
2. 配置插件
插件需要在 cordis.patch.yml 中進行配置。注意，目標配置項（id: spend-receipt）會替換整行配置，因此需要重新聲明所有需要保留的字段。
- id: spend-receipt
config:
receiptPath: ~/.dsh/spend-receipt.jsonl
sessionLog: ~/.dsh/sessions/current.jsonl
| 配置項 | 環境變量回退 | 默認值 |
|---|---|---|
receiptPath |
DSH_SPEND_RECEIPT_PATH |
./spend-receipt.jsonl |
sessionLog |
DSH_SPEND_RECEIPT_SESSION_LOG |
未設置（僅讀模式） |
sessionId |
DSH_SPEND_RECEIPT_SESSION_ID |
未設置（行記錄 null） |
limit |
— | 20 |
使用方法¶
安裝並配置完成後，可以通過 spend_receipt 工具來查看費用收據。
1. 基本用法
該工具支持兩個參數：
* limit：返回最近 N 條記錄，默認爲配置的 limit。
* sync：是否先掃描會話日誌同步新數據，默認爲 true。設爲 false 則僅報告已記錄的數據。
2. 示例輸出
工具會返回收據路徑、使用的費率表、具體行數據、總計以及緩存命中率。示例 JSONL 記錄如下：
{
"ts": "2026-08-29T09:00:12.000Z",
"session_id": "sess-7c2",
"model": "deepseek-v4-pro",
"input_tokens": 12000,
"cache_hit_tokens": 9000,
"output_tokens": 800,
"usd": 0.007524,
"currency": "USD",
"nano_usd": 7524000,
"rate_table": "deepseek-v4@2026-08-29",
"rate_tier": "peak",
"ts_source": "event",
"source": { "kind": "session-log", "path": "…/session.jsonl", "line": 3 }
}
適用場景與注意¶
適用場景：
* 需要精確覈算成本的開發者和團隊。
* 需要審計 API 調用詳情和緩存命中率的場景。
* 希望避免浮點數計算誤差的財務統計。
注意事項：
* 依賴版本：插件依賴 @deepseek-ai/cordis (^4.0.1) 和 @deepseek-ai/dsh-tools (^0.1.1-rc.2)。
* 定價邏輯：定價基於 2026-08-29 的價格表。高峯窗口爲 UTC 01:00-04:00 和 06:00-10:00（週一至週五），其他時間爲低谷期。定價依賴模型名稱、緩存分割或時間戳，缺失任一條件將導致無法定價。
* 權限與安全：插件以 DSH 進程的權限運行。在安裝前，建議檢查源碼和許可證（MIT）。
結語¶
dsh-spend-receipt 插件爲 DeepSeek Harness 提供了一個透明、可驗證的費用追蹤方案。通過將使用情況記錄爲僅追加的 JSONL 文件，並利用整數運算保證精度，它能夠有效解決成本估算不準確的痛點。
插件詳情與源碼可參考：GitHub
