project-overview

LobeHub 项目概览

以下目录列表是关键位置的精选索引，并非完整目录树。packages/、src/store/、路由组等会随着时间不断扩展——请对实际目录运行 ls，查看当前内容。

项目简介

开源、采用现代设计的 AI Agent 工作空间：LobeHub（原名 LobeChat）。 此仓库是开源根仓库（github.com/lobehub/lobehub，包 @lobehub/lobehub）。

支持的平台：

• Web 桌面端/移动端
• 桌面端（Electron）—— apps/desktop
• 移动应用（React Native）——独立仓库，已上线（不在此单体仓库中）

Logo 表情符号： 🤯

完整技术栈

类别	技术
框架	Next.js 16 + React 19
路由	Next.js 内的 SPA，使用 react-router-dom
语言	TypeScript
UI 组件	@lobehub/ui
CSS-in-JS	@lobehub/ui createStaticStyles
图标	lucide-react、@ant-design/icons
国际化	react-i18next
状态管理	zustand
URL 参数	nuqs
数据获取	SWR
React Hooks	aHooks
日期/时间	dayjs
工具库	es-toolkit
API	TRPC（类型安全）
数据库	Neon PostgreSQL + Drizzle ORM
测试	Vitest

具体版本请查看根目录的 package.json，而非此处。

单体仓库布局

扁平布局——apps/、packages/ 和 src/ 均位于仓库根目录。没有 git 子模块。

(repo root)
├── apps/
│   ├── cli/                  # LobeHub CLI
│   ├── desktop/              # Electron desktop app
│   └── server/               # Next.js-backed server (`@/server/*` alias)
│       └── src/
│           ├── router-hono/  # Hono endpoint routers and standalone runtime
│           └── ...           # featureFlags, globalConfig, modules, routers, services, utils, workflows
├── docs/                     # changelog, development, self-hosting, usage
├── locales/                  # en-US, zh-CN, ...
├── packages/                 # ~80 @lobechat/* workspace packages — `ls` for the full set. Key ones:
│   ├── agent-runtime/        # Agent runtime core
│   ├── agent-signal/         # Agent Signal pipeline
│   ├── agent-tracing/        # Tracing / snapshots
│   ├── builtin-tool-*/       # Per-tool packages (calculator, web-browsing, claude-code, ...)
│   ├── builtin-tools/        # Central registries that compose builtin-tool-*
│   ├── context-engine/
│   ├── database/             # src/{models,schemas,repositories}
│   ├── model-bank/           # Model definitions & provider cards
│   ├── model-runtime/        # src/{core,providers}
│   ├── locales/              # i18n source of truth: packages/locales/src/default/
│   ├── env/                  # env schemas (@/envs/* → packages/env/src/*)
│   ├── app-config/
│   ├── business/             # Open-source stubs (config, const, model-bank, model-runtime) — overridden by cloud
│   ├── types/
│   └── utils/
└── src/
    ├── app/
    │   ├── (backend)/        # api, f, market, middleware, oidc, trpc, webapi
    │   ├── spa/              # SPA HTML template service
    │   └── spa-auth/         # Auth HTML shell (SSR)
    ├── routes/               # SPA page segments (thin — delegate to features/)
    │   └── (main)/ (mobile)/ (desktop)/ (popup)/ auth/ onboarding/ share/
    ├── spa/                  # SPA entries + router config
    │   ├── entry.{web,mobile,desktop,popup}.tsx
    │   └── router/
    ├── business/             # Open-source stubs (client/server) — cloud repo provides real impls
    ├── features/             # Domain business components
    ├── store/                # ~30 zustand stores — `ls` for the full set
    └── ...                   # components, hooks, layout, libs, services, types, utils

架构图

层	位置
UI 组件	src/components、src/features
SPA 页面	src/routes/
React Router	src/spa/router/
全局 Provider	src/layout
Zustand Stores	src/store
客户端服务	src/services/
REST API	src/app/(backend)/webapi
tRPC Routers	apps/server/src/routers/{async|lambda|mobile|tools}
服务端服务	apps/server/src/services（可访问数据库）
服务端模块	apps/server/src/modules（无法访问数据库）
功能标志	apps/server/src/featureFlags
全局配置	apps/server/src/globalConfig
数据库架构	packages/database/src/schemas
数据库模型	packages/database/src/models
数据库存储库	packages/database/src/repositories
第三方服务	src/libs（分析、oidc 等）
内置工具	packages/builtin-tool-*、packages/builtin-tools
开源占位模块	src/business/*、packages/business/*（此仓库）

数据流

React UI → Store Actions → Client Service → TRPC Lambda → Server Services → DB Model → PostgreSQL

说明：与 Cloud 仓库的关系

这个开源仓库会被一个独立的私有云（SaaS）仓库作为 Git 子模块挂载在 lobehub/ 路径下使用。Cloud 仓库提供：

• src/business/{client,server} 和 packages/business/* 的实现，用于覆盖此处提供的存根。
• 仅 Cloud 提供的路由（例如 (cloud)/、embed/）、仅 Cloud 提供的存储（例如 subscription/）、仅 Cloud 提供的 TRPC 路由器（计费、预算、风险控制等），以及 src/app/(backend)/cron/ 下的 Vercel 定时任务路由。
• Cloud 中的文件解析顺序：@/store/x → 优先解析 Cloud 的 src/store/x，然后是 lobehub/packages/store/src/x，最后是 lobehub/src/store/x。Cloud 覆盖优先。

仅在此仓库中工作时，请忽略 Cloud 层——src/business/ 和 packages/business/ 中的存根是此处的事实来源。