@lobehub/lobehub 2.0.0-next.353 → 2.0.0-next.355

package/.cursor/rules/desktop-window-management.mdc

@@ -1,301 +0,0 @@
----
-description:
-globs:
-alwaysApply: false
----
-
-# 桌面端窗口管理指南
-
-## 窗口管理概述
-
-LobeChat 桌面应用使用 Electron 的 `BrowserWindow` 管理应用窗口。主要的窗口管理功能包括：
-
-1. **窗口创建和配置**
-2. **窗口状态管理**（大小、位置、最大化等）
-3. **多窗口协调**
-4. **窗口事件处理**
-
-## 相关文件结构
-
-```plaintext
-apps/desktop/src/main/
-├── appBrowsers.ts               # 窗口管理的核心文件
-├── controllers/
-│   └── BrowserWindowsCtr.ts     # 窗口控制器
-└── modules/
-    └── browserWindowManager.ts  # 窗口管理模块
-```
-
-## 窗口管理流程
-
-### 1. 窗口创建
-
-在 `appBrowsers.ts` 或 `BrowserWindowsCtr.ts` 中定义窗口创建逻辑：
-
-```typescript
-export const createMainWindow = () => {
-  const mainWindow = new BrowserWindow({
-    width: 1200,
-    height: 800,
-    minWidth: 600,
-    minHeight: 400,
-    webPreferences: {
-      preload: path.join(__dirname, '../preload/index.js'),
-      contextIsolation: true,
-      nodeIntegration: false,
-    },
-    // 其他窗口配置项...
-  });
-
-  // 加载应用内容
-  if (isDev) {
-    mainWindow.loadURL('http://localhost:3000');
-    mainWindow.webContents.openDevTools();
-  } else {
-    mainWindow.loadFile(path.join(__dirname, '../../renderer/index.html'));
-  }
-
-  return mainWindow;
-};
-```
-
-### 2. 窗口状态管理
-
-实现窗口状态持久化保存和恢复：
-
-1. **保存窗口状态**
-
-   ```typescript
-   const saveWindowState = (window: BrowserWindow) => {
-     if (!window.isMinimized() && !window.isMaximized()) {
-       const position = window.getPosition();
-       const size = window.getSize();
-
-       settings.set('windowState', {
-         x: position[0],
-         y: position[1],
-         width: size[0],
-         height: size[1],
-       });
-     }
-   };
-   ```
-
-2. **恢复窗口状态**
-
-   ```typescript
-   const restoreWindowState = (window: BrowserWindow) => {
-     const savedState = settings.get('windowState');
-
-     if (savedState) {
-       window.setBounds({
-         x: savedState.x,
-         y: savedState.y,
-         width: savedState.width,
-         height: savedState.height,
-       });
-     }
-   };
-   ```
-
-3. **监听窗口事件**
-
-   ```typescript
-   window.on('close', () => saveWindowState(window));
-   window.on('moved', () => saveWindowState(window));
-   window.on('resized', () => saveWindowState(window));
-   ```
-
-### 3. 实现多窗口管理
-
-对于需要多窗口支持的功能：
-
-1. **跟踪窗口**
-
-   ```typescript
-   export class WindowManager {
-     private windows: Map<string, BrowserWindow> = new Map();
-
-     createWindow(id: string, options: BrowserWindowConstructorOptions) {
-       const window = new BrowserWindow(options);
-       this.windows.set(id, window);
-
-       window.on('closed', () => {
-         this.windows.delete(id);
-       });
-
-       return window;
-     }
-
-     getWindow(id: string) {
-       return this.windows.get(id);
-     }
-
-     getAllWindows() {
-       return Array.from(this.windows.values());
-     }
-   }
-   ```
-
-2. **窗口间通信**
-
-   ```typescript
-   // 从一个窗口向另一个窗口发送消息
-   sendMessageToWindow(targetWindowId, channel, data) {
-     const targetWindow = this.getWindow(targetWindowId);
-     if (targetWindow) {
-       targetWindow.webContents.send(channel, data);
-     }
-   }
-   ```
-
-### 4. 窗口与渲染进程通信
-
-通过 IPC 实现窗口操作：
-
-1. **在主进程中注册 IPC 处理器**
-
-   ```typescript
-   // apps/desktop/src/main/controllers/BrowserWindowsCtr.ts
-   import { BrowserWindow } from 'electron';
-
-   import { ControllerModule, IpcMethod } from '@/controllers';
-
-   export default class BrowserWindowsCtr extends ControllerModule {
-     static override readonly groupName = 'windows';
-
-     @IpcMethod()
-     minimizeWindow() {
-       const focusedWindow = BrowserWindow.getFocusedWindow();
-       focusedWindow?.minimize();
-       return { success: true };
-     }
-
-     @IpcMethod()
-     maximizeWindow() {
-       const focusedWindow = BrowserWindow.getFocusedWindow();
-       if (focusedWindow?.isMaximized()) focusedWindow.restore();
-       else focusedWindow?.maximize();
-       return { success: true };
-     }
-
-     @IpcMethod()
-     closeWindow() {
-       BrowserWindow.getFocusedWindow()?.close();
-       return { success: true };
-     }
-   }
-   ```
-
-   - `@IpcMethod()` 根据控制器的 `groupName` 自动将方法映射为 `windows.minimizeWindow` 形式的通道名称。
-   - 控制器需继承 `ControllerModule`，并在 `controllers/registry.ts` 中通过 `controllerIpcConstructors` 注册，便于类型生成。
-
-2. **在渲染进程中调用**
-
-   ```typescript
-   // src/services/electron/windowService.ts
-   import { ensureElectronIpc } from '@/utils/electron/ipc';
-
-   const ipc = ensureElectronIpc();
-
-   export const windowService = {
-     minimize: () => ipc.windows.minimizeWindow(),
-     maximize: () => ipc.windows.maximizeWindow(),
-     close: () => ipc.windows.closeWindow(),
-   };
-   ```
-
-   - `ensureElectronIpc()` 会基于 `DesktopIpcServices` 运行时生成 Proxy，并通过 `window.electronAPI.invoke` 与主进程通信；不再直接使用 `dispatch`。
-
-### 5. 自定义窗口控制 (无边框窗口)
-
-对于自定义窗口标题栏：
-
-1. **创建无边框窗口**
-
-   ```typescript
-   const window = new BrowserWindow({
-     frame: false,
-     titleBarStyle: 'hidden',
-     // 其他选项...
-   });
-   ```
-
-2. **在渲染进程中实现拖拽区域**
-
-   ```css
-   /* CSS */
-   .titlebar {
-     -webkit-app-region: drag;
-   }
-
-   .titlebar-button {
-     -webkit-app-region: no-drag;
-   }
-   ```
-
-## 最佳实践
-
-1. **性能考虑**
-   - 避免创建过多窗口
-   - 使用 `show: false` 创建窗口，在内容加载完成后再显示，避免白屏
-
-2. **安全性**
-   - 始终设置适当的 `webPreferences` 确保安全
-
-   ```typescript
-   webPreferences: {
-     preload: path.join(__dirname, '../preload/index.js'),
-     contextIsolation: true,
-     nodeIntegration: false,
-     sandbox: true,
-   }
-   ```
-
-3. **跨平台兼容性**
-   - 考虑不同操作系统的窗口行为差异
-   - 使用 `process.platform` 为不同平台提供特定实现
-
-4. **崩溃恢复**
-   - 监听 `webContents.on('crashed')` 事件处理崩溃
-   - 提供崩溃恢复选项
-
-5. **内存管理**
-   - 确保窗口关闭时清理所有相关资源
-   - 使用 `window.on('closed')` 而不是 `window.on('close')` 进行最终清理
-
-## 示例：创建设置窗口
-
-```typescript
-// apps/desktop/src/main/controllers/BrowserWindowsCtr.ts
-import type { OpenSettingsWindowOptions } from '@lobechat/electron-client-ipc';
-
-import { ControllerModule, IpcMethod } from '@/controllers';
-
-export default class BrowserWindowsCtr extends ControllerModule {
-  static override readonly groupName = 'windows';
-
-  @IpcMethod()
-  async openSettingsWindow(options?: string | OpenSettingsWindowOptions) {
-    const normalizedOptions =
-      typeof options === 'string' || options === undefined
-        ? { tab: typeof options === 'string' ? options : undefined }
-        : options;
-
-    const mainWindow = this.app.browserManager.getMainWindow();
-    const query = new URLSearchParams();
-    if (normalizedOptions.tab) query.set('active', normalizedOptions.tab);
-    if (normalizedOptions.searchParams) {
-      for (const [key, value] of Object.entries(normalizedOptions.searchParams)) {
-        if (value) query.set(key, value);
-      }
-    }
-
-    const fullPath = `/settings${query.size ? `?${query.toString()}` : ''}`;
-    await mainWindow.loadUrl(fullPath);
-    mainWindow.show();
-
-    return { success: true };
-  }
-}
-```

package/.cursor/rules/drizzle-schema-style-guide.mdc

@@ -1,218 +0,0 @@
----
-description:
-globs: src/database/schemas/*
-alwaysApply: false
----
-
-# Drizzle ORM Schema Style Guide for lobe-chat
-
-This document outlines the conventions and best practices for defining PostgreSQL Drizzle ORM schemas within the lobe-chat project.
-
-## Configuration
-
-- Drizzle configuration is managed in `drizzle.config.ts`
-- Schema files are located in the src/database/schemas/ directory
-- Migration files are output to `src/database/migrations/`
-- The project uses `postgresql` dialect with `strict: true`
-
-## Helper Functions
-
-Commonly used column definitions, especially for timestamps, are centralized in `src/database/schemas/_helpers.ts`:
-
-- `timestamptz(name: string)`: Creates a timestamp column with timezone
-- `createdAt()`, `updatedAt()`, `accessedAt()`: Helper functions for standard timestamp columns
-- `timestamps`: An object `{ createdAt, updatedAt, accessedAt }` for easy inclusion in table definitions
-
-## Naming Conventions
-
-- **Table Names**: Use plural snake_case (e.g., `users`, `agents`, `session_groups`)
-- **Column Names**: Use snake_case (e.g., `user_id`, `created_at`, `background_color`)
-
-## Column Definitions
-
-### Primary Keys (PKs)
-
-- Typically `text('id')` (or `varchar('id')` for some OIDC tables)
-- Often use `.$defaultFn(() => idGenerator('table_name'))` for automatic ID generation with meaningful prefixes
-- **ID Prefix Purpose**: Makes it easy for users and developers to distinguish different entity types at a glance
-- For internal/system tables that users don't need to see, can use `uuid` or auto-increment keys
-- Composite PKs are defined using `primaryKey({ columns: [t.colA, t.colB] })`
-
-### Foreign Keys (FKs)
-
-- Defined using `.references(() => otherTable.id, { onDelete: 'cascade' | 'set null' | 'no action' })`
-- FK columns are usually named `related_table_singular_name_id` (e.g., `user_id` references `users.id`)
-- Most tables include a `user_id` column referencing `users.id` with `onDelete: 'cascade'`
-
-### Timestamps
-
-- Consistently use the `...timestamps` spread from `_helpers.ts` for `created_at`, `updated_at`, and `accessed_at` columns
-
-### Default Values
-
-- `.$defaultFn(() => expression)` for dynamic defaults (e.g., `idGenerator()`, `randomSlug()`)
-- `.default(staticValue)` for static defaults (e.g., `boolean('enabled').default(true)`)
-
-### Indexes
-
-- Defined in the table's second argument: `pgTable('name', {...columns}, (t) => ({ indexName: indexType().on(...) }))`
-- Use `uniqueIndex()` for unique constraints and `index()` for non-unique indexes
-- Naming pattern: `table_name_column(s)_idx` or `table_name_column(s)_unique`
-- Many tables feature a `clientId: text('client_id')` column, often part of a composite unique index with `user_id`
-
-### Data Types
-
-- Common types: `text`, `varchar`, `jsonb`, `boolean`, `integer`, `uuid`, `pgTable`
-- For `jsonb` fields, specify the TypeScript type using `.$type<MyType>()` for better type safety
-
-## Zod Schemas & Type Inference
-
-- Utilize `drizzle-zod` to generate Zod schemas for validation:
-  - `createInsertSchema(tableName)`
-  - `createSelectSchema(tableName)` (less common)
-- Export inferred types: `export type NewEntity = typeof tableName.$inferInsert;` and `export type EntityItem = typeof tableName.$inferSelect;`
-
-## Relations
-
-- Table relationships are defined centrally in `src/database/schemas/relations.ts` using the `relations()` utility from `drizzle-orm`
-
-## Code Style & Structure
-
-- **File Organization**: Each main database entity typically has its own schema file (e.g., `user.ts`, `agent.ts`)
-- All schemas are re-exported from `src/database/schemas/index.ts`
-- **ESLint**: Files often start with `/* eslint-disable sort-keys-fix/sort-keys-fix */`
-- **Comments**: Use JSDoc-style comments to explain the purpose of tables and complex columns, fields that are self-explanatory do not require jsdoc explanations, such as id, user_id, etc.
-
-## Example Pattern
-
-```typescript
-// From src/database/schemas/agent.ts
-export const agents = pgTable(
-  'agents',
-  {
-    id: text('id')
-      .primaryKey()
-      .$defaultFn(() => idGenerator('agents'))
-      .notNull(),
-    slug: varchar('slug', { length: 100 })
-      .$defaultFn(() => randomSlug(4))
-      .unique(),
-    userId: text('user_id')
-      .references(() => users.id, { onDelete: 'cascade' })
-      .notNull(),
-    clientId: text('client_id'),
-    chatConfig: jsonb('chat_config').$type<LobeAgentChatConfig>(),
-    ...timestamps,
-  },
-  // return array instead of object, the object style is deprecated
-  (t) => [uniqueIndex('client_id_user_id_unique').on(t.clientId, t.userId)],
-);
-
-export const insertAgentSchema = createInsertSchema(agents);
-export type NewAgent = typeof agents.$inferInsert;
-export type AgentItem = typeof agents.$inferSelect;
-```
-
-## Common Patterns
-
-### 1. userId + clientId Pattern (Legacy)
-
-Some existing tables include both fields for different purposes:
-
-```typescript
-// Example from agents table (legacy pattern)
-userId: text('user_id')
-  .references(() => users.id, { onDelete: 'cascade' })
-  .notNull(),
-clientId: text('client_id'),
-
-// Usually with a composite unique index
-clientIdUnique: uniqueIndex('agents_client_id_user_id_unique').on(t.clientId, t.userId),
-```
-
-- **`userId`**: Server-side user association, ensures data belongs to specific user
-- **`clientId`**: Unique key for import/export operations, supports data migration between instances
-- **Current Status**: New tables should NOT include `clientId` unless specifically needed for import/export functionality
-- **Note**: This pattern is being phased out for new features to simplify the schema
-
-### 2. Junction Tables (Many-to-Many Relationships)
-
-Use composite primary keys for relationship tables:
-
-```typescript
-// Example: agents_knowledge_bases (from agent.ts)
-export const agentsKnowledgeBases = pgTable(
-  'agents_knowledge_bases',
-  {
-    agentId: text('agent_id')
-      .references(() => agents.id, { onDelete: 'cascade' })
-      .notNull(),
-    knowledgeBaseId: text('knowledge_base_id')
-      .references(() => knowledgeBases.id, { onDelete: 'cascade' })
-      .notNull(),
-    userId: text('user_id')
-      .references(() => users.id, { onDelete: 'cascade' })
-      .notNull(),
-    enabled: boolean('enabled').default(true),
-    ...timestamps,
-  },
-  (t) => [primaryKey({ columns: [t.agentId, t.knowledgeBaseId] })],
-);
-```
-
-**Pattern**: `{entity1}Id` + `{entity2}Id` as composite PK, plus `userId` for ownership
-
-### 3. OIDC Tables Special Patterns
-
-OIDC tables use `varchar` IDs instead of `text` with custom generators:
-
-```typescript
-// Example from oidc.ts
-export const oidcAuthorizationCodes = pgTable('oidc_authorization_codes', {
-  id: varchar('id', { length: 255 }).primaryKey(), // varchar not text
-  data: jsonb('data').notNull(),
-  expiresAt: timestamptz('expires_at').notNull(),
-  // ... other fields
-});
-```
-
-**Reason**: OIDC standards expect specific ID formats and lengths
-
-### 4. File Processing with Async Tasks
-
-File-related tables reference async task IDs for background processing:
-
-```typescript
-// Example from files table
-export const files = pgTable('files', {
-  // ... other fields
-  chunkTaskId: uuid('chunk_task_id').references(() => asyncTasks.id, { onDelete: 'set null' }),
-  embeddingTaskId: uuid('embedding_task_id').references(() => asyncTasks.id, {
-    onDelete: 'set null',
-  }),
-  // ...
-});
-```
-
-**Purpose**:
-
-- Track file chunking progress (breaking files into smaller pieces)
-- Track embedding generation progress (converting text to vectors)
-- Allow querying task status and handling failures
-
-### 5. Slug Pattern (Legacy)
-
-Some entities include auto-generated slugs - this is legacy code:
-
-```typescript
-slug: varchar('slug', { length: 100 })
-  .$defaultFn(() => randomSlug(4))
-  .unique(),
-
-// Often with composite unique constraint
-slugUserIdUnique: uniqueIndex('slug_user_id_unique').on(t.slug, t.userId),
-```
-
-**Current usage**: Only used to identify default agents/sessions (legacy pattern) **Future refactor**: Will likely be replaced with `isDefault: boolean()` field **Note**: Avoid using slugs for new features - prefer explicit boolean flags for status tracking
-
-By following these guidelines, maintain consistency, type safety, and maintainability across database schema definitions.

package/.cursor/rules/hotkey.mdc

@@ -1,162 +0,0 @@
----
-alwaysApply: false
----
-
-# 如何添加新的快捷键：开发者指南
-
-本指南将带您一步步地向 LobeChat 添加一个新的快捷键功能。我们将通过一个完整示例，演示从定义到实现的整个过程。
-
-## 示例场景
-
-假设我们要添加一个新的快捷键功能：**快速清空聊天记录**，快捷键为 `Mod+Shift+Backspace`。
-
-## 步骤 1：更新快捷键常量定义
-
-首先，在 `src/types/hotkey.ts` 中更新 `HotkeyEnum`：
-
-```typescript
-export const HotkeyEnum = {
-  // 已有的快捷键...
-  AddUserMessage: 'addUserMessage',
-  EditMessage: 'editMessage',
-
-  // 新增快捷键
-  ClearChat: 'clearChat', // 添加这一行
-
-  // 其他已有快捷键...
-} as const;
-```
-
-## 步骤 2：注册默认快捷键
-
-在 `src/const/hotkeys.ts` 中添加快捷键的默认配置：
-
-```typescript
-import { KeyMapEnum as Key, combineKeys } from '@lobehub/ui';
-
-// ...现有代码
-
-export const HOTKEYS_REGISTRATION: HotkeyRegistration = [
-  // 现有的快捷键配置...
-
-  // 添加新的快捷键配置
-  {
-    group: HotkeyGroupEnum.Conversation, // 归类到会话操作组
-    id: HotkeyEnum.ClearChat,
-    keys: combineKeys([Key.Mod, Key.Shift, Key.Backspace]),
-    scopes: [HotkeyScopeEnum.Chat], // 在聊天作用域下生效
-  },
-
-  // 其他现有快捷键...
-];
-```
-
-## 步骤 3：添加国际化翻译
-
-在 `src/locales/default/hotkey.ts` 中添加对应的文本描述：
-
-```typescript
-import { HotkeyI18nTranslations } from '@/types/hotkey';
-
-const hotkey: HotkeyI18nTranslations = {
-  // 现有翻译...
-
-  // 添加新快捷键的翻译
-  clearChat: {
-    desc: '清空当前会话的所有消息记录',
-    title: '清空聊天记录',
-  },
-
-  // 其他现有翻译...
-};
-
-export default hotkey;
-```
-
-如需支持其他语言，还需要在相应的语言文件中添加对应翻译。
-
-## 步骤 4：创建并注册快捷键 Hook
-
-在 `src/hooks/useHotkeys/chatScope.ts` 中添加新的 Hook：
-
-```typescript
-export const useClearChatHotkey = () => {
-  const clearMessages = useChatStore((s) => s.clearMessages);
-  const { t } = useTranslation();
-
-  return useHotkeyById(HotkeyEnum.ClearChat, showConfirm);
-};
-
-// 注册聚合
-
-export const useRegisterChatHotkeys = () => {
-  const { enableScope, disableScope } = useHotkeysContext();
-
-  useOpenChatSettingsHotkey();
-  // ...其他快捷键
-  useClearChatHotkey();
-
-  useEffect(() => {
-    enableScope(HotkeyScopeEnum.Chat);
-    return () => disableScope(HotkeyScopeEnum.Chat);
-  }, []);
-
-  return null;
-};
-```
-
-## 步骤 5：给相应 UI 元素添加 Tooltip 提示（可选）
-
-如果有对应的 UI 按钮，可以添加快捷键提示：
-
-```tsx
-import { DeleteOutlined } from '@ant-design/icons';
-import { Tooltip } from '@lobehub/ui';
-import { Button } from 'antd';
-import { useTranslation } from 'react-i18next';
-
-import { useUserStore } from '@/store/user';
-import { settingsSelectors } from '@/store/user/selectors';
-import { HotkeyEnum } from '@/types/hotkey';
-
-const ClearChatButton = () => {
-  const { t } = useTranslation(['hotkey', 'chat']);
-  const clearChatHotkey = useUserStore(settingsSelectors.getHotkeyById(HotkeyEnum.ClearChat));
-
-  // 获取清空聊天的方法
-  const clearMessages = useChatStore((s) => s.clearMessages);
-
-  return (
-    <Tooltip hotkey={clearChatHotkey} title={t('clearChat.title', { ns: 'hotkey' })}>
-      <Button icon={<DeleteOutlined />} onClick={clearMessages} />
-    </Tooltip>
-  );
-};
-```
-
-## 步骤 6：测试新快捷键
-
-1. 启动开发服务器
-2. 打开聊天页面
-3. 按下设置的快捷键组合（`Cmd+Shift+Backspace` 或 `Ctrl+Shift+Backspace`）
-4. 确认功能正常工作
-5. 检查快捷键设置面板中是否正确显示了新快捷键
-
-## 最佳实践
-
-1. **作用域考虑**：根据功能决定快捷键应属于全局作用域还是聊天作用域
-2. **分组合理**：将快捷键放在合适的功能组中（System/Layout/Conversation）
-3. **冲突检查**：确保新快捷键不会与现有系统、浏览器或应用快捷键冲突
-4. **平台适配**：使用 `Key.Mod` 而非硬编码 `Ctrl` 或 `Cmd`，以适配不同平台
-5. **提供清晰描述**：为快捷键添加明确的标题和描述，帮助用户理解功能
-
-按照以上步骤，您可以轻松地向系统添加新的快捷键功能，提升用户体验。如有特殊需求，如桌面专属快捷键，可以通过 `isDesktop` 标记进行区分处理。
-
-## 常见问题排查
-
-- **快捷键未生效**：检查作用域是否正确，以及是否在 RegisterHotkeys 中调用了对应的 hook
-- **快捷键设置面板未显示**：确认在 HOTKEYS_REGISTRATION 中正确配置了快捷键
-- **快捷键冲突**：在 HotkeyInput 组件中可以检测到冲突，用户会看到警告
-- **功能在某些页面失效**：确认是否注册在了正确的作用域，以及相关页面是否激活了该作用域
-
-通过这些步骤，您可以确保新添加的快捷键功能稳定、可靠且用户友好。