mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-26 13:19:34 +07:00
463d6c8762
* 🔧 chore(vscode): add typescript.tsdk and disable mdx server Fix MDX extension crash caused by Cursor's bundled TypeScript version * 🔧 chore(claude): add skills symlink to .claude directory * 📝 docs: update development guides with current tech stack and architecture - Update tech stack: Next.js 16 + React 19, hybrid routing (App Router + React Router DOM), tRPC, Drizzle ORM + PostgreSQL, react-i18next - Update directory structure to reflect monorepo layout (apps/, packages/, e2e/, locales/) - Expand src/server/ with detailed subdirectory descriptions - Add complete SPA routing architecture with desktop and mobile route tables - Add tRPC router grouping details (lambda, async, tools, mobile) - Add data flow diagram - Simplify dev setup section to link to setup-development guide - Fix i18n default language description (English, not Chinese) - Sync all changes between zh-CN and English versions * 📝 docs: expand data flow diagram in folder structure guide Replace the single-line data flow with a detailed layer-by-layer flow diagram showing each layer's location and responsibility. * 📝 docs: modernize feature development guide - Remove outdated clientDB/pglite/indexDB references - Update schema path to packages/database/src/schemas/ - Update types path to packages/types/src/ - Replace inline migration steps with link to db-migrations guide - Add complete layered architecture table (Client Service, WebAPI, tRPC Router, Server Service, Server Module, Repository, DB Model) - Clarify Client Service as frontend code - Add i18n handling section with workflow and key naming convention - Remove verbose CSS style code, keep core business logic only - Expand testing section with commands, skill refs, and CI tip * 🔥 docs: remove outdated frontend feature development guide Content is superseded by the comprehensive feature-development guide which covers the full chain from schema to testing. * 📝 docs: add LobeHub ecosystem and community resources Add official ecosystem packages (LobeUI, LobeIcons, LobeCharts, LobeEditor, LobeTTS, LobeLint, Lobe i18n, MCP Mark) and community platforms (Agent Market, MCP Market, YouTube, X, Discord). * 📝 docs: improve contributing guidelines and resources - Clarify semantic release triggers (feat/fix vs style/chore) - Add testing section with Vitest/E2E/CI requirements - Update contribution steps to include CI check - Add LobeHub ecosystem packages and community platforms to resources * 📝 docs: rewrite architecture guide to reflect current platform design * 📝 docs: add code quality tools to architecture guide * 📝 docs: rewrite chat-api guide to reflect current architecture - Update sequence diagram with Agent Runtime loop as core execution engine - Replace PluginGateway with ToolExecution layer (Builtin/MCP/Plugin) - Update all path references (model-runtime, agent-runtime, fetch-sse packages) - Split old AgentRuntime section into Model Runtime + Agent Runtime - Add tool calling taxonomy: Builtin, MCP, and Plugin (deprecated) - Add client-side vs server-side execution section - Remove outdated adapter pseudo-code examples * 📝 docs: update file paths in add-new-image-model guide - src/libs/standard-parameters/ → packages/model-bank/src/standard-parameters/ - src/config/aiModels/ → packages/model-bank/src/aiModels/ - src/libs/model-runtime/ → packages/model-runtime/src/providers/ * 📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides The S3_PUBLIC_DOMAIN env var was incorrectly removed from all documentation in commit4a87b31. This variable is still required by the code (src/server/services/file/impls/s3.ts) to generate public URLs for uploaded files. Without it, image URLs sent to vision models are just S3 keys instead of full URLs. Closes #12161 * 📦 chore: pin @lobehub/ui to 4.33.4 to fix SortableList type errors @lobehub/ui 4.34.0 introduced breaking type changes in SortableList where SortableListItem became strict, causing type incompatibility in onChange and renderItem callbacks across 6 files. Pin to 4.33.4 via pnpm overrides to enforce consistent version across monorepo. * 🐛 fix: correct ReadableStream type annotations and add dom.asynciterable - Add dom.asynciterable to tsconfig lib for ReadableStream async iteration - Fix createCallbacksTransformer return type: TransformStream<string, Uint8Array> - Update stream function return types from ReadableStream<string> to ReadableStream<Uint8Array> (llama.ts, ollama.ts, claude.ts) - Remove @ts-ignore from for-await loops in test files - Add explicit string[] type for chunks arrays * Revert "📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides" This reverts commit24073f83d3.
221 lines
8.8 KiB
Plaintext
221 lines
8.8 KiB
Plaintext
---
|
||
title: 目录架构
|
||
description: 深入了解 LobeHub 的文件夹目录架构及其功能模块。
|
||
tags:
|
||
- LobeHub
|
||
- 目录架构
|
||
- Next.js
|
||
- API路由
|
||
- 前端开发
|
||
---
|
||
|
||
# 目录架构
|
||
|
||
LobeHub 采用 Monorepo 架构（`@lobechat/` 命名空间），
|
||
顶层目录结构如下：
|
||
|
||
```bash
|
||
lobe-chat/
|
||
├── apps/
|
||
│ └── desktop/ # Electron 桌面应用
|
||
├── packages/ # 共享包（@lobechat/*）
|
||
│ ├── agent-runtime/ # Agent 运行时
|
||
│ ├── database/ # 数据库 schemas、models、repositories
|
||
│ ├── model-runtime/ # 模型运行时（各 AI 提供商适配）
|
||
│ ├── builtin-tool-*/ # 内置工具包
|
||
│ ├── business/ # Cloud 业务插槽 packages
|
||
│ ├── context-engine/ # 上下文引擎
|
||
│ ├── conversation-flow/ # 会话流程
|
||
│ ├── editor-runtime/ # 编辑器运行时
|
||
│ ├── file-loaders/ # 文件加载器
|
||
│ ├── prompts/ # Prompt 模板
|
||
│ └── ... # 更多共享包
|
||
├── src/ # 主应用源码（见下方详细说明）
|
||
├── locales/ # i18n 翻译文件（zh-CN、en-US 等）
|
||
├── e2e/ # E2E 测试（Cucumber + Playwright）
|
||
└── docs/ # 文档
|
||
```
|
||
|
||
## src 目录
|
||
|
||
```bash
|
||
src/
|
||
├── app/ # Next.js App Router（路由组和 API 路由）
|
||
├── business/ # Cloud 版专用业务逻辑（客户端/服务端）
|
||
├── components/ # 可复用的 UI 组件
|
||
├── config/ # 应用配置（客户端与服务端环境变量）
|
||
├── const/ # 应用常量和枚举
|
||
├── envs/ # 环境变量定义和校验
|
||
├── features/ # 业务功能模块（Agent 设置、插件开发弹窗等）
|
||
├── helpers/ # 工具辅助函数
|
||
├── hooks/ # 全应用复用的自定义 Hooks
|
||
├── layout/ # 全局布局组件（AuthProvider、GlobalProvider）
|
||
├── libs/ # 第三方集成（better-auth、OIDC、tRPC、MCP 等）
|
||
├── locales/ # 国际化默认语言文件（英文）
|
||
├── server/ # 服务端模块
|
||
│ ├── featureFlags/ # Feature Flags
|
||
│ ├── globalConfig/ # 全局配置
|
||
│ ├── modules/ # 服务端模块（不访问数据库）
|
||
│ ├── routers/ # tRPC 路由（async、lambda、mobile、tools）
|
||
│ └── services/ # 服务端服务（可访问数据库）
|
||
├── services/ # 客户端服务接口
|
||
├── store/ # zustand 状态管理
|
||
├── styles/ # 全局样式和 CSS-in-JS 配置
|
||
├── tools/ # 内置工具（artifacts、inspectors 等）
|
||
├── types/ # TypeScript 类型定义
|
||
├── utils/ # 通用工具函数
|
||
├── auth.ts # 认证配置（Better Auth）
|
||
├── instrumentation.ts # 应用监控和遥测设置
|
||
└── proxy.ts # Next.js 中间件代理配置
|
||
```
|
||
|
||
## app 目录
|
||
|
||
`app` 目录遵循 Next.js App Router 约定，
|
||
使用[路由组](https://nextjs.org/docs/app/building-your-application/routing/route-groups)
|
||
来组织后端服务、平台变体和应用路由：
|
||
|
||
```bash
|
||
app/
|
||
├── (backend)/ # 后端 API 路由和服务
|
||
│ ├── api/ # REST API 端点（auth、webhooks）
|
||
│ ├── f/ # 文件服务
|
||
│ ├── market/ # 市场服务
|
||
│ ├── middleware/ # 请求中间件
|
||
│ ├── oidc/ # OpenID Connect 路由
|
||
│ ├── trpc/ # tRPC API 端点
|
||
│ │ ├── async/ # 异步 tRPC 路由
|
||
│ │ ├── desktop/ # 桌面端 tRPC 路由
|
||
│ │ ├── lambda/ # Lambda tRPC 路由
|
||
│ │ └── tools/ # 工具 tRPC 路由
|
||
│ └── webapi/ # Web API 端点（chat、models、tts 等）
|
||
├── [variants]/ # 平台和设备变体
|
||
│ ├── (auth)/ # 身份验证页面（login、signup）
|
||
│ ├── (desktop)/ # 桌面端专用路由
|
||
│ ├── (main)/ # 主应用路由（SPA）
|
||
│ │ ├── _layout/ # 布局组件
|
||
│ │ ├── agent/ # Agent 页面
|
||
│ │ ├── home/ # 首页
|
||
│ │ ├── image/ # 图像生成
|
||
│ │ ├── memory/ # 记忆管理
|
||
│ │ ├── resource/ # 资源管理
|
||
│ │ └── settings/ # 应用设置
|
||
│ ├── (mobile)/ # 移动端专用路由
|
||
│ ├── onboarding/ # 新用户引导
|
||
│ ├── router/ # SPA 路由配置
|
||
│ └── share/ # 分享页面
|
||
├── manifest.ts # PWA 清单
|
||
├── robots.tsx # Robots.txt 生成
|
||
├── sitemap.tsx # 站点地图生成
|
||
└── sw.ts # Service Worker
|
||
```
|
||
|
||
### 架构说明
|
||
|
||
**路由组：**
|
||
|
||
- `(backend)` — 所有服务端 API 路由、中间件和后端服务
|
||
- `[variants]` — 处理不同平台变体的动态路由组
|
||
- `(main)` — 主应用 SPA，使用 React Router DOM
|
||
|
||
**平台组织：**
|
||
|
||
- 通过路由组织支持多平台（Web、桌面端、移动端）
|
||
- 桌面端专用路由在 `(desktop)/` 下
|
||
- 移动端专用路由在 `(mobile)/` 下
|
||
- 共享布局组件在 `_layout/` 目录中
|
||
|
||
**API 架构：**
|
||
|
||
- REST API：`(backend)/api/` 和 `(backend)/webapi/`
|
||
- tRPC 端点（`src/server/routers/`）：按运行时分组
|
||
- `lambda/` — 主要业务路由（agent、session、message、
|
||
topic、file、knowledge、settings 等）
|
||
- `async/` — 耗时异步操作（文件处理、图像生成、RAG 评估）
|
||
- `tools/` — 工具调用（search、MCP、market、klavis）
|
||
- `mobile/` — 移动端专用路由
|
||
|
||
**数据流：**
|
||
|
||
以一个典型的用户操作（如更新 Agent 配置）为例，数据在各层之间的流转：
|
||
|
||
```plaintext
|
||
React UI (src/features/, src/app/)
|
||
│ 用户交互触发事件
|
||
▼
|
||
Store Actions (src/store/)
|
||
│ zustand action 更新本地状态，调用 service
|
||
▼
|
||
Client Service (src/services/)
|
||
│ 封装 tRPC 客户端调用，处理请求参数
|
||
▼
|
||
tRPC Router (src/server/routers/lambda/)
|
||
│ 校验输入（zod），路由到对应 service
|
||
▼
|
||
Server Service (src/server/services/)
|
||
│ 执行业务逻辑，调用 DB model
|
||
▼
|
||
DB Model (packages/database/src/models/)
|
||
│ 封装 Drizzle ORM 查询
|
||
▼
|
||
PostgreSQL
|
||
```
|
||
|
||
读取数据的流程方向相反：UI 通过 store selector 消费数据，store 通过 SWR + tRPC query 从后端拉取。
|
||
|
||
### 路由架构
|
||
|
||
项目采用混合路由：
|
||
Next.js App Router 处理静态页面（如认证页），
|
||
React Router DOM 承载主应用 SPA。
|
||
|
||
**入口**：`src/app/[variants]/page.tsx`
|
||
根据设备类型分发到桌面端或移动端路由。
|
||
|
||
**关键配置文件：**
|
||
|
||
- 桌面端路由：`src/app/[variants]/router/desktopRouter.config.tsx`
|
||
- 移动端路由：`src/app/[variants]/(mobile)/router/mobileRouter.config.tsx`
|
||
- 路由工具：`src/utils/router.tsx`
|
||
|
||
**桌面端 SPA 路由（React Router DOM）：**
|
||
|
||
```bash
|
||
/ # 首页
|
||
/agent/:aid # Agent 会话
|
||
/agent/:aid/profile # Agent 详情
|
||
/agent/:aid/cron/:cronId # 定时任务详情
|
||
/group/:gid # 群组会话
|
||
/group/:gid/profile # 群组详情
|
||
/community # 社区发现（agent、model、provider、mcp）
|
||
/community/agent/:slug # Agent 详情页
|
||
/community/model/:slug # 模型详情页
|
||
/community/provider/:slug # 提供商详情页
|
||
/community/mcp/:slug # MCP 详情页
|
||
/resource # 资源管理
|
||
/resource/library/:id # 知识库详情
|
||
/settings/:tab # 设置（profile、provider 等）
|
||
/settings/provider/:id # 模型提供商配置
|
||
/memory # 记忆管理
|
||
/image # 图像生成
|
||
/page/:id # 页面详情
|
||
/share/t/:id # 分享话题
|
||
/onboarding # 新用户引导
|
||
```
|
||
|
||
**移动端 SPA 路由（React Router DOM）：**
|
||
|
||
```bash
|
||
/ # 首页
|
||
/agent/:aid # Agent 会话
|
||
/community # 社区发现
|
||
/settings # 设置首页
|
||
/settings/:tab # 设置详情
|
||
/settings/provider/:id # 模型提供商配置
|
||
/me # 个人中心
|
||
/me/profile # 个人资料
|
||
/me/settings # 个人设置
|
||
/share/t/:id # 分享话题
|
||
/onboarding # 新用户引导
|
||
```
|