@lobehub/chat 1.80.0 → 1.80.2

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

@@ -2,705 +2,462 @@
 
 本文档旨在指导开发者了解如何在 LobeChat 中开发一块完整的功能需求。
 
-我们将以 sessionGroup 的实现为示例：[✨ feat: add session group manager](https://github.com/lobehub/lobe-chat/pull/1055) ， 通过以下六个主要部分来阐述完整的实现流程：
+我们将以 [RFC 021 - 自定义助手开场引导](https://github.com/lobehub/lobe-chat/discussions/891) 为例，阐述完整的实现流程。
 
-1. [数据模型 / 数据库定义](#一数据模型--数据库定义)
-2. [Service 实现 / Model 实现](#二service-实现--model-实现)
-3. [前端数据流 Store 实现](#三前端数据流-store-实现)
-4. [UI 实现与 action 绑定](#四ui-实现与-action-绑定)
-5. [数据迁移](#五数据迁移)
-6. [数据导入导出](#六数据导入导出)
+## 一、更新 schema
 
-## 一、数据模型 / 数据库定义
+lobe-chat 使用 postgres 数据库，浏览器端本地数据库使用 [pglite](https://pglite.dev/)（wasm 版本 postgres）。项目还使用了 [drizzle](https://orm.drizzle.team/) ORM 用来操作数据库。
 
-为了实现 Session Group 功能，首先需要在数据库层面定义相关的数据模型和索引。
+相比旧方案浏览器端使用 indexDB 来说，浏览器端和 server 端都使用 postgres 好处在于 model 层代码可以完全复用。
 
-定义一个新的 sessionGroup 表，分 3 步：
-
-### 1. 建立数据模型 schema
-
-在 `src/database/schema/sessionGroup.ts` 中定义 `DB_SessionGroup` 的数据模型：
-
-```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. 创建数据库索引
-
-由于要新增一个表，所以需要在在数据库 Schema 中，为 `sessionGroup` 表添加索引。
-
-在 `src/database/core/schema.ts` 中添加 `dbSchemaV4`:
+schemas 都统一放在 `src/database/schemas`，我们需要调整 `agents` 表增加两个配置项对应的字段：
 
 ```diff
-// ... 前面的一些实现
-
-// ************************************** //
-// ******* 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]
->
-> 除了 `sessionGroups` 外，此处也修改了 `sessions` 的定义，原因是存在数据迁移的情况。但由于本节只关注 schema 定义，不展开数据迁移部分实现，详情可见第五节。
-
-> \[!Important]
->
-> 如果你不了解为何此处需要创建索引，以及不了解此处的 schema 的定义语法。你可能需要提前了解下 Dexie.js 相关的基础知识。
-
-### 3. 在本地 DB 中加入 sessionGroups 表
-
-扩展本地数据库类以包含新的 `sessionGroups` 表：
-
-```diff
-
-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;
-}
+// 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
+  }),
+);
 
-// 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');
-  }
-}
 ```
 
-如此一来，你就可以通过在 `Application` -> `Storage` -> `IndexedDB` 中查看到 `LOBE_CHAT_DB` 里的 `sessionGroups` 表了。
+需要注意的是，有些时候我们可能还需要更新索引，但对于这个需求我们没有相关的性能瓶颈问题，所以不需要更新索引。
 
-![](https://github.com/lobehub/lobe-chat/assets/28616219/aea50f66-4060-4a32-88c8-b3c672d05be8)
+调整完 schema 后我们需要运行 `npm run db:generate，` 使用 drizzle-kit 自带的数据库迁移能力生成对应的用于迁移到最新 schema 的 sql 代码。执行后会产生四个文件：
 
-## 二、Service 实现 / Model 实现
+- src/database/migrations/meta/\_journal.json：保存每次迁移的相关信息
+- src/database/migrations/0021\_add\_agent\_opening\_settings.sql：此次迁移的 sql 命令
+- src/database/client/migrations.json：pglite 使用的此次迁移的 sql 命令
+- src/database/migrations/meta/0021\_snapshot.json：当前最新的完整数据库快照
 
-### 定义 Model
+注意脚本默认生成的迁移 sql 文件名不会像 `0021_add_agent_opening_settings.sql` 这样语义清晰，你需要自己手动对它重命名并且更新 `src/database/migrations/meta/_journal.json`。
 
-在构建 LobeChat 应用时，Model 负责与数据库的交互，它定义了如何读取、插入、更新和删除数据库的数据，定义具体的业务逻辑。
+以前客户端存储使用 indexDB 数据迁移相对麻烦，现在本地端使用 pglite 之后数据库迁移就是一条命令的事，非常简单快捷，你也可以检查生成的迁移 sql 是否有什么优化空间，手动调整。
 
-在 `src/database/model/sessionGroup.ts` 中定义 `SessionGroupModel`：
+## 二、更新数据模型
 
-```ts
-import { BaseModel } from '@/database/client/core';
-import { DB_SessionGroup, DB_SessionGroupSchema } from '@/database/client/schemas/sessionGroup';
-import { nanoid } from '@/utils/uuid';
+在 `src/types` 下定义了我们项目中使用到的各种数据模型，我们并没有直接使用 drizzle schema 导出的类型，例如 `export type NewAgent = typeof agents.$inferInsert;`，而是根据前端需求和 db schema 定义中对应字段数据类型定义了对应的数据模型。
 
-class _SessionGroupModel extends BaseModel {
-  constructor() {
-    super('sessions', DB_SessionGroupSchema);
-  }
+数据模型定义都放在 `src/types` 文件夹下，更新 `src/types/agent/index.ts` 中 `LobeAgentConfig` 类型：
 
-  async create(name: string, sort?: number, id = nanoid()) {
-    return this._add({ name, sort }, id);
-  }
-
-  // ... 其他 CRUD 方法的实现
-}
-
-export const SessionGroupModel = new _SessionGroupModel();
-```
-
-### Service 实现
-
-在 LobeChat 中，Service 层主要负责与后端服务进行通信，封装业务逻辑，并提供数据给前端的其他层使用。`SessionService` 是一个专门处理与会话（Session）相关业务逻辑的服务类，它封装了创建会话、查询会话、更新会话等操作。
-
-为了保持代码的可维护性和可扩展性，我们将会话分组相关的服务逻辑放在 `SessionService` 中，这样可以使会话领域的业务逻辑保持内聚。当业务需求增加或变化时，我们可以更容易地在这个领域内进行修改和扩展。
-
-`SessionService` 通过调用 `SessionGroupModel` 的方法来实现对会话分组的管理。 在 `sessionService` 中实现 Session Group 相关的请求逻辑：
+```diff
+export interface LobeAgentConfig {
+  // ...
+  chatConfig: LobeAgentChatConfig;
+  /**
+   * 角色所使用的语言模型
+   * @default gpt-4o-mini
+   */
+  model: string;
 
-```ts
-class SessionService {
-  // ... 省略 session 业务逻辑
++  /**
++   * 开场白
++   */
++  openingMessage?: string;
++  /**
++   * 开场问题
++   */
++  openingQuestions?: string[];
 
-  // ************************************** //
-  // ***********  SessionGroup  *********** //
-  // ************************************** //
+  /**
+   * 语言模型参数
+   */
+  params: LLMParams;
+  /**
+   * 启用的插件
+   */
+  plugins?: string[];
 
-  async createSessionGroup(name: string, sort?: number) {
-    const item = await SessionGroupModel.create(name, sort);
-    if (!item) {
-      throw new Error('session group create Error');
-    }
+  /**
+   *  模型供应商
+   */
+  provider?: string;
 
-    return item.id;
-  }
+  /**
+   * 系统角色
+   */
+  systemRole: string;
 
-  // ... 其他 SessionGroup 相关的实现
+  /**
+   * 语音服务
+   */
+  tts: LobeAgentTTSConfig;
 }
 ```
 
-## 三、前端数据流 Store 实现
-
-在 LobeChat 应用中，Store 是用于管理应用前端状态的模块。其中的 Action 是触发状态更新的函数，通常会调用服务层的方法来执行实际的数据处理操作，然后更新 Store 中的状态。我们采用了 `zustand` 作为 Store 模块的底层依赖，对于状态管理的详细实践介绍，可以查阅 [📘 状态管理最佳实践](/zh/docs/development/state-management/state-management-intro)
+## 三、Service 实现 / Model 实现
 
-### sessionGroup CRUD
+- `model` 层封装对 DB 的可复用操作
+- `service` 层实现应用业务逻辑
 
-会话组的 CRUD 操作是管理会话组数据的核心行为。在 `src/store/session/slice/sessionGroup` 中，我们将实现与会话组相关的状态逻辑，包括添加、删除、更新会话组及其排序。
+在 `src` 目录下都有对应的顶层文件夹。
 
-以下是 `action.ts` 文件中需要实现的 `SessionGroupAction` 接口方法：
+我们需要查看是否需要更新其实现，agent 配置在前端被抽象成 session 的配置，在 `src/services/session/server.ts` 中可以看到有个 service 函数 `updateSessionConfig`：
 
-```ts
-export interface SessionGroupAction {
-  // 增加会话组
-  addSessionGroup: (name: string) => Promise<string>;
-  // 删除会话组
-  removeSessionGroup: (id: string) => Promise<void>;
-  // 更新会话的会话组 ID
-  updateSessionGroupId: (sessionId: string, groupId: string) => Promise<void>;
-  // 更新会话组名称
-  updateSessionGroupName: (id: string, name: string) => Promise<void>;
-  // 更新会话组排序
-  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 });
+  };
 }
 ```
 
-以 `addSessionGroup` 方法为例，我们首先调用 `sessionService` 的 `createSessionGroup` 方法来创建新的会话组，然后使用 `refreshSessions` 方法来刷新 sessions 状态：
-
-```ts
-export const createSessionGroupSlice: StateCreator<
-  SessionStore,
-  [['zustand/devtools', never]],
-  [],
-  SessionGroupAction
-> = (set, get) => ({
-  // 实现添加会话组的逻辑
-  addSessionGroup: async (name) => {
-    // 调用服务层的 createSessionGroup 方法并传入会话组名称
-    const id = await sessionService.createSessionGroup(name);
-    // 调用 get 方法获取当前的 Store 状态并执行 refreshSessions 方法刷新会话数据
-    await get().refreshSessions();
-    // 返回新创建的会话组 ID
-    return id;
-  },
-  // ... 其他 action 实现
-});
-```
-
-通过以上的实现，我们可以确保在添加新的会话组后，应用的状态会及时更新，且相关的组件会收到最新的状态并重新渲染。这种方式提高了数据流的可预测性和可维护性，同时也简化了组件之间的通信。
-
-### Sessions 分组逻辑改造
-
-本次需求改造需要对 Sessions 进行升级，从原来的单一列表变成了三个不同的分组：`pinnedSessions`（置顶列表）、`customSessionGroups`（自定义分组）和 `defaultSessions`（默认列表）。
-
-为了处理这些分组，我们需要改造 `useFetchSessions` 的实现逻辑。以下是关键的改动点：
-
-1. 使用 `sessionService.getGroupedSessions` 方法负责调用后端接口来获取分组后的会话数据；
-2. 将获取后的数据保存为三到不同的状态字段中：`pinnedSessions`、`customSessionGroups` 和 `defaultSessions`；
-
-#### `useFetchSessions` 方法
-
-该方法在 `createSessionSlice` 中定义，如下所示：
-
-```ts
-export const createSessionSlice: StateCreator<
-  SessionStore,
-  [['zustand/devtools', never]],
-  [],
-  SessionAction
-> = (set, get) => ({
-  // ... 其他方法
-  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),
-        );
-      },
+跳转 `lambdaClient.session.updateSessionConfig` 实现，发现它只是简单的 **merge** 了新的 config 和旧的 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);
     }),
 });
 ```
 
-在成功获取数据后，我们使用 `set` 方法来更新 `customSessionGroups`、`defaultSessions`、`pinnedSessions` 和 `sessions` 状态。这将保证状态与最新的会话数据同步。
-
-#### getGroupedSessions
-
-使用 `sessionService.getGroupedSessions` 方法负责调用后端接口 `SessionModel.queryWithGroups()`
-
-```ts
-class SessionService {
-  // ... 其他 SessionGroup 相关的实现
-
-  async getGroupedSessions(): Promise<ChatSessionList> {
-    return SessionModel.queryWithGroups();
-  }
-}
-```
-
-#### `SessionModel.queryWithGroups` 方法
+可以预想的到，我们前端会增加两个输入，用户修改的时候去调用这个 `updateSessionConfig`，而目前的时候都没细粒度到 config 中的具体字段，因此，service 层和 model 层不需要修改。
 
-此方法是 `sessionService.getGroupedSessions` 调用的核心方法，它负责查询和组织会话数据，代码如下：
+## 四、前端实现
 
-```ts
-class _SessionModel extends BaseModel {
-  // ... 其他方法
+### 数据流 store 实现
 
-  /**
-   * 查询会话数据，并根据会话组将会话分类。
-   * @returns {Promise<ChatSessionList>} 返回一个对象，其中包含所有会话以及分为不同组的会话列表。
-   */
-  async queryWithGroups(): Promise<ChatSessionList> {
-    // 查询会话组数据
-    const groups = await SessionGroupModel.query();
-    // 根据会话组ID查询自定义会话组
-    const customGroups = await this.queryByGroupIds(groups.map((item) => item.id));
-    // 查询默认会话列表
-    const defaultItems = await this.querySessionsByGroupId(SessionDefaultGroup.Default);
-    // 查询置顶的会话
-    const pinnedItems = await this.getPinnedSessions();
-
-    // 查询所有会话
-    const all = await this.query();
-    // 组合并返回所有会话及其分组信息
-    return {
-      all, // 包含所有会话的数组
-      customGroup: groups.map((group) => ({ ...group, children: customGroups[group.id] })), // 自定义分组
-      default: defaultItems, // 默认会话列表
-      pinned: pinnedItems, // 置顶会话列表
-    };
-  }
-}
-```
+lobe-chat 使用 [zustand](https://zustand.docs.pmnd.rs/getting-started/introduction) 作为全局状态管理框架，对于状态管理的详细实践介绍，可以查阅 [📘 状态管理最佳实践](/zh/docs/development/state-management/state-management-intro)。
 
-方法 `queryWithGroups` 首先查询所有会话组，然后基于这些组的 ID 查询自定义会话组，同时查询默认和固定的会话。最后，它返回一个包含所有会话和按组分类的会话列表对象。
+和 agent 相关的 store 有两个：
 
-### sessions selectors 调整
+- `src/features/AgentSetting/store` 服务于 agent 设置的局部 store
+- `src/store/agent` 用于获取当前会话 agent 的 store
 
-由于 sessions 中关于分组的逻辑发生了变化，因此我们需要调整 `sessions` 的 selectors 逻辑，以确保它们能够正确地处理新的数据结构。
+后者通过 `src/features/AgentSetting/AgentSettings.tsx` 中 `AgentSettings` 组件的 `onConfigChange` 监听并更新当前会话的 agent 配置。
 
-原有的 selectors:
-
-```ts
-// 默认分组
-const defaultSessions = (s: SessionStore): LobeSessions => s.sessions;
-
-// 置顶分组
-const pinnedSessionList = (s: SessionStore) =>
-  defaultSessions(s).filter((s) => s.group === SessionGroupDefaultKeys.Pinned);
-
-// 未置顶分组
-const unpinnedSessionList = (s: SessionStore) =>
-  defaultSessions(s).filter((s) => s.group === SessionGroupDefaultKeys.Default);
-```
+#### 更新 AgentSetting/store
 
-修改后：
+首先我们更新 initialState，阅读 `src/features/AgentSetting/store/initialState.ts` 后得知初始 agent 配置保存在 `src/const/settings/agent.ts` 中的 `DEFAULT_AGENT_CONFIG`：
 
-```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,
+};
 ```
 
-由于在 UI 中的取数全部是通过 `useSessionStore(sessionSelectors.defaultSessions)` 这样的写法实现的，因此我们只需要修改 `defaultSessions` 的选择器实现，即可完成数据结构的变更。 UI 层的取数代码完全不用变更，可以大大降低重构的成本和风险。
+其实你这里不更新都可以，因为 `openingQuestions` 类型本来就是可选的，`openingMessage` 我这里就不更新了。
 
-> !\[Important]
-> 如果你对 Selectors 的概念和功能不太了解，可以查阅 [📘 数据存储取数模块](/zh/docs/development/state-management/state-management-selectors) 部分了解相关内容。
+因为我们增加了两个新字段，为了方便在 `src/features/AgentSetting/AgentOpening` 文件夹中组件访问和性能优化，我们在 `src/features/AgentSetting/store/selectors.ts` 增加相关的 selectors：
 
-## 四、UI 实现与 action 绑定
-
-在 UI 组件中绑定 Store Action 实现交互逻辑，例如 `CreateGroupModal`：
+```diff
+import { DEFAULT_AGENT_CHAT_CONFIG } from '@/const/settings';
+import { LobeAgentChatConfig } from '@/types/agent';
 
-```tsx
-const CreateGroupModal = () => {
-  // ... 其他逻辑
+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 () => {
-        // ... 其他逻辑
-        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,
 };
 ```
 
-## 五、数据迁移
-
-在软件开发过程中，数据迁移是一个不可避免的问题，尤其是当现有的数据结构无法满足新的业务需求时。对于本次 SessionGroup 的迭代，我们需要处理 `session` 的 `group` 字段的迁移，这是一个典型的数据迁移案例。
-
-### 旧数据结构的问题
-
-在旧的数据结构中，`group` 字段被用来标记会话是否为 `pinned`（置顶）或属于某个 `default`（默认）分组。但是当需要支持多个会话分组时，原有的数据结构就显得不够灵活了。
+这里我们就不增加额外的 action 用于更新 agent config 了，因为我观察到已有的其它代码也是直接使用现有代码中统一的 `setChatConfig`：
 
-例如：
-
-```
-before   pin:  group = abc
-after    pin:  group = pinned
-after  unpin:  group = default
+```typescript
+export const store: StateCreator<Store, [['zustand/devtools', never]]> = (set, get) => ({
+  setAgentConfig: (config) => {
+    get().dispatchConfig({ config, type: 'update' });
+  },
+});
 ```
 
-从上述示例中可以看出，一旦会话从置顶状态（`pinned`）取消置顶（`unpin`），`group` 字段将无法恢复为原来的 `abc` 值。这是因为我们没有一个独立的字段来维护置顶状态。因此，我们引入了一个新的字段 `pinned` 来表示会话是否被置顶，而 `group` 字段将仅用于标识会话分组。
-
-### 迁移策略
+#### 更新 store/agent
 
-本次迁移的核心逻辑只有一条：
+在组件 `src/app/[variants]/(main)/chat/(workspace)/@conversation/features/ChatList/WelcomeChatItem/WelcomeMessage.tsx` 我们使用了这个 store 用于获取当前 agent 配置，用来渲染用户自定义的开场消息和引导性问题。
 
-- 当用户的 `group` 字段为 `pinned` 时，将其 `pinned` 字段置为 `true`，同时将 group 设为 `default`;
+这里因为只需要读取两个配置项，我们就简单的加两个 selectors 就好了：
 
-但 LobeChat 中的数据迁移通常涉及到 **配置文件迁移** 和 **数据库迁移** 两个部分。所以上述逻辑会需要分别在两块实现迁移。
-
-#### 配置文件迁移
-
-对于配置文件迁移，我们建议先于数据库迁移进行，因为配置文件迁移通常更容易进行测试和验证。LobeChat 的文件迁移配置位于 `src/migrations/index.ts` 文件中，其中定义了配置文件迁移的各个版本及对应的迁移脚本。
+更新 `src/store/agent/slices/chat/selectors/agent.ts`：
 
 ```diff
-// 当前最新的版本号
-- export const CURRENT_CONFIG_VERSION = 2;
-+ export const CURRENT_CONFIG_VERSION = 3;
-
-// 历史记录版本升级模块
-const ConfigMigrations = [
-+ /**
-+ * 2024.01.22
-+  * from `group = pinned` to `pinned:true`
-+  */
-+ MigrationV2ToV3,
-  /**
-   * 2023.11.27
-   * 从单 key 数据库转换为基于 dexie 的关系型结构
-   */
-  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,
+};
 ```
 
-本次的配置文件迁移逻辑定义在 `src/migrations/FromV2ToV3/index.ts` 中，简化如下：
-
-```ts
-export class MigrationV2ToV3 implements Migration {
-  // 指定从该版本开始向上升级
-  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 实现和 action 绑定
+
+我们这次要新增一个类别的设置， 在 `src/features/AgentSetting` 中定义了 agent 的各种设置的 UI 组件，这次我们要增加一个设置类型：开场设置。增加一个文件夹 `AgentOpening` 存放开场设置相关的组件。项目使用了：
+
+- [ant-design](https://ant.design/) 和 [lobe-ui：](https://github.com/lobehub/lobe-ui)组件库
+- [antd-style](https://ant-design.github.io/antd-style) ： css-in-js 方案
+- [react-layout-kit](https://github.com/arvinxx/react-layout-kit)：响应式布局组件
+- [@ant-design/icons](https://ant.design/components/icon-cn) 和 [lucide](https://lucide.dev/icons/): 图标库
+- [react-i18next](https://github.com/i18next/react-i18next) 和 [lobe-i18n](https://github.com/lobehub/lobe-cli-toolbox/tree/master/packages/lobe-i18n) ：i18n 框架和多语言自动翻译工具
+
+lobe-chat 是个国际化项目，新加的文案需要更新默认的 `locale` 文件： `src/locales/default/setting.ts` 。
+
+我们以子组件 `OpeningQuestion.tsx` 为例，组件实现：
+
+```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;
 }
-```
-
-可以看到迁移的实现非常简单。但重要的是，我们需要保证迁移的正确性，因此需要编写对应的测试用例 `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('');
+
+  // 使用 selector 访问对应配置
+  const openingQuestions = useStore(selectors.openingQuestions);
+  // 使用 action 更新配置
+  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;
+  // 处理拖拽排序后的逻辑
+  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>
+  );
 });
-```
-
-单测需要使用 `fixtures` 来固定测试数据，测试用例包含了两个部分的验证逻辑： 1） 单次迁移（v2 -> v3）和 2） 完整迁移（v1 -> v3）的正确性。
-
-> \[!Important]
->
-> 配置文件的版本号可能与数据库版本号不一致，因为数据库版本的更新不总是伴随数据结构的变化（如新增表或字段），而配置文件的版本更新则通常涉及到数据迁移。
-
-#### 数据库迁移
 
-数据库迁移则需要在 `LocalDB` 类中实施，该类定义在 `src/database/core/db.ts` 文件中。迁移过程涉及到为 `sessions` 表的每条记录添加新的 `pinned` 字段，并重置 `group` 字段：
-
-```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';
-+    });
-+  };
-}
+export default OpeningQuestions;
 ```
 
-以上就是我们的数据迁移策略。在进行迁移时，务必确保迁移脚本的正确性，并通过充分的测试验证迁移结果。
-
-## 六、数据导入导出
-
-在 LobeChat 中，数据导入导出功能是为了确保用户可以在不同设备之间迁移他们的数据。这包括会话、话题、消息和设置等数据。在本次的 Session Group 功能实现中，我们也需要对数据导入导出进行处理，以确保当完整导出的数据在其他设备上可以一模一样恢复。
-
-数据导入导出的核心实现在 `src/service/config.ts` 的 `ConfigService` 中，其中的关键方法如下：
-
-| 方法名称                  | 描述       |
-| --------------------- | -------- |
-| `importConfigState`   | 导入配置数据   |
-| `exportAgents`        | 导出所有助理数据 |
-| `exportSessions`      | 导出所有会话数据 |
-| `exportSingleSession` | 导出单个会话数据 |
-| `exportSingleAgent`   | 导出单个助理数据 |
-| `exportSettings`      | 导出设置数据   |
-| `exportAll`           | 导出所有数据   |
+同时我们需要将用户设置的开场配置展示出来，这个是在 chat 页面，对应组件在 `src/app/[variants]/(main)/chat/(workspace)/@conversation/features/ChatList/WelcomeChatItem/WelcomeMessage.tsx`：
 
-### 数据导出
+```typescript
+const WelcomeMessage = () => {
+  const { t } = useTranslation('chat');
 
-在 LobeChat 中，当用户选择导出数据时，会将当前的会话、话题、消息和设置等数据打包成一个 JSON 文件并提供给用户下载。这个 JSON 文件的标准结构如下：
-
-```json
-{
-  "exportType": "sessions",
-  "state": {
-    "sessions": [],
-    "topics": [],
-    "messages": []
-  },
-  "version": 3
-}
-```
+  // 获取当前开场配置
+  const openingMessage = useAgentStore(agentSelectors.openingMessage);
+  const openingQuestions = useAgentStore(agentSelectors.openingQuestions);
 
-其中：
+  const meta = useSessionStore(sessionMetaSelectors.currentAgentMeta, isEqual);
+  const { isAgentEditable } = useServerConfigStore(featureFlagsSelectors);
+  const activeId = useChatStore((s) => s.activeId);
 
-- `exportType`： 标识导出数据的类型，目前有 `sessions`、 `agent` 、 `settings` 和 `all` 四种；
-- `state`： 存储实际的数据，不同 `exportType` 的数据类型也不同；
-- `version`： 标识数据的版本。
-
-在 Session Group 功能实现中，我们需要在 `state` 字段中添加 `sessionGroups` 数据。这样，当用户导出数据时，他们的 Session Group 数据也会被包含在内。
-
-以导出 sessions 为例，导出数据的相关实现代码修改如下：
-
-```diff
-class ConfigService {
-  // ... 省略其他
+  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(() => {
+    // 用户设置了就用用户设置的
+    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}
+      {/* 渲染引导性问题 */}
+      <OpeningQuestions mobile={mobile} questions={openingQuestions} />
+    </Flexbox>
+  ) : (
+    chatItem
+  );
+};
+export default WelcomeMessage;
 ```
 
-### 数据导入
-
-数据导入的功能是通过 `ConfigService.importConfigState` 来实现的。当用户选择导入数据时，他们需要提供一个由 符合上述结构规范的 JSON 文件。`importConfigState` 方法接受配置文件的数据，并将其导入到应用中。
-
-在 Session Group 功能实现中，我们需要在导入数据的过程中处理 `sessionGroups` 数据。这样，当用户导入数据时，他们的 Session Group 数据也会被正确地导入。
-
-以下是 `importConfigState` 中导入实现的变更代码：
+## 五、测试
 
-```diff
-class ConfigService {
-  // ... 省略其他代码
-
-+ 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),
-        };
-      }
-    }
-  };
-}
-```
+项目使用 vitest 进行单元测试。
 
-上述修改的一个要点是先进行 sessionGroup 的导入，因为如果先导入 session 时，如果没有在当前数据库中查到相应的 SessionGroup Id，那么这个 session 的 group 会兜底修改为默认值。这样就无法正确地将 sessionGroup 的 ID 与 session 进行关联。
+由于我们目前两个新的配置字段都是可选的，所以理论上你不更新测试也能跑通，不过由于我们把前面提到的默认配置 `DEFAULT_AGENT_CONFIG` 增加了 `openingQuestions` 字段，这导致很多测试计算出的配置都是有这个字段的，因此我们还是需要更新一部分测试的快照。
 
-以上就是 LobeChat Session Group 功能在数据导入导出部分的实现。通过这种方式，我们可以确保用户的 Session Group 数据在导入导出过程中能够被正确地处理。
+对于当前这个场景，我建议是本地直接跑下测试，看哪些测试失败了，针对需要更新，例如测试文件 `src/store/agent/slices/chat/selectors/agent.test.ts` 需要执行一下 `npx vitest -u src/store/agent/slices/chat/selectors/agent.test.ts` 更新快照。
 
 ## 总结
 
-以上就是 LobeChat Session Group 功能的完整实现流程。开发者可以参考本文档进行相关功能的开发和测试。
+以上就是 LobeChat 开场设置功能的完整实现流程。开发者可以参考本文档进行相关功能的开发和测试。