前言¶
DSH（DeepSeek Harness）Web profile 會把每次會話的日誌落盤，但自帶的界面只告訴你對話內容，不會彙總“這次跑了多少 token、緩存命中了多少、這個月用了多少”。想自己統計，只能在日誌裏手動翻 assistant/message 的 usage，費時且口徑不一。
下面介紹的插件 genius-alray/dsh-plugin-session-token-stats 解決這個問題：它直接讀取真實的會話日誌，生成一個 Token 用量看板，包含總量、按月用量、緩存命中率、每日時間線，以及按會話分層明細。由 genius-alray 維護，屬於客戶端分類，以 MIT 許可證發佈。
它只統計 token，不顯示成本或預算。原因是這些會話沒有可靠的計費 API，作者的選擇是不要把猜測當成事實呈現。
一、它展示什麼¶
插件接管後，左側邊欄底部會出現一個柱狀圖入口 Token stats。打開後是一個面板，分四塊。
1、彙總卡片¶
顯示總量 token（拆成未緩存輸入 / 命中緩存的輸入 / 輸出）、會話數（回合數，以及合併進來的子代理會話數）、本月已用 token，以及整體緩存命中率。
2、Token 時間線¶
最近 7 / 30 / 90 天的每日堆疊柱狀圖，三類分別是未緩存輸入、命中緩存輸入、輸出。鼠標懸停在柱子上可以看到當天精確數字。時間範圍是瀏覽器側的設置項。
3、按會話用量¶
每個主會話一行，按最新排序。子代理會話會被合併到派生它的那個會話裏，不會單獨列出一行。選中一行展開，可以看到按模型拆分的用量、合併進來的子代理數量、創建與最近活動時間戳，以及 session id。
4、CPU 與內存¶
面板右側列出系統級指標：CPU 使用率（120 秒的迷你折線）、1/5/15 分鐘負載均值、DSH 進程的 CPU 和 RSS、系統內存、核心數、進程運行時長，以及主機標識。
二、計數口徑¶
Host 端通過 ctx.sessionQuery.listSessions() / readSession(id) 讀取持久化會話日誌，逐條統計 assistant/message 裏的 usage，字段口徑如下：
| 字段 | 對應來源 |
|---|---|
| 未緩存輸入 | usage.inputTokens（DeepSeek 在此字段中不包含緩存命中部分） |
| 命中緩存 | usage.cacheReadTokens |
| 輸出 | usage.outputTokens |
| 總量 | 未緩存 + 命中緩存 + 輸出（若 provider 提供了 cacheWriteTokens 則再加） |
| 緩存命中率 | 命中緩存 ÷（未緩存 + 命中緩存） |
爲了讓這些數字可信，插件做了兩條去重規則：
- Fork / 繼承會話：日誌開頭是複製自父會話的一段前綴，那段用量已經在父會話裏計過了。只統計
inheritedEventCount之後的事件（最新的session/title仍從整條日誌讀取）。 - 子代理會話：
header.parentSession指出派生會話，順着這條鏈把子代理會話歸併到最頂層的主會話，合併成一行。
持久化會話是不可變的，所以每條日誌只讀一次並緩存；活躍會話則在每次刷新時重新讀取。首次打開會解壓並對所有日誌做回放校驗（500+ 條日誌大約 10–20 秒），期間以 { done, total } 彙報進度並快速輪詢；之後再刷新只重讀正在運行的會話。
三、安裝與啓用¶
插件是一個標準的 dsh bundle：註冊一行 Host 和一行 Client，不覆蓋任何內置組件。
UI 安裝¶
在 Plugins → Add plugin → Install third-party plugin 中粘貼（該字段也支持本地目錄或 Git URL）：
dsh-plugin-session-token-stats
CLI 安裝¶
# 本地檢出（開發場景）
dsh plugin --profile web add /absolute/path/to/dsh-plugins/session-token-stats
# 或直接取該倉庫
dsh plugin --profile web add https://github.com/genius-alray/dsh-plugin-session-token-stats
安裝完成後刷新頁面，左側邊欄底部會出現柱狀圖入口 Token stats。
四、接口與數據¶
插件註冊了兩個同源 Host 路由，都經過 Connection 服務做 owner 鑑權（未認證返回 401；缺少 Connection 服務返回 403，fail-closed）：
GET /session-token-stats/data：總量、每日分桶、按會話聚合結果、掃描進度。GET /session-token-stats/live：CPU / 負載 / 內存採樣環形緩衝區（1 Hz，保留最近 120 個樣本）。
Host 端的邏輯集中在 server.js：日誌摺疊、子代理歸併、CPU 採樣和兩個 JSON 路由；Client 端在 client.js：主面板、邊欄入口、時間線、表格與設置。多語言元數據放在 locale/*.json，cordis.patch.yml 只插入本插件的 Host 行。
五、運行與驗證¶
依賴很簡單，只需要一個 DeepSeek Harness Web profile，且 dsh >= 0.2.1-rc.2；Host 端的 sessionQuery、webServer、connection 三個服務在出廠的 Web profile 中都已存在。
在本地檢出裏跑自檢和測試（測試使用 node:test，不需要第三方依賴）：
npm run check # 對 server.js 和 client.js 各做一次 node --check
npm test # node --test tests/
Host 測試通過假的 Cordis 上下文驅動 apply()，用合成語料覆蓋用量摺疊、波峯/波谷分桶、繼承前綴排除、子代理歸併、掃描緩存和路由鑑權；Client 測試用 stub module loader 加載瀏覽器 bundle，覆蓋 token 格式化、緩存命中率、時間線補零、瀏覽器側偏好和字典一致性。
六、適用場景與注意事項¶
適合需要長期跟蹤會話 Token 消耗、關注緩存命中率，或想確認本地 DSH 進程資源佔用的開發者。如果只是偶爾查一句話的用量，直接翻日誌成本更低。
幾個要注意的點：
- 插件以當前 dsh 進程的權限運行。它可以讀取本機的會話日誌與系統指標，安裝前應先查看源碼，確認 trust 邊界符合預期。許可證爲 MIT。
- 500+ 條日誌的首次掃描需要幾秒（解壓 + 回放校驗），之後的刷新只重讀運行中的會話。
- 時間線保留 120 天。更早的用量仍會出現在會話行和總量裏，但不會進入每日圖表。
- 當父會話已不在本地語料中（歸檔或清理），其子代理會話會各自成爲一行頂層記錄。
- 標題跟隨最新的
session/title事件；老日誌沒有該事件時，回退到第一條用戶消息。 - 不顯示成本/預算是設計決定。要自己計價，就用插件給出的 token 拆分去算。
七、小結¶
這個插件的價值在於把 DSH 已落盤的會話日誌轉換成一個口徑明確、可覈對的用量面板：總量、緩存命中率、按月趨勢、按會話分層，外加進程級資源監控，同時刻意不做成本估算。安裝是一個 bundle + 一行命令，Host 端做了繼承前綴去重與子代理歸併，保證統計結果可信。
目錄頁：https://www.skillhub.cn/plugins/genius-alray/dsh-plugin-session-token-stats
GitHub：https://github.com/genius-alray/dsh-plugin-session-token-stats
