@lobehub/chat 1.114.6 → 1.116.0

package/.cursor/rules/add-provider-doc.mdc

@@ -0,0 +1,183 @@
+---
+description: Complete guide for adding a new AI provider documentation to LobeChat
+alwaysApply: false
+---
+
+# Adding New AI Provider Documentation
+
+This document provides a step-by-step guide for adding documentation for a new AI provider to LobeChat, based on the complete workflow used for adding providers like BFL (Black Forest Labs) and FAL.
+
+## Overview
+
+Adding a new provider requires creating both user-facing documentation and technical configuration files. The process involves:
+
+1. Creating usage documentation (EN + CN)
+2. Adding environment variable documentation (EN + CN)
+3. Updating Docker configuration files
+4. Updating .env.example file
+5. Preparing image resources
+
+## Step 1: Create Provider Usage Documentation
+
+Create user-facing documentation that explains how to use the new provider.
+
+### Required Files
+
+Create both English and Chinese versions:
+- `docs/usage/providers/{provider-name}.mdx` (English)
+- `docs/usage/providers/{provider-name}.zh-CN.mdx` (Chinese)
+
+### Documentation Structure
+
+Follow the structure and format used in existing provider documentation. For reference, see:
+- `docs/usage/providers/fal.mdx` (English template)
+- `docs/usage/providers/fal.zh-CN.mdx` (Chinese template)
+
+### Key Requirements
+
+- **Images**: Prepare 5-6 screenshots showing the process
+- **Cover Image**: Create or obtain a cover image for the provider
+- **Accurate URLs**: Use real registration and dashboard URLs
+- **Service Type**: Specify whether it's for image generation, text generation, etc.
+- **Pricing Warning**: Include pricing information callout
+
+### Important Notes
+
+- **🔒 API Key Security**: Never include real API keys in documentation. Always use placeholder format (e.g., `bfl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
+- **🖼️ Image Hosting**: Use LobeHub's CDN for all images: `hub-apac-1.lobeobjects.space`
+
+## Step 2: Update Environment Variables Documentation
+
+Add the new provider's environment variables to the self-hosting documentation.
+
+### Files to Update
+
+- `docs/self-hosting/environment-variables/model-provider.mdx` (English)
+- `docs/self-hosting/environment-variables/model-provider.zh-CN.mdx` (Chinese)
+
+### Content to Add
+
+Add two sections for each provider:
+
+```markdown
+### `{PROVIDER}_API_KEY`
+
+- Type: Required
+- Description: This is the API key you applied for in the {Provider Name} service.
+- Default: -
+- Example: `{api-key-format-example}`
+
+### `{PROVIDER}_MODEL_LIST`
+
+- Type: Optional
+- Description: Used to control the {Provider Name} model list. Use `+` to add a model, `-` to hide a model, and `model_name=display_name` to customize the display name of a model. Separate multiple entries with commas. The definition syntax follows the same rules as other providers' model lists.
+- Default: `-`
+- Example: `-all,+{model-id-1},+{model-id-2}={display-name}`
+
+The above example disables all models first, then enables `{model-id-1}` and `{model-id-2}` (displayed as `{display-name}`).
+
+[model-list]: /docs/self-hosting/advanced/model-list
+```
+
+### Important Notes
+
+- **API Key Format**: Use proper UUID format for examples (e.g., `12345678-1234-1234-1234-123456789abc`)
+- **Real Model IDs**: Use actual model IDs from the codebase, not placeholders
+- **Consistent Naming**: Follow the pattern `{PROVIDER}_API_KEY` and `{PROVIDER}_MODEL_LIST`
+
+## Step 3: Update Docker Configuration Files
+
+Add environment variables to all Docker configuration files to ensure the provider works in containerized deployments.
+
+### Files to Update
+
+All Dockerfile variants must be updated:
+- `Dockerfile`
+- `Dockerfile.database`
+- `Dockerfile.pglite`
+
+### Changes Required
+
+Add the new provider's environment variables at the **end** of the ENV section, just before the final line:
+
+```dockerfile
+# Previous providers...
+    # 302.AI
+    AI302_API_KEY="" AI302_MODEL_LIST="" \
+    # {New Provider 1}
+    {PROVIDER1}_API_KEY="" {PROVIDER1}_MODEL_LIST="" \
+    # {New Provider 2}
+    {PROVIDER2}_API_KEY="" {PROVIDER2}_MODEL_LIST=""
+```
+
+### Important Rules
+
+- **Position**: Add new providers at the **end** of the list
+- **Ordering**: When adding multiple providers, use alphabetical order (e.g., FAL before BFL)
+- **Consistency**: Maintain identical ordering across all Dockerfile variants
+- **Format**: Follow the pattern `{PROVIDER}_API_KEY="" {PROVIDER}_MODEL_LIST="" \`
+
+## Step 4: Update .env.example File
+
+Add example configuration entries to help users understand how to configure the provider locally.
+
+### File to Update
+
+- `.env.example`
+
+### Content to Add
+
+Add new sections before the "Market Service" section:
+
+```bash
+### {Provider Name} ###
+
+# {PROVIDER}_API_KEY={provider-prefix}-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### Format Guidelines
+
+- **Section Header**: Use `### {Provider Name} ###` format
+- **Commented Example**: Use `#` to comment out the example
+- **Key Format**: Use appropriate prefix for the provider (e.g., `bfl-`, `fal-`, `sk-`)
+- **Position**: Add before the Market Service section
+- **Spacing**: Maintain consistent spacing with existing entries
+
+## Step 5: Image Resources
+
+Prepare all necessary image resources for the documentation.
+
+### Required Images
+
+1. **Cover Image**: Provider logo or branded image
+2. **API Dashboard Screenshots**: 3-4 screenshots showing API key creation process
+3. **LobeChat Configuration Screenshots**: 2-3 screenshots showing provider setup in LobeChat
+
+### Image Guidelines
+
+- **Quality**: Use high-resolution screenshots
+- **Consistency**: Maintain consistent styling across all screenshots
+- **Privacy**: Remove or blur any sensitive information
+- **Format**: Use PNG format for screenshots
+- **Hosting**: Use LobeHub's CDN (`hub-apac-1.lobeobjects.space`) for all images
+
+## Checklist
+
+Before submitting your provider documentation:
+
+- [ ] Created both English and Chinese usage documentation
+- [ ] Added environment variable documentation (EN + CN)
+- [ ] Updated all 3 Dockerfile variants with consistent ordering
+- [ ] Updated .env.example with proper key format
+- [ ] Prepared all required screenshots and images
+- [ ] Used actual model IDs from the codebase
+- [ ] Verified no real API keys are included in documentation
+- [ ] Used LobeHub CDN for all image hosting
+- [ ] Tested the documentation for clarity and accuracy
+
+## Reference
+
+This guide was created based on the implementation of BFL (Black Forest Labs) provider documentation. For a complete example, refer to:
+- Commits: `d2da03e1a` (documentation) and `6a2e95868` (environment variables)
+- Files: `docs/usage/providers/bfl.mdx`, `docs/usage/providers/bfl.zh-CN.mdx`
+- PR: Current branch `tj/feat/bfl-docs`

package/.cursor/rules/project-introduce.mdc

@@ -10,7 +10,7 @@ Emoji logo: 🤯
 
 ## Project Technologies Stack
 
-read [package.json](mdc:package.json) to know all npm packages you can use. read [folder-structure.mdx](mdc:docs/development/basic/folder-structure.mdx) to learn project structure.
+read [package.json](mdc:package.json) to know all npm packages you can use.
 
 The project uses the following technologies:
 
@@ -42,17 +42,3 @@ The project uses the following technologies:
 - Cursor AI for code editing and AI coding assistance
 
 Note: All tools and libraries used are the latest versions. The application only needs to be compatible with the latest browsers;
-
-## Often used npm scripts and commands
-
-```bash
-# !: don't  any build script to check weather code can work after modify
-# type check
-bun run type-check
-
-# install dependencies
-pnpm install
-
-# run tests
-npx vitest run --config vitest.config.ts '[file-path-pattern]'
-```

package/.cursor/rules/project-structure.mdc

@@ -0,0 +1,227 @@
+---
+description: Project directory structure overview
+alwaysApply: false
+---
+
+# LobeChat Project Structure
+
+## Directory Structure
+
+note: some files are not shown for simplicity.
+
+```plaintext
+lobe-chat/
+├── apps/                           # Applications directory
+│   └── desktop/                    # Electron desktop application
+│       ├── src/                    # Desktop app source code
+│       └── resources/              # Desktop app resources
+├── docs/                           # Project documentation
+│   ├── development/                # Development docs
+│   ├── self-hosting/               # Self-hosting docs
+│   └── usage/                      # Usage guides
+├── locales/                        # Internationalization files
+│   ├── en-US/                      # English
+│   └── zh-CN/                      # Simplified Chinese
+├── packages/                       # Monorepo packages directory
+│   ├── const/                      # Constants definition package
+│   ├── database/                   # Database related package
+│   ├── model-runtime/              # AI model runtime package
+│   ├── types/                      # TypeScript type definitions
+│   ├── utils/                      # Utility functions package
+│   ├── file-loaders/               # File processing packages
+│   ├── prompts/                    # AI prompt management
+│   └── web-crawler/                # Web crawling functionality
+├── public/                         # Static assets
+│   ├── icons/                      # Application icons
+│   ├── images/                     # Image resources
+│   └── screenshots/                # Application screenshots
+├── scripts/                        # Build and tool scripts
+├── src/                            # Main application source code (see below)
+├── tests/                          # Test configuration
+├── .cursor/                        # Cursor AI configuration
+├── docker-compose/                 # Docker configuration
+├── package.json                    # Project dependencies
+├── pnpm-workspace.yaml            # pnpm monorepo configuration
+├── next.config.ts                  # Next.js configuration
+├── drizzle.config.ts              # Drizzle ORM configuration
+└── tsconfig.json                   # TypeScript configuration
+```
+
+## Core Source Directory (`src/`)
+
+```plaintext
+src/
+├── app/                            # Next.js App Router routes
+│   ├── (backend)/                  # Backend API routes
+│   │   ├── api/                    # REST API endpoints
+│   │   │   ├── auth/               # Authentication endpoints
+│   │   │   └── webhooks/           # Webhook handlers for various auth providers
+│   │   ├── middleware/             # Request middleware
+│   │   ├── oidc/                   # OpenID Connect endpoints
+│   │   ├── trpc/                   # tRPC API routes
+│   │   │   ├── async/              # Async tRPC endpoints
+│   │   │   ├── edge/               # Edge runtime endpoints
+│   │   │   ├── lambda/             # Lambda runtime endpoints
+│   │   │   └── tools/              # Tools-specific endpoints
+│   │   └── webapi/                 # Web API endpoints
+│   │       ├── chat/               # Chat-related APIs for various providers
+│   │       ├── models/             # Model management APIs
+│   │       ├── plugin/             # Plugin system APIs
+│   │       ├── stt/                # Speech-to-text APIs
+│   │       ├── text-to-image/      # Image generation APIs
+│   │       └── tts/                # Text-to-speech APIs
+│   ├── [variants]/                 # Page route variants
+│   │   ├── (main)/                 # Main application routes
+│   │   │   ├── chat/               # Chat interface and workspace
+│   │   │   ├── discover/           # Discover page (assistants, models, providers)
+│   │   │   ├── files/              # File management interface
+│   │   │   ├── image/              # Image generation interface
+│   │   │   ├── profile/            # User profile and stats
+│   │   │   ├── repos/              # Knowledge base repositories
+│   │   │   └── settings/           # Application settings
+│   │   └── @modal/                 # Modal routes
+│   └── manifest.ts                 # PWA configuration
+├── components/                     # Global shared components
+│   ├── Analytics/                  # Analytics tracking components
+│   ├── Error/                      # Error handling components
+│   └── Loading/                    # Loading state components
+├── config/                         # Application configuration
+│   ├── aiModels/                   # AI model configurations
+│   └── modelProviders/             # Model provider configurations
+├── features/                       # Feature components (UI Layer)
+│   ├── AgentSetting/               # Agent configuration and management
+│   ├── ChatInput/                  # Chat input with file upload and tools
+│   ├── Conversation/               # Message display and interaction
+│   ├── FileManager/                # File upload and knowledge base
+│   └── PluginStore/                # Plugin marketplace and management
+├── hooks/                          # Custom React hooks
+├── layout/                         # Global layout components
+│   ├── AuthProvider/               # Authentication provider
+│   └── GlobalProvider/             # Global state provider
+├── libs/                           # External library integrations
+│   ├── analytics/                  # Analytics services integration
+│   ├── next-auth/                  # NextAuth.js configuration
+│   └── oidc-provider/              # OIDC provider implementation
+├── locales/                        # Internationalization resources
+│   └── default/                    # Default language definitions
+├── migrations/                     # Client-side data migrations
+├── server/                         # Server-side code
+│   ├── modules/                    # Server modules
+│   ├── routers/                    # tRPC routers
+│   └── services/                   # Server services
+├── services/                       # Client service layer
+│   ├── aiModel/                    # AI model services
+│   ├── session/                    # Session services
+│   └── message/                    # Message services
+├── store/                          # Zustand state management
+│   ├── agent/                      # Agent state
+│   ├── chat/                       # Chat state
+│   └── user/                       # User state
+├── styles/                         # Global styles
+├── tools/                          # Built-in tool system
+│   ├── artifacts/                  # Code artifacts and preview
+│   └── web-browsing/               # Web search and browsing
+├── types/                          # TypeScript type definitions
+└── utils/                          # Utility functions
+    ├── client/                     # Client-side utilities
+    └── server/                     # Server-side utilities
+```
+
+## Key Monorepo Packages
+
+```plaintext
+packages/
+├── const/                          # Global constants and configurations
+├── database/                       # Database schemas and models
+│   ├── src/models/                 # Data models (CRUD operations)
+│   ├── src/schemas/                # Drizzle database schemas
+│   ├── src/repositories/           # Complex query layer
+│   └── migrations/                 # Database migration files
+├── model-runtime/                  # AI model runtime
+│   └── src/
+│       ├── openai/                 # OpenAI provider integration
+│       ├── anthropic/              # Anthropic provider integration
+│       ├── google/                 # Google AI provider integration
+│       ├── ollama/                 # Ollama local model integration
+│       ├── types/                  # Runtime type definitions
+│       └── utils/                  # Runtime utilities
+├── types/                          # Shared TypeScript type definitions
+│   └── src/
+│       ├── agent/                  # Agent-related types
+│       ├── message/                # Message and chat types
+│       ├── user/                   # User and session types
+│       └── tool/                   # Tool and plugin types
+├── utils/                          # Shared utility functions
+│   └── src/
+│       ├── client/                 # Client-side utilities
+│       ├── server/                 # Server-side utilities
+│       ├── fetch/                  # HTTP request utilities
+│       └── tokenizer/              # Token counting utilities
+├── file-loaders/                   # File loaders (PDF, DOCX, etc.)
+├── prompts/                        # AI prompt management
+└── web-crawler/                    # Web crawling functionality
+```
+
+## Architecture Layers
+
+### 1. **Presentation Layer**
+
+- Business-specific feature components and reusable UI components
+- Global layout providers and responsive design wrappers
+
+### 2. **State Management Layer**
+
+- Zustand-based client state with domain-specific slices
+- Actions and selectors for predictable state updates
+
+### 3. **Client Service Layer**
+
+- Environment-adaptive services (local Model vs remote tRPC)
+- Dual implementation pattern for multi-runtime compatibility
+
+### 4. **API Interface Layer**
+
+- Type-safe tRPC routers organized by runtime environment
+- Request routing and validation
+
+### 5. **Server Service Layer**
+
+- Platform-agnostic business logic with implementation abstractions
+- Reusable, testable service composition
+
+### 6. **Data Access Layer**
+
+- **Repository**: Complex queries, joins, and transaction management
+- **Model**: Basic CRUD operations and single-table queries
+- **Schema**: Drizzle ORM definitions and migration management
+
+### 7. **Integration & Extensions**
+
+- **External**: Third-party service integrations and library wrappers
+- **Built-in**: AI runtime, tool system, file processing, and web crawling
+
+## Data Flow Architecture
+
+### Unified Flow Pattern
+
+```
+UI Layer → State Management → Client Service → [Environment Branch] → Database
+   ↓              ↓               ↓                    ↓                ↓
+ React         Zustand     Environment         Local/Remote        PGLite/
+Components      Store      Adaptation            Routing          PostgreSQL
+```
+
+### Environment-Specific Routing
+
+| Mode            | UI       | Service Route          | Database            |
+| --------------- | -------- | ---------------------- | ------------------- |
+| **Browser/PWA** | React    | Direct Model Access    | PGLite (Local)      |
+| **Server**      | React    | tRPC → Server Services | PostgreSQL (Remote) |
+| **Desktop**     | Electron | tRPC → Local Node.js   | PGLite/PostgreSQL\* |
+
+_\*Depends on cloud sync configuration_
+
+### Key Characteristics
+
+- **Type Safety**: End-to-end type safety via tRPC and Drizzle ORM
+- **Local/Remote Dual Mode**: PGLite enables user data ownership and local control

package/.cursor/rules/testing-guide/db-model-test.mdc

@@ -5,6 +5,8 @@ alwaysApply: false
 
 ## 🗃️ 数据库 Model 测试指南
 
+测试 `packages/database` 下的数据库 Model 层。
+
 ### 测试环境选择 💡
 
 数据库 Model 层通过环境变量控制数据库类型，在两种测试环境下有不同的数据库后端：客户端环境 (PGLite) 和 服务端环境 (PostgreSQL)
@@ -17,10 +19,10 @@ alwaysApply: false
 
 ```bash
 # 1. 先在客户端环境测试（快速验证）
-npx vitest run --config vitest.config.ts src/database/models/__tests__/myModel.test.ts
+cd packages/database && TEST_SERVER_DB=0 bunx vitest run --silent='passed-only' src/database/models/__tests__/myModel.test.ts
 
-# 2. 再在服务端环境测试（兼容性验证）
-npx vitest run --config vitest.config.server.ts src/database/models/__tests__/myModel.test.ts
+# 2. 再在服务端环境测试（兼容性验证）, 需要设置环境变量 `TEST_SERVER_DB=1`
+cd packages/database && TEST_SERVER_DB=1 bunx vitest run --silent='passed-only' src/database/models/__tests__/myModel.test.ts #
 ```
 
 ### 创建新 Model 测试的最佳实践 📋