前言¶
在 DeepSeek Harness（DSH）裏跑智能體，token 會分散在多段會話、多種模型和緩存讀寫路徑裏。單靠印象或廠商賬單，很難對照「哪幾次調用花了多少、預算還剩多少」。社區維護者 xkzdwb 的 DSH-UsageStats-WhenNeedOverview（包名 dsh-usage-stats）在 DSH Web UI 側邊欄增加用量統計入口，把 harness 寫入會話日誌的 usage 折成 KPI、時間線和單會話明細，並按你在配置裏填的單價重算費用。數字來自 ~/.dsh/sessions/**/session.v4.jsonl.zstd，不是面板內估算；Host 與 Client 分別只用 Node 內置模塊和瀏覽器已有的 react，沒有額外 npm 依賴。
這是什麼¶
- 倉庫與目錄：GitHub，SkillHub 分類爲客戶端插件。
- 維護者：xkzdwb。
- 版本與許可（資料原文）：
1.0.0，MIT；要求 Node>=20。 - 定位：給 DSH Web UI 加用量統計面板；另提供只讀 JSON 路由，便於 curl 或自建監控對接。
裝好後側邊欄在「插件」「定時」之後多一個柱狀圖標，點開主欄即儀表盤。面板每 5 秒輪詢（CPU 走勢依賴此間隔）；點「刷新」會強制重讀全部會話日誌。
面板能力¶
下面按 README 中的區塊說明（時間範圍按鈕：全部 / 24h / 7d / 30d 隻影響面板顯示；預算 KPI 始終按 budgetPeriod 計算，不受範圍按鈕影響）。
| 區塊 | 內容 |
|---|---|
| 四個 KPI | 總 token（含輸入/輸出/緩存拆分）、會話數、模型調用次數、預估費用；第四格爲預算進度 |
| Token 用量時間線 | 按小時堆疊柱（跨度超過 7 天按天）；緩存讀取 / 輸入 / 輸出；綠線爲每桶費用 |
| 按模型 | 每個 provider/model 的調用數、token、費用、相對花費條 |
| CPU 活動 | 進程與系統 CPU、進程內存、運行時長，約 90 個採樣點的走勢 |
| 會話明細 | 每會話調用數、token、費用、最後活動時間；可搜索、排序 |
面板右上角語言：自動 / 中文 / EN（默認跟隨 Harness 或瀏覽器；選擇寫入 localStorage 的 dsh-usage-stats:lang，僅影響本面板渲染，不重新拉數）。
數據從哪來、怎麼計費¶
Harness 每輪把 assistant/message 事件的 usage 寫入會話日誌。Host 側通過 sessionQuery 列出並讀取會話，從 data.usage 取 inputTokens、outputTokens 及可選的 cacheReadTokens、cacheWriteTokens 等，用 data.message.source 的 provider/model 分組。
兩點實現上容易寫錯、README 也單獨強調：
- 總 token 含緩存讀寫，計費必須四類 token 各乘各自單價，不能用
totalTokens乘單一價。 - 中間結果只存 token 計數、不存費用；改
pricing後歷史會按新價立即重算，無需清緩存。非 live 會話在cacheTtlMs內可只折一次；live 會話刷新會重讀。
對外只讀路由：
GET /plugin-usage-stats/data?days=0&refresh=0
僅 GET/HEAD；響應 cache-control: no-store，不含消息正文。?refresh=1 強制重讀日誌；?days=7 限制最近天數（0 表示全部）。
安裝與啓用¶
插件以 bundle 包形態發佈：package.json 的 dsh.bundle.patch 指向自帶 cordis.patch.yml。要同時出現側邊欄與主欄面板，需把包列入 profile 的 bundles（方式 A）；僅插 Host 入口（方式 B）則只有 JSON 路由、沒有 Web 界面。
方式 0：從 GitHub 安裝（資料原文命令）¶
dsh plugin add github:xkzdwb/DSH-UsageStats-WhenNeedOverview
裝完重啓 DSH。Host 日誌中應出現：
[usage-stats] serving GET /plugin-usage-stats/data
方式 A：作爲 bundle 鏈進 profile（推薦，含 UI）¶
在 ~/.dsh/profiles/<profile>/package.json 增加依賴並把 dsh-usage-stats 放進 dsh.profile.bundles，且排在 @deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app 之後（依賴其 webServer 與 sessionQuery）。本地開發可用 link: 指向倉庫絕對路徑。改配置後同樣需重啓 DSH。
驗證路由¶
將 <DSH 的端口> 換成本機 Web 端口後執行：
curl -i http://127.0.0.1:<DSH 的端口>/plugin-usage-stats/data
期望：200、content-type: application/json、cache-control: no-store，正文爲計數字段。
配置項¶
配置寫在 patch 的 config: 下（完整字段見倉庫 cordis.patch.yml）。價格單位爲每 100 萬 token。
| 字段 | 默認 | 說明 |
|---|---|---|
currency |
CNY |
幣種符號或「數字 + 代碼」 |
budget |
200 |
預算；0 只顯示花費 |
budgetPeriod |
month |
month 本自然月；all 全部歷史 |
cacheTtlMs |
30000 |
摺疊緩存有效期 |
cpuSampleIntervalMs |
2000 |
CPU 採樣間隔（500–60000） |
cpuHistoryLength |
90 |
走勢採樣點數（10–600） |
maxSessions |
2000 |
最多統計會話數 |
maxConversations |
300 |
明細條數上限，按花費降序 |
pricing.default / pricing.models |
見 README | 按 provider/model 覆蓋單價 |
pricing.default 中的數值在文檔中標明爲佔位，需按你的實付價或官方價表填寫。不確定模型鍵名時，可先請求 GET /plugin-usage-stats/data?days=0，用返回裏 byModel[].key 對照填寫 pricing.models。
示例形狀：
pricing:
default:
input: 2
output: 8
cacheRead: 0.5
cacheWrite: 2
models:
some-provider/some-model:
input: 1
output: 4
cacheRead: 0.25
cacheWrite: 1
典型用法¶
- 日常看板：重啓 DSH 後從側邊欄打開面板，用 24h / 7d 等按鈕切換視圖，用「刷新」對齊最新日誌。
- 腳本拉快照：用 curl 訪問
/plugin-usage-stats/data，必要時加refresh=1或days參數。 - 改價後復盤：只改 patch 裏
pricing，無需清緩存，歷史費用按新價重算。 - 離線自測（不必安裝 DSH）：在倉庫目錄執行
node test/run-tests.mjs（不讀~/.dsh、不聯網）；資產檢查可執行node tools/check-assets.mjs。
適用場景與注意¶
適合：已在 DSH Web UI 里長期使用、需要對照真實會話日誌看 token、費用、預算和 CPU 的開發者。
排錯摘要（來自 README）：
- 側邊欄無圖標：未按方式 A 裝入
bundles（缺dsh.client則只有路由）；或未重啓。 - 面板空轉：確認 Host 日誌有
serving GET /plugin-usage-stats/data，且 profile 包含提供webServer的官方 Web bundle。 - 費用異常：檢查
pricing佔位價與byModel[].key是否匹配。 - 數字滯後：點「刷新」或
?refresh=1；非 live 會話受cacheTtlMs影響。
邊界：時間線按 UTC 整點分桶；預算週期僅「本自然月」與「全部」；會話數含子代理會話；金額宿主側四捨五入到 4 位小數。
安全與信任：插件隨當前 DSH 進程權限讀取 ~/.dsh 下會話日誌並註冊 HTTP 路由。安裝前請自行審閱 倉庫源碼 與 MIT 許可證。DSH 社區插件目錄（如 SkillHub）爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
DSH-UsageStats-WhenNeedOverview 把 harness 已落盤的 usage 轉成可讀的 Web 面板與一條只讀 JSON API，費用由配置價驅動、改價即可重算曆史。需要入口與細節時，可查閱 SkillHub 目錄頁 與 GitHub 倉庫。
