@mzzsfy/dsh-usage-stats 0.2.0

package/src/ledger.mjs

@@ -0,0 +1,217 @@
+// 用量统计纯账本模块:调用记录聚合到日/会话,汇总与修剪;模型计价表。
+// 只做数据变换,无 IO;host 半区直接 import 本模块。
+
+const LEDGER_VERSION = 2
+const TOKENS_PER_UNIT = 1000000
+
+function dayKeyOf(ts) {
+  const d = new Date(ts)
+  const pad = (n) => (n < 10 ? '0' + n : String(n))
+  return d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate())
+}
+
+function createLedger() {
+  return { version: LEDGER_VERSION, days: {}, sessions: {} }
+}
+
+// v1 旧账本无顶层 sessions 索引:载入时视为空并按新结构增量写入,不回填历史;结构升级后版本号置位。
+function ensureSessionsIndex(ledger) {
+  if (!ledger.sessions || typeof ledger.sessions !== 'object') ledger.sessions = {}
+  ledger.version = LEDGER_VERSION
+  return ledger
+}
+
+function ensureBucket(days, key) {
+  if (!days[key]) {
+    days[key] = { inputTokens: 0, cacheReadTokens: 0, outputTokens: 0, calls: 0, cost: 0, sessions: {} }
+  }
+  return days[key]
+}
+
+function ensureSession(day, sessionId) {
+  const id = sessionId || 'unknown'
+  if (!day.sessions[id]) {
+    day.sessions[id] = { inputTokens: 0, cacheReadTokens: 0, outputTokens: 0, calls: 0, cost: 0, models: {} }
+  }
+  return day.sessions[id]
+}
+
+function addTokens(target, call) {
+  if (Number.isFinite(call.inputTokens)) target.inputTokens += call.inputTokens
+  if (Number.isFinite(call.cacheReadTokens)) target.cacheReadTokens += call.cacheReadTokens
+  if (Number.isFinite(call.outputTokens)) target.outputTokens += call.outputTokens
+}
+
+// 记录一次模型调用;costUsd 为 null 时只计 token 不计金额。
+function recordCall(ledger, call, costUsd) {
+  ensureSessionsIndex(ledger)
+  const day = ensureBucket(ledger.days, dayKeyOf(call.at))
+  const session = ensureSession(day, call.sessionId)
+  day.calls += 1
+  addTokens(day, call)
+  if (costUsd !== null && Number.isFinite(costUsd)) day.cost += costUsd
+  session.calls += 1
+  addTokens(session, call)
+  if (costUsd !== null && Number.isFinite(costUsd)) session.cost += costUsd
+  const modelName = call.model || 'unknown'
+  if (!session.models[modelName]) session.models[modelName] = { calls: 0, inputTokens: 0, cacheReadTokens: 0, outputTokens: 0 }
+  session.models[modelName].calls += 1
+  addTokens(session.models[modelName], call)
+  const id = call.sessionId || 'unknown'
+  // 顶层会话索引:跨日合并,与按日聚合并存
+  const at = Number.isFinite(call.at) ? call.at : 0
+  if (!ledger.sessions[id]) {
+    ledger.sessions[id] = { firstAt: at, lastAt: at, calls: 0, inputTokens: 0, cacheReadTokens: 0, outputTokens: 0, cost: 0 }
+  }
+  const indexed = ledger.sessions[id]
+  indexed.firstAt = Math.min(indexed.firstAt, at)
+  indexed.lastAt = Math.max(indexed.lastAt, at)
+  indexed.calls += 1
+  addTokens(indexed, call)
+  if (costUsd !== null && Number.isFinite(costUsd)) indexed.cost += costUsd
+}
+
+// 顶层索引读数;索引缺失(v1 旧数据)返回 null。
+function sessionTotals(ledger, sessionId) {
+  const row = ledger.sessions ? ledger.sessions[sessionId] : undefined
+  return row || null
+}
+
+function addTotals(target, source) {
+  target.inputTokens += source.inputTokens
+  target.cacheReadTokens += source.cacheReadTokens
+  target.outputTokens += source.outputTokens
+  target.calls += source.calls
+  target.cost += source.cost
+}
+
+// todayKey 由调用方传入(宿主本地时区),保持纯函数可测。
+function summarize(ledger, todayKey, recentCount) {
+  const empty = { inputTokens: 0, cacheReadTokens: 0, outputTokens: 0, calls: 0, cost: 0 }
+  const summary = {
+    today: { ...empty },
+    month: { ...empty },
+    total: { ...empty },
+    recentDays: [],
+    todaySessions: [],
+  }
+  const monthPrefix = todayKey.slice(0, 7)
+  const dayKeys = Object.keys(ledger.days).sort()
+  for (const key of dayKeys) {
+    const day = ledger.days[key]
+    addTotals(summary.total, day)
+    if (key === todayKey) {
+      addTotals(summary.today, day)
+      summary.todaySessions = Object.keys(day.sessions).map((sessionId) => ({
+        sessionId,
+        ...day.sessions[sessionId],
+      }))
+    }
+    if (key.indexOf(monthPrefix) === 0) addTotals(summary.month, day)
+  }
+  summary.recentDays = dayKeys.slice(-recentCount).reverse().map((key) => ({
+    date: key,
+    ...ledger.days[key],
+  }))
+  return summary
+}
+
+function pruneLedger(ledger, todayKey, keepDays) {
+  const keys = Object.keys(ledger.days).sort()
+  const cutoff = new Date(todayKey + 'T00:00:00')
+  cutoff.setDate(cutoff.getDate() - (keepDays - 1))
+  const cutoffKey = dayKeyOf(cutoff.getTime())
+  for (const key of keys) {
+    if (key < cutoffKey) delete ledger.days[key]
+  }
+  // 顶层会话索引按 lastAt 同步修剪,不无限增长
+  ensureSessionsIndex(ledger)
+  for (const id of Object.keys(ledger.sessions)) {
+    if (ledger.sessions[id].lastAt < cutoff.getTime()) delete ledger.sessions[id]
+  }
+}
+
+// 单价:USD / 百万 token;价格表缺失或全空返回 null(不估金额)。
+function costOfCall(call, price) {
+  if (!price) return null
+  const hasAny = Number.isFinite(call.inputTokens) || Number.isFinite(call.outputTokens) || Number.isFinite(call.cacheReadTokens)
+  if (!hasAny) return null
+  let cost = 0
+  if (Number.isFinite(call.inputTokens) && Number.isFinite(price.input)) {
+    cost += (call.inputTokens / TOKENS_PER_UNIT) * price.input
+  }
+  if (Number.isFinite(call.outputTokens) && Number.isFinite(price.output)) {
+    cost += (call.outputTokens / TOKENS_PER_UNIT) * price.output
+  }
+  if (Number.isFinite(call.cacheReadTokens) && Number.isFinite(price.cacheRead)) {
+    cost += (call.cacheReadTokens / TOKENS_PER_UNIT) * price.cacheRead
+  }
+  return cost
+}
+
+// models.dev api.json -> [{key, input, output, cacheRead}];key 同时含 provider/model 与裸模型名。
+function flattenPricing(raw) {
+  const table = []
+  if (!raw || typeof raw !== 'object') return table
+  for (const providerId of Object.keys(raw)) {
+    const provider = raw[providerId]
+    if (!provider || typeof provider !== 'object' || !provider.models) continue
+    for (const modelId of Object.keys(provider.models)) {
+      const model = provider.models[modelId]
+      const cost = model && typeof model === 'object' ? model.cost : null
+      if (!cost || typeof cost !== 'object') continue
+      if (!Number.isFinite(Number(cost.input)) && !Number.isFinite(Number(cost.output))) continue
+      const entry = {
+        keys: [providerId + '/' + modelId.toLowerCase(), modelId.toLowerCase()],
+        input: Number(cost.input),
+        output: Number(cost.output),
+        cacheRead: Number.isFinite(Number(cost.cache_read)) ? Number(cost.cache_read) : null,
+      }
+      table.push(entry)
+    }
+  }
+  return table
+}
+
+// 匹配顺序:provider/model 精确 -> 任意条目 key 精确 -> 模型名前缀(最长优先)。
+function priceFor(table, provider, model) {
+  if (!model) return null
+  const modelLower = String(model).toLowerCase()
+  const full = (provider || '') + '/' + modelLower
+  for (const entry of table) {
+    if (entry.keys[0] === full) return entry
+  }
+  for (const entry of table) {
+    if (entry.keys.indexOf(modelLower) >= 0) return entry
+  }
+  let best = null
+  for (const entry of table) {
+    for (const key of entry.keys) {
+      const suffix = key.indexOf('/') >= 0 ? key.slice(key.indexOf('/') + 1) : key
+      if (modelLower.indexOf(suffix) === 0 && (best === null || suffix.length > best.suffixLen)) {
+        best = { entry, suffixLen: suffix.length }
+      }
+    }
+  }
+  return best ? best.entry : null
+}
+
+// models.dev 拉取失败时的兜底单价,USD / 百万 token(对齐 dsh-balance 内置表)。
+const FALLBACK_PRICING = [
+  { keys: ['deepseek/deepseek-chat', 'deepseek-chat'], input: 0.14, output: 0.28, cacheRead: 0.0028 },
+  { keys: ['deepseek/deepseek-reasoner', 'deepseek-reasoner'], input: 0.14, output: 0.28, cacheRead: 0.0028 },
+]
+
+export {
+  createLedger,
+  dayKeyOf,
+  recordCall,
+  summarize,
+  pruneLedger,
+  ensureSessionsIndex,
+  sessionTotals,
+  costOfCall,
+  flattenPricing,
+  priceFor,
+  FALLBACK_PRICING,
+}

package/src/pricing.mjs

@@ -0,0 +1,95 @@
+// 自定义单价与币种折算:纯数据变换,无 IO。
+// 币种口径:原生币种计价后统一折 USD 入账本;展示层按当前汇率折 CNY。
+
+const TOKENS_PER_UNIT = 1000000
+const CURRENCY_CNY = 'CNY'
+const CURRENCY_USD = 'USD'
+
+import { FALLBACK_PRICING } from './ledger.mjs'
+
+// 目录价未就绪(启动窗口内为 null/空)时同步回落内置兜底价,计费不静默丢失。
+export function catalogOrFallback(table) {
+  return Array.isArray(table) && table.length > 0 ? table : FALLBACK_PRICING
+}
+
+const TIERS = {
+  custom: { full: 'custom-full', name: 'custom-name', prefix: 'custom-prefix' },
+  catalog: { full: 'catalog', name: 'catalog', prefix: 'catalog' },
+}
+
+// 设置条目 -> 匹配表条目;模型 id 含 / 视为 provider/model 精确键,否则同时给裸名键。
+function normalizeCustomPrices(list) {
+  const table = []
+  if (!Array.isArray(list)) return table
+  for (const item of list) {
+    if (!item || typeof item.model !== 'string' || item.model.trim().length === 0) continue
+    const input = Number(item.input)
+    const output = Number(item.output)
+    if (!Number.isFinite(input) && !Number.isFinite(output)) continue
+    const model = item.model.trim().toLowerCase()
+    const cacheRead = Number.isFinite(Number(item.cacheRead)) ? Number(item.cacheRead) : null
+    const slashAt = model.indexOf('/')
+    table.push({
+      keys: slashAt >= 0 ? [model, model.slice(slashAt + 1)] : [model],
+      input: Number.isFinite(input) ? input : null,
+      output: Number.isFinite(output) ? output : null,
+      cacheRead,
+      currency: item.currency === CURRENCY_CNY ? CURRENCY_CNY : CURRENCY_USD,
+    })
+  }
+  return table
+}
+
+// provider/model 精确 -> 模型名精确 -> 最长前缀,按层返回 {entry, tier}。
+function matchTable(table, full, modelLower, tiers) {
+  for (const entry of table) {
+    if (entry.keys[0] === full) return { entry, tier: tiers.full }
+  }
+  for (const entry of table) {
+    if (entry.keys.indexOf(modelLower) >= 0) return { entry, tier: tiers.name }
+  }
+  let best = null
+  for (const entry of table) {
+    for (const key of entry.keys) {
+      if (modelLower.indexOf(key) === 0 && (best === null || key.length > best.keyLen)) {
+        best = { entry, keyLen: key.length }
+      }
+    }
+  }
+  return best ? { entry: best.entry, tier: tiers.prefix } : null
+}
+
+// 匹配链:自定义 provider/model 精确 -> 自定义模型名精确 -> 自定义最长前缀 -> 目录价(同序)。
+function matchPrice(customTable, catalogTable, provider, model) {
+  if (!model) return null
+  const modelLower = String(model).toLowerCase()
+  const full = (provider || '') + '/' + modelLower
+  return matchTable(customTable, full, modelLower, TIERS.custom) ||
+    matchTable(catalogTable, full, modelLower, TIERS.catalog)
+}
+
+// 原生币种金额;价格缺失或全空 token 返回 null(不估金额)。
+function nativeCostOfCall(call, price) {
+  if (!price) return null
+  const hasAny = Number.isFinite(call.inputTokens) || Number.isFinite(call.outputTokens) || Number.isFinite(call.cacheReadTokens)
+  if (!hasAny) return null
+  let amount = 0
+  if (Number.isFinite(call.inputTokens) && Number.isFinite(price.input)) {
+    amount += (call.inputTokens / TOKENS_PER_UNIT) * price.input
+  }
+  if (Number.isFinite(call.outputTokens) && Number.isFinite(price.output)) {
+    amount += (call.outputTokens / TOKENS_PER_UNIT) * price.output
+  }
+  if (Number.isFinite(call.cacheReadTokens) && Number.isFinite(price.cacheRead)) {
+    amount += (call.cacheReadTokens / TOKENS_PER_UNIT) * price.cacheRead
+  }
+  return { amount, currency: price.currency || CURRENCY_USD }
+}
+
+// 折 USD 入账本:CNY 金额除以汇率(每 USD 兑 CNY)。
+function toUsd(amount, currency, rateUsdToCny) {
+  if (currency === CURRENCY_CNY) return amount / rateUsdToCny
+  return amount
+}
+
+export { normalizeCustomPrices, matchPrice, nativeCostOfCall, toUsd, TIERS }

package/src/rates.mjs

@@ -0,0 +1,37 @@
+// 汇率解析与新鲜度判定:纯函数,网络请求由 host 半区执行。
+
+// 全源失败且无历史缓存时的兜底汇率(每 USD 兑 CNY)。
+export const DEFAULT_USD_CNY = 7.2
+
+// 刷新节奏:每 6 小时。
+export const RATE_TTL_MS = 6 * 60 * 60 * 1000
+
+// 超过刷新周期即视为非实时,沿用上次值并标注。
+export function isRateStale(fetchedAt, now) {
+  return !(now - fetchedAt < RATE_TTL_MS)
+}
+
+// 腾讯财经行情文本:v_whUSDCNY="100~USDCNY~7.2531~..."。
+export function parseTencentRate(text) {
+  if (typeof text !== 'string') return null
+  const match = text.match(/USDCNY[^0-9]+([0-9]+\.[0-9]+)/)
+  const rate = match ? Number(match[1]) : NaN
+  return Number.isFinite(rate) && rate > 0 ? rate : null
+}
+
+// open.er-api 响应:{ result: "success", rates: { CNY } }。
+export function parseErApiRate(payload) {
+  const rate = payload && payload.rates ? Number(payload.rates.CNY) : NaN
+  return Number.isFinite(rate) && rate > 0 ? rate : null
+}
+
+// 拉取成功刷新并清除标注;失败沿用上次汇率并标注非实时;无任何历史时用兜底值。
+export function resolveRate(previous, outcome, now) {
+  if (outcome && outcome.ok && Number.isFinite(outcome.rate) && outcome.rate > 0) {
+    return { rate: outcome.rate, fetchedAt: now, stale: false }
+  }
+  if (previous && Number.isFinite(previous.rate) && previous.rate > 0) {
+    return { rate: previous.rate, fetchedAt: previous.fetchedAt, stale: true }
+  }
+  return { rate: DEFAULT_USD_CNY, fetchedAt: 0, stale: true }
+}

package/test/ledger.test.mjs

@@ -0,0 +1,118 @@
+// 用量统计账本纯模块测试:计量聚合、汇总、修剪、计价(见 dynamic-plugins/usage-stats/README.md)
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  createLedger,
+  dayKeyOf,
+  recordCall,
+  pruneLedger,
+  summarize,
+  costOfCall,
+  flattenPricing,
+  priceFor,
+  FALLBACK_PRICING,
+} from '../src/ledger.mjs'
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const PER_MILLION = 1000000
+
+function callAt(ts, overrides) {
+  return Object.assign({
+    at: ts,
+    sessionId: 'sess-1',
+    model: 'deepseek-chat',
+    provider: 'deepseek',
+    inputTokens: 1000,
+    cacheReadTokens: 500,
+    outputTokens: 200,
+  }, overrides)
+}
+
+test('dayKeyOf:本地时区 YYYY-MM-DD', () => {
+  const ts = new Date(2026, 1, 26, 15, 30).getTime()
+  assert.equal(dayKeyOf(ts), '2026-02-26')
+})
+
+test('recordCall:同会话同日累计,跨日/跨会话分桶', () => {
+  const day0 = new Date(2026, 1, 26, 10).getTime()
+  const ledger = createLedger()
+  recordCall(ledger, callAt(day0), 0.001)
+  recordCall(ledger, callAt(day0, { outputTokens: 300 }), 0.002)
+  recordCall(ledger, callAt(day0 + DAY_MS, { sessionId: 'sess-2' }), 0.003)
+
+  assert.equal(Object.keys(ledger.days).length, 2)
+  const day1 = ledger.days[dayKeyOf(day0)]
+  assert.equal(day1.calls, 2)
+  assert.equal(day1.inputTokens, 2000)
+  assert.equal(day1.outputTokens, 500)
+  assert.ok(Math.abs(day1.cost - 0.003) < 1e-9)
+  assert.equal(day1.sessions['sess-1'].calls, 2)
+  const day2 = ledger.days[dayKeyOf(day0 + DAY_MS)]
+  assert.equal(day2.sessions['sess-2'].calls, 1)
+})
+
+test('recordCall:无 usage 数据不计 token 但计调用', () => {
+  const ts = new Date(2026, 1, 26, 10).getTime()
+  const ledger = createLedger()
+  recordCall(ledger, callAt(ts, { inputTokens: null, cacheReadTokens: null, outputTokens: null }), null)
+  const day = ledger.days[dayKeyOf(ts)]
+  assert.equal(day.calls, 1)
+  assert.equal(day.inputTokens, 0)
+  assert.equal(day.cost, 0)
+})
+
+test('costOfCall:按百万 token 单价计价,缺字段容错', () => {
+  const price = { input: 0.28, output: 0.56, cacheRead: 0.028 }
+  const cost = costOfCall({ inputTokens: PER_MILLION, cacheReadTokens: 0, outputTokens: PER_MILLION }, price)
+  assert.ok(Math.abs(cost - (0.28 + 0.56)) < 1e-9)
+  assert.equal(costOfCall({ inputTokens: 100 }, null), null)
+  assert.equal(costOfCall({ inputTokens: null, outputTokens: null, cacheReadTokens: null }, price), null)
+})
+
+test('flattenPricing + priceFor:provider/model 精确 -> 裸名精确 -> 前缀回退', () => {
+  const raw = {
+    deepseek: {
+      models: {
+        'deepseek-chat': { cost: { input: 0.14, output: 0.28, cache_read: 0.014 } },
+        'deepseek/deepseek-v4-pro': { cost: { input: 1.74, output: 3.48, cache_read: 0.145 } },
+      },
+    },
+  }
+  const table = flattenPricing(raw)
+  assert.equal(table.length, 2)
+  assert.ok(priceFor(table, 'deepseek', 'deepseek-chat'))
+  assert.ok(priceFor(table, 'other', 'deepseek/deepseek-v4-pro'))
+  assert.ok(priceFor(table, 'openai', 'deepseek-chat'))
+  assert.equal(priceFor(table, 'openai', 'unknown-model'), null)
+  assert.equal(priceFor(FALLBACK_PRICING, 'deepseek', 'deepseek-chat') !== null, true)
+})
+
+test('summarize:今日/本月/累计与近 N 天列表', () => {
+  const base = new Date(2026, 1, 26, 10).getTime()
+  const ledger = createLedger()
+  recordCall(ledger, callAt(base), 0.01)
+  recordCall(ledger, callAt(base - DAY_MS, { sessionId: 's0' }), 0.02)
+  recordCall(ledger, callAt(base - 40 * DAY_MS), 0.04)
+
+  const summary = summarize(ledger, dayKeyOf(base), 14)
+  assert.ok(Math.abs(summary.today.cost - 0.01) < 1e-9)
+  assert.equal(summary.today.calls, 1)
+  assert.ok(Math.abs(summary.month.cost - 0.03) < 1e-9)
+  assert.ok(Math.abs(summary.total.cost - 0.07) < 1e-9)
+  assert.equal(summary.recentDays.length, 3)
+  assert.equal(summary.recentDays[0].date, dayKeyOf(base))
+  assert.equal(summary.recentDays[0].calls, 1)
+  assert.ok(Math.abs(summary.recentDays[0].cost - 0.01) < 1e-9)
+  assert.equal(summary.todaySessions.length, 1)
+})
+
+test('pruneLedger:仅保留最近 N 天', () => {
+  const base = new Date(2026, 1, 26, 10).getTime()
+  const ledger = createLedger()
+  for (let i = 0; i < 5; i += 1) {
+    recordCall(ledger, callAt(base - i * DAY_MS), 0.01)
+  }
+  pruneLedger(ledger, dayKeyOf(base), 3)
+  assert.equal(Object.keys(ledger.days).length, 3)
+})