dsh-ui-web/packages/dsh-live-stats

一句话定位

给 DSH Web 的会话状态行加上实时输入/输出 token 估算与生成吞吐速率显示，响应流式输出时数字随 chunks 持续更新，并在 provider 真正返回 usage 时被精确值替换。

核心能力

实时估算输入 token：按字符数加块/消息框架折算响应流开始前的输入量，并把系统提示与工具 schema 也计入
实时估算输出 token：从 text-delta/reasoning-delta/tool-call-delta 流式 chunks 累加，每个新 chunk 触发一次读数刷新
自动替换为精确值：当 provider 返回 usage chunk 或最终消息时，立即用真实值覆盖该步骤之前的启发式估算
显示生成吞吐 TPS：在会话状态行渲染 TPS 31.4 tok/s 形式的吞吐速率，按活跃步骤的输出 token / 墙钟耗时计算
常驻速率显示：一旦任何步骤测得吞吐，新步骤在产出首个 chunk 之前、或者遇到无速率步骤时回退到最近一次测得值，状态行不闪烁消失
提供设置面板：浏览器端在 Web UI 插件组里挂一个设置卡片，可视化编辑三个估算参数和总开关，修改后无需重启即生效

技术实现

语言: TypeScript（peer 依赖 React 18.2，dsh.client.platform="web"）
关键依赖: @deepseek-ai/dsh-session-projection（投影宿主）、schemastery（设置 schema 校验）、zod（投影读数边界 schema）、@deepseek-ai/dsh-token-meter（读数类型来源）
架构模式: Cordis 双向插件。Host 半体注册名为 liveTokenUsage 的可重放会话投影（ctx.sessionProjections.register），把估算参数冻结进折叠闭包；客户端半体在 conversation.composer.dock 槽挂载 TPS 行，在 web-ui.plugin.item 槽挂载设置卡片
入口文件: 宿主侧 src/index.ts（导出 inject/Config/apply），客户端 src/client/index.ts；纯函数核心在 src/estimator.ts（字符密度估算）和 src/projection.ts（事件折叠 + TPS 派生）

适用场景

当你在 DSH Web 上让模型做长任务时，只看到最终 token 数会觉得不踏实：这个插件把"模型现在生成多快""这段回答大约多少 token"做成实时读数贴在状态行上，适合需要即时观察吞吐与用量的重度用户，也适合对 KV 缓存成本敏感的工程师用来对比不同模型/参数下的实际速率。

前置依赖与兼容性

依赖	最低版本	说明
DSH Web	0.1.0-rc.6	peerDependencies 全部钉在 `^0.1.0-rc.6`（含 dsh-client-runtime、dsh-client-connection、dsh-client-ui-conversation、dsh-client-ui-settings、dsh-client-ui-slots、dsh-invariants、dsh-llm、dsh-session、dsh-session-projection、dsh-settings、dsh-token-meter）
React	18.2.0	客户端卡片与 TPS 行均使用 React 组件
平台	跨平台（macOS / Windows / Linux）	运行时不限操作系统，但 `dsh.client.platform="web"`，仅渲染在 Web 宿主里
原生模块	无	全部逻辑在 TypeScript 与 React 内完成，没有 node-gyp 依赖

安装方式

dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-live-stats

安装后重启 dsh web，会话状态行出现 TPS 组；也可作为普通 overlay 行加入 ~/.dsh/config.yaml（保存即热加载）：

- insert:
    - id: live-stats
      name: '@captain1275/dsh-live-stats'
      config:
        charsPerToken: 4
        blockOverhead: 4
        roleOverhead: 4

配置项

配置	类型	说明	默认值
`enabled`	布尔	总开关，关闭后停止 token 估算与吞吐追踪，但仍注册投影骨架	`true`
`charsPerToken`	数字	大约多少个文本字符折算为 1 个 token；中文密度高可调到 1.5 上下	`4`
`blockOverhead`	非负整数	每个内容块（文本/工具调用/工具结果）固定的框架 token 数	`4`
`roleOverhead`	非负整数	每条消息或助手响应固定的框架 token 数	`4`

三个估算参数必须在 charsPerToken 是正有限数、blockOverhead 与 roleOverhead 是非负整数时才生效，否则会在加载阶段抛错。设置面板修改后，宿主会丢弃旧投影并用新参数重新折叠会话日志，无需重启 dsh web。

常见问题

Q: 安装后需要重启 DSH Web 吗？

A: 需要。投影注册发生在 host 进程里，安装或卸载后必须重启 dsh web 才会生效；浏览器侧硬刷新不能替代宿主重启。

Q: 它会不会改变实际发送给模型的 token 数？

A: 不会。插件不注入提示段、不注册工具、不发出 session 事件，对模型端每个请求的 token 影响为零，也不会对系统提示的 KV 缓存稳定性造成影响。

Q: charsPerToken 该填多少？

A: 默认 4 字符/token 对纯 ASCII 足够，但对中文会低估。可在设置面板或 ~/.dsh/config.yaml 中下调到 1.5 左右，再观察 ~ 估算与 provider 实际返回值的偏差来微调。

Q: 状态行里数字前面的 ~ 是什么意思？

A: 表示那是按字符数推算的启发式估算。一旦 provider 在流式过程中返回 usage chunk 或最终消息带 usage，估算会被精确值原地替换；中途重试会替换该步骤之前的估算，被中止的回合会移除其未结算估算。

Q: 卸载后需要清理数据吗？

A: 插件本身不持久化任何数据，卸载后下次启动 dsh web 不再注册 liveTokenUsage 投影，会话状态行自动回到未含 TPS 组的样式，无需手动清缓存或数据。

Q: 支持 TUI 或桌面端吗？

A: 暂不支持。当前 TPS 行只渲染在 DSH Web 的会话状态行（composer dock），TUI、桌面端和移动端没有等价显示位置。

上手难度

入门 — 安装一行命令、重启 DSH Web 即可看到效果，三个估算参数都给了默认值；只有发现估算偏差较大时才需要调整。

已知问题与限制

启发式估算：~ 标记的输入/输出总量在 provider 用量到达前只是字符数近似，精确的缓存命中统计始终来自 DSH 自带的 token 用量投影，本插件不会替代那条权威路径
仅 Web：TPS 组渲染在 DSH Web 的 composer dock 内，TUI、桌面端、移动端没有等价显示位置
单一活跃步骤：每个会话只跟踪一个活跃步骤，状态行显示该会话视图；并发会话各自拥有独立的投影互不干扰
密度假设：charsPerToken=4 对纯 ASCII 高估、对中文低估，若估算偏差明显可按部署微调该值
不影响模型体验：插件对模型的提示/工具/事件流零侵入，仅消费持久化事件流做只读渲染

插件	功能
dsh-task-board	侧边栏任务看板：多列 kanban、真实执行（驱动 agent 会话）、定时执行（cron）
dsh-ssh	SSH 运维：主机管理、远程执行、SFTP 传输、隧道、集群并发、Web 终端
dsh-aionui-panel	右侧「预览 / 文件 / 变更」面板：文件树、多格式预览、git 操作、文件拖拽
dsh-git-graph	会话头部 git 分支选择器 + 提交图
dsh-live-stats	实时 token 估算与生成速度
dsh-full-stats	完整统计行：覆盖官方统计（不省略）+ 运行状态指示 + 自定义状态文本（含替换官方 Deep diving...）
dsh-usage-dashboard	用量看板：彩色统计卡 / 近 14 天趋势 / 模型分布 / 会话排行 / 费用估算
dsh-web-ui-settings	设置页「Web UI 插件」配置组 + 「人格设定」+「关于」版权页
dsh-web-ui-all	聚合包：一键安装全部插件

dsh-ui-web/packages/dsh-live-stats

安装

一句话定位

核心能力

技术实现

适用场景

前置依赖与兼容性

安装方式

配置项

常见问题

上手难度

已知问题与限制

特性

极光（Aurora）皮肤（支持动态背景）

DeepSeek 看板娘（养成系）

Skill 人格设定

用量看板

功能插件

皮肤中心

安装

方式一：npm（推荐，已发布）

方式二：从源码（开发）

开发

目录结构

版权与许可