@lobehub/lobehub 2.0.0-next.353 → 2.0.0-next.355

package/.agents/skills/modal/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: modal
+description: Modal imperative API guide. Use when creating modal dialogs using createModal from @lobehub/ui. Triggers on modal component implementation or dialog creation tasks.
+user-invocable: false
+---
+
+# Modal Imperative API Guide
+
+Use `createModal` from `@lobehub/ui` for imperative modal dialogs.
+
+## Why Imperative?
+
+| Mode | Characteristics | Recommended |
+|------|-----------------|-------------|
+| Declarative | Need `open` state, render `<Modal />` | ❌ |
+| Imperative | Call function directly, no state | ✅ |
+
+## File Structure
+
+```
+features/
+└── MyFeatureModal/
+    ├── index.tsx           # Export createXxxModal
+    └── MyFeatureContent.tsx # Modal content
+```
+
+## Implementation
+
+### 1. Content Component (`MyFeatureContent.tsx`)
+
+```tsx
+'use client';
+
+import { useModalContext } from '@lobehub/ui';
+import { useTranslation } from 'react-i18next';
+
+export const MyFeatureContent = () => {
+  const { t } = useTranslation('namespace');
+  const { close } = useModalContext(); // Optional: get close method
+
+  return <div>{/* Modal content */}</div>;
+};
+```
+
+### 2. Export createModal (`index.tsx`)
+
+```tsx
+'use client';
+
+import { createModal } from '@lobehub/ui';
+import { t } from 'i18next'; // Note: use i18next, not react-i18next
+
+import { MyFeatureContent } from './MyFeatureContent';
+
+export const createMyFeatureModal = () =>
+  createModal({
+    allowFullscreen: true,
+    children: <MyFeatureContent />,
+    destroyOnHidden: false,
+    footer: null,
+    styles: { body: { overflow: 'hidden', padding: 0 } },
+    title: t('myFeature.title', { ns: 'setting' }),
+    width: 'min(80%, 800px)',
+  });
+```
+
+### 3. Usage
+
+```tsx
+import { createMyFeatureModal } from '@/features/MyFeatureModal';
+
+const handleOpen = useCallback(() => {
+  createMyFeatureModal();
+}, []);
+
+return <Button onClick={handleOpen}>Open</Button>;
+```
+
+## i18n Handling
+
+- **Content component**: `useTranslation` hook (React context)
+- **createModal params**: `import { t } from 'i18next'` (non-hook, imperative)
+
+## useModalContext Hook
+
+```tsx
+const { close, setCanDismissByClickOutside } = useModalContext();
+```
+
+## Common Config
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `allowFullscreen` | `boolean` | Allow fullscreen mode |
+| `destroyOnHidden` | `boolean` | Destroy content on close |
+| `footer` | `ReactNode \| null` | Footer content |
+| `width` | `string \| number` | Modal width |
+
+## Examples
+
+- `src/features/SkillStore/index.tsx`
+- `src/features/LibraryModal/CreateNew/index.tsx`

package/{.cursor/rules/project-structure.mdc → .agents/skills/project-overview/SKILL.md}

@@ -1,19 +1,50 @@
 ---
-alwaysApply: true
+name: project-overview
+description: Complete project architecture and structure guide. Use when exploring the codebase, understanding project organization, finding files, or needing comprehensive architectural context. Triggers on architecture questions, directory navigation, or project overview needs.
 ---
 
-# LobeChat Project Structure
+# LobeChat Project Overview
 
-## Complete Project Structure
+## Project Description
+
+Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat).
+
+**Supported platforms:**
+- Web desktop/mobile
+- Desktop (Electron)
+- Mobile app (React Native) - coming soon
+
+**Logo emoji:** 🤯
+
+## Complete Tech Stack
 
-This project uses common monorepo structure. The workspace packages name use `@lobechat/` namespace.
+| Category | Technology |
+|----------|------------|
+| Framework | Next.js 16 + React 19 |
+| Routing | SPA inside Next.js with `react-router-dom` |
+| Language | TypeScript |
+| UI Components | `@lobehub/ui`, antd |
+| CSS-in-JS | antd-style |
+| Icons | lucide-react, `@ant-design/icons` |
+| i18n | react-i18next |
+| State | zustand |
+| URL Params | nuqs |
+| Data Fetching | SWR |
+| React Hooks | aHooks |
+| Date/Time | dayjs |
+| Utilities | es-toolkit |
+| API | TRPC (type-safe) |
+| Database | Neon PostgreSQL + Drizzle ORM |
+| Testing | Vitest |
 
-**note**: some not very important files are not shown for simplicity.
+## Complete Project Structure
+
+Monorepo using `@lobechat/` namespace for workspace packages.
 
-```plaintext
+```
 lobe-chat/
 ├── apps/
-│   └── desktop/
+│   └── desktop/                 # Electron desktop app
 ├── docs/
 │   ├── changelog/
 │   ├── development/
@@ -23,10 +54,10 @@ lobe-chat/
 │   ├── en-US/
 │   └── zh-CN/
 ├── packages/
-│   ├── agent-runtime/
+│   ├── agent-runtime/           # Agent runtime
 │   ├── builtin-agents/
-│   ├── builtin-tool-*/           # builtin tool packages
-│   ├── business/                 # cloud-only business logic packages
+│   ├── builtin-tool-*/          # Builtin tool packages
+│   ├── business/                # Cloud-only business logic
 │   │   ├── config/
 │   │   ├── const/
 │   │   └── model-runtime/
@@ -59,8 +90,6 @@ lobe-chat/
 │   ├── types/
 │   ├── utils/
 │   └── web-crawler/
-├── public/
-├── scripts/
 ├── src/
 │   ├── app/
 │   │   ├── (backend)/
@@ -78,7 +107,7 @@ lobe-chat/
 │   │   │   ├── onboarding/
 │   │   │   └── router/
 │   │   └── desktop/
-│   ├── business/                 # cloud-only business logic (client/server)
+│   ├── business/                # Cloud-only (client/server)
 │   │   ├── client/
 │   │   ├── locales/
 │   │   └── server/
@@ -117,33 +146,32 @@ lobe-chat/
 │   ├── tools/
 │   ├── types/
 │   └── utils/
-└── package.json
+└── e2e/                         # E2E tests (Cucumber + Playwright)
 ```
 
 ## Architecture Map
 
-- UI Components: `src/components`, `src/features`
-- Global providers: `src/layout`
-- Zustand stores: `src/store`
-- Client Services: `src/services/`
-- API Routers:
-  - `src/app/(backend)/webapi` (REST)
-  - `src/server/routers/{async|lambda|mobile|tools}` (tRPC)
-- Server:
-  - Services (can access serverDB): `src/server/services`
-  - Modules (can't access db): `src/server/modules`
-  - Feature Flags: `src/server/featureFlags`
-  - Global Config: `src/server/globalConfig`
-- Database:
-  - Schema (Drizzle): `packages/database/src/schemas`
-  - Model (CRUD): `packages/database/src/models`
-  - Repository (bff-queries): `packages/database/src/repositories`
-- Third-party Integrations: `src/libs` — analytics, oidc etc.
-- Builtin Tools: `src/tools`, `packages/builtin-tool-*`
-- Business (cloud-only): Code specific to LobeHub cloud service, only expose empty interfaces for opens-source version.
-  - `src/business/*`
-  - `packages/business/*`
+| Layer | Location |
+|-------|----------|
+| UI Components | `src/components`, `src/features` |
+| Global Providers | `src/layout` |
+| Zustand Stores | `src/store` |
+| Client Services | `src/services/` |
+| REST API | `src/app/(backend)/webapi` |
+| tRPC Routers | `src/server/routers/{async\|lambda\|mobile\|tools}` |
+| Server Services | `src/server/services` (can access DB) |
+| Server Modules | `src/server/modules` (no DB access) |
+| Feature Flags | `src/server/featureFlags` |
+| Global Config | `src/server/globalConfig` |
+| DB Schema | `packages/database/src/schemas` |
+| DB Model | `packages/database/src/models` |
+| DB Repository | `packages/database/src/repositories` |
+| Third-party | `src/libs` (analytics, oidc, etc.) |
+| Builtin Tools | `src/tools`, `packages/builtin-tool-*` |
+| Cloud-only | `src/business/*`, `packages/business/*` |
 
-## Data Flow Architecture
+## Data Flow
 
-React UI → Store Actions → Client Service → TRPC Lambda → Server Services -> DB Model → PostgreSQL (Remote)
+```
+React UI → Store Actions → Client Service → TRPC Lambda → Server Services → DB Model → PostgreSQL
+```

package/.agents/skills/react/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: react
+description: React component development guide. Use when working with React components (.tsx files), creating UI, using @lobehub/ui components, implementing routing, or building frontend features. Triggers on React component creation, modification, layout implementation, or navigation tasks.
+---
+
+# React Component Writing Guide
+
+- Use antd-style for complex styles; for simple cases, use inline `style` attribute
+- Use `Flexbox` and `Center` from `@lobehub/ui` for layouts (see `references/layout-kit.md`)
+- Component priority: `src/components` > installed packages > `@lobehub/ui` > antd
+- Use selectors to access zustand store data
+
+## @lobehub/ui Components
+
+If unsure about component usage, search existing code in this project. Most components extend antd with additional props.
+
+Reference: `node_modules/@lobehub/ui/es/index.mjs` for all available components.
+
+**Common Components:**
+- General: ActionIcon, ActionIconGroup, Block, Button, Icon
+- Data Display: Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip
+- Data Entry: CodeEditor, CopyButton, EditableText, Form, FormModal, Input, SearchBar, Select
+- Feedback: Alert, Drawer, Modal
+- Layout: Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow
+- Navigation: Burger, Dropdown, Menu, SideNav, Tabs
+
+## Routing Architecture
+
+Hybrid routing: Next.js App Router (static pages) + React Router DOM (main SPA).
+
+| Route Type | Use Case | Implementation |
+|------------|----------|----------------|
+| Next.js App Router | Auth pages (login, signup, oauth) | `src/app/[variants]/(auth)/` |
+| React Router DOM | Main SPA (chat, settings) | `desktopRouter.config.tsx` |
+
+### Key Files
+- Entry: `src/app/[variants]/page.tsx`
+- Desktop router: `src/app/[variants]/router/desktopRouter.config.tsx`
+- Mobile router: `src/app/[variants]/(mobile)/router/mobileRouter.config.tsx`
+- Router utilities: `src/utils/router.tsx`
+
+### Router Utilities
+
+```tsx
+import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
+
+element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
+element: redirectElement('/settings/profile');
+errorElement: <ErrorBoundary resetPath="/chat" />;
+```
+
+### Navigation
+
+**Important**: For SPA pages, use `Link` from `react-router-dom`, NOT `next/link`.
+
+```tsx
+// ❌ Wrong
+import Link from 'next/link';
+<Link href="/">Home</Link>
+
+// ✅ Correct
+import { Link } from 'react-router-dom';
+<Link to="/">Home</Link>
+
+// In components
+import { useNavigate } from 'react-router-dom';
+const navigate = useNavigate();
+navigate('/chat');
+
+// From stores
+const navigate = useGlobalStore.getState().navigate;
+navigate?.('/settings');
+```

package/.agents/skills/react/references/layout-kit.md

@@ -0,0 +1,100 @@
+# Flexbox Layout Components Guide
+
+`@lobehub/ui` provides `Flexbox` and `Center` components for creating flexible layouts.
+
+## Flexbox Component
+
+Flexbox is the most commonly used layout component, similar to CSS `display: flex`.
+
+### Basic Usage
+
+```jsx
+import { Flexbox } from '@lobehub/ui';
+
+// Default vertical layout
+<Flexbox>
+  <div>Child 1</div>
+  <div>Child 2</div>
+</Flexbox>
+
+// Horizontal layout
+<Flexbox horizontal>
+  <div>Left</div>
+  <div>Right</div>
+</Flexbox>
+```
+
+### Common Props
+
+- `horizontal`: Boolean, set horizontal direction layout
+- `flex`: Number or string, controls flex property
+- `gap`: Number, spacing between children
+- `align`: Alignment like 'center', 'flex-start', etc.
+- `justify`: Main axis alignment like 'space-between', 'center', etc.
+- `padding`: Padding value
+- `paddingInline`: Horizontal padding
+- `paddingBlock`: Vertical padding
+- `width/height`: Set dimensions, typically '100%' or specific pixels
+- `style`: Custom style object
+
+### Layout Example
+
+```jsx
+// Classic three-column layout
+<Flexbox horizontal height={'100%'} width={'100%'}>
+  {/* Left sidebar */}
+  <Flexbox
+    width={260}
+    style={{
+      borderRight: `1px solid ${theme.colorBorderSecondary}`,
+      height: '100%',
+      overflowY: 'auto',
+    }}
+  >
+    <SidebarContent />
+  </Flexbox>
+
+  {/* Center content */}
+  <Flexbox flex={1} style={{ height: '100%' }}>
+    <Flexbox flex={1} padding={24} style={{ overflowY: 'auto' }}>
+      <MainContent />
+    </Flexbox>
+
+    {/* Footer */}
+    <Flexbox
+      style={{
+        borderTop: `1px solid ${theme.colorBorderSecondary}`,
+        padding: '16px 24px',
+      }}
+    >
+      <Footer />
+    </Flexbox>
+  </Flexbox>
+</Flexbox>
+```
+
+## Center Component
+
+Center wraps Flexbox with horizontal and vertical centering.
+
+```jsx
+import { Center } from '@lobehub/ui';
+
+<Center width={'100%'} height={'100%'}>
+  <Content />
+</Center>
+
+// Icon centered
+<Center className={styles.icon} flex={'none'} height={40} width={40}>
+  <Icon icon={icon} size={24} />
+</Center>
+```
+
+## Best Practices
+
+- Use `flex={1}` to fill available space
+- Use `gap` instead of margin for spacing
+- Nest Flexbox for complex layouts
+- Set `overflow: 'auto'` for scrollable content
+- Use `horizontal` for horizontal layout (default is vertical)
+- Combine with `useTheme` hook for theme-responsive layouts

package/.agents/skills/recent-data/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: recent-data
+description: Guide for using Recent Data (topics, resources, pages). Use when working with recently accessed items, implementing recent lists, or accessing session store recent data. Triggers on recent data usage or implementation tasks.
+user-invocable: false
+---
+
+# Recent Data Usage Guide
+
+Recent data (recentTopics, recentResources, recentPages) is stored in session store.
+
+## Initialization
+
+In app top-level (e.g., `RecentHydration.tsx`):
+
+```tsx
+import { useInitRecentTopic } from '@/hooks/useInitRecentTopic';
+import { useInitRecentResource } from '@/hooks/useInitRecentResource';
+import { useInitRecentPage } from '@/hooks/useInitRecentPage';
+
+const App = () => {
+  useInitRecentTopic();
+  useInitRecentResource();
+  useInitRecentPage();
+  return <YourComponents />;
+};
+```
+
+## Usage
+
+### Method 1: Read from Store (Recommended)
+
+```tsx
+import { useSessionStore } from '@/store/session';
+import { recentSelectors } from '@/store/session/selectors';
+
+const Component = () => {
+  const recentTopics = useSessionStore(recentSelectors.recentTopics);
+  const isInit = useSessionStore(recentSelectors.isRecentTopicsInit);
+
+  if (!isInit) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {recentTopics.map((topic) => (
+        <div key={topic.id}>{topic.title}</div>
+      ))}
+    </div>
+  );
+};
+```
+
+### Method 2: Use Hook Return (Single component)
+
+```tsx
+const { data: recentTopics, isLoading } = useInitRecentTopic();
+```
+
+## Available Selectors
+
+### Recent Topics
+
+```tsx
+const recentTopics = useSessionStore(recentSelectors.recentTopics);
+// Type: RecentTopic[]
+
+const isInit = useSessionStore(recentSelectors.isRecentTopicsInit);
+// Type: boolean
+```
+
+**RecentTopic type:**
+```typescript
+interface RecentTopic {
+  agent: { avatar: string | null; backgroundColor: string | null; id: string; title: string | null } | null;
+  id: string;
+  title: string | null;
+  updatedAt: Date;
+}
+```
+
+### Recent Resources
+
+```tsx
+const recentResources = useSessionStore(recentSelectors.recentResources);
+// Type: FileListItem[]
+
+const isInit = useSessionStore(recentSelectors.isRecentResourcesInit);
+```
+
+### Recent Pages
+
+```tsx
+const recentPages = useSessionStore(recentSelectors.recentPages);
+const isInit = useSessionStore(recentSelectors.isRecentPagesInit);
+```
+
+## Features
+
+1. **Auto login detection**: Only loads when user is logged in
+2. **Data caching**: Stored in store, no repeated loading
+3. **Auto refresh**: SWR refreshes on focus (5-minute interval)
+4. **Type safe**: Full TypeScript types
+
+## Best Practices
+
+1. Initialize all recent data at app top-level
+2. Use selectors to read from store
+3. For multi-component use, prefer Method 1
+4. Use selectors for render optimization

package/.agents/skills/testing/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: testing
+description: Testing guide using Vitest. Use when writing tests (.test.ts, .test.tsx), fixing failing tests, improving test coverage, or debugging test issues. Triggers on test creation, test debugging, mock setup, or test-related questions.
+---
+
+# LobeChat Testing Guide
+
+## Quick Reference
+
+**Commands:**
+```bash
+# Run specific test file
+bunx vitest run --silent='passed-only' '[file-path]'
+
+# Database package (client)
+cd packages/database && bunx vitest run --silent='passed-only' '[file]'
+
+# Database package (server)
+cd packages/database && TEST_SERVER_DB=1 bunx vitest run --silent='passed-only' '[file]'
+```
+
+**Never run** `bun run test` - it runs all 3000+ tests (~10 minutes).
+
+## Test Categories
+
+| Category | Location | Config |
+|----------|----------|--------|
+| Webapp | `src/**/*.test.ts(x)` | `vitest.config.ts` |
+| Packages | `packages/*/**/*.test.ts` | `packages/*/vitest.config.ts` |
+| Desktop | `apps/desktop/**/*.test.ts` | `apps/desktop/vitest.config.ts` |
+
+## Core Principles
+
+1. **Prefer `vi.spyOn` over `vi.mock`** - More targeted, easier to maintain
+2. **Tests must pass type check** - Run `bun run type-check` after writing tests
+3. **After 1-2 failed fix attempts, stop and ask for help**
+4. **Test behavior, not implementation details**
+
+## Basic Test Structure
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('ModuleName', () => {
+  describe('functionName', () => {
+    it('should handle normal case', () => {
+      // Arrange → Act → Assert
+    });
+  });
+});
+```
+
+## Mock Patterns
+
+```typescript
+// ✅ Spy on direct dependencies
+vi.spyOn(messageService, 'createMessage').mockResolvedValue('id');
+
+// ✅ Use vi.stubGlobal for browser APIs
+vi.stubGlobal('Image', mockImage);
+vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock');
+
+// ❌ Avoid mocking entire modules globally
+vi.mock('@/services/chat'); // Too broad
+```
+
+## Detailed Guides
+
+See `references/` for specific testing scenarios:
+- **Database Model testing**: `references/db-model-test.md`
+- **Electron IPC testing**: `references/electron-ipc-test.md`
+- **Zustand Store Action testing**: `references/zustand-store-action-test.md`
+- **Agent Runtime E2E testing**: `references/agent-runtime-e2e.md`
+- **Desktop Controller testing**: `references/desktop-controller-test.md`
+
+## Common Issues
+
+1. **Module pollution**: Use `vi.resetModules()` when tests fail mysteriously
+2. **Mock not working**: Check setup position and use `vi.clearAllMocks()` in beforeEach
+3. **Test data pollution**: Clean database state in beforeEach/afterEach
+4. **Async issues**: Wrap state changes in `act()` for React hooks