前言¶

DeepSeek Harness（dsh）把模型適配、工具、會話日誌和界面都做成插件。日常用下來，token 是實打實燒掉的：今天已經用了多少、近一週哪幾個模型佔大頭、開過多少頂層對話，默認界面並不集中展示。自己翻會話日誌也能算，但事件字段散、子代理會話混在一起，數字很難一眼看完。

社區插件 dsh-token-monitor 把這件事做成側邊欄底部的「今日用量」卡片：數字一直掛着，點一下彈出完整看板。本文按社區目錄頁、GitHub 倉庫 README、package.json 和宿主源碼交叉覈對後整理：它是什麼、當前版本實際畫什麼、怎麼安裝，以及數據從哪來。

這是什麼¶

dsh-token-monitor 是一款面向 DeepSeek Harness Web 界面的會話與消息插件，由 zhangzheng25 維護，倉庫在 zhangzheng25/dsh-token-monitor，許可證爲 MIT，主要語言是 JavaScript。查閱時 package.json 版本爲 0.6.0，GitHub 顯示 5 星；社區目錄頁仍顯示 4 星，收錄分類爲「會話與消息」。

它解決的是本地用量可見性，而不是去官方計費接口拉餘額。當前實現（2026-08-16 的 main 提交 a627daf）是：

• 在側邊欄底部、設置圖標旁放一張「今日用量」卡片，單行顯示今日 token 總量
• 點擊卡片彈出「Token 用量」窗口：今日 / 近 7 天 / 近 30 天總量、近 30 天按模型堆疊柱狀圖、前 4 名模型排行，以及對應時段的頂層會話數
• 用量只從會話日誌回填，安裝之前的歷史也會統計進來

需要先說明一處來源差異。社區目錄頁和 GitHub 倉庫簡介仍寫着「設置 → Token 用量」以及 GitHub 風格的 90 天貢獻圖。那是較早版本的文案。倉庫 README 與 client/bundle.js 已經改成側邊欄卡片加彈窗，不再註冊設置頁，圖表也改成近 30 天按模型分色堆疊，而不是 90 天貢獻熱力圖。下文以倉庫當前源碼爲準。

DeepSeek Harness 官方倉庫的定位是「一切皆插件」，社區插件目錄是獨立站點，和 DeepSeek / 幻方沒有從屬關係，不能當成官方應用商店。

核心功能¶

側邊欄「今日用量」卡片¶

客戶端把卡片掛到 sidebar.footer.action 槽位，位置在會話列表下方、設置齒輪旁邊。展開側欄時顯示「今日用量：」加數值；摺疊成約 56px 窄欄時只留數字。

卡片每 30 秒請求一次宿主的 /token-monitor/today。這條路由只讀內存裏的「今天」桶，不觸發全量重建，所以側欄輪詢比較輕。今日總量按輸入、輸出、緩存命中、緩存寫入四項相加；推理 token 會寫入按天桶，但不計入這張卡片和彈窗裏的總量數字。

數值格式按量級切換：過萬用「萬」，過億用「億」，再大用 B / T。README 裏的示例文案是「今日用量：8888萬」。

彈窗裏的總量和會話卡¶

點擊卡片後出現固定遮罩彈窗，標題爲「Token 用量」，可用 Esc、右上角 ✕ 或點擊遮罩關閉，打開時鎖定背景滾動。面板裏先是三張總量卡：

• 今日 Tokens
• 近 7 天 Tokens
• 近 30 天 Tokens

下面再跟三張會話卡：今日 / 近 7 天 / 近 30 天開啓的頂層對話數。副文字是對應時段的模型請求次數。子代理內部會話（delegationDepth !== 0）不計入對話數，避免一次委派把數字抬高。

頁頭還有「刷新」和「回填歷史」兩個按鈕，並顯示「統計自 … · 歷史回填至 …」時間。彈窗打開後拉 /token-monitor/snapshot，之後同樣每 30 秒輪詢。

近 30 天按模型堆疊圖¶

圖表固定 30 天窗口。每一天一根柱，按模型分色堆疊；當天用量最高的模型在柱底，顏色按近 30 天總用量排名固定，用一套莫蘭迪色板。橫軸只標每週一的日期。懸浮或點擊某天會釘住明細卡：日期、總計、各模型色塊行。沒有柱上數字，也沒有高亮變灰。

沒有數據時，界面提示：「暫無模型用量數據——插件升級後點一次「回填歷史」即可。」

模型使用排行¶

排行同樣鎖在 30 天窗口，取前 4 名，排成 2×2 卡片。每張卡是：序號一行、模型名加 token 總數、提供商加佔比。佔比在瀏覽器端用該模型總量除以 30 天全模型總量算出。卡片不顯示增長率，也不顯示「總計」「新增」這類標籤。

模型身份來自會話事件裏 message.source 的 provider 和 model，拼成 provider:model。缺字段時記爲 unknown。

會話日誌回填和本地持久化¶

宿主半在 src/index.js。v3 把會話日誌定爲唯一數據源：通過 sessionQuery 列出會話、讀事件，只摺疊 assistant/message 上的 usage（輸入 / 輸出 / 緩存命中 / 緩存未命中 / 推理），按天、按模型分桶。sessionQuery 是 live-preferred，內存裏的進行中會話和落盤日誌都會算進去，所以不必再掛 llm/stream 即時鉤子。README 寫明舊版「瀑布流即時捕獲 + 日誌回填」會把同一次調用計兩次，v3 已去掉即時路徑，每次把窗口內數據折進新 Map 再原子替換，重複運行不會疊加。

回填在這些時機觸發：啓動約 3 秒後、點擊「回填歷史」、快照輪詢帶 ?backfill=1。全量摺疊有 20 秒節流，同一時刻只跑一輪。

持久化文件是 $DSH_HOME/plugins/token-monitor/data.json（未設置 DSH_HOME 時爲 ~/.dsh/plugins/token-monitor/data.json），schema 版本 3，按天桶保留 181 天。若仍存在舊路徑 $DSH_HOME/plugins/token-usage/data.json，首次加載會嘗試遷過去。

安裝與啓用¶

社區目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端裏運行：

dsh plugin add github:zhangzheng25/dsh-token-monitor

倉庫 README 額外標明這是 Web 端插件（package.json 裏 dsh.client.platform 爲 "web"），建議顯式指定 web profile：

dsh plugin --profile web add github:zhangzheng25/dsh-token-monitor

本地目錄也可以裝：

dsh plugin --profile web add /path/to/dsh-token-monitor

需要可復現安裝時，目錄頁建議固定 commit 哈希。查閱時 main 最新提交是 a627daf（2026-08-16，對應 0.6.0 側邊欄卡片改動）：

dsh plugin --profile web add github:zhangzheng25/dsh-token-monitor#a627daf46e6ac822445e882353f70a8a81c2420a

dsh plugin 會在 profile 目錄裏交給 pnpm，並調和 dsh.profile.bundles。包內 cordis.patch.yml 把 id 爲 token-monitor 的插件行插入宿主組合，而不是某個 agent 預設——它要讀宿主上的 sessionQuery、timer、webServer。

安裝後需要重啓 DSH。官方 Web UI 的啓動方式是：

npx @deepseek-ai/dsh web

默認地址 http://127.0.0.1:3080。重啓後側邊欄底部應出現「今日用量」卡片；點卡片即彈出統計窗口。package.json 要求 Node.js >= 20。DeepSeek Harness 本身仍處於開發者預覽，官方 README 寫明可能出現破壞兼容性的變更。

典型用法¶

1. 確認當前跑的是 Web 界面，而不是無界面的 headless 一次運行。該插件的客戶端 bundle 只給 web 外殼加載。
2. 按上一節安裝並重啓。若卡片不出現，先看 profile 是否爲 web，以及宿主組合裏是否已插入 token-monitor。
3. 看側欄數字是否在變。進行中的調用也會進會話語料，但卡片 30 秒才輪詢一次，不必期待每個 token 都即時跳動。
4. 打開彈窗。若堆疊圖是空的，點一次「回填歷史」，等下一輪快照。升級後舊桶可能被丟棄，源碼註釋寫明 v1/v2 遷到 v3 時會清空再從會話語料重建。
5. 用 30 天排行對照自己實際在用的模型名。佔比只反映本機會話日誌裏的用量結構，不是官方賬單。
6. 需要覈對原始數字時，打開 $DSH_HOME/plugins/token-monitor/data.json。裏面是按天、按模型的桶，不是計費明細。

適用場景與注意事項¶

適合這些情況：

• 長期開着 DSH Web UI，想在側欄直接看到今日 token
• 同一套環境裏切換多個模型，想看近 30 天誰佔用最多
• 關心頂層對話開了多少，而不是把子代理內部會話算進去
• 插件裝得比較晚，但仍希望把安裝前的會話日誌統計進來

使用前注意下面幾條，均來自目錄頁、倉庫說明或源碼，不是額外發揮：

1. 插件以當前 dsh 進程的權限運行。 社區目錄頁寫明：安裝時可能執行代碼。裝之前應查看源代碼倉庫和許可證；需要可復現安裝時固定 commit。
2. 只統計本機會話語料，不查賬戶餘額，也不按單價折算費用。 和走 DeepSeek 官方用量接口、或專門做費用賬本的插件不是同一類東西。
3. 只服務 Web 界面。 dsh.client.platform 爲 "web"，headless 流程看不到這張卡片。
4. 界面總量不含推理 token。 桶裏有 reasoningTokens 字段，卡片和排行用的合計是輸入 + 輸出 + 緩存讀寫。
5. 會話數只計頂層。 delegationDepth === 0 才計入；子代理內部會話被排除。
6. 倉庫帶有 AI 生成聲明。 README 寫明項目由 AI 輔助生成，僅供學習與技術交流，不構成商業保證或支持承諾。許可證是 MIT，版權頁標註 Copyright (c) 2026 zhangzheng25。
7. 目錄頁文案可能滯後。 若仍看到「設置頁 / 90 天貢獻圖」，以倉庫 README 和當前 main 爲準。

小結¶

dsh-token-monitor 把 token 用量和頂層會話統計做成 DSH Web 側欄裏的一張卡片：今日數字一直可見，點開是 7 天 / 30 天總量、按模型堆疊圖和前 4 名排行。數據只從會話日誌冪等回填，裝插件之前的用量也能算進來，重啓後落在本地 data.json。它不替代官方賬單，只解決「這臺機器上的 Harness 到底用了多少」這一眼能看清的問題。

目錄頁與倉庫：

• 社區目錄：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-token-monitor/
• GitHub：https://github.com/zhangzheng25/dsh-token-monitor
• DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness