[RFC] 129 - Phase Ⅰ : Project Structure Modularization

[arvinxx]

摘要

本 RFC 提出将 LobeChat 项目从当前的单体仓库架构重构为完整的 Monorepo 架构，以支持多平台应用开发（Web、Desktop、Mobile App、Chrome Plugin 等）并提高代码复用性和维护效率。

背景与动机

当前状况

LobeChat 项目目前已经初步实现了部分模块的 packages 化，包括：

• @lobechat/file-loaders - 文件加载器
• @lobechat/web-crawler - 网页爬虫
• @lobechat/electron-client-ipc / @lobechat/electron-server-ipc - Electron IPC 通信

驱动因素

1. 多平台扩展需求：已有 Web 和 Desktop 应用，目前正在开发 Mobile App ，未来可能还会有浏览器插件等
2. 代码复用：核心业务逻辑、类型定义、工具函数需要在多个平台间共享
3. 开发效率：统一的开发工具链和构建流程
4. 维护成本：集中化的依赖管理和版本控制
5. 团队协作：清晰的模块边界和职责分离

目标架构设计

整体结构

lobe-chat/
├── apps/                          # 应用层
│   ├── desktop/                   # Desktop 应用 (已存在)
│   ├── mobile/                    # Mobile 应用 (计划)
│   └── chrome-extension/          # Chrome 插件 (计划)
├── packages/                      # 共享包
│   ├── types/                     # 类型定义 (已存在)
│   ├── const/                     # 常量定义 (已存在)
│   ├── database/                  # 数据库层
│   ├── utils/                     # 工具函数
│   ├── config/                    # 配置管理
│   ├── file-loaders/              # 文件加载器 (已存在)
│   ├── web-crawler/               # 网页爬虫 (已存在)
│   └── mobile-bridge/             # Mobile 桥接层 (计划)
└── docs/                          # 文档

包设计原则

1. 单一职责：每个包专注于特定功能领域
2. 最小依赖：减少包间的循环依赖
3. 平台无关：核心包应该是平台无关的
4. 渐进式：支持渐进式迁移，不影响现有功能

详细包规划

2. @lobechat/database

• 职责：数据库抽象层，支持多种存储后端
• 功能：
  • 统一的数据访问接口
  • 支持 PostgreSQL (Server) 、PGLite （Web、Desktop）
  • 数据迁移和同步

4. @lobechat/utils

• 职责：通用工具函数
• 功能：
  • 数据处理工具
  • 加密解密
  • 文件处理
  • 网络请求封装

平台特定包

应用层设计 (apps/)

2. apps/desktop

• 保持现有结构
• 依赖：核心包 + Electron 包
• 构建：Electron + Next.js

3. apps/mobile (计划)

• 技术栈：React Native
• 依赖：核心包 + Mobile 桥接包

4. apps/extension (计划)

• 技术栈：Chrome Extension API + React
• 依赖：核心包 + 轻量化 UI 包

迁移计划

核心思想：渐进式迁移，每一步迁移不造成破坏性变更。

Step1: 目录结构调整

types、const 、database 等目录结构从 src 迁移至 packages 独立包。由于不希望变更在 web 的引入逻辑，通过在 alias 完成路径关联：

tsconfig.json

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "paths": {
      "@/const/*": ["./packages/const/src/*"],
      "@/types/*": ["./packages/types/src/*", "./src/types/*"],
      "@/*": ["./src/*"]
    }
}

vitest.config.ts

export default defineConfig({

  test: {
    alias: {
      '@/types': resolve(__dirname, './packages/types/src'),
      '@/const': resolve(__dirname, './packages/const/src'),
      '@': resolve(__dirname, './src'),
      /* eslint-enable */
    },
})

这种做法可以实现最小 git diff 情况下变更。

Step2: 包导入替换

各个包的引用逐一替换成 @lobechat/xxx ，并且在这个过程中逐步梳理现有引用实现的合理性，如存在必要重构的部分则进行重构。

Step3: 删除 alias

等所有引入迁移完毕后，最后删除 tsconfig 和 vitest 的 alias 引用关系，至此完成迁移实现。

进展

• types
  • step1 ♻️ refactor: move types to separate package #8635
  • step2 ♻️ refactor: refactor trace type #8699
  • step3
• const
  • step1 ♻️ refactor: refactor const folder to a new package #8756
  • step2
  • step3 ♻️ refactor: refactor to remove edge runtime and add more tests #9133
• database
  • step1 ♻️ refactor: move database to packages #8874
  • step2 ♻️ refactor: refactor package types #10233
  • step3
• model-runtime
  • step1 ♻️ refactor: refactor model-runtime to a seperated package #8763
  • step2
    • ♻️ refactor(model-runtime): refactor model-runtime dependencies and clean code #8997
    • ✅ test: add model runtime tests #9128
  • step3 ♻️ refactor: refactor model runtime folder and add more tests #9210
• utils
  • step1 ♻️ refactor: move utils to separate package  #8889
  • step2
  • step3 ♻️ refactor: refactor to remove edge runtime and add more tests #9133
• prompts ♻️ refactor: refactor prompts folder to the @lobechat/prompts pacakge #8810
  • ♻️ refactor: move chain into @lobechat/prompts #8875

---

2025.08.22 更新：

一期 6 个基础模块完成迁移，同时重构 test workflow 实现子包并行测试，顺利将耗时从 13 分钟减少到 8 分钟

[MapleEve]

啊……终于要抽象重构了，现在稍微做点大的到处找，加一个要改10个地方

PS：electron本地打包真阴间，每次要删79个文件

[arvinxx]

PS：electron本地打包真阴间，每次要删79个文件

因为 nextjs 不支持定制ignore文件… 只能前置跑脚本