✨ feat: support AI Image (#8312)

Co-authored-by: canisminor1990 <i@canisminor.cc>
2026-06-14 03:30:19 +00:00 · 2025-07-14 20:29:57 +08:00
parent c98860e6cf
commit 095de57675
402 changed files with 29173 additions and 510 deletions
@@ -1,8 +1,9 @@
 ---
-description: 
+description:
 globs: src/services/**/*,src/database/**/*,src/server/**/*
 alwaysApply: false
 ---
+
 # LobeChat 后端技术架构指南

 本指南旨在阐述 LobeChat 项目的后端分层架构，重点介绍各核心目录的职责以及它们之间的协作方式。
@@ -29,24 +30,21 @@ LobeChat 的后端设计注重模块化、可测试性和灵活性，以适应
 其主要分层如下：

 1.  客户端服务层 (`src/services`):
-
    - 位于 src/services/。
    - 这是客户端业务逻辑的核心层，负责封装各种业务操作和数据处理逻辑。
    - 环境适配: 根据不同的运行环境，服务层会选择合适的数据访问方式：
-        - 本地数据库模式: 直接调用 `Model` 层进行数据操作，适用于浏览器 PGLite 和本地 Electron 应用。
-        - 远程数据库模式: 通过 `tRPC` 客户端调用服务端 API，适用于需要云同步的场景。
+      - 本地数据库模式: 直接调用 `Model` 层进行数据操作，适用于浏览器 PGLite 和本地 Electron 应用。
+      - 远程数据库模式: 通过 `tRPC` 客户端调用服务端 API，适用于需要云同步的场景。
    - 类型转换: 对于简单的数据类型转换，直接在此层进行类型断言，如 `this.pluginModel.query() as Promise<LobeTool[]>`
    - 每个服务模块通常包含 `client.ts`（本地模式）、`server.ts`（远程模式）和 `type.ts`（接口定义）文件，在实现时应该确保本地模式和远程模式业务逻辑实现一致，只是数据库不同。

 2.  API 接口层 (`TRPC`):
-
    - 位于 src/server/routers/
    - 使用 `tRPC` 构建类型安全的 API。Router 根据运行时环境（如 Edge Functions, Node.js Lambda）进行组织。
    - 负责接收客户端请求，并将其路由到相应的 `Service` 层进行处理。
    - 新建 lambda 端点时可以参考 src/server/routers/lambda/\_template.ts

 3.  仓库层 (`Repositories`):
-
    - 位于 src/database/repositories/。
    - 主要处理复杂的跨表查询和数据聚合逻辑，特别是当需要从多个 `Model` 获取数据并进行组合时。
    - 与 `Model` 层不同，`Repository` 层专注于复杂的业务查询场景，而不涉及简单的领域模型转换。
@@ -54,7 +52,6 @@ LobeChat 的后端设计注重模块化、可测试性和灵活性，以适应
    - 如果数据操作简单（仅涉及单个 `Model`），则通常直接在 `src/services` 层调用 `Model` 并进行简单的类型断言。

 4.  模型层 (`Models`):
-
    - 位于 src/database/models/ (例如 src/database/models/plugin.ts 和 src/database/models/document.ts)。
    - 提供对数据库中各个表（由 src/database/schemas/ 中的 Drizzle ORM schema 定义）的基本 CRUD (创建、读取、更新、删除) 操作和简单的查询能力。
    - `Model` 类专注于单个数据表的直接操作，不涉及复杂的领域模型转换，这些转换通常在上层的 `src/services` 中通过类型断言完成。
@@ -65,11 +62,11 @@ LobeChat 的后端设计注重模块化、可测试性和灵活性，以适应
    - 客户端模式 (浏览器/PWA): 使用 PGLite (基于 WASM 的 PostgreSQL)，数据存储在用户浏览器本地。
    - 服务端模式 (云部署): 使用远程 PostgreSQL 数据库。
    - Electron 桌面应用:
-        - Electron 客户端会启动一个本地 Node.js 服务。
-        - 本地服务通过 `tRPC` 与 Electron 的渲染进程通信。
-        - 数据库选择依赖于是否开启云同步功能：
-            - 云同步开启: 连接到远程 PostgreSQL 数据库。
-            - 云同步关闭: 使用 PGLite (通过 Node.js 的 WASM 实现) 在本地存储数据。
+      - Electron 客户端会启动一个本地 Node.js 服务。
+      - 本地服务通过 `tRPC` 与 Electron 的渲染进程通信。
+      - 数据库选择依赖于是否开启云同步功能：
+        - 云同步开启: 连接到远程 PostgreSQL 数据库。
+        - 云同步关闭: 使用 PGLite (通过 Node.js 的 WASM 实现) 在本地存储数据。

 ## 数据流向说明

@@ -93,8 +90,87 @@ UI (Electron Renderer) → Zustand action → Client Service -> TRPC Client →

 ## 服务层 (Server Services)

-  位于 src/server/services/。
-  核心职责是封装独立的、可复用的业务逻辑单元。这些服务应易于测试。
-  平台差异抽象: 一个关键特性是通过其内部的 `impls` 子目录（例如 src/server/services/file/impls 包含 s3.ts 和 local.ts）来抹平不同运行环境带来的差异（例如云端使用 S3 存储，桌面版使用本地文件系统）。这使得上层（如 `tRPC` routers）无需关心底层具体实现。
-  目标是使 `tRPC` router 层的逻辑尽可能纯粹，专注于请求处理和业务流程编排。
-  服务可能会调用 `Repository` 层或直接调用 `Model` 层进行数据持久化和检索，也可能调用其他服务。
+- 位于 src/server/services/。
+- 核心职责是封装独立的、可复用的业务逻辑单元。这些服务应易于测试。
+- 平台差异抽象: 一个关键特性是通过其内部的 `impls` 子目录（例如 src/server/services/file/impls 包含 s3.ts 和 local.ts）来抹平不同运行环境带来的差异（例如云端使用 S3 存储，桌面版使用本地文件系统）。这使得上层（如 `tRPC` routers）无需关心底层具体实现。
+- 目标是使 `tRPC` router 层的逻辑尽可能纯粹，专注于请求处理和业务流程编排。
+- 服务可能会调用 `Repository` 层或直接调用 `Model` 层进行数据持久化和检索，也可能调用其他服务。
+
+## 最佳实践 (Best Practices)
+
+### 数据库操作封装原则
+
+**连续的数据库操作应该封装到 Model 层**
+
+当业务逻辑涉及多个相关的数据库操作时，建议将这些操作封装到 Model 层中，而不是在上层（Service 或 Router 层）中进行多次数据库调用。
+
+**优势：**
+
+- **代码复用**: Client DB 环境的 service 实现和 Server DB 的 lambda 层实现可以复用相同的 Model 方法
+- **事务一致性**: 相关的数据库操作可以在同一个方法中管理，便于维护数据一致性
+- **性能优化**: 减少数据库连接次数，提高查询效率
+- **职责清晰**: Model 层专注数据访问，上层专注业务协调
+
+**示例：**
+
+```typescript
+// ✅ 推荐：在 Model 层封装连续的数据库操作
+class GenerationBatchModel {
+  async delete(id: string): Promise<{ deletedBatch: BatchItem; thumbnailUrls: string[] }> {
+    // 1. 查询相关数据
+    const batchWithGenerations = await this.db.query.generationBatches.findFirst({...});
+
+    // 2. 收集需要处理的数据
+    const thumbnailUrls = [...];
+
+    // 3. 执行删除操作
+    const [deletedBatch] = await this.db.delete(generationBatches)...;
+
+    return { deletedBatch, thumbnailUrls };
+  }
+}
+
+// ✅ 上层使用简洁
+const { thumbnailUrls } = await model.delete(id);
+await fileService.deleteFiles(thumbnailUrls);
+```
+
+### 文件操作与数据库操作的执行顺序
+
+**删除操作原则：数据库删除在前，文件删除在后**
+
+当业务逻辑同时涉及数据库记录和文件系统操作时，应该遵循"数据库优先"的原则。
+
+**原因：**
+
+- **用户体验优先**: 如果先删除文件再删除数据库记录，可能出现文件已删除但数据库记录仍存在的情况，用户访问时会遇到文件不存在的错误
+- **影响程度较小**: 如果先删除数据库记录再删除文件，即使文件删除失败，用户也看不到这个记录，只是造成一些存储空间浪费，对用户体验影响更小
+- **数据一致性**: 数据库记录是业务逻辑的核心，应该优先保证其一致性
+
+**示例：**
+
+```typescript
+// ✅ 推荐：先删除数据库记录，再删除文件
+async deleteGeneration(id: string) {
+  // 1. 先删除数据库记录
+  const deletedGeneration = await generationModel.delete(id);
+
+  // 2. 再删除相关文件
+  if (deletedGeneration.asset?.thumbnailUrl) {
+    await fileService.deleteFile(deletedGeneration.asset.thumbnailUrl);
+  }
+}
+
+// ❌ 不推荐：先删除文件
+async deleteGeneration(id: string) {
+  const generation = await generationModel.findById(id);
+
+  // 如果这里删除成功，但后面数据库删除失败，用户会遇到访问错误
+  await fileService.deleteFile(generation.asset.thumbnailUrl);
+  await generationModel.delete(id); // 可能失败
+}
+```
+
+**创建操作原则：数据库创建在前，文件操作在后**
+
+创建操作同样应该优先处理数据库记录，确保数据的一致性和完整性。
@@ -1,21 +1,25 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
+
 # Guide to Optimize Output(Response) Rendering

 ## File Path and Code Symbol Rendering

 - When rendering file paths, use backtick wrapping instead of markdown links so they can be parsed as clickable links in Cursor IDE.
+  - Good: `src/components/Button.tsx`
+  - Bad: [src/components/Button.tsx](src/components/Button.tsx)

-    - Good: `src/components/Button.tsx`
-    - Bad: [src/components/Button.tsx](mdc:src/components/Button.tsx)
+- Don't use line and column number in file path, this will make file path not clickable in Cursor IDE.
+  - Good: `src/components/Button.tsx` `10:20` (add a space between the file path and the line and column number)
+  - Bad: `src/components/Button.tsx:10:20`

 - When rendering functions, variables, or other code symbols, use backtick wrapping so they can be parsed as navigable links in Cursor IDE
-    - Good: The `useState` hook in `MyComponent`
-    - Bad: The useState hook in MyComponent
-     
+  - Good: The `useState` hook in `MyComponent`
+  - Bad: The useState hook in MyComponent
+
 ## Markdown Render

 - don't use br tag to wrap in table cell
@@ -23,9 +27,9 @@ alwaysApply: true
 ## Terminal Command Output

 - If terminal commands don't produce output, it's likely due to paging issues. Try piping the command to `cat` to ensure full output is displayed.
-    - Good: `git show commit_hash -- file.txt | cat`
-    - Good: `git log --oneline | cat`
-    - Reason: Some git commands use pagers by default, which may prevent output from being captured properly
+  - Good: `git show commit_hash -- file.txt | cat`
+  - Good: `git log --oneline | cat`
+  - Reason: Some git commands use pagers by default, which may prevent output from being captured properly

 ## Mermaid Diagram Generation: Strict Syntax Validation Checklist

@@ -44,50 +48,56 @@ Before producing any Mermaid diagram, you **must** compare your final code line-

 ### Checklist Details

-#### Rule 1: Edge Labels – Must Be Plain Text Only  
+#### Rule 1: Edge Labels – Must Be Plain Text Only
+
 > **Essence:** Anything inside `|...|` must contain pure, unformatted text. Absolutely NO Markdown, list markers, or parentheses/brackets allowed—these often cause rendering failures.

-   **✅ Do:** `A -->|Process plain text data| B`
-   **❌ Don't:** `A -->|1. Ordered list item| B`    (No numbered lists)
-   **❌ Don't:** `CC --"1. fetch('/api/...')"--> API`   (No square brackets)
-   **❌ Don't:** `A -->|- Unordered list item| B`   (No hyphen lists)
-   **❌ Don't:** `A -->|Transform (important)| B`   (No parentheses)
-   **❌ Don't:** `A -->|Transform [important]| B`   (No square brackets)
+- **✅ Do:** `A -->|Process plain text data| B`
+- **❌ Don't:** `A -->|1. Ordered list item| B` (No numbered lists)
+- **❌ Don't:** `CC --"1. fetch('/api/...')"--> API` (No square brackets)
+- **❌ Don't:** `A -->|- Unordered list item| B` (No hyphen lists)
+- **❌ Don't:** `A -->|Transform (important)| B` (No parentheses)
+- **❌ Don't:** `A -->|Transform [important]| B` (No square brackets)
+
+#### Rule 2: Node Definition – Handle Special Characters with Care

-#### Rule 2: Node Definition – Handle Special Characters with Care  
 > **Essence:** When node text or subgraph titles contain special characters like `()` or `[]`, wrap the text in quotes to avoid conflicts with Mermaid shape syntax.

-   **When your node text includes parentheses (e.g., 'React (JSX)'):**
-    -   **✅ Do:** `I_REACT["<b>React component (JSX)</b>"]` (Quotes wrap all text)
-    -   **❌ Don't:** `I_REACT(<b>React component (JSX)</b>)` (Wrong, Mermaid parses this as a shape)
-    -   **❌ Don't:** `subgraph Plugin Features (Plugins)` (Wrong, subgraph titles with parentheses must also be wrapped in quotes)
+- **When your node text includes parentheses (e.g., 'React (JSX)'):**
+  - **✅ Do:** `I_REACT["<b>React component (JSX)</b>"]` (Quotes wrap all text)
+  - **❌ Don't:** `I_REACT(<b>React component (JSX)</b>)` (Wrong, Mermaid parses this as a shape)
+  - **❌ Don't:** `subgraph Plugin Features (Plugins)` (Wrong, subgraph titles with parentheses must also be wrapped in quotes)
+
+#### Rule 3: Double Quotes in Text – Must Be Escaped

-#### Rule 3: Double Quotes in Text – Must Be Escaped  
 > **Essence:** Use `&quot;` for double quotes **inside node text**.

-   **✅ Do:** `A[This node contains &quot;quotes&quot;]`
-   **❌ Don't:** `A[This node contains "quotes"]`
+- **✅ Do:** `A[This node contains &quot;quotes&quot;]`
+- **❌ Don't:** `A[This node contains "quotes"]`
+
+#### Rule 4: All Formatting Must Use HTML Tags (NOT Markdown!)

-#### Rule 4: All Formatting Must Use HTML Tags (NOT Markdown!)  
 > **Essence:** For newlines, bold, and other text formatting in nodes, use HTML tags only. Markdown is not supported.

-   **✅ Do (robust):** `A["<b>Bold</b> and <code>code</code><br>This is a new line"]`
-   **❌ Don't (not rendered):** `C["# This is a heading"]`
-   **❌ Don't (not rendered):** ``C["`const` means constant"]``
-   **⚠️ Warning (unreliable):** `B["Markdown **bold** might sometimes work but DON'T rely on it"]`
+- **✅ Do (robust):** `A["<b>Bold</b> and <code>code</code><br>This is a new line"]`
+- **❌ Don't (not rendered):** `C["# This is a heading"]`
+- **❌ Don't (not rendered):** ``C["`const` means constant"]``
+- **⚠️ Warning (unreliable):** `B["Markdown **bold** might sometimes work but DON'T rely on it"]`
+
+#### Rule 5: No HTML Tags for Participants and Message Labels (Sequence Diagrams)

-#### Rule 5: No HTML Tags for Participants and Message Labels (Sequence Diagrams)  
 > **Important Addition:**  
 > In Mermaid sequence diagrams, you MUST NOT use any HTML tags (such as `<b>`, `<code>`, etc.) in:
+>
 > - `participant` display names (`as` part)
 > - Message labels (the text after `:` in diagram flows)
 >
 > These tags are generally not rendered—they may appear as-is or cause compatibility issues.

-   **✅ Do:** `participant A as Client`
-   **❌ Don't:** `participant A as <b>Client</b>`
-   **✅ Do:** `A->>B: 1. Establish connection`
-   **❌ Don't:** `A->>B: 1. <code>Establish connection</code>`
+- **✅ Do:** `participant A as Client`
+- **❌ Don't:** `participant A as <b>Client</b>`
+- **✅ Do:** `A->>B: 1. Establish connection`
+- **❌ Don't:** `A->>B: 1. <code>Establish connection</code>`

 ---

@@ -1,6 +0,0 @@
---
-description: 
-globs: src/locales/**/*
-alwaysApply: false
---
-read [i18n.mdc](mdc:.cursor/rules/i18n/i18n.mdc)
@@ -1,19 +1,16 @@
 ---
-description: 
-globs: 
 alwaysApply: true
 ---
+
 ## Project Description

-You are developing an open-source, modern-design AI chat framework: lobe chat. 
-
-Emoji logo: 🤯 
+You are developing an open-source, modern-design AI chat framework: lobe chat.

+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. read [folder-structure.mdx](mdc:docs/development/basic/folder-structure.mdx) to learn project structure.

 The project uses the following technologies:

@@ -45,3 +42,72 @@ 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
+
+```bash
+# type check
+bun type-check
+
+# install dependencies
+pnpm install
+
+# !: don't  any build script to check weather code can work after modify
+```
+
+check [testing guide](./testing-guide.mdc) to learn test scripts.
+
+## Project Description
+
+You are developing an open-source, modern-design AI chat framework: lobe chat.
+
+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.
+
+The project uses the following technologies:
+
+- pnpm as package manager
+- Next.js 15 for frontend and backend, using app router instead of pages router
+- react 19, using hooks, functional components, react server components
+- TypeScript programming language
+- antd, @lobehub/ui for component framework
+- antd-style for css-in-js framework
+- react-layout-kit for flex layout
+- react-i18next for i18n
+- lucide-react, @ant-design/icons for icons
+- @lobehub/icons for AI provider/model logo icon
+- @formkit/auto-animate for react list animation
+- zustand for global state management
+- nuqs for type-safe search params state manager
+- SWR for react data fetch
+- 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
+- Drizzle ORM
+- Vitest for testing, testing-library for react component test
+- Prettier for code formatting
+- 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;
+
+## Often used npm scripts
+
+```bash
+# type check
+bun type-check
+
+# install dependencies
+pnpm install
+
+# !: don't  any build script to check weather code can work after modify
+```
+
+check [testing guide](./testing-guide.mdc) to learn test scripts.
@@ -1,8 +1,9 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
+
 # LobeChat Cursor Rules System Guide

 This document explains how the LobeChat project's Cursor rules system works and serves as an index for manually accessible rules.
@@ -14,22 +15,26 @@ This document explains how the LobeChat project's Cursor rules system works and
 ## 📚 Four Ways to Access Rules

 ### 1. **Always Applied Rules** - `always_applied_workspace_rules`
+
 - **What**: Core project guidelines that are always active
 - **Content**: Project tech stack, basic coding standards, output formatting rules
 - **Access**: No tools needed - automatically provided in every conversation

 ### 2. **Dynamic Context Rules** - `cursor_rules_context`
+
 - **What**: Rules automatically matched based on files referenced in the conversation
 - **Trigger**: Only when user **explicitly @ mentions files** or **opens files in Cursor**
 - **Content**: May include brief descriptions or full rule content, depending on relevance
 - **Access**: No tools needed - automatically updated when files are referenced

 ### 3. **Agent Requestable Rules** - `agent_requestable_workspace_rules`
+
 - **What**: Detailed operational guides that can be requested on-demand
 - **Access**: Use `fetch_rules` tool with rule names
 - **Examples**: `debug`, `i18n/i18n`, `code-review`

 ### 4. **Manual Rules Index** - This file + `read_file`
+
 - **What**: Additional rules not covered by the above mechanisms
 - **Why needed**: Cursor's rule system only supports "agent request" or "auto attach" modes
 - **Access**: Use `read_file` tool to read specific `.mdc` files
@@ -47,10 +52,13 @@ Use `read_file` to access rules from the index below when:
 The following rules are available via `read_file` from the `.cursor/rules/` directory:

 - `backend-architecture.mdc` – Backend layer architecture and design guidelines
- `zustand-action-patterns.mdc` – Recommended patterns for organizing Zustand actions
- `zustand-slice-organization.mdc` – Best practices for structuring Zustand slices
+- `define-database-model.mdc` – Database model definition guidelines
 - `drizzle-schema-style-guide.mdc` – Style guide for defining Drizzle ORM schemas
 - `react-component.mdc` – React component style guide and conventions
+- `testing-guide.mdc` – Comprehensive testing guide for Vitest environment
+- `typescript.mdc` – TypeScript code style guide
+- `zustand-action-patterns.mdc` – Recommended patterns for organizing Zustand actions
+- `zustand-slice-organization.mdc` – Best practices for structuring Zustand slices

 ## ❌ Common Misunderstandings to Avoid

@@ -62,7 +70,7 @@ The following rules are available via `read_file` from the `.cursor/rules/` dire

 ```
 1. Start with always_applied_workspace_rules (automatic)
-2. Check cursor_rules_context for auto-matched rules (automatic) 
+2. Check cursor_rules_context for auto-matched rules (automatic)
 3. If you need specific guides: fetch_rules (manual)
 4. If you identify gaps: consult this index → read_file (manual)
 ```
@@ -70,7 +78,8 @@ The following rules are available via `read_file` from the `.cursor/rules/` dire
 ## Example Decision Flow

 **Scenario**: Working on a new Zustand store slice
+
 1. Follow always_applied_workspace_rules ✅
-2. If store files were @ mentioned → use cursor_rules_context rules ✅  
+2. If store files were @ mentioned → use cursor_rules_context rules ✅
 3. Need detailed Zustand guidance → `read_file('.cursor/rules/zustand-slice-organization.mdc')` ✅
-4. All rules apply simultaneously - no conflicts ✅
+4. All rules apply simultaneously - no conflicts ✅