mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2025-12-28 05:11:24 +08:00
973f26f9dd
This commit introduces a new data migration service with various IPC channels for migration tasks, including checking if migration is needed, starting the migration, and tracking progress. Additionally, the database architecture section has been added to the documentation, detailing the use of SQLite with Drizzle ORM, migration standards, and JSON field handling. Legacy migration files for ElectronStore and Redux have been removed as they are now deprecated.
137 lines
5.1 KiB
Markdown
137 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Development Commands
|
|
|
|
### Environment Setup
|
|
|
|
- **Prerequisites**: Node.js v22.x.x or higher, Yarn 4.9.1
|
|
- **Setup Yarn**: `corepack enable && corepack prepare yarn@4.9.1 --activate`
|
|
- **Install Dependencies**: `yarn install`
|
|
|
|
### Development
|
|
|
|
- **Start Development**: `yarn dev` - Runs Electron app in development mode
|
|
- **Debug Mode**: `yarn debug` - Starts with debugging enabled, use chrome://inspect
|
|
|
|
### Testing & Quality
|
|
|
|
- **Run Tests**: `yarn test` - Runs all tests (Vitest)
|
|
- **Run E2E Tests**: `yarn test:e2e` - Playwright end-to-end tests
|
|
- **Type Check**: `yarn typecheck` - Checks TypeScript for both node and web
|
|
- **Lint**: `yarn lint` - ESLint with auto-fix
|
|
- **Format**: `yarn format` - Prettier formatting
|
|
|
|
### Build & Release
|
|
|
|
- **Build**: `yarn build` - Builds for production (includes typecheck)
|
|
- **Platform-specific builds**:
|
|
- Windows: `yarn build:win`
|
|
- macOS: `yarn build:mac`
|
|
- Linux: `yarn build:linux`
|
|
|
|
## Architecture Overview
|
|
|
|
### Electron Multi-Process Architecture
|
|
|
|
- **Main Process** (`src/main/`): Node.js backend handling system integration, file operations, and services
|
|
- **Renderer Process** (`src/renderer/`): React-based UI running in Chromium
|
|
- **Preload Scripts** (`src/preload/`): Secure bridge between main and renderer processes
|
|
|
|
### Key Architectural Components
|
|
|
|
#### Main Process Services (`src/main/services/`)
|
|
|
|
- **MCPService**: Model Context Protocol server management
|
|
- **KnowledgeService**: Document processing and knowledge base management
|
|
- **FileStorage/S3Storage/WebDav**: Multiple storage backends
|
|
- **WindowService**: Multi-window management (main, mini, selection windows)
|
|
- **ProxyManager**: Network proxy handling
|
|
- **SearchService**: Full-text search capabilities
|
|
|
|
#### AI Core (`src/renderer/src/aiCore/`)
|
|
|
|
- **Middleware System**: Composable pipeline for AI request processing
|
|
- **Client Factory**: Supports multiple AI providers (OpenAI, Anthropic, Gemini, etc.)
|
|
- **Stream Processing**: Real-time response handling
|
|
|
|
#### State Management (`src/renderer/src/store/`)
|
|
|
|
- **Redux Toolkit**: Centralized state management
|
|
- **Persistent Storage**: Redux-persist for data persistence
|
|
- **Thunks**: Async actions for complex operations
|
|
|
|
#### Knowledge Management
|
|
|
|
- **Embeddings**: Vector search with multiple providers (OpenAI, Voyage, etc.)
|
|
- **OCR**: Document text extraction (system OCR, Doc2x, Mineru)
|
|
- **Preprocessing**: Document preparation pipeline
|
|
- **Loaders**: Support for various file formats (PDF, DOCX, EPUB, etc.)
|
|
|
|
### Build System
|
|
|
|
- **Electron-Vite**: Development and build tooling (v4.0.0)
|
|
- **Rolldown-Vite**: Using experimental rolldown-vite instead of standard vite
|
|
- **Workspaces**: Monorepo structure with `packages/` directory
|
|
- **Multiple Entry Points**: Main app, mini window, selection toolbar
|
|
- **Styled Components**: CSS-in-JS styling with SWC optimization
|
|
|
|
### Testing Strategy
|
|
|
|
- **Vitest**: Unit and integration testing
|
|
- **Playwright**: End-to-end testing
|
|
- **Component Testing**: React Testing Library
|
|
- **Coverage**: Available via `yarn test:coverage`
|
|
|
|
### Key Patterns
|
|
|
|
- **IPC Communication**: Secure main-renderer communication via preload scripts
|
|
- **Service Layer**: Clear separation between UI and business logic
|
|
- **Plugin Architecture**: Extensible via MCP servers and middleware
|
|
- **Multi-language Support**: i18n with dynamic loading
|
|
- **Theme System**: Light/dark themes with custom CSS variables
|
|
|
|
### Database Architecture
|
|
|
|
- **Database**: SQLite (`cherrystudio.sqlite`) + libsql driver
|
|
- **ORM**: Drizzle ORM with comprehensive migration system
|
|
- **Schemas**: Located in `src/main/data/db/schemas/` directory
|
|
|
|
#### Database Standards
|
|
|
|
- **Table Naming**: Use singular form with snake_case (e.g., `topic`, `message`, `app_state`)
|
|
- **Schema Exports**: Export using `xxxTable` pattern (e.g., `topicTable`, `appStateTable`)
|
|
- **Field Definition**: Drizzle auto-infers field names, no need to add default field names
|
|
- **JSON Fields**: For JSON support, add `{ mode: 'json' }`, refer to `preference.ts` table definition
|
|
- **JSON Serialization**: For JSON fields, no need to manually serialize/deserialize when reading/writing to database, Drizzle handles this automatically
|
|
- **Timestamps**: Use existing `crudTimestamps` utility
|
|
- **Migrations**: Generate via `yarn run migrations:generate`
|
|
|
|
## Logging Standards
|
|
|
|
### Usage
|
|
|
|
```typescript
|
|
// Main process
|
|
import { loggerService } from '@logger'
|
|
const logger = loggerService.withContext('moduleName')
|
|
|
|
// Renderer process (set window source first)
|
|
loggerService.initWindowSource('windowName')
|
|
const logger = loggerService.withContext('moduleName')
|
|
|
|
// Logging
|
|
logger.info('message', CONTEXT)
|
|
logger.error('message', new Error('error'), CONTEXT)
|
|
```
|
|
|
|
### Log Levels (highest to lowest)
|
|
|
|
- `error` - Critical errors causing crash/unusable functionality
|
|
- `warn` - Potential issues that don't affect core functionality
|
|
- `info` - Application lifecycle and key user actions
|
|
- `verbose` - Detailed flow information for feature tracing
|
|
- `debug` - Development diagnostic info (not for production)
|
|
- `silly` - Extreme debugging, low-level information
|