@mzzsfy/dsh-usage-dash 0.4.0 → 0.6.0

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 () => {

package/test/query.test.mjs

@@ -316,6 +316,54 @@ test('attachCosts 保留槽级 speed 字段供曲线消费', () => {
   assert.equal(out.daily[1].speed, 5)
 })
 
+test('decode 口径:速度分子取 decodeTokens,timing 样本零桶不稀释 token 总量', () => {
+  const rows = [
+    // token 样本行:只有 token 桶,无时长
+    makeRow({ bucket: '2020-01-01', model: 'm1', provider: 'p1', outputTokens: 20 }),
+    // 纯 timing 增量行:零 token 桶 + decode 配对
+    makeRow({ bucket: '2020-01-02', model: 'm1', provider: 'p1', outputTokens: 0, decodeTokens: 30, durationMs: 2500 }),
+  ]
+  const out = aggregateRange(rows, 'D', '2020-01-01', '2020-01-02')
+  const entry = out.models.find((item) => item.model === 'm1')
+  assert.equal(entry.tokens, 20)
+  assert.equal(entry.speed, 30 / (2500 / 1000))
+})
+
+test('旧格式行 durationMs 无 decodeTokens:分子回落 outputTokens', () => {
+  const rows = [
+    makeRow({ bucket: '2020-01-01', model: 'm1', provider: 'p1', outputTokens: 20, durationMs: 4000 }),
+  ]
+  const out = aggregateRange(rows, 'D', '2020-01-01', '2020-01-01')
+  assert.equal(out.models[0].speed, 5)
+})
+
+test('ttft 模型级聚合:加权平均,无 ttft 行不参与,无数据不挂字段', () => {
+  const rows = [
+    makeRow({ bucket: '2020-01-01', model: 'm1', provider: 'p1', outputTokens: 20, ttftMs: 1000, ttftSteps: 1 }),
+    makeRow({ bucket: '2020-01-02', model: 'm1', provider: 'p1', outputTokens: 30, ttftMs: 3000, ttftSteps: 2 }),
+    makeRow({ bucket: '2020-01-03', model: 'm1', provider: 'p1', outputTokens: 100 }),
+    makeRow({ bucket: '2020-01-01', model: 'm2', provider: 'p2', outputTokens: 5 }),
+  ]
+  const out = aggregateRange(rows, 'D', '2020-01-01', '2020-01-03')
+  const m1 = out.models.find((item) => item.model === 'm1')
+  assert.equal(m1.ttft, (1000 + 3000) / (1 + 2))
+  const m2 = out.models.find((item) => item.model === 'm2')
+  assert.equal('ttft' in m2, false)
+})
+
+test('槽级 ttft 聚合:同槽配对,无 ttft 槽不挂字段,attachCosts 保留', () => {
+  const rows = [
+    makeRow({ bucket: '2020-01-01', model: 'm1', provider: 'p1', outputTokens: 20, ttftMs: 2000, ttftSteps: 1 }),
+    makeRow({ bucket: '2020-01-01', model: 'm2', provider: 'p2', outputTokens: 30, ttftMs: 4000, ttftSteps: 1 }),
+    makeRow({ bucket: '2020-01-02', model: 'm1', provider: 'p1', outputTokens: 100 }),
+  ]
+  const result = aggregateRange(rows, 'D', '2020-01-01', '2020-01-02')
+  assert.equal(result.daily[0].ttft, (2000 + 4000) / 2)
+  assert.equal('ttft' in result.daily[1], false)
+  const out = attachCosts(result, rows, 'D', [ruleOf()])
+  assert.equal(out.daily[0].ttft, 3000)
+})
+
 test('attachCosts H 槽按桶起点计价并归集 totals 与 models', () => {
   const rows = [
     makeRow({ bucket: '2020-01-01T01', model: 'm1', provider: 'p1', inputTokens: 1000000, outputTokens: 500000 }),

package/test/store.test.mjs

@@ -219,6 +219,64 @@ test('老行缺 durationMs 字段:增量求和不产 NaN', async () => {
   assert.equal(seen.outputTokens, 40)
 })
 
+test('decode 配对与首字样本落三粒度累加,timing 样本不重复计 token', async () => {
+  const domain = fakeDomain()
+  const store = new UsageStore(facilityOf(domain))
+  const at = local(2026, 8, 2, 14, 37)
+  // chunk 先发 token 样本:只有 token 桶
+  await store.record(tokenSample(at, { durationMs: undefined }))
+  // message 补发纯 timing 增量:零桶 + decodeTokens + durationMs + ttftMs
+  await store.record(tokenSample(at + 1000, {
+    inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0,
+    decodeTokens: 20, durationMs: 30000, ttftMs: 10000,
+  }))
+  await store.flushNow()
+  const key = 'D|2026-08-02|deepseek|deepseek/deepseek-chat'
+  const daily = domain.rows.get(key)
+  assert.equal(daily.outputTokens, 20)
+  assert.equal(daily.decodeTokens, 20)
+  assert.equal(daily.durationMs, 30000)
+  assert.equal(daily.ttftMs, 10000)
+  assert.equal(daily.ttftSteps, 1)
+  const minute = domain.rows.get('M|2026-08-02T14:30|deepseek|deepseek/deepseek-chat')
+  assert.equal(minute.decodeTokens, 20)
+  assert.equal(minute.ttftMs, 10000)
+})
+
+test('timing 缺失样本:decodeTokens 与 ttft 字段按零累计', async () => {
+  const domain = fakeDomain()
+  const store = new UsageStore(facilityOf(domain))
+  const at = local(2026, 8, 2, 14, 37)
+  await store.record(tokenSample(at))
+  await store.flushNow()
+  const seen = domain.rows.get('D|2026-08-02|deepseek|deepseek/deepseek-chat')
+  assert.equal(seen.decodeTokens, 0)
+  assert.equal(seen.durationMs, 0)
+  assert.equal(seen.ttftMs, 0)
+  assert.equal(seen.ttftSteps, 0)
+})
+
+test('老行缺 decode/ttft 字段:增量求和不产 NaN', async () => {
+  const domain = fakeDomain()
+  const store = new UsageStore(facilityOf(domain))
+  const at = local(2026, 8, 2, 14, 37)
+  const key = 'D|2026-08-02|deepseek|deepseek/deepseek-chat'
+  await store.record(tokenSample(at))
+  await store.flushNow()
+  // 模拟存量旧格式行:回写去掉新增字段
+  const stored = domain.rows.get(key)
+  delete stored.decodeTokens
+  delete stored.ttftMs
+  delete stored.ttftSteps
+  await store.record(tokenSample(at + 1000, { decodeTokens: 20, durationMs: 3000, ttftMs: 500 }))
+  await store.flushNow()
+  const seen = domain.rows.get(key)
+  assert.equal(seen.decodeTokens, 20)
+  assert.equal(seen.durationMs, 3000)
+  assert.equal(seen.ttftMs, 500)
+  assert.equal(seen.ttftSteps, 1)
+})
+
 test('missing-record 首写竞态:put 种子后重试写入真值', async () => {
   const domain = fakeDomain()
   const store = new UsageStore(facilityOf(domain))

package/test/stream-parity.test.mjs

@@ -0,0 +1,75 @@
+// 官方同构 parity:collector 移植的助手流首 token 读取与官方 dsh-llm
+// assistantStreamFirstTokenTime / isTokenDelta / runFirstTokenTime 语义逐向量对表。
+// 期望值按官方源码语义推导(首个 token delta = 非空 text/reasoning 成员、
+// 非空 tool-call arguments 成员或具名 tool-call run 起点)。
+// 对表锚点:对表自 dsh 0.1.2-rc.1 官方源码(dsh-llm/lib/types/assistant-stream.js
+// 与 dsh-session-stats/lib/types/projection.js);dsh 本体升级后须重对表,
+// 此处静态向量不感知官方实现漂移。
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+import { assistantStreamFirstTokenTime } from '../src/collector.js'
+
+const textRun = (time0, texts, dt = []) => ({ type: 'text-chunks', time0, index: 0, dt, texts })
+const reasoningRun = (time0, texts, dt = []) => ({ type: 'reasoning-chunks', time0, index: 0, dt, texts })
+const toolRun = (time0, args, extra = {}) => ({ type: 'tool-call-chunks', time0, index: 0, dt: [], id: 'c1', args, ...extra })
+const rawChunk = (time, chunk) => ({ type: 'chunk', time, chunk })
+
+test('text run 首个非空成员时刻按 time0+dt 差分还原', () => {
+  assert.equal(assistantStreamFirstTokenTime([textRun(1000, ['', 'ab'], [100])]), 1100)
+})
+
+test('全空 text run 无首 token', () => {
+  assert.equal(assistantStreamFirstTokenTime([textRun(1000, ['', ''])]), undefined)
+})
+
+test('reasoning run 与 text run 同语义', () => {
+  assert.equal(assistantStreamFirstTokenTime([reasoningRun(500, ['', '思考'], [20])]), 520)
+})
+
+test('具名 tool call run 整体起于 time0', () => {
+  assert.equal(assistantStreamFirstTokenTime([toolRun(700, ['', '{'], { name: 'fn' })]), 700)
+})
+
+test('匿名 tool call run 取首个非空 arguments 成员', () => {
+  assert.equal(assistantStreamFirstTokenTime([toolRun(700, ['', '{'], { dt: [30] })]), 730)
+})
+
+test('裸 chunk:text-delta 非空即 token,空文本跳过', () => {
+  assert.equal(assistantStreamFirstTokenTime([
+    rawChunk(100, { type: 'text-delta', index: 0, text: '' }),
+    rawChunk(200, { type: 'text-delta', index: 0, text: 'hi' }),
+  ]), 200)
+})
+
+test('裸 chunk:usage 与 finish 非 token', () => {
+  assert.equal(assistantStreamFirstTokenTime([
+    rawChunk(100, { type: 'usage' }),
+    rawChunk(200, { type: 'finish' }),
+  ]), undefined)
+})
+
+test('首个产出 token 的记录生效,后续记录不覆盖', () => {
+  assert.equal(assistantStreamFirstTokenTime([
+    rawChunk(100, { type: 'usage' }),
+    textRun(900, ['a']),
+    textRun(500, ['b']),
+  ]), 900)
+})
+
+test('空流与非数组输入无首 token', () => {
+  assert.equal(assistantStreamFirstTokenTime([]), undefined)
+  assert.equal(assistantStreamFirstTokenTime(undefined), undefined)
+})
+
+test('未知记录形态安全跳过不崩溃', () => {
+  assert.equal(assistantStreamFirstTokenTime([
+    { type: 'text-delta', text: 'x' },
+    textRun(300, ['晚到']),
+  ]), 300)
+})
+
+test('dt 差分短缺视为损坏,按无首 token 处理', () => {
+  assert.equal(assistantStreamFirstTokenTime([textRun(1000, ['', 'ab'], [])]), undefined)
+})

package/test/turn-tail.test.mjs

@@ -17,6 +17,8 @@ const {
   turnCostTitleText,
   turnModelOf,
   turnTokenUsageOfMessage,
+  turnUsageSourceOfMessage,
+  usageSourceBuckets,
 } = core
 
 const zhT = createTranslator(MESSAGES_ZH)
@@ -85,6 +87,70 @@ test('反查:单节点形状残缺跳过不抛,后续命中不受阻', () => {
   assert.equal(turnTokenUsageOfMessage([null, 'x', 42], 'm-1'), null)
 })
 
+test('反查:同一容器重复调用命中索引,结果一致', () => {
+  const tokenUsage = { uncachedInputTokens: 10, outputTokens: 5, totalTokens: 15 }
+  const nodes = [tailNode('m-1', tokenUsage)]
+  // Given 同一容器连续两次反查(首次建索引,二次命中缓存)
+  const first = turnTokenUsageOfMessage(nodes, 'm-1')
+  const second = turnTokenUsageOfMessage(nodes, 'm-1')
+  // Then 结果一致且均为 tokenUsage 本体
+  assert.equal(first, tokenUsage)
+  assert.equal(second, tokenUsage)
+  // 未命中的 messageId 二次查询仍为 null(索引缓存不放大误命中)
+  assert.equal(turnTokenUsageOfMessage(nodes, 'm-2'), null)
+})
+
+test('反查源:命中返回仓库内原始引用,采样形态不归一(归一属渲染层)', () => {
+  const tokenUsage = { uncachedInputTokens: 10, outputTokens: 5, totalTokens: 15 }
+  assert.equal(turnUsageSourceOfMessage([tailNode('m-1', tokenUsage)], 'm-1'), tokenUsage)
+  // 视图节点直挂 tokenUsage 次选
+  const directNode = { kind: 'turn-tail', data: { closing: { finalNode: { seq: 1, messageId: 'm-2' } }, tokenUsage } }
+  assert.equal(turnUsageSourceOfMessage([directNode], 'm-2'), tokenUsage)
+  // 采样 usage 原样返回(引用稳定,useSyncExternalStore 快照可比对)
+  const sampled = { inputTokens: 100, outputTokens: 20, totalTokens: 130, cacheReadTokens: 10 }
+  const sampledNode = { kind: 'turn-tail', data: { closing: { finalNode: { seq: 2, messageId: 'm-3' }, usage: sampled } } }
+  assert.equal(turnUsageSourceOfMessage([sampledNode], 'm-3'), sampled)
+  // 三级全缺返回 null(稳定值)
+  assert.equal(turnUsageSourceOfMessage([{ kind: 'turn-tail', data: { closing: { finalNode: { seq: 3, messageId: 'm-4' } } } }], 'm-4'), null)
+  assert.equal(turnUsageSourceOfMessage([], 'm-1'), null)
+  assert.equal(turnUsageSourceOfMessage(null, 'm-1'), null)
+  // 仓库两态
+  assert.equal(turnUsageSourceOfMessage(new Map([['k', tailNode('m-1', tokenUsage)]]), 'm-1'), tokenUsage)
+})
+
+test('反查源:节点数据更新后同容器引用随之更替', () => {
+  // Given 命中节点无用量源 When 位置数据补上 tokenUsage(同一容器对象,仓库可变语义)
+  const node = { kind: 'turn-tail', data: { closing: { finalNode: { seq: 1, messageId: 'm-1' } } } }
+  const nodes = [node]
+  assert.equal(turnUsageSourceOfMessage(nodes, 'm-1'), null)
+  const tokenUsage = { uncachedInputTokens: 1, outputTokens: 1, totalTokens: 2 }
+  node.data.tokenUsage = tokenUsage
+  // Then 反查读到新引用 —— selector 快照由恒等(null)变为新引用,驱动重渲染
+  assert.equal(turnUsageSourceOfMessage(nodes, 'm-1'), tokenUsage)
+})
+
+test('归一:采样形态转聚合桶,聚合形态原样直通', () => {
+  assert.deepEqual(
+    usageSourceBuckets({ inputTokens: 100, outputTokens: 20, totalTokens: 130, cacheReadTokens: 10 }),
+    { uncachedInputTokens: 100, outputTokens: 20, totalTokens: 130, cacheReadTokens: 10 },
+  )
+  const aggregated = { uncachedInputTokens: 8, outputTokens: 2, totalTokens: 10, routes: [{ provider: 'p', model: 'm' }] }
+  assert.equal(usageSourceBuckets(aggregated), aggregated)
+  assert.equal(usageSourceBuckets(null), null)
+})
+
+test('反查:容器换引用(快照更替)后新节点可见', () => {
+  const oldUsage = { uncachedInputTokens: 1, outputTokens: 1, totalTokens: 2 }
+  const oldNodes = [tailNode('m-1', oldUsage)]
+  assert.equal(turnTokenUsageOfMessage(oldNodes, 'm-1'), oldUsage)
+  // Given 节点表内容变化以新容器表达(官方 store 快照语义),新增回合节点
+  const newUsage = { uncachedInputTokens: 7, outputTokens: 7, totalTokens: 14 }
+  const newNodes = [...oldNodes, tailNode('m-2', newUsage)]
+  // Then 新容器首查即可见新节点,旧容器结果不受影响
+  assert.equal(turnTokenUsageOfMessage(newNodes, 'm-2'), newUsage)
+  assert.equal(turnTokenUsageOfMessage(oldNodes, 'm-1'), oldUsage)
+})
+
 test('计价模型键:双全拼两段,仅 model 用裸名,双缺回退全通配键', () => {
   assert.equal(turnModelOf({ routes: [{ provider: 'p', model: 'm' }] }), 'p/m')
   assert.equal(turnModelOf({ routes: [{ model: 'm' }] }), 'm')