前言¶
在本地運行 DeepSeek Harness、Codex 或 OpenCode 時，追蹤 token 消耗是控制成本的關鍵。通常這些數據散落在本地日誌中，難以進行跨會話的彙總分析。本文介紹的工具通過讀取本地日誌，聚合三個來源的 token 數據，並提供可視化的看板與命令行工具，用於估算費用與監控緩存命中率。
什麼是 dsh-token-usage-observer¶
這是一個 DeepSeek Harness 插件，由維護者 RyzenWang 提供，遵循 MIT 許可證。它的核心作用是收集、彙總並展示本機 DeepSeek Harness、Codex (ChatGPT) 和 OpenCode 的 token 使用情況，包括緩存命中情況與預計費用，同時不修改任何原始數據。
核心功能¶
- 數據聚合與計算：插件會聚合三個來源的 token 用量（輸入、緩存命中、緩存寫入、輸出），並計算緩存命中率與預計費用。
- WebUI 側邊欄看板：安裝後，WebUI 側邊欄會出現「Token 統計」入口。看板支持按來源、時間段、分類與分組維度篩選，提供總量分佈圖表（堆疊條形圖）與逐會話明細列表。
- Agent 工具：提供
usage_stats工具，支持通過命令行顯式調用，並返回分組統計與明細表。 - 會話名稱解析：自動解析會話名稱（Harness 取
session/title，Codex 取thread_name，OpenCode 取session.title），缺失時使用會話 ID。 - 費用單價配置：支持配置每百萬 token 的費用單價，默認按 DeepSeek 公開價設置。
安裝與啓用¶
通過 dsh 插件命令安裝：
dsh plugin --profile web add "github:ZhengDaoWang/dsh-token-usage-observer"
安裝或更新後，需要重啓 dsh web，側邊欄「Token 統計」入口與看板纔會加載。
典型用法¶
安裝完成後，可以在對話中直接詢問：
- “統計我本機的 token 用量”
- “看看 codex 這週花了多少 token”
- “8 月 deepseek 模型的用量按天分組，並按公開價估算費用”
也可以通過工具名 usage_stats 顯式調用，支持的參數包括：
* source：數據來源（all, deepseek-harness, codex, opencode）
* from / to：起止日期（YYYY-MM-DD）
* category：分類篩選（模型 ID 或 preset 子串）
* groupBy：分組維度（source, category, day, none）
* prices：單價覆蓋對象
數據來源與配置¶
插件讀取本地日誌文件。費用單價默認值如下（每百萬 token）：
* 輸入：\(0.14
* 緩存命中：\)0.014
* 輸出：$0.28
數據來源位置包括：
* DeepSeek Harness：~/.dsh/sessions/<encoded-cwd>/session-<uuid>/session.jsonl[.zstd]
* Codex：~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
* OpenCode：~/.local/share/opencode/opencode.db
可以通過環境變量 DSH_HOME 或 CODEX_HOME 覆蓋 Harness 與 Codex 的日誌根目錄。插件對損壞或無法讀取的文件會靜默跳過。
注意事項¶
- 插件以只讀方式訪問本地日誌，不會修改任何數據。
- 安裝前建議檢查源碼與許可證。
總結¶
該工具通過讀取本地日誌，爲開發者提供了一個統一的視角來監控 DeepSeek Harness、Codex 和 OpenCode 的 token 消耗。結合 WebUI 看板與 Agent 工具，可以方便地進行成本估算與用量分析。
GitHub: https://github.com/RyzenWang/dsh-token-usage-observer
