@mzzsfy/dsh-usage-dash 0.4.0 → 0.5.0

package/src/query.js

@@ -98,6 +98,10 @@ const percentOf = (part, total) => (total === 0 ? 0 : (part / total) * PERCENT_S
 
 const rowTokens = (row) => row.inputTokens + row.outputTokens + row.cacheReadTokens + row.cacheWriteTokens
 
+// 速度配对分子:decode 口径取 decodeTokens;存量旧格式行(带时长无 decodeTokens)
+// 回落 outputTokens,聚合随新数据自然收敛
+const speedTokensOf = (row) => (row.durationMs ? row.decodeTokens ?? row.outputTokens : 0)
+
 export function aggregateRange(rows, g, from, to) {
   const form = BUCKET_FORMS[g]
   const slots = enumerateBucketKeys(form)(from, to).map((key) => emptySlot(key))
@@ -105,43 +109,59 @@ export function aggregateRange(rows, g, from, to) {
   const modelTotals = new Map()
   const providerTotals = new Map()
   const activeBuckets = new Set()
-  // 槽级速度配对:桶串 → {outputTokens, durationMs},与模型级同口径(仅带时长行)
+  // 槽级配对:桶串 → 速度对 {decodeTokens, durationMs} 与首字对 {ttftMs, ttftSteps},
+  // 与模型级同口径(仅带配对数据的行计入)
   const slotSpeeds = new Map()
+  const slotTtfts = new Map()
   for (const row of rows) {
     const slot = slotByKey.get(row.bucket)
     // 桶串未落在枚举序列(如改粒度前的历史残行)不可归属,跳过防崩
     if (!slot) continue
     const tokens = rowTokens(row)
     addRowToSlot(slot, row, tokens)
-    if (tokens === 0) continue
-    activeBuckets.add(row.bucket)
-    slot.byModel[row.model] = (slot.byModel[row.model] ?? 0) + tokens
-    slot.byProvider[row.provider] = (slot.byProvider[row.provider] ?? 0) + tokens
+    // 纯 timing 行(零 token 桶 + decode 配对)不参与归因,但仍进配对聚合
+    if (tokens > 0) {
+      activeBuckets.add(row.bucket)
+      slot.byModel[row.model] = (slot.byModel[row.model] ?? 0) + tokens
+      slot.byProvider[row.provider] = (slot.byProvider[row.provider] ?? 0) + tokens
+    }
     if (row.durationMs) {
-      const pair = slotSpeeds.get(row.bucket) ?? { outputTokens: 0, durationMs: 0 }
-      pair.outputTokens += row.outputTokens
+      const pair = slotSpeeds.get(row.bucket) ?? { decodeTokens: 0, durationMs: 0 }
+      pair.decodeTokens += speedTokensOf(row)
       pair.durationMs += row.durationMs
       slotSpeeds.set(row.bucket, pair)
     }
+    if (row.ttftSteps > 0) {
+      const pair = slotTtfts.get(row.bucket) ?? { ttftMs: 0, ttftSteps: 0 }
+      pair.ttftMs += row.ttftMs ?? 0
+      pair.ttftSteps += row.ttftSteps
+      slotTtfts.set(row.bucket, pair)
+    }
     const modelTotal = modelTotals.get(row.model)
     if (modelTotal) {
       modelTotal.tokens += tokens
       modelTotal.speedDurationMs += row.durationMs ?? 0
-      modelTotal.speedOutputTokens += row.durationMs ? row.outputTokens : 0
+      modelTotal.speedOutputTokens += speedTokensOf(row)
+      modelTotal.ttftMs += row.ttftMs ?? 0
+      modelTotal.ttftSteps += row.ttftSteps ?? 0
     } else {
       modelTotals.set(row.model, {
         provider: row.provider,
         tokens,
         speedDurationMs: row.durationMs ?? 0,
-        speedOutputTokens: row.durationMs ? row.outputTokens : 0,
+        speedOutputTokens: speedTokensOf(row),
+        ttftMs: row.ttftMs ?? 0,
+        ttftSteps: row.ttftSteps ?? 0,
       })
     }
     providerTotals.set(row.provider, (providerTotals.get(row.provider) ?? 0) + tokens)
   }
-  // 槽级 speed 条件挂:无时长数据的槽不挂字段(存量槽形契约不变)
+  // 槽级 speed/ttft 条件挂:无配对数据的槽不挂字段(存量槽形契约不变)
   for (const slot of slots) {
-    const pair = slotSpeeds.get(slot.day)
-    if (pair && pair.durationMs > 0) slot.speed = pair.outputTokens / (pair.durationMs / MS_PER_SECOND)
+    const speedPair = slotSpeeds.get(slot.day)
+    if (speedPair && speedPair.durationMs > 0) slot.speed = speedPair.decodeTokens / (speedPair.durationMs / MS_PER_SECOND)
+    const ttftPair = slotTtfts.get(slot.day)
+    if (ttftPair && ttftPair.ttftSteps > 0) slot.ttft = ttftPair.ttftMs / ttftPair.ttftSteps
   }
   const totals = { tokens: 0, requests: 0, turns: 0, cacheHit: 0, cacheMiss: 0 }
   for (const slot of slots) {
@@ -151,18 +171,22 @@ export function aggregateRange(rows, g, from, to) {
     totals.cacheHit += slot.cacheHit
     totals.cacheMiss += slot.cacheMiss
   }
-  // speed = 配对口径的输出 token ÷ 模型时长秒;仅时长>0 的行计入分子分母,
-  // 存量旧格式行只进 tokens 不进分母,无时长数据条目不挂 speed 字段
+  // speed = decode 配对口径(decodeTokens ÷ 时长秒);ttft = 首 token 延迟
+  // 加权平均(毫秒);仅配对数据存在的条目挂字段,无数据条目不挂;
+  // 纯 timing 行可能产生 0-token 条目,列表保持只含 token 行(存量契约)
   const models = [...modelTotals.entries()]
+    .filter(([, agg]) => agg.tokens > 0)
     .map(([model, agg]) => ({
       model,
       provider: agg.provider,
       tokens: agg.tokens,
       percent: percentOf(agg.tokens, totals.tokens),
       ...(agg.speedDurationMs > 0 ? { speed: agg.speedOutputTokens / (agg.speedDurationMs / MS_PER_SECOND) } : {}),
+      ...(agg.ttftSteps > 0 ? { ttft: agg.ttftMs / agg.ttftSteps } : {}),
     }))
     .sort((a, b) => b.tokens - a.tokens)
   const providers = [...providerTotals.entries()]
+    .filter(([, tokens]) => tokens > 0)
     .map(([provider, tokens]) => ({ provider, tokens, percent: percentOf(tokens, totals.tokens) }))
     .sort((a, b) => b.tokens - a.tokens)
   const truncated = slots.length > MAX_SLOTS

package/src/store.js

@@ -82,8 +82,12 @@ export const usageRowSchema = z.object({
   outputTokens: z.number(),
   cacheReadTokens: z.number(),
   cacheWriteTokens: z.number(),
-  // 模型时长累计(毫秒):optional 兼容存量记录(域 open 逐记录 parse)
+  // 模型时长累计(毫秒)与 decode 口径速度分子:optional 兼容存量记录(域 open 逐记录 parse)
   durationMs: z.number().optional(),
+  decodeTokens: z.number().optional(),
+  // 首 token 延迟累计(毫秒)与样本步数:optional 兼容存量记录
+  ttftMs: z.number().optional(),
+  ttftSteps: z.number().optional(),
   requests: z.number(),
   turns: z.number(),
   lastSeen: z.number(),
@@ -136,13 +140,17 @@ function emptyRow(bucket, provider, model, nowMs) {
     cacheReadTokens: 0,
     cacheWriteTokens: 0,
     durationMs: 0,
+    decodeTokens: 0,
+    ttftMs: 0,
+    ttftSteps: 0,
     requests: 0,
     turns: 0,
     lastSeen: nowMs,
   }
 }
 
-// 样本折叠为计数增量:turn/request 只计次,token 样本累加四类桶
+// 样本折叠为计数增量:turn/request 只计次,token 样本累加四类桶;
+// decodeTokens 与 durationMs 同源配对构成速度,timing 缺失按零累计
 function deltaOf(sample, nowMs) {
   const delta = emptyRow('', '', '', nowMs)
   delete delta.bucket
@@ -156,6 +164,9 @@ function deltaOf(sample, nowMs) {
     delta.cacheReadTokens = sample.cacheReadTokens
     delta.cacheWriteTokens = sample.cacheWriteTokens
     delta.durationMs = sample.durationMs ?? 0
+    delta.decodeTokens = sample.decodeTokens ?? 0
+    delta.ttftMs = sample.ttftMs ?? 0
+    delta.ttftSteps = sample.ttftMs !== undefined ? 1 : 0
   }
   return delta
 }
@@ -170,6 +181,9 @@ function addDelta(base, delta) {
     cacheWriteTokens: base.cacheWriteTokens + delta.cacheWriteTokens,
     // base 侧 ?? 0 容存量旧格式行(缺字段);delta 侧经 deltaOf 恒为数值
     durationMs: (base.durationMs ?? 0) + delta.durationMs,
+    decodeTokens: (base.decodeTokens ?? 0) + delta.decodeTokens,
+    ttftMs: (base.ttftMs ?? 0) + delta.ttftMs,
+    ttftSteps: (base.ttftSteps ?? 0) + delta.ttftSteps,
     requests: base.requests + delta.requests,
     turns: base.turns + delta.turns,
     lastSeen: Math.max(base.lastSeen, delta.lastSeen),

package/test/client.test.mjs

@@ -90,6 +90,10 @@ const {
   trendLayout,
   trendRatePoints,
   trendSpeedPoints,
+  trendTtftPoints,
+  ttftScaleMax,
+  ttftTipText,
+  modelTtftText,
   speedTipText,
   speedScaleMax,
   legendToggle,
@@ -597,6 +601,44 @@ test('speedScaleMax 全零或空槽钳底防除零,混合取最大速度', () =>
   assert.equal(speedScaleMax([{ day: 'd0', speed: 30 }, { day: 'd1', speed: 12.5 }]), 30)
 })
 
+test('trendTtftPoints 点映射列中心与刻度上限比例高度且无 ttft 槽跳过', () => {
+  const slots = [
+    { day: 'd0', ttft: 2000 },
+    { day: 'd1', total: 10 },
+    { day: 'd2', ttft: 1000 },
+  ]
+  const bars = [{ x: 10 }, { x: 20 }, { x: 30 }]
+  const plotHeight = CHART_HEIGHT - CHART_PAD.top - CHART_PAD.bottom
+  const points = trendTtftPoints(slots, bars, plotHeight, 2200)
+  assert.equal(points.length, 2)
+  assert.equal(points[0].day, 'd0')
+  assert.equal(points[0].x, 10)
+  approx(points[0].y, CHART_PAD.top + plotHeight - (2000 / 2200) * plotHeight)
+  assert.equal(points[1].day, 'd2')
+  assert.equal(points[1].x, 30)
+  approx(points[1].y, CHART_PAD.top + plotHeight - (1000 / 2200) * plotHeight)
+})
+
+test('ttftScaleMax 全零或空槽钳底防除零,混合取最大延迟', () => {
+  assert.equal(ttftScaleMax([]), 1)
+  assert.equal(ttftScaleMax([{ day: 'd0' }, { day: 'd1', ttft: 0 }]), 1)
+  assert.equal(ttftScaleMax([{ day: 'd0', ttft: 3000 }, { day: 'd1', ttft: 1250 }]), 3000)
+})
+
+test('ttftTipText 无 ttft 为占位符有 ttft 为官方时长口径', () => {
+  const zhT = createTranslator(MESSAGES_ZH)
+  const enT = createTranslator(MESSAGES_EN)
+  assert.equal(ttftTipText(undefined, zhT), '—')
+  assert.equal(ttftTipText(200, zhT), '0.2秒')
+  assert.equal(ttftTipText(200, enT), '0.2s')
+  assert.equal(ttftTipText(9500, zhT), '9.5秒')
+})
+
+test('ttftLegend 中英文案注册', () => {
+  assert.equal(MESSAGES_ZH.ttftLegend, '首 token 延迟')
+  assert.equal(MESSAGES_EN.ttftLegend, 'First-token latency')
+})
+
 test('smoothPath 空点集为空串单点为移动命令', () => {
   assert.equal(smoothPath([]), '')
   assert.equal(smoothPath([{ x: 1, y: 2 }]), 'M 1 2')
@@ -612,6 +654,14 @@ test('smoothPath 三点后段取真实邻点', () => {
   assert.equal(d, 'M 0 0 C 10 5, 40 30, 60 30 C 80 30, 110 5, 120 0')
 })
 
+test('smoothPath 相邻点间距超 maxGap 折线断开成新段', () => {
+  const points = [{ x: 0, y: 0 }, { x: 60, y: 0 }, { x: 300, y: 0 }, { x: 360, y: 0 }]
+  const d = smoothPath(points, 90)
+  assert.equal(d, 'M 0 0 C 10 0, 10 0, 60 0 M 300 0 C 350 0, 350 0, 360 0')
+  // 无 maxGap 时不分段,行为与旧签名一致
+  assert.equal(smoothPath(points).includes('M 300'), false)
+})
+
 // —— S8 模型 donut 与列表 ——
 
 test('donut 常量锁定视口与环几何', () => {
@@ -687,6 +737,13 @@ test('模型速度文本:官方吞吐口径格式化,无速度为空串', () =>
   assert.equal(modelSpeedText(undefined), '')
 })
 
+test('模型首字文本:语言中立短时长,无 ttft 为空串', () => {
+  assert.equal(modelTtftText(200), 'TTFT 0.2s')
+  assert.equal(modelTtftText(162000), 'TTFT 2m42s')
+  assert.equal(modelTtftText(0), 'TTFT 0s')
+  assert.equal(modelTtftText(undefined), '')
+})
+
 // —— S14 费用格式化与展示辅助(镜像函数核心语义见 pricing-parity.test.mjs) ——
 
 test('formatCost 千分位与两位小数', () => {

package/test/collector.test.mjs

@@ -17,6 +17,12 @@ const usage = (extra = {}) => ({
   cacheWriteTokens: 4,
   ...extra,
 })
+// 官方助手流紧凑记录构造(与 dsh-llm AssistantStreamAccumulator.snapshot 同形):
+// packed run 以 time0 + dt 差分还原成员时刻,裸 chunk 携带原始 time
+const textRun = (time0, texts, dt = []) => ({ type: 'text-chunks', time0, index: 0, dt, texts })
+const toolRun = (time0, args, extra = {}) => ({ type: 'tool-call-chunks', time0, index: 0, dt: [], id: 't1', args, ...extra })
+const rawChunk = (time, chunk) => ({ type: 'chunk', time, chunk })
+const attempt = (seq, time, turn, step, stream) => ev('assistant/attempt', seq, time, { turn, step, stream })
 const session = (id) => ({ id })
 const tick = () => new Promise((resolve) => setImmediate(resolve))
 
@@ -168,12 +174,12 @@ test('step/start 与 llm/retry-started 产生 request 标记样本', async () =>
   }
 })
 
-test('step/start 观测起点:首个 usage 样本附 durationMs(start 到样本时刻)', async () => {
+test('decode 口径:durationMs 为首 token 到汇报,ttftMs 为起点到首 token', async () => {
   const { ctx, store } = liveCollector()
   const start = local(2026, 8, 2, 10, 0)
-  const sampleAt = start + 6 * 1000 + 500
   ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
-  ctx.emit('session/event', session('s1'), ev('assistant/message', 2, sampleAt, {
+  ctx.emit('session/event', session('s1'), attempt(2, start + 35 * 1000, 0, 0, [textRun(start + 10 * 1000, ['你好'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 3, start + 40 * 1000, {
     turn: 0,
     step: 0,
     usage: usage(),
@@ -181,7 +187,98 @@ test('step/start 观测起点:首个 usage 样本附 durationMs(start 到样本
   }))
   await tick()
   const usageSample = store.samples.find((sample) => !sample.request)
-  assert.equal(usageSample.durationMs, 6500)
+  assert.equal(usageSample.durationMs, 30 * 1000)
+  assert.equal(usageSample.ttftMs, 10 * 1000)
+  assert.equal(usageSample.decodeTokens, 20)
+  assert.equal(usageSample.outputTokens, 20)
+})
+
+test('无 attempt 时回落 message 自带 stream 取首 token', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 2, start + 40 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    stream: [textRun(start + 8 * 1000, ['好'])],
+    message: {},
+  }))
+  await tick()
+  const usageSample = store.samples.find((sample) => !sample.request)
+  assert.equal(usageSample.durationMs, 32 * 1000)
+  assert.equal(usageSample.ttftMs, 8 * 1000)
+})
+
+test('chunk 先发 token 契约保持,message 补发纯 timing 增量样本', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), ev('assistant/chunk', 2, start + 30 * 1000, {
+    turn: 0,
+    step: 0,
+    chunk: { type: 'usage', usage: usage() },
+  }))
+  ctx.emit('session/event', session('s1'), attempt(3, start + 35 * 1000, 0, 0, [textRun(start + 10 * 1000, ['你好'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 4, start + 40 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage({ inputTokens: 999 }),
+    message: {},
+  }))
+  await tick()
+  assert.equal(store.samples.length, 3)
+  const chunkSample = store.samples[1]
+  assert.equal(chunkSample.inputTokens, 10)
+  assert.equal(chunkSample.durationMs, undefined)
+  assert.equal(chunkSample.ttftMs, undefined)
+  assert.equal(chunkSample.decodeTokens, undefined)
+  assert.equal(store.samples[0].request, true)
+  const timingSample = store.samples[2]
+  assert.equal(timingSample.inputTokens, 0)
+  assert.equal(timingSample.outputTokens, 0)
+  assert.equal(timingSample.decodeTokens, 20)
+  assert.equal(timingSample.durationMs, 30 * 1000)
+  assert.equal(timingSample.ttftMs, 10 * 1000)
+})
+
+test('attempt 首 token 锁定:后续 attempt 不覆盖首个产出 token 的时刻', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), attempt(2, start + 35 * 1000, 0, 0, [textRun(start + 10 * 1000, ['a'])]))
+  ctx.emit('session/event', session('s1'), attempt(3, start + 38 * 1000, 0, 0, [textRun(start + 20 * 1000, ['b'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 4, start + 40 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  await tick()
+  const usageSample = store.samples.find((sample) => !sample.request)
+  assert.equal(usageSample.ttftMs, 10 * 1000)
+  assert.equal(usageSample.durationMs, 30 * 1000)
+})
+
+test('首个 attempt 无 token,由后续产出 token 的 attempt 锁定', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), attempt(2, start + 5 * 1000, 0, 0, [
+    textRun(start + 5 * 1000, ['']),
+    rawChunk(start + 6 * 1000, { type: 'usage' }),
+  ]))
+  ctx.emit('session/event', session('s1'), attempt(3, start + 38 * 1000, 0, 0, [toolRun(start + 15 * 1000, ['{'], { name: 'fn' })]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 4, start + 40 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  await tick()
+  const usageSample = store.samples.find((sample) => !sample.request)
+  assert.equal(usageSample.ttftMs, 15 * 1000)
+  assert.equal(usageSample.durationMs, 25 * 1000)
 })
 
 test('(session,turn,step) 去重:同键先到样本生效,重复报告吞掉', async () => {
@@ -217,14 +314,194 @@ test('无 step/start 起点的 usage 样本不带 durationMs', async () => {
   assert.equal(store.samples[0].durationMs, undefined)
 })
 
-test('retry-started 重置起点:时长只含最终尝试', async () => {
+test('retry 不重置起点:TTFT 含失败尝试,decode 段自成功首 token 起', async () => {
   const { ctx, store } = liveCollector()
   const start = local(2026, 8, 2, 10, 0)
   const retryAt = start + 60 * 1000
-  const sampleAt = retryAt + 5 * 1000
   ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
   ctx.emit('session/event', session('s1'), ev('llm/retry-started', 2, retryAt, { turn: 0, step: 0 }))
-  ctx.emit('session/event', session('s1'), ev('assistant/message', 3, sampleAt, {
+  ctx.emit('session/event', session('s1'), attempt(3, retryAt + 3 * 1000, 0, 0, [textRun(retryAt + 5 * 1000, ['好'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 4, retryAt + 35 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  await tick()
+  const usageSample = store.samples.find((sample) => !sample.request)
+  assert.equal(usageSample.ttftMs, 65 * 1000)
+  assert.equal(usageSample.durationMs, 30 * 1000)
+})
+
+test('零 TTFT(起点即出 token)附 ttftMs 为 0', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), attempt(2, start + 30 * 1000, 0, 0, [textRun(start, ['快'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 3, start + 30 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  await tick()
+  const usageSample = store.samples.find((sample) => !sample.request)
+  assert.equal(usageSample.ttftMs, 0)
+  assert.equal(usageSample.durationMs, 30 * 1000)
+})
+
+test('时刻倒挂防回拨:首 token 晚于汇报,durationMs 钳 0 不附,ttftMs 照常', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), attempt(2, start + 50 * 1000, 0, 0, [textRun(start + 50 * 1000, ['晚'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 3, start + 3 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  await tick()
+  const usageSample = store.samples.find((sample) => !sample.request)
+  assert.equal(usageSample.durationMs, undefined)
+  assert.equal(usageSample.decodeTokens, undefined)
+  assert.equal(usageSample.ttftMs, 50 * 1000)
+})
+
+test('时刻倒挂防回拨:首 token 早于起点,ttftMs 钳 0 照常计步,durationMs 照常', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), attempt(2, start + 1 * 1000, 0, 0, [textRun(start - 5 * 1000, ['回拨'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 3, start + 3 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  await tick()
+  const usageSample = store.samples.find((sample) => !sample.request)
+  assert.equal(usageSample.ttftMs, 0)
+  assert.equal(usageSample.durationMs, 8 * 1000)
+})
+
+test('usage 缺 outputTokens:不建 decode 配对(官方守卫),ttft 照常', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), attempt(2, start + 30 * 1000, 0, 0, [textRun(start + 10 * 1000, ['早'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 3, start + 40 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage({ outputTokens: undefined }),
+    message: {},
+  }))
+  await tick()
+  const usageSample = store.samples.find((sample) => !sample.request)
+  assert.equal(usageSample.outputTokens, 0)
+  assert.equal(usageSample.durationMs, undefined)
+  assert.equal(usageSample.decodeTokens, undefined)
+  assert.equal(usageSample.ttftMs, 10 * 1000)
+})
+
+test('重复报告不重复补发 timing:chunk → message → 重复 message 恰一条增量', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), ev('assistant/chunk', 2, start + 30 * 1000, {
+    turn: 0,
+    step: 0,
+    chunk: { type: 'usage', usage: usage() },
+  }))
+  ctx.emit('session/event', session('s1'), attempt(3, start + 35 * 1000, 0, 0, [textRun(start + 10 * 1000, ['好'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 4, start + 40 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage({ inputTokens: 999 }),
+    message: {},
+  }))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 5, start + 41 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  await tick()
+  const timingSamples = store.samples.filter((sample) => !sample.request && sample.decodeTokens !== undefined)
+  assert.equal(timingSamples.length, 1)
+  assert.equal(timingSamples[0].decodeTokens, 20)
+  assert.equal(timingSamples[0].durationMs, 30 * 1000)
+  assert.equal(timingSamples[0].ttftMs, 10 * 1000)
+})
+
+test('message 首发后到达的 chunk usage 不补 timing', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), attempt(2, start + 35 * 1000, 0, 0, [textRun(start + 10 * 1000, ['好'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 3, start + 40 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  ctx.emit('session/event', session('s1'), ev('assistant/chunk', 4, start + 41 * 1000, {
+    turn: 0,
+    step: 0,
+    chunk: { type: 'usage', usage: usage() },
+  }))
+  await tick()
+  const usageSamples = store.samples.filter((sample) => !sample.request)
+  assert.equal(usageSamples.length, 1)
+  assert.equal(usageSamples[0].decodeTokens, 20)
+  assert.equal(usageSamples[0].durationMs, 30 * 1000)
+})
+
+test('chunk 非零后 message usage 全零仍补发 timing', async () => {
+  const { ctx, store } = liveCollector()
+  const start = local(2026, 8, 2, 10, 0)
+  const zeroUsage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 }
+  ctx.emit('session/event', session('s1'), ev('step/start', 1, start, { turn: 0, step: 0 }))
+  ctx.emit('session/event', session('s1'), ev('assistant/chunk', 2, start + 30 * 1000, {
+    turn: 0,
+    step: 0,
+    chunk: { type: 'usage', usage: usage() },
+  }))
+  ctx.emit('session/event', session('s1'), attempt(3, start + 35 * 1000, 0, 0, [textRun(start + 10 * 1000, ['好'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 4, start + 40 * 1000, {
+    turn: 0,
+    step: 0,
+    usage: zeroUsage,
+    message: {},
+  }))
+  await tick()
+  const timingSamples = store.samples.filter((sample) => !sample.request && sample.ttftMs !== undefined)
+  assert.equal(timingSamples.length, 1)
+  assert.equal(timingSamples[0].inputTokens, 0)
+  assert.equal(timingSamples[0].ttftMs, 10 * 1000)
+  assert.equal(timingSamples[0].decodeTokens, 0)
+  assert.equal(timingSamples[0].durationMs, 30 * 1000)
+})
+
+test('缺 turn/step 的 message 带 stream:首发全量样本含 timing 且不污染去重集合', async () => {
+  const { ctx, store } = liveCollector()
+  const t = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 1, t + 30 * 1000, {
+    usage: usage(),
+    stream: [textRun(t, ['早'])],
+    message: {},
+  }))
+  await tick()
+  assert.equal(store.samples.length, 1)
+  assert.equal(store.samples[0].durationMs, 30 * 1000)
+  assert.equal(store.samples[0].ttftMs, undefined)
+})
+
+test('有首 token 无起点:durationMs 附而 ttftMs 不附', async () => {
+  const { ctx, store } = liveCollector()
+  const t = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), attempt(1, t + 10 * 1000, 0, 0, [textRun(t, ['早'])]))
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 2, t + 30 * 1000, {
     turn: 0,
     step: 0,
     usage: usage(),
@@ -232,7 +509,23 @@ test('retry-started 重置起点:时长只含最终尝试', async () => {
   }))
   await tick()
   const usageSample = store.samples.find((sample) => !sample.request)
-  assert.equal(usageSample.durationMs, 5000)
+  assert.equal(usageSample.durationMs, 30 * 1000)
+  assert.equal(usageSample.ttftMs, undefined)
+})
+
+test('无任何 stream 信息不附时长与首字(存量超旧日志形态)', async () => {
+  const { ctx, store } = liveCollector()
+  const t = local(2026, 8, 2, 10, 0)
+  ctx.emit('session/event', session('s1'), ev('assistant/message', 1, t, {
+    turn: 0,
+    step: 0,
+    usage: usage(),
+    message: {},
+  }))
+  await tick()
+  assert.equal(store.samples.length, 1)
+  assert.equal(store.samples[0].durationMs, undefined)
+  assert.equal(store.samples[0].ttftMs, undefined)
 })
 
 test('同时刻零时长不附 durationMs,request 标记样本不带时长', async () => {
@@ -519,14 +812,15 @@ test('回扫:无边界会话全量重放,归因与游标写回', async () => {
   assert.equal(collector.status().scannedSessions, 1)
 })
 
-test('回扫:重放路径同样附加 durationMs', async () => {
+test('回扫:重放路径同样产出 decode 口径时长与首字', async () => {
   const start = local(2026, 8, 2, 14, 0)
   const persistence = fakePersistence([{
     id: 's1',
     events: [
       ev('request/context', 0, start, { provider: 'deepseek', model: 'chat' }),
       ev('step/start', 1, start, { turn: 0, step: 0 }),
-      ev('assistant/message', 2, start + 7 * 1000, {
+      attempt(2, start + 5 * 1000, 0, 0, [textRun(start + 2 * 1000, ['回'])]),
+      ev('assistant/message', 3, start + 7 * 1000, {
         turn: 0,
         step: 0,
         usage: usage(),
@@ -538,7 +832,8 @@ test('回扫:重放路径同样附加 durationMs', async () => {
   const collector = new UsageCollector(fakeCtx({ persistence }), store)
   await collector.backfill(persistence, fakeSessions())
   const usageSample = store.samples.find((sample) => !sample.request)
-  assert.equal(usageSample.durationMs, 7000)
+  assert.equal(usageSample.durationMs, 5 * 1000)
+  assert.equal(usageSample.ttftMs, 2 * 1000)
 })
 
 test('回扫:已入游标会话不再重扫', async () => {