前言¶
在 DeepSeek Harness（DSH）裏跑 Agent、多輪對話時，模型調用會不斷累積：未緩存輸入、緩存命中、輸出各佔多少，摺合參考費用又是多少，往往要事後翻會話或自己記賬。若部署環境不固定、也不綁定某一產品的本地數據庫，就更難用「讀私有庫」的方式做統一統計。
下面介紹的 dsh-llm-token-usage（維護者 dgjin，分類：客戶端）面向「運行本插件的 harness 自身」：數據來自 harness 官方的會話查詢服務 ctx.sessionQuery，不解析任何私有文件，裝在同一套 DSH 上即可統計當前實例的用量與參考費用，並在原生界面裏給出儀表盤、斜槓命令與 Agent 工具。
這是什麼¶
插件統計本 harness 進程內 LLM token 用量與參考費用。每條 assistant/message 事件自帶 usage 與 provider/model，按天、按模型、按工作區、按會話的聚合是逐輪精確的。
與依賴某一客戶端本地數據庫的做法不同，它只調用 ctx.sessionQuery（listSessions → readSession → 逐條讀取 usage），只讀、不寫會話數據。參考費用由本地價表換算；平臺賬戶餘額在可用時通過 ctx.deepseekAccount.getBalance() 展示真實值，未登錄或查詢失敗時可回落到本地 balance.json 的估算口徑。
- 目錄頁：https://www.skillhub.cn/plugins/dgjin/dsh-llm-token-usage
- 源碼與文檔：https://github.com/dgjin/dsh-llm-token-usage
- 當前 package 版本：0.5.4（MIT，Node >= 22.5.0）
核心功能¶
入口一覽¶
| 能力 | 入口 |
|---|---|
| 主面板儀表盤 | 左側圖標欄 Token 用量（與 Plugins、Schedules 並列） |
| 文本報表 | /token-usage |
| 平臺賬戶餘額（真實值） | 儀表盤 KPI、會話頭部膠囊、狀態欄、/token-balance |
| 本會話花費 + 餘額 | 會話標題欄右側膠囊（懸停看明細） |
| 狀態欄精簡顯示 | composer 下方：本會話 ¥… · …M tokens · 餘 ¥… |
| 價表查看 / 同步 | /token-pricing、/token-pricing update；插件更新時可自動同步 |
| Agent 按需取數 | 工具 llm_token_usage（支持 format: "html" 導出） |
| 獨立 HTML 儀表盤 | 面板「打開獨立儀表盤 / 下載 HTML」，或 /token-usage-dashboard |
儀表盤內容¶
主面板與設置 → LLM Token 用量 共用同一份組件，與導出 HTML 對齊：
- 6 張 KPI：合計 Tokens、參考費用、賬戶餘額、模型調用（含未緩存輸入與輸出）、緩存命中率、輪次。
- 每日 Token 用量：緩存命中 / 未緩存輸入 / 輸出堆疊柱，帶峯值與懸停明細。
- 每日參考費用：折線 + 漸變面積。
- 模型 / 工作區分佈：橫向比例條（合計、佔比、費用）。
- 明細表：按天 / 模型 / 工作區 / 會話切換，表頭排序，可導出 CSV（UTF-8 BOM）。
- 口徑說明：價表版本、未配置單價的模型、餘額與數據覆蓋範圍。
面板打開期間約每 60 秒靜默刷新（頁面隱藏時跳過）；無調用記錄時顯示引導空態。點擊模型或工作區分佈某一行可篩選整個面板，自定義日期區間通過查詢參數交給 Host 計算；餘額與數據覆蓋說明仍按全量口徑，避免篩選後誤讀。
餘額與計價¶
餘額優先展示平臺真實值（充值錢包 + 贈金錢包）；估算口徑爲：期初餘額（balance.json）減去自 as_of（北京時間 00:00）起的參考費用。賬戶查詢帶 60s 緩存與 4s 超時，失敗不影響統計。
計價字段包括未緩存輸入、緩存命中、緩存寫入、輸出；緩存命中率 = 命中 /（未緩存輸入 + 命中）。價表默認複製到 ${DSH_HOME:-~/.dsh}/llm-token-usage/pricing.json，內置常用模型參考價，支持峯谷時段（北京時間工作日 9:00–12:00、14:00–18:00 爲高峯）。未配置單價的模型只統計 token，費用列顯示 —。
插件通過測試 tests/analytics-parity.mjs 與 harness 自身 tokenUsage 投影對賬，文檔中給出的凍結基準會話在主要字段上與 harness 賬本一致（差異爲 0）。
隱私與安全¶
正常使用全程本地、只讀；面板數據路由僅接受本機迴環直連。只有顯式執行 /token-pricing update（或開啓自動價表同步）纔會從公開倉庫拉取價表（HTTPS、校驗、備份後寫入）。可用環境變量 DSH_TOKEN_USAGE_NO_NET=1 或配置 autoUpdatePricing: false 關閉自動同步。
安裝與啓用¶
在 DSH 桌面端或 CLI 的插件管理裏安裝本包。資料中的安裝方式如下：
# 打包後安裝（將路徑換成本地 tgz 的絕對路徑）
dsh plugin --profile web add --workspace-root file:/絕對路徑/dsh-llm-token-usage-0.5.4.tgz
# 上架 npm 後
dsh plugin --profile web add dsh-llm-token-usage
裝完後重啓一次 Harness，斜槓命令、工具與設置頁入口才會生效。插件不裸導入 harness 包，鏈接安裝與打包安裝行爲一致。
典型用法¶
斜槓命令¶
近 7 天按天彙總：
/token-usage
近 30 天按模型、全部歷史按工作區或會話：
/token-usage 30 --by model
/token-usage all --by project
/token-usage all --by session
/token-usage --since 2026-09-01 --until 2026-09-15
估算餘額（期初餘額默認從今天起算）：
/token-balance
/token-balance --set 100
/token-balance --set 100 --as-of 2026-09-01
/token-balance --clear
導出 HTML 儀表盤：
/token-usage-dashboard
/token-usage-dashboard --path ./dash.html
價表：
/token-pricing
/token-pricing update
也可直接讓 Agent 回答「用了多少 token」「花了多少錢」「哪個模型最費」「緩存命中率多少」等，由 llm_token_usage 工具按需取數。
可選配置¶
插件行 config 均爲可選，例如：pricingPath、autoUpdatePricing（默認 true）、pricingSyncIntervalMs（默認 86400000）、balancePath、templatePath、cacheTtlMs（默認 60000）、maxSessions（默認 200，超出按最新會話截斷並在報表中標註）。
餘額配置文件示例路徑：${DSH_HOME:-~/.dsh}/llm-token-usage/balance.json：
{ "balance": 100.0, "as_of": "2026-11-01" }
適用場景與注意¶
適合誰：需要在 DSH Web 客戶端側長期觀察本實例 token 與參考費用、對比模型與工作區、導出 CSV 或獨立 HTML 報表，並在會話中實時看到本會話花費與餘額的開發者或團隊。
使用前請知悉：
- 插件以當前 dsh 進程權限運行，安裝前應閱讀源碼與 MIT 許可證，確認行爲符合你的安全策略。
- 參考費用依賴本地價表與模型配置，與平臺賬單可能存在差異；真實餘額以平臺 API 爲準。
- 社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；DSH 生態理念是「一切皆插件」，本介紹僅描述該插件在資料中聲明的能力。
結尾¶
dsh-llm-token-usage 把 harness 官方會話查詢裏的 usage 聚合成可讀的報表與原生儀表盤，並在狀態欄、會話膠囊裏補上本會話成本與餘額，適合作爲 DSH 部署上的本地只讀用量面板。進一步瞭解可訪問目錄頁 https://www.skillhub.cn/plugins/dgjin/dsh-llm-token-usage 與 GitHub 倉庫 https://github.com/dgjin/dsh-llm-token-usage。
