目录架构
LobeHub 采用 Monorepo 架构(@lobechat/ 命名空间),
顶层目录结构如下:
src 目录
config/、envs/、locales/、tools/ 已从 src/ 迁出,独立为 packages ——
packages/app-config、packages/env、packages/locales、packages/builtin-tools。
@/config/*、@/envs/*、@/locales/* 路径别名会优先解析到这些 packages(见 tsconfig.json),
所以大部分 import 不需要改动。
app、routes 和 spa 目录
页面路由现在拆分到三个目录中:
src/app/— Next.js App Router,仅负责后端 API 路由((backend)/)以及两条负责渲染 SPA HTML 外壳的 Next.js 路由:spa/[variants]/[[...path]]/route.ts(主应用) 和spa-auth/[locale]/[[...path]]/route.ts(认证页)。src/routes/— SPA 页面片段,按平台路由组分组 ((main)、(mobile)、(desktop)、(popup)),以及auth/、onboarding/、share/。 这些文件很薄,只负责委托给src/features/*中的实际 UI 和业务逻辑。src/spa/— SPA 入口(entry.web.tsx、entry.mobile.tsx、entry.desktop.tsx、entry.popup.tsx、entry.auth.tsx)和router/下的 React Router 配置。
架构说明
路由组:
(backend)— 所有服务端 API 路由、中间件和后端服务(main)/(mobile)/(desktop)/(popup)—src/routes/下按平台划分的 SPA 路由组
平台组织:
- 通过路由组织支持多平台(Web、桌面端、移动端)
- 桌面端专用路由在
(desktop)/下 - 移动端专用路由在
(mobile)/下 - 共享布局组件在
_layout/目录中
API 架构:
- REST API:
(backend)/api/和(backend)/webapi/ - tRPC 端点(
apps/server/src/routers/):按运行时分组lambda/— 主要业务路由(agent、session、message、 topic、file、knowledge、settings 等)async/— 耗时异步操作(文件处理、图像生成、RAG 评估)tools/— 工具调用(search、MCP、market、composio)mobile/— 移动端专用路由
数据流:
以一个典型的用户操作(如更新 Agent 配置)为例,数据在各层之间的流转:
读取数据的流程方向相反:UI 通过 store selector 消费数据,store 通过 SWR + tRPC query 从后端拉取。
路由架构
项目采用混合路由: Next.js App Router 负责渲染 SPA 的 HTML 外壳和静态 / 认证页面, React Router DOM 在浏览器中加载 bundle 后承载主应用 SPA。
入口:Next.js 路由 src/app/spa/[variants]/[[...path]]/route.ts
渲染 HTML 外壳(根据设备类型选择桌面端或移动端模板),
随后加载 src/spa/ 下对应的 Vite 入口(entry.web.tsx、entry.mobile.tsx
或 entry.desktop.tsx)来挂载 React Router 应用。
关键配置文件:
- 桌面端路由:
src/spa/router/desktopRouter.config.tsx(需与desktopRouter.config.desktop.tsx保持同步) - 移动端路由:
src/spa/router/mobileRouter.config.tsx - 弹出窗口路由:
src/spa/router/popupRouter.config.tsx - 认证页路由:
src/spa/router/authRouter.config.tsx - 路由工具:
src/utils/router.tsx
桌面端 SPA 路由(React Router DOM):
移动端 SPA 路由(React Router DOM):