@lobehub/chat 1.90.3 → 1.91.0

package/.cursor/rules/backend-architecture.mdc

@@ -29,37 +29,40 @@ LobeChat 的后端设计注重模块化、可测试性和灵活性，以适应
 其主要分层如下：
 
 1.  **客户端服务层 (`src/services`)**:
-    *   位于 [src/services/](mdc:src/services)。
+    *   位于 src/services/。
     *   这是客户端业务逻辑的核心层，负责封装各种业务操作和数据处理逻辑。
     *   **环境适配**: 根据不同的运行环境，服务层会选择合适的数据访问方式：
         *   **本地数据库模式**: 直接调用 `Model` 层进行数据操作，适用于浏览器 PGLite 和本地 Electron 应用。
         *   **远程数据库模式**: 通过 `tRPC` 客户端调用服务端 API，适用于需要云同步的场景。
-    *   **类型转换**: 对于简单的数据类型转换，直接在此层进行类型断言，如 `this.pluginModel.query() as Promise<LobeTool[]>`（参见 [src/services/plugin/client.ts](mdc:src/services/plugin/client.ts)）。
-    *   每个服务模块通常包含 `client.ts`（本地模式）、`server.ts`（远程模式）和 `type.ts`（接口定义）文件。
+    *   **类型转换**: 对于简单的数据类型转换，直接在此层进行类型断言，如 `this.pluginModel.query() as Promise<LobeTool[]>`
+    *   每个服务模块通常包含 `client.ts`（本地模式）、`server.ts`（远程模式）和 `type.ts`（接口定义）文件，在实现时应该确保本地模式和远程模式业务逻辑实现一致，只是数据库不同。
 
 2.  **API 接口层 (`TRPC`)**:
-    *   位于 [src/server/routers/](mdc:src/server/routers)。
+    *   位于 src/server/routers/
     *   使用 `tRPC` 构建类型安全的 API。Router 根据运行时环境（如 Edge Functions, Node.js Lambda）进行组织。
     *   负责接收客户端请求，并将其路由到相应的 `Service` 层进行处理。
+    *   新建 lambda 端点时可以参考 src/server/routers/lambda/_template.ts
 
 3.  **服务端服务层 (`server/services`)**:
-    *   位于 [src/server/services/](mdc:src/server/services)。
+    *   位于 src/server/services/。
     *   核心职责是封装独立的、可复用的业务逻辑单元。这些服务应易于测试。
-    *   **平台差异抽象**: 一个关键特性是通过其内部的 `impls` 子目录（例如 [src/server/services/file/impls/](mdc:src/server/services/file/impls) 包含 `s3.ts` 和 `local.ts`）来抹平不同运行环境带来的差异（例如云端使用 S3 存储，桌面版使用本地文件系统）。这使得上层（如 `tRPC` routers）无需关心底层具体实现。
+    *   **平台差异抽象**: 一个关键特性是通过其内部的 `impls` 子目录（例如 src/server/services/file/impls 包含 s3.ts 和 local.ts）来抹平不同运行环境带来的差异（例如云端使用 S3 存储，桌面版使用本地文件系统）。这使得上层（如 `tRPC` routers）无需关心底层具体实现。
     *   目标是使 `tRPC` router 层的逻辑尽可能纯粹，专注于请求处理和业务流程编排。
     *   服务会调用 `Repository` 层或直接调用 `Model` 层进行数据持久化和检索，也可能调用其他服务。
 
 4.  **仓库层 (`Repositories`)**:
-    *   位于 [src/database/repositories/](mdc:src/database/repositories)。
+    *   位于 src/database/repositories/。
     *   主要处理**复杂的跨表查询和数据聚合**逻辑，特别是当需要从**多个 `Model`** 获取数据并进行组合时。
     *   与 `Model` 层不同，`Repository` 层专注于复杂的业务查询场景，而不涉及简单的领域模型转换。
     *   当业务逻辑涉及多表关联、复杂的数据统计或需要事务处理时，会使用 `Repository` 层。
     *   如果数据操作简单（仅涉及单个 `Model`），则通常直接在 `src/services` 层调用 `Model` 并进行简单的类型断言。
 
 5.  **模型层 (`Models`)**:
-    *   位于 [src/database/models/](mdc:src/database/models) (例如 [src/database/models/plugin.ts](mdc:src/database/models/plugin.ts) 和 [src/database/models/document.ts](mdc:src/database/models/document.ts))。
-    *   提供对数据库中各个表（由 [src/database/schemas/](mdc:src/database/schemas) 中的 Drizzle ORM schema 定义）的基本 CRUD (创建、读取、更新、删除) 操作和简单的查询能力。
+    *   位于 src/database/models/ (例如 src/database/models/plugin.ts 和 src/database/models/document.ts)。
+    *   提供对数据库中各个表（由 src/database/schemas/ 中的 Drizzle ORM schema 定义）的基本 CRUD (创建、读取、更新、删除) 操作和简单的查询能力。
     *   `Model` 类专注于单个数据表的直接操作，**不涉及复杂的领域模型转换**，这些转换通常在上层的 `src/services` 中通过类型断言完成。
+    * model（例如 Topic） 层接口经常需要从对应的 schema 层导入 NewTopic 和 TopicItem
+    * 创建新的 model 时可以参考 src/database/models/_template.ts
 
 6.  **数据库 (`Database`)**:
     *   **客户端模式 (浏览器/PWA)**: 使用 PGLite (基于 WASM 的 PostgreSQL)，数据存储在用户浏览器本地。

package/.cursor/rules/cursor-ux-optimize.mdc

@@ -24,4 +24,4 @@ Example:
 | 2  | Bob     | User      |
 | 3  | Charlie | Moderator |
 +----+---------+-----------+
-```
+```

package/.cursor/rules/define-database-model.mdc

@@ -5,4 +5,4 @@ alwaysApply: false
 ---
 1. first read [lobe-chat-backend-architecture.mdc](mdc:.cursor/rules/lobe-chat-backend-architecture.mdc)
 2. refer to the [_template.ts](mdc:src/database/models/_template.ts) to create new model
-3. if an operation involves multiple models or complex queries, consider defining it in the `repositories` layer under `src/database/repositories/`
+3. if an operation involves multiple models or complex queries, consider defining it in the `repositories` layer under `src/database/repositories/`

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

@@ -199,4 +199,4 @@ slugUserIdUnique: uniqueIndex('slug_user_id_unique').on(t.slug, t.userId),
 **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.
+By following these guidelines, maintain consistency, type safety, and maintainability across database schema definitions.

package/.cursor/rules/i18n/i18n.mdc

@@ -180,4 +180,4 @@ export default {
 
 - Check if the key exists in src/locales/default/namespace.ts
 - Ensure proper namespace import in component
-- Ensure new namespaces are exported in [src/locales/default/index.ts](mdc:src/locales/default/index.ts)
+- Ensure new namespaces are exported in [src/locales/default/index.ts](mdc:src/locales/default/index.ts)

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

@@ -34,6 +34,7 @@ The project uses the following technologies:
 - aHooks for react hooks library
 - dayjs for date and time library
 - lodash-es for utility library
+- fast-deep-equal for deep comparison of JavaScript objects
 - zod for data validation
 - TRPC for type safe backend
 - PGLite for client DB and PostgreSQL for backend DB
@@ -43,4 +44,4 @@ The project uses the following technologies:
 - ESLint for code linting
 - 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;
+Note: All tools and libraries used are the latest versions. The application only needs to be compatible with the latest browsers;

package/.cursor/rules/system-role.mdc

@@ -0,0 +1,42 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+## System Role
+
+You are an expert in full-stack Web development, proficient in JavaScript, TypeScript, CSS, React, Node.js, Next.js, Postgresql, all kinds of network protocols.
+
+You are an expert in LLM and Ai art. In Ai image generation, you are proficient in Stable Diffusion and ComfyUI's architectural principles, workflows, model structures, parameter configurations, training methods, and inference optimization.
+
+You are an expert in UI/UX design, proficient in web interaction patterns, responsive design, accessibility, and user behavior optimization. You excel at improving user retention and paid conversion rates through various interaction details.
+
+
+## Problem Solving
+
+- When modifying existing code, clearly describe the differences and reasons for the changes
+- Provide alternative solutions that may be better overall or superior in specific aspects
+- Always consider using the latest technologies, standards, and APIs to strive for code optimization, not just the conventional wisdom
+- Provide optimization suggestions for deprecated API usage
+- Cite sources whenever possible at the end, not inline
+- When you provide multiple solutions, provide the recommended solution first, and note it as `Recommended`
+- Express uncertainty when there might not be a correct answer
+- Admit when you don't know something instead of guessing
+
+## Code Implementation
+
+- Write minimal code changes that are ONLY directly related to the requirements
+- Write correct, up-to-date, bug-free, fully functional, secure, maintainable and efficient code
+- First, think step-by-step: describe your plan in detailed pseudocode before implementation
+- Confirm the plan before writing code
+- Focus on maintainable over being performant
+- Leave NO TODOs, placeholders, or missing pieces
+- Be sure to reference file names
+- Please respect my prettier preferences when you provide code
+- When you notice I have manually modified the code, that was definitely on purpose and do not revert them
+- Don't remove meaningful code comments, be sure to keep original comments when providing applied code
+- Update the code comments when needed after you modify the related code
+- If documentation links or required files are missing, ask for them before proceeding with the task rather than making assumptions
+- If you're unable to access or retrieve content from websites, please inform me immediately and request the specific information needed rather than making assumptions
+- Sometimes ESLint errors may not be reasonable, and making changes could introduce logical bugs. If you find an ESLint rule unreasonable, disable it directly. For example, with the 'prefer-dom-node-text-content' rule, there are actual differences between innerText and textContent
+- You can use emojis, npm packages like `chalk`/`chalk-animation`/`terminal-link`/`gradient-string`/`log-symbols`/`boxen`/`consola`/`@clack/prompts` to create beautiful terminal output

package/.cursor/rules/zustand-action-patterns.mdc

@@ -0,0 +1,318 @@
+---
+description: 
+globs: src/store/**
+alwaysApply: false
+---
+# LobeChat Zustand Action 组织模式
+
+本文档详细说明了 LobeChat 项目中 Zustand Action 的组织方式、命名规范和实现模式，特别关注乐观更新与后端服务的集成。
+
+## Action 类型分层
+
+LobeChat 的 Action 采用分层架构，明确区分不同职责：
+
+### 1. Public Actions
+对外暴露的主要接口，供 UI 组件调用：
+- 命名：动词形式（`createTopic`, `sendMessage`, `updateTopicTitle`）
+- 职责：参数验证、流程编排、调用 internal actions
+- 示例：[src/store/chat/slices/topic/action.ts](mdc:src/store/chat/slices/topic/action.ts)
+
+```typescript
+// Public Action 示例
+createTopic: async () => {
+  const { activeId, internal_createTopic } = get();
+  const messages = chatSelectors.activeBaseChats(get());
+  
+  if (messages.length === 0) return;
+  
+  const topicId = await internal_createTopic({
+    sessionId: activeId,
+    title: t('defaultTitle', { ns: 'topic' }),
+    messages: messages.map((m) => m.id),
+  });
+  
+  return topicId;
+},
+```
+
+### 2. Internal Actions (`internal_*`)
+内部实现细节，处理核心业务逻辑：
+- 命名：`internal_` 前缀 + 动词（`internal_createTopic`, `internal_updateMessageContent`）
+- 职责：乐观更新、服务调用、错误处理、状态同步
+- 不应该被 UI 组件直接调用
+
+```typescript
+// Internal Action 示例 - 乐观更新模式
+internal_createTopic: async (params) => {
+  const tmpId = Date.now().toString();
+  
+  // 1. 立即更新前端状态（乐观更新）
+  get().internal_dispatchTopic(
+    { type: 'addTopic', value: { ...params, id: tmpId } },
+    'internal_createTopic',
+  );
+  get().internal_updateTopicLoading(tmpId, true);
+  
+  // 2. 调用后端服务
+  const topicId = await topicService.createTopic(params);
+  get().internal_updateTopicLoading(tmpId, false);
+  
+  // 3. 刷新数据确保一致性
+  get().internal_updateTopicLoading(topicId, true);
+  await get().refreshTopic();
+  get().internal_updateTopicLoading(topicId, false);
+  
+  return topicId;
+},
+```
+
+### 3. Dispatch Methods (`internal_dispatch*`)
+专门处理状态更新的方法：
+- 命名：`internal_dispatch` + 实体名（`internal_dispatchTopic`, `internal_dispatchMessage`）
+- 职责：调用 reducer、更新 Zustand store、处理状态对比
+
+```typescript
+// Dispatch Method 示例
+internal_dispatchTopic: (payload, action) => {
+  const nextTopics = topicReducer(topicSelectors.currentTopics(get()), payload);
+  const nextMap = { ...get().topicMaps, [get().activeId]: nextTopics };
+
+  if (isEqual(nextMap, get().topicMaps)) return;
+  
+  set({ topicMaps: nextMap }, false, action ?? n(`dispatchTopic/${payload.type}`));
+},
+```
+
+## 何时使用 Reducer 模式 vs. 简单 `set`
+
+### 使用 Reducer 模式的场景
+
+**适用于复杂的数据结构管理**，特别是：
+- 管理对象列表或映射（如 `messagesMap`, `topicMaps`）
+- 需要乐观更新的场景
+- 状态转换逻辑复杂
+- 需要类型安全的 action payload
+
+```typescript
+// Reducer 模式示例 - 复杂消息状态管理
+export const messagesReducer = (state: ChatMessage[], payload: MessageDispatch): ChatMessage[] => {
+  switch (payload.type) {
+    case 'updateMessage': {
+      return produce(state, (draftState) => {
+        const index = draftState.findIndex((i) => i.id === payload.id);
+        if (index < 0) return;
+        draftState[index] = merge(draftState[index], { 
+          ...payload.value, 
+          updatedAt: Date.now() 
+        });
+      });
+    }
+    case 'createMessage': {
+      return produce(state, (draftState) => {
+        draftState.push({ 
+          ...payload.value, 
+          id: payload.id,
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+          meta: {}
+        });
+      });
+    }
+    // ...其他复杂状态转换
+  }
+};
+```
+
+### 使用简单 `set` 的场景
+
+**适用于简单状态更新**：
+- 切换布尔值
+- 更新简单字符串/数字
+- 设置单一状态字段
+
+```typescript
+// 简单 set 示例
+updateInputMessage: (message) => {
+  if (isEqual(message, get().inputMessage)) return;
+  set({ inputMessage: message }, false, n('updateInputMessage'));
+},
+
+togglePortal: (open?: boolean) => {
+  set({ showPortal: open ?? !get().showPortal }, false, 'togglePortal');
+},
+```
+
+## 乐观更新实现模式
+
+乐观更新是 LobeChat 中的核心模式，用于提供流畅的用户体验：
+
+### 标准乐观更新流程
+
+```typescript
+// 完整的乐观更新示例
+internal_updateMessageContent: async (id, content, extra) => {
+  const { internal_dispatchMessage, refreshMessages } = get();
+
+  // 1. 立即更新前端状态（乐观更新）
+  internal_dispatchMessage({
+    id,
+    type: 'updateMessage',
+    value: { content },
+  });
+
+  // 2. 调用后端服务
+  await messageService.updateMessage(id, {
+    content,
+    tools: extra?.toolCalls ? internal_transformToolCalls(extra.toolCalls) : undefined,
+    // ...其他字段
+  });
+
+  // 3. 刷新确保数据一致性
+  await refreshMessages();
+},
+```
+
+### 创建操作的乐观更新
+
+```typescript
+internal_createMessage: async (message, context) => {
+  const { internal_createTmpMessage, refreshMessages, internal_toggleMessageLoading } = get();
+  
+  let tempId = context?.tempMessageId;
+  if (!tempId) {
+    // 创建临时消息用于乐观更新
+    tempId = internal_createTmpMessage(message);
+    internal_toggleMessageLoading(true, tempId);
+  }
+
+  try {
+    const id = await messageService.createMessage(message);
+    if (!context?.skipRefresh) {
+      await refreshMessages();
+    }
+    internal_toggleMessageLoading(false, tempId);
+    return id;
+  } catch (e) {
+    internal_toggleMessageLoading(false, tempId);
+    // 错误处理：更新消息错误状态
+    internal_dispatchMessage({
+      id: tempId,
+      type: 'updateMessage',
+      value: { error: { type: ChatErrorType.CreateMessageError, message: e.message } },
+    });
+  }
+},
+```
+
+## 加载状态管理模式
+
+LobeChat 使用统一的加载状态管理模式：
+
+### 数组式加载状态
+
+```typescript
+// 在 initialState.ts 中定义
+export interface ChatMessageState {
+  messageLoadingIds: string[];      // 消息加载状态
+  messageEditingIds: string[];      // 消息编辑状态
+  chatLoadingIds: string[];         // 对话生成状态
+}
+
+// 在 action 中管理
+internal_toggleMessageLoading: (loading, id) => {
+  set({
+    messageLoadingIds: toggleBooleanList(get().messageLoadingIds, id, loading),
+  }, false, `internal_toggleMessageLoading/${loading ? 'start' : 'end'}`);
+},
+```
+
+### 统一的加载状态工具
+
+```typescript
+// 通用的加载状态切换工具
+internal_toggleLoadingArrays: (key, loading, id, action) => {
+  const abortControllerKey = `${key}AbortController`;
+  
+  if (loading) {
+    const abortController = new AbortController();
+    set({
+      [abortControllerKey]: abortController,
+      [key]: toggleBooleanList(get()[key] as string[], id!, loading),
+    }, false, action);
+    return abortController;
+  } else {
+    set({
+      [abortControllerKey]: undefined,
+      [key]: id ? toggleBooleanList(get()[key] as string[], id, loading) : [],
+    }, false, action);
+  }
+},
+```
+
+## SWR 集成模式
+
+LobeChat 使用 SWR 进行数据获取和缓存管理：
+
+### Hook 式数据获取
+
+```typescript
+// 在 action.ts 中定义 SWR hook
+useFetchMessages: (enable, sessionId, activeTopicId) =>
+  useClientDataSWR<ChatMessage[]>(
+    enable ? [SWR_USE_FETCH_MESSAGES, sessionId, activeTopicId] : null,
+    async ([, sessionId, topicId]) => messageService.getMessages(sessionId, topicId),
+    {
+      onSuccess: (messages, key) => {
+        const nextMap = {
+          ...get().messagesMap,
+          [messageMapKey(sessionId, activeTopicId)]: messages,
+        };
+        
+        if (get().messagesInit && isEqual(nextMap, get().messagesMap)) return;
+        
+        set({ messagesInit: true, messagesMap: nextMap }, false, n('useFetchMessages'));
+      },
+    },
+  ),
+```
+
+### 缓存失效和刷新
+
+```typescript
+// 刷新数据的标准模式
+refreshMessages: async () => {
+  await mutate([SWR_USE_FETCH_MESSAGES, get().activeId, get().activeTopicId]);
+},
+
+refreshTopic: async () => {
+  return mutate([SWR_USE_FETCH_TOPIC, get().activeId]);
+},
+```
+
+## 命名规范总结
+
+### Action 命名模式
+- **Public Actions**: 动词形式，描述用户意图
+  - `createTopic`, `sendMessage`, `regenerateMessage`
+- **Internal Actions**: `internal_` + 动词，描述内部操作
+  - `internal_createTopic`, `internal_updateMessageContent`
+- **Dispatch Methods**: `internal_dispatch` + 实体名
+  - `internal_dispatchTopic`, `internal_dispatchMessage`
+- **Toggle Methods**: `internal_toggle` + 状态名
+  - `internal_toggleMessageLoading`, `internal_toggleChatLoading`
+
+### 状态命名模式
+- **ID 数组**: `[entity]LoadingIds`, `[entity]EditingIds`
+- **映射结构**: `[entity]Maps`, `[entity]Map`
+- **当前激活**: `active[Entity]Id`
+- **初始化标记**: `[entity]sInit`
+
+## 最佳实践
+
+1. **始终实现乐观更新**：对于用户交互频繁的操作
+2. **加载状态管理**：使用统一的加载状态数组管理并发操作
+3. **类型安全**：为所有 action payload 定义 TypeScript 接口
+4. **SWR 集成**：使用 SWR 管理数据获取和缓存失效
+5. **AbortController**：为长时间运行的操作提供取消能力
+
+这套 Action 组织模式确保了代码的一致性、可维护性，并提供了优秀的用户体验。