@lobehub/chat 1.98.2 → 1.99.1

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

@@ -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); // 可能失败
+}
+```
+
+**创建操作原则：数据库创建在前，文件操作在后**
+
+创建操作同样应该优先处理数据库记录，确保数据的一致性和完整性。

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

@@ -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>`
 
 ---
 

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

@@ -1,19 +1,71 @@
 ---
-description: 
-globs: 
 alwaysApply: true
 ---
+
 ## Project Description
 
-You are developing an open-source, modern-design AI chat framework: lobe chat. 
+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.
+
+## Project Description
 
-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 +97,17 @@ 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.

package/.cursor/rules/rules-attach.mdc

@@ -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 ✅

package/.eslintrc.js

@@ -36,6 +36,16 @@ config.overrides = [
       'mdx/code-blocks': false,
     },
   },
+
+  {
+    files: ['src/store/image/**/*', 'src/types/generation/**/*'],
+    rules: {
+      '@typescript-eslint/no-empty-interface': 0,
+      'sort-keys-fix/sort-keys-fix': 0,
+      'typescript-sort-keys/interface': 0,
+      'typescript-sort-keys/string-enum': 0,
+    },
+  },
 ];
 
 module.exports = config;

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 # Changelog
 
+### [Version 1.99.1](https://github.com/lobehub/lobe-chat/compare/v1.99.0...v1.99.1)
+
+<sup>Released on **2025-07-15**</sup>
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+## [Version 1.99.0](https://github.com/lobehub/lobe-chat/compare/v1.98.2...v1.99.0)
+
+<sup>Released on **2025-07-14**</sup>
+
+#### ✨ Features
+
+- **plugin**: Support Streamable HTTP MCP Server Auth.
+- **misc**: support AI Image.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **plugin**: Support Streamable HTTP MCP Server Auth, closes [#8425](https://github.com/lobehub/lobe-chat/issues/8425) ([853a09a](https://github.com/lobehub/lobe-chat/commit/853a09a))
+- **misc**: support AI Image, closes [#8312](https://github.com/lobehub/lobe-chat/issues/8312) ([095de57](https://github.com/lobehub/lobe-chat/commit/095de57))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ### [Version 1.98.2](https://github.com/lobehub/lobe-chat/compare/v1.98.1...v1.98.2)
 
 <sup>Released on **2025-07-14**</sup>

package/apps/desktop/README.md

@@ -24,6 +24,13 @@ LobeHub Desktop 是 [LobeChat](https://github.com/lobehub/lobe-chat) 的跨平
 pnpm install-isolated
 ```
 
+### 配置环境变量
+
+复制 `.env.desktop` 到 `.env`。
+
+> [!WARNING]
+> 注意提前备份好 `.env` 文件，避免丢失配置。
+
 ### 开发模式运行
 
 ```bash

package/apps/desktop/electron-builder.js

@@ -25,6 +25,11 @@ const config = {
     artifactName: '${productName}-${version}.${ext}',
   },
   asar: true,
+  asarUnpack: [
+    // https://github.com/electron-userland/electron-builder/issues/9001#issuecomment-2778802044
+    '**/node_modules/sharp/**/*',
+    '**/node_modules/@img/**/*',
+  ],
   detectUpdateChannel: true,
   directories: {
     buildResources: 'build',

package/apps/desktop/package.json

@@ -14,12 +14,13 @@
     "build-local": "npm run build && electron-builder --dir --config electron-builder.js  --c.mac.notarize=false -c.mac.identity=null --c.asar=false",
     "build:linux": "npm run build && electron-builder --linux --config electron-builder.js  --publish never",
     "build:mac": "npm run build && electron-builder --mac --config electron-builder.js  --publish never",
+    "build:mac:local": "npm run build && UPDATE_CHANNEL=nightly electron-builder --mac --config electron-builder.js --publish never",
     "build:win": "npm run build && electron-builder --win --config electron-builder.js  --publish never",
     "electron:dev": "electron-vite dev",
     "electron:run-unpack": "electron .",
     "format": "prettier --write ",
     "i18n": "bun run scripts/i18nWorkflow/index.ts && lobe-i18n",
-    "postinstall": "electron-builder install-app-deps",
+    "postinstall": "electron-builder install-app-deps && pnpm rebuild sharp",
     "install-isolated": "pnpm install",
     "lint": "eslint --cache ",
     "pg-server": "bun run scripts/pglite-server.ts",

package/apps/desktop/src/main/appBrowsers.ts

@@ -36,7 +36,7 @@ export const appBrowsers = {
     autoHideMenuBar: true,
     height: 800,
     identifier: 'settings',
-    keepAlive: true,
+    // keepAlive: true,
     minWidth: 600,
     parentIdentifier: 'chat',
     path: '/settings',

package/apps/desktop/src/main/const/dir.ts

@@ -27,3 +27,6 @@ export const LOCAL_DATABASE_DIR = 'lobehub-local-db';
 export const FILE_STORAGE_DIR = 'file-storage';
 // Plugin 安装目录
 export const INSTALL_PLUGINS_DIR = 'plugins';
+
+// Desktop file service
+export const LOCAL_STORAGE_URL_PREFIX = '/lobe-desktop-file';

package/apps/desktop/src/main/controllers/UploadFileCtr.ts

@@ -1,15 +1,10 @@
+import { UploadFileParams } from '@lobechat/electron-client-ipc';
+import { CreateFileParams } from '@lobechat/electron-server-ipc';
+
 import FileService from '@/services/fileSrv';
 
 import { ControllerModule, ipcClientEvent, ipcServerEvent } from './index';
 
-interface UploadFileParams {
-  content: ArrayBuffer;
-  filename: string;
-  hash: string;
-  path: string;
-  type: string;
-}
-
 export default class UploadFileCtr extends ControllerModule {
   private get fileService() {
     return this.app.getService(FileService);
@@ -27,8 +22,18 @@ export default class UploadFileCtr extends ControllerModule {
     return this.fileService.getFilePath(id);
   }
 
+  @ipcServerEvent('getFileHTTPURL')
+  async getFileHTTPURL(path: string) {
+    return this.fileService.getFileHTTPURL(path);
+  }
+
   @ipcServerEvent('deleteFiles')
   async deleteFiles(paths: string[]) {
     return this.fileService.deleteFiles(paths);
   }
+
+  @ipcServerEvent('createFile')
+  async createFile(params: CreateFileParams) {
+    return this.fileService.uploadFile(params);
+  }
 }