mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 17:47:27 +00: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.
110 lines
4.9 KiB
Text
110 lines
4.9 KiB
Text
---
|
||
title: 架构设计
|
||
description: 深入了解 LobeHub 的架构设计，包括前端、后端、运行时和数据存储。
|
||
tags:
|
||
- LobeHub
|
||
- 架构设计
|
||
- Agent 平台
|
||
- Next.js
|
||
---
|
||
|
||
# 架构设计
|
||
|
||
LobeHub 是一个基于 Next.js 构建的开源 AI Agent 平台，使用户能够与 AI 进行自然语言交互、使用工具、管理知识库等。以下是 LobeHub 的架构设计概览。
|
||
|
||
## 应用架构概览
|
||
|
||
LobeHub 的整体架构由以下核心层组成：
|
||
|
||
```plaintext
|
||
+---------------------+--------------------------------------------------+
|
||
| Layer | Description |
|
||
+---------------------+--------------------------------------------------+
|
||
| Frontend | Next.js RSC + React Router DOM 混合路由 SPA |
|
||
| Backend API | RESTful WebAPI + tRPC Routers |
|
||
| Runtime | Model Runtime + Agent Runtime |
|
||
| Auth | Better Auth（邮箱密码 + SSO） |
|
||
| Data Storage | PostgreSQL + Redis + S3 |
|
||
| Marketplace | Agent 市场 + MCP 工具市场 |
|
||
+---------------------+--------------------------------------------------+
|
||
```
|
||
|
||
## 前端架构
|
||
|
||
前端采用 Next.js 框架，使用 **Next.js RSC + React Router DOM 混合路由**方案：Next.js App Router 处理服务端渲染页面（如认证页），React Router DOM 承载主应用 SPA。
|
||
|
||
主要技术栈：
|
||
|
||
- **UI 组件**：`@lobehub/ui`、antd
|
||
- **CSS-in-JS**：antd-style
|
||
- **状态管理**：zustand（slice 模式）
|
||
- **数据请求**：SWR + tRPC
|
||
- **国际化**：react-i18next
|
||
|
||
前端代码按职责分层在 `src/` 目录下，详见 [目录架构](/zh/docs/development/basic/folder-structure)。
|
||
|
||
## 后端 API
|
||
|
||
后端提供两种 API 形式：
|
||
|
||
- **RESTful WebAPI**（`src/app/(backend)/webapi/`）：处理 chat 流式响应、TTS、文件服务等需要特殊处理的端点
|
||
- **tRPC Routers**（`src/server/routers/`）：类型安全的主要业务路由，按运行时分组：
|
||
- `lambda/` — 主业务（agent、session、message、topic、file、knowledge、settings 等）
|
||
- `async/` — 耗时异步操作（文件处理、图像生成、RAG 评估）
|
||
- `tools/` — 工具调用（search、MCP、market）
|
||
- `mobile/` — 移动端专用
|
||
|
||
## Runtime
|
||
|
||
### Model Runtime
|
||
|
||
`@lobechat/model-runtime`（`packages/model-runtime/`）是 LLM API 适配层，抹平了 30+ 不同 AI Provider 之间的 API 差异（OpenAI、Anthropic、Google、Bedrock、Ollama 等），提供统一的调用接口。每个 Provider 有独立的适配器实现。它是无状态的，每次调用独立。
|
||
|
||
### Agent Runtime
|
||
|
||
`@lobechat/agent-runtime`（`packages/agent-runtime/`）是 Agent 编排引擎，位于 Model Runtime 之上，负责驱动多步 AI Agent 行为的完整生命周期：
|
||
|
||
- **Plan-Execute 循环**：核心状态机，循环执行 LLM 调用 → 工具执行 → 结果处理
|
||
- **工具调用与批量执行**：支持单工具和批量工具调用
|
||
- **Human-in-the-Loop**：安全检查、人工审批流程
|
||
- **上下文压缩**：管理上下文窗口
|
||
- **用量与成本追踪**：累计 token 用量和费用
|
||
- **多 Agent 协作**：`GroupOrchestrationRuntime` 支持 Supervisor + Executor 模式的多 Agent 编排
|
||
|
||
简言之：Model Runtime 解决 "如何与 LLM Provider 通信"，Agent Runtime 解决 "如何运行一个使用 LLM、工具、人工审批的完整 Agent"。
|
||
|
||
## 认证鉴权
|
||
|
||
LobeHub 使用 [Better Auth](https://www.better-auth.com/) 作为认证框架，支持：
|
||
|
||
- 邮箱 + 密码注册登录
|
||
- SSO 单点登录（GitHub、Google 等多种 OAuth Provider）
|
||
|
||
认证配置位于 `src/auth.ts`，相关路由在 `src/app/(backend)/api/` 下。
|
||
|
||
## 数据存储
|
||
|
||
```plaintext
|
||
+---------------+----------------------------------------------+
|
||
| Storage | Usage |
|
||
+---------------+----------------------------------------------+
|
||
| PostgreSQL | 主数据库，存储用户、会话、消息、Agent 配置等 |
|
||
| Redis | 缓存、会话状态、速率限制 |
|
||
| S3 | 文件存储（用户上传、图片、知识库文件等） |
|
||
+---------------+----------------------------------------------+
|
||
```
|
||
|
||
数据库使用 Drizzle ORM 操作，schema 定义在 `packages/database/src/schemas/`。
|
||
|
||
## 市场
|
||
|
||
- **Agent 市场**：提供各种场景的 AI Agent，用户可以发现、使用和分享 Agent
|
||
- **MCP 工具市场**：发现和集成 MCP 工具，扩展 Agent 的能力
|
||
|
||
## 开发和部署
|
||
|
||
- **版本控制**：Git + GitHub，gitmoji commit 规范
|
||
- **代码质量**：ESLint、Stylelint、TypeScript 类型检查、循环依赖检测 (dpdm)、死代码检测 (knip)
|
||
- **测试**：Vitest 单元测试 + Cucumber/Playwright E2E 测试
|
||
- **CI/CD**：GitHub Actions 自动化测试、构建和发布
|
||
- **部署**：支持 Vercel、Docker、各大云平台自托管
|