@mzzsfy/dsh-usage-dash 0.4.0 → 0.5.0

package/README.md

@@ -9,8 +9,8 @@
 - 三粒度视图:天(7/30/90 天/自定义日期段)、小时(24 小时/3 天/7 天/15 天)、分钟(3 小时/24 小时/3 天/7 天,10 分钟桶粒度),后两者为滚动窗口;各视图时间范围统一 4 挡,时/分选择上限与数据保留期一致
 - 汇总卡六张:Tokens 用量(服务商总口径)、会话数量、请求数量、最常用模型、平均缓存命中率、活跃天数(恒按天口径,不随视图切换);配置定价规则后 Tokens 卡头部行右侧显示估算费用
 - 活动热力图:GitHub 风格周列×星期行,26 周窗口,五档色阶,悬停明细;仅按天视图展示
-- 缓存命中率曲线:日粒度命中率 + 右侧副轴,并叠加平均生成速度曲线(单独颜色,读数走悬停;仅含有时长数据的槽,整图无时长数据不绘制),悬停显示当前时段命中率、平均生成速度与 token 明细(配置定价规则后附当前时段估算费用行,受「费用显示」开关;三粒度趋势图通用)
-- 模型 donut 与列表:按 token 前 5 模型占比环形图(中心为总量),列表含命中率与占比,并为每模型显示平均生成速度(tok/s,无时长数据不显示),悬停联动
+- 缓存命中率曲线:日粒度命中率 + 右侧副轴,并叠加平均生成速度曲线与首 token 延迟曲线(各自单独颜色,读数走悬停;仅含配对数据的槽参与,整图无数据不绘制),悬停显示当前时段命中率、平均生成速度、首 token 延迟与 token 明细(配置定价规则后附当前时段估算费用行,受「费用显示」开关;三粒度趋势图通用)
+- 模型 donut 与列表:按 token 前 5 模型占比环形图(中心为总量),列表含命中率与占比;每模型右侧两行:第一行占比%·token 数,第二行估算费用·TTFT·生成速度(语言中立,点分隔;费用需配置定价规则,TTFT/速度无配对数据不显示),悬停联动
 - 三粒度堆叠柱状趋势图(数据量大时裁最旧并提示);图例可点击切换显隐:点击单选(仅显示该项,左轴刻度按可见项归一)/再点恢复全部,Ctrl+点击多选,隐藏最后一项无效
 - 回扫状态行默认隐藏:首次启用自动回扫历史会话,运行中显示进度(常显);右上角为折叠箭头与刷新图标,折叠层内展开扫描异常日志块(逐条:时间/类型/明细,计数即明细条数,上限 200 条超限丢最旧,重建时清空)与「重建」入口(二次确认 3 秒后清库重扫),采集错误常显;工具栏分主区与右侧操作区,窄宽度时挡位组在主区内换行
 - 会话底栏接管:替换官方信息行为增强版,偏好卡三个开关默认全开——精确缓存命中率(两位小数)、会话 Token 明细(总/命中缓存/未命中缓存/输出)、费用显示(底栏费用项、趋势 tooltip 费用行与回合费用芯片);三开关全关时与官方逐字节一致
@@ -19,7 +19,7 @@
 - 双语:跟随宿主语言设置(设置 → 通用 → 语言)即时切换 en/zh
 - 数据 API 守卫:POST 同源校验 + JSON content-type(与 dsh-usage-panel 同构),局域网远程访问可用
 
-口径:token 总量 = 未缓存输入 + 输出 + 缓存读 + 缓存写;命中率 = 缓存读 / (缓存读 + 未缓存输入 + 缓存写);桶按 host 本地时区。平均生成速度 = 输出 token ÷ 模型时长,时长为 `step/start` 到该步首个 usage 汇报(与官方 session-stats 投影 llmMs 口径同构,`llm/retry-started` 重置起点,时长只含最终尝试);仅带时长的行参与速度分子分母,升级前存量数据与未观测到起点的样本不显示速度。保留策略:天桶永久,小时桶固定 15 天,分钟桶默认 7 天且上限 7 天(设置项 `minuteRetentionDays`,0 = 禁用分钟桶)。
+口径:token 总量 = 未缓存输入 + 输出 + 缓存读 + 缓存写;命中率 = 缓存读 / (缓存读 + 未缓存输入 + 缓存写);桶按 host 本地时区。平均生成速度 = 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 周期,统计可由会话重扫重建。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-usage-dash",
   "description": "用量统计面板:天/小时/分钟三粒度 token 与请求统计,26 周活跃热力图,会话底栏信息接管与官方动作行回合费用芯片,多条件分时段定价规则与费用估算;复刻自 github.com/HaoyueQin/dsh-usage-statistics-panel,感谢原作者 HaoyueQin",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -128,6 +128,7 @@ const MESSAGES_ZH = {
   hitRateLegend: '缓存命中率',
   avgSpeed: '平均生成速度',
   speedLegend: '平均生成速度',
+  ttftLegend: '首 token 延迟',
   topModel: '最常用模型',
   topModelHint: '按 token 用量排序,非调用次数',
   heatmap: '活跃热力图',
@@ -267,6 +268,7 @@ const MESSAGES_EN = {
   hitRateLegend: 'Cache-hit rate',
   avgSpeed: 'Avg speed',
   speedLegend: 'Avg speed',
+  ttftLegend: 'First-token latency',
   topModel: 'Top model',
   topModelHint: 'Ranked by token usage, not call count',
   heatmap: 'Activity heatmap',
@@ -529,11 +531,14 @@ const BAR_MAX_WIDTH = 30
 const AXIS_TICK_COUNT = 4
 // 速度刻度上限钳底:全零或无速度防除零(速度不设轴,读数走 tooltip)
 const SPEED_SCALE_FLOOR = 1
+// 首 token 延迟刻度上限钳底(毫秒):全零或无数据防除零(不设轴,读数走 tooltip)
+const TTFT_SCALE_FLOOR = 1
 // 轴上限留白系数:数据峰不顶满绘图区,顶部留出标注空间
 const AXIS_SCALE_HEADROOM = 1.1
 // 图例键:折线项与模型项共处同一显隐集合
 const LEGEND_KEY_RATE = 'rate'
 const LEGEND_KEY_SPEED = 'speed'
+const LEGEND_KEY_TTFT = 'ttft'
 
 function niceTicks(max, count) {
   if (max <= 0 || count <= 0) return []
@@ -614,6 +619,7 @@ function trendLayout(slots, modelOrder, avail, labelMinPitch) {
 const PERCENT_SCALE = 100
 const RATE_AXIS_STEPS = 4
 const TREND_LINE_WIDTH = 2
+const TREND_LINE_GAP_SLOTS = 1.5
 const TREND_DOT_RADIUS = 4
 const TREND_DOT_RING = 2
 const AXIS_RATE_GAP = 8
@@ -650,8 +656,22 @@ function trendSpeedPoints(slots, bars, plotHeight, scaleMax) {
   return points
 }
 
-// Catmull-Rom 转三次贝塞尔:控制点取邻点差六分之一,端点折返
-function smoothPath(points) {
+// 首 token 延迟曲线点:仅带 ttft 槽产出,高度按刻度上限归一(毫秒域独立归一)
+function trendTtftPoints(slots, bars, plotHeight, scaleMax) {
+  const points = []
+  slots.forEach((slot, index) => {
+    if (slot.ttft === undefined) return
+    points.push({
+      day: slot.day,
+      x: bars[index].x,
+      y: CHART_PAD.top + plotHeight - (slot.ttft / scaleMax) * plotHeight,
+    })
+  })
+  return points
+}
+
+// Catmull-Rom 转三次贝塞尔:控制点取邻点差六分之一,端点折返;相邻点间距超 maxGap 折线断开成新段(稀疏槽防长弧跨越)
+function smoothPath(points, maxGap = Number.POSITIVE_INFINITY) {
   if (points.length === 0) return ''
   if (points.length === 1) return `M ${points[0].x} ${points[0].y}`
   let d = `M ${points[0].x} ${points[0].y}`
@@ -660,6 +680,10 @@ function smoothPath(points) {
     const p1 = points[i]
     const p2 = points[i + 1]
     const p3 = points[i + 2] ?? p2
+    if (p2.x - p1.x > maxGap) {
+      d += ` M ${p2.x} ${p2.y}`
+      continue
+    }
     const c1x = p1.x + (p2.x - p0.x) / 6
     const c1y = p1.y + (p2.y - p0.y) / 6
     const c2x = p2.x - (p3.x - p1.x) / 6
@@ -719,6 +743,30 @@ function speedScaleMax(slots) {
   return Math.max(SPEED_SCALE_FLOOR, ...slots.map((slot) => slot.speed ?? 0))
 }
 
+// 首 token 延迟刻度上限(毫秒):全零或无数据钳底防除零
+function ttftScaleMax(slots) {
+  return Math.max(TTFT_SCALE_FLOOR, ...slots.map((slot) => slot.ttft ?? 0))
+}
+
+// tooltip 首 token 延迟行文本:无 ttft 与命中率同款占位符,有则为官方时长口径
+function ttftTipText(ttft, t) {
+  return ttft === undefined ? TOOLTIP_MISSING : formatDuration(ttft, t)
+}
+
+// 语言中立短时长:60 秒内一位小数秒,以上整秒折分秒(模型列表第二行用,禁本地化)
+function formatDurationShort(ms) {
+  const seconds = ms / MS_PER_SECOND
+  if (seconds < DURATION_MINUTE_SECONDS) return `${Math.round(seconds * NUMBER_ONE_DECIMAL) / NUMBER_ONE_DECIMAL}s`
+  const whole = Math.round(seconds)
+  return `${Math.floor(whole / SECONDS_PER_MINUTE)}m${whole % SECONDS_PER_MINUTE}s`
+}
+
+// 模型首 token 延迟短文本:语言中立;无 ttft(无配对数据)为空串
+function modelTtftText(ttft) {
+  if (ttft === undefined) return ''
+  return `TTFT ${formatDurationShort(ttft)}`
+}
+
 // 热力图:窗口固定 26 周,与所选范围无关
 const HEAT_WEEKS = 26
 const HEAT_ROW_COUNT = 7
@@ -1264,32 +1312,76 @@ const TURN_COST_CHIP_ORDER = 20 + 10
 // messageId 反查:节点表为 chat 节点仓库(values() 可枚举,Map/仓库两态兼容);
 // 回合级用量优先取回合位置数据(location.turn.data.get('turn-tail')).tokenUsage(官方 tokenUsage 聚合,
 // 分页窗口缺 turn/start 时缺席),回退视图节点 data.closing.usage(末步用量采样,输入侧已含缓存,计费口径同源)
-function turnTokenUsageOfMessage(nodes, messageId) {
+// 索引缓存:每份节点表快照只全量扫描一次建 messageId→turn-tail 索引(WeakMap 随快照释放),
+// 长会话流式期间多芯片各自全量扫描是 O(消息数×节点数) 放大,索引后单快照 O(节点数)
+const TURN_USAGE_INDEX_CACHE = new WeakMap()
+
+function turnUsageIndexOf(nodes) {
+  let index = TURN_USAGE_INDEX_CACHE.get(nodes)
+  if (index !== undefined) return index
+  index = new Map()
   const list = nodes && typeof nodes.values === 'function' ? [...nodes.values()] : nodes
-  if (!Array.isArray(list)) return null
-  for (const node of list) {
-    try {
-      if (node?.kind !== 'turn-tail') continue
-      if (node.data?.closing?.finalNode?.messageId !== messageId) continue
-      const turnData = node.location?.turn?.data
-      const tail = turnData && typeof turnData.get === 'function' ? turnData.get('turn-tail') : null
-      if (tail?.tokenUsage) return tail.tokenUsage
-      if (node.data.tokenUsage) return node.data.tokenUsage
-      const sampled = node.data?.closing?.usage
-      if (!sampled) return null
-      return {
-        uncachedInputTokens: sampled.inputTokens,
-        outputTokens: sampled.outputTokens,
-        totalTokens: sampled.totalTokens,
-        ...sampled.cacheReadTokens === undefined ? {} : { cacheReadTokens: sampled.cacheReadTokens },
-        ...sampled.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: sampled.cacheWriteTokens },
-        ...sampled.reasoningTokens === undefined ? {} : { reasoningTokens: sampled.reasoningTokens },
-      }
-    } catch { /* 单节点形状残缺跳过,扫描继续 */ }
+  if (Array.isArray(list)) {
+    for (const node of list) {
+      try {
+        if (node?.kind !== 'turn-tail') continue
+        const messageId = node.data?.closing?.finalNode?.messageId
+        if (typeof messageId !== 'string' || index.has(messageId)) continue
+        index.set(messageId, node)
+      } catch { /* 单节点形状残缺跳过 */ }
+    }
   }
+  TURN_USAGE_INDEX_CACHE.set(nodes, index)
+  return index
+}
+
+function turnTokenUsageOfMessage(nodes, messageId) {
+  // 非对象(含 null/undefined)直接 null:WeakMap 键要求对象,展开校验收进索引构建,
+  // 每快照只物化一次节点序列
+  if (nodes === null || typeof nodes !== 'object') return null
+  const node = turnUsageIndexOf(nodes).get(messageId)
+  if (node === undefined) return null
+  try {
+    const turnData = node.location?.turn?.data
+    const tail = turnData && typeof turnData.get === 'function' ? turnData.get('turn-tail') : null
+    if (tail?.tokenUsage) return tail.tokenUsage
+    if (node.data.tokenUsage) return node.data.tokenUsage
+    return usageSourceBuckets(node.data?.closing?.usage ?? null)
+  } catch { /* 单节点形状残缺跳过,语义同扫描容错 */ }
   return null
 }
 
+// messageId 反查用量源:返回仓库内既有引用(官方聚合 tokenUsage → 视图节点 tokenUsage → closing.usage 采样),
+// 引用恒定直至该回合数据被替换;全缺返回 null。供 useChat selector 使用 ——
+// selector 必须返回稳定引用(useSyncExternalStore 以 Object.is 比对快照),返回新建对象会造成无限渲染;
+// 采样形态(字段名差异)由 usageSourceBuckets 在渲染层归一
+function turnUsageSourceOfMessage(nodes, messageId) {
+  if (nodes === null || typeof nodes !== 'object') return null
+  const node = turnUsageIndexOf(nodes).get(messageId)
+  if (node === undefined) return null
+  try {
+    const turnData = node.location?.turn?.data
+    const tail = turnData && typeof turnData.get === 'function' ? turnData.get('turn-tail') : null
+    return tail?.tokenUsage ?? node.data.tokenUsage ?? node.data?.closing?.usage ?? null
+  } catch { /* 单节点形状残缺跳过,语义同扫描容错 */ }
+  return null
+}
+
+// 用量源 → 聚合桶形态:closing.usage 采样字段名不同(inputTokens 即 uncached 口径,实测 total-input=output 恒等),
+// 聚合形态(已带 uncachedInputTokens)原样直通保持引用
+function usageSourceBuckets(source) {
+  if (!source || source.uncachedInputTokens !== undefined) return source
+  if (source.inputTokens === undefined) return null
+  return {
+    uncachedInputTokens: source.inputTokens,
+    outputTokens: source.outputTokens,
+    totalTokens: source.totalTokens,
+    ...source.cacheReadTokens === undefined ? {} : { cacheReadTokens: source.cacheReadTokens },
+    ...source.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: source.cacheWriteTokens },
+    ...source.reasoningTokens === undefined ? {} : { reasoningTokens: source.reasoningTokens },
+  }
+}
+
 // 计价模型键:routes 首条按官方 messageRoute 分离字段拼两段键,与采集器 refOf 双实现同源
 // (官方 source.provider/model 是分离字段,routes[].model 是裸模型名,展示侧才拼 provider),
 // 仅 model 用裸名命中 */model 档,双缺回退全通配键;多 route 取首条(单轮估算口径)
@@ -1693,9 +1785,9 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     const STYLE_CSS = `
 .ud-panel{display:flex;flex-direction:column;gap:12px;font-size:13px;color:var(--dsw-alias-label-primary);
 --ud-chart-1:color-mix(in srgb,#0576ff 70%,white);--ud-chart-2:color-mix(in srgb,#2f6f37 70%,white);--ud-chart-3:color-mix(in srgb,#c46212 70%,white);--ud-chart-4:color-mix(in srgb,#975bf1 70%,white);--ud-chart-5:color-mix(in srgb,#d34591 70%,white);--ud-chart-other:color-mix(in srgb,#576270 70%,white);
---dsw-heat-0:#ebedf0;--dsw-heat-1:#dbe3ff;--dsw-heat-2:#b7c5ff;--dsw-heat-3:#8ea4ff;--dsw-heat-4:#6884ff;--dsw-heat-5:#4d6bfe;--ud-trend-line:#0576ff;--ud-trend-speed:#0ca678}
+--dsw-heat-0:#ebedf0;--dsw-heat-1:#dbe3ff;--dsw-heat-2:#b7c5ff;--dsw-heat-3:#8ea4ff;--dsw-heat-4:#6884ff;--dsw-heat-5:#4d6bfe;--ud-trend-line:#0576ff;--ud-trend-speed:#0ca678;--ud-trend-ttft:#e8590c}
 body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,white);--ud-chart-2:color-mix(in srgb,#2f6f37 65%,white);--ud-chart-3:color-mix(in srgb,#c46212 65%,white);--ud-chart-4:color-mix(in srgb,#975bf1 65%,white);--ud-chart-5:color-mix(in srgb,#d34591 65%,white);--ud-chart-other:color-mix(in srgb,#576270 65%,white);
---dsw-heat-0:#21262d;--dsw-heat-1:#2f4bd0;--dsw-heat-2:#4d6bfe;--dsw-heat-3:#6e8bff;--dsw-heat-4:#93aaff;--dsw-heat-5:#c4d0ff;--ud-trend-line:#4d6bfe;--ud-trend-speed:#2fbf8f}
+--dsw-heat-0:#21262d;--dsw-heat-1:#2f4bd0;--dsw-heat-2:#4d6bfe;--dsw-heat-3:#6e8bff;--dsw-heat-4:#93aaff;--dsw-heat-5:#c4d0ff;--ud-trend-line:#4d6bfe;--ud-trend-speed:#2fbf8f;--ud-trend-ttft:#ffa94d}
 .ud-toolbar{display:flex;align-items:flex-start;gap:8px}
 .ud-toolbar-main{display:flex;align-items:center;gap:8px;flex-wrap:wrap;flex:1 1 auto;min-width:0}
 .ud-group{display:flex;align-items:center;gap:2px;padding:3px;border:1px solid var(--dsw-alias-border-l2);border-radius:9px;background:var(--dsw-alias-bg-layer-1)}
@@ -1781,10 +1873,13 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
 .ud-bar-hit{fill:transparent;pointer-events:all}
 .ud-trend{stroke:var(--ud-trend-line);opacity:.9;fill:none;pointer-events:none}
 .ud-trend--speed{stroke:var(--ud-trend-speed)}
+.ud-trend--ttft{stroke:var(--ud-trend-ttft)}
 .ud-trend-dot{fill:var(--ud-trend-line);stroke:var(--dsw-alias-bg-layer-1);stroke-width:${TREND_DOT_RING}px;pointer-events:none}
 .ud-trend-dot--speed{fill:var(--ud-trend-speed)}
+.ud-trend-dot--ttft{fill:var(--ud-trend-ttft)}
 .ud-legend-swatch--line{height:2px;border-radius:1px;background:var(--ud-trend-line)}
 .ud-legend-swatch--line--speed{background:var(--ud-trend-speed)}
+.ud-legend-swatch--line--ttft{background:var(--ud-trend-ttft)}
 .ud-model-usage{display:flex;flex-wrap:wrap;align-items:flex-start;gap:16px}
 .ud-donut-wrap{flex:0 0 auto}
 .ud-donut-seg{cursor:pointer;outline:none;transition:stroke-width .12s ease}
@@ -1935,7 +2030,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
           h(FitText, null, String(stats.activeDays))))
     }
 
-    function Legend({ models, colorFor, speedEnabled = false, isVisible, onItem, t = defaultT }) {
+    function Legend({ models, colorFor, speedEnabled = false, ttftEnabled = false, isVisible, onItem, t = defaultT }) {
       const itemProps = (key) => ({
         className: cx('ud-legend-item', isVisible && !isVisible(key) && 'ud-legend-item--off'),
         onClick: onItem ? (event) => onItem(key, event.ctrlKey || event.metaKey) : undefined,
@@ -1950,7 +2045,10 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
           h('span', null, t('hitRateLegend'))),
         speedEnabled ? h('span', { key: 'speed', title: t('speedLegend'), ...itemProps(LEGEND_KEY_SPEED) },
           h('i', { className: 'ud-legend-swatch ud-legend-swatch--line ud-legend-swatch--line--speed' }),
-          h('span', null, t('speedLegend'))) : null)
+          h('span', null, t('speedLegend'))) : null,
+        ttftEnabled ? h('span', { key: 'ttft', title: t('ttftLegend'), ...itemProps(LEGEND_KEY_TTFT) },
+          h('i', { className: 'ud-legend-swatch ud-legend-swatch--line ud-legend-swatch--line--ttft' }),
+          h('span', null, t('ttftLegend'))) : null)
     }
 
     const colorForModel = (models) => (model) => {
@@ -1980,22 +2078,33 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
         return () => observer.disconnect()
       }, [])
       const hasSpeed = slots.some((slot) => slot.speed !== undefined)
-      const visibleSet = visibleKeys ?? new Set([...modelOrder, LEGEND_KEY_RATE, ...(hasSpeed ? [LEGEND_KEY_SPEED] : [])])
+      const hasTtft = slots.some((slot) => slot.ttft !== undefined)
+      const visibleSet = visibleKeys ?? new Set([
+        ...modelOrder, LEGEND_KEY_RATE,
+        ...(hasSpeed ? [LEGEND_KEY_SPEED] : []),
+        ...(hasTtft ? [LEGEND_KEY_TTFT] : []),
+      ])
       const visibleModels = modelOrder.filter((model) => visibleSet.has(model))
       const showRate = visibleSet.has(LEGEND_KEY_RATE)
       const showSpeed = hasSpeed && visibleSet.has(LEGEND_KEY_SPEED)
+      const showTtft = hasTtft && visibleSet.has(LEGEND_KEY_TTFT)
       const layout = trendLayout(slots, visibleModels, avail, labelMinPitch)
       const plotRight = CHART_PAD.left + (slots.length - 1) * layout.step + layout.barWidth
       const ratePoints = trendRatePoints(slots, layout.bars, layout.plotHeight)
       const speedMax = speedScaleMax(slots)
       const speedAxisMax = speedMax * AXIS_SCALE_HEADROOM
       const speedPoints = showSpeed ? trendSpeedPoints(slots, layout.bars, layout.plotHeight, speedAxisMax) : []
+      const ttftMax = ttftScaleMax(slots)
+      const ttftAxisMax = ttftMax * AXIS_SCALE_HEADROOM
+      const ttftPoints = showTtft ? trendTtftPoints(slots, layout.bars, layout.plotHeight, ttftAxisMax) : []
       // 左轴标定:可见柱有数据标 token;无柱数据且速度线可见标速度(tok/s);否则空
+      // (ttft 不设轴,读数走 tooltip,毫秒域与速度轴不同单位不混轴)
       const speedAxisTicks = layout.ticks.length === 0 && showSpeed ? niceTicks(speedMax, AXIS_TICK_COUNT) : []
       const yTicks = leftAxisTicks(layout.ticks, layout.scaleMax, speedAxisTicks, speedAxisMax)
       const hoverSlot = hover ? slots[hover.index] : null
       const hoverRatePoint = showRate && hoverSlot ? ratePoints.find((point) => point.day === hoverSlot.day) : null
       const hoverSpeedPoint = hoverSlot ? speedPoints.find((point) => point.day === hoverSlot.day) : null
+      const hoverTtftPoint = hoverSlot ? ttftPoints.find((point) => point.day === hoverSlot.day) : null
       const pick = (index) => (event) => setHover({ index, anchor: event.currentTarget })
       const clear = () => setHover(null)
       const otherEntries = hoverSlot
@@ -2038,11 +2147,15 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
               ? h('text', { key: slot.day, className: 'ud-axis', x: layout.bars[index].x, y: CHART_HEIGHT - X_LABEL_OFFSET, textAnchor: 'middle' }, labelFor(slot.day))
               : null),
             showRate ? h('path', {
-              className: 'ud-trend', d: smoothPath(ratePoints),
+              className: 'ud-trend', d: smoothPath(ratePoints, layout.step * TREND_LINE_GAP_SLOTS),
               strokeWidth: TREND_LINE_WIDTH, strokeLinejoin: 'round', strokeLinecap: 'round',
             }) : null,
             showSpeed ? h('path', {
-              className: cx('ud-trend', 'ud-trend--speed'), d: smoothPath(speedPoints),
+              className: cx('ud-trend', 'ud-trend--speed'), d: smoothPath(speedPoints, layout.step * TREND_LINE_GAP_SLOTS),
+              strokeWidth: TREND_LINE_WIDTH, strokeLinejoin: 'round', strokeLinecap: 'round',
+            }) : null,
+            showTtft ? h('path', {
+              className: cx('ud-trend', 'ud-trend--ttft'), d: smoothPath(ttftPoints, layout.step * TREND_LINE_GAP_SLOTS),
               strokeWidth: TREND_LINE_WIDTH, strokeLinejoin: 'round', strokeLinecap: 'round',
             }) : null,
             hoverRatePoint
@@ -2051,13 +2164,16 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
             hoverSpeedPoint
               ? h('circle', { className: cx('ud-trend-dot', 'ud-trend-dot--speed'), cx: hoverSpeedPoint.x, cy: hoverSpeedPoint.y, r: TREND_DOT_RADIUS })
               : null,
+            hoverTtftPoint
+              ? h('circle', { className: cx('ud-trend-dot', 'ud-trend-dot--ttft'), cx: hoverTtftPoint.x, cy: hoverTtftPoint.y, r: TREND_DOT_RADIUS })
+              : null,
             slots.map((slot, index) => h('rect', {
               key: `hit-${slot.day}`, className: 'ud-bar-hit',
               x: layout.bars[index].x - layout.step / 2, y: CHART_PAD.top, width: layout.step, height: layout.plotHeight,
               onMouseEnter: pick(index), onFocus: pick(index), onMouseLeave: clear, onBlur: clear,
             })))),
         h(Legend, {
-          models: legendModels, colorFor, speedEnabled: hasSpeed,
+          models: legendModels, colorFor, speedEnabled: hasSpeed, ttftEnabled: hasTtft,
           isVisible: (key) => visibleSet.has(key),
           onItem: (key, ctrl) => setVisibleKeys(legendToggle(visibleKeys, key, ctrl)),
         }),
@@ -2073,6 +2189,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
                   `${model}: ${formatTokens(tokens)}`)) : []),
                 showRate ? h('div', { key: 'rate', className: 'ud-tip-row' }, `${t('cacheHitRate')}: ${cacheRateText(hoverSlot.cacheHit, hoverSlot.cacheMiss)}`) : null,
                 showSpeed ? h('div', { key: 'speed', className: 'ud-tip-row' }, `${t('avgSpeed')}: ${speedTipText(hoverSlot.speed)}`) : null,
+                showTtft ? h('div', { key: 'ttft', className: 'ud-tip-row' }, `${t('ttftLegend')}: ${ttftTipText(hoverSlot.ttft, t)}`) : null,
                 costEnabled && prefsRef.current.costDisplay && hoverSlot.cost !== undefined
                   ? h('div', { key: 'cost', className: 'ud-tip-row' }, `≈ ${formatCost(hoverSlot.cost, costCurrency)}`)
                   : null,
@@ -2233,6 +2350,12 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
             models.map((item) => {
               const isOther = item.model === OTHER_MODEL
               const speedText = modelSpeedText(item.speed)
+              const ttftText = modelTtftText(item.ttft)
+              const metaParts = [
+                item.cost !== undefined ? `≈ ${formatCost(item.cost, costCurrency)}` : null,
+                ttftText,
+                speedText,
+              ].filter(Boolean)
               return h(React.Fragment, { key: item.model },
                 h('div', {
                   className: cx('ud-model-row', isOther && 'ud-model-row--expand'),
@@ -2254,11 +2377,9 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
                       }, '›')
                     : null,
                   h('div', { className: 'ud-model-values' },
-                    h('span', { className: 'ud-model-tokens' }, formatTokens(item.tokens)),
-                    h('span', { className: 'ud-model-pct' },
-                      item.cost !== undefined ? h('span', { className: 'ud-model-cost' }, `≈ ${formatCost(item.cost, costCurrency)} · `) : null,
-                      formatPercent((item.tokens / total) * PERCENT_SCALE),
-                      speedText ? ` · ${speedText}` : null))),
+                    h('span', { className: 'ud-model-tokens' },
+                      `${formatTokens(item.tokens)} (${formatPercent((item.tokens / total) * PERCENT_SCALE)})`),
+                    h('span', { className: 'ud-model-pct' }, metaParts.join(' · ')))),
                 isOther
                   ? h('div', { className: cx('ud-model-other', expandedOther && 'ud-model-other--open') },
                       h('div', { className: 'ud-model-other-list' },
@@ -2350,9 +2471,13 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
     // 注入点B 组件:回合费用芯片,官方动作行内渲染(复制与分支图标之间,赞踩/上下文跳转同排);
     // 受费用显示开关;价格异步首帧未回不渲染,回包后补渲染;显隐节奏随官方 data-actions-reveal
     // 官方槽容器固定在用量/用时芯片之前,末位排布由 SlotTailPortal 移交实现
+    // 响应性:useChat selector 返回用量源稳定引用(null→引用 / 引用→引用),回合结束数据发布即触发重渲染;
+    // 返回仓库本体则引用恒定,快照比对恒等,新回合永不重渲染(刷新才出现的根因)
     const CostChip = React.memo(function CostChip({ messageId, useChat, t = defaultT }) {
       if (typeof useChat !== 'function') return null
-      const chatNodes = useChat((state) => (state && typeof state === 'object') ? state.nodes : undefined)
+      const usageSource = typeof messageId === 'string' && messageId !== ''
+        ? useChat((state) => turnUsageSourceOfMessage(state?.nodes, messageId))
+        : null
       const [prefs, setPrefs] = useState(() => statsLineState.get())
       useEffect(() => statsLineState.subscribe(() => setPrefs(statsLineState.get())), [])
       const [pricingRules, setPricingRules] = useState(null)
@@ -2363,9 +2488,7 @@ body[data-ds-dark-theme] .ud-panel{--ud-chart-1:color-mix(in srgb,#0576ff 65%,wh
         })
         return () => { alive = false }
       }, [])
-      const matched = typeof messageId === 'string' && messageId !== ''
-        ? turnTokenUsageOfMessage(chatNodes, messageId)
-        : null
+      const matched = usageSourceBuckets(usageSource)
       const price = matched && prefs.costDisplay && pricingRules !== null
         ? matchPrice(pricingRules, turnModelOf(matched), new Date())
         : null

package/src/collector.js

@@ -35,13 +35,57 @@ function emptySkipCounts() {
   return { [SKIP_KINDS.descriptor]: 0, [SKIP_KINDS.corrupt]: 0, [SKIP_KINDS.legacy]: 0, [SKIP_KINDS.other]: 0 }
 }
 
+// 官方 dsh-llm 助手流读取器同构镜像(isTokenDelta/runFirstTokenTime/
+// assistantStreamFirstTokenTime):从紧凑记录还原首个产出 token 的时刻。
+// 语义由 test/stream-parity.test.mjs 锁定,改一侧必须同步 parity
+function isTokenDelta(chunk) {
+  if (chunk?.type === 'text-delta' || chunk?.type === 'reasoning-delta') return chunk.text !== ''
+  return chunk?.type === 'tool-call-delta' && (chunk.argumentsDelta !== '' || chunk.name !== undefined)
+}
+
+function runFirstTokenTime(run) {
+  if (run.type === 'tool-call-chunks' && run.name !== undefined) return run.time0
+  const fragments = run.type === 'tool-call-chunks' ? run.args : run.texts
+  let time = run.time0
+  for (let index = 0; index < fragments.length; index += 1) {
+    if (index > 0) {
+      const gap = run.dt[index - 1]
+      // 差分短缺属存储形态损坏,按无首 token 处理,保留后续报告锁定机会
+      if (typeof gap !== 'number') return undefined
+      time += gap
+    }
+    if (fragments[index] !== '') return time
+  }
+  return undefined
+}
+
+// 已知 packed run 形态白名单:未知记录形态(宿主未来新字段)安全跳过,
+// 采集是观测性的,绝不因流记录形态漂移而崩溃
+const RUN_RECORD_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks'])
+
+export function assistantStreamFirstTokenTime(stream) {
+  if (!Array.isArray(stream)) return undefined
+  for (const record of stream) {
+    const time = record?.type === 'chunk'
+      ? (isTokenDelta(record.chunk) ? record.time : undefined)
+      : RUN_RECORD_TYPES.has(record?.type) ? runFirstTokenTime(record) : undefined
+    if (time !== undefined) return time
+  }
+  return undefined
+}
+
 // 会话内单 pass 折叠:跟踪每个 (turn,step) 槽的最新报告,只把首次发射交 store
 export class UsageFold {
   constructor() {
     this.seen = new Map()
-    // (turn,step) 最近一次模型启动时刻:retry-started 覆盖重置,时长与首样本
-    // token 同源配对(分子只含最终尝试,分母不含失败尝试,避免速度被污染)
+    // (turn,step) 模型启动时刻:仅 step/start 设定(官方口径 TTFT 含失败尝试,
+    // 不随 retry-started 重置);(turn,step) 首 token 时刻:由首个产出 token
+    // 的 attempt 锁定,存活于步内重试。时长均为官方 decode 口径:durationMs
+    // = 汇报 - 首 token(吞吐分母),ttftMs = 首 token - 启动
     this.starts = new Map()
+    this.firstTokens = new Map()
+    // 已补发 timing 的键:token 先发后只补一次,重复报告不重复配对
+    this.timingDone = new Set()
   }
 
   keyOf(event) {
@@ -64,9 +108,9 @@ export class UsageFold {
     }
     if (event.type === 'step/start' || event.type === 'llm/retry-started') {
       // step/start 恰开一次模型调用,retry-started 标记每次实际启动的重试;
-      // 请求只由标记计数,与 token 样本双计
+      // 请求只由标记计数,与 token 样本双计;时长起点不随重试重置
       const key = this.keyOf(event)
-      if (key !== null) this.starts.set(key, event.time)
+      if (event.type === 'step/start' && key !== null) this.starts.set(key, event.time)
       return {
         time: event.time,
         inputTokens: 0,
@@ -76,6 +120,15 @@ export class UsageFold {
         request: true,
       }
     }
+    if (event.type === 'assistant/attempt') {
+      // 首 token 锁定:仅首个产出 token 的 attempt 生效,后续 attempt 不覆盖
+      const key = this.keyOf(event)
+      if (key !== null && !this.firstTokens.has(key)) {
+        const first = assistantStreamFirstTokenTime(event.data?.stream)
+        if (typeof first === 'number') this.firstTokens.set(key, first)
+      }
+      return null
+    }
     if (event.type === 'assistant/chunk') {
       const usage = event.data?.chunk?.type === 'usage' ? event.data.chunk.usage : undefined
       return usage ? this.replaceSample(event, usage) : null
@@ -87,11 +140,39 @@ export class UsageFold {
   }
 
   replaceSample(event, usage) {
-    // 四桶全零为噪声;纯缓存调用(仅缓存桶非零)仍有效
+    const key = this.keyOf(event)
+    const first = key !== null
+      ? this.firstTokens.get(key) ?? assistantStreamFirstTokenTime(event.data?.stream)
+      : assistantStreamFirstTokenTime(event.data?.stream)
+    // decode 配对有效性对齐官方 usageOutputTokens 守卫:输出 token 非有效数值
+    // 不建配对(官方同款),首字延迟不受 usage 影响照常采集;
+    // 负差值按官方 Math.max(0) 钳 0(时钟回拨计 0 延迟样本),0 时长不附配对
+    // (存储侧 0 时长配对天然惰性,防 0 分母放大)
+    const decodeable = typeof usage.outputTokens === 'number'
+      && Number.isFinite(usage.outputTokens) && usage.outputTokens >= 0
+    const timing = typeof first === 'number'
+      ? {
+          durationMs: Math.max(0, event.time - first),
+          ttftMs: key !== null && this.starts.has(key) ? Math.max(0, first - this.starts.get(key)) : undefined,
+          decodeable,
+        }
+      : undefined
+    const prev = key !== null ? this.seen.get(key) : undefined
+    // 首样本生效:内部无条件跟踪最新报告,但交 store 的只有首次发射;
+    // 首 token 时刻不在 chunk 事件上,token 先发后由后续报告补纯 timing 增量,
+    // 已补发的键不重复补(timingDone 独立集合持久跟踪,防重复报告双计);
+    // 补发判定先于四桶和门:usage 全零的报告仍补 timing(token 已由首发承载)
+    if (prev) {
+      if (timing === undefined || this.timingDone.has(key)) return null
+      this.timingDone.add(key)
+      return this.emitTimingOnly(usage, timing, event.time)
+    }
+    // 四桶全零为噪声(不占去重键),纯缓存调用(仅缓存桶非零)仍有效。
+    // retry 场景 attempt 先于 chunk 落流时,chunk 首发即带 timing,分母以
+    // chunk 时刻近似官方汇报时刻(毫秒级组装间隔),主路径仍由 message 补发
     const sum = (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
       + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
     if (sum <= 0) return null
-    const key = this.keyOf(event)
     const sample = {
       time: event.time,
       inputTokens: usage.inputTokens ?? 0,
@@ -99,18 +180,37 @@ export class UsageFold {
       cacheReadTokens: usage.cacheReadTokens ?? 0,
       cacheWriteTokens: usage.cacheWriteTokens ?? 0,
     }
-    // 模型时长口径与官方 session-stats 投影 llmMs 同构(step/start → 汇报时刻),
-    // 附加到交 store 的首样本;未观测起点或时刻倒挂(时钟回拨)不附,0 视为无
-    const start = key !== null ? this.starts.get(key) : undefined
-    if (start !== undefined) {
-      const durationMs = Math.max(0, event.time - start)
-      if (durationMs > 0) sample.durationMs = durationMs
+    if (key !== null) this.seen.set(key, sample)
+    return this.emitSample(sample, timing, key)
+  }
+
+  emitSample(sample, timing, key) {
+    if (timing === undefined) return { ...sample }
+    // decode 口径聚合对:分子 decodeTokens 与分母 durationMs 同源配对
+    if (timing.decodeable && timing.durationMs > 0) {
+      sample.decodeTokens = sample.outputTokens
+      sample.durationMs = timing.durationMs
+    }
+    if (timing.ttftMs !== undefined) sample.ttftMs = timing.ttftMs
+    if (key !== undefined && key !== null) this.timingDone.add(key)
+    return { ...sample }
+  }
+
+  emitTimingOnly(usage, timing, time) {
+    // 纯 timing 增量:token 桶全零不重复计数,decodeTokens 单独承载速度分子
+    const delta = {
+      time,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+    }
+    if (timing.decodeable && timing.durationMs > 0) {
+      delta.decodeTokens = usage.outputTokens
+      delta.durationMs = timing.durationMs
     }
-    if (key === null) return sample
-    const prev = this.seen.get(key)
-    this.seen.set(key, sample)
-    // 首样本生效:内部无条件跟踪最新报告,但交 store 的只有首次发射的独立拷贝
-    return prev ? null : { ...sample }
+    if (timing.ttftMs !== undefined) delta.ttftMs = timing.ttftMs
+    return delta
   }
 }