Merge pull request #47 from yeahhe365/refactor/pure-frontend-platform

Refactor pure frontend platform architecture

Author: yeahhe365

.gitignore

@@ -32,3 +32,6 @@ Thumbs.db
 
 # Coverage
 coverage/
+
+# Local worktrees
+.worktrees/

README.md

@@ -143,9 +143,11 @@ npm run dev
 除了在界面中手动配置，也可在根目录创建 `.env.local`：
 
 ```bash
-GEMINI_API_KEY=your_api_key_here
+VITE_GEMINI_API_KEY=your_api_key_here
 ```
 
+兼容旧配置：如果你之前使用的是 `GEMINI_API_KEY`，当前版本仍会回退读取，但建议迁移到 `VITE_GEMINI_API_KEY`。
+
 ### 构建部署
 
 ```bash

docs/superpowers/plans/2026-04-08-pure-frontend-platform-refactor.md

@@ -0,0 +1,127 @@
+# Pure Frontend Platform Refactor Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Refactor the app into a safer, adapter-driven pure-frontend architecture while preserving persisted user data and fixing Gemini protocol drift.
+
+**Architecture:** Start with a narrow phase that creates stable seams around Gemini integration, persistence migration, and quality gates. Use that phase to stop protocol breakage and type drift before expanding the refactor into broader feature decomposition.
+
+**Tech Stack:** React 18, TypeScript, Vite, Vitest, Zustand, IndexedDB, `@google/genai`
+
+---
+
+## File Structure
+
+- Create: `src/platform/genai/client.ts`
+- Create: `src/platform/genai/modelCatalog.ts`
+- Create: `src/platform/genai/liveApi.ts`
+- Create: `src/platform/persistence/schema.ts`
+- Create: `src/platform/persistence/migrations.ts`
+- Modify: `src/hooks/live-api/useLiveConnection.ts`
+- Modify: `src/hooks/live-api/useLiveConfig.ts`
+- Modify: `src/hooks/live-api/useLiveMessageProcessing.ts`
+- Modify: `src/services/api/baseApi.ts`
+- Modify: `src/utils/apiUtils.ts`
+- Modify: `src/constants/appConstants.ts`
+- Modify: `src/constants/modelConstants.ts`
+- Modify: `src/utils/modelHelpers.ts`
+- Modify: `src/hooks/useModelCapabilities.ts`
+- Modify: `vite.config.ts`
+- Modify: `package.json`
+- Test: `src/hooks/live-api/__tests__/useLiveMessageProcessing.test.ts`
+- Test: `src/platform/genai/__tests__/liveApi.test.ts`
+- Test: `src/platform/persistence/__tests__/migrations.test.ts`
+- Test: `src/utils/__tests__/apiUtils.test.ts`
+- Test: `src/services/api/__tests__/baseApi.test.ts`
+
+### Task 1: Lock In Live API 3.1 Behavior
+
+**Files:**
+- Create: `src/platform/genai/liveApi.ts`
+- Modify: `src/hooks/live-api/useLiveConnection.ts`
+- Modify: `src/hooks/live-api/useLiveConfig.ts`
+- Modify: `src/hooks/live-api/useLiveMessageProcessing.ts`
+- Test: `src/platform/genai/__tests__/liveApi.test.ts`
+- Test: `src/hooks/live-api/__tests__/useLiveMessageProcessing.test.ts`
+
+- [ ] Write failing tests for Gemini 3.1 text transport selection and multipart server-event parsing.
+- [ ] Run the targeted tests and confirm failure against current `sendClientContent` and first-part-only logic.
+- [ ] Implement a `liveApi` adapter that selects request mode by model descriptor and exposes helper predicates.
+- [ ] Refactor live hooks to use the adapter and iterate over all response parts in each event.
+- [ ] Re-run targeted tests and then the full test suite.
+
+### Task 2: Restore Safe Default Request Configuration
+
+**Files:**
+- Modify: `src/services/api/baseApi.ts`
+- Modify: `src/constants/appConstants.ts`
+- Modify: `src/constants/modelConstants.ts`
+- Modify: `src/services/api/__tests__/baseApi.test.ts`
+
+- [ ] Write failing tests for safety-setting omission when the user has not customized defaults.
+- [ ] Run the targeted base API tests and verify failure.
+- [ ] Change request-building logic so default Gemini behavior is preserved unless the user explicitly overrides safety settings.
+- [ ] Reconcile thinking defaults between model metadata and request configuration for the touched paths.
+- [ ] Re-run targeted tests and the full suite.
+
+### Task 3: Introduce Model Metadata and Remove Stringly Live Decisions
+
+**Files:**
+- Create: `src/platform/genai/modelCatalog.ts`
+- Modify: `src/utils/modelHelpers.ts`
+- Modify: `src/hooks/useModelCapabilities.ts`
+- Modify: `src/constants/modelConstants.ts`
+- Test: `src/utils/__tests__/modelHelpers.test.ts`
+
+- [ ] Write failing tests for structured capability lookups replacing current `includes(...)` checks on touched model paths.
+- [ ] Run model helper tests and confirm failure.
+- [ ] Add a typed `ModelDescriptor` catalog for currently supported and deprecated models in scope.
+- [ ] Switch live and capability logic to use catalog helpers first, leaving legacy helpers only as compatibility wrappers where needed.
+- [ ] Re-run targeted tests and the full suite.
+
+### Task 4: Add Persistence Schema Versioning and Compatibility Entry Point
+
+**Files:**
+- Create: `src/platform/persistence/schema.ts`
+- Create: `src/platform/persistence/migrations.ts`
+- Modify: `src/stores/settingsStore.ts`
+- Modify: `src/utils/db.ts`
+- Test: `src/platform/persistence/__tests__/migrations.test.ts`
+
+- [ ] Write failing tests for version detection, no-op migrations, and future compatibility hooks.
+- [ ] Run migration tests and confirm failure.
+- [ ] Add a minimal schema-version store and migration pipeline without rewriting existing user data yet.
+- [ ] Integrate startup reads through the migration entry point.
+- [ ] Re-run targeted tests and the full suite.
+
+### Task 5: Fix Environment Contract and Quality Gates
+
+**Files:**
+- Modify: `vite.config.ts`
+- Modify: `src/utils/apiUtils.ts`
+- Modify: `package.json`
+- Modify: `README.md`
+- Test: `src/utils/__tests__/apiUtils.test.ts`
+
+- [ ] Write failing tests for environment variable priority and compatibility.
+- [ ] Run the API utils tests and confirm failure if the current contract is inconsistent.
+- [ ] Align build-time and runtime env variable handling so `VITE_GEMINI_API_KEY` behaves exactly as documented.
+- [ ] Make `build` depend on `typecheck` and ensure the touched code path compiles cleanly.
+- [ ] Re-run targeted tests, `npm run typecheck`, `npm run build`, and the full suite.
+
+### Task 6: Expand Quality Gates for the Touched Surface
+
+**Files:**
+- Modify: touched files from Tasks 1-5
+- Test: existing targeted suites
+
+- [ ] Resolve TypeScript and lint issues introduced or exposed in the touched files.
+- [ ] Run `npm run typecheck` and confirm that touched-surface regressions are eliminated.
+- [ ] Run `npm test` and `npm run build` from the worktree.
+- [ ] Summarize remaining repo-wide debt that is intentionally left for later phases.
+
+## Self-Review
+
+- Spec coverage checked: Phase 1 covers Live protocol drift, safety defaults, model metadata foundation, migration scaffolding, env contract, and quality gates.
+- Placeholder scan checked: task outputs are concrete and bounded to the current phase.
+- Type consistency checked: `ModelDescriptor`, migration entry points, and Live adapter names are consistent across tasks.

docs/superpowers/specs/2026-04-08-pure-frontend-platform-refactor-design.md

@@ -0,0 +1,163 @@
+# Pure Frontend Platform Refactor Design
+
+**Date:** 2026-04-08
+
+## Goal
+
+Refactor `All-Model-Chat` into a maintainable pure-frontend platform that preserves existing IndexedDB and localStorage user data, fixes Gemini protocol drift, and creates clear module boundaries for future work.
+
+## Constraints
+
+- Pure frontend remains the primary deployment model.
+- Existing chat history, session settings, saved model lists, shortcuts, and API configuration must migrate automatically and remain usable.
+- Google AI Studio / zero-build mode may be downgraded or removed if it conflicts with maintainability.
+- Large refactors are acceptable if they reduce long-term structural debt.
+
+## Current Problems
+
+- Gemini SDK usage is scattered across hooks, services, helpers, and stores.
+- Live API behavior is mixed across model generations and does not match current Gemini 3.1 semantics.
+- Safety defaults are more permissive than the documented Gemini defaults.
+- Model capability checks depend on string matching instead of structured metadata.
+- `build` can pass while `typecheck` and `lint` fail, so the repo has no trustworthy quality gate.
+- Persistent data uses ad hoc compatibility logic instead of schema-driven migrations.
+
+## Target Architecture
+
+The refactor will reorganize the app into a layered frontend monolith:
+
+- `src/app`
+  Bootstrap, app shell, providers, boundary setup.
+- `src/features/*`
+  User-facing workflows such as `chat`, `live`, `files`, `settings`, `history`.
+- `src/application/*`
+  Use-case orchestration such as `send message`, `resume session`, `migrate persisted data`.
+- `src/domain/*`
+  Business models and rules without React or browser APIs.
+- `src/platform/*`
+  Adapters for Gemini SDK, IndexedDB, browser media APIs, notifications, and storage.
+- `src/shared/*`
+  Shared UI primitives and utilities with no feature ownership.
+
+The first implementation phase will not move every file immediately. It will establish the seams and move the highest-risk integrations first.
+
+## Data Compatibility Design
+
+Persistent data will adopt explicit schema versioning.
+
+- Add a persisted app schema version key.
+- On startup, run `detect -> migrate -> validate -> load`.
+- Migrations must be idempotent and non-destructive.
+- If migration fails, preserve original data and enter a recoverable fallback mode.
+
+### Data to Preserve
+
+- IndexedDB chat sessions
+- Per-session chat settings
+- App settings
+- Saved model preferences
+- Shortcuts
+- API config
+
+### Compatibility Strategy
+
+- Keep current stored shapes readable during the transition.
+- Introduce normalized in-memory models first.
+- Add background rewrite migrations only after normalized read/write paths are stable.
+
+## Gemini Integration Design
+
+Gemini integration will be consolidated behind platform adapters:
+
+- `platform/genai/client.ts`
+- `platform/genai/model-catalog.ts`
+- `platform/genai/chat-api.ts`
+- `platform/genai/live-api.ts`
+- `platform/genai/content-mapper.ts`
+- `platform/genai/safety.ts`
+- `platform/genai/errors.ts`
+
+### Model Metadata
+
+Replace string-based capability checks with a `ModelDescriptor` structure that includes:
+
+- `id`
+- `family`
+- `mode`
+- `supportsThinkingLevel`
+- `supportsThinkingBudget`
+- `supportsLive`
+- `supportsImageGeneration`
+- `supportsImageEditing`
+- `supportsTts`
+- `supportsTranscription`
+- `supportsGoogleSearch`
+- `supportsCodeExecution`
+- `supportsUrlContext`
+- `deprecatedAt`
+- `replacement`
+
+## Live API Design
+
+Live API handling must split by model-generation behavior.
+
+- Gemini 3.1 Live:
+  use `sendRealtimeInput` for conversational text updates and process all parts in each server event.
+- Gemini 2.5 live/native-audio:
+  retain compatible request/response handling where still valid.
+
+The UI should clearly mark direct browser Live connections using long-lived API keys as less safe than ephemeral-token-backed flows.
+
+## Safety Design
+
+Default app behavior should follow Gemini documented defaults unless the user explicitly overrides safety settings.
+
+- Do not eagerly send permissive `BLOCK_NONE` defaults.
+- Only send request-level safety settings after user customization.
+- Keep UI state expressive, but map it to API payloads only when needed.
+
+## Quality Gates
+
+The repo must not rely on `vite build` as the only health check.
+
+- `build` should depend on `typecheck`.
+- CI should run `test`, `typecheck`, `lint`, and `build`.
+- SDK type drift should be isolated behind adapter types instead of leaking into business code.
+
+## Migration Phases
+
+### Phase 1
+
+- Fix Gemini Live protocol drift.
+- Fix Live multipart event parsing.
+- Align safety defaults with documented behavior.
+- Resolve environment variable/documentation mismatch.
+- Establish adapter entry points and migration scaffolding.
+- Make `typecheck` failures actionable in the touched surface.
+
+### Phase 2
+
+- Introduce structured model catalog and capability lookups.
+- Move chat request construction into application/platform boundaries.
+- Begin persistent schema migration support.
+
+### Phase 3
+
+- Break remaining monolithic hooks into feature/application modules.
+- Reduce bundle size with lazy loading for heavyweight features.
+- Remove obsolete zero-build assumptions if they continue to constrain architecture.
+
+## Risks
+
+- Existing uncommitted work in the main workspace may diverge from the refactor branch.
+- Migration bugs could affect stored session integrity if validation is weak.
+- Gemini SDK changes can still break adapter assumptions if the adapter surface is not tightly typed.
+- Live API behavior differs by model family, so regression tests must cover both 2.5 and 3.1 paths.
+
+## Success Criteria
+
+- Existing users can open the refactored app without losing sessions or settings.
+- Gemini 3.1 Live text and multipart responses behave according to current docs.
+- Safety defaults match documented Gemini defaults.
+- `test`, `typecheck`, `lint`, and `build` become meaningful quality gates for the touched code paths.
+- New Gemini integration work can be added through adapters and model metadata instead of string matching across the codebase.

package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
+    "build": "npm run typecheck && vite build",
     "preview": "vite preview",
     "lint": "eslint . --ext .ts,.tsx",
     "lint:fix": "eslint . --ext .ts,.tsx --fix",

src/components/chat/MessageList.tsx

@@ -17,6 +17,7 @@ import { useMessageListScroll } from './message-list/hooks/useMessageListScroll'
 import { MessageListFooter } from './message-list/MessageListFooter';
 import { useChatStore } from '../../stores/chatStore';
 import { useSettingsStore } from '../../stores/settingsStore';
+import type { Translator } from '../../utils/translations';
 
 export interface MessageListProps {
   messages: ChatMessage[];
@@ -63,12 +64,12 @@ export const MessageList: React.FC<MessageListProps> = ({
   const storeTtsMessageId = useChatStore(s => s.ttsMessageId);
   const storeAppSettings = useSettingsStore(s => s.appSettings);
   const storeThemeId = useSettingsStore(s => s.currentTheme.id);
-  const storeScrollContainerRef = useChatStore(s => s.scrollContainerRef);
 
   // Use store values with fallback to props
   const ttsMessageId = storeTtsMessageId ?? propsTtsMessageId;
   const appSettings = storeAppSettings ?? propsAppSettings;
   const themeId = storeThemeId ?? propsThemeId;
+  const translate = t as Translator;
 
   // UI Logic (Modals, Previews, Configuration)
   const {
@@ -93,7 +94,7 @@ export const MessageList: React.FC<MessageListProps> = ({
   // Scroll Logic
   const {
       virtuosoRef,
-      setInternalScrollerRef,
+      handleScrollerRef,
       setAtBottom,
       onRangeChanged,
       scrollToPrevTurn,
@@ -121,7 +122,7 @@ export const MessageList: React.FC<MessageListProps> = ({
           <Virtuoso
             ref={virtuosoRef}
             data={messages}
-            scrollerRef={setInternalScrollerRef}
+            scrollerRef={handleScrollerRef}
             atBottomStateChange={setAtBottom}
             followOutput={false} // Disable auto-scroll to bottom during streaming (we handle it via auto-anchor or user interaction)
             rangeChanged={onRangeChanged}
@@ -155,7 +156,7 @@ export const MessageList: React.FC<MessageListProps> = ({
                         onContinueGeneration={onContinueGeneration}
                         ttsMessageId={ttsMessageId}
                         onSuggestionClick={onFollowUpSuggestionClick}
-                        t={t}
+                        t={translate}
                         appSettings={appSettings}
                         onOpenSidePanel={onOpenSidePanel}
                         onConfigureFile={msg.role === 'user' ? handleConfigureFile : undefined}
@@ -172,7 +173,7 @@ export const MessageList: React.FC<MessageListProps> = ({
             onInsert={onInsert} 
             onTTS={onQuickTTS} 
             containerRef={scrollerRef as any} 
-            t={t} 
+            t={translate} 
         />
 
         <ScrollNavigation 
@@ -188,7 +189,7 @@ export const MessageList: React.FC<MessageListProps> = ({
       <FilePreviewModal 
           file={previewFile} 
           onClose={closeFilePreviewModal}
-          t={t}
+          t={translate}
           onPrev={handlePrevImage}
           onNext={handleNextImage}
           hasPrev={currentImageIndex > 0}
@@ -209,7 +210,7 @@ export const MessageList: React.FC<MessageListProps> = ({
           onClose={() => setConfiguringFile(null)} 
           file={configuringFile?.file || null}
           onSave={handleSaveFileConfig}
-          t={t}
+          t={translate}
           isGemini3={isGemini3}
       />
     </>