DeepSeek Harness (dsh) 的設計理念是“一切皆插件”。在開發或使用 dsh 過程中，開發者常需要快速瞭解會話的 Token 使用量、首字生成時延（TTFT）、吞吐量（TPS）以及估算成本。dsh-tokstat 是一個由 kongjianguan 維護的插件，它直接讀取本地的會話日誌，提供兩種形態的統計面板：Web 設置頁插件和 Python TUI 儀表盤。
核心能力¶
插件通過 zstd 幀級增量解析還原指標，將散落在 ~/.dsh/sessions/ 下的日誌轉化爲可分析的數據：
- 實時面板：提供兩種形態。一種是 Web 設置頁插件，在 dsh Web 設置頁增加「統計」section，每 2 秒輪詢更新；另一種是獨立 Python TUI，提供 7 個視圖的終端儀表盤。
- 多維視圖：支持 切換 7 個視圖，包括總覽（Hero 卡 + 火花線）、趨勢（按小時/天柱狀圖）、模型/供應商、會話、請求、錯誤。
- 詳細指標：還原輸入/輸出/緩存 Tokens、TTFT（首 token 時延）、TPS、耗時、重試與失敗、估算成本。支持按每小時/天統計，支持點擊表頭排序。
- 錯誤分析：支持重試原因分佈（TRANSPORT/SERVER/TIMEOUT 等）及逐條重試事件、失敗步驟的查看。
安裝與啓用¶
在 dsh 中安裝插件到指定 profile（例如 web-dev）：
dsh plugin --profile web-dev add https://github.com/kongjianguan/dsh-tokstat.git
安裝後啓動 dsh Web：
dsh --profile web-dev --port 3199
打開瀏覽器訪問 http://127.0.0.1:3199/，進入 設置 → 統計 即可看到面板。
使用方式¶
Web 設置頁插件¶
插件通過 dsh 進程內的 Node half 通過 sessionPersistence 讀取會話日誌並聚合，提供 /tokstat/stats 接口。面板無需額外服務，直接展示聚合後的統計信息。
Python TUI 運行¶
在倉庫根目錄下運行：
./run.sh # 默認範圍：全部
./run.sh --range today # 只看今日
TUI 快捷鍵：
o t m p s r e：切換 總覽/趨勢/模型/供應商/會話/請求/錯誤 視圖。1 2 3 4：切換時間範圍（全部/今日/近7天/近30天）。f：聚焦請求日誌過濾框（Esc退出）。space：暫停 / 繼續自動刷新。
配置價格表¶
通過 YAML 文件配置各模型的價格（每百萬 Token）：
./run.sh --prices PATH
注意事項¶
- 版本兼容性：數據格式基於 dsh 0.1.0-rc.6 的會話日誌結構驗證。插件形態需要 Node ≥ 23.6；TUI 需要 Python 3.11+。
- 權限與安全：插件全程只讀，僅讀取
~/.dsh/sessions/下的session.jsonl.zstd與~/.dsh/settings.yaml，不修改任何 dsh 數據。TUI 全程離線運行，不聯網，無遙測，不會讀取或上傳 API 密鑰。 - 敏感數據：會話日誌包含對話內容，請勿將包含敏感對話的
~/.dsh目錄提交到任何倉庫。 - 指標口徑：TTFT 定義含排隊/思考時間，長尾明顯，請以 p50/p95 爲準。部分會話的持久化日誌只有批量 chunk，TTFT 爲近似值（誤差 <10%）。
- 成本說明：成本爲估算，中轉渠道價格需在
prices.yaml中自行配置。
