SKILL.md
只读
名称
project-overview
描述
LobeHub 开源 Monorepo 架构全景图。用于定位代码层级、梳理 apps/packages/src 目录布局、了解业务存根（stub）、探究项目整体结构或快速上手熟悉该仓库。
LobeHub 项目全景概览
下方目录列表仅挑选了核心关键位置构成的架构地图，并非完整的目录树。
packages/、src/store/以及路由组等目录会随版本迭代不断扩充——若需获取最新完整的目录清单，请直接在真实目录下运行ls命令查看。
项目简介
现代感设计的开源 AI Agent 工作台：LobeHub（原 LobeChat）。
本仓库为 开源根仓库（github.com/lobehub/lobehub，包名为 @lobehub/lobehub）。
支持平台：
- Web 桌面端 / 移动端
- 桌面客户端 (Electron) —
apps/desktop - 移动端 App (React Native) — 独立仓库，已发布上线（不在当前 Monorepo 中）
Logo Emoji： 🤯
完整技术栈
| 分类 | 技术选型 |
|---|---|
| 框架 | Next.js 16 + React 19 |
| 路由 | 基于 Next.js 的 SPA，结合 react-router-dom |
| 语言 | TypeScript |
| UI 组件库 | @lobehub/ui、antd |
| CSS-in-JS | antd-style |
| 图标库 | lucide-react、@ant-design/icons |
| 国际化 (i18n) | react-i18next |
| 状态管理 | zustand |
| URL 参数 | nuqs |
| 数据请求 | SWR |
| React Hooks | aHooks |
| 日期时间 | dayjs |
| 工具函数 | es-toolkit |
| API 层 | TRPC (类型安全) |
| 数据库 | Neon PostgreSQL + Drizzle ORM |
| 测试 | Vitest |
确切的版本号请直接查阅根目录下的
package.json，以此处为准。
Monorepo 目录结构
平铺式结构——apps/、packages/ 和 src/ 均直接置于仓库根目录下，无 git submodule。
(repo root)
├── apps/
│ ├── cli/ # LobeHub CLI 工具
│ ├── desktop/ # Electron 桌面端应用
│ ├── device-gateway/ # 设备网关服务
│ └── server/ # 基于 Next.js 的服务端：featureFlags、globalConfig、modules、routers、services、utils、workflows（别名为 `@/server/*`）
├── docs/ # 更新日志、开发指南、私有化部署、使用说明
├── locales/ # en-US, zh-CN, ... 多语言文案
├── packages/ # ~80 个 @lobechat/* 工作区 packages — 完整列表请运行 `ls` 查看。核心包包括：
│ ├── agent-runtime/ # Agent 运行时核心
│ ├── agent-signal/ # Agent Signal 流水线
│ ├── agent-tracing/ # 链路追踪 / 快照
│ ├── builtin-tool-*/ # 各独立内置工具包 (calculator, web-browsing, claude-code, ...)
│ ├── builtin-tools/ # 组装 builtin-tool-* 的中央注册中心
│ ├── context-engine/
│ ├── database/ # src/{models,schemas,repositories} 数据库层
│ ├── model-bank/ # 模型定义与 Provider 卡片
│ ├── model-runtime/ # src/{core,providers} 模型运行时
│ ├── locales/ # i18n 唯一真实源：packages/locales/src/default/
│ ├── env/ # 环境变量 Schema (@/envs/* → packages/env/src/*)
│ ├── app-config/
│ ├── business/ # 开源版业务存根 (config, const, model-bank, model-runtime) — 云端版本会将其覆盖
│ ├── types/
│ └── utils/
└── src/
├── app/
│ ├── (backend)/ # api, f, market, middleware, oidc, trpc, webapi
│ ├── spa/ # SPA HTML 模板服务
│ └── spa-auth/ # 鉴权 HTML 壳 (SSR)
├── routes/ # SPA 页面分段（薄层 — 具体委托给 features/）
│ └── (main)/ (mobile)/ (desktop)/ (popup)/ auth/ onboarding/ share/
├── spa/ # SPA 入口 + 路由配置
│ ├── entry.{web,mobile,desktop,popup}.tsx
│ └── router/
├── business/ # 开源版业务存根（客户端/服务端）— 云端仓库提供真实实现
├── features/ # 领域业务组件
├── store/ # ~30 个 zustand store — 完整列表请运行 `ls` 查看
├── server/ # 仅含独立 Hono 服务端模块：agent-hono, workflows-hono（主后端位于 `apps/server`）
└── ... # components, hooks, layout, libs, services, types, utils
架构映射表
| 层级 | 所在位置 |
|---|---|
| UI 组件 | src/components、src/features |
| SPA 页面 | src/routes/ |
| React Router | src/spa/router/ |
| 全局 Provider | src/layout |
| Zustand Store | src/store |
| 客户端 Service | src/services/ |
| REST API | src/app/(backend)/webapi |
| tRPC Router | apps/server/src/routers/{async|lambda|mobile|tools} |
| 服务端 Service | apps/server/src/services（可直接操作 DB） |
| 服务端 Module | apps/server/src/modules（无 DB 访问权限） |
| 功能开关 | apps/server/src/featureFlags |
| 全局配置 | apps/server/src/globalConfig |
| DB Schema | packages/database/src/schemas |
| DB Model | packages/database/src/models |
| DB Repository | packages/database/src/repositories |
| 第三方集成 | src/libs（统计分析、OIDC 等） |
| 内置工具 | packages/builtin-tool-*、packages/builtin-tools |
| 开源业务存根 | src/business/*、packages/business/*（本仓库内） |
数据流向
React UI → Store Actions → 客户端 Service → TRPC Lambda → 服务端 Service → DB Model → PostgreSQL
注意事项：与云端 (Cloud) 仓库的关系
当前开源仓库会被一个独立的私有云端 (SaaS) 仓库作为 git submodule 挂载在 lobehub/ 目录下引入。云端仓库额外提供：
src/business/{client,server}与packages/business/*的具体业务实现，用来覆盖本开源仓库中的 Stub 存根。- 云端专属路由（如
(cloud)/、embed/）、云端专属 Store（如subscription/）、云端专属 tRPC 路由（计费、预算、风控等），以及位于src/app/(backend)/cron/下的 Vercel Cron 定时任务路由。 - 云端环境下的文件解析优先级：
@/store/x→ 优先解析云端src/store/x，其次是lobehub/packages/store/src/x，最后才是lobehub/src/store/x。即云端覆盖优先（Cloud override wins）。
若仅在当前开源仓库中开发，忽略云端层即可——src/business/ 与 packages/business/ 中的存根代码即为当前仓库的唯一真实源（Source of truth）。
