dsh-token-total：DSH Token 用量统计看板与会话树用量分析

前言¶

在智能体开发中，能看清「用量」是控制成本与优化行为的前提。但 DSH 原生的统计多聚焦于单次请求，缺少全局看板与会话树的完整视图。本插件在 DSH 侧边栏提供一个独立的用量看板，并在会话层面接管原有的 Token 胶囊，展示主智能体与全部子智能体的合计与明细，从而让一次会话的真实消耗一目了然。

插件简介¶

dsh-token-total 是一个 DSH Web 插件，提供 Token 用量统计看板与会话树用量分析功能。它通过三个入口整合统计与明细：侧边栏的统计看板、会话输入框下方的增强胶囊，以及会话详情页新增的「用量」标签页。所有图表均使用手写 SVG，不依赖第三方图表库，并适配 DSH 的明暗主题。

核心功能¶

统计看板¶

统计看板位于左侧边栏的插件区（与原生「插件」页并列），打开后分为上、中、下三部分。

上部¶

• 快捷筛选：支持今日、近 3 天、近 7 天、近 1 月、近 3 月以及自定义起止日期。
• 六个汇总卡片：总 Tokens、输入 Tokens、输出 Tokens、缓存 Tokens、缓存命中率、请求数量。Token 数量使用 K/M/B 紧凑单位，下方显示精确值。「请求数量」在存在失败调用时，会额外显示「失败 N · 占比」。
• 活跃热力图：GitHub 风格，颜色深浅表示每日 token 消耗量，图例分五档。
• 刷新：仅重取聚合结果，不重建统计。

中部¶

• 缓存命中率趋势：平滑折线，展示随时间变化的命中率。
• 分模型柱状图：堆叠柱表示实际 token 消耗，不同模型用不同颜色；右侧轴显示 0–100% 缓存命中率。悬浮时显示该时间桶内各模型的 token 与命中率。
• 横轴粒度：今日 / 近 3 天按小时分桶，更长时间段按天分桶。

下部¶

• 按模型 Top5：按模型选择器的显示名称跨供应商聚合，展示模型名、总 Tokens、缓存命中率（多供应商时附供应商列表）。模型名称归一化规则为忽略大小写、统一空格、下划线和连字符为 -，但保留版本号与后缀差异。
• 按供应商 Top5：聚合单个供应商下所有模型，展示供应商名、总 Tokens、缓存命中率。

单会话统计¶

在会话输入框下方，原生的「用时与速度 / Token 用量」两枚胶囊被接管并增强：

• Token 胶囊显示整棵会话树（主智能体 + 全部子智能体）的合计，点击弹窗分为「主智能体 / 子智能体 / 会话合计」三行，并给出子智能体会话数。
• 子智能体通过日志头的 parentSession 串成树，插件按需重放日志汇总，使用与主会话相同的 (turn, step) 去重规则，并跳过 fork 继承的事件前缀。
• 会话 Token 明细始终开启：列出未命中缓存、缓存读 / 写、输出等各部分。
• 流式吞吐速度始终开启：输出过程中显示估算的解码速度，输出结束后回到会话累计的精确值。
• 底部胶囊的缓存命中率始终显示两位小数，不再提供开关。

会话「用量」页¶

每个会话详情页新增「用量」标签，与原生「对话 / 轨迹」并列，不改变视图导航结构。

• 两行统计卡：第一行为请求数量（含失败数）、总 tokens（含精确值）、缓存命中率（含命中 token）、token 速度（含平均首 token）；第二行为输入、输出、缓存读取、缓存写入四个 token 桶。不显示费用。
• 子代理明细：使用子代理的真实名称（取自标签，缺失时回退到会话标题、工作目录或会话 id），与按模型明细并排展示，窄视口自动堆叠。长名称可悬浮查看全名，token 数同样可悬浮查看精确值。按模型明细的名称使用模型选择器的显示名称，路由 id 保留在悬浮提示中。
• 请求记录按轮折叠：压缩调用归入独立分组，默认全部折叠。展开某一轮可查看该轮每一次请求的时间、模型、tokens、命中率、状态与入 / 出 / 读 / 写明细。失败尝试、实际重试、压缩调用均纳入统计，仅继承的父会话历史不重复计算。
• 页面每 1.5 秒串行读取当前会话明细，切换或离开标签页时取消请求与计时器。统计包含本会话及所有后代的自有历史日志，缺失的首 token / 速度显示 —，读取错误时保留上次成功结果。

数据来源与统计口径¶

• 事件来源：sessionPersistence 的会话日志。兼容 assistant/message 顶层 usage，也读取消息及失败 assistant/attempt 的原始流式用量；同一次请求以最后一份用量为准，修正值按差额更新。插件订阅 session/event 实时增量累加，同时一次性回扫已有历史会话；llm/retry-started 会清空当前 (turn, step) 槽位，因此失败尝试和后续重试分别计入，不重复累加。
• 本地持久化：聚合结果写入 storage-domain 的 token_total_history 域（$DSH_HOME/storages/ 下），纯本地、无外部依赖。回扫游标按会话记录已消费的事件序号，重启后从断点继续。
• 单会话统计：不走聚合存储，而是按需重放该会话及全部子孙会话的自有日志；已加载会话优先使用实时事件快照，结果缓存 4 秒，任意会话的新事件都会使缓存失效。前端从首次读取起每 4 秒刷新，显示时使用原生实时主会话用量、主会话压缩调用用量与子树用量之和；切换会话时立即清除旧会话读数。
• 缓存命中率 = 缓存命中 token ÷ 输入 token 总量（命中 + 未命中）。
• 失败数量：以宿主记录的 assistant/attempt 事件为准。宿主只有在流以错误结束、或调用在提交任何内容之前被取消时才写 assistant/attempt，其余调用一律写 assistant/message。失败数是请求数的子集，不额外计入请求；失败调用若在流中断前已上报用量，token 仍按用量计入。老版本升级后会有一次只写失败数的增量回扫。

HTTP 接口¶

宿主侧注册前缀路由 /token-total/api，所有接口均为 POST + JSON：

请求经过与官方 /api 网关同源的信任栅栏（Host / Origin / sec-fetch-site 三重校验）。

配置¶

安装与启用¶

安装命令如下：

dsh plugin --profile <profile> add dsh-token-total@latest

本地开发时直接指向目录：

dsh plugin --profile <profile> add "file:D:\work\dsh-token-total"

package.json 里的 dsh.bundle.patch 会让 CLI 在安装后把本插件追加进该 profile 的 dsh.profile.bundles，重启后自动挂载，无需手动修改 profile 配置。若该 profile 的 cordis.patch.yml 里还保留旧的手工挂载行，请先删除，否则会重复挂载（两个宿主实例、两条重复路由）。

Electron 桌面端的 desktop profile 由应用独占管理，CLI 会拒绝写入（profile "desktop" is managed exclusively by the Electron application）。请使用应用内的插件管理器安装，或另建一个 profile 进行验证。

pnpm run build 只更新本项目的构建产物，不会自动覆盖桌面 profile 已安装的插件副本。桌面端请在应用内的插件管理器更新 / 安装本地构建后的插件，再按提示重启宿主并刷新页面；不要直接覆盖运行中的 profile。

兼容性¶

• DSH >= 0.1.7-rc.1（peerDependencies）；实测运行于 0.2.1-rc.2，会话日志格式 v3 与 v4 均可读取（v3 走 alpha 的 open/read 接口，v4 走句柄分页读取）。
• 浏览器半区只依赖 @deepseek-ai/dsh-client-{locale,ui-slots,ui-primitives} 与 React 18，不引入任何 Node 内置模块。

适用场景与注意¶

• 适合需要全局用量概览、按模型与供应商分析、以及会话树级 Token 明细的开发者。
• 插件以当前 DSH 进程的权限运行，安装前建议查看源码与许可证（MIT）。
• 桌面端更新时请通过应用内的插件管理器进行，避免直接覆盖运行中的 profile。

总结¶

dsh-token-total 在 DSH 侧边栏提供统计看板，在会话层面接管并增强 Token 胶囊，并在会话详情页新增「用量」标签页，展示完整的会话树用量与按轮折叠的请求记录。所有数据来源于本地会话日志，不依赖外部服务，适合需要精细化用量分析的开发场景。

• 插件目录页：https://www.skillhub.cn/plugins/GaoHu1997/dsh-token-total
• GitHub 仓库：https://github.com/GaoHu1997/dsh-token-total