dsh-usage-dash

@mzzsfy/dsh-usage-dash

用量统计面板(dsh 插件)。天/小时/分钟三粒度 token 与请求统计,设置页自绘面板:汇总卡、活动热力图、缓存命中率曲线、模型 donut 与列表、回扫状态行、会话底栏追加与回合费用芯片,支持 en/zh 双语与可选费用估算。复刻自 HaoyueQin/dsh-usage-statistics-panel,感谢原作者。

功能(全阶段已交付)

设置页「使用统计」区块:

• 三粒度视图,全部支持自定义时间范围:天(7/30/90 天/自定义日期段)、小时(24 小时/3 天/7 天/15 天/自定义时刻段)、分钟(3 小时/24 小时/3 天/7 天/自定义时刻段,10 分钟桶粒度),预设挡为滚动窗口;自定义时刻段为起止 datetime 双输入,两端归一到桶边界(小时取所在整点、分钟起点对齐 10 分钟且终点保留原分钟,均闭区间),跨度上限与数据保留期一致(小时 15 天、分钟 7 天,超限自动钳起点),首次切到自定义挡预填最近 24 小时,时/分两视图共享同一对自定义输入;已知限制:自定义输入残缺(任一端为空)时面板不发请求且图表静默空白,与天视图行为一致,交互反馈留待后续增强
• 汇总卡六张:Tokens 用量(服务商总口径)、会话数量、请求数量、最常用模型、平均缓存命中率、活跃天数(恒按天口径,不随视图切换);配置定价规则后 Tokens 卡头部行右侧显示估算费用
• 活动热力图:GitHub 风格周列×星期行,26 周窗口,五档色阶,悬停明细(配置定价规则后附「费用 ≈」估算行,受「费用显示」开关;费用数据依赖小时桶保留期,仅最近 15 天的天显示,更早的天无该行);仅按天视图展示
• 缓存命中率曲线:日粒度命中率 + 右侧副轴,并叠加平均生成速度曲线与首 token 延迟曲线(各自单独颜色,读数走悬停;仅含配对数据的槽参与,整图无数据不绘制),悬停显示当前时段命中率、平均生成速度、首 token 延迟与 token 明细(配置定价规则后附当前时段估算费用行,受「费用显示」开关;三粒度趋势图通用)
• 模型 donut 与列表:按 token 排序的模型占比环形图(中心为总量,模型不超过 5 个时全展示,超过时折叠为前 4 +「其他」,「其他」可展开),每行名称两行展示(厂商/模型名),右侧三排:第一排 token 数·占比,第二排输入输出占比构成(缓存/输入/输出 三段各占该模型 token 总量,缓存=读+写,三段合计 100%,无四桶数据不显示),第三排估算费用·TTFT·生成速度(费用需配置定价规则,TTFT/速度无配对数据不显示),悬停明细含输入/缓存读/缓存写/输出四桶 token 拆分并联动
• 三粒度堆叠柱状趋势图(数据量大时裁最旧并提示);节头「金额」开关把柱状图从 token 消耗切到金额消耗——柱按模型堆叠估算费用,标题与左轴同步切金额读数(悬停明细保持 token 口径与估算费用行不变,命中率/速度/首 token 延迟曲线不受影响),三粒度通用;开关仅在存在正计价数据时显示(未配置规则或全量未计价时不渲染,避免全零金额柱误导);图例可点击切换显隐:点击单选(仅显示该项,左轴刻度按可见项归一)/再点恢复全部,Ctrl+点击多选,隐藏最后一项无效;悬停明细按当前时段数据展示,零用量模型不显示,全零时段不显示悬浮框
• 回扫状态行默认隐藏:首次启用自动回扫历史会话,运行中显示进度(常显);右上角为折叠箭头与刷新图标,折叠层内展开扫描异常日志块(逐条:时间/类型/明细,计数即明细条数,上限 200 条超限丢最旧,重建时清空)与「重建」入口(二次确认 3 秒后清库重扫),采集错误常显;折叠且有待读信息(异常日志或写入失败)时箭头带红点提醒,展开后消失;工具栏分主区与右侧操作区,窄宽度时挡位组在主区内换行
• 会话底栏追加(append 模式):本插件在官方 activity/usage 胶囊之后仅显示估算费用,不另建明细按钮或浮层。精确缓存命中率开关(cachePrecision)原位修改官方 usage 胶囊的命中率文字、按钮 aria-label 与官方弹窗原命中率 dd,统一显示两位小数;关闭开关或卸载增强时还原,保留官方节点与交互。「会话 Token 明细」开关(tokenDetail)只在已打开的官方 [data-session-stats-usage] 用量弹窗 dl 末尾追加「输入合计（含缓存）」(未缓存输入+缓存读+缓存写),仅当 cacheWriteTokens > 0 再追加「未命中合计（含缓存写入）」(未缓存输入+缓存写入)。合计使用完整千分位计数,官方已有的总量、缓存读写、输出与命中率不重复追加;无输入用量时不追加零值合计。偏好卡三个开关仍默认全开,已有偏好继续生效;「费用显示」控制底栏费用、趋势 tooltip 费用行与回合费用芯片。官方弹窗关闭时不挂载补充行;空用量无插件可见条目,精度或明细单独开启均不产生底栏入口。官方未公开用量弹窗扩展 slot,上述增强依赖宿主 DOM 语义标记,标记改变或无法唯一确认弹窗归属时停用相应增强,底栏费用仍独立显示。
• 回合费用芯片:经官方 conversation.chat.assistant-actions 槽注入动作行(复制与分支图标之间,官方赞/踩与上下文跳转同排),每轮对话结束后显示该轮估算费用(悬停 title 带 token 摘要与估算口径;显隐节奏随官方动作行——最新一轮常显,历史轮悬停显现;受「费用显示」开关;官方用量芯片弹窗已有 token 明细,芯片只承载费用)。旧宿主无该插槽时告警禁用
• 定价规则编辑器:设置面板内按模型分组编辑,组头 = 模型键(整组一次改名,改后即时重新聚合)+ 删除整组;组内 = 默认价槽(价格四桶,不设条件——附加规则全不命中时兜底,禁排序/删除)+ 附加计费规则列表(四桶单价 + 条件组合,「+添加条件」追加条件行,行内下拉切换类型,规则带 ↑/↓ 调序与删除),「添加额外计费规则」追加一条(默认带全天时段条件);货币为全局切换(「定价规则」标题右侧,仅 ¥/$ 两档,整表统一),显式「保存」整表写入
• 双语:跟随宿主语言设置(设置 → 通用 → 语言)即时切换 en/zh
• 数据 API 守卫:POST 同源校验 + JSON content-type(与 dsh-usage-panel 同构),局域网远程访问可用

口径:token 总量 = 未缓存输入 + 输出 + 缓存读 + 缓存写;命中率 = 缓存读 / (缓存读 + 未缓存输入 + 缓存写);桶按 host 本地时区。聚合响应 models 数组每模型带 inputTokens/outputTokens/cacheReadTokens/cacheWriteTokens 四桶拆分(与定价四桶同口径),模型列表据此展示输入输出对比。平均生成速度 = decode 配对分子 ÷ 解码时长,两者均取官方吞吐口径(与官方 session-stats 投影同构):解码时长为该步首 token 时刻(首个产出 token 的 attempt 流,回落 message 自带流)到 usage 汇报时刻,不含首 token 前的排队与提示处理等待;首 token 延迟(TTFT)= 首 token 时刻 − step/start(起点不随 llm/retry-started 重置,即含失败尝试时间)。首 token 时刻在 chunk token 样本上不可得,由后续 usage 报告(message 为主)补发零桶 timing 增量行承载(decodeTokens 与时长同源配对,不重复计 token);存量旧行(时长为旧全时长口径)速度分子回落输出 token,聚合随新数据自然收敛,重建(重扫)可全量按新口径重建。保留策略:天桶永久,小时桶固定 15 天,分钟桶默认 7 天且上限 7 天(设置项 minuteRetentionDays,0 = 禁用分钟桶)。

写入模型:样本先同步合并进内存 pending,按 2 秒周期批量落盘(单布局存储域每次持久化写都全量重发布 unit 文档,合并把每样本 3 次写降为每脏行 1 次,回扫万级样本写放大降约 99%);查询前自动 flush 保证读己之写;flush 失败的行留 pending 下轮重试并经异常日志可观测,崩溃丢失窗口 = flush 周期,统计可由会话重扫重建。

定价与费用估算

规则存于设置存储域,经 GET/POST /api/usage-dash/pricing 读写(响应含单调 revision);设置面板编辑器为常规入口。

规则形态:{ model, currency, price: { input, output, cacheRead, cacheWrite }, conditions },单价单位固定「每百万 token」。货币为编辑器级全局设置:「定价规则」标题右侧切换,仅 ¥/$ 两档(无「空」档),打开编辑器即按首个非空货币归一显示(无非空回落 ¥),切换或保存后整表统一;wire 形态不变(仍为逐规则字段),存量空货币规则经编辑器保存后归一。费用显示为全局价格定位:汇总卡/趋势悬浮/模型列表/底栏费用项/回合费用芯片的货币符号统一取规则表首个非空货币(数值仍按命中规则单价计算),切换并保存后全部显示点随之变更。

• 模型匹配:model 为两段式 vendor/model(首个 / 分段,模型段允许含 /),两段各自可 * 通配;匹配链为 全名精确 > 模型名精确(*/model,跨供应商同模型名同价)> 供应商精确(vendor/*,同供应商多模型同价)> */* 全通,档位相同按数组序取首个命中,高档条件不满足逐层落低档;全链无命中不计费用并计 unpriced。提交(编辑器保存与 pricing POST)强制两段式,单段旧形态(* 或裸名)不再合法
• 同模型多规则(分时段定价):组内附加计费规则从上到下首个「条件全过」者生效,全不命中落组内默认价(无条件规则,恒兜底);附加规则卡带 ↑/↓ 调序。注意同一模型的多条规则请使用相同的模型键写法——不同写法(如 */model 与 vendor/model)分属不同档位,按档位优先级而非数组序取胜
• 条件类型(数组内 AND,空数组恒生效),所有范围条件统一双侧包含(含起始含结束,from===to 即单点/单日;相邻区间请写 1~15 与 16~31,端点重叠时数组靠前者优先),编辑器支持添加/编辑/删除:每条计费规则下方「+添加条件」按钮追加一条默认条件(时段默认全天 00:00~23:59,行内类型下拉切换即重置为该类型默认值:周几默认空、号段默认全月 1~31、日期段默认当天单日);编辑器端校验拒绝非法时刻(需 24 小时制 HH:MM)、周几(需 0-6)、月号(需 1-31)、非规范日期与日期段倒序(时段/号段倒序是跨午夜/跨月环绕,合法);每日时段为自绘 HH:MM 文本输入(原生 time 控件的段位由浏览器按系统区域决定,部分环境渲染秒段导致带秒值被拒),全角数字折半角,凑满四位自动补冒号,粘贴带秒串自动截取前四位
• dailyWindow:{ from: 'HH:MM', to: 'HH:MM' } 每日时段双侧包含,fromto 跨午夜,from===to 单点;全天即 00:00~23:59
• weekdays:{ days: [0-6] } 星期几(集合,非范围),0=周日,空数组不成立;编辑器为日~六七枚 pill 多选
• monthDays:{ from, to } 月内号段双侧包含整数(1-31),from>to 跨月环绕(账单周期),from===to 单日(如 5~5 即 5 号);2 月无 31 号自然不触发
• dateRange:{ from: 'YYYY-MM-DD', to: 'YYYY-MM-DD' } 零填充字典序双侧包含,from===to 单日,from>to 倒序不成立(不可保存)
• 费用精度:小时级——聚合按小时桶起点时刻匹配价格,分钟槽费用由其所属小时桶价格导出;改价即时生效,历史费用下次查询按新规则重算(不回溯账单)。定价激活时聚合响应在槽级携带 cost 与逐模型拆分 costByModel(金额柱状图与悬浮读数的数据源)
• 时区口径:匹配与聚合均用 host 进程本地时区;client 侧注入点(底栏费用项/回合费用芯片)按浏览器本地时区的当前时刻评估条件,跨时区访问时与面板费用存在预期内偏差;所有费用均为按当前费率的估算值(标注「≈」与「估算」),不构成账单

与 dsh-usage-statistics-panel 的关系

本插件复刻自 HaoyueQin/dsh-usage-statistics-panel(npm 包 dsh-usage-statistics-panel),感谢原作者 HaoyueQin 的开源实现。在其基础上补足缺失的小时/分钟粒度与热力图/曲线/donut,移除其远程访问限制。路由(/api/usage-dash/*)与存储域(usage_stats)均不冲突,共存只是重复采集。

同装时两插件争抢会话底栏 'stats' 槽位(append 后位增强条目):槽注册表对同 id 同 priority 直接抛错,本插件以更低 priority 注册遮蔽原插件(lowest renders),同装时本插件胜出、卸载本插件后原插件恢复。仍建议卸载原插件以避免重复采集。

存档兼容

回扫经内部存档读取适配层(src/archive-reader.js)访问宿主 sessionPersistence:按能力检测在宿主 API 代际间分派(现役 open('read') 句柄式 / 旧代 inspect 一次整读),宿主再变只增适配器,回扫主体不动。旧格式会话存档文件(v0 起)由宿主迁移链在读路径统一转换为当前事件词汇,新旧多版本存档均可解析。

降级直读(宿主拒读时的恢复能力)

宿主对部分档案 fail-closed 拒读(descriptor 元数据校验、格式代际校验、seq gap 等),但档案数据本身完好。适配层在宿主 open/read/inspect 拒读时自动降级为文件直读(src/direct-log-reader.js):定位 sessions/ 下的会话档案,按 zstd 帧解压(Node 内置 node:zlib,零外部依赖、零宿主模块),JSONL 宽松解析出 usage 词汇交由统计折叠。统计只消费 assistant/message 的用量与 request/context 路由,无需完整会话语义——corrupt(seq gap)与 legacy(未知成员)对统计无影响,直读天然免疫。list 同样并入磁盘直扫,补齐旧宿主不枚举的新代文件名档案。

实测(0.1.5-alpha.1,同一批 1023 个可见档案):纯宿主读取 503 成功 / 520 拒读;直读降级后 1023 全部恢复,skipped=0,近 7 天统计从 30.5 亿 tokens 回补至 35.2 亿(+4.7 亿 tokens、+7857 请求为拒读档沉淀的真实用量)。

宿主可见性边界(0.1.1-rc.2 / 0.1.2-rc.1 / 0.1.5-alpha.1 实测)

三代宿主对同一批 1036 个会话档(1000 个旧格式 session.jsonl.zstd + 36 个 V3 格式 session.v3.jsonl.zstd)的枚举与解析能力各不相同:

宿主 · 列出 · 宿主可解析 · 直读补齐后 0.1.1-rc.2 · 1000 · 566 · V3 档经直读可见可解析 0.1.2-rc.1 · 1000 · 993 · V3 档经直读可见可解析 0.1.5-alpha.1 · 1023 · 503 · 520 个拒读档经直读全部恢复

插件无法修正宿主自身的解析语义,但拒读档的恢复不再依赖宿主修复:失败不进游标,每轮扫描自动重试直读。

跨宿主互补回扫

游标与统计存于全局 storage-domain(跨 profile/宿主共享):某代宿主读得动的档,扫过即永久入账;读不动的档留给能读的宿主。遇到 0.1.5 下 skipped 偏多时,可用旧宿主跑一轮互补:

# 以 0.1.2-rc.1(实测兼容性最好)挂同一份会话数据启动,扫完即走
dsh --profile <profile> --no-open --port 9191

两代扫描的并集即当前可达的历史全集。

警告:多宿主测试必须隔离 `DSH_HOME`,仅建独立 profile 不够——~/.dsh/storages/ 全局共享,旧版本插件(旧 store schema)在旧宿主上扫描后会把统计域覆盖成旧格式,新版本宿主读到不认识的 schema 即清空重建(游标与样本丢失,靠全量回扫自愈)。正确姿势:

```sh

$env:DSH_HOME = "$env:USERPROFILE.dsh-probe" # PowerShell;bash 用 export DSH_HOME=...

dsh web --no-open --port 9191

`

注意

装载本插件需要它在 dsh.profile.bundles(dsh plugin --profile web add @mzzsfy/dsh-usage-dash);bundles 表变化不支持热重载,需重启 dsh 生效。之后代码改动:宿主半区经 dev-link 自动热重载,client 半区刷新页面即生效。

双语能力经宿主 locale 服务声明装载(与官方插件同构);极端旧宿主无该服务时插件整体未激活(cordis 门控,升级宿主即自愈)。

dsh 版本兼容

按仓库动态窗口验证(scripts/compat/window.mjs),不预置任何固定版本槽:主测 = 渠道 dist-tag 最新 rc,完全适配口径;基线 = npm latest,不崩溃底线口径;主测与基线同版时收敛单槽。兼容面以窗口实测为准,不逐版本承诺。逐轮实测结论见 docs/兼容性测试/逐包测试进度.md 与本包 兼容性测试.md。