SKILL.md
唯讀
名稱
project-overview
描述
LobeHub 開源 Monorepo 架構地圖。當需要定位程式碼架構分層、理解 apps/packages/src 的目錄配置、商業 Stub 占位檔、專案整體結構，或是需要快速熟悉此儲存庫（Onboarding）時使用。
LobeHub 專案總覽
以下目錄清單為精心整理的核心位置地圖，非完整詳盡的樹狀圖。
packages/、src/store/、路由群組（route groups）等會隨時間擴充——請在實際目錄執行ls以取得最新的完整結構。
專案描述
具備現代化設計的開源 AI Agent 工作區：LobeHub（前身為 LobeChat）。
本儲存庫為開源根專案（github.com/lobehub/lobehub，套件名稱 @lobehub/lobehub）。
支援平台：
- Web 桌面端 / 行動端
- 桌面端應用程式（Electron）—
apps/desktop - 行動端 App（React Native）— 獨立儲存庫，已正式上線（未包含在此 Monorepo 中）
Logo Emoji： 🤯
完整技術棧
| 類別 | 技術 |
|---|---|
| 框架 (Framework) | Next.js 16 + React 19 |
| 路由 (Routing) | Next.js 內建 SPA（搭配 react-router-dom） |
| 語言 (Language) | TypeScript |
| UI 元件 | @lobehub/ui、antd |
| CSS-in-JS | antd-style |
| 圖示 (Icons) | lucide-react、@ant-design/icons |
| 多語系 (i18n) | react-i18next |
| 狀態管理 (State) | zustand |
| URL 參數 | nuqs |
| 資料擷取 | SWR |
| React Hooks | aHooks |
| 日期/時間 | dayjs |
| 工具函式庫 | es-toolkit |
| API | TRPC（型別安全） |
| 資料庫 | Neon PostgreSQL + Drizzle ORM |
| 測試 (Testing) | Vitest |
精確的套件版本請參閱根目錄的
package.json——以該檔案為準。
Monorepo 目錄架構
扁平化配置——apps/、packages/ 與 src/ 均位於儲存庫根目錄。未採用 git submodules。
(repo root)
├── apps/
│ ├── cli/ # LobeHub CLI
│ ├── desktop/ # Electron 桌面端應用程式
│ ├── device-gateway/ # 裝置閘道器服務 (Device gateway service)
│ └── server/ # 基於 Next.js 的伺服器端：featureFlags, globalConfig, modules, routers, services, utils, workflows（別名 `@/server/*`）
├── docs/ # 更新日誌、開發指南、自主託管、使用說明 (changelog, development, self-hosting, usage)
├── locales/ # en-US, zh-CN, ...
├── packages/ # 約 80 個 @lobechat/* 工作區套件——請執行 `ls` 查看完整列表。核心套件包含：
│ ├── agent-runtime/ # Agent 執行階段核心 (Agent runtime core)
│ ├── agent-signal/ # Agent Signal 處理管道
│ ├── agent-tracing/ # 追蹤 / 快照 (Tracing / snapshots)
│ ├── builtin-tool-*/ # 單一工具套件（計算機、網頁瀏覽、claude-code 等）
│ ├── builtin-tools/ # 整合 builtin-tool-* 的中央註冊表
│ ├── context-engine/
│ ├── database/ # src/{models,schemas,repositories}
│ ├── model-bank/ # 模型定義與提供者卡片 (Model definitions & provider cards)
│ ├── model-runtime/ # src/{core,providers}
│ ├── locales/ # 多語系單一事實來源：packages/locales/src/default/
│ ├── env/ # 環境變數 schemas (@/envs/* → packages/env/src/*)
│ ├── app-config/
│ ├── business/ # 開源版 Stub 占位檔 (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/ # 開源版 Stub 占位檔 (client/server) — 雲端版儲存庫會提供實際實作
├── features/ # 領域業務元件 (Domain business components)
├── store/ # 約 30 個 zustand stores — 請執行 `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/ |
| 全域 Providers | src/layout |
| Zustand Stores 狀態 | src/store |
| 用戶端服務 (Client Services) | src/services/ |
| REST API | src/app/(backend)/webapi |
| tRPC Routers | apps/server/src/routers/{async|lambda|mobile|tools} |
| 伺服器端服務 (Server Services) | apps/server/src/services（可存取 DB） |
| 伺服器端模組 (Server Modules) | apps/server/src/modules（無法存取 DB） |
| 功能旗標 (Feature Flags) | apps/server/src/featureFlags |
| 全域配置 (Global Config) | apps/server/src/globalConfig |
| DB Schema | packages/database/src/schemas |
| DB Model | packages/database/src/models |
| DB Repository | packages/database/src/repositories |
| 第三方整合 (Third-party) | src/libs（分析、OIDC 等） |
| 內建工具 (Builtin Tools) | packages/builtin-tool-*, packages/builtin-tools |
| 開源預留 Stub 檔 | src/business/*, packages/business/*（本儲存庫） |
資料流向
React UI → Store Actions → Client Service → TRPC Lambda → Server Services → DB Model → PostgreSQL
注意：與雲端版儲存庫（Cloud Repo）的關係
此開源儲存庫被另一個獨立的私有雲端（SaaS）儲存庫引入，並以 Git Submodule 形式掛載於 lobehub/ 目錄。雲端版儲存庫提供了：
src/business/{client,server}與packages/business/*的完整實作，用於覆蓋本開源版中所提供的預留 Stub 檔。- 雲端版專用的路由（例如
(cloud)/、embed/）、雲端版專用的 stores（例如subscription/）、雲端版專用的 tRPC 路由（帳務、預算、風控等），以及位於src/app/(backend)/cron/下的 Vercel Cron 定時任務路由。 - 雲端版中的檔案解析優先順序（File-resolution order）：
@/store/x→ 優先載入雲端版的src/store/x，其次為lobehub/packages/store/src/x，最後才是lobehub/src/store/x。雲端版的覆蓋擁有最高優先權。
若僅在此儲存庫獨立開發，可直接忽略雲端層——本儲存庫中的 src/business/ 與 packages/business/ 的 Stub 檔即為此處的單一事實來源（Source of Truth）。
