@mzzsfy/dsh-usage-dash 0.1.0

package/src/collector.js

@@ -0,0 +1,327 @@
+// 采集器:session/event 实时折叠与持久化日志回扫,产出 {time,...} 采集样本交
+// store.record 落三粒度。事件判定表、(session,turn,step) 首样本生效、归因链
+// message.source > 观测路由 > requestContext 懒播种,均与原插件同构;单次
+// 事件 pass 内的去重由 per-session fold 保证,跨 boot/回扫的不重复由持久
+// 游标(liveFirstSeq 分区 + backfilledSessions)保证。采集是观测性的:一切
+// store 失败计入 recordFailures,绝不成为逃逸拒绝。
+
+const UNKNOWN_SESSION_ID = '(unknown-session)'
+const SEQ_UNKNOWN = -1
+const DEFAULT_BACKFILL_CONCURRENCY = 4
+const MARK_BATCH = 32
+
+// 会话内单 pass 折叠:跟踪每个 (turn,step) 槽的最新报告,只把首次发射交 store
+export class UsageFold {
+  constructor() {
+    this.seen = new Map()
+  }
+
+  keyOf(event) {
+    const data = event.data
+    if (typeof data?.turn !== 'number' || typeof data?.step !== 'number') return null
+    return `${data.turn}:${data.step}`
+  }
+
+  fold(event) {
+    if (event.type === 'turn/end') {
+      // 一个 turn 恰好结束一次,失败轮也发,无需去重键
+      return {
+        time: event.time,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        turn: true,
+      }
+    }
+    if (event.type === 'step/start' || event.type === 'llm/retry-started') {
+      // step/start 恰开一次模型调用,retry-started 标记每次实际启动的重试;
+      // 请求只由标记计数,与 token 样本双计
+      return {
+        time: event.time,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        request: true,
+      }
+    }
+    if (event.type === 'assistant/chunk') {
+      const usage = event.data?.chunk?.type === 'usage' ? event.data.chunk.usage : undefined
+      return usage ? this.replaceSample(event, usage) : null
+    }
+    if (event.type === 'assistant/message') {
+      return event.data?.usage ? this.replaceSample(event, event.data.usage) : null
+    }
+    return null
+  }
+
+  replaceSample(event, usage) {
+    // 四桶全零为噪声;纯缓存调用(仅缓存桶非零)仍有效
+    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,
+      outputTokens: usage.outputTokens ?? 0,
+      cacheReadTokens: usage.cacheReadTokens ?? 0,
+      cacheWriteTokens: usage.cacheWriteTokens ?? 0,
+    }
+    if (key === null) return sample
+    const prev = this.seen.get(key)
+    this.seen.set(key, sample)
+    // 首样本生效:内部无条件跟踪最新报告,但交 store 的只有首次发射的独立拷贝
+    return prev ? null : { ...sample }
+  }
+}
+
+function sessionIdOf(target) {
+  const id = target?.id
+  return typeof id === 'string' && id !== '' ? id : UNKNOWN_SESSION_ID
+}
+
+// 规范 provider/model 引用:双全拼引用,仅 model 用裸名
+function refOf(route) {
+  if (!route) return undefined
+  if (route.provider && route.model) return `${route.provider}/${route.model}`
+  return route.model || undefined
+}
+
+export class UsageCollector {
+  constructor(ctx, store) {
+    this.ctx = ctx
+    this.store = store
+    this.folds = new Map()
+    this.routes = new Map()
+    this.started = false
+    this.liveMarked = new Set()
+    this.liveMarkBuffer = new Map()
+    this.liveMarkFlushScheduled = false
+    this.scanController = null
+    this.resetInFlight = null
+    this.#state = {
+      running: false,
+      total: 0,
+      done: 0,
+      scannedSessions: 0,
+      lastSessionId: undefined,
+      error: undefined,
+      recordFailures: 0,
+      skippedSessions: 0,
+    }
+    // error 保留给采集器自身故障;单会话读取失败走 skippedSessions 跳过计数
+  }
+
+  #state
+
+  status() {
+    return { ...this.#state }
+  }
+
+  get running() {
+    return this.#state.running
+  }
+
+  // reset 引发的重扫同样 running 为 true,409 守卫据此区分两种 running
+  get rebuilding() {
+    return this.resetInFlight !== null
+  }
+
+  start() {
+    if (this.started) return
+    this.started = true
+    this.ctx.on?.('session/event', (session, event) => {
+      const sid = sessionIdOf(session)
+      this.markLiveSession(sid, event?.seq)
+      if (event.type === 'request/context') {
+        if (event.data?.provider && event.data?.model) this.routes.set(sid, `${event.data.provider}/${event.data.model}`)
+        else if (event.data?.model) this.routes.set(sid, event.data.model)
+      }
+      let fromSource
+      if (event.type === 'assistant/message') {
+        fromSource = refOf(event.data?.message?.source)
+        if (fromSource !== undefined) this.routes.set(sid, fromSource)
+      }
+      const sample = this.foldFor(sid).fold(event)
+      if (!sample) return
+      // turn 标记落合成行不归因;其余样本先取本调用 source,再取会话路由
+      if (!sample.turn) sample.model = fromSource ?? this.routeFor(sid)
+      void this.store.record(sample).catch(() => {
+        this.#state.recordFailures += 1
+      })
+    })
+    // 释放销毁会话的内存桶,防长跑宿主按会话数累积
+    this.ctx.on?.('session/disposed', (session) => {
+      const sid = sessionIdOf(session)
+      this.folds.delete(sid)
+      this.routes.delete(sid)
+    })
+  }
+
+  routeFor(sid) {
+    const known = this.routes.get(sid)
+    if (known !== undefined) return known
+    // request/context 只在路由变更时落日志,先于采集器存在的会话靠
+    // requestContext() 懒播种归因,否则用量全部落入 (unknown)
+    const ref = refOf(this.ctx.sessions?.get?.(sid)?.requestContext?.())
+    if (ref !== undefined) this.routes.set(sid, ref)
+    return ref
+  }
+
+  foldFor(sid) {
+    let fold = this.folds.get(sid)
+    if (!fold) {
+      fold = new UsageFold()
+      this.folds.set(sid, fold)
+    }
+    return fold
+  }
+
+  // 首个被观测的实时事件写入游标边界,合批为单次 markLiveSequences;
+  // -1 哨兵记录"观测到但边界未知",语义是重放零事件,宁漏不冒双计
+  markLiveSession(sid, firstSeq) {
+    if (sid === UNKNOWN_SESSION_ID || this.liveMarked.has(sid)) return
+    this.liveMarked.add(sid)
+    this.liveMarkBuffer.set(sid, typeof firstSeq === 'number' ? firstSeq : SEQ_UNKNOWN)
+    if (this.liveMarkFlushScheduled) return
+    this.liveMarkFlushScheduled = true
+    queueMicrotask(() => {
+      this.liveMarkFlushScheduled = false
+      const batch = [...this.liveMarkBuffer.entries()]
+      this.liveMarkBuffer.clear()
+      if (batch.length > 0) {
+        void this.store.markLiveSequences(batch).catch(() => {
+          this.#state.recordFailures += 1
+        })
+      }
+    })
+  }
+
+  // 单控制器槽:boot 回扫、reset 重扫共用,新扫描先中止旧扫描
+  async rescan() {
+    this.scanController?.abort()
+    const controller = new AbortController()
+    this.scanController = controller
+    await this.store.readyPromise()
+    await this.backfill(this.ctx.sessionPersistence, this.ctx.sessions, controller.signal)
+  }
+
+  abort() {
+    this.scanController?.abort()
+  }
+
+  // wipe 时刻为每个活跃会话取日志长度作重放上界:回扫恰好重建 [0,watermark)
+  // 一次,watermark 起的事件仍归在跑的实时路径;seq 读不出沿用旧游标边界,
+  // 无则 -1 哨兵。死会话不进边界,全量重放即精确。并发调用合并为一次重建
+  resetAndRescan() {
+    if (this.resetInFlight) return this.resetInFlight
+    this.resetInFlight = (async () => {
+      const previous = await this.store.liveSequences()
+      const boundaries = new Map()
+      for (const handle of this.ctx.sessions.list()) {
+        const seq = handle.seq
+        if (typeof seq === 'number' && Number.isFinite(seq) && seq >= 0) {
+          boundaries.set(handle.id, seq)
+          continue
+        }
+        const old = previous.get(handle.id)
+        boundaries.set(handle.id, typeof old === 'number' ? old : SEQ_UNKNOWN)
+      }
+      await this.store.reset(boundaries)
+      await this.rescan()
+    })().finally(() => {
+      this.resetInFlight = null
+    })
+    return this.resetInFlight
+  }
+
+  // 回扫:persistence.list 驱动,逐会话全新 fold 重放;seen 独自决定是否重扫,
+  // liveFirstSeq 边界划走实时已拥区间,liveness 复查防陈旧快照放大重放范围,
+  // inheritedCut 跳过 fork 继承前缀。只有干净重放完的会话进游标,失败下轮重试
+  async backfill(persistence, 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 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.skippedSessions = 0
+      const workerCount = Math.min(DEFAULT_BACKFILL_CONCURRENCY, Math.max(1, targets.length))
+      let next = 0
+      const completed = []
+      const flushCompleted = async () => {
+        if (completed.length === 0) return
+        const batch = completed.splice(0, completed.length)
+        await this.store.markSeenSessions(batch)
+      }
+      const worker = async () => {
+        for (;;) {
+          if (signal?.aborted) return
+          const i = next++
+          if (i >= targets.length) return
+          const header = targets[i]
+          this.#state.lastSessionId = header.id
+          const boundary = liveSeq.get(header.id)
+          // 活跃会话仅在有有效边界时安全重放前缀;无边界或 -1 哨兵说明
+          // 事件归本 boot 实时路径,或会话 mid-scan 恢复、边界在快照后写入
+          const isLiveNow = sessions.list().some((item) => item.id === header.id)
+          if (isLiveNow && (boundary === undefined || boundary < 0)) {
+            this.#state.done += 1
+            continue
+          }
+          const fromScratch = boundary === undefined
+          const replayNothing = !fromScratch && boundary < 0
+          const skipLiveOwned = (event) => {
+            if (replayNothing) return true
+            if (fromScratch) return false
+            return typeof event.seq === 'number' && event.seq >= boundary
+          }
+          // 每会话全新 fold:(turn,step) 键按会话隔离,并发重放不共享
+          const fold = new UsageFold()
+          let route = ''
+          try {
+            const inspection = await persistence.inspect(header.id, signal)
+            const inheritedCut = inspection.inheritedEventCount
+            for (const event of inspection.events) {
+              if (signal?.aborted) return
+              if (skipLiveOwned(event)) continue
+              if (inheritedCut > 0 && typeof event.seq === 'number' && event.seq < inheritedCut) continue
+              // 继承前缀整体跳过含路由播种:子会话路由在首次变更时重新宣告
+              if (event.type === 'request/context') {
+                if (event.data?.provider && event.data?.model) route = `${event.data.provider}/${event.data.model}`
+                else if (event.data?.model) route = event.data.model
+              } else if (event.type === 'assistant/message') {
+                const ref = refOf(event.data?.message?.source)
+                if (ref !== undefined) route = ref
+              }
+              const sample = fold.fold(event)
+              if (sample) {
+                if (!sample.turn) sample.model = route || undefined
+                await this.store.record(sample)
+              }
+            }
+            completed.push(header.id)
+            if (completed.length >= MARK_BATCH) await flushCompleted()
+            this.#state.scannedSessions += 1
+          } catch {
+            // 读取失败(如宿主报会话日志损坏)按定案跳过:计数并继续,不中断回扫、不挂错误横幅
+            this.#state.skippedSessions += 1
+          } finally {
+            this.#state.done += 1
+          }
+        }
+      }
+      await Promise.all(Array.from({ length: workerCount }, () => worker()))
+      await flushCompleted()
+    } finally {
+      this.#state.running = false
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,104 @@
+// 用量统计面板 Host 半区:采集 session/event 落 usage_stats 域,经 webServer
+// 暴露 /api/usage-dash/* 供浏览器半区消费。S2 落存储域与 settings 注册,
+// S3 接入采集与启动回扫,S13 扩展 pricing 形状并接线定价能力。
+
+import schemastery from '@deepseek-ai/schemastery'
+
+import { UsageCollector } from './collector.js'
+import { CURRENCIES, CONDITION_KINDS, UNIT_PER_MILLION } from './pricing.js'
+import { registerUsageRoutes } from './routes.js'
+import { DEFAULT_MINUTE_RETENTION_DAYS, sharedStore } from './store.js'
+// 顶层 inject 仅声明 web profile 必然存在的四个服务;settings 在 apply 内
+// 嵌套 inject(通道级静默不激活),构成干净禁用。
+export const inject = ['webServer', 'sessionPersistence', 'sessions', 'storageDomain']
+
+export const name = 'dsh-usage-dash'
+
+const SETTINGS_NAMESPACE = 'usage-dash'
+
+// 定价形状与 pricing.js 契约同源:kind 判别 required 恒成立,
+// 防 nullable 直通误入首个 union 成员
+const WEEKDAY_MIN = 0
+const WEEKDAY_MAX = 6
+
+const CONDITION_FIELD_SCHEMAS = {
+  dailyWindow: { from: schemastery.string(), to: schemastery.string() },
+  weekdays: { days: schemastery.array(schemastery.number().min(WEEKDAY_MIN).max(WEEKDAY_MAX).step(1)) },
+  monthDays: { from: schemastery.number().step(1), to: schemastery.number().step(1) },
+  dateRange: { from: schemastery.string(), to: schemastery.string() },
+}
+
+const CONDITION_SCHEMA = schemastery.union(
+  CONDITION_KINDS.map((kind) => schemastery.object({
+    kind: schemastery.const(kind).required(),
+    ...CONDITION_FIELD_SCHEMAS[kind],
+  })),
+)
+
+const PRICING_RULE_SCHEMA = schemastery.object({
+  model: schemastery.string(),
+  unit: schemastery.const(UNIT_PER_MILLION),
+  currency: schemastery.union(CURRENCIES.map((currency) => schemastery.const(currency))),
+  price: schemastery.object({
+    input: schemastery.number().min(0),
+    output: schemastery.number().min(0),
+    cacheRead: schemastery.number().min(0),
+    cacheWrite: schemastery.number().min(0),
+  }),
+  conditions: schemastery.array(CONDITION_SCHEMA),
+})
+
+const SETTINGS_SCHEMA = schemastery.object({
+  minuteRetentionDays: schemastery.number().min(0).step(1).default(DEFAULT_MINUTE_RETENTION_DAYS)
+    .description('分钟桶保留天数(上限 48h),0 表示禁用分钟桶'),
+  pricing: schemastery.object({ rules: schemastery.array(PRICING_RULE_SCHEMA) })
+    .description('定价规则(wire 由 /api/usage-dash/pricing 读写)'),
+})
+
+export function apply(ctx, config) {
+  const store = sharedStore(ctx.storageDomain)
+  const collector = new UsageCollector(ctx, store)
+  // pricing 能力门面:settings 激活前置 active=false(routes 侧 GET 空值、
+  // POST 拒 503),激活后实时读 settings——改价下次查询即时生效
+  const pricing = {
+    active: false,
+    rules: () => [],
+    revision: () => 0,
+    replace: async () => {
+      throw new Error('usage-dash: pricing settings inactive')
+    },
+  }
+  ctx.inject(['settings'], (settingsCtx) => {
+    const settings = settingsCtx.settings
+    settings.register(SETTINGS_NAMESPACE, SETTINGS_SCHEMA, { base: config })
+    // 每日本地日首次写入时按保留值清理分钟/小时桶;启动回扫前的触发在下方回扫入口
+    store.retentionDays = () =>
+      settings.get(SETTINGS_NAMESPACE)?.minuteRetentionDays ?? DEFAULT_MINUTE_RETENTION_DAYS
+    pricing.active = true
+    pricing.rules = () => settings.get(SETTINGS_NAMESPACE)?.pricing?.rules ?? []
+    // revision 取 describe 中本 ns 描述符,settings 任何写入都会自增
+    pricing.revision = () =>
+      settings.describe().find((descriptor) => descriptor.ns === SETTINGS_NAMESPACE)?.revision ?? 0
+    pricing.replace = async (rules) => {
+      // update 深合并下数组整体替换,不动 minuteRetentionDays 用户层
+      await settings.update(SETTINGS_NAMESPACE, { pricing: { rules } })
+      return settings.get(SETTINGS_NAMESPACE)?.pricing?.rules ?? []
+    }
+  })
+  const bootScan = async () => {
+    await store.readyPromise()
+    await store.pruneMinutes()
+    await store.pruneHours()
+    await collector.rescan()
+  }
+  ctx.effect(() => {
+    collector.start()
+    void bootScan().catch((err) => {
+      ctx.logger?.warn(`usage-dash: 启动回扫未完成 ${err instanceof Error ? err.message : String(err)}`)
+    })
+    // 卸载中止在飞扫描,防热重载后遗留扫描向已关闭的域写入
+    return () => collector.abort()
+  }, 'usage-dash: collector')
+  // 保留值经 store 单源转发:settings 激活即取设置值,未激活回落构造默认
+  registerUsageRoutes(ctx, { store, collector, retentionDays: () => store.retentionDays(), pricing })
+}

package/src/pricing.js

@@ -0,0 +1,119 @@
+// 定价纯函数:规则匹配与四桶计价,零宿主依赖、零 IO、无全局状态。
+// 本地时区取 Date 本地分量,timestamp 接受 Date 或 epoch 毫秒;匹配只读遍历入参规则。
+
+export const UNIT_PER_MILLION = 'perMillion'
+export const CURRENCIES = ['¥', '$']
+export const CONDITION_KINDS = ['dailyWindow', 'weekdays', 'monthDays', 'dateRange']
+export const TOKENS_PER_MILLION = 1000 * 1000
+
+const MODEL_WILDCARD = '*'
+const MINUTES_PER_HOUR = 60
+const DAY_PART_WIDTH = 2
+const ISO_DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+const pad = (value) => String(value).padStart(DAY_PART_WIDTH, '0')
+const formatDate = (date) => `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+
+const minutesOfDay = (date) => date.getHours() * MINUTES_PER_HOUR + date.getMinutes()
+
+const toMinutesOfDay = (hhmm) => {
+  if (typeof hhmm !== 'string') return Number.NaN
+  const [hours, minutes] = hhmm.split(':')
+  const h = Number(hours)
+  const m = Number(minutes)
+  return Number.isFinite(h) && Number.isFinite(m) ? h * MINUTES_PER_HOUR + m : Number.NaN
+}
+
+// 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
+}
+
+// days 空数组不成立;0=周日,取 getDay()
+const weekdaysMatches = (condition, date) => {
+  const { days } = condition
+  return Array.isArray(days) && days.length > 0 && days.includes(date.getDay())
+}
+
+// 号段双闭;from>to 跨月环绕(如 26~25 账单周期);日号必须整数,2 月无 31 号自然不触发
+const monthDaysMatches = (condition, date) => {
+  const { from, to } = condition
+  if (!Number.isInteger(from) || !Number.isInteger(to)) return false
+  const d = date.getDate()
+  return from <= to ? d >= from && d <= to : d >= from || d <= to
+}
+
+// 要求零填充 YYYY-MM-DD 字典序双闭;from>to 属配置错误不成立,非规范串同样不成立
+const dateRangeMatches = (condition, date) => {
+  const { from, to } = condition
+  if (typeof from !== 'string' || typeof to !== 'string') return false
+  if (!ISO_DAY_PATTERN.test(from) || !ISO_DAY_PATTERN.test(to) || from > to) return false
+  const iso = formatDate(date)
+  return iso >= from && iso <= to
+}
+
+const CONDITION_MATCHERS = {
+  dailyWindow: dailyWindowMatches,
+  weekdays: weekdaysMatches,
+  monthDays: monthDaysMatches,
+  dateRange: dateRangeMatches,
+}
+
+// 单条件判定;未知 kind、形状残缺或非法 Date 一律不成立
+export const conditionMatches = (condition, date) => {
+  const matcher = condition && CONDITION_MATCHERS[condition.kind]
+  if (!matcher || !(date instanceof Date) || Number.isNaN(date.getTime())) return false
+  return matcher(condition, date)
+}
+
+// 形状残缺规则跳过:缺 model/price、unit 非 perMillion、conditions 非数组(含缺失)
+const isRuleShaped = (rule) =>
+  !!rule && typeof rule === 'object' && typeof rule.model === 'string'
+  && (rule.unit === undefined || rule.unit === UNIT_PER_MILLION)
+  && !!rule.price && typeof rule.price === 'object' && !Array.isArray(rule.price)
+  && Array.isArray(rule.conditions)
+
+const firstMatchingPrice = (rules, date, modelFilter) => {
+  for (const rule of rules) {
+    if (!isRuleShaped(rule) || !modelFilter(rule)) continue
+    if (rule.conditions.every((condition) => conditionMatches(condition, date))) return rule.price
+  }
+  return null
+}
+
+const toLocalDate = (timestamp) => {
+  const date = timestamp instanceof Date ? timestamp : new Date(timestamp)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+// 精确子集按数组序取首个命中;无精确子集或全不命中回落 '*' 子集;仍无命中为 null(调用方计 unpriced)
+export const matchPrice = (rules, model, timestamp) => {
+  const date = toLocalDate(timestamp)
+  if (!Array.isArray(rules) || !date || typeof model !== 'string') return null
+  return firstMatchingPrice(rules, date, (rule) => rule.model === model)
+    ?? firstMatchingPrice(rules, date, (rule) => rule.model === MODEL_WILDCARD)
+}
+
+const BUCKET_PRICE_KEYS = [
+  { tokens: 'inputTokens', price: 'input' },
+  { tokens: 'outputTokens', price: 'output' },
+  { tokens: 'cacheReadTokens', price: 'cacheRead' },
+  { tokens: 'cacheWriteTokens', price: 'cacheWrite' },
+]
+
+const toFiniteNumber = (value) => (Number.isFinite(value) ? value : 0)
+
+// 费用 = Σ(桶 token × 桶单价) / 每百万;缺桶或非法值按 0,原始浮点不圆整(展示层负责)
+export const costOf = (price, buckets) => {
+  let raw = 0
+  for (const { tokens, price: priceKey } of BUCKET_PRICE_KEYS) {
+    raw += toFiniteNumber(buckets?.[tokens]) * toFiniteNumber(price?.[priceKey])
+  }
+  return raw / TOKENS_PER_MILLION
+}