Skip to content

Commit 9fb4b0d

Browse files
arvinxxcanisminor1990
arvinxx
and
canisminor1990
authored
♻️ refactor: add badge and improve document (#8528)
* update readme * 📝 docs: Update readme * 💄 style: Update PlanIcon * improve tooltip placement * improve tray --------- Co-authored-by: canisminor1990 <i@canisminor.cc>
1 parent caffbbd commit 9fb4b0d

File tree

42 files changed

+1772
-179
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+1772
-179
lines changed

‎apps/desktop/README.md

Lines changed: 322 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,353 @@
1-
# LobeHub Desktop Application
1+
# 🤯 LobeHub Desktop Application
22

3-
LobeHub Desktop 是 [LobeChat](https://github.com/lobehub/lobe-chat) 的跨平台桌面应用程序，使用 Electron 构建，提供了更加原生的桌面体验和功能。
3+
LobeHub Desktop is a cross-platform desktop application for [LobeChat](https://github.com/lobehub/lobe-chat), built with Electron, providing a more native desktop experience and functionality.
44

5-
## 功能特点
5+
## ✨ Features
66

7-
- **跨平台支持**：支持 macOS (Intel/Apple Silicon)、Windows 和 Linux 系统
8-
- **自动更新**：内置更新机制，确保您始终使用最新版本
9-
- **多语言支持**：完整的国际化支持，包括中文、英文等多种语言
10-
- **原生集成**：与操作系统深度集成，提供原生菜单、快捷键和通知
11-
- **安全可靠**：macOS 版本经过公证，确保安全性
12-
- **多渠道发布**：提供稳定版、测试版和每日构建版本
7+
- **🌍 Cross-platform Support**: Supports macOS (Intel/Apple Silicon), Windows, and Linux systems
8+
- **🔄 Auto Updates**: Built-in update mechanism ensures you always have the latest version
9+
- **🌐 Multi-language Support**: Complete i18n support for 18+ languages with lazy loading
10+
- **🎨 Native Integration**: Deep OS integration with native menus, shortcuts, and notifications
11+
- **🔒 Secure & Reliable**: macOS notarized, encrypted token storage, secure OAuth flow
12+
- **📦 Multiple Release Channels**: Stable, beta, and nightly build versions
13+
- **⚡ Advanced Window Management**: Multi-window architecture with theme synchronization
14+
- **🔗 Remote Server Sync**: Secure data synchronization with remote LobeChat instances
15+
- **🎯 Developer Tools**: Built-in development panel and comprehensive debugging tools
1316

14-
## 开发环境设置
17+
## 🚀 Development Setup
1518

16-
### 前提条件
19+
### Prerequisites
1720

18-
- Node.js 22+
19-
- pnpm 10+
21+
- **Node.js** 22+
22+
- **pnpm** 10+
23+
- **Electron** compatible development environment
2024

21-
### 安装依赖
25+
### Quick Start
2226

2327
```bash
28+
# Install dependencies
2429
pnpm install-isolated
25-
```
2630

27-
### 配置环境变量
31+
# Start development server
32+
pnpm electron:dev
33+
34+
# Type checking
35+
pnpm typecheck
2836

29-
复制 `.env.desktop` 到 `.env`。
37+
# Run tests
38+
pnpm test
39+
```
3040

31-
> [!WARNING]
32-
> 注意提前备份好 `.env` 文件，避免丢失配置。
41+
### Environment Configuration
3342

34-
### 开发模式运行
43+
Copy `.env.desktop` to `.env` and configure as needed:
3544

3645
```bash
37-
pnpm electron:dev
46+
cp .env.desktop .env
3847
```
3948

40-
### 构建应用
49+
> \[!WARNING]
50+
> Backup your `.env` file before making changes to avoid losing configurations.
51+
52+
### Build Commands
4153

42-
构建所有平台：
54+
| Command | Description |
55+
| ------------------ | --------------------------------------- |
56+
| `pnpm build` | Build for all platforms |
57+
| `pnpm build:mac` | Build for macOS (Intel + Apple Silicon) |
58+
| `pnpm build:win` | Build for Windows |
59+
| `pnpm build:linux` | Build for Linux |
60+
| `pnpm build-local` | Local development build |
61+
62+
### Development Workflow
4363

4464
```bash
45-
pnpm build
65+
# 1. Development
66+
pnpm electron:dev # Start with hot reload
67+
68+
# 2. Code Quality
69+
pnpm lint # ESLint checking
70+
pnpm format # Prettier formatting
71+
pnpm typecheck # TypeScript validation
72+
73+
# 3. Testing
74+
pnpm test # Run Vitest tests
75+
76+
# 4. Build & Package
77+
pnpm build # Production build
78+
pnpm build-local # Local testing build
4679
```
4780

48-
构建特定平台：
81+
## 🎯 Release Channels
82+
83+
| Channel | Description | Stability | Auto-Updates |
84+
| ----------- | -------------------------------- | --------- | ------------ |
85+
| **Stable** | Thoroughly tested releases | 🟢 High | ✅ Yes |
86+
| **Beta** | Pre-release with new features | 🟡 Medium | ✅ Yes |
87+
| **Nightly** | Daily builds with latest changes | 🟠 Low | ✅ Yes |
88+
89+
## 🛠 Technology Stack
90+
91+
### Core Framework
92+
93+
- **Electron** `37.1.0` - Cross-platform desktop framework
94+
- **Node.js** `22+` - Backend runtime
95+
- **TypeScript** `5.7+` - Type-safe development
96+
- **Vite** `6.2+` - Build tooling
97+
98+
### Architecture & Patterns
99+
100+
- **Dependency Injection** - IoC container with decorator-based registration
101+
- **Event-Driven Architecture** - IPC communication between processes
102+
- **Module Federation** - Dynamic controller and service loading
103+
- **Observer Pattern** - State management and UI synchronization
104+
105+
### Development Tools
106+
107+
- **Vitest** - Unit testing framework
108+
- **ESLint** - Code linting
109+
- **Prettier** - Code formatting
110+
- **electron-builder** - Application packaging
111+
- **electron-updater** - Auto-update mechanism
112+
113+
### Security & Storage
114+
115+
- **Electron Safe Storage** - Encrypted token storage
116+
- **OAuth 2.0 + PKCE** - Secure authentication flow
117+
- **electron-store** - Persistent configuration
118+
- **Custom Protocol Handler** - Secure callback handling
119+
120+
## 🏗 Architecture
121+
122+
The desktop application uses a sophisticated dependency injection and event-driven architecture:
123+
124+
### 📁 Core Structure
125+
126+
```
127+
src/main/core/
128+
├── App.ts # 🎯 Main application orchestrator
129+
├── IoCContainer.ts # 🔌 Dependency injection container
130+
├── window/ # 🪟 Window management modules
131+
│ ├── WindowThemeManager.ts # 🎨 Theme synchronization
132+
│ ├── WindowPositionManager.ts # 📐 Position persistence
133+
│ ├── WindowErrorHandler.ts # ⚠️ Error boundaries
134+
│ └── WindowConfigBuilder.ts # ⚙️ Configuration builder
135+
├── browser/ # 🌐 Browser management modules
136+
│ ├── Browser.ts # 🪟 Individual window instances
137+
│ └── BrowserManager.ts # 👥 Multi-window coordinator
138+
├── ui/ # 🎨 UI system modules
139+
│ ├── Tray.ts # 📍 System tray integration
140+
│ ├── TrayManager.ts # 🔧 Tray management
141+
│ ├── MenuManager.ts # 📋 Native menu system
142+
│ └── ShortcutManager.ts # ⌨️ Global shortcuts
143+
└── infrastructure/ # 🔧 Infrastructure services
144+
├── StoreManager.ts # 💾 Configuration storage
145+
├── I18nManager.ts # 🌍 Internationalization
146+
├── UpdaterManager.ts # 📦 Auto-update system
147+
└── StaticFileServerManager.ts # 🗂️ Local file serving
148+
```
149+
150+
### 🔄 Application Lifecycle
151+
152+
The `App.ts` class orchestrates the entire application lifecycle through key phases:
153+
154+
#### 1. 🚀 Initialization Phase
155+
156+
- **System Information Logging** - Captures OS, CPU, RAM, and locale details
157+
- **Store Manager Setup** - Initializes persistent configuration storage
158+
- **Dynamic Module Loading** - Auto-discovers controllers and services via glob imports
159+
- **IPC Event Registration** - Sets up inter-process communication channels
160+
161+
#### 2. 🏃 Bootstrap Phase
162+
163+
- **Single Instance Check** - Ensures only one application instance runs
164+
- **IPC Server Launch** - Starts the communication server
165+
- **Core Manager Initialization** - Sequential initialization of all managers:
166+
- 🌍 I18n for internationalization
167+
- 📋 Menu system for native menus
168+
- 🗂️ Static file server for local assets
169+
- ⌨️ Global shortcuts registration
170+
- 🪟 Browser window management
171+
- 📍 System tray (Windows only)
172+
- 📦 Auto-updater system
173+
174+
### 🔧 Core Components Deep Dive
175+
176+
#### 🌐 Browser Management System
177+
178+
- **Multi-Window Architecture** - Supports chat, settings, and devtools windows
179+
- **Window State Management** - Handles positioning, theming, and lifecycle
180+
- **WebContents Mapping** - Bidirectional mapping between WebContents and identifiers
181+
- **Event Broadcasting** - Centralized event distribution to all or specific windows
182+
183+
#### 🔌 Dependency Injection & Event System
184+
185+
- **IoC Container** - WeakMap-based container for decorated controller methods
186+
- **Decorator Registration** - `@ipcClientEvent` and `@ipcServerEvent` decorators
187+
- **Automatic Event Mapping** - Events registered during controller loading
188+
- **Service Locator** - Type-safe service and controller retrieval
189+
190+
#### 🪟 Window Management
191+
192+
- **Theme-Aware Windows** - Automatic adaptation to system dark/light mode
193+
- **Platform-Specific Styling** - Windows title bar and overlay customization
194+
- **Position Persistence** - Save and restore window positions across sessions
195+
- **Error Boundaries** - Centralized error handling for window operations
196+
197+
#### 🔧 Infrastructure Services
198+
199+
##### 🌍 I18n Manager
200+
201+
- **18+ Language Support** with lazy loading and namespace organization
202+
- **System Integration** with Electron's locale detection
203+
- **Dynamic UI Refresh** on language changes
204+
- **Resource Management** with efficient loading strategies
205+
206+
##### 📦 Update Manager
207+
208+
- **Multi-Channel Support** (stable, beta, nightly) with configurable intervals
209+
- **Background Downloads** with progress tracking and user notifications
210+
- **Rollback Protection** with error handling and recovery mechanisms
211+
- **Channel Management** with automatic channel switching
212+
213+
##### 💾 Store Manager
214+
215+
- **Type-Safe Storage** using electron-store with TypeScript interfaces
216+
- **Encrypted Secrets** via Electron's Safe Storage API
217+
- **Configuration Validation** with default value management
218+
- **File System Integration** with automatic directory creation
219+
220+
##### 🗂️ Static File Server
221+
222+
- **Local HTTP Server** for serving application assets and user files
223+
- **Security Controls** with request filtering and access validation
224+
- **File Management** with upload, download, and deletion capabilities
225+
- **Path Resolution** with intelligent routing between storage locations
226+
227+
#### 🎨 UI System Integration
228+
229+
- **Global Shortcuts** - Platform-aware keyboard shortcut registration with conflict detection
230+
- **System Tray** - Native integration with context menus and notifications
231+
- **Native Menus** - Platform-specific application and context menus with i18n
232+
- **Theme Synchronization** - Automatic theme updates across all UI components
233+
234+
### 🏛 Controller & Service Architecture
235+
236+
#### 🎮 Controller Pattern
237+
238+
- **IPC Event Handling** - Processes events from renderer with decorator-based registration
239+
- **Lifecycle Hooks** - `beforeAppReady` and `afterAppReady` for initialization phases
240+
- **Type-Safe Communication** - Strong typing for all IPC events and responses
241+
- **Error Boundaries** - Comprehensive error handling with proper propagation
242+
243+
#### 🔧 Service Pattern
244+
245+
- **Business Logic Encapsulation** - Clean separation of concerns
246+
- **Dependency Management** - Managed through IoC container
247+
- **Cross-Controller Sharing** - Services accessible via service locator pattern
248+
- **Resource Management** - Proper initialization and cleanup
249+
250+
### 🔗 Inter-Process Communication
251+
252+
#### 📡 IPC System Features
253+
254+
- **Bidirectional Communication** - Main↔Renderer and Main↔Next.js server
255+
- **Type-Safe Events** - TypeScript interfaces for all event parameters
256+
- **Context Awareness** - Events include sender context for window-specific operations
257+
- **Error Propagation** - Centralized error handling with proper status codes
258+
259+
#### 🛡️ Security Features
260+
261+
- **OAuth 2.0 + PKCE** - Secure authentication with state parameter validation
262+
- **Encrypted Token Storage** - Using Electron's Safe Storage API when available
263+
- **Custom Protocol Handler** - Secure callback handling for OAuth flows
264+
- **Request Filtering** - Security controls for web requests and external links
265+
266+
## 🧪 Testing
267+
268+
### Test Structure
49269

50270
```bash
51-
# macOS
52-
pnpm build:mac
271+
apps/desktop/src/main/controllers/__tests__/ # Controller unit tests
272+
tests/ # Integration tests
273+
```
53274

54-
# Windows
55-
pnpm build:win
275+
### Running Tests
56276

57-
# Linux
58-
pnpm build:linux
277+
```bash
278+
pnpm test # Run all tests
279+
pnpm test:watch # Watch mode
280+
pnpm typecheck # Type validation
59281
```
60282

61-
## 发布渠道
283+
### Test Coverage
284+
285+
- **Controller Tests** - IPC event handling validation
286+
- **Service Tests** - Business logic verification
287+
- **Integration Tests** - End-to-end workflow testing
288+
- **Type Tests** - TypeScript interface validation
289+
290+
## 🔒 Security Features
291+
292+
### Authentication & Authorization
293+
294+
- **OAuth 2.0 Flow** with PKCE for secure token exchange
295+
- **State Parameter Validation** to prevent CSRF attacks
296+
- **Encrypted Token Storage** using platform-native secure storage
297+
- **Automatic Token Refresh** with fallback to re-authentication
298+
299+
### Application Security
300+
301+
- **Code Signing** - macOS notarization for enhanced security
302+
- **Sandboxing** - Controlled access to system resources
303+
- **CSP Controls** - Content Security Policy management
304+
- **Request Filtering** - Security controls for external requests
305+
306+
### Data Protection
307+
308+
- **Encrypted Configuration** - Sensitive data encrypted at rest
309+
- **Secure IPC** - Type-safe communication channels
310+
- **Path Validation** - Secure file system access controls
311+
- **Network Security** - HTTPS enforcement and proxy support
312+
313+
## 🤝 Contribution
314+
315+
Desktop application development involves complex cross-platform considerations and native integrations. We welcome community contributions to improve functionality, performance, and user experience. You can participate in improvements through:
316+
317+
### How to Contribute
318+
319+
1. **Platform Support**: Enhance cross-platform compatibility and native integrations
320+
2. **Performance Optimization**: Improve application startup time, memory usage, and responsiveness
321+
3. **Feature Development**: Add new desktop-specific features and capabilities
322+
4. **Bug Fixes**: Fix platform-specific issues and edge cases
323+
5. **Security Improvements**: Enhance security measures and authentication flows
324+
6. **UI/UX Enhancements**: Improve desktop user interface and experience
325+
326+
### Contribution Process
327+
328+
1. Fork the [LobeChat repository](https://github.com/lobehub/lobe-chat)
329+
2. Set up the desktop development environment following our setup guide
330+
3. Make your changes to the desktop application
331+
4. Submit a Pull Request describing:
332+
333+
- Platform compatibility testing results
334+
- Performance impact analysis
335+
- Security considerations
336+
- User experience improvements
337+
- Breaking changes (if any)
338+
339+
### Development Areas
340+
341+
- **Core Architecture**: Dependency injection, event system, and lifecycle management
342+
- **Window Management**: Multi-window support, theme synchronization, and state persistence
343+
- **IPC Communication**: Type-safe inter-process communication between main and renderer
344+
- **Platform Integration**: Native menus, shortcuts, notifications, and system tray
345+
- **Security Features**: OAuth flows, token encryption, and secure storage
346+
- **Auto-Update System**: Multi-channel updates and rollback mechanisms
62347

63-
应用提供三个发布渠道：
348+
## 📚 Additional Resources
64349

65-
- **稳定版**：经过充分测试的正式版本
66-
- **测试版 (Beta)**：预发布版本，包含即将发布的新功能
67-
- **每日构建版 (Nightly)**：包含最新开发进展的构建版本
350+
- **Development Guide**: [`Development.md`](./Development.md) - Comprehensive development documentation
351+
- **Architecture Docs**: [`/docs`](../../docs/) - Detailed technical specifications
352+
- **Contributing**: [`CONTRIBUTING.md`](../../CONTRIBUTING.md) - Contribution guidelines
353+
- **Issues & Support**: [GitHub Issues](https://github.com/lobehub/lobe-chat/issues)

0 commit comments

Comments
 (0)