@mzzsfy/dsh-usage-dash 0.3.0 → 0.5.0

package/src/collector.js

@@ -5,19 +5,87 @@
 // 游标(liveFirstSeq 分区 + backfilledSessions)保证。采集是观测性的:一切
 // store 失败计入 recordFailures,绝不成为逃逸拒绝。
 
+import { createArchiveReader } from './archive-reader.js'
+
 const UNKNOWN_SESSION_ID = '(unknown-session)'
 const SEQ_UNKNOWN = -1
 const DEFAULT_BACKFILL_CONCURRENCY = 4
 const MARK_BATCH = 32
 const SCAN_LOG_MAX_ENTRIES = 200
 
+// 不可读会话分类:宿主可见性/可读性边界的三代实测形态(见 README 存档兼容)
+const SKIP_KINDS = { descriptor: 'descriptor', corrupt: 'corrupt', legacy: 'legacy', other: 'other' }
+const SKIP_PATTERNS = [
+  // 宿主新校验拒读历史档(0.1.5 descriptor v2),宿主修复后自动补扫
+  [SKIP_KINDS.descriptor, /unsupported descriptor version/i],
+  // 存档损坏(seq gap 等 fail-closed 拒绝),宿主 repair 后自动补扫
+  [SKIP_KINDS.corrupt, /corrupt|seq gap|SessionFormatError/i],
+  // 超旧格式词汇(v0 时代字段),宿主迁移链覆盖后自动补扫
+  [SKIP_KINDS.legacy, /format v0|unexpected member|does not provide|not a function/i],
+]
+
+function classifySkip(detail) {
+  for (const [kind, pattern] of SKIP_PATTERNS) {
+    if (pattern.test(detail)) return kind
+  }
+  return SKIP_KINDS.other
+}
+
+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) {
@@ -40,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,
@@ -52,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
@@ -63,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,
@@ -75,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
   }
 }
 
@@ -95,8 +219,9 @@ function sessionIdOf(target) {
   return typeof id === 'string' && id !== '' ? id : UNKNOWN_SESSION_ID
 }
 
-// 规范 provider/model 引用:双全拼引用,仅 model 用裸名
-function refOf(route) {
+// 规范 provider/model 引用:双全拼引用,仅 model 用裸名;
+// 与 client 侧注入点B turnModelOf 双实现同源(routes[].model 是裸模型名,展示侧才拼 provider),改一侧必须同步 parity
+export function refOf(route) {
   if (!route) return undefined
   if (route.provider && route.model) return `${route.provider}/${route.model}`
   return route.model || undefined
@@ -126,6 +251,10 @@ export class UsageCollector {
       lastSessionId: undefined,
       error: undefined,
       log: [],
+      // 计数独立累加,不受日志截断影响;skipped 细分供面板归因
+      skippedTotal: 0,
+      recordTotal: 0,
+      skipCounts: emptySkipCounts(),
     }
     // error 保留给采集器自身故障;单会话读取失败走日志 skipped 条目,计数由日志派生
   }
@@ -141,17 +270,24 @@ export class UsageCollector {
       scannedSessions: this.#state.scannedSessions,
       lastSessionId: this.#state.lastSessionId,
       error: this.#state.error,
-      skippedSessions: log.filter((entry) => entry.kind === 'skipped').length,
-      recordFailures: log.filter((entry) => entry.kind === 'record').length,
+      skippedSessions: this.#state.skippedTotal,
+      recordFailures: this.#state.recordTotal,
+      skippedBreakdown: { ...this.#state.skipCounts },
       log,
     }
   }
 
-  // 扫描异常日志:供面板明细展示,超上限丢最旧
+  // 扫描异常日志:供面板明细展示,超上限丢最旧;计数独立累加不随截断漂移
   pushLog(kind, detail) {
     const log = this.#state.log
     log.push({ time: Date.now(), kind, detail })
     if (log.length > SCAN_LOG_MAX_ENTRIES) log.splice(0, log.length - SCAN_LOG_MAX_ENTRIES)
+    if (kind === 'skipped') {
+      this.#state.skippedTotal += 1
+      this.#state.skipCounts[classifySkip(detail)] += 1
+    } else if (kind === 'record') {
+      this.#state.recordTotal += 1
+    }
   }
 
   get running() {
@@ -239,7 +375,9 @@ export class UsageCollector {
     const controller = new AbortController()
     this.scanController = controller
     await this.store.readyPromise()
-    await this.backfill(this.ctx.sessionPersistence, this.ctx.sessions, controller.signal)
+    // 适配发生在宿主服务边界:回扫主体只面向 ArchiveReader 内部契约
+    const reader = createArchiveReader(this.ctx.sessionPersistence)
+    await this.backfill(reader, this.ctx.sessions, controller.signal)
   }
 
   abort() {
@@ -271,22 +409,30 @@ export class UsageCollector {
     return this.resetInFlight
   }
 
-  // 回扫:persistence.list 驱动,逐会话全新 fold 重放;seen 独自决定是否重扫,
-  // liveFirstSeq 边界划走实时已拥区间,liveness 复查防陈旧快照放大重放范围,
-  // inheritedCut 跳过 fork 继承前缀。只有干净重放完的会话进游标,失败下轮重试
-  async backfill(persistence, sessions, signal) {
+  // 回扫:ArchiveReader 契约驱动(宿主 persistence 多版本适配见 archive-reader),
+  // 逐会话全新 fold 重放;seen 独自决定是否重扫,liveFirstSeq 边界划走实时
+  // 已拥区间,liveness 复查防陈旧快照放大重放范围,inheritedCut 跳过 fork
+  // 继承前缀。只有干净重放完的会话进游标,失败下轮重试
+  async backfill(reader, sessions, signal) {
     if (this.#state.running) return
     if (signal?.aborted) return
     this.#state.running = true
     this.#state.error = undefined
     try {
-      const headers = await persistence.list(signal)
+      const headers = await reader.list(signal).catch((error) => {
+        // 枚举失败(含宿主 API 未识别)按采集器自身故障呈现,面板可见
+        this.#state.error = error instanceof Error ? error.message : String(error)
+        throw error
+      })
       const seen = await this.store.seenSessions()
       const liveSeq = await this.store.liveSequences()
       const targets = headers.filter((header) => !seen.has(header.id))
       this.#state.total = targets.length
       this.#state.done = 0
       this.#state.log = []
+      this.#state.skippedTotal = 0
+      this.#state.recordTotal = 0
+      this.#state.skipCounts = emptySkipCounts()
       const workerCount = Math.min(DEFAULT_BACKFILL_CONCURRENCY, Math.max(1, targets.length))
       let next = 0
       const completed = []
@@ -321,7 +467,7 @@ export class UsageCollector {
           const fold = new UsageFold()
           let route = ''
           try {
-            const inspection = await persistence.inspect(header.id, signal)
+            const inspection = await reader.readLog(header.id, signal)
             const inheritedCut = inspection.inheritedEventCount
             for (const event of inspection.events) {
               if (signal?.aborted) return

package/src/direct-log-reader.js

@@ -0,0 +1,126 @@
+// 会话档案文件直读器:宿主 persistence 服务 fail-closed 拒读(descriptor 校验、
+// 格式校验、seq gap 等)时,对磁盘档案做降级直读。统计只消费 usage 词汇
+// (assistant/message 的 usage 与 request/context 路由),无需完整会话语义,
+// 宽松解析即可恢复;corrupt(seq gap)与 legacy(未知成员)对统计无影响。
+//
+// 物理格式(与宿主 jsonl 后端同构):首行 header JSON + 事件行 JSONL 文本,
+// 按 zstd 帧独立压缩顺序拼接;帧以 magic 28 b5 2f fd 起始。压缩由 Node 内置
+// node:zlib 提供(Node >= 24),不依赖宿主模块,不受宿主升级影响。
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { zstdDecompressSync } from 'node:zlib'
+
+const ZSTD_MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
+
+// 档案根目录:DSH_HOME 可重定向(多版本共存测试的隔离约定),默认 ~/.dsh
+function sessionsRoot() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  return join(home, 'sessions')
+}
+
+// 按帧边界切分 zstd 流:帧首 magic 定位,各帧解压范围到下一 magic 或流尾
+function frameRanges(bytes) {
+  const ranges = []
+  let at = bytes.indexOf(ZSTD_MAGIC)
+  while (at >= 0) {
+    if (ranges.length > 0) ranges[ranges.length - 1].end = at
+    ranges.push({ start: at, end: bytes.length })
+    at = bytes.indexOf(ZSTD_MAGIC, at + ZSTD_MAGIC.length)
+  }
+  return ranges
+}
+
+// 多帧解压;任何一帧失败即整体失败(宁缺勿错,调用方按原拒读路径上报)
+export function decodeZstdFile(bytes) {
+  const ranges = frameRanges(bytes)
+  if (ranges.length === 0) throw new Error('no zstd frame found')
+  let text = ''
+  for (const range of ranges) {
+    text += zstdDecompressSync(bytes.subarray(range.start, range.end)).toString('utf8')
+  }
+  return text
+}
+
+// JSONL 文本 → 宽松事件流:首行为档案 header,其余行逐行解析,坏行跳过;
+// 只要求行能解出 JSON 对象,词汇/代际差异由上层折叠消化
+export function parseJsonlEvents(text) {
+  const events = []
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    try {
+      const row = JSON.parse(trimmed)
+      if (row && typeof row === 'object' && row.type !== undefined && row.type !== 'session/header') {
+        events.push(row)
+      }
+    } catch {}
+  }
+  return events
+}
+
+// 会话目录定位:sessions/<cwd 编码桶>/<id>/;桶名是宿主对 cwd 的编码,不解析,
+// 逐桶探测 id 子目录
+export function findSessionDir(id, root = sessionsRoot()) {
+  const sessions = root
+  if (!existsSync(sessions)) return undefined
+  for (const bucket of readdirSync(sessions)) {
+    const candidate = join(sessions, bucket, id)
+    if (existsSync(candidate) && statDirSync(candidate)) return candidate
+  }
+  return undefined
+}
+
+function statDirSync(path) {
+  try {
+    return readdirSync(path).length >= 0
+  } catch {
+    return false
+  }
+}
+
+// 会话目录内选最新代档案:V3 专用名优先,退化为任意 jsonl(压缩/明文)
+function pickLogFile(dir) {
+  const names = readdirSync(dir)
+  const v3 = names.find((name) => name.startsWith('session.v3.') && name.endsWith('.zstd'))
+  if (v3) return join(dir, v3)
+  const compressed = names.find((name) => name.endsWith('.jsonl.zstd'))
+  if (compressed) return join(dir, compressed)
+  const plain = names.find((name) => name.endsWith('.jsonl'))
+  if (plain) return join(dir, plain)
+  return undefined
+}
+
+// 直读单会话事件流;文件缺失/无法解压抛错,由调用方决定降级链终止
+export function readSessionLogDirect(id, root) {
+  const dir = findSessionDir(id, root)
+  if (dir === undefined) throw new Error(`session artifact directory not found: ${id}`)
+  const file = pickLogFile(dir)
+  if (file === undefined) throw new Error(`session artifact file not found: ${id}`)
+  const bytes = readFileSync(file)
+  const text = file.endsWith('.zstd') ? decodeZstdFile(bytes) : bytes.toString('utf8')
+  return parseJsonlEvents(text)
+}
+
+// 磁盘全量会话 id:sessions/<cwd 编码桶>/<id>/;旧代宿主的 list 不枚举新代
+// 文件名的档案,直读侧补齐可见集
+export function listSessionIdsDirect(root = sessionsRoot()) {
+  if (!existsSync(root)) return []
+  const ids = []
+  for (const bucket of readdirSync(root)) {
+    const bucketPath = join(root, bucket)
+    let entries
+    try {
+      entries = readdirSync(bucketPath)
+    } catch {
+      continue
+    }
+    for (const id of entries) {
+      if (existsSync(join(bucketPath, id, 'session.jsonl.zstd')) || existsSync(join(bucketPath, id, 'session.v3.jsonl.zstd'))) {
+        ids.push(id)
+      }
+    }
+  }
+  return ids
+}

package/src/pricing.js

@@ -30,15 +30,14 @@ const toMinutesOfDay = (hhmm) => {
   return Number.isFinite(h) && Number.isFinite(m) ? h * MINUTES_PER_HOUR + m : Number.NaN
 }
 
-// from<to 含头不含尾;from>to 跨午夜;from===to 全天生效
+// 所有范围条件统一双侧包含;from>to 跨午夜/跨月环绕;from===to 单点/单日
 const dailyWindowMatches = (condition, date) => {
   const from = toMinutesOfDay(condition.from)
   const to = toMinutesOfDay(condition.to)
   if (Number.isNaN(from) || Number.isNaN(to)) return false
   const m = minutesOfDay(date)
-  if (from < to) return m >= from && m < to
-  if (from > to) return m >= from || m < to
-  return true
+  if (from <= to) return m >= from && m <= to
+  return m >= from || m <= to
 }
 
 // days 空数组不成立;0=周日,取 getDay()
@@ -47,7 +46,7 @@ const weekdaysMatches = (condition, date) => {
   return Array.isArray(days) && days.length > 0 && days.includes(date.getDay())
 }
 
-// 号段双闭;from>to 跨月环绕(如 26~25 账单周期);日号必须整数,2 月无 31 号自然不触发
+// 号段双侧包含;from>to 跨月环绕(账单周期);from===to 单日,2 月无 31 号自然不触发
 const monthDaysMatches = (condition, date) => {
   const { from, to } = condition
   if (!Number.isInteger(from) || !Number.isInteger(to)) return false
@@ -55,7 +54,7 @@ const monthDaysMatches = (condition, date) => {
   return from <= to ? d >= from && d <= to : d >= from || d <= to
 }
 
-// 要求零填充 YYYY-MM-DD 字典序双闭;from>to 属配置错误不成立,非规范串同样不成立
+// 零填充 YYYY-MM-DD 字典序双侧包含;from>to 配置错误不成立(编辑器校验拦截)
 const dateRangeMatches = (condition, date) => {
   const { from, to } = condition
   if (typeof from !== 'string' || typeof to !== 'string') return false

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/routes.js

@@ -274,7 +274,10 @@ const pricingHandler = (deps) => async (req, res) => {
 }
 
 const statusHandler = (deps) => async (req, res) => {
-  writeJson(res, { ok: true, value: deps.collector.status() })
+  writeJson(res, {
+    ok: true,
+    value: { ...deps.collector.status(), backup: deps.store.backupInfo() },
+  })
 }
 
 // 409 只拒 boot 期扫描;reset 自身引发的重扫同样 running 为真,经 rebuilding 放行
@@ -286,6 +289,15 @@ const resetHandler = (deps) => async (req, res) => {
   writeJson(res, { ok: true, value: deps.collector.status() })
 }
 
+// 回退到最近一次重建(或恢复)前的快照;扫描进行中同样拒绝,避免写交错
+const restoreHandler = (deps) => async (req, res) => {
+  if (deps.collector.running) {
+    throw usageError(HTTP_STATUS_CONFLICT, MESSAGE_BACKFILL_RUNNING)
+  }
+  const result = await deps.store.restoreFromBackup()
+  writeJson(res, { ok: true, value: result })
+}
+
 const STANDARD_GUARDS = [rejectWrongMethod, rejectCrossOrigin, rejectNonJson]
 const PRICING_GUARDS = [rejectPricingMethod, rejectCrossOrigin]
 
@@ -295,6 +307,7 @@ const ENDPOINTS = [
   { path: `${ROUTE_PREFIX}/minutes`, mount: minuteHandler },
   { path: `${ROUTE_PREFIX}/status`, mount: statusHandler },
   { path: `${ROUTE_PREFIX}/reset`, mount: resetHandler },
+  { path: `${ROUTE_PREFIX}/restore`, mount: restoreHandler },
   { path: `${ROUTE_PREFIX}/pricing`, mount: pricingHandler, guards: PRICING_GUARDS },
 ]