前言¶
用 DSH（DeepSeek Harness）跑智能體會話時，有兩個問題經常要回答：這輪對話到底消耗了多少 token，上下文窗口還剩多少。默認的 Web GUI 裏只有 Chat 和 Trajectory 兩個頁，這些數字要麼看不見，要麼要自己去翻原始記錄。
samecorner/dsh-token-usage 解決的就是這件事：它是一個客戶端插件，在會話頂部 Tab 欄（Chat / Trajectory 之後）新增一個「Token 用量」頁，把整輪對話的 token 明細和上下文佔用直接展示出來。下面介紹它的功能、安裝方式和使用時需要注意的口徑問題。
這是什麼¶
dsh-token-usage 是 DSH Web GUI 的 Token 用量分析插件，npm 包名 @samecorner/dsh-client-ui-token-usage，當前版本 0.1.3，MIT 許可，由 samecorner 維護。
它的思路是：host 端的 token-meter、session-stats 模塊已經內置在 dsh web 中，會持續產出 tokenUsage、contextPressure、contextBreakdown、sessionStats 等投影數據；插件在瀏覽器端註冊一個 conversation.view slot 條目，把這些投影數據渲染成可視化面板。逐輪級別的數據則由插件客戶端從會話事件窗口摺疊 assistant/message 的 usage 得到。
作者在 README 中提到，靈感來自 pi-web-token-usage（pi-web 的同類插件），但完全按 DSH 的插件契約重新實現。
核心功能¶
按數據來源分，插件提供這幾塊內容：
1、整輪 KPI。總 token / 計費 token / 輸出 / 緩存讀取四張卡片，帶數字滾動動畫，數據來自 host 端 tokenUsage projection。
2、上下文壓力。上下文佔用進度條，達到 80% 及以上會警告變色；旁邊還有提示緩存命中率、推理佔比、平均與峯值單次調用。
3、上下文構成。系統提示 / 工具 schema / 對話內容三段堆疊條，反映新請求的組成估算，來自 host 端 contextBreakdown projection。
4、輪次與步數統計。來自 host 端 sessionStats projection。
5、構成環形圖和明細表。按輸入 / 緩存讀 / 緩存寫 / 輸出 / 推理拆分，每項帶佔比微條。
6、逐輪視圖。逐輪堆疊柱狀圖（hover 顯示 tooltip）、逐輪明細（含耗時）、累計計費曲線，由客戶端從會話事件窗口摺疊 usage 計算。
7、按模型拆分。每個模型的 token、調用數、緩存命中率。
8、輔助操作。一鍵複製 Markdown 報告；「加載更早記錄」按鈕翻閱更早的輪次。
安裝與啓用¶
推薦用 npm 一鍵安裝，免編譯、免改配置：
# 在哪裏執行都可以，dsh 會自動到對應的 profile 目錄裏跑 pnpm
# （首次使用會自動初始化 profile）
dsh plugin --profile web add @samecorner/dsh-client-ui-token-usage
# 重啓 dsh web，頂部即出現「Token 用量」Tab
這個包聲明瞭 dsh.bundle.patch（對應包內的 bundle.patch.yml），dsh plugin add 之後會自動掛載：包被加進 profile 的 bundle 層，不需要手動改 cordis.patch.yml。
有一個前提要注意：如果之前在 cordis.patch.yml 裏手動 insert 過同 id 的條目，請先刪掉，否則會因重複掛載報錯。
更新和卸載也是一條命令：
dsh plugin --profile web update @samecorner/dsh-client-ui-token-usage
dsh plugin --profile web remove @samecorner/dsh-client-ui-token-usage
卸載時，依賴與層列表會自動一併摘除。
源碼構建與本地開發¶
想改代碼或本地調試，可以走源碼構建：
# 1. 構建（需要 node >= 18；依賴只來自 npm 公開包，不需要 DSH 源碼）
npm install
npm run build # 產出 lib/client.js + lib/index.js
# 2. 以本地目錄安裝進 profile（同樣走 dsh plugin，自動掛載）
dsh plugin --profile web add /path/to/dsh-token-usage
# 3. 重啓 dsh web
目錄依賴是鏈接語義：改代碼後重新 npm run build，重啓 web 即生效，不需要拷貝或同步文件。
常用的開發命令：
npm run typecheck # tsc --noEmit
npm run build # esbuild：瀏覽器 bundle + node half
npm run test # 冒煙：loader 形態 + SSR 渲染（不啓動 web）
打包格式上有一個硬性要求：lib/client.js 必須帶 window.__ModuleLoader__.load({ id, factory }) 包裝，react / cordis / ui-slots 等平臺模塊保持 external。這個包的運行時是零依賴的——package.json 裏只有 devDependencies（類型和構建工具）。
如果打算自己寫 DSH 客戶端插件，倉庫裏的 docs/client-plugin-dev-guide.zh.md 是一份開發手冊，覆蓋官方 Demo 目錄、完整流程和踩坑清單。
數據口徑與已知限制¶
看數字之前，先弄清楚幾個口徑，避免誤讀：
- 逐輪明細只覆蓋「窗口內已裝配且帶 usage 的 assistant/message」。被取消的步、usage 缺失的調用不會出現在逐輪表裏；整輪合計以 host projection 爲準，兩者口徑可能略有差異。
- 推理 token 計入輸出，與 token-meter 口徑一致。
- 沒有成本估算。DSH 不記錄單價，插件不做猜測計費。
- 上下文佔用顯示的是 token-meter 的近似投影（projectedTokens / contextWindow），不是計費口徑。
適用場景與注意事項¶
這個插件適合兩類場景：一是長會話開發，需要盯着上下文佔用、決定什麼時候開新會話；二是成本與效率優化，比如覈對提示緩存命中率、比較不同模型的實際消耗。複製 Markdown 報告的功能，也方便把用量數據貼進 issue 或文檔裏討論。
兩點提醒：
第一，和所有 DSH 插件一樣，它以當前 dsh 進程的權限運行。安裝前建議先看一下源碼（倉庫公開）和許可證（MIT），確認沒問題再裝。
第二，插件依賴 host 端 projection 數據，逐輪視圖依賴會話事件窗口內的 usage 字段。如果某些調用本身沒有 usage，對應行不會出現，這不是插件壞了，是口徑限制。
結尾¶
dsh-token-usage 做的事情很集中：把 DSH 內置的 token 投影數據變成一個看得懂的分析頁。如果你在用 dsh web 跑智能體會話，裝上它，重啓後頂部多一個「Token 用量」Tab，就能直接回答「這次會話花了多少 token、上下文還剩多少」這類問題。
- GitHub 倉庫：https://github.com/samecorner/dsh-token-usage
- 社區插件目錄頁：https://www.skillhub.cn/plugins/samecorner/dsh-token-usage
（社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。）
