前言¶

在 DeepSeek Harness（DSH）里跑多轮对话或带工具的智能体时，API 会返回 usage，但很难回答更细的问题：上下文里哪一段占了多少 token、前缀缓存是按 64 token 块怎么命中的、某次 tool 结果或 assistant 回复是否把缓存弄断了、以及按官方费率（含峰谷）这一轮实际花了多少钱、缓存又省了多少。社区插件 dsh-token-optima（维护者 Boris-boomer）挂在 Cordis 插件框架上，面向上述诊断需求；它不是计费账单系统，也不是 prompt 压缩器。

这是什么¶

dsh-token-optima 是 DSH 的深度 Token 监测插件：用 64 token 块级缓存模型和 14 类归因，展示每轮请求的 token 去向、缓存命中情况，以及基于 DeepSeek 官方费率的费用与缓存 ROI。分类上属于「模型推理」相关能力；仓库见 GitHub，社区目录页见 SkillHub。当前 package 版本为 0.5.0，许可证 MIT，运行环境要求 Node >= 22.0.0。

README 中的隐私说明要点：插件不主动向外网发请求、无遥测；不持久化 prompt / reasoning / 工具结果原文，仅在内存中用哈希做对比；全局调试对象 window.__tokenOptimaDebug 默认关闭；仅在 ~/.dsh/token-optima/ 写入接口健康诊断文件，失败不阻塞主流程。

核心功能¶

下面按 README 列出的能力说明；数据质量分三档：实测（API 真值）、推断、估算。

14 类 Token 归因¶

底层使用坐标模型 (source, cache_status, direction, is_reasoning)，把一轮请求中的 token 按来源与缓存状态等维度拆开，便于对照面板查看构成。

真实费用与缓存 ROI（峰谷计价）¶

接入 DeepSeek 官方费率，计算每轮对话的总花费以及缓存节省金额。按北京时间识别高峰（工作日 9–12、14–18）与空闲时段，并支持历史累计统计。

64 token 块级缓存建模¶

按官方 64 token 存储单元切分前缀，追踪命中与未命中；可识别前缀断裂、上下文被压缩、surface 中间被替换等情况。

智能失效归因¶

缓存被破坏时，尝试定位破坏来源（例如 tool_result、assistant_msg），便于排查「是谁弄废了缓存」。

多会话与历史分析¶

面板内可切换会话，查看历史轮次明细（每轮花费、省下金额、命中率等）。

UI 与图表¶

提供深/浅色主题，以及可交互的环形构成图与趋势图。

安装与启用¶

插件以本地 link 方式接入 DSH profile，安装步骤来自仓库 README。

1、在 DSH profile 的 package.json 中增加依赖与 bundle：

"dependencies": {
  "dsh-token-optima": "link:<插件绝对路径>"
},
"dsh": {
  "profile": {
    "bundles": [
      ...,
      "dsh-token-optima"
    ]
  }
}

2、在 profile 目录执行安装：

cd <profile 目录>
pnpm install

3、完全退出 DSH（含托盘）后再启动，否则新 bundle 可能不会生效。

安装前请自行审阅 源码 与 MIT 许可证；插件随当前 DSH 进程权限运行，与 DSH 内其它本地插件相同。

启用精确 Tokenizer（可选）¶

默认用字符加权算法估算 token（README 称约 80–90% 准确率）。若要让归因标记为 exact（100% 精确），需手动加载 DeepSeek 词表。

第一步：下载词表

从 HuggingFace 下载以下文件（合计约 7.8 MB）到 ~/.dsh/：

• https://huggingface.co/deepseek-ai/DeepSeek-V3/resolve/main/tokenizer.json
• https://huggingface.co/deepseek-ai/DeepSeek-V3/resolve/main/tokenizer_config.json

第二步：设置环境变量

Windows（PowerShell）；若通过托盘或快捷方式启动 DSH，应写入用户环境变量并完全重启 DSH：

[Environment]::SetEnvironmentVariable('DSH_TOKENIZER_JSON', "$env:USERPROFILE\.dsh\tokenizer.json", 'User')
[Environment]::SetEnvironmentVariable('DSH_TOKENIZER_CONFIG', "$env:USERPROFILE\.dsh\tokenizer_config.json", 'User')

macOS / Linux：在 ~/.bashrc 或 ~/.zshrc 中加入：

export DSH_TOKENIZER_JSON="$HOME/.dsh/tokenizer.json"
export DSH_TOKENIZER_CONFIG="$HOME/.dsh/tokenizer_config.json"

第三步：验证

重启 DSH 并打开插件面板；若底部状态栏显示 tokenizer: hf:... (exact)，表示加载成功。

典型用法¶

日常使用以 DSH 内嵌面板为主：发起对话后查看当轮 token 构成、缓存命中与费用/节省金额；多轮或带工具场景下，结合失效归因判断是哪类消息导致前缀缓存断裂。需要切换上下文时，在面板内更换会话并浏览历史轮次列表与趋势图。

仓库 examples/demo.ts 可通过 pnpm demo 运行（开发依赖侧命令，见 package.json scripts）；一般用户以 profile bundle 启用后的 UI 为准。

适用场景与注意¶

适合已经在 DSH 上使用 DeepSeek API、希望优化长上下文与缓存策略的开发者：需要看清 token 花在哪、缓存 ROI 是否合理、以及失效点是否在 tool 或 assistant 输出。

注意：

• 费用与 ROI 基于插件内置的官方费率与峰谷规则，用于诊断而非替代账单。
• 默认可选依赖 @huggingface/tokenizers；未配置词表时归因精度为估算档。
• 社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，按需选用并审查源码。

结尾¶

dsh-token-optima 把「这轮 token 花在哪、缓存省了多少钱」拆到块级与 14 类归因，并本地完成统计。目录：SkillHub 插件页；源码与完整说明：GitHub README。