feat: user dashboard (#1354)

* feat(settings): add usage dashboard

* feat: change layout for dashboard

* feat: add input/output in dashboard

* feat: change style for dashboard

* feat(settings): add dashboard charts

* feat(settings): polish usage dashboard

* fix(usage): harden stats and dashboard

Author: zerob13

docs/specs/settings-dashboard/plan.md

@@ -0,0 +1,46 @@
+# Plan
+
+## Data Model
+
+- Add `deepchat_usage_stats` keyed by `message_id`.
+- Store final per-message usage snapshots:
+  - session, provider, model
+  - input/output/total tokens
+  - cached input tokens
+  - estimated USD cost
+  - local usage date
+  - source (`backfill` or `live`)
+
+## Backfill
+
+- Trigger in `AFTER_START` with a non-blocking hook.
+- Scan only `deepchat_messages` joined with `deepchat_sessions`.
+- Use message metadata provider/model first, then session fallback.
+- Persist backfill status in config under `dashboardStatsBackfillV1`.
+- Re-running is safe because stats rows are upserted by `message_id`.
+
+## Live Recording
+
+- Extend stream usage metadata with optional `cached_tokens`.
+- Persist cached input tokens into assistant message metadata.
+- Upsert stats from `DeepChatMessageStore.finalizeAssistantMessage` and `setMessageError`.
+
+## Dashboard Query
+
+- Expose `newAgentPresenter.getUsageDashboard()`.
+- Aggregate summary, 365-day calendar, provider breakdown, and model breakdown from `deepchat_usage_stats`.
+
+## UI
+
+- Add `DashboardSettings.vue` as a scrollable settings page.
+- Keep the visual language aligned with the current project theme.
+- Show loading, empty, running backfill, and failed backfill states.
+- Render four summary cards only; remove the cache hit rate card from the dashboard overview.
+- Adopt the official `shadcn-vue chart` component with `Unovis` for dashboard chart rendering.
+- Rebuild the overview layout as `1 large + 3 small`, with total tokens as the hero chart.
+- Replace the total-token number card with a donut-based hero chart that visualizes input/output ratio.
+- Visualize cached input tokens with a compact horizontal stacked bar for cached versus uncached input.
+- Visualize estimated cost with a 30-day area chart while keeping the total cost as the primary value.
+- Reuse `recordingStartedAt` to render a locale-specific, number-first "days with DeepChat" summary card in the renderer.
+- Keep provider/model ranking queries unchanged, but render them as horizontal token bar charts with internal scrolling.
+- Translate changed dashboard copy per locale instead of falling back to English sentence structure.

docs/specs/settings-dashboard/spec.md

@@ -0,0 +1,33 @@
+# Settings Dashboard
+
+## Goal
+
+Add a dedicated dashboard page under settings to show token usage, cached token usage, estimated cost, and a GitHub-like contribution calendar.
+
+## User Stories
+
+- As a user, I want to see my total token usage, cached token usage, and estimated cost in one place.
+- As an existing user, I want the dashboard to initialize from the current `deepchat_messages` table once, without scanning legacy tables.
+- As a user, I want the dashboard to keep growing from newly recorded usage without repeatedly recomputing from old chat tables.
+
+## Acceptance Criteria
+
+- A new settings route named `settings-dashboard` is available after provider settings.
+- The dashboard reads from a dedicated `deepchat_usage_stats` table only.
+- Existing users get a one-time background backfill from current `deepchat_messages`.
+- Historical backfill sets cached input tokens to `0`.
+- New assistant message finalization and error finalization upsert usage rows into `deepchat_usage_stats`.
+- Price estimation uses current provider pricing first and falls back to `aihubmix` for the same model id when needed.
+- The page contains four overview cards arranged as `1 large + 3 small`: a total-token hero chart, a cached-token ratio card, an estimated-cost trend card, and a days-with-DeepChat card.
+- The total-token hero chart uses the shared `shadcn-vue chart + Unovis` visual language, keeps the donut semantics for input/output composition, and shows exact values plus percentages.
+- The cached-token card uses the same chart system to visualize cached versus uncached input tokens and shows exact values plus percentages.
+- The estimated-cost card uses the same chart system to show the total estimated cost plus a lightweight 30-day area trend.
+- The "days with DeepChat" card is derived from the earliest recorded usage date and rendered in a number-first, locale-specific layout.
+- The page contains a 365-day contribution calendar and provider/model breakdowns.
+- Provider and model breakdown cards render horizontal token bar charts with internal scrolling without growing the full page indefinitely.
+
+## Non-Goals
+
+- No backfill from legacy `messages` or `conversations` tables.
+- No delete-triggered rollback of accumulated usage stats.
+- No additional day-level rollup table in v1.

docs/specs/settings-dashboard/tasks.md

@@ -0,0 +1,8 @@
+# Tasks
+
+1. Add shared dashboard types and cached token usage plumbing.
+2. Add `deepchat_usage_stats` table and wire it into `SQLitePresenter`.
+3. Record live usage stats on assistant finalize and error finalize.
+4. Implement one-time historical backfill and dashboard query methods in `NewAgentPresenter`.
+5. Add settings route, dashboard page, and i18n strings.
+6. Add focused main/renderer tests and run format, i18n, and lint.

package.json

@@ -115,6 +115,8 @@
     "@lingual/i18n-check": "0.8.12",
     "@mcp-ui/client": "^5.13.3",
     "@pinia/colada": "^0.20.0",
+    "@unovis/ts": "1.6.4",
+    "@unovis/vue": "1.6.4",
     "@tailwindcss/typography": "^0.5.19",
     "@tailwindcss/vite": "^4.1.18",
     "@tiptap/core": "^2.11.7",

src/main/presenter/deepchatAgentPresenter/accumulator.ts

@@ -123,6 +123,7 @@ export function accumulate(state: StreamState, event: LLMCoreStreamEvent): void
       state.metadata.inputTokens = event.usage.prompt_tokens
       state.metadata.outputTokens = event.usage.completion_tokens
       state.metadata.totalTokens = event.usage.total_tokens
+      state.metadata.cachedInputTokens = event.usage.cached_tokens
       break
     }
     case 'stop': {

src/main/presenter/deepchatAgentPresenter/messageStore.ts

@@ -8,7 +8,14 @@ import type {
   MessageMetadata
 } from '@shared/types/agent-interface'
 import type { SearchResult } from '@shared/types/core/search'
+import logger from '@shared/logger'
 import type { DeepChatMessageRow } from '../sqlitePresenter/tables/deepchatMessages'
+import {
+  buildUsageStatsRecord,
+  parseMessageMetadata,
+  resolveUsageModelId,
+  resolveUsageProviderId
+} from '../usageStats'
 
 export class DeepChatMessageStore {
   private sqlitePresenter: SQLitePresenter
@@ -81,6 +88,7 @@ export class DeepChatMessageStore {
       'sent',
       metadata
     )
+    this.persistUsageStats(messageId, metadata, 'live')
   }
 
   updateCompactionMessage(
@@ -112,6 +120,7 @@ export class DeepChatMessageStore {
       'error',
       metadata
     )
+    this.persistUsageStats(messageId, metadata, 'live')
   }
 
   getMessages(sessionId: string): ChatMessageRecord[] {
@@ -376,4 +385,55 @@ export class DeepChatMessageStore {
       summaryUpdatedAt
     }
   }
+
+  private persistUsageStats(
+    messageId: string,
+    metadataRaw: string,
+    source: 'backfill' | 'live'
+  ): void {
+    const usageStatsTable = this.sqlitePresenter.deepchatUsageStatsTable
+    if (!usageStatsTable) {
+      return
+    }
+
+    const messageRow = this.sqlitePresenter.deepchatMessagesTable.get(messageId)
+    if (!messageRow || messageRow.role !== 'assistant') {
+      return
+    }
+
+    try {
+      const metadata = parseMessageMetadata(metadataRaw)
+      if (metadata.messageType === 'compaction') {
+        return
+      }
+
+      const sessionRow = this.sqlitePresenter.deepchatSessionsTable.get(messageRow.session_id)
+      const providerId = resolveUsageProviderId(metadata, sessionRow?.provider_id)
+      const modelId = resolveUsageModelId(metadata, sessionRow?.model_id)
+
+      if (!providerId || !modelId) {
+        return
+      }
+
+      const usageRecord = buildUsageStatsRecord({
+        messageId: messageRow.id,
+        sessionId: messageRow.session_id,
+        createdAt: messageRow.created_at,
+        updatedAt: messageRow.updated_at,
+        providerId,
+        modelId,
+        metadata,
+        source
+      })
+
+      if (!usageRecord) {
+        return
+      }
+
+      usageStatsTable.upsert(usageRecord)
+    } catch (error) {
+      logger.error('Failed to persist deepchat usage stats', { messageId, source }, error)
+      return
+    }
+  }
 }

src/main/presenter/deepchatAgentPresenter/process.ts

@@ -225,5 +225,8 @@ function buildUsageSnapshot(state: StreamState): Record<string, number> {
   if (typeof state.metadata.outputTokens === 'number') {
     usage.outputTokens = state.metadata.outputTokens
   }
+  if (typeof state.metadata.cachedInputTokens === 'number') {
+    usage.cachedInputTokens = state.metadata.cachedInputTokens
+  }
   return usage
 }

src/main/presenter/lifecyclePresenter/hooks/after-start/usageStatsBackfillHook.ts

@@ -0,0 +1,26 @@
+import { LifecycleHook, LifecycleContext } from '@shared/presenter'
+import { LifecyclePhase } from '@shared/lifecycle'
+import { presenter } from '@/presenter'
+
+export const usageStatsBackfillHook: LifecycleHook = {
+  name: 'usage-stats-backfill',
+  phase: LifecyclePhase.AFTER_START,
+  priority: 21,
+  critical: false,
+  execute: async (_context: LifecycleContext) => {
+    if (!presenter) {
+      throw new Error('usageStatsBackfillHook: Presenter not initialized')
+    }
+
+    const newAgentPresenter = presenter.newAgentPresenter as unknown as {
+      startUsageStatsBackfill?: () => Promise<void>
+    }
+    if (!newAgentPresenter.startUsageStatsBackfill) {
+      return
+    }
+
+    void newAgentPresenter.startUsageStatsBackfill().catch((error) => {
+      console.error('usageStatsBackfillHook: failed to start usage stats backfill:', error)
+    })
+  }
+}

src/main/presenter/lifecyclePresenter/hooks/index.ts

@@ -11,6 +11,7 @@ export { eventListenerSetupHook } from './ready/eventListenerSetupHook'
 export { traySetupHook } from './after-start/traySetupHook'
 export { windowCreationHook } from './after-start/windowCreationHook'
 export { legacyImportHook } from './after-start/legacyImportHook'
+export { usageStatsBackfillHook } from './after-start/usageStatsBackfillHook'
 export { trayDestroyHook } from './beforeQuit/trayDestroyHook'
 export { floatingDestroyHook } from './beforeQuit/floatingDestroyHook'
 export { presenterDestroyHook } from './beforeQuit/presenterDestroyHook'

src/main/presenter/llmProviderPresenter/providers/openAICompatibleProvider.ts

@@ -66,6 +66,28 @@ const SUPPORTED_IMAGE_SIZES = {
 // Add list of models with configurable sizes
 const SIZE_CONFIGURABLE_MODELS = ['gpt-image-1', 'gpt-4o-image', 'gpt-4o-all']
 
+function getOpenAIChatCachedTokens(usage: unknown): number | undefined {
+  if (!usage || typeof usage !== 'object') {
+    return undefined
+  }
+
+  const promptTokensDetails = (usage as { prompt_tokens_details?: unknown }).prompt_tokens_details
+  const inputTokensDetails = (usage as { input_tokens_details?: unknown }).input_tokens_details
+  const promptCachedTokens =
+    promptTokensDetails && typeof promptTokensDetails === 'object'
+      ? (promptTokensDetails as { cached_tokens?: unknown }).cached_tokens
+      : undefined
+  const inputCachedTokens =
+    inputTokensDetails && typeof inputTokensDetails === 'object'
+      ? (inputTokensDetails as { cached_tokens?: unknown }).cached_tokens
+      : undefined
+  const cachedTokens =
+    typeof promptCachedTokens === 'number' ? promptCachedTokens : inputCachedTokens
+  return typeof cachedTokens === 'number' && Number.isFinite(cachedTokens)
+    ? cachedTokens
+    : undefined
+}
+
 export class OpenAICompatibleProvider extends BaseLLMProvider {
   protected openai!: OpenAI
   protected isNoModelsApi: boolean = false
@@ -976,7 +998,8 @@ export class OpenAICompatibleProvider extends BaseLLMProvider {
             yield createStreamEvent.usage({
               prompt_tokens: result.usage.input_tokens || 0,
               completion_tokens: result.usage.output_tokens || 0,
-              total_tokens: result.usage.total_tokens || 0
+              total_tokens: result.usage.total_tokens || 0,
+              cached_tokens: getOpenAIChatCachedTokens(result.usage)
             })
           }
 
@@ -1142,6 +1165,7 @@ export class OpenAICompatibleProvider extends BaseLLMProvider {
           prompt_tokens: number
           completion_tokens: number
           total_tokens: number
+          cached_tokens?: number
         }
       | undefined = undefined
 
@@ -1156,7 +1180,10 @@ export class OpenAICompatibleProvider extends BaseLLMProvider {
 
       // 1. 处理非内容事件 (如 usage, reasoning, tool_calls)
       if (chunk.usage) {
-        usage = chunk.usage
+        usage = {
+          ...chunk.usage,
+          cached_tokens: getOpenAIChatCachedTokens(chunk.usage)
+        }
       }
 
       // 原生 reasoning 内容处理（直接产出）