dsh-token-chart 0.0.0-stage → 0.1.0

package/src/client/contract.ts

@@ -0,0 +1,62 @@
+/**
+ * Package-wide constants shared by every client module: the API
+ * prefix, the entry id, colors, chart vocabulary and preference defaults.
+ *
+ * @module dsh-token-chart/client/contract
+ */
+import type { Prefs } from '../types.ts'
+
+import { CHART_IDS, METRIC_IDS as SHARED_METRIC_IDS } from '../constants.ts'
+import type { ChartId, MetricId } from '../types.ts'
+
+import type { Translate } from './models.ts'
+
+export const API = '/token-chart/api'
+export const NS = 'token-chart'
+/** Right-sidebar tab type id and kind; also the slot key of its seats. */
+export const KIND = 'dsh-token-chart'
+/** Left sidebar panel id and the key of its `main` seat. */
+export const PANEL_ID = 'token-chart'
+
+export const COLOR = {
+  total: 'var(--dsw-alias-brand-primary)',
+  input: 'var(--dsw-alias-state-warn-primary)',
+  output: 'var(--dsw-alias-state-success-primary)',
+  cache: 'var(--dsw-alias-state-idle-primary)',
+  cacheHitRate: 'var(--dsw-alias-state-error-primary)',
+}
+export const METRIC_COLOR = {
+  total: COLOR.total,
+  input: COLOR.input,
+  output: COLOR.output,
+  cache: COLOR.cache,
+  cacheHitRate: COLOR.cacheHitRate,
+}
+export const CHART_KINDS: ChartId[] = [...CHART_IDS]
+export const METRIC_IDS: MetricId[] = [...SHARED_METRIC_IDS]
+export const DEFAULT_PREFS: Prefs = {
+  sessionChart: 'multi-bar',
+  dailyChart: 'multi-bar',
+  sessionMetrics: ['input', 'output', 'cache', 'total'],
+  dailyMetrics: ['input', 'output', 'cache', 'total'],
+  showTable: true,
+  showCacheHitRate: true,
+  interceptUsageButton: true,
+}
+
+/* ------------------------------------------------------------ locale */
+
+/** What the shell hands a browser-half plugin when it mounts `apply`. */
+export interface ClientContext {
+  effect: (callback: () => unknown, description?: string) => unknown
+  inject: (deps: string[], callback: (services: Record<string, any>) => unknown) => unknown
+  logger?: { info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void }
+  locale: {
+    bind: (namespace: string) => Translate
+    register: (namespace: string, dictionaries: { zh: Record<string, string>; en: Record<string, string> }) => unknown
+  }
+  slots: {
+    inject: (name: string, callback: () => unknown) => () => void
+    register: (options: Record<string, unknown>, component?: unknown) => unknown
+  }
+}

package/src/client/drawer.tsx

@@ -0,0 +1,113 @@
+/**
+ * The session drawer body shown in the right sidebar.
+ *
+ * @module dsh-token-chart/client/drawer
+ */
+import type { SessionReport } from '../types.ts'
+
+import type { ChartPoint, TableRow } from './models.ts'
+
+import { useEndpoint } from './api.ts'
+
+import type { ColumnSpec, Translate } from './models.ts'
+
+import { React } from './react.ts'
+
+import { usePrefs } from './api.ts'
+import { clockText, exactTokens, fill, percentText } from './format.ts'
+import { ChartBlock } from './series.tsx'
+import { KpiRow, UsageFacts } from './ui.tsx'
+
+export function SessionUsageBody({ sessionId, t }: { sessionId: string; t: Translate }) {
+  const prefs = usePrefs()
+  const [tick, setTick] = React.useState(0)
+  const endpoint = useEndpoint(`/session?sessionId=${encodeURIComponent(sessionId ?? '')}`, tick)
+  const report = endpoint.value as SessionReport | undefined
+  const totals = report?.totals
+  const turns: TableRow[] = Array.isArray(report?.turns) ? (report.turns as TableRow[]) : []
+  const points: ChartPoint[] = turns.map((turn: TableRow) => ({
+    label: `#${turn.turn}`,
+    values: {
+      input: turn.input,
+      output: turn.output,
+      cache: turn.cache,
+      total: turn.total,
+      cacheHitRate: turn.cacheHitRate,
+    },
+  }))
+  const columns: ColumnSpec[] = [
+    { key: 'turn', label: t('table.turn') },
+    { key: 'time', label: t('table.time'), render: (row) => clockText(row.time) },
+    { key: 'total', label: t('metric.total'), align: 'right', render: (row) => exactTokens(row.total) },
+    { key: 'input', label: t('metric.input'), align: 'right', render: (row) => exactTokens(row.input) },
+    { key: 'output', label: t('metric.output'), align: 'right', render: (row) => exactTokens(row.output) },
+    { key: 'cache', label: t('metric.cache'), align: 'right', render: (row) => exactTokens(row.cache) },
+    {
+      key: 'cacheHitRate',
+      label: t('metric.cacheHitRate'),
+      align: 'right',
+      render: (row) => percentText(row.cacheHitRate),
+    },
+  ]
+  const routes: Array<[string, string]> =
+    Array.isArray(totals?.routes) && totals.routes.length > 0 ? [[t('usage.route'), totals.routes.join(', ')]] : []
+
+  return (
+    <div className="dtc-root dtc-drawer">
+      {
+        <div className="dtc-head">
+          <div>
+            <h3 className="dtc-title">{t('usage.title')}</h3>
+            <p className="dtc-subtitle">{`${t('usage.session')} · ${turns.length} ${t('usage.turns')}`}</p>
+          </div>
+          {
+            <button
+              type="button"
+              className="dtc-button"
+              onClick={() => setTick((value) => value + 1)}
+              title={t('usage.refresh')}
+            >
+              {t('panel.refresh')}
+            </button>
+          }
+        </div>
+      }
+      {endpoint.loading && report === undefined ? (
+        <p className="dtc-empty">{t('panel.loading')}</p>
+      ) : endpoint.error !== undefined ? (
+        <p className="dtc-error">{endpoint.error}</p>
+      ) : turns.length === 0 ? (
+        <p className="dtc-empty">{t('usage.emptySession')}</p>
+      ) : (
+        <React.Fragment>
+          <div className="dtc-banner">
+            <span className="dtc-banner-label">{t('metric.total')}</span>
+            <span className="dtc-banner-value">{exactTokens(totals?.total)}</span>
+          </div>
+          <UsageFacts totals={totals} t={t} extra={routes} />
+          {report?.crossCheck?.matches === false ? (
+            <p className="dtc-warn" data-dtc-crosscheck="mismatch">
+              {fill(t('usage.crossCheckFailed'), { product: exactTokens(report.crossCheck.total) })}
+            </p>
+          ) : null}
+          <p className="dtc-footnote">{t('usage.accounting')}</p>
+          <KpiRow totals={totals} t={t} />
+          <div className="dtc-section-title">{t('settings.sessionChart')}</div>
+          <ChartBlock
+            kind={prefs.sessionChart}
+            points={points}
+            totals={totals}
+            metrics={prefs.sessionMetrics}
+            columns={columns}
+            rows={turns}
+            showTable={prefs.showTable}
+            showHitRate={prefs.showCacheHitRate}
+            t={t}
+          />
+        </React.Fragment>
+      )}
+    </div>
+  )
+}
+
+/* -------------------------------------------------- daily usage panel */

package/src/client/format.ts

@@ -0,0 +1,36 @@
+/**
+ * Number, rate and time formatting shared by charts, tables and facts.
+ *
+ * @module dsh-token-chart/client/format
+ */
+export function compactTokens(value: unknown): string {
+  const number = Number(value) || 0
+  if (Math.abs(number) >= 1e9) return `${(number / 1e9).toFixed(2)}B`
+  if (Math.abs(number) >= 1e6) return `${(number / 1e6).toFixed(2)}M`
+  if (Math.abs(number) >= 1e4) return `${(number / 1e3).toFixed(1)}K`
+  return String(Math.round(number))
+}
+
+export function exactTokens(value: unknown): string {
+  return (Number(value) || 0).toLocaleString('en-US')
+}
+
+export function percentText(rate: unknown): string {
+  return `${((Number(rate) || 0) * 100).toFixed(1)}%`
+}
+
+export function clockText(time: unknown, withSeconds = false): string {
+  const date = new Date(Number(time) || Date.now())
+  const pad = (input: number): string => String(input).padStart(2, '0')
+  const base = `${pad(date.getHours())}:${pad(date.getMinutes())}`
+  return withSeconds ? `${base}:${pad(date.getSeconds())}` : base
+}
+
+/** Translate one template with `{name}` placeholders. */
+export function fill(template: string, values: Record<string, string | number>): string {
+  return String(template).replace(/\{(\w+)\}/g, (_match, key) =>
+    values[key] === undefined ? `{${key}}` : String(values[key]),
+  )
+}
+
+/* ------------------------------------------------------- prefs store */

package/src/client/globals.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ambient declarations for the loader-provided globals a browser half sees.
+ *
+ * `require` is not Node's: the client module system passes a function whose
+ * `async` member loads a declared package-local chunk. `window.__ModuleLoader__`
+ * is the registration entry point every client bundle calls.
+ *
+ * @module dsh-token-chart/client/globals
+ */
+
+/** The chunk-aware require the loader injects into a client factory. */
+declare const require: {
+  (specifier: string): any
+  async: (chunk: string) => Promise<any>
+}
+
+interface Window {
+  __ModuleLoader__: {
+    load: (registration: { id: string; chunk?: string; factory: (require: any) => unknown }) => void
+  }
+}

package/src/client/index.tsx

@@ -0,0 +1,227 @@
+/**
+ * dsh-token-chart — browser half entry.
+ *
+ * Registers the plugin's seats (settings section, sidebar entry + panel, the
+ * right-sidebar drawer, the session-header action), intercepts the product's
+ * own usage pill, and keeps the preference store warm for every seat.
+ *
+ * Built by scripts/build-client.mjs into lib/client.js as a
+ * `window.__ModuleLoader__` factory — the DSH client-module contract, the same
+ * shape the shipped plugins use.
+ *
+ * @module dsh-token-chart/client
+ */
+import type { Translate } from './models.ts'
+
+import { DEFAULT_PREFS, KIND, NS, PANEL_ID } from './contract.ts'
+import { apiGet, prefsStore } from './api.ts'
+import { HeaderUsageButton, installStyles, PanelIcon, registerSettingsNavIcon } from './chrome.tsx'
+import { isUsagePill } from './pill.ts'
+import { en, zh } from './locales.ts'
+import { DailyUsagePanel } from './panel.tsx'
+import { SessionUsageBody } from './drawer.tsx'
+import { TokenChartSettings } from './settings.tsx'
+import type { ClientContext } from './contract.ts'
+
+export const inject = ['slots', 'locale']
+
+export function apply(ctx: ClientContext): void {
+  const t = ctx.locale.bind(NS)
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-token-chart: dictionaries')
+  ctx.effect(() => installStyles(), 'dsh-token-chart: styles')
+  ctx.effect(() => registerSettingsNavIcon(() => t('settings.nav')), 'dsh-token-chart: settings nav icon')
+
+  /** Optional services captured as they appear. */
+  const services: { sidebarRight: any; sidebarRightTabs: any } = {
+    sidebarRight: undefined,
+    sidebarRightTabs: undefined,
+  }
+
+  const openDrawer = (sessionId: string): boolean => {
+    const right = services.sidebarRight
+    if (right === undefined || typeof sessionId !== 'string' || sessionId === '') return false
+    try {
+      right.openTab(KIND, { params: { sessionId } })
+      return true
+    } catch (error) {
+      console.warn('[dsh-token-chart] could not open the usage drawer:', error)
+      return false
+    }
+  }
+
+  const mountedSessionId = () => {
+    const right = services.sidebarRight
+    if (right === undefined || right.mounted === undefined) return undefined
+    try {
+      return right.mounted.getSnapshot()
+    } catch {
+      return undefined
+    }
+  }
+
+  /* Warm the preference store for every seat. */
+  ctx.effect(() => {
+    let live = true
+    apiGet('/prefs')
+      .then((payload) => {
+        if (live) prefsStore.set({ ...DEFAULT_PREFS, ...payload.value })
+      })
+      .catch(() => {
+        /* defaults */
+      })
+    return () => {
+      live = false
+    }
+  }, 'dsh-token-chart: preferences')
+
+  /* ---- settings page ------------------------------------------- */
+
+  ctx.slots.inject('settings.section', () =>
+    ctx.slots.register(
+      {
+        name: 'settings.section',
+        id: 'token-chart',
+        order: 30,
+        label: () => t('settings.nav'),
+        locale: NS,
+      },
+      TokenChartSettings,
+    ),
+  )
+
+  /* ---- left sidebar entry + panel ------------------------------ */
+
+  ctx.slots.inject('sidebar.panellist', () =>
+    ctx.slots.register(
+      {
+        name: 'sidebar.panellist',
+        id: PANEL_ID,
+        order: 12,
+        label: () => t('panel.title'),
+        locale: NS,
+      },
+      PanelIcon,
+    ),
+  )
+
+  ctx.slots.inject('main', () =>
+    ctx.slots.register(
+      {
+        name: 'main',
+        key: PANEL_ID,
+        locale: NS,
+      },
+      DailyUsagePanel,
+    ),
+  )
+
+  /* ---- session header shortcut --------------------------------- */
+
+  ctx.slots.inject('conversation.session.header.utilities', () =>
+    ctx.slots.register(
+      {
+        name: 'conversation.session.header.utilities',
+        id: 'token-chart',
+        order: 6,
+        locale: NS,
+        inject: (sessionId: string) => ({ sessionId, open: openDrawer }),
+      },
+      HeaderUsageButton,
+    ),
+  )
+
+  /* ---- right sidebar tab type + seats -------------------------- */
+
+  ctx.inject(['sidebarRightTabs'], (injected: Record<string, any>) => {
+    const tabs = injected.get('sidebarRightTabs')
+    if (tabs === undefined) return undefined
+    services.sidebarRightTabs = tabs
+    const disposers: Array<() => void> = []
+    try {
+      disposers.push(
+        tabs.register({
+          id: KIND,
+          kind: KIND,
+          priority: 'extension',
+          title: () => t('usage.title'),
+          guide: [
+            {
+              id: KIND,
+              order: 40,
+              title: () => t('usage.title'),
+              description: () => t('usage.session'),
+            },
+          ],
+        }),
+      )
+    } catch (error) {
+      console.warn('[dsh-token-chart] tab type registration failed:', error)
+      return undefined
+    }
+    disposers.push(
+      ctx.slots.inject('sidebar.right.pane.tab', () =>
+        ctx.slots.register(
+          {
+            name: 'sidebar.right.pane.tab',
+            key: KIND,
+            locale: NS,
+            inject: (sessionId: string) => ({ sessionId }),
+          },
+          SessionUsageBody,
+        ),
+      ),
+    )
+    disposers.push(
+      ctx.slots.inject('sidebar.right.pane.tab.title', () =>
+        ctx.slots.register(
+          {
+            name: 'sidebar.right.pane.tab.title',
+            key: KIND,
+            locale: NS,
+          },
+          ({ t: translate }: { t: Translate }) => <span className="dtc-tab-title">{translate('usage.title')}</span>,
+        ),
+      ),
+    )
+    return () => {
+      services.sidebarRightTabs = undefined
+      for (const dispose of disposers) {
+        try {
+          dispose()
+        } catch {
+          /* a seat already collapsed is not a failure */
+        }
+      }
+    }
+  })
+
+  ctx.inject(['sidebarRight'], (injected: Record<string, any>) => {
+    services.sidebarRight = injected.get('sidebarRight')
+    return () => {
+      services.sidebarRight = undefined
+    }
+  })
+
+  /* ---- usage pill interception --------------------------------- */
+
+  ctx.effect(() => {
+    const onClick = (event: MouseEvent): void => {
+      if (prefsStore.get().interceptUsageButton !== true) return
+      if (isUsagePill(event.target) === false) return
+      const sessionId = mountedSessionId()
+      if (sessionId === undefined) return
+      if (openDrawer(sessionId) === false) return
+      event.preventDefault()
+      event.stopPropagation()
+    }
+    document.addEventListener('click', onClick, true)
+    return () => document.removeEventListener('click', onClick, true)
+  }, 'dsh-token-chart: usage pill interception')
+
+  ctx.effect(
+    () => () => {
+      /* listeners and registrations are disposed with this fiber */
+    },
+    'dsh-token-chart: teardown',
+  )
+}

package/src/client/locales.ts

@@ -0,0 +1,164 @@
+/**
+ * The plugin's own dictionaries (zh / en) for its namespace.
+ *
+ * @module dsh-token-chart/client/locales
+ */
+export const zh = {
+  'panel.title': 'Token 用量',
+  'panel.subtitle': '统计今天、近 3 天、近 7 天的 Token 用量',
+  'panel.range.today': '今天',
+  'panel.range.3d': '近 3 天',
+  'panel.range.7d': '近 7 天',
+  'panel.refresh': '刷新',
+  'panel.loading': '正在统计…',
+  'panel.empty': '所选区间内还没有 Token 用量记录',
+  'table.total': '共 {count} 条',
+  'table.pagination': '分页',
+  'table.prev': '上一页',
+  'table.next': '下一页',
+  'table.pageSizeLabel': '每页条数',
+  'table.page': '第 {page} 页',
+  'table.pageSize': '{size} 条/页',
+  'panel.updated': '更新于 {time}',
+  'panel.retention': '仅保留近 {days} 天的数据',
+  'settings.nav': 'Token 用量',
+  'settings.title': 'Token 用量可视化',
+  'settings.description': '选择各场景使用的图表形式与展示指标，保存后立即生效。',
+  'settings.sessionChart': '会话用量抽屉',
+  'settings.sessionChartHint': '点击会话中的「用量」按钮后，在右侧抽屉里展示的图形。',
+  'settings.dailyChart': '每日用量面板',
+  'settings.dailyChartHint': '侧边栏「Token 用量」菜单中「今天 / 近 3 天 / 近 7 天」的图形。',
+  'settings.metrics': '展示指标',
+  'settings.showTable': '图表下方附带数据表格',
+  'settings.showCacheHitRate': '叠加缓存命中率折线',
+  'settings.showCacheHitRateHint': '在柱状图、折线图与组合图中叠加缓存命中率折线（右轴）',
+  'settings.interceptUsageButton': '点击「用量」按钮打开侧边抽屉',
+  'settings.interceptUsageButtonHint': '关闭后恢复 DSH 默认的用量弹窗。',
+  'settings.saved': '已保存',
+  'settings.saving': '保存中…',
+  'settings.saveFailed': '保存失败：{error}',
+  'settings.preview': '预览',
+  'settings.reset': '恢复默认',
+  'chart.bar': '柱状图',
+  'chart.line': '折线图',
+  'chart.pie': '饼图',
+  'chart.table': '表格',
+  'chart.multi-bar': '多柱状图',
+  'chart.multi-line': '多折线图',
+  'chart.bar-line': '柱状折线组合图',
+  'chart.loading': '正在加载图表…',
+  'settings.update': '更新版本',
+  'settings.update.checking': '正在检查更新…',
+  'settings.update.upToDate': '已是最新版本',
+  'settings.update.unpublished': '未发布到 registry，无法自动更新',
+  'settings.update.running': '正在更新…',
+  'settings.update.done': '更新完成：{target}',
+  'settings.update.failed': '更新失败：{error}',
+  'settings.update.local': '本地安装，请在源码目录重建并重新加载',
+  'settings.update.check': '检查更新',
+  'metric.total': '总 Token',
+  'metric.input': '输入 Token',
+  'metric.output': '输出 Token',
+  'metric.cache': '缓存 Token',
+  'metric.cacheHitRate': '缓存命中率',
+  'usage.title': 'Token 用量',
+  'usage.session': '会话 Token 用量',
+  'usage.turns': '对话轮次',
+  'usage.sessions': '活跃会话',
+  'usage.cacheRead': '缓存读取',
+  'usage.cacheWrite': '缓存写入',
+  'usage.route': '模型',
+  'usage.openDrawer': '打开 Token 用量抽屉',
+  'usage.refresh': '刷新用量',
+  'table.day': '日期',
+  'table.turn': '轮次',
+  'table.time': '时间',
+  'table.metric': '指标',
+  'table.value': '数值',
+  'table.share': '占比',
+  'table.session': '会话',
+  'usage.emptySession': '该会话还没有可统计的 Token 用量',
+  'usage.accounting': '总量按计费口径累计：每次请求的上下文（含缓存重读）都计入，与 DSH 产品内「用量」一致',
+  'usage.crossCheckFailed': '与产品内「用量」投影不一致（产品 {product}）——请反馈此差异',
+}
+export const en = {
+  'panel.title': 'Token usage',
+  'panel.subtitle': 'Today, last 3 days, and last 7 days of token usage',
+  'panel.range.today': 'Today',
+  'panel.range.3d': 'Last 3 days',
+  'panel.range.7d': 'Last 7 days',
+  'panel.refresh': 'Refresh',
+  'panel.loading': 'Collecting…',
+  'panel.empty': 'No token usage recorded in this window',
+  'table.total': '{count} rows',
+  'table.pagination': 'Pagination',
+  'table.prev': 'Previous page',
+  'table.next': 'Next page',
+  'table.page': 'Page {page}',
+  'table.pageSize': '{size} / page',
+  'table.pageSizeLabel': 'Rows per page',
+  'panel.updated': 'Updated {time}',
+  'panel.retention': 'Only the last {days} days are kept',
+  'settings.nav': 'Token usage',
+  'settings.title': 'Token usage charts',
+  'settings.description': 'Choose the chart form and the metrics for each surface; changes apply immediately.',
+  'settings.sessionChart': 'Session usage drawer',
+  'settings.sessionChartHint': 'The chart shown in the right drawer after clicking the usage button.',
+  'settings.dailyChart': 'Daily usage panel',
+  'settings.dailyChartHint': 'The chart for Today / last 3 days / last 7 days in the sidebar panel.',
+  'settings.metrics': 'Metrics',
+  'settings.showTable': 'Show the data table under the chart',
+  'settings.showCacheHitRate': 'Overlay the cache-hit-rate line',
+  'settings.showCacheHitRateHint': 'Overlay the cache-hit-rate line (right axis) on bar, line and combo charts',
+  'settings.interceptUsageButton': 'Open the drawer from the usage button',
+  'settings.interceptUsageButtonHint': 'Turn off to restore the shipped usage dialog.',
+  'settings.saved': 'Saved',
+  'settings.saving': 'Saving…',
+  'settings.saveFailed': 'Save failed: {error}',
+  'settings.preview': 'Preview',
+  'settings.reset': 'Restore defaults',
+  'chart.bar': 'Bar',
+  'chart.line': 'Line',
+  'chart.pie': 'Pie',
+  'chart.table': 'Table',
+  'chart.multi-bar': 'Grouped bars',
+  'chart.multi-line': 'Multi line',
+  'chart.bar-line': 'Bar + line',
+  'chart.loading': 'Loading chart…',
+  'settings.update': 'Update',
+  'settings.update.checking': 'Checking for updates…',
+  'settings.update.upToDate': 'Up to date',
+  'settings.update.unpublished': 'Not published to a registry',
+  'settings.update.running': 'Updating…',
+  'settings.update.done': 'Updated: {target}',
+  'settings.update.failed': 'Update failed: {error}',
+  'settings.update.local': 'Local install — rebuild and reload from the source directory',
+  'settings.update.check': 'Check for updates',
+  'metric.total': 'Total tokens',
+  'metric.input': 'Input tokens',
+  'metric.output': 'Output tokens',
+  'metric.cache': 'Cache tokens',
+  'metric.cacheHitRate': 'Cache hit rate',
+  'usage.title': 'Token usage',
+  'usage.session': 'Session token usage',
+  'usage.turns': 'Turns',
+  'usage.sessions': 'Active sessions',
+  'usage.cacheRead': 'Cache read',
+  'usage.cacheWrite': 'Cache write',
+  'usage.route': 'Model',
+  'usage.openDrawer': 'Open the token usage drawer',
+  'usage.refresh': 'Refresh usage',
+  'table.day': 'Day',
+  'table.turn': 'Turn',
+  'table.time': 'Time',
+  'table.metric': 'Metric',
+  'table.value': 'Value',
+  'table.share': 'Share',
+  'table.session': 'Session',
+  'usage.emptySession': 'This session has no token usage yet',
+  'usage.accounting':
+    'Totals follow the billing rule: every request re-reads the context (cache included) and counts — same as the product usage pill',
+  'usage.crossCheckFailed': 'Differs from the product usage projection ({product}) — please report this',
+}
+
+/* -------------------------------------------------------------- util */