@lobehub/chat 1.80.0 → 1.80.1

package/docs/development/basic/feature-development.mdx

@@ -1,712 +1,463 @@
-# Complete Guide to LobeChat Feature Development
+# LobeChat Feature Development Complete Guide
 
-This document aims to guide developers on how to develop a complete feature requirement in LobeChat.
+This document aims to guide developers on how to develop a complete feature in LobeChat.
 
-We will use the implementation of sessionGroup as an example: [✨ feat: add session group manager](https://github.com/lobehub/lobe-chat/pull/1055), and explain the complete implementation process through the following six main sections:
+We will use [RFC 021 - Custom Assistant Opening Guidance](https://github.com/lobehub/lobe-chat/discussions/891) as an example to illustrate the complete implementation process.
 
-1. [Data Model / Database Definition](#1-data-model--database-definition)
-2. [Service Implementation / Model Implementation](#2-service-implementation--model-implementation)
-3. [Frontend Data Flow Store Implementation](#3-frontend-data-flow-store-implementation)
-4. [UI Implementation and Action Binding](#4-ui-implementation-and-action-binding)
-5. [Data Migration](#5-data-migration)
-6. [Data Import and Export](#6-data-import-and-export)
+## 1. Update Schema
 
-## 1. Data Model / Database Definition
+lobe-chat uses a postgres database, with the browser-side local database using [pglite](https://pglite.dev/) (wasm version of postgres). The project also uses [drizzle](https://orm.drizzle.team/) ORM to operate the database.
 
-To implementation the Session Group feature, it is necessary to define the relevant data model and indexes at the database level.
+Compared to the old solution where the browser side used indexDB, having both the browser side and server side use postgres has the advantage that the model layer code can be completely reused.
 
-Define a new sessionGroup table in 3 steps:
-
-### 1. Establish Data Model Schema
-
-Define the data model of `DB_SessionGroup` in `src/database/schema/sessionGroup.ts`:
-
-```ts
-import { z } from 'zod';
-
-export const DB_SessionGroupSchema = z.object({
-  name: z.string(),
-  sort: z.number().optional(),
-});
-
-export type DB_SessionGroup = z.infer<typeof DB_SessionGroupSchema>;
-```
-
-### 2. Create Database Indexes
-
-Since a new table needs to be added, an index needs to be added to the database schema for the `sessionGroup` table.
-
-Add `dbSchemaV4` in `src/database/core/schema.ts`:
-
-```diff
-// ... previous implementations
-
-// ************************************** //
-// ******* Version 3 - 2023-12-06 ******* //
-// ************************************** //
-// - Added `plugin` table
-
-export const dbSchemaV3 = {
-  ...dbSchemaV2,
-  plugins:
-    '&identifier, type, manifest.type, manifest.meta.title, manifest.meta.description, manifest.meta.author, createdAt, updatedAt',
-};
-
-+ // ************************************** //
-+ // ******* Version 4 - 2024-01-21 ******* //
-+ // ************************************** //
-+ // - Added `sessionGroup` table
-
-+ export const dbSchemaV4 = {
-+   ...dbSchemaV3,
-+   sessionGroups: '&id, name, sort, createdAt, updatedAt',
-+   sessions: '&id, type, group, pinned, meta.title, meta.description, meta.tags, createdAt, updatedAt',
-};
-```
-
-> \[!Note]
->
-> In addition to `sessionGroups`, the definition of `sessions` has also been modified here due to data migration. However, as this section only focuses on schema definition and does not delve into the implementation of data migration, please refer to section five for details.
-
-> \[!Important]
->
-> If you are unfamiliar with the need to create indexes here and the syntax of schema definition, you may need to familiarize yourself with the basics of Dexie.js.
-
-### 3. Add the sessionGroups Table to the Local DB
-
-Extend the local database class to include the new `sessionGroups` table:
+All schemas are uniformly placed in `src/database/schemas`. We need to adjust the `agents` table to add two fields corresponding to the configuration items:
 
 ```diff
+// src/database/schemas/agent.ts
+export const agents = pgTable(
+  'agents',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => idGenerator('agents'))
+      .notNull(),
+    avatar: text('avatar'),
+    backgroundColor: text('background_color'),
+    plugins: jsonb('plugins').$type<string[]>().default([]),
+    // ...
+    tts: jsonb('tts').$type<LobeAgentTTSConfig>(),
+
++   openingMessage: text('opening_message'),
++   openingQuestions: text('opening_questions').array().default([]),
+
+    ...timestamps,
+  },
+  (t) => ({
+    // ...
+    // !: update index here
+  }),
+);
 
-import { dbSchemaV1, dbSchemaV2, dbSchemaV3, dbSchemaV4 } from './schemas';
-
-interface LobeDBSchemaMap {
-  files: DB_File;
-  messages: DB_Message;
-  plugins: DB_Plugin;
-+ sessionGroups: DB_SessionGroup;
-  sessions: DB_Session;
-  topics: DB_Topic;
-}
-
-// Define a local DB
-export class LocalDB extends Dexie {
-  public files: LobeDBTable<'files'>;
-  public sessions: LobeDBTable<'sessions'>;
-  public messages: LobeDBTable<'messages'>;
-  public topics: LobeDBTable<'topics'>;
-  public plugins: LobeDBTable<'plugins'>;
-+ public sessionGroups: LobeDBTable<'sessionGroups'>;
-
-  constructor() {
-    super(LOBE_CHAT_LOCAL_DB_NAME);
-    this.version(1).stores(dbSchemaV1);
-    this.version(2).stores(dbSchemaV2);
-    this.version(3).stores(dbSchemaV3);
-+   this.version(4).stores(dbSchemaV4);
-
-    this.files = this.table('files');
-    this.sessions = this.table('sessions');
-    this.messages = this.table('messages');
-    this.topics = this.table('topics');
-    this.plugins = this.table('plugins');
-+   this.sessionGroups = this.table('sessionGroups');
-  }
-}
 ```
 
-As a result, you can now view the `sessionGroups` table in the `LOBE_CHAT_DB` in `Application` -> `Storage` -> `IndexedDB`.
-
-![](https://github.com/lobehub/lobe-chat/assets/28616219/aea50f66-4060-4a32-88c8-b3c672d05be8)
+Note that sometimes we may also need to update the index, but for this feature, we don't have any related performance bottleneck issues, so we don't need to update the index.
 
-## 2. Service Implementation / Model Implementation
+After adjusting the schema, we need to run `npm run db:generate` to use drizzle-kit's built-in database migration capability to generate the corresponding SQL code for migrating to the latest schema. After execution, four files will be generated:
 
-### Define Model
+- src/database/migrations/meta/\_journal.json: Saves information about each migration
+- src/database/migrations/0021\_add\_agent\_opening\_settings.sql: SQL commands for this migration
+- src/database/client/migrations.json: SQL commands for this migration used by pglite
+- src/database/migrations/meta/0021\_snapshot.json: The current latest complete database snapshot
 
-When building the LobeChat application, the Model is responsible for interacting with the database. It defines how to read, insert, update, and delete data from the database, as well as defining specific business logic.
+Note that the migration SQL filename generated by the script by default is not semantically clear like `0021_add_agent_opening_settings.sql`. You need to manually rename it and update `src/database/migrations/meta/_journal.json`.
 
-In `src/database/model/sessionGroup.ts`, the `SessionGroupModel` is defined as follows:
+Previously, client-side storage using indexDB made database migration relatively complicated. Now with pglite on the local side, database migration is a simple command, very quick and easy. You can also check if there's any room for optimization in the generated migration SQL and make manual adjustments.
 
-```ts
-import { BaseModel } from '@/database/client/core';
-import { DB_SessionGroup, DB_SessionGroupSchema } from '@/database/client/schemas/sessionGroup';
-import { nanoid } from '@/utils/uuid';
+## 2. Update Data Model
 
-class _SessionGroupModel extends BaseModel {
-  constructor() {
-    super('sessions', DB_SessionGroupSchema);
-  }
+Data models used in our project are defined in `src/types`. We don't directly use the types exported from the drizzle schema, such as `export type NewAgent = typeof agents.$inferInsert;`, but instead define corresponding data models based on frontend requirements and data types of the corresponding fields in the db schema definition.
 
-  async create(name: string, sort?: number, id = nanoid()) {
-    return this._add({ name, sort }, id);
-  }
+Data model definitions are placed in the `src/types` folder. Update the `LobeAgentConfig` type in `src/types/agent/index.ts`:
 
-  // ... Implementation of other CRUD methods
-}
-
-export const SessionGroupModel = new _SessionGroupModel();
-```
-
-### Service Implementation
-
-In LobeChat, the Service layer is mainly responsible for communicating with the backend service, encapsulating business logic, and providing data to other layers in the frontend. `SessionService` is a service class specifically handling business logic related to sessions. It encapsulates operations such as creating sessions, querying sessions, and updating sessions.
-
-To maintain code maintainability and extensibility, we place the logic related to session grouping in the `SessionService`. This helps to keep the business logic of the session domain cohesive. When business requirements increase or change, it becomes easier to modify and extend within this domain.
-
-`SessionService` implements session group-related request logic by calling methods from `SessionGroupModel`. The following is the implementation of Session Group-related request logic in `sessionService`:
+```diff
+export interface LobeAgentConfig {
+  // ...
+  chatConfig: LobeAgentChatConfig;
+  /**
+   * The language model used by the agent
+   * @default gpt-4o-mini
+   */
+  model: string;
 
-```ts
-class SessionService {
-  // ... Omitted session business logic
++  /**
++   * Opening message
++   */
++  openingMessage?: string;
++  /**
++   * Opening questions
++   */
++  openingQuestions?: string[];
 
-  // ************************************** //
-  // ***********  SessionGroup  *********** //
-  // ************************************** //
+  /**
+   * Language model parameters
+   */
+  params: LLMParams;
+  /**
+   * Enabled plugins
+   */
+  plugins?: string[];
 
-  async createSessionGroup(name: string, sort?: number) {
-    const item = await SessionGroupModel.create(name, sort);
-    if (!item) {
-      throw new Error('session group create Error');
-    }
+  /**
+   * Model provider
+   */
+  provider?: string;
 
-    return item.id;
-  }
+  /**
+   * System role
+   */
+  systemRole: string;
 
-  // ... Other SessionGroup related implementations
+  /**
+   * Text-to-speech service
+   */
+  tts: LobeAgentTTSConfig;
 }
 ```
 
-## 3. Frontend Data Flow Store Implementation
+## 3. Service Implementation / Model Implementation
 
-In the LobeChat application, the Store module is used to manage the frontend state of the application. The Actions within it are functions that trigger state updates, usually by calling methods in the service layer to perform actual data processing operations and then updating the state in the Store. We use `zustand` as the underlying dependency for the Store module. For a detailed practical introduction to state management, you can refer to [📘 Best Practices for State Management](../state-management/state-management-intro).
+- The `model` layer encapsulates reusable operations on the DB
+- The `service` layer implements application business logic
 
-### sessionGroup CRUD
+Both have corresponding top-level folders in the `src` directory.
 
-CRUD operations for session groups are the core behaviors for managing session group data. In `src/store/session/slice/sessionGroup`, we will implement the state logic related to session groups, including adding, deleting, updating session groups, and their sorting.
+We need to check if we need to update their implementation. Agent configuration in the frontend is abstracted as session configuration. In `src/services/session/server.ts` we can see a service function `updateSessionConfig`:
 
-The following are the methods of the `SessionGroupAction` interface that need to be implemented in the `action.ts` file:
-
-```ts
-export interface SessionGroupAction {
-  // Add session group
-  addSessionGroup: (name: string) => Promise<string>;
-  // Remove session group
-  removeSessionGroup: (id: string) => Promise<void>;
-  // Update session group ID for a session
-  updateSessionGroupId: (sessionId: string, groupId: string) => Promise<void>;
-  // Update session group name
-  updateSessionGroupName: (id: string, name: string) => Promise<void>;
-  // Update session group sorting
-  updateSessionGroupSort: (items: SessionGroupItem[]) => Promise<void>;
+```typescript
+export class ServerService implements ISessionService {
+  // ...
+  updateSessionConfig: ISessionService['updateSessionConfig'] = (id, config, signal) => {
+    return lambdaClient.session.updateSessionConfig.mutate({ id, value: config }, { signal });
+  };
 }
 ```
 
-Taking the `addSessionGroup` method as an example, we first call the `createSessionGroup` method of `sessionService` to create a new session group, and then use the `refreshSessions` method to refresh the sessions state:
-
-```ts
-export const createSessionGroupSlice: StateCreator<
-  SessionStore,
-  [['zustand/devtools', never]],
-  [],
-  SessionGroupAction
-> = (set, get) => ({
-  // Implement the logic for adding a session group
-  addSessionGroup: async (name) => {
-    // Call the createSessionGroup method in the service layer and pass in the session group name
-    const id = await sessionService.createSessionGroup(name);
-    // Call the get method to get the current Store state and execute the refreshSessions method to refresh the session data
-    await get().refreshSessions();
-    // Return the ID of the newly created session group
-    return id;
-  },
-  // ... Other action implementations
-});
-```
-
-With the above implementation, we can ensure that after adding a new session group, the application's state will be updated in a timely manner, and the relevant components will receive the latest state and re-render. This approach improves the predictability and maintainability of the data flow, while also simplifying communication between components.
-
-### Sessions Group Logic Refactoring
-
-This requirement involves upgrading the Sessions feature to transform it from a single list to three different groups: `pinnedSessions` (pinned list), `customSessionGroups` (custom groups), and `defaultSessions` (default list).
-
-To handle these groups, we need to refactor the implementation logic of `useFetchSessions`. Here are the key changes:
-
-1. Use the `sessionService.getGroupedSessions` method to call the backend API and retrieve the grouped session data.
-2. Save the retrieved data into three different state fields: `pinnedSessions`, `customSessionGroups`, and `defaultSessions`.
-
-#### `useFetchSessions` Method
-
-This method is defined in `createSessionSlice` as follows:
-
-```ts
-export const createSessionSlice: StateCreator<
-  SessionStore,
-  [['zustand/devtools', never]],
-  [],
-  SessionAction
-> = (set, get) => ({
-  // ... other methods
-  useFetchSessions: () =>
-    useSWR<ChatSessionList>(FETCH_SESSIONS_KEY, sessionService.getGroupedSessions, {
-      onSuccess: (data) => {
-        set(
-          {
-            customSessionGroups: data.customGroup,
-            defaultSessions: data.default,
-            isSessionsFirstFetchFinished: true,
-            pinnedSessions: data.pinned,
-            sessions: data.all,
-          },
-          false,
-          n('useFetchSessions/onSuccess', data),
-        );
-      },
+Jumping to the implementation of `lambdaClient.session.updateSessionConfig`, we find that it simply **merges** the new config with the old config.
+
+```typescript
+export const sessionRouter = router({
+  // ..
+  updateSessionConfig: sessionProcedure
+    .input(
+      z.object({
+        id: z.string(),
+        value: z.object({}).passthrough().partial(),
+      }),
+    )
+    .mutation(async ({ input, ctx }) => {
+      const session = await ctx.sessionModel.findByIdOrSlug(input.id);
+      // ...
+      const mergedValue = merge(session.agent, input.value);
+      return ctx.sessionModel.updateConfig(session.agent.id, mergedValue);
     }),
 });
 ```
 
-After successfully retrieving the data, we use the `set` method to update the `customSessionGroups`, `defaultSessions`, `pinnedSessions`, and `sessions` states. This ensures that the states are synchronized with the latest session data.
-
-#### `sessionService.getGroupedSessions` Method
-
-The `sessionService.getGroupedSessions` method is responsible for calling the backend API `SessionModel.queryWithGroups()`.
-
-```ts
-class SessionService {
-  // ... other SessionGroup related implementations
-
-  async getGroupedSessions(): Promise<ChatSessionList> {
-    return SessionModel.queryWithGroups();
-  }
-}
-```
-
-#### `SessionModel.queryWithGroups` Method
+Foreseeably, the frontend will add two inputs, calling updateSessionConfig upon user modification. As the current implementation lacks field-level granularity for the config update, the service and model layers remain unaffected.
 
-This method is the core method called by `sessionService.getGroupedSessions`, and it is responsible for querying and organizing session data. The code is as follows:
+## 4. Frontend Implementation
 
-```ts
-class _SessionModel extends BaseModel {
-  // ... other methods
+### Data Flow Store Implementation
 
-  /**
-   * Query session data and categorize sessions based on groups.
-   * @returns {Promise<ChatSessionList>} An object containing all sessions and categorized session lists.
-   */
-  async queryWithGroups(): Promise<ChatSessionList> {
-    // Query session group data
-    const groups = await SessionGroupModel.query();
-    // Query custom session groups based on session group IDs
-    const customGroups = await this.queryByGroupIds(groups.map((item) => item.id));
-    // Query default session list
-    const defaultItems = await this.querySessionsByGroupId(SessionDefaultGroup.Default);
-    // Query pinned sessions
-    const pinnedItems = await this.getPinnedSessions();
-
-    // Query all sessions
-    const all = await this.query();
-    // Combine and return all sessions and their group information
-    return {
-      all, // Array containing all sessions
-      customGroup: groups.map((group) => ({ ...group, children: customGroups[group.id] })), // Custom groups
-      default: defaultItems, // Default session list
-      pinned: pinnedItems, // Pinned session list
-    };
-  }
-}
-```
-
-The `queryWithGroups` method first queries all session groups, then based on the IDs of these groups, it queries custom session groups, as well as default and pinned sessions. Finally, it returns an object containing all sessions and categorized session lists.
+lobe-chat uses [zustand](https://zustand.docs.pmnd.rs/getting-started/introduction) as the global state management framework. For detailed practices on state management, you can refer to [📘 State Management Best Practices](/docs/development/state-management/state-management-intro).
 
-### Adjusting sessions selectors
+There are two stores related to the agent:
 
-Due to changes in the logic of grouping within sessions, we need to adjust the logic of the `sessions` selectors to ensure they can correctly handle the new data structure.
+- `src/features/AgentSetting/store` serves the local store for agent settings
+- `src/store/agent` is used to get the current session agent's store
 
-Original selectors:
+The latter listens for and updates the current session's agent configuration through the `onConfigChange` in the `AgentSettings` component in `src/features/AgentSetting/AgentSettings.tsx`.
 
-```ts
-// Default group
-const defaultSessions = (s: SessionStore): LobeSessions => s.sessions;
+#### Update AgentSetting/store
 
-// Pinned group
-const pinnedSessionList = (s: SessionStore) =>
-  defaultSessions(s).filter((s) => s.group === SessionGroupDefaultKeys.Pinned);
+First, we update the initialState. After reading `src/features/AgentSetting/store/initialState.ts`, we learn that the initial agent configuration is saved in `DEFAULT_AGENT_CONFIG` in `src/const/settings/agent.ts`:
 
-// Unpinned group
-const unpinnedSessionList = (s: SessionStore) =>
-  defaultSessions(s).filter((s) => s.group === SessionGroupDefaultKeys.Default);
-```
-
-Revised:
-
-```ts
-const defaultSessions = (s: SessionStore): LobeSessions => s.defaultSessions;
-const pinnedSessions = (s: SessionStore): LobeSessions => s.pinnedSessions;
-const customSessionGroups = (s: SessionStore): CustomSessionGroup[] => s.customSessionGroups;
+```diff
+export const DEFAULT_AGENT_CONFIG: LobeAgentConfig = {
+  chatConfig: DEFAULT_AGENT_CHAT_CONFIG,
+  model: DEFAULT_MODEL,
++ openingQuestions: [],
+  params: {
+    frequency_penalty: 0,
+    presence_penalty: 0,
+    temperature: 1,
+    top_p: 1,
+  },
+  plugins: [],
+  provider: DEFAULT_PROVIDER,
+  systemRole: '',
+  tts: DEFAUTT_AGENT_TTS_CONFIG,
+};
 ```
 
-Since all data retrieval in the UI is implemented using syntax like `useSessionStore(sessionSelectors.defaultSessions)`, we only need to modify the selector implementation of `defaultSessions` to complete the data structure change. The data retrieval code in the UI layer does not need to be changed at all, which can greatly reduce the cost and risk of refactoring.
-
-> !\[Important]
->
-> If you are not familiar with the concept and functionality of selectors, you can refer to the section [📘 Data Storage and Retrieval Module](./State-Management-Selectors.en-US) for relevant information.
+Actually, you don't even need to update this since the `openingQuestions` type is already optional. I'm not updating `openingMessage` here.
 
-## 4. UI Implementation and Action Binding
+Because we've added two new fields, to facilitate access by components in the `src/features/AgentSetting/AgentOpening` folder and for performance optimization, we add related selectors in `src/features/AgentSetting/store/selectors.ts`:
 
-Bind Store Action in the UI component to implement interactive logic, for example `CreateGroupModal`:
+```diff
+import { DEFAULT_AGENT_CHAT_CONFIG } from '@/const/settings';
+import { LobeAgentChatConfig } from '@/types/agent';
 
-```tsx
-const CreateGroupModal = () => {
-  // ... Other logic
+import { Store } from './action';
 
-  const [updateSessionGroup, addCustomGroup] = useSessionStore((s) => [
-    s.updateSessionGroupId,
-    s.addSessionGroup,
-  ]);
+const chatConfig = (s: Store): LobeAgentChatConfig =>
+  s.config.chatConfig || DEFAULT_AGENT_CHAT_CONFIG;
 
-  return (
-    <Modal
-      onOk={async () => {
-        // ... Other logic
-        const groupId = await addCustomGroup(name);
-        await updateSessionGroup(sessionId, groupId);
-      }}
-    >
-      {/* ... */}
-    </Modal>
-  );
++export const DEFAULT_OPENING_QUESTIONS: string[] = [];
+export const selectors = {
+  chatConfig,
++ openingMessage: (s: Store) => s.config.openingMessage,
++ openingQuestions: (s: Store) => s.config.openingQuestions || DEFAULT_OPENING_QUESTIONS,
 };
 ```
 
-## 5. Data Migration
-
-In the process of software development, data migration is an inevitable issue, especially when the existing data structure cannot meet the new business requirements. For this iteration of SessionGroup, we need to handle the migration of the `group` field in the `session`, which is a typical data migration case.
-
-### Issues with the Old Data Structure
-
-In the old data structure, the `group` field was used to mark whether the session was "pinned" or belonged to a "default" group. However, when support for multiple session groups is needed, the original data structure becomes inflexible.
-
-For example:
+We won't add additional actions to update the agent config here, as I've observed that other existing code also directly uses the unified `setChatConfig` in the existing code:
 
+```typescript
+export const store: StateCreator<Store, [['zustand/devtools', never]]> = (set, get) => ({
+  setAgentConfig: (config) => {
+    get().dispatchConfig({ config, type: 'update' });
+  },
+});
 ```
-before   pin:  group = abc
-after    pin:  group = pinned
-after  unpin:  group = default
-```
-
-From the above example, it can be seen that once a session is unpinned from the "pinned" state, the `group` field cannot be restored to its original `abc` value. This is because we do not have a separate field to maintain the pinned state. Therefore, we have introduced a new field `pinned` to indicate whether the session is pinned, while the `group` field will be used solely to identify the session group.
-
-### Migration Strategy
 
-The core logic of this migration is as follows:
+#### Update store/agent
 
-- When the user's `group` field is `pinned`, set their `pinned` field to `true`, and set the group to `default`.
+In the component `src/app/[variants]/(main)/chat/(workspace)/@conversation/features/ChatList/WelcomeChatItem/WelcomeMessage.tsx`, we use this store to get the current agent configuration to render user-customized opening messages and guiding questions.
 
-However, data migration in LobeChat typically involves two parts: **configuration file migration** and **database migration**. Therefore, the above logic will need to be implemented separately in these two areas.
+Since we only need to read two configuration items, we'll simply add two selectors:
 
-#### Configuration File Migration
-
-For configuration file migration, we recommend performing it before database migration, as configuration file migration is usually easier to test and validate. LobeChat's file migration configuration is located in the `src/migrations/index.ts` file, which defines the various versions of configuration file migration and their corresponding migration scripts.
+Update `src/store/agent/slices/chat/selectors/agent.ts`:
 
 ```diff
-// Current latest version number
-- export const CURRENT_CONFIG_VERSION = 2;
-+ export const CURRENT_CONFIG_VERSION = 3;
-
-// Historical version upgrade module
-const ConfigMigrations = [
-+ /**
-+ * 2024.01.22
-+  * from `group = pinned` to `pinned:true`
-+  */
-+ MigrationV2ToV3,
-  /**
-   * 2023.11.27
-   * Migrate from single key database to dexie-based relational structure
-   */
-  MigrationV1ToV2,
-  /**
-   * 2023.07.11
-   * just the first version, Nothing to do
-   */
-  MigrationV0ToV1,
-];
+// ...
++const openingQuestions = (s: AgentStoreState) =>
++  currentAgentConfig(s).openingQuestions || DEFAULT_OPENING_QUESTIONS;
++const openingMessage = (s: AgentStoreState) => currentAgentConfig(s).openingMessage || '';
+
+export const agentSelectors = {
+  // ...
+  isInboxSession,
++ openingMessage,
++ openingQuestions,
+};
 ```
 
-The logic for this configuration file migration is defined in `src/migrations/FromV2ToV3/index.ts`, simplified as follows:
-
-```ts
-export class MigrationV2ToV3 implements Migration {
-  // Specify the version from which to upgrade
-  version = 2;
-
-  migrate(data: MigrationData<V2ConfigState>): MigrationData<V3ConfigState> {
-    const { sessions } = data.state;
-
-    return {
-      ...data,
-      state: {
-        ...data.state,
-        sessions: sessions.map((s) => this.migrateSession(s)),
-      },
-    };
-  }
-
-  migrateSession = (session: V2Session): V3Session => {
-    return {
-      ...session,
-      group: 'default',
-      pinned: session.group === 'pinned',
-    };
-  };
+### UI Implementation and Action Binding
+
+We're adding a new category of settings this time. In `src/features/AgentSetting`, various UI components for agent settings are defined. This time we're adding a setting type: opening settings. We'll add a folder `AgentOpening` to store opening settings-related components. The project uses:
+
+- [ant-design](https://ant.design/) and [lobe-ui](https://github.com/lobehub/lobe-ui): component libraries
+- [antd-style](https://ant-design.github.io/antd-style): css-in-js solution
+- [react-layout-kit](https://github.com/arvinxx/react-layout-kit): responsive layout components
+- [@ant-design/icons](https://ant.design/components/icon-cn) and [lucide](https://lucide.dev/icons/): icon libraries
+- [react-i18next](https://github.com/i18next/react-i18next) and [lobe-i18n](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n): i18n framework and multi-language automatic translation tool
+
+lobe-chat is an internationalized project, so newly added text needs to update the default `locale` file: `src/locales/default/setting.ts`.
+
+Let's take the subcomponent `OpeningQuestion.tsx` as an example. Component implementation:
+
+```typescript
+// src/features/AgentSetting/AgentOpening/OpeningQuestions.tsx
+'use client';
+
+import { DeleteOutlined, PlusOutlined } from '@ant-design/icons';
+import { SortableList } from '@lobehub/ui';
+import { Button, Empty, Input } from 'antd';
+import { createStyles } from 'antd-style';
+import { memo, useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Flexbox } from 'react-layout-kit';
+
+import { useStore } from '../store';
+import { selectors } from '../store/selectors';
+
+const useStyles = createStyles(({ css, token }) => ({
+  empty: css`
+    margin-block: 24px;
+    margin-inline: 0;
+  `,
+  questionItemContainer: css`
+    margin-block-end: 8px;
+    padding-block: 2px;
+    padding-inline: 10px 0;
+    background: ${token.colorBgContainer};
+  `,
+  questionItemContent: css`
+    flex: 1;
+  `,
+  questionsList: css`
+    width: 100%;
+    margin-block-start: 16px;
+  `,
+  repeatError: css`
+    margin: 0;
+    color: ${token.colorErrorText};
+  `,
+}));
+
+interface QuestionItem {
+  content: string;
+  id: number;
 }
-```
-
-It can be seen that the migration implementation is very simple. However, it is important to ensure the correctness of the migration, so corresponding test cases need to be written in `src/migrations/FromV2ToV3/migrations.test.ts`:
-
-```ts
-import { MigrationData, VersionController } from '@/migrations/VersionController';
-
-import { MigrationV1ToV2 } from '../FromV1ToV2';
-import inputV1Data from '../FromV1ToV2/fixtures/input-v1-session.json';
-import inputV2Data from './fixtures/input-v2-session.json';
-import outputV3DataFromV1 from './fixtures/output-v3-from-v1.json';
-import outputV3Data from './fixtures/output-v3.json';
-import { MigrationV2ToV3 } from './index';
-
-describe('MigrationV2ToV3', () => {
-  let migrations;
-  let versionController: VersionController<any>;
-
-  beforeEach(() => {
-    migrations = [MigrationV2ToV3];
-    versionController = new VersionController(migrations, 3);
-  });
 
-  it('should migrate data correctly through multiple versions', () => {
-    const data: MigrationData = inputV2Data;
-
-    const migratedData = versionController.migrate(data);
+const OpeningQuestions = memo(() => {
+  const { t } = useTranslation('setting');
+  const { styles } = useStyles();
+  const [questionInput, setQuestionInput] = useState('');
+
+  // Use selector to access corresponding configuration
+  const openingQuestions = useStore(selectors.openingQuestions);
+  // Use action to update configuration
+  const updateConfig = useStore((s) => s.setAgentConfig);
+  const setQuestions = useCallback(
+    (questions: string[]) => {
+      updateConfig({ openingQuestions: questions });
+    },
+    [updateConfig],
+  );
 
-    expect(migratedData.version).toEqual(outputV3Data.version);
-    expect(migratedData.state.sessions).toEqual(outputV3Data.state.sessions);
-    expect(migratedData.state.topics).toEqual(outputV3Data.state.topics);
-    expect(migratedData.state.messages).toEqual(outputV3Data.state.messages);
-  });
+  const addQuestion = useCallback(() => {
+    if (!questionInput.trim()) return;
+
+    setQuestions([...openingQuestions, questionInput.trim()]);
+    setQuestionInput('');
+  }, [openingQuestions, questionInput, setQuestions]);
+
+  const removeQuestion = useCallback(
+    (content: string) => {
+      const newQuestions = [...openingQuestions];
+      const index = newQuestions.indexOf(content);
+      newQuestions.splice(index, 1);
+      setQuestions(newQuestions);
+    },
+    [openingQuestions, setQuestions],
+  );
 
-  it('should work correct from v1 to v3', () => {
-    const data: MigrationData = inputV1Data;
+  // Handle logic after drag and drop sorting
+  const handleSortEnd = useCallback(
+    (items: QuestionItem[]) => {
+      setQuestions(items.map((item) => item.content));
+    },
+    [setQuestions],
+  );
 
-    versionController = new VersionController([MigrationV2ToV3, MigrationV1ToV2], 3);
+  const items: QuestionItem[] = useMemo(() => {
+    return openingQuestions.map((item, index) => ({
+      content: item,
+      id: index,
+    }));
+  }, [openingQuestions]);
 
-    const migratedData = versionController.migrate(data);
+  const isRepeat = openingQuestions.includes(questionInput.trim());
 
-    expect(migratedData.version).toEqual(outputV3DataFromV1.version);
-    expect(migratedData.state.sessions).toEqual(outputV3DataFromV1.state.sessions);
-    expect(migratedData.state.topics).toEqual(outputV3DataFromV1.state.topics);
-    expect(migratedData.state.messages).toEqual(outputV3DataFromV1.state.messages);
-  });
+  return (
+    <Flexbox gap={8}>
+      <Flexbox gap={4}>
+        <Input
+          addonAfter={
+            <Button
+              // don't allow repeat
+              disabled={openingQuestions.includes(questionInput.trim())}
+              icon={<PlusOutlined />}
+              onClick={addQuestion}
+              size="small"
+              type="text"
+            />
+          }
+          onChange={(e) => setQuestionInput(e.target.value)}
+          onPressEnter={addQuestion}
+          placeholder={t('settingOpening.openingQuestions.placeholder')}
+          value={questionInput}
+        />
+
+        {isRepeat && (
+          <p className={styles.repeatError}>{t('settingOpening.openingQuestions.repeat')}</p>
+        )}
+      </Flexbox>
+
+      <div className={styles.questionsList}>
+        {openingQuestions.length > 0 ? (
+          <SortableList
+            items={items}
+            onChange={handleSortEnd}
+            renderItem={(item) => (
+              <SortableList.Item className={styles.questionItemContainer} id={item.id}>
+                <SortableList.DragHandle />
+                <div className={styles.questionItemContent}>{item.content}</div>
+                <Button
+                  icon={<DeleteOutlined />}
+                  onClick={() => removeQuestion(item.content)}
+                  type="text"
+                />
+              </SortableList.Item>
+            )}
+          />
+        ) : (
+          <Empty
+            className={styles.empty}
+            description={t('settingOpening.openingQuestions.empty')}
+          />
+        )}
+      </div>
+    </Flexbox>
+  );
 });
-```
 
-```markdown
+export default OpeningQuestions;
 ```
 
-Unit tests require the use of `fixtures` to fix the test data. The test cases include verification logic for two parts: 1) the correctness of a single migration (v2 -> v3) and 2) the correctness of a complete migration (v1 -> v3).
+At the same time, we need to display the opening configuration set by the user, which is on the chat page. The corresponding component is in `src/app/[variants]/(main)/chat/(workspace)/@conversation/features/ChatList/WelcomeChatItem/WelcomeMessage.tsx`:
 
-> \[!Important]
->
-> The version number in the configuration file may not match the database version number, as database version updates do not always involve changes to the data structure (such as adding tables or fields), while configuration file version updates usually involve data migration.
+```typescript
+const WelcomeMessage = () => {
+  const { t } = useTranslation('chat');
 
-````
+  // Get current opening configuration
+  const openingMessage = useAgentStore(agentSelectors.openingMessage);
+  const openingQuestions = useAgentStore(agentSelectors.openingQuestions);
 
-#### Database Migration
+  const meta = useSessionStore(sessionMetaSelectors.currentAgentMeta, isEqual);
+  const { isAgentEditable } = useServerConfigStore(featureFlagsSelectors);
+  const activeId = useChatStore((s) => s.activeId);
 
-Database migration needs to be implemented in the `LocalDB` class, which is defined in the `src/database/core/db.ts` file. The migration process involves adding a new `pinned` field for each record in the `sessions` table and resetting the `group` field:
-
-```diff
-export class LocalDB extends Dexie {
-  public files: LobeDBTable<'files'>;
-  public sessions: LobeDBTable<'sessions'>;
-  public messages: LobeDBTable<'messages'>;
-  public topics: LobeDBTable<'topics'>;
-  public plugins: LobeDBTable<'plugins'>;
-  public sessionGroups: LobeDBTable<'sessionGroups'>;
-
-  constructor() {
-    super(LOBE_CHAT_LOCAL_DB_NAME);
-    this.version(1).stores(dbSchemaV1);
-    this.version(2).stores(dbSchemaV2);
-    this.version(3).stores(dbSchemaV3);
-    this.version(4)
-      .stores(dbSchemaV4)
-+     .upgrade((trans) => this.upgradeToV4(trans));
-
-    this.files = this.table('files');
-    this.sessions = this.table('sessions');
-    this.messages = this.table('messages');
-    this.topics = this.table('topics');
-    this.plugins = this.table('plugins');
-    this.sessionGroups = this.table('sessionGroups');
-  }
-
-+  /**
-+   * 2024.01.22
-+   *
-+   * DB V3 to V4
-+   * from `group = pinned` to `pinned:true`
-+   */
-+  upgradeToV4 = async (trans: Transaction) => {
-+    const sessions = trans.table('sessions');
-+    await sessions.toCollection().modify((session) => {
-+      // translate boolean to number
-+      session.pinned = session.group === 'pinned' ? 1 : 0;
-      session.group = 'default';
-    });
-+  };
-}
-````
-
-This is our data migration strategy. When performing the migration, it is essential to ensure the correctness of the migration script and validate the migration results through thorough testing.
-
-## 6. Data Import and Export
-
-In LobeChat, the data import and export feature is designed to ensure that users can migrate their data between different devices. This includes session, topic, message, and settings data. In the implementation of the Session Group feature, we also need to handle data import and export to ensure that the complete exported data can be restored exactly the same on other devices.
-
-The core implementation of data import and export is in the `ConfigService` in `src/service/config.ts`, with key methods as follows:
-
-| Method Name           | Description                |
-| --------------------- | -------------------------- |
-| `importConfigState`   | Import configuration data  |
-| `exportAgents`        | Export all agent data      |
-| `exportSessions`      | Export all session data    |
-| `exportSingleSession` | Export single session data |
-| `exportSingleAgent`   | Export single agent data   |
-| `exportSettings`      | Export settings data       |
-| `exportAll`           | Export all data            |
-
-### Data Export
-
-In LobeChat, when a user chooses to export data, the current session, topic, message, and settings data are packaged into a JSON file and provided for download. The standard structure of this JSON file is as follows:
-
-```json
-{
-  "exportType": "sessions",
-  "state": {
-    "sessions": [],
-    "topics": [],
-    "messages": []
-  },
-  "version": 3
-}
-```
-
-Where:
-
-- `exportType`: Identifies the type of data being exported, currently including `sessions`, `agent`, `settings`, and `all`.
-- `state`: Stores the actual data, with different data types for different `exportType`.
-- `version`: Indicates the data version.
-
-In the implementation of the Session Group feature, we need to add `sessionGroups` data to the `state` field. This way, when users export data, their Session Group data will also be included.
-
-For example, when exporting sessions, the relevant implementation code modification is as follows:
-
-```diff
-class ConfigService {
-  // ... Other code omitted
+  const agentSystemRoleMsg = t('agentDefaultMessageWithSystemRole', {
+    name: meta.title || t('defaultAgent'),
+    systemRole: meta.description,
+  });
 
-  exportSessions = async () => {
-    const sessions = await sessionService.getAllSessions();
-+   const sessionGroups = await sessionService.getSessionGroups();
-    const messages = await messageService.getAllMessages();
-    const topics = await topicService.getAllTopics();
+  const agentMsg = t(isAgentEditable ? 'agentDefaultMessage' : 'agentDefaultMessageWithoutEdit', {
+    name: meta.title || t('defaultAgent'),
+    url: `/chat/settings?session=${activeId}`,
+  });
 
--   const config = createConfigFile('sessions', { messages, sessions, topics });
-+   const config = createConfigFile('sessions', { messages, sessionGroups, sessions, topics });
+  const message = useMemo(() => {
+    // Use user-set message if available
+    if (openingMessage) return openingMessage;
+    return !!meta.description ? agentSystemRoleMsg : agentMsg;
+  }, [openingMessage, agentSystemRoleMsg, agentMsg, meta.description]);
+
+  const chatItem = (
+    <ChatItem
+      avatar={meta}
+      editing={false}
+      message={message}
+      placement={'left'}
+      type={type === 'chat' ? 'block' : 'pure'}
+    />
+  );
 
-    exportConfigFile(config, 'sessions');
-  };
-}
+  return openingQuestions.length > 0 ? (
+    <Flexbox>
+      {chatItem}
+      {/* Render guiding questions */}
+      <OpeningQuestions mobile={mobile} questions={openingQuestions} />
+    </Flexbox>
+  ) : (
+    chatItem
+  );
+};
+export default WelcomeMessage;
 ```
 
-### Data Import
-
-The data import functionality is implemented through `ConfigService.importConfigState`. When users choose to import data, they need to provide a JSON file that conforms to the above structure specification. The `importConfigState` method accepts the data of the configuration file and imports it into the application.
-
-In the implementation of the Session Group feature, we need to handle the `sessionGroups` data during the data import process. This way, when users import data, their Session Group data will also be imported correctly.
-
-The following is the modified code for the import implementation in `importConfigState`:
+## 5. Testing
 
-```diff
-class ConfigService {
-  // ... Other code omitted
-
-+ importSessionGroups = async (sessionGroups: SessionGroupItem[]) => {
-+   return sessionService.batchCreateSessionGroups(sessionGroups);
-+ };
-
-  importConfigState = async (config: ConfigFile): Promise<ImportResults | undefined> => {
-    switch (config.exportType) {
-      case 'settings': {
-        await this.importSettings(config.state.settings);
-
-        break;
-      }
-
-      case 'agents': {
-+       const sessionGroups = await this.importSessionGroups(config.state.sessionGroups);
-
-        const data = await this.importSessions(config.state.sessions);
-        return {
-+         sessionGroups: this.mapImportResult(sessionGroups),
-          sessions: this.mapImportResult(data),
-        };
-      }
-
-      case 'all': {
-        await this.importSettings(config.state.settings);
-
-+       const sessionGroups = await this.importSessionGroups(config.state.sessionGroups);
-
-        const [sessions, messages, topics] = await Promise.all([
-          this.importSessions(config.state.sessions),
-          this.importMessages(config.state.messages),
-          this.importTopics(config.state.topics),
-        ]);
-
-        return {
-          messages: this.mapImportResult(messages),
-+         sessionGroups: this.mapImportResult(sessionGroups),
-          sessions: this.mapImportResult(sessions),
-          topics: this.mapImportResult(topics),
-        };
-      }
-
-      case 'sessions': {
-+       const sessionGroups = await this.importSessionGroups(config.state.sessionGroups);
-
-        const [sessions, messages, topics] = await Promise.all([
-          this.importSessions(config.state.sessions),
-          this.importMessages(config.state.messages),
-          this.importTopics(config.state.topics),
-        ]);
-
-        return {
-          messages: this.mapImportResult(messages),
-+         sessionGroups: this.mapImportResult(sessionGroups),
-          sessions: this.mapImportResult(sessions),
-          topics: this.mapImportResult(topics),
-        };
-      }
-    }
-  };
-}
-```
+The project uses vitest for unit testing.
 
-One key point of the above modification is to import sessionGroup first, because if sessions are imported first and the corresponding SessionGroup Id is not found in the current database, the group of this session will default to be modified to the default value. This will prevent the correct association of the sessionGroup's ID with the session.
+Since our two new configuration fields are both optional, theoretically you could pass the tests without updating them. However, since we added the `openingQuestions` field to the `DEFAULT_AGENT_CONFIG` mentioned earlier, this causes many tests to calculate configurations that include this field, so we still need to update some test snapshots.
 
-This is the implementation of the LobeChat Session Group feature in the data import and export process. This approach ensures that users' Session Group data is correctly handled during the import and export process.
+For the current scenario, I recommend running the tests locally to see which tests fail, and then update them as needed. For example, for the test file `src/store/agent/slices/chat/selectors/agent.test.ts`, you need to run `npx vitest -u src/store/agent/slices/chat/selectors/agent.test.ts` to update the snapshot.
 
 ## Summary
 
-The above is the complete implementation process of the LobeChat Session Group feature. Developers can refer to this document for the development and testing of related functionalities.
+The above is the complete implementation process for the LobeChat opening settings feature. Developers can refer to this document for the development and testing of related features.