前言¶
在 DSH 里跑 QQ 桥接时，模型每回合都会留下 token 用量，但默认往往只能看到单次对话或全局日志，很难回答「哪个群、哪段私聊最费 token」「缓存命中率如何」「最近一周趋势怎样」。若只靠 grep 或手工汇总 token-usage.jsonl，成本高且不利于对比占比与时段分布。dsh-token-flow 是社区维护的 DSH 插件，只读桥接写入的用量文件，在 Harness 内提供表格、图表与导出，把消耗按会话和时间去向可视化。
这是什么¶
dsh-token-flow（维护者 xiaole3349，社区目录分类为「记忆」）定位是：统计各群 / 私聊的 token 消耗与流向。数据来源是 QQ 桥接写下的 token-usage.jsonl（每个回合一行，字段含 cacheHit、cacheMiss、output、reasoning）。插件只读磁盘，不写任何文件，也不修改会话状态。
核心功能¶
装好后通过 Harness 提供的 Web 页面与 HTTP 接口查看聚合结果（具体路径见下文「典型用法」）。
概览页（README 描述）包括：
- 按会话排序的表格：回合数、未命中、命中、输出、总 token、命中率、均值、占比
- 两张饼图：总 token 占比、实付（未命中 + 输出）占比
- 各群按天的多线图、每日总量折线、未命中按天
- 峰 / 谷拆分、按小时分布、最贵的 10 个回合
- 点击某行进入该会话详情；右上角可导出 CSV
HTTP 接口（与页面同源，可用 days 筛选时间范围）：
/dsh-token-flow/api?days=7（days=0表示全部历史）/dsh-token-flow/csv?days=7/dsh-token-flow/detail?days=7&key=group:<群号>
辅助逻辑（README 说明）：群名优先从 SnowLuma 的群列表读取（缓存 10 分钟），取不到时退回磁盘缓存。「峰 / 谷」按工作日 09:00–12:00、14:00–18:00 粗分，不查节假日表。
安装与启用¶
插件随 DSH 生态以 bundle 形式安装，官方 README 给出两种方式，不要自行拼接未在文档出现的安装命令。
先在本地取得插件目录（例如从 GitHub 仓库 下载 release 或拷贝已解压目录），在该目录下执行：
plugin_manager install_bundle <本目录>
或将 patch 写入 profile 的 cordis.patch.yml：
- insert:
- id: token-flow
name: dsh-token-flow
package.json 中声明版本为 0.1.0，许可证 MIT；入口为 lib/index.js，bundle 补丁文件为 cordis.patch.yml。
安装完成后重启或按你当前 DSH 流程加载插件，再访问页面与接口。
典型用法¶
- 确认 QQ 桥接已在运行，且持续向
token-usage.jsonl追加每回合记录。 - 在浏览器打开
<DSH 地址>/dsh-token-flow，默认可按 README 使用最近 7 天等视图（页面内筛选与 API 的days参数一致）。 - 需要离线分析时，使用导出或 CSV 接口，例如：
<DSH 地址>/dsh-token-flow/csv?days=7
- 查看单个群会话明细时，使用 detail 接口，
key形如group:<群号>：
<DSH 地址>/dsh-token-flow/detail?days=7&key=group:<群号>
- 程序化拉取 JSON 聚合：
<DSH 地址>/dsh-token-flow/api?days=7
将 <DSH 地址> 替换为你实际部署的 Harness 基址。
适用场景与注意¶
适合：已在 DSH 中使用 QQ 桥接、并希望按群 / 私聊对比 token、命中率与时间分布的开发者或运维；需要 CSV 或 API 做二次统计的场景。
注意：
- 无
token-usage.jsonl或桥接未写盘时，页面无有效数据；插件不会代写该文件。 - 群名依赖 SnowLuma 群列表与本地缓存，名称可能短暂与 QQ 客户端不一致。
- 峰 / 谷划分是工作时段 heuristic，不适合作为计费或 SLA 的唯一依据。
- 插件以当前 DSH 进程权限读盘并提供 Web 路由；安装前应阅读 源码与 MIT 许可，确认路径与数据范围符合你的部署策略。DSH 社区插件目录（SkillHub 条目）为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-token-flow 把桥接已有的 token-usage.jsonl 转成会话维度的表格、图表与导出，只读、不碰会话，适合在 Harness 内快速看清 token 流向。进一步了解可访问社区目录页与 GitHub 仓库：
- https://www.skillhub.cn/plugins/xiaole3349/dsh-token-flow
- https://github.com/xiaole3349/dsh-token-flow
