前言¶

在 DeepSeek Harness（DSH）裏跑多會話、多模型調用時，token 會分散在會話日誌、底層 llm/stream 和開放平臺賬戶賬單裏，口徑並不相同。若只看某一側，容易把輔助調用漏算，或把其他客戶端上的消費誤當成「本機用量」。下面介紹的 dsh-usage-monitor 是社區插件，由 Dekurri 維護，在 DSH 左側欄提供一個本地儀表盤：彙總 token、成本估算、緩存命中率、分模型與會話明細，並採樣本機 CPU/GPU/內存，同時支持與 DeepSeek 開放平臺賬單對賬。數據默認只在本機聚合與落盤，插件自述不上報遙測。

這是什麼¶

dsh-usage-monitor 歸類爲 admin-security，當前包版本 1.0.1（MIT 許可）。它在側欄註冊面板，把「會話口徑」「全量調用口徑」「平臺賬單口徑」並列展示，避免把三組數字簡單相加。Host 側零第三方依賴；瀏覽器端使用宿主注入的 React 模塊，圖表爲手寫 SVG。

面板裏有什麼¶

打開側欄圖標後，主面板按 README 中的結構組織，主要包括：

• KPI：總 Token、成本（人民幣爲基準，美元爲派生展示）、會話數、活躍會話、緩存命中率、請求數。
• 對賬條：全量調用口徑與平臺賬單的對比提示。
• 趨勢：堆疊柱（未緩存輸入 / 緩存讀 / 緩存寫 / 輸出）、構成餅圖、模型佔比餅圖。
• 實時：CPU、GPU、內存、RSS、heap、運行時長；約 2 秒輪詢，sparkline 保留 60 個點。
• 分會話：可排序、可搜索；含 token、命中率、TTFT、token 速度、時長等。
• 分模型：請求數、token 分桶、成本。
• 對話性能：TTFT 分位、平均輸出速度、工具耗時佔比。
• 全量調用：按 purpose（對話 / 壓縮 / 標題 / 其他）與模型拆分。
• 平臺賬單：餘額、今日 / 昨日 / 7 天 / 30 天消費、採樣覆蓋度（數據不全時金額前會標 ≥）。
• 賬單歷史：按天的柱狀圖，覆蓋餘額賬本記錄的每一天，含安裝插件之前的日期（在可回填範圍內）。
• 設置與計費規則：官方價表、峯谷時段、法定節假日、匯率位、各板塊顯隱（存 localStorage，隻影響展示）。

底部可勾選 11 個大板塊的顯隱；統計邏輯不因隱藏而改變。

三種口徑，不要相加¶

插件在文檔中明確區分三類數據來源，用途不同：

會話日誌主要記錄 assistant/message，可能漏掉 Auto review、標題生成、上下文壓縮、聯網搜索等仍計費的調用；全量調用口徑用於與平臺「API requests / Tokens」對齊。平臺賬單是賬戶級，同賬號其他 Key、機器、客戶端都會計入，且可能有最多約 5 分鐘延遲。餘額差法在區間內檢測到充值時會標記爲不可信，而不是給出錯誤消費數。

成本、匯率與賬單¶

成本估算使用編譯進包內的官方人民幣價目（元 / 百萬 token），按每次調用發生的時刻判斷峯谷；週末及內置的中國法定節假日全天按谷價，內置表覆蓋 2025–2026 共 61 天法定假日。2027 年及以後若官方尚未發佈安排，文檔說明未內置年份的工作日 9–12 / 14–18 可能按高峯價計（可能高估）；可用配置追加 pricingHolidays。

匯率啓動後異步拉取中國外匯交易中心（央行授權發佈）人民幣中間價，默認 30 分鐘刷新；失敗時按「歷史中間價 → 非央行市場匯率（面板標註）→ 配置兜底」降級，不會靜默沿用舊值。人民幣爲結算基準，美元僅爲展示；實時匯率不會回改已結算的歷史成本。

平臺相關讀寫經 DSH 的 deepseekAccount 服務，插件不接觸 token 或密碼。自建按天複式賬本（opening / closing / debit / credit），充值不計入消費；若本機存在其他 DSH 插件的歷史賬本文件，可作爲可選回填逐日合併（觀測級，不重複計）。

安裝與啓用¶

需要 DSH 0.2.x（Host 提供 sessionQuery / webServer；deepseekAccount、llm 爲可選服務，缺失時對應卡片顯示「不可用」，其餘面板照常）。插件不需要在包內執行 npm install。

完整步驟與排錯見倉庫 INSTALL.md。README 給出三條路徑，任選其一：

1、下載即用（推薦給普通用戶）

從 Releases 下載 dsh-usage-monitor-<版本>.tgz，解壓到長期目錄，在 DSH 插件管理器裏對 install_bundle 傳入該目錄的絕對路徑，然後刷新頁面。

2、源碼安裝

將倉庫克隆或解壓到本地目錄，同樣把含 package.json 的目錄絕對路徑交給 install_bundle：

plugin_manager({ action:"install_bundle", target:"<插件目錄絕對路徑>" })

安裝結果裏 application 必須是 "applied"。若 failed 且 failedAt === "registry"，文檔建議原樣重試一次（多爲網絡抖動）。不要手工改 profile 的 package.json / cordis.patch.yml。

3、交給 DSH 助手

把 README 中的安裝校驗段落髮給助手，由其執行 clone 或解壓、install_bundle、以及 cordis_inspect_query 與 HTTP 校驗。

驗證示例（將 <DSH Web 地址> 換成你的實例地址）：

GET <DSH Web 地址>/usage-monitor/api/overview?range=today  → 200 且含 kpi
GET <DSH Web 地址>/usage-monitor/api/live                   → 200 且含 host.cpuPercent

側欄註冊檢查：

cordis_inspect_query({ platform:"client", provider:"Slots", method:"listSubTree",
                       input:{ root:"sidebar.panellist" } })
→ occupants 中應有 { registrant:"usage-monitor", id:"usage-monitor", active:true }

卸載：在插件管理器中移除 dsh-usage-monitor。

配置要點¶

默認值在 cordis.patch.yml，可在 profile 層覆蓋。常用項包括：

緩存與賬本文件落在 $DSH_HOME/usage-monitor/ 等路徑，詳見 README 配置表。

典型用法¶

日常使用時，在 DSH Web 界面打開左側欄 usage-monitor 面板即可。按時間範圍查看 KPI 與趨勢，在分會話列表裏搜索慢會話或高 token 會話，用「全量調用」塊覈對是否包含壓縮、標題等輔助調用，用「平臺賬單」塊對照開放平臺消費（需已登錄且 deepseekAccount 可用）。

需要程序化探活或對接監控時，可調用 Host 暴露的 REST 路由（契約見 CONTRACT.md）：

• GET /usage-monitor/api/overview
• GET /usage-monitor/api/live
• 以及 ledger、account、bill-history、fx 等（見 lib/routes.js）。

適用場景與注意¶

適合：在本機 DSH 上長期跑 agent、希望同時看清會話用量、全量 API 調用與賬戶賬單差異的開發者；需要粗略成本估算（官方價表 + 峯谷 + 匯率規則）與運行資源佔用（CPU / 內存，有 nvidia-smi 時含 GPU）的場景。

注意：

• 插件以當前 DSH 進程權限運行，安裝前應閱讀源碼與 MIT 許可證，確認可接受其本地讀寫與對外匯率請求行爲。
• 成本爲按官方價目表的估算值，與開放平臺賬單可能存在口徑差，請以平臺爲準；README 標明爲非官方項目，與 DeepSeek 無隸屬關係。
• GPU 監控依賴 nvidia-smi，無則 gpu.available:false，面板隱藏顯卡塊。
• 版本升級若觸發 CACHE_VERSION 變化，首次打開面板可能略慢（全量冷掃後走緩存）。
• 對外網絡除匯率外自述無遙測；價目表運行時不再聯網抓取。

結尾¶

dsh-usage-monitor 把會話、全量調用與平臺賬單三種口徑拆開展示，並在同一側欄面板裏補上緩存命中率、分模型統計與本機實時資源採樣，適合在 DSH 0.2.x 上做用量觀測與對賬參考。

• 社區目錄頁：skillhub.cn/plugins/Dekurri/dsh-usage-monitor
• 源碼與文檔：github.com/Dekurri/dsh-usage-monitor