前言¶
同時接幾家模型供應商是 DSH 用戶的常態：Kimi For Coding 是訂閱額度，DeepSeek 官方按量扣餘額，OpenRouter 看積分。想知道「還剩多少、這個月花了多少」，通常要分別登錄各家控制檯，來回切換，查完一圈，手頭的工作早被打斷。
dsh-token-monitor 把這件事搬進了 DSH Web：會話頭部常駐餘量徽標，主區多一個「用量」頁籤，本地 SQLite 記錄每次調用的 token 與估算費用。下面介紹它的功能、安裝與配置。
這是什麼¶
dsh-token-monitor 是 DeepSeek Harness（DSH）Web 界面的大模型餘量與用量監控插件，作者 licyer，當前版本 1.0.2，MIT 許可證。它解決的問題很具體：用量與餘量數據散落在各供應商控制檯，在 DSH 裏看不到。
插件做三件事：
1、在會話頭部即時顯示當前模型供應商的餘量；
2、在主區提供與「對話 / 軌跡」並列的「用量」頁籤，統計 token、估算費用與使用趨勢；
3、自動採集 DSH 會話日誌，把每次調用的 token 與費用落進本地 SQLite（token-monitor.db）。
核心功能¶
餘量徽標¶
徽標顯示當前模型供應商的餘量，形如 k3 · 5h 剩 82%。兩類供應商的展示邏輯不同：
1、訂閱制供應商（如 Kimi For Coding）：顯示滾動窗口與周額度百分比；
2、按量付費供應商（如 DeepSeek 官方）：顯示賬戶餘額。
點擊徽標彈出詳情層，包含當前提供方指標、本會話 token 用量（可切換會話）、全部提供方摺疊區、cc-switch 數據同步提示條、更新時間與手動刷新。
用量頁籤¶
「用量」頁籤與「對話 / 軌跡」並列。頂部是篩選（客戶端 / 供應商 / 模型級聯，供應商按廠商歸併）和時間窗（當天 / 昨天 / 7 / 30 / 90 天 / 全部），統計卡給出總消耗、請求次數、預估費用、平均 TTFT、新增輸入、緩存命中、輸出、緩存命中率。往下依次是：
- 使用趨勢：漸變面積圖，左軸 token 構成，右軸可切換預估費用 / 請求次數；當天視圖爲分鐘級刻度（2~60 分鐘自適應、至少 12 桶，補桶不跨天），懸浮提示顯示桶區間（如
15:00~15:30）； - 供應商消耗統計：X 軸供應商、柱內按模型堆疊，右側可切換費用 / 次數；
- 年度消耗熱力圖：GitHub 日曆風格，覆蓋近 12 個整月，色深對應當日 token，首尾按周補齊；
- 使用排行：模型 / 供應商 / 客戶端三個維度聚合，默認按總消耗降序；
- 請求記錄：分頁明細表，時間倒序，頁碼跳轉，每頁條數可選 10/20/50/100。
自動採集與存儲¶
插件自動採集 $DSH_HOME/sessions 下的會話日誌，增量寫入本地 SQLite（token-monitor.db）。採集由後臺定時器、手動刷新和打開頁籤時觸發，頁面查詢直接讀庫。數據不出本地。
歷史導入與跨設備同步¶
兩處補數據的入口：
1、cc-switch 歷史記錄導入，重複導入不產生重複數據；
2、JSON 快照導出 / 導入（含明細與聚合），可把不同設備的使用記錄合併到一臺設備，冪等不重複。
兩個入口都在「用量」頁籤底部的「數據來源」。
語言跟隨¶
界面文案跟隨 DSH 的中文 / 英文切換，不需要單獨設置。
安裝與啓用¶
前置條件：Node.js ≥ 22（依賴內置的 node:sqlite），且僅支持 DSH Web 端（platform: web）。從 npm 安裝（推薦方式）：
dsh plugin --profile web add dsh-token-monitor
也可以從 GitHub 安裝：
dsh plugin --profile web add github:licyer/dsh-token-monitor
安裝即自動註冊，寫入 profile 的 package.json bundles 與依賴，不需要手動改配置。經過上面的步驟，重啓 dsh web 進程後生效，會話頭部應出現餘量徽標，主區多了「用量」頁籤。
憑證配置¶
餘量查詢讀取 DSH 已有憑證，寫在 ~/.dsh/.credentials.yaml，或通過環境變量提供，如 DEEPSEEK_API_KEY、KIMI_CODING_API_KEY。憑證沒配時徽標會提示「未配置 API Key」，配置後自動恢復。
插件配置¶
配置文件位於 $DSH_HOME/storages/token-monitor/config.json。設置入口在 DSH 設置面板（左下角齒輪）→ Token Monitor 頁，表單保存後即時寫回該文件。共三個設置項：
| 字段 | 默認值 | 含義 |
|---|---|---|
defaultDays |
1 |
用量頁籤默認時間窗天數，0 表示全部 |
pollMs |
60 |
頭部餘量輪詢間隔，設置頁與 config.json 均存秒，需要毫秒時由前端單獨 ×1000，取值 5–86400 |
retentionDays |
60 |
請求記錄保留天數，超期記錄定期清理但不影響聚合統計，設置頁提供 30/60/90 |
設置頁下方還附有已適配供應商清單，標明哪些提供方已適配、開發者是否用真實憑證驗證過。
遇到端點漂移（供應商 API 地址變更，常見 404）時，可在插件配置裏用 providers.<id>.url 覆蓋端點地址。
供應商適配¶
| 提供方 | 類型 | 展示內容 | 驗證狀態 |
|---|---|---|---|
kimi-coding |
訂閱額度 | 5h / 7d / 權益等級（百分比與重置倒計時） | 已驗證 |
moonshotai-cn |
按量餘額 | 可用餘額（CNY）+ 現金 / 代金券明細 | 已驗證 |
deepseek |
按量餘額 | 賬戶餘額（按幣種賬戶顯示） | 已驗證 |
opencode-go |
訂閱額度 | 5h / 7d / 30d（百分比與重置倒計時） | 已驗證 |
openrouter |
按量餘額 | 積分餘額（1 積分 = $1）+ 本月 / 總消耗 | 已驗證 |
minimax / minimax-cn |
訂閱額度 | 5h / 7d 用量百分比（剩餘%） | 待真實 key 驗證 |
zai / zai-coding-cn |
訂閱額度 | 5h / 7d 用量百分比（窗口自動識別，含重置時間） | 待真實 key 驗證 |
後兩組已通過 mock 測試，但未用真實 key 校準；若實際響應結構與參考實現有出入，可提交接口返回的 raw 原文協助校準。
常見問題¶
徽標沒顯示或提示「查詢失敗」¶
先看文案：「未配置 API Key」說明憑證沒配，按上面的憑證配置補齊即可；「查詢失敗」說明憑證已配置但餘量接口查詢失敗，按條排查：網絡不通或超時、端點漂移（用 providers.<id>.url 覆蓋）、響應字段結構異常無法解析。若提示「插件未適配該提供方」，則是適配範圍問題，與以上無關。
用量頁籤沒數據¶
用量來自會話日誌採集：先確認 $DSH_HOME/sessions 下有會話日誌，再點頂部「刷新」（先採集再查詢）；cc-switch 數據需在「數據來源」手動導入。
費用準不準¶
費用按 pi-ai 本地刊例價估算，僅供參考、非實際賬單；訂閱制不產生真實扣費；未定價模型計入 token、不計入費用。
本地開發¶
克隆倉庫後用本地路徑掛載：
git clone https://github.com/licyer/dsh-token-monitor.git
dsh plugin --profile web add link:/path/to/dsh-token-monitor
改前端（lib/client.js）走 HMR 熱替換，刷新即生效；改服務端（lib/index.js / lib/util/）需重啓 dsh web 進程。
適用場景與注意事項¶
適合同時使用訂閱制與按量付費供應商、想在 DSH Web 裏直接看餘量和用量明細的開發者，也適合需要本地留存調用記錄、做跨設備合併的人。
使用前注意：
1、插件以當前 dsh 進程的權限運行，安裝前建議檢查源碼與許可證（MIT）；
2、費用爲本地刊例價估算，不要當賬單對賬；
3、minimax 與 zai 兩組適配未經真實 key 驗證，結果以實際爲準；
4、僅支持 Web 端，Node.js 版本必須 ≥ 22。
相關鏈接¶
DSH 的理念是「一切皆插件」，dsh-token-monitor 把餘量查詢和用量統計收進同一個界面，數據留在本地，安裝只需一條命令。
- GitHub 倉庫：https://github.com/licyer/dsh-token-monitor
- 社區目錄收錄頁：https://www.skillhub.cn/plugins/licyer/dsh-token-monitor （社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係）
