前言¶
DeepSeek Harness（DSH）在計算會話歷史時，會累加四個核心桶的 Token 使用量。其中 cacheReadTokens 和 cacheWriteTokens 有默認的空值保護（?? 0），但 inputTokens 和 outputTokens 被視爲原始數字，沒有進行類型校驗。
當上遊服務商、本地推理服務或自定義網關返回非標準數據包（如缺失字段或 NaN）時，JavaScript 算術運算 total += NaN 會導致累計總額直接變爲 NaN。DSH 的 Schema 校驗會因此拒絕該會話摘要，導致整個對話歷史無法打開。
dsh-usage-guard 是一個運行時攔截器，它通過 Monkey-Patching 修改 DSH 的投影計算邏輯，在數據進入累加器前進行清洗、映射和校驗，從而恢復已損壞的會話並防止未來的數據污染。
插件定位¶
- 名稱：
dsh-usage-guard（由goodandready維護） - 定位：會話 Token 使用清洗器、歷史崩潰防護與算術保護工具
- 核心功能：防止因畸形 Provider 指標導致的歷史記錄損壞，支持即時恢復。
核心功能¶
1. 即時回放恢復¶
插件不修改磁盤上的日誌文件，而是掛鉤運行時的投影摺疊點。由於會話回放會經過這一攔截點，安裝插件後，所有之前損壞或鎖定的會話將被立即恢復並變爲可讀狀態。
2. 全面的別名借用詞典¶
在默認爲 0 之前，插件會檢查廣泛的行業標準字段別名，將其映射到 DSH 預定義字段。常見映射包括：
* inputTokens：input_tokens, input, promptTokens, prompt_tokens, promptTokenCount, prompt_eval_count
* outputTokens：output_tokens, output, completionTokens, completion_tokens, candidatesTokenCount, eval_count
* cacheReadTokens：cache_read_tokens, cachedTokens, cached_tokens, cache_read_input_tokens, cachedContentTokenCount, prompt_tokens_details.cached_tokens
* cacheWriteTokens：cache_write_tokens, cacheCreationTokens, cache_creation_input_tokens
3. 有限非負整數健全性校驗¶
嚴格驗證 typeof value === 'number' && Number.isFinite(value) && value >= 0 && Number.isInteger(value)，過濾掉 NaN、Infinity、null、undefined、負數錯誤碼（如 -1）、非整數浮點數及畸形字符串。
4. 安全零回退與浮點數取整¶
如果無法通過別名解析，計數器將被安全初始化爲 0。通過 Math.round() 對分片 Token 或小數字符串進行安全取整，滿足 DSH 核心契約 z.number().int().nonnegative()。
5. 內存註冊表 Monkey-Patching¶
- 現有投影：包裹
sessionProjections.registrations中現有的.apply方法，保留this上下文。 - 延遲綁定：通過包裹
map.set攔截未來的投影註冊，保證 100% 覆蓋。 - 通用保護：保護 Token 計數器、上下文壓力計算器和忙碌狀態分析器。
- 性能：使用淺拷貝和
WeakMap緩存，在 10-15 個並行 DSH 投影中保持零性能開銷。
6. 去重診斷報告¶
記錄詳細的診斷警告，包含會話 ID、輪次、步驟、原始載荷及恢復操作（如“從別名借用”或“歸零”）。內存中會去重日誌，防止回放時日誌刷屏，緩存上限爲 1,000 條 FIFO 項。
7. 原生 Web UI 設置卡片¶
掛載到設置標籤頁 Settings → Plugins → Plugin Settings，顯示實時狀態徽章、自動關閉的保存反饋以及中英雙語本地化。
8. Token 峯值鉗制¶
在投影計算前限制異常巨大的步數使用計數器（例如 > 1,000,000），防止整數溢出和會話摘要損壞。可在設置中配置或設爲 0 禁用。
9. 內存遙測與診斷端點¶
提供 /api/dsh-usage-guard/telemetry 端點，實時追蹤被修復的畸形樣本、總修復 Token 數、被鉗制的峯值，並維護包含精確時間戳和座標的最近事件 FIFO 循環緩衝區。
10. 端側一鍵更新¶
提供 /api/dsh-usage-guard/update 接口，實現主機側的一鍵更新功能。
使用示例¶
插件在運行時自動處理以下場景：
* 別名映射：將上游返回的 prompt_tokens 映射爲 inputTokens。
* 數據清洗：將 NaN 或缺失字段替換爲 0。
* 格式修正：將分片或小數字符串轉換爲整數。
* 異常限制：將超過 1,000,000 的異常計數器進行鉗制。
環境要求與依賴¶
- Node.js 版本：
>= 20 - 依賴項：
@deepseek-ai/cordis(^4.0.1)@deepseek-ai/schemastery(^3.18.1)
- 日誌處理：插件不會修改或重寫磁盤上的日誌文件。
總結¶
dsh-usage-guard 通過在 DSH 核心投影層插入防護邏輯，解決了上游數據畸形導致會話歷史永久損壞的痛點。它通過嚴格的類型校驗、別名兼容和內存級攔截，確保了 Token 統計數據的完整性，並支持對已損壞會話的即時恢復。
