前言¶
在 DeepSeek Harness（DSH）的 web UI 中，默认的会话 token 用量通常只显示为 composer 下方的一行纯文本 stats 行。对于需要频繁关注上下文窗口、缓存命中和生成速度的 DSH 插件开发者来说，这一行文本不够直观：上下文还剩多少、输入里有多少 cache-read / cache-write / uncached、当前 decode throughput 和平均 TTFT 是多少，都需要逐项看文本才能拼出完整信息。
dsh-token-usage 是一个社区 DSH 插件，用更清晰的条状区域和详情面板取代默认纯文本 stats 行。它由 hashdiana 维护，许可证为 MIT，当前版本为 0.1.0。
这是什么¶
dsh-token-usage 是一个纯客户端 DSH 插件，用于在 DeepSeek Harness web UI 中展示会话 Token 用量。它不是官方组件，也不依赖服务端新增接口，而是在浏览器端读取已有的持久投影数据，并替换默认 stats 单元。
该插件注册到 conversation.composer.dock 的 stats 单元，优先级为 -1，因此会取代默认的纯文本 stats 行。插件的 host 端 apply() 为空，客户端部分负责 UI 展示。
核心功能¶
上下文占用条¶
插件会在条状区域显示 Used / window tokens，并用颜色表示上下文占用状态：占用较低时为绿色，继续升高时变为琥珀色，接近窗口上限时变为红色。
输入、输出与缓存分离¶
插件会把输入 token 拆分为 cache-read、cache-write 和 uncached，并展示 cache-hit rate。这样可以直接看到当前会话中输入部分由哪些 token 构成，而不是只看到一个总输入数。
吞吐与首字延迟¶
条状区域还会显示 tok/s 和 TTFT。其中 tok/s 表示 decode throughput，TTFT 表示平均 first-token latency。
详情面板¶
点击条状区域可以打开详情面板。面板中可以看到上下文组成、输入拆分、吞吐与 TTFT，以及会话的 turn、step、model 和 tool time。
当详情面板内容超出可视范围时，顶部和底部边缘会出现淡出和模糊效果，表示还可以继续滚动；滚动到端点时，这些边缘效果会消失。
主题与语言¶
插件样式使用 --dsw-* tokens 适配 light/dark 主题，并提供中文和英文两种语言。
数据读取¶
插件读取 tokenUsage、contextPressure、contextBreakdown 和 sessionStats 等持久投影。没有数据时，整行会隐藏，不会显示空占位。
安装与启用¶
从 GitHub 安装¶
下面命令通过 dsh plugin 从 GitHub 安装 hashdiana/dsh-token-usage，并指定 web profile：
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:hashdiana/dsh-token-usage
安装完成后需要重启 web profile，使插件生效：
dsh web
从本地安装¶
如果你本地已经拿到仓库代码，可以使用仓库路径安装。把 <path-to-this-repo> 替换为本地目录路径：
npx -p @deepseek-ai/dsh dsh plugin --profile web add <path-to-this-repo>
同样需要执行：
dsh web
典型用法¶
查看 Token 用量¶
安装并重启后，在 DeepSeek Harness web UI 的 composer 下方可以看到用量条。可以直接查看上下文占用、输入、输出、cache-hit rate、tok/s 和 TTFT。
点击条状区域，打开详情面板，查看更完整的上下文组成、输入拆分、吞吐、TTFT 和会话统计。
临时禁用¶
如果只想临时关闭该插件，而不是卸载，可以在 web profile 的 patch 文件中添加禁用项。路径为：
$DSH_HOME/profiles/web/cordis.patch.yml
添加如下配置：
- id: dsh-token-usage
disabled: true
然后重启：
dsh web
默认 stats 行会恢复显示。重新启用时，删除上面两行配置，并再次重启 dsh web。
开发构建¶
如果你要修改或贡献这个插件，可以在仓库目录中执行：
pnpm install
安装依赖后，运行类型检查：
pnpm typecheck
构建插件产物：
pnpm build
运行测试：
pnpm test
注意：Git 安装会使用已构建好的 lib/，不会在安装时运行构建脚本。因此从 Git 仓库分发或提交代码时，需要包含 lib/ 目录。
适用场景与注意¶
这个插件适合以下几类用户：
- 使用 DeepSeek Harness web UI 进行长会话、长上下文开发的开发者。
- 需要关注 cache-read / cache-write / uncached 构成和 cache-hit rate 的人。
- 希望在 UI 中直接看到
tok/s与TTFT的 DSH 用户。 - 想要替换默认纯文本 stats 行，减少信息阅读成本的社区用户。
使用注意：
- DSH 插件会在当前
dsh进程环境中加载。安装前建议检查源码、许可证和依赖。 - 该插件许可证为 MIT。
- 安装、禁用或重新启用后，都需要重启
dsh web才能生效。 - 通过 Git 安装时，使用的是仓库中已有的
lib/构建产物；如果没有lib/，安装可能无法获得可用插件。 - 该插件是纯客户端插件，host 端
apply()为空，主要影响 web UI 的 stats 展示。
结尾¶
dsh-token-usage 的价值在于把原本挤在 composer 下方的一行文本，变成可扫一眼的 Token 用量条：上下文占用、输入输出缓存分解、吞吐和首字延迟都能直接看到，点击还能打开详情面板查看会话统计。
GitHub 仓库：
https://github.com/hashdiana/dsh-token-usage
