From ed2ce8d32f0ba317fbbf9207cecd212d7e82daa9 Mon Sep 17 00:00:00 2001 From: YuTengjing Date: Thu, 29 May 2025 15:46:27 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=20some=20cursor=20ru?= =?UTF-8?q?les=20&=20optimize=20codebase=20indexing=20(#7999)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📝 docs: add some cursor rules & optimize codebase indexing * 📝 docs: some code reviews issue by greptile --- .cursor/rules/backend-architecture.mdc | 94 +++++++++ .cursor/rules/cursor-ux-optimize.mdc | 27 +++ .cursor/rules/define-database-model.mdc | 8 + .cursor/rules/drizzle-schema-style-guide.mdc | 202 +++++++++++++++++++ .cursor/rules/i18n/i18n-auto-attached.mdc | 6 + .cursor/rules/i18n/i18n.mdc | 183 +++++++++++++++++ .cursor/rules/packages/lobe-ui.mdc | 72 +++++++ .cursor/rules/packages/react-layout-kit.mdc | 126 ++++++++++++ .cursor/rules/project-introduce.mdc | 46 +++++ .cursor/rules/react-component.mdc | 68 +++++++ .cursorindexingignore | 6 + 11 files changed, 838 insertions(+) create mode 100644 .cursor/rules/backend-architecture.mdc create mode 100644 .cursor/rules/cursor-ux-optimize.mdc create mode 100644 .cursor/rules/define-database-model.mdc create mode 100644 .cursor/rules/drizzle-schema-style-guide.mdc create mode 100644 .cursor/rules/i18n/i18n-auto-attached.mdc create mode 100644 .cursor/rules/i18n/i18n.mdc create mode 100644 .cursor/rules/packages/lobe-ui.mdc create mode 100644 .cursor/rules/packages/react-layout-kit.mdc create mode 100644 .cursor/rules/project-introduce.mdc create mode 100644 .cursor/rules/react-component.mdc create mode 100644 .cursorindexingignore diff --git a/.cursor/rules/backend-architecture.mdc b/.cursor/rules/backend-architecture.mdc new file mode 100644 index 0000000000..3f3b5acf2e --- /dev/null +++ b/.cursor/rules/backend-architecture.mdc @@ -0,0 +1,94 @@ +--- +description: +globs: src/services/**/*,src/database/**/*,src/server/**/* +alwaysApply: false +--- +# LobeChat 后端技术架构指南 + +本指南旨在阐述 LobeChat 项目的后端分层架构，重点介绍各核心目录的职责以及它们之间的协作方式。 + +## 目录结构映射 + +``` +src/ +├── server/ +│ ├── routers/ # tRPC API 路由定义 +│ └── services/ # 业务逻辑服务层 +│ └── */impls/ # 平台特定实现 +├── database/ +│ ├── models/ # 数据模型 (单表 CRUD) +│ ├── repositories/ # 仓库层 (复杂查询/聚合) +│ └── schemas/ # Drizzle ORM 表定义 +└── services/ # 客户端服务 (调用 tRPC 或直接访问 Model) +``` + +## 核心架构分层 + +LobeChat 的后端设计注重模块化、可测试性和灵活性，以适应不同的运行环境（如浏览器端 PGLite、服务端远程 PostgreSQL 以及 Electron 桌面应用）。 + +其主要分层如下： + +1. **客户端服务层 (`src/services`)**: + * 位于 [src/services/](mdc:src/services)。 + * 这是客户端业务逻辑的核心层，负责封装各种业务操作和数据处理逻辑。 + * **环境适配**: 根据不同的运行环境，服务层会选择合适的数据访问方式： + * **本地数据库模式**: 直接调用 `Model` 层进行数据操作，适用于浏览器 PGLite 和本地 Electron 应用。 + * **远程数据库模式**: 通过 `tRPC` 客户端调用服务端 API，适用于需要云同步的场景。 + * **类型转换**: 对于简单的数据类型转换，直接在此层进行类型断言，如 `this.pluginModel.query() as Promise`（参见 [src/services/plugin/client.ts](mdc:src/services/plugin/client.ts)）。 + * 每个服务模块通常包含 `client.ts`（本地模式）、`server.ts`（远程模式）和 `type.ts`（接口定义）文件。 + +2. **API 接口层 (`TRPC`)**: + * 位于 [src/server/routers/](mdc:src/server/routers)。 + * 使用 `tRPC` 构建类型安全的 API。Router 根据运行时环境（如 Edge Functions, Node.js Lambda）进行组织。 + * 负责接收客户端请求，并将其路由到相应的 `Service` 层进行处理。 + +3. **服务端服务层 (`server/services`)**: + * 位于 [src/server/services/](mdc:src/server/services)。 + * 核心职责是封装独立的、可复用的业务逻辑单元。这些服务应易于测试。 + * **平台差异抽象**: 一个关键特性是通过其内部的 `impls` 子目录（例如 [src/server/services/file/impls/](mdc:src/server/services/file/impls) 包含 `s3.ts` 和 `local.ts`）来抹平不同运行环境带来的差异（例如云端使用 S3 存储，桌面版使用本地文件系统）。这使得上层（如 `tRPC` routers）无需关心底层具体实现。 + * 目标是使 `tRPC` router 层的逻辑尽可能纯粹，专注于请求处理和业务流程编排。 + * 服务会调用 `Repository` 层或直接调用 `Model` 层进行数据持久化和检索，也可能调用其他服务。 + +4. **仓库层 (`Repositories`)**: + * 位于 [src/database/repositories/](mdc:src/database/repositories)。 + * 主要处理**复杂的跨表查询和数据聚合**逻辑，特别是当需要从**多个 `Model`** 获取数据并进行组合时。 + * 与 `Model` 层不同，`Repository` 层专注于复杂的业务查询场景，而不涉及简单的领域模型转换。 + * 当业务逻辑涉及多表关联、复杂的数据统计或需要事务处理时，会使用 `Repository` 层。 + * 如果数据操作简单（仅涉及单个 `Model`），则通常直接在 `src/services` 层调用 `Model` 并进行简单的类型断言。 + +5. **模型层 (`Models`)**: + * 位于 [src/database/models/](mdc:src/database/models) (例如 [src/database/models/plugin.ts](mdc:src/database/models/plugin.ts) 和 [src/database/models/document.ts](mdc:src/database/models/document.ts))。 + * 提供对数据库中各个表（由 [src/database/schemas/](mdc:src/database/schemas) 中的 Drizzle ORM schema 定义）的基本 CRUD (创建、读取、更新、删除) 操作和简单的查询能力。 + * `Model` 类专注于单个数据表的直接操作，**不涉及复杂的领域模型转换**，这些转换通常在上层的 `src/services` 中通过类型断言完成。 + +6. **数据库 (`Database`)**: + * **客户端模式 (浏览器/PWA)**: 使用 PGLite (基于 WASM 的 PostgreSQL)，数据存储在用户浏览器本地。 + * **服务端模式 (云部署)**: 使用远程 PostgreSQL 数据库。 + * **Electron 桌面应用**: + * Electron 客户端会启动一个本地 Node.js 服务。 + * 本地服务通过 `tRPC` 与 Electron 的渲染进程通信。 + * 数据库选择依赖于是否开启**云同步**功能： + * **云同步开启**: 连接到远程 PostgreSQL 数据库。 + * **云同步关闭**: 使用 PGLite (通过 Node.js 的 WASM 实现) 在本地存储数据。 + +## 数据流向说明 + +### 浏览器/PWA 模式 +``` +UI (React) → Zustand State → Model Layer → PGLite (本地数据库) +``` + +### 服务端模式 +``` +UI (React) → Zustand State → tRPC Client → tRPC Routers → Services → Repositories/Models → Remote PostgreSQL +``` + +### Electron 桌面应用模式 +``` +UI (Electron Renderer) → Zustand State → tRPC Client → 本地 Node.js 服务 → tRPC Routers → Services → Repositories/Models → PGLite/Remote PostgreSQL (取决于云同步设置) +``` + + + + + diff --git a/.cursor/rules/cursor-ux-optimize.mdc b/.cursor/rules/cursor-ux-optimize.mdc new file mode 100644 index 0000000000..d8eae2b794 --- /dev/null +++ b/.cursor/rules/cursor-ux-optimize.mdc @@ -0,0 +1,27 @@ +--- +description: +globs: +alwaysApply: false +--- +## Formatting Response + +This is about how you should format your responses. + +### Render Markdown Table + +- Be aware that the cursor chat you are in can't render markdown table correctly. +- IMPORTANT: Tables need to be rendered in plain text and not markdown + +When rendering tables, do not use markdown table syntax or plain text alone. Instead, place the entire table inside a code/text block (using triple backticks). This ensures the table formatting is preserved and readable in the chat interface. + +Example: + +```plaintext ++----+---------+-----------+ +| ID | Name | Role | ++----+---------+-----------+ +| 1 | Alice | Admin | +| 2 | Bob | User | +| 3 | Charlie | Moderator | ++----+---------+-----------+ +``` \ No newline at end of file diff --git a/.cursor/rules/define-database-model.mdc b/.cursor/rules/define-database-model.mdc new file mode 100644 index 0000000000..a149c2886c --- /dev/null +++ b/.cursor/rules/define-database-model.mdc @@ -0,0 +1,8 @@ +--- +description: +globs: src/database/models/**/* +alwaysApply: false +--- +1. first read [lobe-chat-backend-architecture.mdc](mdc:.cursor/rules/lobe-chat-backend-architecture.mdc) +2. refer to the [_template.ts](mdc:src/database/models/_template.ts) to create new model +3. if an operation involves multiple models or complex queries, consider defining it in the `repositories` layer under `src/database/repositories/` \ No newline at end of file diff --git a/.cursor/rules/drizzle-schema-style-guide.mdc b/.cursor/rules/drizzle-schema-style-guide.mdc new file mode 100644 index 0000000000..ac91063914 --- /dev/null +++ b/.cursor/rules/drizzle-schema-style-guide.mdc @@ -0,0 +1,202 @@ +--- +description: +globs: src/database/schemas/* +alwaysApply: false +--- +# Drizzle ORM Schema Style Guide for lobe-chat + +This document outlines the conventions and best practices for defining PostgreSQL Drizzle ORM schemas within the lobe-chat project. + +## Configuration + +- Drizzle configuration is managed in [drizzle.config.ts](mdc:drizzle.config.ts) +- Schema files are located in the src/database/schemas/ directory +- Migration files are output to `src/database/migrations/` +- The project uses `postgresql` dialect with `strict: true` + +## Helper Functions + +Commonly used column definitions, especially for timestamps, are centralized in [src/database/schemas/_helpers.ts](mdc:src/database/schemas/_helpers.ts): +- `timestamptz(name: string)`: Creates a timestamp column with timezone +- `createdAt()`, `updatedAt()`, `accessedAt()`: Helper functions for standard timestamp columns +- `timestamps`: An object `{ createdAt, updatedAt, accessedAt }` for easy inclusion in table definitions + +## Naming Conventions + +- **Table Names**: Use plural snake_case (e.g., `users`, `agents`, `session_groups`) +- **Column Names**: Use snake_case (e.g., `user_id`, `created_at`, `background_color`) + +## Column Definitions + +### Primary Keys (PKs) +- Typically `text('id')` (or `varchar('id')` for some OIDC tables) +- Often use `.$defaultFn(() => idGenerator('table_name'))` for automatic ID generation with meaningful prefixes +- **ID Prefix Purpose**: Makes it easy for users and developers to distinguish different entity types at a glance +- For internal/system tables that users don't need to see, can use `uuid` or auto-increment keys +- Composite PKs are defined using `primaryKey({ columns: [t.colA, t.colB] })` + +### Foreign Keys (FKs) +- Defined using `.references(() => otherTable.id, { onDelete: 'cascade' | 'set null' | 'no action' })` +- FK columns are usually named `related_table_singular_name_id` (e.g., `user_id` references `users.id`) +- Most tables include a `user_id` column referencing `users.id` with `onDelete: 'cascade'` + +### Timestamps +- Consistently use the `...timestamps` spread from [_helpers.ts](mdc:src/database/schemas/_helpers.ts) for `created_at`, `updated_at`, and `accessed_at` columns + +### Default Values +- `.$defaultFn(() => expression)` for dynamic defaults (e.g., `idGenerator()`, `randomSlug()`) +- `.default(staticValue)` for static defaults (e.g., `boolean('enabled').default(true)`) + +### Indexes +- Defined in the table's second argument: `pgTable('name', {...columns}, (t) => ({ indexName: indexType().on(...) }))` +- Use `uniqueIndex()` for unique constraints and `index()` for non-unique indexes +- Naming pattern: `table_name_column(s)_idx` or `table_name_column(s)_unique` +- Many tables feature a `clientId: text('client_id')` column, often part of a composite unique index with `user_id` + +### Data Types +- Common types: `text`, `varchar`, `jsonb`, `boolean`, `integer`, `uuid`, `pgTable` +- For `jsonb` fields, specify the TypeScript type using `.$type()` for better type safety + +## Zod Schemas & Type Inference + +- Utilize `drizzle-zod` to generate Zod schemas for validation: + - `createInsertSchema(tableName)` + - `createSelectSchema(tableName)` (less common) +- Export inferred types: `export type NewEntity = typeof tableName.$inferInsert;` and `export type EntityItem = typeof tableName.$inferSelect;` + +## Relations + +- Table relationships are defined centrally in [src/database/schemas/relations.ts](mdc:src/database/schemas/relations.ts) using the `relations()` utility from `drizzle-orm` + +## Code Style & Structure + +- **File Organization**: Each main database entity typically has its own schema file (e.g., [user.ts](mdc:src/database/schemas/user.ts), [agent.ts](mdc:src/database/schemas/agent.ts)) +- All schemas are re-exported from [src/database/schemas/index.ts](mdc:src/database/schemas/index.ts) +- **ESLint**: Files often start with `/* eslint-disable sort-keys-fix/sort-keys-fix */` +- **Comments**: Use JSDoc-style comments to explain the purpose of tables and complex columns, fields that are self-explanatory do not require jsdoc explanations, such as id, user_id, etc. + +## Example Pattern + +```typescript +// From src/database/schemas/agent.ts +export const agents = pgTable( + 'agents', + { + id: text('id') + .primaryKey() + .$defaultFn(() => idGenerator('agents')) + .notNull(), + slug: varchar('slug', { length: 100 }) + .$defaultFn(() => randomSlug(4)) + .unique(), + userId: text('user_id') + .references(() => users.id, { onDelete: 'cascade' }) + .notNull(), + clientId: text('client_id'), + chatConfig: jsonb('chat_config').$type(), + ...timestamps, + }, + // return array instead of object, the object style is deprecated + (t) => [ + uniqueIndex('client_id_user_id_unique').on(t.clientId, t.userId), + ], +); + +export const insertAgentSchema = createInsertSchema(agents); +export type NewAgent = typeof agents.$inferInsert; +export type AgentItem = typeof agents.$inferSelect; +``` + +## Common Patterns + +### 1. userId + clientId Pattern (Legacy) +Some existing tables include both fields for different purposes: + +```typescript +// Example from agents table (legacy pattern) +userId: text('user_id') + .references(() => users.id, { onDelete: 'cascade' }) + .notNull(), +clientId: text('client_id'), + +// Usually with a composite unique index +clientIdUnique: uniqueIndex('agents_client_id_user_id_unique').on(t.clientId, t.userId), +``` + +- **`userId`**: Server-side user association, ensures data belongs to specific user +- **`clientId`**: Unique key for import/export operations, supports data migration between instances +- **Current Status**: New tables should NOT include `clientId` unless specifically needed for import/export functionality +- **Note**: This pattern is being phased out for new features to simplify the schema + +### 2. Junction Tables (Many-to-Many Relationships) +Use composite primary keys for relationship tables: + +```typescript +// Example: agents_knowledge_bases (from agent.ts) +export const agentsKnowledgeBases = pgTable( + 'agents_knowledge_bases', + { + agentId: text('agent_id').references(() => agents.id, { onDelete: 'cascade' }).notNull(), + knowledgeBaseId: text('knowledge_base_id').references(() => knowledgeBases.id, { onDelete: 'cascade' }).notNull(), + userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }).notNull(), + enabled: boolean('enabled').default(true), + ...timestamps, + }, + (t) => [ + primaryKey({ columns: [t.agentId, t.knowledgeBaseId] }), + ], +); +``` + +**Pattern**: `{entity1}Id` + `{entity2}Id` as composite PK, plus `userId` for ownership + +### 3. OIDC Tables Special Patterns +OIDC tables use `varchar` IDs instead of `text` with custom generators: + +```typescript +// Example from oidc.ts +export const oidcAuthorizationCodes = pgTable('oidc_authorization_codes', { + id: varchar('id', { length: 255 }).primaryKey(), // varchar not text + data: jsonb('data').notNull(), + expiresAt: timestamptz('expires_at').notNull(), + // ... other fields +}); +``` + +**Reason**: OIDC standards expect specific ID formats and lengths + +### 4. File Processing with Async Tasks +File-related tables reference async task IDs for background processing: + +```typescript +// Example from files table +export const files = pgTable('files', { + // ... other fields + chunkTaskId: uuid('chunk_task_id').references(() => asyncTasks.id, { onDelete: 'set null' }), + embeddingTaskId: uuid('embedding_task_id').references(() => asyncTasks.id, { onDelete: 'set null' }), + // ... +}); +``` + +**Purpose**: +- Track file chunking progress (breaking files into smaller pieces) +- Track embedding generation progress (converting text to vectors) +- Allow querying task status and handling failures + +### 5. Slug Pattern (Legacy) +Some entities include auto-generated slugs - this is legacy code: + +```typescript +slug: varchar('slug', { length: 100 }) + .$defaultFn(() => randomSlug(4)) + .unique(), + +// Often with composite unique constraint +slugUserIdUnique: uniqueIndex('slug_user_id_unique').on(t.slug, t.userId), +``` + +**Current usage**: Only used to identify default agents/sessions (legacy pattern) +**Future refactor**: Will likely be replaced with `isDefault: boolean()` field +**Note**: Avoid using slugs for new features - prefer explicit boolean flags for status tracking + +By following these guidelines, maintain consistency, type safety, and maintainability across database schema definitions. \ No newline at end of file diff --git a/.cursor/rules/i18n/i18n-auto-attached.mdc b/.cursor/rules/i18n/i18n-auto-attached.mdc new file mode 100644 index 0000000000..50b8c5f27d --- /dev/null +++ b/.cursor/rules/i18n/i18n-auto-attached.mdc @@ -0,0 +1,6 @@ +--- +description: +globs: src/locales/**/* +alwaysApply: false +--- +read [i18n.mdc](mdc:.cursor/rules/i18n/i18n.mdc) \ No newline at end of file diff --git a/.cursor/rules/i18n/i18n.mdc b/.cursor/rules/i18n/i18n.mdc new file mode 100644 index 0000000000..b6b3e65267 --- /dev/null +++ b/.cursor/rules/i18n/i18n.mdc @@ -0,0 +1,183 @@ +--- +description: i18n workflow and troubleshooting +globs: +alwaysApply: false +--- +# LobeChat Internationalization (i18n) Guide + +## Architecture Overview + +LobeChat uses **react-i18next** for internationalization with a well-structured namespace approach: + +- **Default language**: Chinese (zh-CN) - serves as the source language +- **Supported locales**: 18 languages including English, Japanese, Korean, Arabic, etc. +- **Framework**: react-i18next with Next.js app router +- **Translation automation**: [@lobehub/i18n-cli](mdc:package.json) for automated translations, config file: .i18nrc.js + +## Directory Structure + +``` +src/locales/ +├── default/ # Source language files (zh-CN) +│ ├── index.ts # Namespace exports +│ ├── common.ts # Common translations +│ ├── chat.ts # Chat-related translations +│ ├── setting.ts # Settings translations +│ └── ... # Other namespace files +└── resources.ts # Type definitions and locale config + +locales/ # Translated files +├── en-US/ # English translations +│ ├── common.json # Common translations +│ ├── chat.json # Chat translations +│ ├── setting.json # Settings translations +│ └── ... # Other namespace JSON files +├── ja-JP/ # Japanese translations +│ ├── common.json +│ ├── chat.json +│ └── ... +└── ... # Other language folders +``` + +## Workflow for Adding New Translations + +### 1. Add New Translation Keys + +**Step 1**: Add translation key to the appropriate namespace file in [src/locales/default/](mdc:src/locales/default) + +```typescript +// Example: src/locales/default/common.ts +export default { + // ... existing keys + newFeature: { + title: "新功能标题", + description: "功能描述文案", + button: "操作按钮", + }, +}; +``` + +**Step 2**: If creating a new namespace, export it in [src/locales/default/index.ts](mdc:src/locales/default/index.ts) + +```typescript +import newNamespace from "./newNamespace"; + +const resources = { + // ... existing namespaces + newNamespace, +} as const; +``` + +### 2. Translation Process + +**Development Mode** (Recommended): + +- Manually add Chinese translations to corresponding JSON files in `locales/zh-CN/namespace.json`, this avoids running slow automation during development +- Don't auto add translations for other language like English etc, most of developer is Chinese, + +**Production Mode**: + +```bash +# Generate translations for all languages +npm run i18n +``` + +## Usage in Components + +### Basic Usage with Hooks + +```tsx +import { useTranslation } from "react-i18next"; + +const MyComponent = () => { + const { t } = useTranslation("common"); // namespace + + return ( +
+

{t("newFeature.title")}

+

{t("newFeature.description")}

+ +
+ ); +}; +``` + +### With Parameters + +```tsx +const { t } = useTranslation("common"); + +// Translation key with interpolation +

{t("welcome.message", { name: "John" })}

; + +// Corresponding locale file: +// welcome: { message: '欢迎 {{name}} 使用!' } +``` + +### Multiple Namespaces + +```tsx +const { t } = useTranslation(['common', 'chat']); + +// Access different namespaces + +{t('chat:typing')} +``` + +## Type Safety + +The project uses TypeScript for type-safe translations with auto-generated types from [src/locales/resources.ts](mdc:src/locales/resources.ts): + +```typescript +import type { DefaultResources, NS, Locales } from "@/locales/resources"; + +// Available types: +// - NS: Available namespace keys ('common' | 'chat' | 'setting' | ...) +// - Locales: Supported locale codes ('en-US' | 'zh-CN' | 'ja-JP' | ...) + +// Type-safe namespace usage +const namespace: NS = "common"; // ✅ Valid +const locale: Locales = "en-US"; // ✅ Valid +``` + +## Best Practices + +### 1. Namespace Organization + +- **common**: Shared UI elements (buttons, labels, actions) +- **chat**: Chat-specific features +- **setting**: Configuration and settings +- **error**: Error messages and handling +- **[feature]**: Feature-specific or page specific namespaces + +### 2. Key Naming Conventions + +```typescript +// ✅ Good: Hierarchical structure +export default { + modal: { + confirm: { + title: "确认操作", + message: "确定要执行此操作吗？", + actions: { + confirm: "确认", + cancel: "取消", + }, + }, + }, +}; + +// ❌ Avoid: Flat structure +export default { + modalConfirmTitle: "确认操作", + modalConfirmMessage: "确定要执行此操作吗？", +}; +``` + +## Troubleshooting + +### Missing Translation Keys + +- Check if the key exists in src/locales/default/namespace.ts +- Ensure proper namespace import in component +- Ensure new namespaces are exported in [src/locales/default/index.ts](mdc:src/locales/default/index.ts) \ No newline at end of file diff --git a/.cursor/rules/packages/lobe-ui.mdc b/.cursor/rules/packages/lobe-ui.mdc new file mode 100644 index 0000000000..f83ef55304 --- /dev/null +++ b/.cursor/rules/packages/lobe-ui.mdc @@ -0,0 +1,72 @@ +--- +description: @lobehub/ui components list +globs: +alwaysApply: false +--- +## @lobehub/ui Components + +- General + ActionIcon + ActionIconGroup + Block + Button + Icon +- Data Display + Avatar + Collapse + FileTypeIcon + FluentEmoji + GuideCard + Highlighter + Hotkey + Image + List + Markdown + MaterialFileTypeIcon + Mermaid + Segmented + Snippet + SortableList + Tag + Tooltip + Video +- Data Entry + AutoComplete + CodeEditor + ColorSwatches + CopyButton + DatePicker + EditableText + EmojiPicker + Form + FormModal + HotkeyInput + ImageSelect + Input + SearchBar + Select + SliderWithInput + ThemeSwitch +- Feedback + Alert + Drawer + Modal +- Layout + DraggablePanel + Footer + Grid + Header + Layout + MaskShadow + ScrollShadow +- Navigation + Burger + Dropdown + Menu + SideNav + Tabs + Toc +- Theme + ConfigProvider + FontLoader + ThemeProvider \ No newline at end of file diff --git a/.cursor/rules/packages/react-layout-kit.mdc b/.cursor/rules/packages/react-layout-kit.mdc new file mode 100644 index 0000000000..cf69912983 --- /dev/null +++ b/.cursor/rules/packages/react-layout-kit.mdc @@ -0,0 +1,126 @@ +--- +description: react flex layout package `react-layout-kit` usage +globs: +alwaysApply: false +--- +# React Layout Kit 使用指南 + +`react-layout-kit` 是一个功能丰富的 React flex 布局组件库，在 lobe-chat 项目中被广泛使用。以下是重点组件的使用方法： + +## Flexbox 组件 + +Flexbox 是最常用的布局组件，用于创建弹性布局，类似于 CSS 的 `display: flex`。 + +### 基本用法 + +```jsx +import { Flexbox } from 'react-layout-kit'; + +// 默认垂直布局 + +
子元素1
+
子元素2
+ + +// 水平布局 + +
左侧元素
+
右侧元素
+ +``` + +### 常用属性 + +- `horizontal`: 布尔值，设置为水平方向布局 +- `flex`: 数值或字符串，控制 flex 属性 +- `gap`: 数值，设置子元素之间的间距 +- `align`: 对齐方式，如 'center', 'flex-start' 等 +- `justify`: 主轴对齐方式，如 'space-between', 'center' 等 +- `padding`: 内边距值 +- `paddingInline`: 水平内边距值 +- `paddingBlock`: 垂直内边距值 +- `width/height`: 设置宽高，通常用 `'100%'` 或具体像素值 +- `style`: 自定义样式对象 + +### 实际应用示例 + +```jsx +// 经典三栏布局 + + {/* 左侧边栏 */} + + + + + {/* 中间内容区 */} + + {/* 主要内容 */} + + + + + {/* 底部区域 */} + +