dsh-tokenlens 1.1.0 → 1.2.1

package/index.js

@@ -25,6 +25,7 @@ import { createUsageStats } from './lib/usage-stats.mjs'
 import {
   DEFAULT_SETTINGS,
   DETAILS_DEFAULTS,
+  DETAILS_WINDOWS,
   DISPLAY_VIEWS,
   LABEL_STYLES,
   STATS_SCOPES,
@@ -71,7 +72,7 @@ export const inject = []
 export const PLUGIN_NAME = 'dsh-tokenlens'
 
 /** Plugin version; mirrors package.json (kept here so diagnostics need no fs read). */
-export const PLUGIN_VERSION = '1.1.0'
+export const PLUGIN_VERSION = '1.2.1'
 
 /** Documented defaults; every field of the raw row config is optional. */
 const DEFAULTS = {
@@ -1655,6 +1656,14 @@ export function apply(ctx, rawConfig) {
           }
           next.detailsExpanded = incoming.detailsExpanded
         }
+        if (Object.prototype.hasOwnProperty.call(incoming, 'detailsWindow')) {
+          if (!DETAILS_WINDOWS.includes(incoming.detailsWindow)) {
+            throw new UsageError('unsupported-provider', `settings.detailsWindow must be one of ${DETAILS_WINDOWS.join(', ')}`, {
+              retryable: false,
+            })
+          }
+          next.detailsWindow = incoming.detailsWindow
+        }
         providerStore = saveProviderStore(providerStoreFile, {
           ...providerStore,
           settings: next,

package/lib/provider-store.mjs

@@ -29,6 +29,8 @@ export const LABEL_STYLES = ['short', 'full']
 export const DISPLAY_VIEWS = ['chart', 'data']
 export const STATS_SCOPES = ['provider', 'all']
 export const DETAILS_DEFAULTS = ['auto', 'expanded', 'collapsed']
+/** The 明细 donut windows of the chart mode (v1.2.1): 今日 / 最近7天 / 最近X天 / 总计. */
+export const DETAILS_WINDOWS = ['today', 'last7Days', 'second', 'total']
 
 /** Default display settings (management 插件设置 tab). */
 export const DEFAULT_SETTINGS = {
@@ -36,6 +38,8 @@ export const DEFAULT_SETTINGS = {
   defaultView: 'chart',
   defaultScope: 'provider',
   detailsExpanded: 'auto',
+  // v1.2.1 图表明细窗口默认值: 总计 (the last choice is persisted there).
+  detailsWindow: 'total',
 }
 
 /** The default override file: `$DSH_HOME/dsh-tokenlens/providers.json`. */
@@ -119,6 +123,9 @@ export function sanitizeSettings(value) {
     detailsExpanded: DETAILS_DEFAULTS.includes(source.detailsExpanded)
       ? source.detailsExpanded
       : DEFAULT_SETTINGS.detailsExpanded,
+    detailsWindow: DETAILS_WINDOWS.includes(source.detailsWindow)
+      ? source.detailsWindow
+      : DEFAULT_SETTINGS.detailsWindow,
   }
 }
 

package/lib/usage-jsonl.mjs

@@ -33,7 +33,7 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
-import { localDayKey } from './usage-zcode.mjs'
+import { localDayKey, localHour } from './usage-zcode.mjs'
 
 const num = (value) => (typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0)
 
@@ -81,11 +81,12 @@ export function jsonlTreeSignature(root) {
     .join('|')
 }
 
-/** Merge one row into a day/provider/model group map. */
-function addGroup(groups, { day, providerId, modelId, input, output, cacheRead, cacheWrite, total }) {
-  const key = `${day}\u0000${providerId}\u0000${modelId}`
+/** Merge one row into a (day, hour, provider, model) group map. */
+function addGroup(groups, { day, hour, providerId, modelId, input, output, cacheRead, cacheWrite, total }) {
+  const key = `${day}\u0000${hour}\u0000${providerId}\u0000${modelId}`
   const group = groups.get(key) ?? {
     day,
+    hour,
     providerId,
     modelId,
     bucket: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, messages: 0 },
@@ -171,6 +172,7 @@ export function readWorkbuddyUsage(input = {}) {
     const model = String(providerData.model ?? providerData.requestModelId ?? 'unknown')
     addGroup(groups, {
       day: localDayKey(time),
+      hour: localHour(time),
       providerId: 'workbuddy',
       modelId: model,
       // prompt_tokens includes the cached prefix.
@@ -181,7 +183,7 @@ export function readWorkbuddyUsage(input = {}) {
       total,
     })
   })
-  const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day))
+  const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day) || a.hour - b.hour)
   return { harness: 'workbuddy', label: 'WorkBuddy', root, groups: list, rows: list.length, requests, skippedZero, durationMs: Date.now() - started }
 }
 
@@ -263,6 +265,7 @@ export function readQoderUsage(input = {}) {
     const modelId = custom !== null ? rawModel : rawModel
     addGroup(groups, {
       day: localDayKey(time),
+      hour: localHour(time),
       providerId,
       modelId,
       // Qoder's input_tokens include the cached prompt.
@@ -273,6 +276,6 @@ export function readQoderUsage(input = {}) {
       total,
     })
   })
-  const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day))
+  const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day) || a.hour - b.hour)
   return { harness: 'qoder', label: 'Qoder', root, groups: list, rows: list.length, requests, durationMs: Date.now() - started }
 }

package/lib/usage-opencode.mjs

@@ -24,7 +24,7 @@
 import { statSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
-import { localDayKey } from './usage-zcode.mjs'
+import { localDayKey, localHour } from './usage-zcode.mjs'
 
 /** The default OpenCode CLI database location. */
 export function defaultOpencodeDbPath(env = process.env, home = homedir()) {
@@ -52,7 +52,7 @@ export function opencodeDbSignature(dbPath) {
  *
  * @param input.dbPath - database file (read-only).
  * @param input.openDatabase - test seam: `(path) => DatabaseSync`-like handle.
- * @returns `{ groups: [{day, providerId, modelId, bucket}], rows, durationMs, dbPath }`.
+ * @returns `{ groups: [{day, hour, providerId, modelId, bucket}], rows, durationMs, dbPath }`.
  */
 export function readOpencodeUsage(input = {}) {
   const dbPath =
@@ -91,12 +91,16 @@ export function readOpencodeUsage(input = {}) {
       const time = typeof row.timeCreated === 'number' ? row.timeCreated : null
       if (time === null) continue
       const day = localDayKey(time)
+      // Local clock hour: the chart's hourly drill-down bucket (DST fold hours
+      // collapse into one slot, like `getHours()`).
+      const hour = localHour(time)
       const providerId =
         typeof message.providerID === 'string' && message.providerID !== '' ? message.providerID : 'unknown'
       const modelId = typeof message.modelID === 'string' && message.modelID !== '' ? message.modelID : 'unknown'
-      const key = `${day}\u0000${providerId}\u0000${modelId}`
+      const key = `${day}\u0000${hour}\u0000${providerId}\u0000${modelId}`
       const group = groups.get(key) ?? {
         day,
+        hour,
         providerId,
         modelId,
         bucket: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, messages: 0 },
@@ -110,7 +114,9 @@ export function readOpencodeUsage(input = {}) {
       group.bucket.messages += 1
       groups.set(key, group)
     }
-    const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day))
+    // Day-ascending then hour-ascending keeps the groups deterministic for tests
+    // and for the daily merge.
+    const list = [...groups.values()].sort((a, b) => a.day.localeCompare(b.day) || a.hour - b.hour)
     return {
       harness: 'opencode',
       label: 'OpenCode',

package/lib/usage-stats.mjs

@@ -200,6 +200,34 @@ export function cloneBucket(from) {
   return addBucket(emptyBucket(), from)
 }
 
+/** An all-zero 24-slot local-hour token series. */
+export function emptyHourSeries() {
+  return new Array(24).fill(0)
+}
+
+/** Add one local-hour token amount into a 24-slot series; invalid slots are ignored. */
+export function addHourTokens(series, hour, tokens) {
+  if (!Array.isArray(series) || !Number.isInteger(hour) || hour < 0 || hour > 23) return series
+  if (typeof tokens !== 'number' || !Number.isFinite(tokens) || tokens <= 0) return series
+  series[hour] += tokens
+  return series
+}
+
+/** Accumulate one 24-slot series onto another (in place); false when `from` is not one. */
+export function addHourSeries(target, from) {
+  if (!Array.isArray(target) || !Array.isArray(from)) return false
+  for (let hour = 0; hour < 24; hour += 1) {
+    const value = from[hour]
+    if (typeof value === 'number' && Number.isFinite(value)) target[hour] += value
+  }
+  return true
+}
+
+/** A 24-slot series as wire integers (hourly token bars are rounded). */
+export function roundHourSeries(series) {
+  return series.map((value) => (typeof value === 'number' && Number.isFinite(value) ? Math.round(value) : 0))
+}
+
 /** Fold one decoded session into per-day / per-provider / per-model buckets. */
 export function foldSession(records) {
   const days = Object.create(null)
@@ -477,8 +505,8 @@ export function createUsageStats(input) {
     const daysAggregate = Object.create(null)
     const providersAggregate = Object.create(null)
     const modelsAggregate = Object.create(null)
-  const hoursAggregate = Object.create(null)
-  const workspacesAggregate = Object.create(null)
+    const hoursAggregate = Object.create(null)
+    const workspacesAggregate = Object.create(null)
     for (const entry of Object.values(cache.files)) {
       for (const [day, dayBucket] of Object.entries(entry.days ?? {})) {
         const target = (daysAggregate[day] ??= { providers: Object.create(null) })
@@ -516,6 +544,23 @@ export function createUsageStats(input) {
         }
       }
     }
+    // Local-hour series per day, folded from the epoch-hour buckets the session
+    // folds already carry: the chart mode drills into one day's 24 bars. Values
+    // stay raw here; `daily` rounds them once at the wire boundary.
+    const dayHoursAggregate = Object.create(null)
+    for (const [epochHour, bucket] of Object.entries(hoursAggregate)) {
+      const hourStart = Number(epochHour) * 3600_000
+      const date = new Date(hourStart)
+      if (!Number.isFinite(date.getTime())) continue
+      const slot = date.getHours()
+      const dayEntry = (dayHoursAggregate[dayKey(hourStart)] ??= { total: emptyHourSeries(), providers: Object.create(null) })
+      for (const [provider, providerBucket] of Object.entries(bucket.providers ?? {})) {
+        const tokens = providerBucket?.total
+        if (typeof tokens !== 'number' || !Number.isFinite(tokens) || tokens <= 0) continue
+        dayEntry.total[slot] += tokens
+        addHourTokens((dayEntry.providers[provider] ??= emptyHourSeries()), slot, tokens)
+      }
+    }
 
     const allTime = emptyBucket()
     for (const bucket of Object.values(providersAggregate)) addBucket(allTime, bucket)
@@ -627,7 +672,10 @@ export function createUsageStats(input) {
       })
       .sort((a, b) => b.allTime.total - a.allTime.total)
 
-    // Compact daily series (bounded) for the client chart view.
+    // Compact daily series (bounded) for the client chart view. `hours` is only
+    // present for a day with real local-hour data: a very old session's hour
+    // buckets are pruned by the fold, and a non-drillable day must not pretend
+    // to have an all-zero hour series.
     const daily = Object.entries(daysAggregate)
       .sort(([left], [right]) => left.localeCompare(right))
       .slice(-120)
@@ -638,7 +686,19 @@ export function createUsageStats(input) {
           providers[providerId] = { total: providerBucket.total ?? 0, messages: providerBucket.messages ?? 0 }
           addBucket(totals, providerBucket)
         }
-        return { day, total: { total: totals.total, messages: totals.messages }, providers }
+        const dayHours = dayHoursAggregate[day]
+        if (dayHours !== undefined) {
+          for (const [providerId, providerHours] of Object.entries(dayHours.providers)) {
+            // Only a provider already present in the day bucket gets a series.
+            if (providers[providerId] !== undefined) providers[providerId].hours = roundHourSeries(providerHours)
+          }
+        }
+        return {
+          day,
+          total: { total: totals.total, messages: totals.messages },
+          ...(dayHours === undefined ? {} : { hours: roundHourSeries(dayHours.total) }),
+          providers,
+        }
       })
 
     return {
@@ -789,7 +849,7 @@ export function createUsageStats(input) {
     try {
       const value = readZcodeUsage({ dbPath: zcodeDbPath })
       zcodeMemo = { sig, at: now, value, error: null }
-      log.info(`ZCode usage: ${value.rows} grouped day/provider/model rows in ${value.durationMs} ms`)
+      log.info(`ZCode usage: ${value.rows} grouped day/hour/provider/model rows in ${value.durationMs} ms`)
       return { enabled: true, dbPath: zcodeDbPath, value, error: null, cached: false }
     } catch (error) {
       const wire = {
@@ -921,7 +981,7 @@ export function createUsageStats(input) {
     try {
       const value = def.read()
       def.setMemo({ sig, at: now, value, error: null })
-      log.info(def.label + ' usage: ' + value.rows + ' grouped day/provider/model rows in ' + value.durationMs + ' ms')
+      log.info(def.label + ' usage: ' + value.rows + ' grouped day/hour/provider/model rows in ' + value.durationMs + ' ms')
       return { enabled: true, dbPath: def.dbPath, value, error: null, cached: false, installed: true }
     } catch (error) {
       const wire = {
@@ -1142,15 +1202,26 @@ export function createUsageStats(input) {
       for (const entry of unmapped) unmappedRows.push({ harnessId: def.id, harnessLabel: def.label, ...entry })
     }
 
-    // Daily series (last 120 days) for the chart view.
+    // Daily series (last 120 days) for the chart view. Each day keeps a bucket
+    // per canonical provider plus a 24-slot local-hour series; `hours` is only
+    // emitted for a day where at least one harness reported an hour, so the
+    // client never has to invent an all-zero drill-down.
     const dailyMap = new Map()
     for (const entry of dsh.daily ?? []) {
-      const dayEntry = dailyMap.get(entry.day) ?? { total: emptyBucket(), providers: new Map() }
+      const dayEntry = dailyMap.get(entry.day) ?? { total: emptyBucket(), providers: new Map(), hours: null }
       addBucket(dayEntry.total, entry.total)
+      if (Array.isArray(entry.hours)) {
+        dayEntry.hours ??= emptyHourSeries()
+        addHourSeries(dayEntry.hours, entry.hours)
+      }
       for (const [providerId, totals] of Object.entries(entry.providers ?? {})) {
-        const bucket = dayEntry.providers.get(providerId) ?? emptyBucket()
-        addBucket(bucket, totals)
-        dayEntry.providers.set(providerId, bucket)
+        const slot = dayEntry.providers.get(providerId) ?? { bucket: emptyBucket(), hours: null }
+        addBucket(slot.bucket, totals)
+        if (Array.isArray(totals?.hours)) {
+          slot.hours ??= emptyHourSeries()
+          addHourSeries(slot.hours, totals.hours)
+        }
+        dayEntry.providers.set(providerId, slot)
       }
       dailyMap.set(entry.day, dayEntry)
     }
@@ -1160,28 +1231,40 @@ export function createUsageStats(input) {
       if (slice.value === null) continue
       for (const group of slice.value.groups) {
         const mapped = mapHarnessProvider(group.providerId, group.modelId, def.aliases, catalog)
+        // Unmapped usage stays out of `daily` (it never had a provider row);
+        // its tokens only feed the all-harness buckets.
         if (mapped === null) continue
-        const dayEntry = dailyMap.get(group.day) ?? { total: emptyBucket(), providers: new Map() }
+        const dayEntry = dailyMap.get(group.day) ?? { total: emptyBucket(), providers: new Map(), hours: null }
         addBucket(dayEntry.total, group.bucket)
-        const bucket = dayEntry.providers.get(mapped.providerId) ?? emptyBucket()
-        addBucket(bucket, group.bucket)
-        dayEntry.providers.set(mapped.providerId, bucket)
+        if (Number.isInteger(group.hour)) {
+          addHourTokens((dayEntry.hours ??= emptyHourSeries()), group.hour, group.bucket.total)
+        }
+        const slot = dayEntry.providers.get(mapped.providerId) ?? { bucket: emptyBucket(), hours: null }
+        addBucket(slot.bucket, group.bucket)
+        if (Number.isInteger(group.hour)) {
+          addHourTokens((slot.hours ??= emptyHourSeries()), group.hour, group.bucket.total)
+        }
+        dayEntry.providers.set(mapped.providerId, slot)
         dailyMap.set(group.day, dayEntry)
       }
     }
     const daily = [...dailyMap.entries()]
       .sort(([left], [right]) => left.localeCompare(right))
       .slice(-120)
-      .map(([day, entry]) => ({
-        day,
-        total: { total: entry.total.total, messages: entry.total.messages },
-        providers: Object.fromEntries(
-          [...entry.providers.entries()].map(([providerId, bucket]) => [
-            providerId,
-            { total: bucket.total, messages: bucket.messages },
-          ]),
-        ),
-      }))
+      .map(([day, entry]) => {
+        const providers = Object.create(null)
+        for (const [providerId, slot] of entry.providers) {
+          const row = { total: slot.bucket.total, messages: slot.bucket.messages }
+          if (slot.hours !== null) row.hours = roundHourSeries(slot.hours)
+          providers[providerId] = row
+        }
+        return {
+          day,
+          total: { total: entry.total.total, messages: entry.total.messages },
+          ...(entry.hours === null ? {} : { hours: roundHourSeries(entry.hours) }),
+          providers,
+        }
+      })
 
     // Earliest record per provider across every contributing harness. This is
     // the local "effective date" used for the 最近X天 provider window.

package/lib/usage-zcode.mjs

@@ -20,13 +20,13 @@
  *   cacheWrite = cache_creation_input_tokens
  *   total      = computed_total_tokens (= input + output, cache included)
  *
- * Only token counters, provider/model ids and the completion day are read: no
+ * Only token counters, provider/model ids and the completion time are read: no
  * prompt or message content. The database is opened read-only.
  *
- * The result is a flat `groups` list (local day + ZCode provider id + model id +
- * bucket). Mapping a ZCode provider onto a canonical DSH provider (e.g.
- * `opencode-go-chat` -> `opencode-go`) is the caller's job, because the mapping
- * needs the Harness model catalog.
+ * The result is a flat `groups` list (local day + local hour + ZCode provider id
+ * + model id + bucket). Mapping a ZCode provider onto a canonical DSH provider
+ * (e.g. `opencode-go-chat` -> `opencode-go`) is the caller's job, because the
+ * mapping needs the Harness model catalog.
  */
 import { statSync } from 'node:fs'
 import { join } from 'node:path'
@@ -73,12 +73,23 @@ export function localDayKey(ms) {
   return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`
 }
 
+/**
+ * The local clock hour (0..23) of an epoch-ms instant.
+ *
+ * A DST fall-back day repeats one wall-clock hour, so both instants collapse
+ * into the same slot — which is exactly how the chart's 24 bars are defined.
+ */
+export function localHour(ms) {
+  const hour = new Date(ms).getHours()
+  return Number.isInteger(hour) && hour >= 0 && hour <= 23 ? hour : 0
+}
+
 /**
  * Read ZCode usage groups.
  *
  * @param input.dbPath - database file (read-only).
  * @param input.openDatabase - test seam: `(path) => DatabaseSync`-like handle.
- * @returns `{ groups: [{day, providerId, modelId, bucket}], rows, durationMs, dbPath }`.
+ * @returns `{ groups: [{day, hour, providerId, modelId, bucket}], rows, durationMs, dbPath }`.
  */
 export function readZcodeUsage(input = {}) {
   const dbPath = typeof input.dbPath === 'string' && input.dbPath !== '' ? input.dbPath : defaultZcodeDbPath()
@@ -89,6 +100,7 @@ export function readZcodeUsage(input = {}) {
     const rows = db
       .prepare(
         `SELECT date(completed_at / 1000, 'unixepoch', 'localtime') AS day,
+                CAST(strftime('%H', completed_at / 1000, 'unixepoch', 'localtime') AS INTEGER) AS hour,
                 provider_id AS providerId,
                 model_id AS modelId,
                 COUNT(*) AS messages,
@@ -99,8 +111,8 @@ export function readZcodeUsage(input = {}) {
                 SUM(computed_total_tokens) AS total
            FROM model_usage
           WHERE computed_total_tokens > 0 AND completed_at IS NOT NULL
-          GROUP BY day, provider_id, model_id
-          ORDER BY day`,
+          GROUP BY day, hour, provider_id, model_id
+          ORDER BY day, hour`,
       )
       .all()
     const groups = rows
@@ -108,8 +120,11 @@ export function readZcodeUsage(input = {}) {
       .map((row) => {
         const input = Math.max(0, Number(row.input ?? 0))
         const cacheRead = Math.max(0, Number(row.cacheRead ?? 0))
+        const hour = Number(row.hour)
         return {
           day: row.day,
+          // SQLite yields '00'..'23'; keep the wire field an integer.
+          hour: Number.isInteger(hour) && hour >= 0 && hour <= 23 ? hour : 0,
           providerId: typeof row.providerId === 'string' && row.providerId !== '' ? row.providerId : 'unknown',
           modelId: typeof row.modelId === 'string' && row.modelId !== '' ? row.modelId : 'unknown',
           bucket: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tokenlens",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "type": "module",
   "description": "dsh-TokenLens (词元透镜) — provider-aware plan capacity plus local token statistics (today/7d/30d/all-time, by harness/provider/model/workspace) for DSH.",
   "license": "MIT",