@mzzsfy/dsh-usage-dash 0.4.0 → 0.6.0

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
   }
 }
 

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

@@ -75,6 +75,7 @@ const {
   otherDetailItems,
   parseEnvelope,
   partitionGroupOf,
+  pointerAt,
   providerOf,
   rateAxisTicks,
   removeRulesAt,
@@ -82,6 +83,11 @@ const {
   resolveDayRange,
   resolveHourRange,
   resolveMinuteRange,
+  resolveHourCustomRange,
+  resolveMinuteCustomRange,
+  resolvePointQuery,
+  formatDateTimeInput,
+  parseLocalDateTime,
   shortDay,
   smoothPath,
   tipPlace,
@@ -90,6 +96,10 @@ const {
   trendLayout,
   trendRatePoints,
   trendSpeedPoints,
+  trendTtftPoints,
+  ttftScaleMax,
+  ttftTipText,
+  modelTtftText,
   speedTipText,
   speedScaleMax,
   legendToggle,
@@ -173,6 +183,112 @@ test('pointStats 缓存命中须视图与挡位双匹配', () => {
   assert.equal(pointStatsMatches(null, 'hour', '24h'), false)
 })
 
+// —— 时/分自定义时间范围:归一语义与预设挡一致(小时 floor 整点桶,分钟 from 对齐 10 分钟桶、to 保原分钟) ——
+
+const CUSTOM_FROM = '2026-03-14T09:45'
+const CUSTOM_TO = '2026-03-15T14:10'
+
+test('hour 自定义范围两端 floor 到所在小时桶', () => {
+  // Given datetime 输入含分钟偏移 When 解析 Then 两端均取所在小时桶起点(闭区间)
+  assert.deepEqual(resolveHourCustomRange(CUSTOM_FROM, CUSTOM_TO), { from: '2026-03-14T09', to: '2026-03-15T14' })
+  assert.deepEqual(resolveHourCustomRange('2026-03-14T09:00', '2026-03-15T14:59'), { from: '2026-03-14T09', to: '2026-03-15T14' })
+})
+
+test('hour 自定义跨度超保留期钳起点,临界窗经 floor 与原窗输出等价', () => {
+  // Given 跨度 16 天 When 解析 Then 起点钳到终点前 15 天整点;15 天余零头的窗钳后 floor 输出不变
+  assert.deepEqual(
+    resolveHourCustomRange('2026-02-27T00:00', '2026-03-15T14:10'),
+    { from: '2026-02-28T14', to: '2026-03-15T14' },
+  )
+  assert.deepEqual(
+    resolveHourCustomRange('2026-02-28T14:00', '2026-03-15T14:10'),
+    { from: '2026-02-28T14', to: '2026-03-15T14' },
+  )
+})
+
+test('hour 自定义非法输入返回 null', () => {
+  // Given 空值/垃圾串/from 晚于 to When 解析 Then 恒 null,不发请求
+  assert.equal(resolveHourCustomRange('', CUSTOM_TO), null)
+  assert.equal(resolveHourCustomRange(CUSTOM_FROM, ''), null)
+  assert.equal(resolveHourCustomRange('junk', CUSTOM_TO), null)
+  assert.equal(resolveHourCustomRange('2026-13-40T09:00', CUSTOM_TO), null)
+  assert.equal(resolveHourCustomRange(CUSTOM_TO, CUSTOM_FROM), null)
+})
+
+test('parseLocalDateTime 拒绝数字分量回卷的日历非法值', () => {
+  // Given 超界分量(13 月/2 月 30 日/25 时)在 Date 构造下静默回卷 When 解析 Then 逐分量回读拦截为 null
+  assert.equal(parseLocalDateTime('2026-13-01T00:00'), null)
+  assert.equal(parseLocalDateTime('2026-02-30T10:00'), null)
+  assert.equal(parseLocalDateTime('2026-03-14T25:00'), null)
+  assert.deepEqual(parseLocalDateTime('2026-03-14T09:45'), new Date(2026, 2, 14, 9, 45))
+})
+
+test('hour 自定义拒绝回卷后仍保序的非法日历输入', () => {
+  // Given 13 月回卷为次年 1 月且整体仍早于 to When 解析 Then 恒 null,不静默改写查询时段
+  assert.equal(resolveHourCustomRange('2026-13-01T00:00', '2027-06-01T00:00'), null)
+})
+
+test('minute 自定义 from 对齐 10 分钟桶,to 保持原始分钟', () => {
+  // Given from 含非对齐分钟 When 解析 Then from floor 到桶边界,to 原值保留(闭区间上界)
+  assert.deepEqual(resolveMinuteCustomRange(CUSTOM_FROM, CUSTOM_TO), { from: '2026-03-14T09:40', to: '2026-03-15T14:10' })
+  assert.deepEqual(resolveMinuteCustomRange('2026-03-14T09:40', '2026-03-15T14:17'), { from: '2026-03-14T09:40', to: '2026-03-15T14:17' })
+})
+
+test('minute 自定义跨度超保留期钳起点', () => {
+  // Given 跨度 8 天 When 解析 Then 起点钳到终点前 7 天的 10 分钟桶边界
+  assert.deepEqual(
+    resolveMinuteCustomRange('2026-03-06T00:00', '2026-03-15T14:10'),
+    { from: '2026-03-08T14:10', to: '2026-03-15T14:10' },
+  )
+})
+
+test('minute 自定义非法输入返回 null', () => {
+  assert.equal(resolveMinuteCustomRange('', CUSTOM_TO), null)
+  assert.equal(resolveMinuteCustomRange('junk', CUSTOM_TO), null)
+  assert.equal(resolveMinuteCustomRange(CUSTOM_TO, CUSTOM_FROM), null)
+})
+
+test('resolvePointQuery 预设挡返回挡位键与滚动窗口请求', () => {
+  // Given 时/分预设挡 When 解析查询 Then 键为挡位 id,请求与既有 resolve 同构
+  const hour = resolvePointQuery('hour', '24h', '', '', NOW)
+  assert.equal(hour.key, '24h')
+  assert.deepEqual(hour.request, resolveHourRange('24h', NOW))
+  const minute = resolvePointQuery('minute', '3h', '', '', NOW)
+  assert.equal(minute.key, '3h')
+  assert.deepEqual(minute.request, resolveMinuteRange('3h', NOW))
+})
+
+test('resolvePointQuery 自定义挡键含归一范围且随范围变化', () => {
+  // Given 同视图同挡不同范围 When 解析查询 Then 键互异;同范围键稳定(缓存可命中)
+  const first = resolvePointQuery('hour', 'custom', CUSTOM_FROM, CUSTOM_TO, NOW)
+  assert.deepEqual(first.request, { from: '2026-03-14T09', to: '2026-03-15T14' })
+  assert.equal(first.key, 'custom:2026-03-14T09:2026-03-15T14')
+  const again = resolvePointQuery('hour', 'custom', CUSTOM_FROM, CUSTOM_TO, NOW)
+  assert.equal(again.key, first.key)
+  const shifted = resolvePointQuery('hour', 'custom', '2026-03-14T10:45', CUSTOM_TO, NOW)
+  assert.notEqual(shifted.key, first.key)
+  const minute = resolvePointQuery('minute', 'custom', CUSTOM_FROM, CUSTOM_TO, NOW)
+  assert.deepEqual(minute.request, { from: '2026-03-14T09:40', to: '2026-03-15T14:10' })
+  assert.notEqual(minute.key, first.key)
+})
+
+test('resolvePointQuery 自定义输入不完整返回 null', () => {
+  // Given 任一端为空 When 解析查询 Then null,面板不发请求不误清缓存
+  assert.equal(resolvePointQuery('hour', 'custom', '', CUSTOM_TO, NOW), null)
+  assert.equal(resolvePointQuery('minute', 'custom', CUSTOM_FROM, '', NOW), null)
+})
+
+test('maxSlotsFor custom 挡取保留期桶数上限', () => {
+  // Given 自定义挡受保留期钳制 When 取渲染上限 Then 小时为 15 天小时桶数,分钟为 7 天 10 分钟桶数
+  assert.equal(maxSlotsFor('hour', 'custom'), 15 * 24 + 1)
+  assert.equal(maxSlotsFor('minute', 'custom'), (7 * 24 * 60) / 10 + 1)
+})
+
+test('formatDateTimeInput 产出 datetime-local 分钟粒度值', () => {
+  assert.equal(formatDateTimeInput(new Date(2026, 2, 15, 9, 5)), '2026-03-15T09:05')
+  assert.equal(formatDateTimeInput(NOW), '2026-03-15T14:30')
+})
+
 test('每视图渲染上限等于闭区间桶数', () => {
   assert.equal(maxSlotsFor('day', '90'), DAY_MAX_SLOTS)
   assert.equal(maxSlotsFor('hour', '24h'), 25)
@@ -472,50 +588,57 @@ test('heatLevel 零值为空档其余按峰值四分位', () => {
   assert.equal(heatLevel(1, 1), 5)
 })
 
-const TIP_ANCHOR = { left: 100, top: 100, right: 140, bottom: 114 }
+const TIP_ANCHOR = { x: 100, y: 100 }
 const TIP_SIZE = { width: 80, height: 40 }
 const TIP_BOUNDS = { left: 0, top: 0, right: 800, bottom: 600 }
 
-test('tipPlace 小锚点默认翻上方水平居中', () => {
-  assert.deepEqual(tipPlace(TIP_ANCHOR, TIP_SIZE, TIP_BOUNDS), { left: 80, top: 52 })
+test('tipPlace 指针右下空位放右下', () => {
+  assert.deepEqual(tipPlace(TIP_ANCHOR, TIP_SIZE, TIP_BOUNDS), { left: 108, top: 108 })
+})
+
+test('tipPlace 右侧越界翻左侧', () => {
+  assert.deepEqual(tipPlace({ x: 730, y: 100 }, TIP_SIZE, TIP_BOUNDS), { left: 642, top: 108 })
+})
+
+test('tipPlace 下方越界翻上方', () => {
+  assert.deepEqual(tipPlace({ x: 100, y: 570 }, TIP_SIZE, TIP_BOUNDS), { left: 108, top: 522 })
+})
+
+test('tipPlace 右下均越界双翻', () => {
+  assert.deepEqual(tipPlace({ x: 730, y: 570 }, TIP_SIZE, TIP_BOUNDS), { left: 642, top: 522 })
 })
 
-test('tipPlace 锚定区装得下提示框贴内顶', () => {
-  const anchor = { left: 100, top: 100, right: 240, bottom: 460 }
-  assert.deepEqual(tipPlace(anchor, TIP_SIZE, TIP_BOUNDS), { left: 130, top: 108 })
+test('tipPlace 双翻后仍越界钳进边界', () => {
+  assert.deepEqual(tipPlace({ x: 798, y: 598 }, TIP_SIZE, TIP_BOUNDS), { left: 710, top: 550 })
 })
 
-test('tipPlace 上方不足翻下方', () => {
-  const anchor = { left: 100, top: 20, right: 140, bottom: 60 }
-  assert.equal(tipPlace(anchor, TIP_SIZE, TIP_BOUNDS).top, 68)
+test('tipPlace 恰贴右缘等号归属放右侧', () => {
+  assert.deepEqual(tipPlace({ x: 704, y: 100 }, TIP_SIZE, TIP_BOUNDS), { left: 712, top: 108 })
 })
 
-test('tipPlace 候选边界等号归属', () => {
-  assert.deepEqual(tipPlace({ left: 100, top: 100, right: 240, bottom: 148 }, TIP_SIZE, TIP_BOUNDS), { left: 130, top: 108 })
-  assert.equal(tipPlace({ left: 100, top: 56, right: 140, bottom: 96 }, TIP_SIZE, TIP_BOUNDS).top, 8)
-  assert.equal(tipPlace({ left: 100, top: 8, right: 140, bottom: 48 }, TIP_SIZE, { left: 0, top: 0, right: 800, bottom: 104 }).top, 56)
+test('tipPlace 左上角指针放右下不翻转', () => {
+  assert.deepEqual(tipPlace({ x: 2, y: 2 }, TIP_SIZE, TIP_BOUNDS), { left: 10, top: 10 })
 })
 
-test('tipPlace 下方放不下翻转上方', () => {
-  const anchor = { ...TIP_ANCHOR, top: 540, bottom: 580 }
-  assert.equal(tipPlace(anchor, TIP_SIZE, TIP_BOUNDS).top, 492)
+test('tipPlace 提示框宽于边界钳贴左缘', () => {
+  assert.equal(tipPlace({ x: 400, y: 100 }, { width: 900, height: 40 }, TIP_BOUNDS).left, 8)
 })
 
-test('tipPlace 两侧均放不下钳到边界顶', () => {
-  const bounds = { left: 0, top: 0, right: 800, bottom: 50 }
-  const anchor = { left: 100, top: 20, right: 140, bottom: 50 }
-  assert.equal(tipPlace(anchor, TIP_SIZE, bounds).top, 8)
+test('pointerAt 指针事件取指针坐标', () => {
+  assert.deepEqual(pointerAt({ clientX: 12, clientY: 34 }), { x: 12, y: 34 })
 })
 
-test('tipPlace 水平越界钳到边界左缘', () => {
-  const anchor = { left: 2, top: 100, right: 10, bottom: 114 }
-  assert.equal(tipPlace(anchor, TIP_SIZE, TIP_BOUNDS).left, 8)
+test('pointerAt 焦点事件回退目标矩形中心', () => {
+  const event = {
+    currentTarget: { getBoundingClientRect: () => ({ left: 10, top: 20, right: 30, bottom: 60 }) },
+  }
+  assert.deepEqual(pointerAt(event), { x: 20, y: 40 })
 })
 
-test('tipPlace 零尺寸或全零锚定矩形返回隐藏', () => {
+test('tipPlace 零尺寸或非法锚点返回隐藏', () => {
   assert.equal(tipPlace(TIP_ANCHOR, { width: 0, height: 0 }, TIP_BOUNDS), null)
-  assert.equal(tipPlace({ left: 0, top: 0, right: 0, bottom: 0 }, TIP_SIZE, TIP_BOUNDS), null)
   assert.equal(tipPlace(null, TIP_SIZE, TIP_BOUNDS), null)
+  assert.equal(tipPlace({ x: Number.NaN, y: 100 }, TIP_SIZE, TIP_BOUNDS), null)
 })
 
 // —— S8 命中率曲线 ——
@@ -597,6 +720,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 +773,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 +856,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 千分位与两位小数', () => {