前言¶
在 DeepSeek Harness（DSH）裏跑多模型、多會話時，單條會話裏的用量氣泡只能看當前會話。若要回答「一共燒了多少」「哪個模型佔大頭」「近七天趨勢如何」，只能自己翻 ~/.dsh/sessions 下的日誌，或寫腳本逐條解析 session.v4.jsonl.zstd。下面介紹的 dsh-token-usage 是社區插件，由 fuchen9 維護，在 Harness 側邊欄增加「Token 用量」面板，把本機全部已存會話的 token 消耗彙總起來，並按模型、提供商、會話類型、預設與時間窗口拆分；統計口徑與 Harness 自帶的 tokenUsage 投影一致，離線完成，運行時零第三方依賴。
這是什麼¶
dsh-token-usage（npm 包名 @local/dsh-token-usage，當前版本 0.1.1，MIT 許可）面向已安裝 DeepSeek Harness 桌面版或 dsh web 的用戶。它不改動會話數據、不發任何出站請求，只只讀本地會話日誌並渲染統計頁；在 SkillHub 目錄中歸類爲 admin-security。
核心功能¶
裝好後，側邊欄面板列表會出現「Token 用量」入口，點開是一整頁統計，主要包括：
- 彙總：合計、輸入、緩存命中、輸出、請求數、會話數。
- 按模型：每個「提供商 + 模型」的請求數、各分項 token、合計、佔比條、最近使用時間；模型分組以
message.source.provider與message.source.model爲準，重複的provider/前綴會在與 provider 相容時自動剝掉，避免同一模型裂成兩行。 - 維度對照：按會話類型（主會話 / 子會話）、按 agent preset、按提供商聚合。
- 時間窗口：全部、近 30 天、近 7 天、今天一鍵切換；另有按本地日曆日的最近幾天曲線、最近會話排行。
數據來源僅爲 ~/.dsh/sessions/**/session.v4.jsonl.zstd。Host 半通過 sessionPersistence 枚舉並增量讀取（按會話 revision 判斷變化）；進程內活躍會話走 sessions 的 snapshot。掃描時即按 YYYY-MM-DD 分桶，切換 range 只在內存合併，不重讀磁盤。實測 README 中提到的規模（220+ 會話、8700+ 條用量事件）首次全量約 1–2 秒，之後請求可命中緩存。
界面使用 --dsw-alias-* 設計 token，跟隨明暗主題；支持中文與 English。禁用插件後，路由與槽位通過 ctx.effect 撤銷。
統計口徑（與面板數字對齊）¶
- 總 token =
inputTokens + cacheReadTokens + cacheWriteTokens + outputTokens，並與事件自帶的totalTokens取較大者。 - 請求數：帶
usage的assistant/message事件條數；會話數：至少有一條用量事件的會話數。 - 多輪對話裏緩存讀取往往佔多數，因此「輸入」常遠小於「合計」，屬正常現象；事件裏的
usage來自模型回報，與單會話用量氣泡同源。
若本機有用量歷史不足 30 天，「近 30 天」與「全部」數字相同是預期行爲，可用「今天」或「近 7 天」對照驗證窗口是否生效。
安裝與啓用¶
需要 DeepSeek Harness。本包是標準 bundle：package.json 的 dsh.bundle.patch 指向 cordis.patch.yml，其中插入 @local/dsh-token-usage。
方式一：插件管理器（推薦）¶
在 Harness 插件管理器中選擇「安裝 bundle / 本地目錄」，指向本倉庫克隆或解壓後的絕對路徑，然後重啓 Harness。
方式二：手工裝進某個 profile¶
# <profile> 換成你的 profile 名（桌面版是 desktop，CLI 通常是 default）
cd ~/.dsh/profiles/<profile>
# 備份 package.json / pnpm-lock.yaml
pnpm link /絕對路徑/dsh-token-usage # 寫入依賴 + 建 node_modules 軟鏈接
然後把 "@local/dsh-token-usage" 追加到該 package.json 的 dsh.profile.bundles 數組裏，重啓 Harness。
桌面版注意：dsh plugin --profile desktop ... 會被拒絕（profile "desktop" is managed exclusively by the Electron application）；桌面版請用插件管理器或上述手工步驟。
方式三：從 GitHub 以 git 依賴安裝¶
cd ~/.dsh/profiles/<profile>
pnpm add github:fuchen9/dsh-token-usage
# 同樣別忘把 "@local/dsh-token-usage" 加進 dsh.profile.bundles
裝完之後：修改 lib/index.js（Host 半）必須重啓 Harness；只改 lib/client.js 時刷新頁面（必要時 Ctrl+Shift+R）即可，客戶端 bundle 支持 HMR。
典型用法¶
在界面中查看¶
- 安裝並重啓 Harness。
- 打開側邊欄，進入「Token 用量」。
- 在頁頂切換 全部 / 近 30 天 / 近 7 天 / 今天，對照彙總卡片、按模型表格、按天曲線與最近會話列表。
HTTP API（同源 GET）¶
本機 Harness 提供只讀接口，供自動化或調試；路由校驗 loopback / 同源，非 GET/HEAD 返回 405。
GET /api/dsh-token-usage?range=all|30d|7d|today&refresh=1
refresh=1 強制重掃（有 1.5 秒節流），否則使用緩存。響應包含 totals、models、providers、agents、presets、daily、sessions 等字段，各數組有上限（例如 models ≤200、sessions ≤60），避免超大用量撐爆響應。具體 JSON 結構見倉庫 README 的示例。
適用場景與注意¶
適合誰：需要在 DSH 內一眼看清本機歷史 token 消耗、按模型與時間段做對照、且不希望數據離開本機的開發者或管理員。
權限與安全：插件以當前 DSH 進程權限讀取會話目錄；安裝前應自行審閱 GitHub 源碼 與 MIT 許可證。README 明確說明插件本身無出站請求；唯一與模型相關的網絡行爲來自 Harness 調用模型，而非本插件上報。
故障排查：若面板顯示「無法讀取用量索引」或數字全爲 0，常見原因是 Host 半 export const inject 漏聲明 webServer、sessionPersistence 或 sessions 之一，導致掃描被靜默吞掉；可查看 Harness 日誌中的 dsh-token-usage: scan failed: …。頁面下半截無法滾動時，與 flex 佈局守衛有關，倉庫 scripts/harness-layout.mjs 用於驗證此類問題。
DSH 生態理念是「一切皆插件」；SkillHub 目錄頁 是社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-token-usage 把分散在各會話日誌裏的用量收成一塊離線面板，口徑與 Harness 單會話展示一致，適合在本機做用量審計與模型佔比分析。更多信息與更新日誌見 GitHub 倉庫；目錄條目見 SkillHub。
- 目錄頁：https://www.skillhub.cn/plugins/fuchen9/dsh-token-usage
- GitHub：https://github.com/fuchen9/dsh-token-usage
