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

package/.agents/skills/zustand/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: zustand
+description: Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
+---
+
+# LobeChat Zustand State Management
+
+## Action Type Hierarchy
+
+### 1. Public Actions
+Main interfaces for UI components:
+- Naming: Verb form (`createTopic`, `sendMessage`)
+- Responsibilities: Parameter validation, flow orchestration
+
+### 2. Internal Actions (`internal_*`)
+Core business logic implementation:
+- Naming: `internal_` prefix (`internal_createTopic`)
+- Responsibilities: Optimistic updates, service calls, error handling
+- Should not be called directly by UI
+
+### 3. Dispatch Methods (`internal_dispatch*`)
+State update handlers:
+- Naming: `internal_dispatch` + entity (`internal_dispatchTopic`)
+- Responsibilities: Calling reducers, updating store
+
+## When to Use Reducer vs Simple `set`
+
+**Use Reducer Pattern:**
+- Managing object lists/maps (`messagesMap`, `topicMaps`)
+- Optimistic updates
+- Complex state transitions
+
+**Use Simple `set`:**
+- Toggling booleans
+- Updating simple values
+- Setting single state fields
+
+## Optimistic Update Pattern
+
+```typescript
+internal_createTopic: async (params) => {
+  const tmpId = Date.now().toString();
+
+  // 1. Immediately update frontend (optimistic)
+  get().internal_dispatchTopic(
+    { type: 'addTopic', value: { ...params, id: tmpId } },
+    'internal_createTopic'
+  );
+
+  // 2. Call backend service
+  const topicId = await topicService.createTopic(params);
+
+  // 3. Refresh for consistency
+  await get().refreshTopic();
+  return topicId;
+},
+```
+
+**Delete operations**: Don't use optimistic updates (destructive, complex recovery)
+
+## Naming Conventions
+
+**Actions:**
+- Public: `createTopic`, `sendMessage`
+- Internal: `internal_createTopic`, `internal_updateMessageContent`
+- Dispatch: `internal_dispatchTopic`
+- Toggle: `internal_toggleMessageLoading`
+
+**State:**
+- ID arrays: `messageLoadingIds`, `topicEditingIds`
+- Maps: `topicMaps`, `messagesMap`
+- Active: `activeTopicId`
+- Init flags: `topicsInit`
+
+## Detailed Guides
+
+- Action patterns: `references/action-patterns.md`
+- Slice organization: `references/slice-organization.md`

package/.agents/skills/zustand/references/action-patterns.md

@@ -0,0 +1,125 @@
+# Zustand Action Patterns
+
+## Optimistic Update Implementation
+
+### Standard Flow
+
+```typescript
+internal_updateMessageContent: async (id, content, extra) => {
+  const { internal_dispatchMessage, refreshMessages } = get();
+
+  // 1. Immediately update frontend
+  internal_dispatchMessage({
+    id,
+    type: 'updateMessage',
+    value: { content },
+  });
+
+  // 2. Call backend
+  await messageService.updateMessage(id, { content });
+
+  // 3. Refresh for consistency
+  await refreshMessages();
+},
+```
+
+### Create Operations
+
+```typescript
+internal_createMessage: async (message, context) => {
+  let tempId = context?.tempMessageId;
+  if (!tempId) {
+    tempId = internal_createTmpMessage(message);
+    internal_toggleMessageLoading(true, tempId);
+  }
+
+  try {
+    const id = await messageService.createMessage(message);
+    await refreshMessages();
+    internal_toggleMessageLoading(false, tempId);
+    return id;
+  } catch (e) {
+    internal_toggleMessageLoading(false, tempId);
+    internal_dispatchMessage({
+      id: tempId,
+      type: 'updateMessage',
+      value: { error: { type: ChatErrorType.CreateMessageError } },
+    });
+  }
+},
+```
+
+### Delete Operations (No Optimistic Update)
+
+```typescript
+internal_removeGenerationTopic: async (id: string) => {
+  get().internal_updateGenerationTopicLoading(id, true);
+
+  try {
+    await generationTopicService.deleteTopic(id);
+    await get().refreshGenerationTopics();
+  } finally {
+    get().internal_updateGenerationTopicLoading(id, false);
+  }
+},
+```
+
+## Loading State Management
+
+```typescript
+// Define in initialState.ts
+export interface ChatMessageState {
+  messageEditingIds: string[];
+}
+
+// Manage in action
+toggleMessageEditing: (id, editing) => {
+  set(
+    { messageEditingIds: toggleBooleanList(get().messageEditingIds, id, editing) },
+    false,
+    'toggleMessageEditing'
+  );
+}
+```
+
+## SWR Integration
+
+```typescript
+useFetchMessages: (enable, sessionId, activeTopicId) =>
+  useClientDataSWR<ChatMessage[]>(
+    enable ? [SWR_USE_FETCH_MESSAGES, sessionId, activeTopicId] : null,
+    async ([, sessionId, topicId]) => messageService.getMessages(sessionId, topicId),
+    {
+      onSuccess: (messages) => {
+        const nextMap = { ...get().messagesMap, [messageMapKey(sessionId, activeTopicId)]: messages };
+        if (get().messagesInit && isEqual(nextMap, get().messagesMap)) return;
+        set({ messagesInit: true, messagesMap: nextMap }, false, n('useFetchMessages'));
+      },
+    }
+  ),
+
+// Cache invalidation
+refreshMessages: async () => {
+  await mutate([SWR_USE_FETCH_MESSAGES, get().activeId, get().activeTopicId]);
+};
+```
+
+## Reducer Pattern
+
+```typescript
+export const messagesReducer = (state: ChatMessage[], payload: MessageDispatch): ChatMessage[] => {
+  switch (payload.type) {
+    case 'updateMessage': {
+      return produce(state, (draftState) => {
+        const index = draftState.findIndex((i) => i.id === payload.id);
+        if (index < 0) return;
+        draftState[index] = merge(draftState[index], {
+          ...payload.value,
+          updatedAt: Date.now(),
+        });
+      });
+    }
+    // ...other cases
+  }
+};
+```

package/.agents/skills/zustand/references/slice-organization.md

@@ -0,0 +1,125 @@
+# Zustand Slice Organization
+
+## Top-Level Store Structure
+
+Key aggregation files:
+- `src/store/chat/initialState.ts`: Aggregate all slice initial states
+- `src/store/chat/store.ts`: Define top-level `ChatStore`, combine all slice actions
+- `src/store/chat/selectors.ts`: Export all slice selectors
+- `src/store/chat/helpers.ts`: Chat helper functions
+
+## Store Aggregation Pattern
+
+```typescript
+// src/store/chat/initialState.ts
+import { ChatTopicState, initialTopicState } from './slices/topic/initialState';
+import { ChatMessageState, initialMessageState } from './slices/message/initialState';
+
+export type ChatStoreState = ChatTopicState & ChatMessageState & ...
+
+export const initialState: ChatStoreState = {
+  ...initialMessageState,
+  ...initialTopicState,
+  ...
+};
+
+// src/store/chat/store.ts
+export interface ChatStoreAction
+  extends ChatMessageAction, ChatTopicAction, ...
+
+const createStore: StateCreator<ChatStore, [['zustand/devtools', never]]> = (...params) => ({
+  ...initialState,
+  ...chatMessage(...params),
+  ...chatTopic(...params),
+});
+
+export const useChatStore = createWithEqualityFn<ChatStore>()(
+  subscribeWithSelector(devtools(createStore)),
+  shallow
+);
+```
+
+## Single Slice Structure
+
+```plaintext
+src/store/chat/slices/
+└── [sliceName]/
+    ├── action.ts          # Define actions (or actions/ directory)
+    ├── initialState.ts    # State structure and initial values
+    ├── reducer.ts         # (Optional) Reducer pattern
+    ├── selectors.ts       # Define selectors
+    └── index.ts           # (Optional) Re-exports
+```
+
+### initialState.ts
+
+```typescript
+export interface ChatTopicState {
+  activeTopicId?: string;
+  topicMaps: Record<string, ChatTopic[]>;
+  topicsInit: boolean;
+  topicLoadingIds: string[];
+}
+
+export const initialTopicState: ChatTopicState = {
+  activeTopicId: undefined,
+  topicMaps: {},
+  topicsInit: false,
+  topicLoadingIds: [],
+};
+```
+
+### selectors.ts
+
+```typescript
+const currentTopics = (s: ChatStoreState): ChatTopic[] | undefined => s.topicMaps[s.activeId];
+
+const getTopicById = (id: string) => (s: ChatStoreState): ChatTopic | undefined =>
+  currentTopics(s)?.find((topic) => topic.id === id);
+
+// Core pattern: Use xxxSelectors aggregate
+export const topicSelectors = {
+  currentTopics,
+  getTopicById,
+};
+```
+
+## Complex Actions Sub-directory
+
+```plaintext
+src/store/chat/slices/aiChat/
+├── actions/
+│   ├── generateAIChat.ts
+│   ├── rag.ts
+│   ├── memory.ts
+│   └── index.ts
+├── initialState.ts
+└── selectors.ts
+```
+
+## State Design Patterns
+
+### Map Structure for Associated Data
+```typescript
+topicMaps: Record<string, ChatTopic[]>;
+messagesMap: Record<string, ChatMessage[]>;
+```
+
+### Arrays for Loading State
+```typescript
+messageLoadingIds: string[]
+topicLoadingIds: string[]
+```
+
+### Optional Fields for Active Items
+```typescript
+activeId: string
+activeTopicId?: string
+```
+
+## Best Practices
+
+1. **Slice division**: By functional domain (message, topic, aiChat)
+2. **File naming**: camelCase for directories, consistent patterns
+3. **State structure**: Flat, avoid deep nesting
+4. **Type safety**: Clear TypeScript interfaces for each slice

package/AGENTS.md

@@ -4,12 +4,10 @@ This document serves as a comprehensive guide for all team members when developi
 
 ## Project Description
 
-You are developing an open-source, modern-design AI Agent Workspace: LobeHub(previous LobeChat).
+You are developing an open-source, modern-design AI Agent Workspace: LobeHub (previously LobeChat).
 
 ## Tech Stack
 
-Built with modern technologies:
-
 - **Frontend**: Next.js 16, React 19, TypeScript
 - **UI Components**: Ant Design, @lobehub/ui, antd-style
 - **State Management**: Zustand, SWR
@@ -19,24 +17,33 @@ Built with modern technologies:
 
 ## Directory Structure
 
-The project follows a well-organized monorepo structure:
-
-- `apps/` - Main applications
-- `packages/` - Shared packages and libraries
-- `src/` - Main source code
-- `docs/` - Documentation
-- `.cursor/rules/` - Development rules and guidelines
-- PR titles starting with `✨ feat/` or `🐛 fix` will trigger the release workflow upon merge. Only use these prefixes for significant user-facing feature changes or bug fixes
+```
+lobe-chat/
+├── apps/desktop/           # Electron desktop app
+├── packages/               # Shared packages (@lobechat/*)
+│   ├── database/           # Database schemas, models, repositories
+│   ├── agent-runtime/      # Agent runtime
+│   └── ...
+├── src/
+│   ├── app/                # Next.js app router
+│   ├── store/              # Zustand stores
+│   ├── services/           # Client services
+│   ├── server/             # Server services and routers
+│   └── ...
+├── .agents/skills/         # AI development skills
+└── e2e/                    # E2E tests (Cucumber + Playwright)
+```
 
 ## Development Workflow
 
 ### Git Workflow
 
-- The current release branch is `next` instead of `main` until v2.0.0 is officially released
+- The current release branch is `next` until v2.0.0 is officially released
 - Use rebase for git pull
 - Git commit messages should prefix with gitmoji
 - Git branch name format: `username/feat/feature-name`
 - Use `.github/PULL_REQUEST_TEMPLATE.md` for PR descriptions
+- PR titles with `✨ feat/` or `🐛 fix` trigger releases
 
 ### Package Management
 
@@ -52,17 +59,18 @@ The project follows a well-organized monorepo structure:
 
 ### Testing Strategy
 
-**Required Rule**: `testing-guide/testing-guide.mdc`
+```bash
+# Web tests
+bunx vitest run --silent='passed-only' '[file-path-pattern]'
 
-**Commands**:
-
-- Web: `bunx vitest run --silent='passed-only' '[file-path-pattern]'`
-- Packages: `cd packages/[package-name] && bunx vitest run --silent='passed-only' '[file-path-pattern]'` (each subpackage contains its own vitest.config.mts)
+# Package tests (e.g., database)
+cd packages/[package-name] && bunx vitest run --silent='passed-only' '[file-path-pattern]'
+```
 
 **Important Notes**:
 
 - Wrap file paths in single quotes to avoid shell expansion
-- Never run `bun run test` - this runs all tests and takes \~10 minutes
+- Never run `bun run test` - this runs all tests and takes ~10 minutes
 
 ### Type Checking
 
@@ -78,40 +86,19 @@ The project follows a well-organized monorepo structure:
 
 Follow [Linear rules in CLAUDE.md](CLAUDE.md#linear-issue-management-ignore-if-not-installed-linear-mcp) when working with Linear issues.
 
-## Project Rules Index
-
-All following rules are saved under `.cursor/rules/` directory:
-
-### Backend
-
-- `drizzle-schema-style-guide.mdc` – Style guide for defining Drizzle ORM schemas
-
-### Frontend
-
-- `react.mdc` – React component style guide and conventions
-- `i18n.mdc` – Internationalization guide using react-i18next
-- `typescript.mdc` – TypeScript code style guide
-- `packages/react-layout-kit.mdc` – Usage guide for Flexbox and Center components from @lobehub/ui
-
-### State Management
-
-- `zustand-action-patterns.mdc` – Recommended patterns for organizing Zustand actions
-- `zustand-slice-organization.mdc` – Best practices for structuring Zustand slices
-
-### Desktop (Electron)
-
-- `desktop-feature-implementation.mdc` – Implementing new Electron desktop features
-- `desktop-controller-tests.mdc` – Desktop controller unit testing guide
-- `desktop-local-tools-implement.mdc` – Workflow to add new desktop local tools
-- `desktop-menu-configuration.mdc` – Desktop menu configuration guide
-- `desktop-window-management.mdc` – Desktop window management guide
-
-### Debugging
-
-- `debug-usage.mdc` – Using the debug package and namespace conventions
-
-### Testing
-
-- `testing-guide/testing-guide.mdc` – Comprehensive testing guide for Vitest
-- `testing-guide/electron-ipc-test.mdc` – Electron IPC interface testing strategy
-- `testing-guide/db-model-test.mdc` – Database Model testing guide
+## Skills (Auto-loaded)
+
+All AI development skills are available in `.agents/skills/` directory:
+
+| Category | Skills |
+|----------|--------|
+| Frontend | `react`, `typescript`, `i18n`, `microcopy` |
+| State | `zustand` |
+| Backend | `drizzle` |
+| Desktop | `desktop` |
+| Testing | `testing` |
+| UI | `modal`, `hotkey`, `recent-data` |
+| Config | `add-provider-doc`, `add-setting-env` |
+| Workflow | `linear`, `debug` |
+| Performance | `vercel-react-best-practices` |
+| Overview | `project-overview` |

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 # Changelog
 
+## [Version 2.0.0-next.355](https://github.com/lobehub/lobe-chat/compare/v2.0.0-next.354...v2.0.0-next.355)
+
+<sup>Released on **2026-01-23**</sup>
+
+#### 🐛 Bug Fixes
+
+- **home**: Use correct CreateGroupModal for session group creation.
+- **misc**: Fix favorite refresh bug and group topic refresh issue.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **home**: Use correct CreateGroupModal for session group creation, closes [#11752](https://github.com/lobehub/lobe-chat/issues/11752) ([36bcc50](https://github.com/lobehub/lobe-chat/commit/36bcc50))
+- **misc**: Fix favorite refresh bug and group topic refresh issue, closes [#11745](https://github.com/lobehub/lobe-chat/issues/11745) ([5d115ef](https://github.com/lobehub/lobe-chat/commit/5d115ef))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+## [Version 2.0.0-next.354](https://github.com/lobehub/lobe-chat/compare/v2.0.0-next.353...v2.0.0-next.354)
+
+<sup>Released on **2026-01-23**</sup>
+
+#### ♻ Code Refactoring
+
+- **misc**: Migrate AI Rules to Claude Code Skills.
+
+#### 🐛 Bug Fixes
+
+- **pdf**: Ensure worker config before Document render.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### Code refactoring
+
+- **misc**: Migrate AI Rules to Claude Code Skills, closes [#11737](https://github.com/lobehub/lobe-chat/issues/11737) ([346fc46](https://github.com/lobehub/lobe-chat/commit/346fc46))
+
+#### What's fixed
+
+- **pdf**: Ensure worker config before Document render, closes [#11746](https://github.com/lobehub/lobe-chat/issues/11746) ([ad34072](https://github.com/lobehub/lobe-chat/commit/ad34072))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ## [Version 2.0.0-next.353](https://github.com/lobehub/lobe-chat/compare/v2.0.0-next.352...v2.0.0-next.353)
 
 <sup>Released on **2026-01-23**</sup>

package/CLAUDE.md

@@ -1,72 +1,83 @@
 # CLAUDE.md
 
-This document serves as a shared guideline for all team members when using Claude Code in this opensource lobe-chat(also known as lobehub) repository.
+Guidelines for using Claude Code in this LobeChat repository.
 
 ## Tech Stack
 
-read @.cursor/rules/project-introduce.mdc
-
-## Directory Structure
-
-read @.cursor/rules/project-structure.mdc
+- Next.js 16 + React 19 + TypeScript
+- SPA inside Next.js with `react-router-dom`
+- `@lobehub/ui`, antd for components; antd-style for CSS-in-JS
+- react-i18next for i18n; zustand for state management
+- SWR for data fetching; TRPC for type-safe backend
+- Drizzle ORM with PostgreSQL; Vitest for testing
+
+## Project Structure
+
+```
+lobe-chat/
+├── apps/desktop/           # Electron desktop app
+├── packages/               # Shared packages (@lobechat/*)
+│   ├── database/           # Database schemas, models, repositories
+│   ├── agent-runtime/      # Agent runtime
+│   └── ...
+├── src/
+│   ├── app/                # Next.js app router
+│   ├── store/              # Zustand stores
+│   ├── services/           # Client services
+│   ├── server/             # Server services and routers
+│   └── ...
+└── e2e/                    # E2E tests (Cucumber + Playwright)
+```
 
 ## Development
 
 ### Git Workflow
 
-- use rebase for git pull
-- git commit message should prefix with gitmoji
-- git branch name format template: <type>/<feature-name>
-- use .github/PULL_REQUEST_TEMPLATE.md to generate pull request description
-- PR titles starting with `✨ feat/` or `🐛 fix` will trigger the release workflow upon merge. Only use these prefixes for significant user-facing feature changes or bug fixes
+- Use rebase for `git pull`
+- Commit messages: prefix with gitmoji
+- Branch format: `<type>/<feature-name>`
+- PR titles with `✨ feat/` or `🐛 fix` trigger releases
 
 ### Package Management
 
-This repository adopts a monorepo structure.
-
-- Use `pnpm` as the primary package manager for dependency management
-- Use `bun` to run npm scripts
-- Use `bunx` to run executable npm packages
-
-### TypeScript Code Style Guide
-
-see @.cursor/rules/typescript.mdc
-
-### Code Comments
-
-- **Avoid meaningless comments**: Do not write comments that merely restate what the code does. Comments should explain _why_ something is done, not _what_ is being done. The code itself should be self-explanatory.
+- `pnpm` for dependency management
+- `bun` to run npm scripts
+- `bunx` for executable npm packages
 
 ### Testing
 
-- **Required Rule**: read `.cursor/rules/testing-guide/testing-guide.mdc` before writing tests
-- **Command**:
-  - web: `bunx vitest run --silent='passed-only' '[file-path-pattern]'`
-  - packages(eg: database): `cd packages/database && bunx vitest run --silent='passed-only' '[file-path-pattern]'`
+```bash
+# Run specific test (NEVER run `bun run test` - takes ~10 minutes)
+bunx vitest run --silent='passed-only' '[file-path]'
 
-**Important**:
+# Database package
+cd packages/database && bunx vitest run --silent='passed-only' '[file]'
+```
 
-- wrap the file path in single quotes to avoid shell expansion
-- Never run `bun run test` etc to run tests, this will run all tests and cost about 10mins
-- If trying to fix the same test twice, but still failed, stop and ask for help.
-- **Prefer `vi.spyOn` over `vi.mock`**: When mocking modules or functions, prefer using `vi.spyOn` to mock specific functions rather than `vi.mock` to mock entire modules. This approach is more targeted, easier to maintain, and allows for better control over mock behavior in individual tests.
-- **Tests must pass type check**: After writing or modifying tests, run `bun run type-check` to ensure there are no type errors. Tests should pass both runtime execution and TypeScript type checking.
+- Prefer `vi.spyOn` over `vi.mock`
+- Tests must pass type check: `bun run type-check`
+- After 2 failed fix attempts, stop and ask for help
 
-### Typecheck
+### i18n
 
-- use `bun run type-check` to check type errors.
+- Add keys to `src/locales/default/namespace.ts`
+- For dev preview: translate `locales/zh-CN/` and `locales/en-US/`
+- Don't run `pnpm i18n` - CI handles it
 
-### i18n
+## Linear Issue Management
+
+**Trigger conditions** - when ANY of these occur, apply Linear workflow:
 
-- **Keys**: Add to `src/locales/default/namespace.ts`
-- **Dev**: Translate `locales/zh-CN/namespace.json` and `locales/en-US/namespace.json` locales file only for dev preview
-- DON'T run `pnpm i18n`, let CI auto handle it
+- User mentions issue ID like `LOBE-XXX`
+- User says "linear", "link linear", "linear issue"
+- Creating PR that references a Linear issue
 
-## Linear Issue Management (search tools first; ignore if not installed)
+**Workflow:**
 
-ClaudeCode may not inject MCP tools until they are discovered/used.\
-Before applying Linear workflows, **use tool search** to confirm `linear-server` exists (e.g. search `linear` / `mcp__linear-server__`). If not found, treat it as not installed.\
-Then read `@.cursor/rules/linear.mdc` when working with Linear issues.
+1. Use `ToolSearch` to confirm `linear-server` MCP exists (search `linear` or `mcp__linear-server__`)
+2. If found, read `.agents/skills/linear/SKILL.md` and follow the workflow
+3. If not found, skip Linear integration (treat as not installed)
 
-## Rules Index
+## Skills (Auto-loaded by Claude)
 
-Some useful project rules are listed in @.cursor/rules/rules-index.mdc
+Claude Code automatically loads relevant skills from `.agents/skills/`.