前言¶
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 统计数据的完整性，并支持对已损坏会话的即时恢复。
