dsh-usage-badge 0.1.1 → 0.1.3

package/lib/pricing.js

@@ -7,6 +7,13 @@
  * the same case-insensitive key matching, and the same per-request application of
  * the model multiplier, the context-length tier and the peak/valley rule.
  *
+ * Two rules were added on top of that port, both opt-out and both documented in
+ * `docs/design-notes.md`: a trailing `*` on a model part makes a family row, and — unless
+ * `modelPrefixFallback` is off — an ordinary row also prices its own separator-suffixed
+ * variants (`deepseek-flash` covers `deepseek-flash-preview`). `priceUnmatchedModels` can
+ * also be switched off, which makes a model no row matches cost nothing rather than being
+ * priced by the `default` row.
+ *
  * Naming note: every cost function here returns an amount in the *total currency*
  * (`totalCurrency`, CNY by default), not necessarily USD — the sidecar inherited
  * the misleading `usageCostUsd` name, which this port drops.
@@ -18,9 +25,11 @@
 export const PRICE_KEYS = ['inputPerMillion', 'cacheReadPerMillion', 'cacheWritePerMillion', 'outputPerMillion']
 
 /**
- * Written to `usage-pricing.json` on first run (only when the file is missing) so
- * a fresh install starts from a working table instead of zero prices. Mirrors the
- * shell's template.
+ * The rates a table with no `default` row of its own falls back to, plus the exchange rate the
+ * shell used. **Never written to disk** — nothing in this module (or the plugin) persists it, it
+ * is only the in-memory fallback so a fresh install shows an estimate instead of zeroes. It is
+ * served to the panel as `template` so those rates can be labelled as what they are, and
+ * 「应用官方价格」 replaces them with the published list's first line.
  */
 export const DEFAULT_TEMPLATE = {
   exchangeRate: 6.74,
@@ -82,6 +91,16 @@ export function normalizePricing(raw) {
     exchangeRate: Number(user.exchangeRate) || DEFAULT_TEMPLATE.exchangeRate,
     default: { ...DEFAULT_TEMPLATE.default, ...(user.default ?? {}) },
     overrides: user.overrides && typeof user.overrides === 'object' ? user.overrides : {},
+    // Implicit prefix fallback: an authored row also prices the suffixed variants of
+    // its own name, so the `deepseek-flash` row the official list writes covers
+    // `deepseek-flash-preview` with nothing hand-written. On unless switched off, and
+    // only an explicit `false` switches it off.
+    modelPrefixFallback: user.modelPrefixFallback !== false,
+    // Whether a model that no row matches is priced by the `default` row at all. On by
+    // default — pricing everything is what that row is for — and switched off it means
+    // "we do not know what this cost": the request contributes tokens and requests but no
+    // amount, and the snapshot reports which routes those are rather than a silent ¥0.
+    priceUnmatchedModels: user.priceUnmatchedModels !== false,
     timeOfUse: user.timeOfUse,
     multiplier: user.multiplier ?? DEFAULT_TEMPLATE.multiplier,
     contextMultiplier: user.contextMultiplier,
@@ -98,6 +117,10 @@ export function normalizePricing(raw) {
  * `*|model` wildcards. This lets a single row like `"deepseek-v4-flash"` apply to
  * every provider.
  *
+ * These are the *exact* keys a route can resolve to. Rows that end a model part with
+ * `*` are family rules and are appended after these by {@link rowsForRoute}, because
+ * an exact row always outranks a family one.
+ *
  * @param {string|null} provider - provider id as recorded in the session log.
  * @param {string|null} model - model id as recorded in the session log.
  * @returns {string[]} candidate override keys, highest priority first.
@@ -149,6 +172,132 @@ function overrideRow(pricing, key) {
   return actual === undefined ? undefined : rows[actual]
 }
 
+/**
+ * The prefix a family row matches on, or null when the key is not a family row.
+ *
+ * A trailing `*` on the model part means "every model whose id starts with this", so
+ * the row `deepseek-flash-*` prices `deepseek-flash-preview` and any dated or
+ * experimental variant of the family without a row per name.
+ *
+ * The prefix must be non-empty, and that is exactly what keeps a bare `*` inert:
+ * `provider|*` already means "any model" through the exact candidate list, and a lone
+ * `*` key has never matched anything. The star is not a separator either, so
+ * `deepseek-flash-*` does not cover the model `deepseek-flash` itself — write
+ * `deepseek-flash*` when the family includes the unsuffixed name.
+ */
+function familyPrefix(pattern) {
+  const text = String(pattern)
+  return text.endsWith('*') && text.length > 1 ? text.slice(0, -1) : null
+}
+
+/**
+ * What must follow a prefix for the *implicit* fallback to accept it: a separator.
+ *
+ * Without this, `gpt-4` would swallow `gpt-4o` — a different model with a different
+ * price — and `deepseek-flash` would swallow `deepseek-flashlight`. With it, the
+ * fallback only ever reaches `deepseek-flash-preview`, `deepseek.v3`, `qwen:72b`
+ * shapes. An explicit `deepseek-flash*` row skips this test: writing the star is how
+ * you say "yes, the glued-together names too".
+ */
+const PREFIX_BOUNDARY = /^[-_.:/@]/
+
+/**
+ * The prefix rows that apply to one route, most specific first.
+ *
+ * Two kinds end up here, and they share one ranking:
+ *
+ *   - explicit family rows, a model part ending in `*` (`deepseek-flash-*`);
+ *   - implicit ones, when `modelPrefixFallback` is on: an ordinary row also prices the
+ *     suffixed variants of its own name, which is what lets the row the official price
+ *     list writes — `deepseek-flash` — cover `deepseek-flash-preview` with nothing
+ *     hand-written at all.
+ *
+ * Ranked by the shape they take — pure model, `provider|model`, `*|model`, the same
+ * order the exact keys resolve in — then by prefix length (the narrow `deepseek-flash-*`
+ * outranks the broad `deepseek-*`), and explicit wins a tie against implicit. A key that
+ * names a different provider, or has more than one `|`, belongs to no shape and is
+ * ignored, exactly as it was when it could never match.
+ */
+function familyRows(rows, provider, model, fallback) {
+  if (!model) return []
+  const routeProvider = String(provider ?? '').toLowerCase()
+  const routeModel = String(model).toLowerCase()
+  const found = []
+  for (const key of Object.keys(rows)) {
+    const parts = String(key).split('|')
+    if (parts.length > 2) continue
+    const modelPart = String(parts.length === 2 ? parts[1] : parts[0])
+    const prefix = familyPrefix(modelPart)
+    let length
+    if (prefix !== null) {
+      if (!routeModel.startsWith(prefix.toLowerCase())) continue
+      length = prefix.length
+    } else if (fallback) {
+      const name = modelPart.toLowerCase()
+      // The exact key has already had its turn by the time this runs, so an implicit
+      // row is always a *strict* prefix plus a separator.
+      if (!name || !routeModel.startsWith(name) || !PREFIX_BOUNDARY.test(routeModel.slice(name.length))) continue
+      length = name.length
+    } else {
+      continue
+    }
+    let shape
+    if (parts.length === 1) shape = 0
+    else if (parts[0] === '*') shape = 2
+    else if (parts[0].toLowerCase() === routeProvider) shape = 1
+    else continue
+    // A row can be `null` in the file — a hand edit, or a delete that left the key behind. The
+    // exact-key path has always skipped those; skipping them here too is what keeps a single such
+    // row from throwing out of every price lookup and turning `/summary` into a permanent 500.
+    const row = rows[key]
+    if (!row) continue
+    found.push({ shape, length, explicit: prefix === null ? 0 : 1, row })
+  }
+  return found
+    .sort((a, b) => a.shape - b.shape || b.length - a.length || b.explicit - a.explicit)
+    .map((entry) => entry.row)
+}
+
+/**
+ * The override rows that price one route, highest priority first.
+ *
+ * Exact keys come first, in the order {@link matchKeys} establishes, so a table that
+ * writes no family row resolves exactly as it did before families existed. Prefix rows
+ * follow — same shape order, longest prefix first — which is what lets a family rule
+ * cover the models nobody wrote a row for without ever outranking one that somebody did.
+ *
+ * Memoized per override set and route: this is consulted once per price field of every
+ * request record while a day is folded. The entry is only reusable while the override *map*
+ * is the same object — adding or removing a key in place would go unnoticed, so callers must
+ * treat a document as immutable (every path here re-parses the file instead of editing it).
+ * The fallback switch is part of the cache key because two normalized documents can share one
+ * override map and differ only by that flag — which is exactly what toggling the switch does
+ * when a caller re-normalizes without re-reading.
+ */
+const routeRows = new WeakMap()
+
+function rowsForRoute(pricing, provider, model) {
+  const rows = pricing.overrides
+  if (!rows) return []
+  const fallback = pricing.modelPrefixFallback !== false
+  let byRoute = routeRows.get(rows)
+  if (!byRoute) {
+    byRoute = new Map()
+    routeRows.set(rows, byRoute)
+  }
+  const routeKey = `${fallback ? 'p' : 'e'}\u0000${provider ?? ''}\u0000${model ?? ''}`
+  const cached = byRoute.get(routeKey)
+  if (cached) return cached
+  const resolved = []
+  for (const key of matchKeys(provider, model)) {
+    const row = overrideRow(pricing, key)
+    if (row) resolved.push(row)
+  }
+  const all = resolved.concat(familyRows(rows, provider, model, fallback))
+  byRoute.set(routeKey, all)
+  return all
+}
+
 /**
  * Resolve the four price fields for one route.
  *
@@ -158,11 +307,11 @@ function overrideRow(pricing, key) {
  */
 export function resolvePrice(pricing, provider, model) {
   const out = {}
+  const rows = rowsForRoute(pricing, provider, model)
   for (const k of PRICE_KEYS) {
     out[k] = Number(pricing.default?.[k]) || 0
-    for (const key of matchKeys(provider, model)) {
-      const row = overrideRow(pricing, key)
-      if (row && row[k] != null) {
+    for (const row of rows) {
+      if (row[k] != null) {
         out[k] = Number(row[k]) || 0
         break
       }
@@ -173,36 +322,32 @@ export function resolvePrice(pricing, provider, model) {
 
 /** Per-model peak/valley rule: the first matching row's own rule, else the global one. */
 export function modelTimeOfUse(pricing, provider, model) {
-  for (const key of matchKeys(provider, model)) {
-    const row = overrideRow(pricing, key)
-    if (row && row.timeOfUse) return row.timeOfUse
+  for (const row of rowsForRoute(pricing, provider, model)) {
+    if (row.timeOfUse) return row.timeOfUse
   }
   return pricing.timeOfUse
 }
 
 /** Per-model multiplier applied to the whole request cost (row wins, else global, default 1). */
 export function modelMultiplier(pricing, provider, model) {
-  for (const key of matchKeys(provider, model)) {
-    const row = overrideRow(pricing, key)
-    if (row && row.multiplier != null) return Number(row.multiplier) || 1
+  for (const row of rowsForRoute(pricing, provider, model)) {
+    if (row.multiplier != null) return Number(row.multiplier) || 1
   }
   return Number(pricing.multiplier) || 1
 }
 
 /** Per-model context-length tier rule (row wins, else the default-row rule). */
 export function modelContextMultiplier(pricing, provider, model) {
-  for (const key of matchKeys(provider, model)) {
-    const row = overrideRow(pricing, key)
-    if (row && row.contextMultiplier != null) return row.contextMultiplier
+  for (const row of rowsForRoute(pricing, provider, model)) {
+    if (row.contextMultiplier != null) return row.contextMultiplier
   }
   return pricing.contextMultiplier
 }
 
 /** The currency a route's prices are quoted in (`cny` unless the row says otherwise). */
 export function resolveCurrency(pricing, provider, model) {
-  for (const key of matchKeys(provider, model)) {
-    const row = overrideRow(pricing, key)
-    if (row && row.currency) return row.currency
+  for (const row of rowsForRoute(pricing, provider, model)) {
+    if (row.currency) return row.currency
   }
   return pricing.default?.currency || 'cny'
 }
@@ -212,6 +357,23 @@ export function totalCurrencyOf(pricing) {
   return pricing.totalCurrency === 'usd' ? 'usd' : 'cny'
 }
 
+/**
+ * Whether a route has no price at all.
+ *
+ * True only when `priceUnmatchedModels` is switched off *and* no override row applies to
+ * the route. A row that matches counts even when it defines nothing but a multiplier:
+ * "matched" means the table has something to say about this model, and the `default` row
+ * supplies whatever the row leaves out.
+ *
+ * @param {object} pricing - the normalized pricing document.
+ * @param {string|null} provider - route provider.
+ * @param {string|null} model - route model.
+ */
+export function isUnpriced(pricing, provider, model) {
+  if (pricing.priceUnmatchedModels !== false) return false
+  return rowsForRoute(pricing, provider, model).length === 0
+}
+
 /**
  * Convert a cost quoted in `from` into the configured total currency. Same-currency
  * conversion is a no-op, so an all-CNY table needs no exchange rate at all.
@@ -279,6 +441,7 @@ export function contextMultiplierFor(pricing, provider, model, tokens) {
  */
 export function requestCost(tokens, provider, model, hour, pricing, day) {
   const context = normalizeDay(day)
+  if (isUnpriced(pricing, provider, model)) return 0
   const price = resolvePrice(pricing, provider, model)
   const timeMultiplier = multiplierFor(context.weekday, hour, modelTimeOfUse(pricing, provider, model), context.class)
   const modelMultiplierValue = modelMultiplier(pricing, provider, model)
@@ -294,6 +457,7 @@ export function requestCost(tokens, provider, model, hour, pricing, day) {
  */
 export function legacyCost(tokens, provider, model, hour, pricing, day) {
   const context = normalizeDay(day)
+  if (isUnpriced(pricing, provider, model)) return 0
   const price = resolvePrice(pricing, provider, model)
   const timeMultiplier = multiplierFor(context.weekday, hour, modelTimeOfUse(pricing, provider, model), context.class)
   const cost = tokenCost(tokens, price) * timeMultiplier * modelMultiplier(pricing, provider, model)
@@ -439,7 +603,11 @@ function normalizeDay(day) {
  * surcharge and is floored at 1.
  *
  * A public holiday is off-peak for the whole day, which is DeepSeek's published
- * rule — so the holiday check comes first and overrides every `days` form.
+ * rule — so the holiday check comes before every `days` form. A rule can decline that
+ * calendar with `honorHolidays: false`, which is what a gateway that keeps charging its
+ * own peak windows on a Chinese public holiday needs; the day is then judged by `days`
+ * like any other. Weekends need no such flag: they are already per rule through `days`
+ * (`"all"`, `"weekend"`, `[6,7]`).
  *
  * @param {number} weekday - ISO weekday (1=Mon … 7=Sun).
  * @param {number} hour - local hour (0–23).
@@ -448,7 +616,7 @@ function normalizeDay(day) {
  */
 export function multiplierFor(weekday, hour, tou, dayClass = 'normal') {
   if (!tou || !tou.enabled) return 1
-  if (dayClass === 'holiday') return 1
+  if (dayClass === 'holiday' && tou.honorHolidays !== false) return 1
   if (!dayMatches(weekday, tou.days)) return 1
   for (const range of tou.peakRanges || []) {
     if (!Array.isArray(range) || range.length < 2) continue

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-usage-badge",
-  "version": "0.1.1",
-  "description": "DeepSeek Harness 的用量徽标插件：侧边栏底部一行显示当天的 token 总量与估算费用，点开可看 24 小时 / 近 7 日 / 近 30 日 / 近 12 个月用量，按 provider 筛选，并按 DeepSeek 官方定价与中国法定节假日计价。A usage badge plugin for DeepSeek Harness: today's tokens and estimated spend in the sidebar, with 24h / 7d / 30d / 12-month charts, official DeepSeek pricing and Chinese public holidays.",
+  "version": "0.1.3",
+  "description": "DeepSeek Harness 的用量徽标插件：侧边栏底部一行显示当天的 token 总量与估算费用，点开可看 24 小时 / 近 7 日 / 近 30 日 / 近 12 个月 / 按年用量，按 provider 筛选，并按 DeepSeek 官方定价与中国法定节假日计价。A usage badge plugin for DeepSeek Harness: today's tokens and estimated spend in the sidebar, with 24h / 7d / 30d / 12-month and per-year charts, official DeepSeek pricing and Chinese public holidays.",
   "type": "module",
   "main": "lib/index.js",
   "repository": {