前言¶
用 DSH（DeepSeek Harness）跑智能体会话时，有两个问题经常要回答：这轮对话到底消耗了多少 token，上下文窗口还剩多少。默认的 Web GUI 里只有 Chat 和 Trajectory 两个页，这些数字要么看不见，要么要自己去翻原始记录。
samecorner/dsh-token-usage 解决的就是这件事：它是一个客户端插件，在会话顶部 Tab 栏（Chat / Trajectory 之后）新增一个「Token 用量」页，把整轮对话的 token 明细和上下文占用直接展示出来。下面介绍它的功能、安装方式和使用时需要注意的口径问题。
这是什么¶
dsh-token-usage 是 DSH Web GUI 的 Token 用量分析插件，npm 包名 @samecorner/dsh-client-ui-token-usage，当前版本 0.1.3，MIT 许可，由 samecorner 维护。
它的思路是：host 端的 token-meter、session-stats 模块已经内置在 dsh web 中，会持续产出 tokenUsage、contextPressure、contextBreakdown、sessionStats 等投影数据；插件在浏览器端注册一个 conversation.view slot 条目，把这些投影数据渲染成可视化面板。逐轮级别的数据则由插件客户端从会话事件窗口折叠 assistant/message 的 usage 得到。
作者在 README 中提到，灵感来自 pi-web-token-usage（pi-web 的同类插件），但完全按 DSH 的插件契约重新实现。
核心功能¶
按数据来源分，插件提供这几块内容：
1、整轮 KPI。总 token / 计费 token / 输出 / 缓存读取四张卡片，带数字滚动动画，数据来自 host 端 tokenUsage projection。
2、上下文压力。上下文占用进度条，达到 80% 及以上会警告变色；旁边还有提示缓存命中率、推理占比、平均与峰值单次调用。
3、上下文构成。系统提示 / 工具 schema / 对话内容三段堆叠条，反映新请求的组成估算，来自 host 端 contextBreakdown projection。
4、轮次与步数统计。来自 host 端 sessionStats projection。
5、构成环形图和明细表。按输入 / 缓存读 / 缓存写 / 输出 / 推理拆分，每项带占比微条。
6、逐轮视图。逐轮堆叠柱状图（hover 显示 tooltip）、逐轮明细（含耗时）、累计计费曲线，由客户端从会话事件窗口折叠 usage 计算。
7、按模型拆分。每个模型的 token、调用数、缓存命中率。
8、辅助操作。一键复制 Markdown 报告；「加载更早记录」按钮翻阅更早的轮次。
安装与启用¶
推荐用 npm 一键安装，免编译、免改配置：
# 在哪里执行都可以，dsh 会自动到对应的 profile 目录里跑 pnpm
# （首次使用会自动初始化 profile）
dsh plugin --profile web add @samecorner/dsh-client-ui-token-usage
# 重启 dsh web，顶部即出现「Token 用量」Tab
这个包声明了 dsh.bundle.patch（对应包内的 bundle.patch.yml），dsh plugin add 之后会自动挂载：包被加进 profile 的 bundle 层，不需要手动改 cordis.patch.yml。
有一个前提要注意：如果之前在 cordis.patch.yml 里手动 insert 过同 id 的条目，请先删掉，否则会因重复挂载报错。
更新和卸载也是一条命令：
dsh plugin --profile web update @samecorner/dsh-client-ui-token-usage
dsh plugin --profile web remove @samecorner/dsh-client-ui-token-usage
卸载时，依赖与层列表会自动一并摘除。
源码构建与本地开发¶
想改代码或本地调试，可以走源码构建：
# 1. 构建（需要 node >= 18；依赖只来自 npm 公开包，不需要 DSH 源码）
npm install
npm run build # 产出 lib/client.js + lib/index.js
# 2. 以本地目录安装进 profile（同样走 dsh plugin，自动挂载）
dsh plugin --profile web add /path/to/dsh-token-usage
# 3. 重启 dsh web
目录依赖是链接语义：改代码后重新 npm run build，重启 web 即生效，不需要拷贝或同步文件。
常用的开发命令：
npm run typecheck # tsc --noEmit
npm run build # esbuild：浏览器 bundle + node half
npm run test # 冒烟：loader 形态 + SSR 渲染（不启动 web）
打包格式上有一个硬性要求：lib/client.js 必须带 window.__ModuleLoader__.load({ id, factory }) 包装，react / cordis / ui-slots 等平台模块保持 external。这个包的运行时是零依赖的——package.json 里只有 devDependencies（类型和构建工具）。
如果打算自己写 DSH 客户端插件，仓库里的 docs/client-plugin-dev-guide.zh.md 是一份开发手册，覆盖官方 Demo 目录、完整流程和踩坑清单。
数据口径与已知限制¶
看数字之前，先弄清楚几个口径，避免误读：
- 逐轮明细只覆盖「窗口内已装配且带 usage 的 assistant/message」。被取消的步、usage 缺失的调用不会出现在逐轮表里；整轮合计以 host projection 为准，两者口径可能略有差异。
- 推理 token 计入输出，与 token-meter 口径一致。
- 没有成本估算。DSH 不记录单价，插件不做猜测计费。
- 上下文占用显示的是 token-meter 的近似投影（projectedTokens / contextWindow），不是计费口径。
适用场景与注意事项¶
这个插件适合两类场景：一是长会话开发，需要盯着上下文占用、决定什么时候开新会话；二是成本与效率优化，比如核对提示缓存命中率、比较不同模型的实际消耗。复制 Markdown 报告的功能，也方便把用量数据贴进 issue 或文档里讨论。
两点提醒：
第一，和所有 DSH 插件一样，它以当前 dsh 进程的权限运行。安装前建议先看一下源码（仓库公开）和许可证（MIT），确认没问题再装。
第二，插件依赖 host 端 projection 数据，逐轮视图依赖会话事件窗口内的 usage 字段。如果某些调用本身没有 usage，对应行不会出现，这不是插件坏了，是口径限制。
结尾¶
dsh-token-usage 做的事情很集中：把 DSH 内置的 token 投影数据变成一个看得懂的分析页。如果你在用 dsh web 跑智能体会话，装上它，重启后顶部多一个「Token 用量」Tab，就能直接回答「这次会话花了多少 token、上下文还剩多少」这类问题。
- GitHub 仓库：https://github.com/samecorner/dsh-token-usage
- 社区插件目录页：https://www.skillhub.cn/plugins/samecorner/dsh-token-usage
（社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。）
