前言¶

在 DSH（DeepSeek Harness）里跑多会话、长链路智能体时，用量分散在各次 session 日志与事件流里，很难一眼看清「一共花了多少 billed token、缓存读写各占多少、按你的单价大概多少钱」。手工翻日志或单独跑统计脚本，成本高且难和日常界面联动。

@shallbay/dsh-token-stats 是社区维护的双面插件：宿主侧汇总全部会话用量并提供看板与 API，客户端侧在侧边栏注册「Token 用量」入口。下面介绍它的定位、能力与安装用法；事实以 GitHub 仓库 README 为准。

这是什么¶

• 包名：@shallbay/dsh-token-stats（npm 发布名；源码开发副本在 profile 内以 @deepseek-ai/dsh-token-stats 链接）
• 维护者：ShallBay
• 分类：客户端（同时包含宿主 bundle 与 Web 客户端注入）
• 许可：MIT
• 目录页：skillhub.cn/plugins/ShallBay/dsh-token-stats

插件在 Harness 范围内聚合 billed token：未缓存输入、缓存读取、缓存写入、输出，并按高峰 / 低谷给出人民币费用预估；看板路由为 /token-stats，支持定时与手动刷新。

双面架构¶

README 将插件拆成两半，职责不同但同一包内交付：

宿主半

• 汇总全部会话的 billed token 用量。
• 提供看板页面与实时数据接口（/api/token-stats/refresh、/api/token-stats/data）。
• 数据源与 dsh-token-meter 共用 session/event 事件流（v3，事件驱动），刷新时不再全量扫描日志。

客户端半

• 在侧边栏底部（设置上方）注册「Token 用量」入口。
• Web 端：点击后在新标签页打开 /token-stats。
• 桌面端：在应用内弹窗（iframe 覆盖层）打开看板；Electron shell 会拦截 window.open 且仅把 http(s) 交给系统浏览器，因此桌面端必须走应用内弹窗。

核心功能¶

用量与费用展示¶

看板按供应商 / 模型展示三项计费维度相关指标：缓存命中、缓存未命中、输出；并区分高峰与低谷单价。默认使用内置单价估算，可在看板「价格」中按模型修改，并保存在浏览器 localStorage（键 dsh-token-stats/pricing/v1）。升级插件不会清掉这些自定义价格。

页面每 60 秒自动轮询刷新，并保留手动刷新按钮。

数据同步（v3）¶

主路径是消费与 dsh-token-meter 相同的 session/event 流，按 session:turn:step 增量 upsert；兼容 0.1.x 的 assistant/chunk 与 0.2.x 的 assistant/message、assistant/attempt 等事件形态。0.2.0 起对 LLM 重试的计费：同一 turn/step 的重试会追加 #n 键（如 1:1#2），与旧 rollup 合并幂等。

冷历史会话：优先从 $DSH_HOME/token-stats-rollup.<profile>.json 恢复；否则一次性扫描日志；之后仅对 mtime/size 变化的会话文件做增量重解析。会话日志匹配 session[.<version>].jsonl[.zstd]（含 session.jsonl.zstd、session.v3.jsonl.zstd、session.v4.jsonl.zstd 等）。

页面取数优先级：/api/token-stats/refresh（本插件）→ /api/refresh（独立 exe）→ 本地 token-usage.json。

路由¶

嵌入模式（?embed=1 或 iframe）下头部与内边距更紧凑，统计卡片自适应列数，宽屏时「用量概览」与「使用趋势」可并排。

安装与启用¶

插件以当前 DSH 进程权限运行；安装前建议阅读仓库源码与 MIT 许可证。社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系，属「一切皆插件」生态中的第三方包。

没有 dsh 命令时，可在桌面端 Plugins → 添加插件 填入 @shallbay/dsh-token-stats，或调用安装目录下 resources\runtime\cli\bin\dsh.cmd。

桌面端：

dsh plugin --profile desktop add @shallbay/dsh-token-stats

Web 端：

dsh plugin --profile web add @shallbay/dsh-token-stats

装完后必须重启对应 surface（bundle 仅在 profile 加载时读取）：

• 桌面端：完全退出并重开 App；或在 Plugins 页将 dsh-token-stats 关闭再打开以热加载。
• Web 端：Restart-Service dshweb。

客户端模块可热更新；若侧边栏无入口，先强制刷新（Ctrl+F5）。

安装指定版本示例（README 中的版本号，以 registry 实际发布为准）：

dsh plugin --profile desktop add @shallbay/dsh-token-stats@1.2.0

查看已装版本：

dsh plugin --profile desktop why @shallbay/dsh-token-stats
npm view @shallbay/dsh-token-stats version --registry=https://registry.npmjs.org/

典型用法¶

1. 按上文命令为 desktop 或 web profile 安装插件并重启 surface。
2. 在侧边栏底部（设置上方）点击「Token 用量」。
3. Web 端在新标签查看 /token-stats；桌面端在应用内弹窗查看，按 Esc 关闭。
4. 若费用与账单不符，在看板价格表中按模型调整高峰 / 低谷单价并保存（本地持久化）。
5. 需要最新汇总时点击手动刷新，或等待 60 秒自动轮询。

升级与卸载¶

包管理器不会自动升级已装版本，需先 remove 再 add，然后同样重启 surface：

dsh plugin --profile desktop remove @shallbay/dsh-token-stats
dsh plugin --profile desktop add    @shallbay/dsh-token-stats

卸载示例：

dsh plugin --profile desktop remove @shallbay/dsh-token-stats
dsh plugin --profile web remove @shallbay/dsh-token-stats

重启后侧边栏入口与 /token-stats 路由会消失。以下数据不会自动删除，需自行清理：

适用场景与注意¶

适合谁

• 长期在 DSH 上跑多会话智能体，需要 Harness 级 billed token 汇总与趋势，而不是单会话肉眼统计。
• 希望用高峰 / 低谷单价做人民币粗算，并能在看板里按模型改价。
• Web 与桌面端都要统一入口：Web 新标签、桌面应用内弹窗。

常见问题（来自 README）

• 侧边栏无入口：Ctrl+F5；确认 profile 的 dsh.profile.bundles 含 @shallbay/dsh-token-stats 并已重启。
• /token-stats 404：插件未加载，检查 bundle 与宿主日志中的 token-stats 报错。
• 数字全 0：需至少一次带用量的事件；旧会话首次加载可能触发一次性日志扫描播种。
• 费用偏差：改看板价格表中的模型单价。

开发或离线可从源码执行 install.ps1（见仓库 README）；不要手工往 cordis.patch.yml 追加 insert 行，应通过 dsh.profile.bundles 持久化。

结尾¶

@shallbay/dsh-token-stats 把 Harness 范围内的 billed token 与费用预估集中到 /token-stats，并通过侧边栏「Token 用量」接到日常操作路径；数据侧与 token-meter 事件流对齐，并支持 profile 级 rollup 与增量刷新。

• 目录页：https://www.skillhub.cn/plugins/ShallBay/dsh-token-stats
• 源码与文档：https://github.com/ShallBay/dsh-token-stats