前言¶
在 DeepSeek Harness (DSH) 的智能體開發場景中，輸入 token 的估算直接關係到上下文窗口的使用情況和成本控制。官方 Web GUI 原生並未提供實時的、精確的輸入 token 計數功能，特別是在涉及系統提示詞、工具定義以及技能引用時，開發者難以直觀判斷上下文佔用。
dsh-composer-tokens 是一個由 wbycloud 維護的純客戶端插件，它通過掛載到 Web GUI 的輸入框組件，提供實時 token 計數與詳細統計。該插件基於 @huggingface/tokenizers 實現，支持精確計數與離線估算兩種模式。
功能說明¶
實時計數與展示¶
插件在 conversation.input.right 位置注入一個行內徽標，顯示預計總 tokens（基線+草稿+幀）及上下文佔用率。
- 顯示格式：≈12,345 · 38%
- 防抖機制：輸入時觸發 250ms 防抖刷新草稿部分，避免頻繁計算。
- 顏色分級：根據本次請求總 token 數着色：<100k 爲綠色，100k-300k 爲琥珀色，>300k 爲紅色。
詳細信息 Tooltip¶
通過鼠標懸停或鍵盤焦點，展開 Tooltip 查看詳細數據，包括：
- 基線：基於最近一次請求的真實錨點（projectedTokens）。
- 草稿增量：當前輸入框內的變化量。
- Usage：會話累計真實 tokenUsage 四桶。
- 緩存命中率：僅在 provider usage 到達後顯示。
- 引擎與模型：精確引擎（HF Tokenizers）或估算引擎（啓發式），以及當前模型口徑標記。
計算口徑¶
- 基線優先：優先使用
projectedTokens（已含系統提示詞+工具定義）。 - 草稿包含：技能文本、引用文本（
@skill）按發送路徑計入草稿。 - 估算兜底：未知模型、離線無緩存或加載失敗時，使用
ceil(len/4)啓發式估算（標~）。
安裝與啓用¶
前置要求¶
- Node.js ≥ 22
- pnpm
- 構建產物：若修改了源碼，需先運行
npm run bundle生成lib/client.js。
安裝命令¶
推薦使用 npm 發佈版本安裝：
dsh plugin --profile web add dsh-composer-tokens
本地開發安裝¶
若需開發調試，直接安裝本地目錄：
dsh plugin --profile web add D:\path\to\dsh-composer-tokens
老版本遷移¶
v0.1 版本起插件自帶 dsh.bundle.patch，安裝後無需手動在 cordis.patch.yml 中添加 loader 行。若之前手動添加過，請刪除舊行，否則會衝突。
使用方法¶
基礎查看¶
啓動 Web GUI（dsh web）並刷新頁面。在輸入框右側、發送按鈕左側會出現計數徽標。新會話首次請求前顯示上次會話規模佔位，發送後自動校準。
模型覆寫配置¶
插件支持通過 localStorage 覆寫模型對應的 tokenizer 家族或自定義 URL。
localStorage.setItem("dsh-composer-tokens.overrides", JSON.stringify({
"qwen-72b": "deepseek", // 指定內置家族
"my-model": "https://…/tokenizer.json" // 或自定義 tokenizer.json URL
}));
開發構建¶
插件源碼包含 React 組件、Tokenizer 引擎及數據拉取邏輯。
npm run prepare-tokenizer # 下載/校驗 tokenizer 數據，生成 tokenizer-data.ts
npm run bundle # 生成 lib/client.js
npm run watch # 增量構建（配合 HMR）
注意事項¶
- 不含輸出 tokens：由於輸出不可預測，徽標僅顯示輸入側的預計 tokens。
- 模型切換冷卻：模型切換無 wire 事件，會話緩存 + 投影幀存在 3s 冷卻重查機制。
- 超長草稿：草稿超過 10 萬字符時，尾部將自動切換爲估算模式。
- 行內顯示限制：輸入框空間有限，徽標可能被截斷，完整數值在 Tooltip 中可見。
- Windows pnpm link：本地開發時，
pnpm link在跨盤符時可能生成文件符號鏈接導致 Node 無法解析，需手動重建爲目錄 junction。 - 老安裝清理：v0.1 之前手動添加 loader 行的用戶，卸載或更新時需手動清理
cordis.patch.yml中的對應行。
