前言¶
在 DSH（DeepSeek Harness）裏跑多輪對話和工具調用時，token 會分散在各會話裏；若只看模型側賬單或手工翻日誌，很難在同一視圖裏對齊「用了多少、大概花多少錢、宿主是否喫緊」。DSH 本身會維護會話投影緩存，但默認界面未必覆蓋預算水位和進程級 CPU 採樣。下面介紹的插件從這份緩存讀數，復刻官方「會話統計」工作臺排版，把 KPI、圖表和月度預算放在側欄單頁裏。
這是什麼¶
dsh-usage-stats 是社區維護的 DSH bundle 插件（維護者 Stopning，GitHub 倉庫 Stopning/dsh-usage-stats，SkillHub 分類爲 admin-security）。它不做原始日誌解析，而是統計 token 消耗、估算成本、會話數、緩存命中率，並展示 月度預算（鯨魚水位） 與 宿主進程運行狀態（CPU / 內存 / 事件循環 / 運行時長）。界面單頁滾動，無第三方運行時依賴；當前 package 版本爲 0.1.0，許可證 MIT。
核心功能¶
KPI 與時間範圍¶
頂部可選時間範圍（24h / 7d / 14d / 30d / all），下列卡片隨範圍聯動：
| 卡片 | 內容 |
|---|---|
| 總 Token 消耗 | 四類 token 合計，副標拆出未緩存輸入 / 輸出 |
| 預估成本 | 按模型目錄價折算的人民幣金額（可配置 currency），副標註明計價口徑 |
| 會話數 | 範圍內會話總量，副標給出平均每會話 token |
| 緩存命中率 | cacheRead / (cacheRead + uncached)，副標爲緩存讀取總量 |
DSH 運行狀態¶
每 5 秒採樣（與官方一致，CPU_HISTORY = 60 點覆蓋最近 5 分鐘）：單核 CPU 百分比、整機負載與核數、內存 RSS、V8 堆、事件循環延遲 p99 與均值、進程運行時長 / PID / Node 版本，以及最近 5 分鐘 CPU 柱狀圖。
圖表與會話排行¶
- 每日消耗：按 token 類型堆疊柱狀圖，右上角顯示範圍總量與金額。
- 模型花費：按模型列出金額與佔比條。
- 會話消耗排行：可切換「按 Token / 按花費 / 按耗時」。
- Token 構成：環形圖與四項明細（緩存讀取 / 未緩存輸入 / 緩存寫入 / 輸出）。
- 對話性能：平均每輪耗時、平均首字延遲（TTFT）、輸出速度（tok/s）、工具錯誤率（部分指標不隨頂部範圍變化，見下文限制）。
月度預算（鯨魚水位）¶
統計 固定爲當前自然月，不隨頂部時間範圍變化。點擊金額可就地編輯上限，回車保存、Esc 取消；剩餘比例 1 - 已用 / 上限 以「水位」展示，顏色從墨黑經綠、黃、橙到紅隨額度消耗變化。上限持久化在插件私有存儲，而非僅 profile 配置。
安裝與啓用¶
插件通過 DSH 的 bundle 機制安裝。對助手說「裝這個插件」，並給出倉庫來源（不要手改 profile 的 package.json 或 cordis.patch.yml，也不要手動拷進 node_modules，否則升級會丟）：
github:Stopning/dsh-usage-stats
本地開發時可指定路徑：
/path/to/dsh-usage-stats
底層等價於：
plugin_manager{ action: "install_bundle", target: "github:Stopning/dsh-usage-stats" }
裝好後側欄出現 「會話與用量」，位於「插件」與「自動化任務」之間。助手會走 bundle 安裝並自動排期重啓。
生效規則：
- 改
client.js→ 刷新頁面（revision 由 mtime + size 計算）。 - 改
index.js→ 重啓宿主；可排隊空閒重啓：~/.dsh/bin/dsh-restart-idle。
典型用法¶
在面板裏看數與改預算¶
- 打開側欄「會話與用量」，選擇頂部時間範圍查看 KPI 與圖表。
- 在「月度預算」區域點擊金額，輸入上限後回車保存；Esc 取消。
通過 HTTP 接口（需 DSH 認證 Cookie）¶
四條路由均爲 POST，返回 { ok: true, value: ... }：
| 路由 | 請求體 | 用途 |
|---|---|---|
/api/dsh-usage-stats/overview |
{ range?, currency? } |
KPI、每日消耗、模型花費、Token 構成、對話性能、月度預算 |
/api/dsh-usage-stats/sessions |
{ range?, limit?, currency? } |
會話列表（含按天明細） |
/api/dsh-usage-stats/budget |
{ amount } |
寫入預算上限 |
/api/dsh-usage-stats/cpu |
— | 一次宿主進程快照 |
示例：設置月度預算上限爲 100（將 <port> 換爲實際端口，dsh-auth-... 換爲有效 Cookie）：
curl -X POST http://127.0.0.1:<port>/api/dsh-usage-stats/budget \
-H 'Content-Type: application/json' \
-H 'Cookie: dsh-auth-...' \
-d '{"amount": 100}'
預算文件位置（供瞭解；直接改文件不生效，須走路由或面板編輯以同步宿主內存）：
~/.dsh/storages/dsh-usage-stats/budget.json
可選 profile 配置¶
在 profile 的插件配置裏可覆蓋（全部可選）：
budgetAmount: 100 # 被 budget.json 覆蓋
budgetPeriod: month # 目前只支持 month
defaultRange: 30d
refreshIntervalMs: 5000
topSessions: 200
currency: CNY
數據來源與計價說明¶
插件讀取 DSH 已維護的投影緩存：
| 數據 | 位置 / 通道 |
|---|---|
| 每會話 token、耗時、按天成本 | storageDomain → session_projcache → sessions 表 |
| 宿主進程指標 | node:os + node:perf_hooks，進程內採樣 |
按天成本由 contextActivity.days[date].cost 的四類 token 乘以價目表得到；價目表四級回退：模型定價 → 本渠道 provider → 跨渠道 proxied → 默認價（界面可能標「估算」）。成本換算在宿主完成，客戶端使用 cost.display。
適用場景與注意¶
適合誰：需要在 DSH 內長期跑 agent、希望一眼看到 token / 估算成本、自然月預算水位，並同時觀察宿主 CPU 與事件循環是否異常的開發者或運維。
權限與安全：插件以當前 DSH 宿主進程權限運行，會讀會話投影緩存並註冊 HTTP 路由；安裝前請閱讀 源碼與 MIT 許可證，確認符合你的部署策略。社區目錄 SkillHub 插件頁 與 DeepSeek / 幻方無官方從屬關係，DSH 生態理念是「一切皆插件」。
已知限制（README 原文）：
- 成本是估算，不是賬單；與實際扣費可能有出入。
- 多數渠道不上報
cacheWriteTokens，「緩存寫入」常爲 0。 - TTFT 與輸出速度只能取全會話累計值，不隨頂部範圍變化。
- 工具錯誤率粒度爲命令執行失敗 / 命令執行總數。
- 預算按自然月，無自定義起止日期。
結尾¶
dsh-usage-stats 把會話 token、估算成本、月度鯨魚水位和宿主 CPU 監控收進側欄單頁，數據來自 DSH 自帶的 session_projcache，安裝走 bundle、一行來源即可。進一步細節見倉庫 README 與 DESIGN.md。
