前言¶
在 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中的对应行。
