前言¶
做 DSH 插件時，常見一類需求：我想知道本機每個會話每天燒了多少 token，順便看看 DeepSeek 賬號還剩多少餘額。這類數據散落在本地的會話日誌裏，通常得開終端翻文件、寫腳本，才能拼出一張按天的彙總。
dsh-usage-monitor 就是針對這個痛點：它不替代任何統計命令，只把會話日誌解析成按天的彙總，再疊加一個餘額卡片。下面介紹它的功能、安裝方式、數據流向和侷限。
這是什麼¶
- 維護者：Alvin-Sun6612
- 倉庫：https://github.com/Alvin-Sun6612/dsh-usage-monitor
- 目錄頁：https://www.skillhub.cn/plugins/Alvin-Sun6612/dsh-usage-monitor
- 定位：DSH（DeepSeek Harness）客戶端插件，在側邊欄開一個「用量與餘額」面板
它解決兩件事：
- 按天統計本機會話的 token 用量，分今日、近 7 天、近 30 天、累計四個窗口。
- 顯示 DeepSeek 賬號餘額，但需要你自己在面板裏粘貼 API Key。
核心功能¶
下面是 README 中已覈實的能力，逐條列出。
- 用量窗口：今日 / 近 7 天 / 近 30 天 / 累計，每個窗口給 token 總量、調用次數、緩存命中率。
- 今日明細：未緩存輸入、緩存命中、輸出。
- 近 30 天柱狀圖，懸停可看當天數值。
- 餘額卡片：需要 DeepSeek API Key，在面板裏粘貼即可，Key 存在本機。
- 面板名與描述提供中英兩份 locale。
關於餘額，README 明確寫了一點容易踩坑的約束：餘額接口 /user/balance 只認 API Key（sk-...）。如果只在 DSH 裏登錄了 DeepSeek 賬號、沒有 Key，面板會顯示「未配置 API Key」。用量統計本身不需要 Key。
安裝與啓用¶
README 給了三條安裝路徑，按場景選。安裝命令照抄自 README，沒有自行拼接。
方式一：本機目錄（開發用）¶
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
# 或指定 profile：-Profile web
裝完需要重啓 DSH，側邊欄纔會出現「用量與餘額」。這條路徑假設你已經把倉庫拉到本地，適合改源碼的階段。
方式二：安裝 Release 裏的 tgz¶
這是 README 標註的推薦路徑，不需要 git、也不需要 npm：
# 直接裝 Release 附件（推薦）
dsh plugin --profile desktop add "https://github.com/Alvin-Sun6612/dsh-usage-monitor/releases/download/v0.1.0/dsh-usage-monitor-0.1.0.tgz"
# 手上有 tgz 文件時
dsh plugin --profile desktop add .\dsh-usage-monitor-0.1.0.tgz
# 倉庫裝了 git 時也可以用 GitHub 直裝（pnpm 會走 git，需 allowBuilds 授權）
dsh plugin --profile desktop add github:Alvin-Sun6612/dsh-usage-monitor
裝完同樣要重啓 DSH。卸載命令：
dsh plugin --profile desktop remove dsh-usage-monitor
注意這裏的 profile 固定爲 desktop。如果你裝完看不到入口，README 讓檢查 ~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles 是否包含 dsh-usage-monitor。
它讀什麼、發什麼¶
這部分決定你願意在多大範圍內信任它。README 給了一張表，下面照錄重點。
| 項目 | 說明 |
|---|---|
| 數據來源 | ~/.dsh/sessions/<工作區>/<會話>/*.jsonl.zstd，只讀 |
| 解析內容 | assistant/message 事件的 usage（inputTokens / cacheReadTokens / cacheWriteTokens / outputTokens）與事件時間 |
| 本地服務 | 127.0.0.1:46850 起只讀 HTTP 服務，CORS 只放行 localhost |
| 聯網 | 只有配置了 API Key 後，才請求 https://api.deepseek.com/user/balance；用量統計完全離線 |
| Key 存放 | ~/.dsh/dsh-usage-monitor.json（權限 0600），面板不回顯、不記錄 |
| 緩存 | 會話文件按 (mtime, size) 緩存解析結果；餘額結果緩存 60 秒 |
端口被佔用時，可以在面板底部改端口（瀏覽器端記住設置），也可以直接在 ~/.dsh/dsh-usage-monitor.json 裏寫：
{"port": 46851}
典型用法¶
不必起 DSH，直接驗證 Host 半¶
README 提供一條獨立自測路徑。index.js 是 Host 半，負責解析 zstd 日誌、代理餘額、起本地 HTTP 服務；它不依賴 DSH 運行時，可以直接跑起來：
node index.js
# http://127.0.0.1:46850/health
# http://127.0.0.1:46850/summary?days=30
# http://127.0.0.1:46850/balance
/health：服務是否存活。/summary?days=30：用量彙總。/balance：餘額，未配 Key 時返回未配置狀態。
/summary 返回結構（README 節選）：
{
"sessions": 22, "scanned": 22, "parsed": 22, "scanMs": 465,
"today": { "requests": 525, "totalTokens": 43301332, "cacheHitRate": 0.982 },
"last7": { "...": "同上結構" },
"last30": { "...": "同上結構" },
"allTime":{ "...": "同上結構" },
"series": [{ "date": "2026-11-05", "totalTokens": 43301332 }]
}
瀏覽器半契約測試¶
修改面板邏輯後，README 建議跑一遍 19 項契約測試，覆蓋瀏覽器半的渲染與交互：
node test/smoke.mjs
版本與發佈¶
package.json 裏的 version 是 0.1.0，license 是 MIT。README 還給了幾條發佈路徑，這裏只提醒兩點：npm publish 前要 npm login，且 package.json 裏得有 repository；直接發 tgz 則用 pnpm pack，產出 dsh-usage-monitor-0.1.0.tgz。
目錄結構¶
dsh-usage-monitor/
├─ package.json # dsh.bundle + dsh.client 聲明，exports 四項
├─ cordis.patch.yml # 組合包補丁：insert id=usage-monitor
├─ index.js # Host 半：解析 zstd 會話日誌 + 餘額代理 + 本地 HTTP 服務
├─ client.js # 瀏覽器半：側邊欄面板（無構建，React.createElement）
├─ locale/{zh,en}.json # 面板名與描述
├─ icon.svg / icon.png # 圖標
├─ install.ps1 # 一鍵安裝（UTF-8 BOM）
└─ test/smoke.mjs # 契約測試：node test/smoke.mjs
兩部分是分離的：index.js 跑在本機進程裏，client.js 跑在瀏覽器側邊欄，中間靠 127.0.0.1:46850 的本地只讀 HTTP 服務連通。想改造功能時，client.js 是面板側，index.js 是數據側。
自定義與上架¶
如果你想改名或換成自己的功能，README 給了四步：改 package.json（保留 dsh.bundle.patch）；cordis.patch.yml 的 id 與 name 與包名對齊；client.js 裏的 NS、PANEL_ID、PORT_KEY 和 CSS 前綴 dsh-um-* 建議一起換，避免與別的插件衝突；locale/*.json 的 meta.title / meta.description 就是市場卡片文案。
上架 DSH 插件市場（dshmarket）時，README 結論很明確：不要給 dsh-market 倉庫提 PR，也不要手改 README / plugins.json / index.json，它們由 CI 生成。唯一動作是往 https://github.com/awesome-dsh-plugin/awesome-dsh-plugin 提交一個新文件 data/plugins/Alvin-Sun6612__dsh-usage-monitor.yml，條目用 category: usage。本插件的市場條目已經準備好，位於倉庫內的 data/plugins/Alvin-Sun6612__dsh-usage-monitor.yml。
前置條件之一是把目錄內容推到你自己的 GitHub 倉庫根目錄，倉庫創建滿 1 天，加 dsh-plugin topic。合併後市場自動重建，通常一天內可搜到。
常見問題¶
下面幾條是 README 已列的故障與處理，挑了最常見的四條。
| 現象 | 原因 / 處理 |
|---|---|
| 面板提示「讀不到本地服務的數據」 | 插件沒隨 DSH 重啓加載，或 Host 半端口被佔。重啓 DSH；必要時在面板底部改端口。 |
| 餘額一直是「未配置 API Key」 | 用的是賬號登錄而非 API Key。去 platform.deepseek.com 建 Key 粘貼進面板。 |
| 餘額顯示 HTTP 401 | Key 無效或已被刪除；重新生成。 |
| 今日用量爲 0，但確實在用 | 面板按本機時區分桶；剛產生的調用需要點「刷新」清緩存。 |
還有一條環境坑：PowerShell 5.1 讀文件要加 -Encoding UTF8，.ps1 要存成 UTF-8 with BOM。
適用場景與注意¶
適合這些人和場景：
- 想按天、按窗口看本機 token 趨勢，而不是隻有單次調用的瞬時數字。
- 想順手盯 DeepSeek 餘額，不想開瀏覽器登控制台。
- 要做 DSH 插件、需要一個 Host 半 + 瀏覽器半的最小參考結構。
需要留意的點：
- 插件以當前 DSH 進程權限運行。安裝前應讀一遍源碼與
LICENSE（MIT），確認它訪問~/.dsh/sessions/和~/.dsh/dsh-usage-monitor.json的權限你能接受。 - 用量統計是本機範圍，只覆蓋
~/.dsh/sessions/下的會話日誌；多機、多工作區的全局視圖它不提供。 - 餘額是插件轉發的
api.deepseek.com/user/balance結果，Key 只存在本機、面板不回顯。 - 本地服務默認端口固定爲 46850，被佔用時才需要改。
結尾¶
dsh-usage-monitor 的價值在於把「用量統計」和「餘額」這兩件運維級小事收進側邊欄，Host 半離線跑、瀏覽器半做展示，職責切得乾淨。目錄頁在 https://www.skillhub.cn/plugins/Alvin-Sun6612/dsh-usage-monitor ，源碼在 https://github.com/Alvin-Sun6612/dsh-usage-monitor 。
