@lobehub/chat 1.2.0 → 1.2.2

package/contributing/State-Management/State-Management-Intro.md

@@ -0,0 +1,224 @@
+# Best Practices for State Management
+
+LobeChat differs from traditional CRUD web applications in that it involves a large amount of rich interactive capabilities. Therefore, it is crucial to design a data flow architecture that is easy to develop and maintain. This document will introduce the best practices for data flow management in LobeChat.
+
+## TOC
+
+- [Key Concepts](#key-concepts)
+- [Hierarchical Structure](#hierarchical-structure)
+  - [Best Practices for LobeChat SessionStore Directory Structure](#best-practices-for-lobechat-sessionstore-directory-structure)
+- [Implementation of SessionStore](#implementation-of-sessionstore)
+
+## Key Concepts
+
+| Concept  | Explanation                                                                                                                                                                                                                                                                                                                                                                      |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| store    | The store contains the application's state and actions. It allows access to and modification of the state during application rendering.                                                                                                                                                                                                                                          |
+| state    | State refers to the data of the application, storing the current state of the application. Any change in the state will **trigger a re-rendering** to reflect the new state.                                                                                                                                                                                                     |
+| action   | An action is an operation function that describes the interactive events occurring in the application. Actions are typically triggered by user interactions, network requests, or timers. Actions can be **synchronous** or **asynchronous**.                                                                                                                                    |
+| reducer  | A reducer is a pure function that takes the current state and action as parameters and returns a new state. It is used to update the application's state based on the action type. A reducer is a pure function with no side effects, therefore it is always a **synchronous** function.                                                                                         |
+| selector | A selector is a function used to retrieve specific data from the application's state. It takes the application's state as a parameter and returns computed or transformed data. Selectors can combine parts of the state or multiple states to generate derived data. Selectors are commonly used to map the application's state to a component's props for the component's use. |
+| slice    | A slice is a concept used to express a part of the data model state. It specifies a state slice and its related state, action, reducer, and selector. Using slices, a large store can be divided into smaller, maintainable subtypes.                                                                                                                                            |
+
+## Hierarchical Structure
+
+The structure of the Store can vary greatly depending on the complexity:
+
+- **Low Complexity**: Generally includes 2 to 5 states and 3 to 4 actions. In this case, the structure usually consists of a `store.ts` and an `initialState.ts`.
+
+```bash
+DataFill/store
+├── index.ts
+└── initialState.ts
+```
+
+- **Moderate Complexity**: Typically involves 5 to 15 states and 5 to 10 actions, with the possibility of selectors for derived states and reducers to simplify data changes. The structure usually includes a `store.ts`, an `initialState.ts`, and a `selectors.ts`/`reducer.ts`.
+
+```bash
+IconPicker/store
+├── index.ts
+├── initialState.ts
+├── selectors.ts
+└── store.ts
+```
+
+```bash
+SortableList/store
+├── index.ts
+├── initialState.ts
+├── listDataReducer.ts
+└── store.ts
+```
+
+- **Medium Complexity**: Involves 15 to 30 states and 10 to 20 actions, often requiring the use of multiple slices to manage different actions. The following code represents the internal data flow of the `SortableTree` component:
+
+```bash
+SortableTree/store
+├── index.ts
+├── initialState.ts
+├── selectors.ts
+├── slices
+│ ├── crudSlice.ts
+│ ├── dndSlice.ts
+│ └── selectionSlice.ts
+├── store.ts
+└── treeDataReducer.ts
+```
+
+- **High Complexity**: Involves over 30 states and 20 actions, requiring modular cohesion using slices. Each slice declares its own initState, actions, reducers, and selectors.
+
+The directory structure of the previous version of SessionStore for LobeChat, with high complexity, implements a large amount of business logic. However, with the modularization of slices and the fractal architecture, it is easy to find the corresponding modules, making it easy to maintain and iterate on new features.
+
+```bash
+LobeChat SessionStore
+├── index.ts
+├── initialState.ts
+├── selectors.ts
+├── slices
+│ ├── agentConfig
+│ │ ├── action.ts
+│ │ ├── index.ts
+│ │ ├── initialState.ts
+│ │ └── selectors.ts
+│ ├── chat
+│ │ ├── actions
+│ │ │ ├── index.ts
+│ │ │ ├── message.ts
+│ │ │ └── topic.ts
+│ │ ├── index.ts
+│ │ ├── initialState.ts
+│ │ ├── reducers
+│ │ │ ├── message.ts
+│ │ │ └── topic.ts
+│ │ ├── selectors
+│ │ │ ├── chat.ts
+│ │ │ ├── index.ts
+│ │ │ ├── token.ts
+│ │ │ ├── topic.ts
+│ │ │ └── utils.ts
+│ │ └── utils.ts
+│ └── session
+│ ├── action.ts
+│ ├── index.ts
+│ ├── initialState.ts
+│ ├── reducers
+│ │ └── session.ts
+│ └── selectors
+│ ├── export.ts
+│ ├── index.ts
+│ └── list.ts
+└── store.ts
+```
+
+Based on the provided directory structure of LobeChat SessionStore, we can update the previous document and convert the examples to the implementation of LobeChat's SessionStore. The following is a portion of the updated document:
+
+### Best Practices for LobeChat SessionStore Directory Structure
+
+In the LobeChat application, session management is a complex functional module, so we use the Slice pattern to organize the data flow. Below is the directory structure of LobeChat SessionStore, where each directory and file has its specific purpose:
+
+```bash
+src/store/session
+├── helpers.ts                         # Helper functions
+├── hooks                              # Custom React hooks
+│   ├── index.ts                       # Export file for hooks
+│   ├── useEffectAfterHydrated.ts      # Hook for effects after session hydration
+│   ├── useOnFinishHydrationSession.ts # Hook for session hydration completion
+│   ├── useSessionChatInit.ts          # Hook for session chat initialization
+│   └── useSessionHydrated.ts          # Hook for session hydration status
+├── index.ts                           # Aggregated export file for SessionStore
+├── initialState.ts                    # Aggregated initialState for all slices
+├── selectors.ts                       # Selectors exported from various slices
+├── slices                             # Separated functional modules
+│   ├── agent                          # State and operations related to agents
+│   │   ├── action.ts                  # Action definitions related to agents
+│   │   ├── index.ts                   # Entry file for agent slice
+│   │   ├── selectors.test.ts          # Tests for agent-related selectors
+│   │   └── selectors.ts               # Selector definitions related to agents
+│   └── session                        # State and operations related to sessions
+│   ├── action.test.ts                 # Tests for session-related actions
+│   ├── action.ts                      # Action definitions related to sessions
+│   ├── helpers.ts                     # Helper functions related to sessions
+│   ├── initialState.ts                # Initial state for session slice
+│   └── selectors                      # Session-related selectors and their tests
+│   ├── export.ts                      # Aggregated export for session selectors
+│   ├── index.ts                       # Entry file for session selectors
+│   ├── list.test.ts                   # Tests for list selectors
+│   └── list.ts                        # Definitions for list-related selectors
+└── store.ts                           # Creation and usage of SessionStore
+```
+
+## Implementation of SessionStore
+
+In LobeChat, the SessionStore is designed as the core module for managing session state and logic. It consists of multiple Slices, with each Slice managing a relevant portion of state and logic. Below is a simplified example of the SessionStore implementation:
+
+#### store.ts
+
+```ts
+import { PersistOptions, devtools, persist, subscribeWithSelector } from 'zustand/middleware';
+import { shallow } from 'zustand/shallow';
+import { devtools } from 'zustand/middleware';
+import { createWithEqualityFn } from 'zustand/traditional';
+
+import { SessionStoreState, initialState } from './initialState';
+import { AgentAction, createAgentSlice } from './slices/agent/action';
+import { SessionAction, createSessionSlice } from './slices/session/action';
+
+//  ===============  Aggregate createStoreFn ============ //
+
+export type SessionStore = SessionAction & AgentAction & SessionStoreState;
+const createStore: StateCreator<SessionStore, [['zustand/devtools', never]]> = (...parameters) => ({
+  ...initialState,
+  ...createAgentSlice(...parameters),
+  ...createSessionSlice(...parameters),
+});
+
+
+
+//  ===============  Implement useStore ============ //
+
+export const useSessionStore = createWithEqualityFn<SessionStore>()(
+  persist(
+    subscribeWithSelector(
+      devtools(createStore, {
+        name: 'LobeChat_Session' + (isDev ? '_DEV' : ''),
+      }),
+    ),
+    persistOptions,
+  ),
+  shallow,
+);
+
+```
+
+In this `store.ts` file, we create a `useSessionStore` hook that uses the `zustand` library to create a global state manager. We merge the initialState and the state and actions of each Slice to create a complete SessionStore.
+
+#### slices/session/action.ts
+
+```ts
+import { StateCreator } from 'zustand';
+
+import { SessionStore } from '@/store/session';
+
+export interface SessionActions {
+  /**
+   * A custom hook that uses SWR to fetch sessions data.
+   */
+  useFetchSessions: () => SWRResponse<any>;
+}
+
+export const createSessionSlice: StateCreator<
+  SessionStore,
+  [['zustand/devtools', never]],
+  [],
+  SessionAction
+> = (set, get) => ({
+  useFetchSessions: () => {
+    // ...logic for initializing sessions
+  },
+  // ...implementation of other actions
+});
+```
+
+In the `action.ts` file, we define a `SessionActions` interface to describe session-related actions and implement a `useFetchSessions` function to create these actions. Then, we merge these actions with the initial state to form the session-related Slice.
+
+Through this layered and modular approach, we can ensure that LobeChat's SessionStore is clear, maintainable, and easy to extend and test.

package/contributing/State-Management/State-Management-Intro.zh-CN.md

@@ -0,0 +1,216 @@
+# 状态管理最佳实践
+
+LobeChat 不同于传统 CRUD 的网页，存在大量的富交互能力，如何设计一个易于开发与易于维护的数据流架构非常重要。本篇文档将介绍 LobeChat 中的数据流管理最佳实践。
+
+## TOC
+
+- [概念要素](#概念要素)
+- [结构分层](#结构分层)
+  - [LobeChat SessionStore 目录结构最佳实践](#lobechat-sessionstore-目录结构最佳实践)
+- [SessionStore 的实现](#sessionstore-的实现)
+
+## 概念要素
+
+| 概念名词 | 解释                                                                                                                                                                                                                                                                 |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| store    | 状态库 (store)，包含存储应用的状态、动作。允许在应用渲染中访问和修改状态。                                                                                                                                                                                           |
+| state    | 状态 (state) 是指应用程序的数据，存储了应用程序的当前状态，状态的变化**一定会触发应用的重新渲染**，以反映新的状态。                                                                                                                                                  |
+| action   | 动作 (action) 是一个操作函数，它描述了应用程序中发生的交互事件。动作通常是由用户交互、网络请求或定时器等触发。 action 可以是**同步**的，也可以是**异步**的。                                                                                                         |
+| reducer  | 归约器 (reducer) 是一个纯函数，它接收当前状态和动作作为参数，并返回一个新的状态。它用于根据动作类型来更新应用程序的状态。Reducer 是一个纯函数，不存在副作用，因此一定是 **同步** 函数。                                                                              |
+| selector | 选择器 (selector) 是一个函数，用于从应用程序的状态中获取特定的数据。它接收应用程序的状态作为参数，并返回经过计算或转换后的数据。Selector 可以将状态的一部分或多个状态组合起来，以生成派生的数据。Selector 通常用于将应用程序的状态映射到组件的 props，以供组件使用。 |
+| slice    | 切片 (slice) 是一个概念，用于表达数据模型状态的一部分。它指定了一个状态切片（slice），以及与该切片相关的 state、action、reducer 和 selector。使用 Slice 可以将大型的 Store 拆分为更小的、可维护的子类型。                                                            |
+
+## 结构分层
+
+在不同的复杂度下，我们可以将 Store 的结构组织可以由很大的不同：
+
+- **较低复杂度**：一般包含 2\~5 个 state 、3 \~ 4 个 action。此时的结构一般直接一个 `store.ts` + 一个 `initialState.ts` 即可。
+
+```bash
+DataFill/store
+├── index.ts
+└── initialState.ts
+```
+
+- **一般复杂度** ：一般复杂度存在 5 \~ 15 个 state、 5 \~ 10 个 action，可能会存在 selector 实现派生状态，也有可能存在 reducer 简化部分数据变更的复杂度。此时的结构一般为一个 `store.ts` + 一个 `initialState.ts` + 一个 `selectors.ts`/`reducer.ts`。
+
+```bash
+IconPicker/store
+├── index.ts
+├── initialState.ts
+├── selectors.ts
+└── store.ts
+```
+
+```bash
+SortableList/store
+├── index.ts
+├── initialState.ts
+├── listDataReducer.ts
+└── store.ts
+```
+
+- **中等复杂度** ： 中等复杂度存在 15 \~ 30 个 state、 10 \~ 20 个 action，大概率会存在 selector 来聚合派生状态，大概率存在 reducer 简化部分数据变更的复杂度。
+
+此时结构，用单一的 action store 已经较难维护，往往会拆解出来多个 slice 用于管理不同的 action。 下方的代码代表了 `SortableTree` 组件的内部数据流：
+
+```bash
+SortableTree/store
+├── index.ts
+├── initialState.ts
+├── selectors.ts
+├── slices
+├── crudSlice.ts
+├── dndSlice.ts
+└── selectionSlice.ts
+├── store.ts
+└── treeDataReducer.ts
+```
+
+- 高等复杂度：高等复杂度存在 30 个以上的 state、 20 个以上的 action。必然需要 slice 做模块化内聚。在每个 slice 中都各自声明了各自的 initState、 action、reducer 与 selector。
+
+下述这个数据流的目录结构是之前一版 SessionStore，具有很高的复杂度，实现了大量的业务逻辑。但借助于 slice 的模块化和分形架构的心智，我们可以很容易地找到对应的模块，新增功能与迭代都很易于维护。
+
+```bash
+LobeChat SessionStore
+├── index.ts
+├── initialState.ts
+├── selectors.ts
+├── slices
+│ ├── agentConfig
+│ │ ├── action.ts
+│ │ ├── index.ts
+│ │ ├── initialState.ts
+│ │ └── selectors.ts
+│ ├── chat
+│ │ ├── actions
+│ │ │ ├── index.ts
+│ │ │ ├── message.ts
+│ │ │ └── topic.ts
+│ │ ├── index.ts
+│ │ ├── initialState.ts
+│ │ ├── reducers
+│ │ │ ├── message.ts
+│ │ │ └── topic.ts
+│ │ ├── selectors
+│ │ │ ├── chat.ts
+│ │ │ ├── index.ts
+│ │ │ ├── token.ts
+│ │ │ ├── topic.ts
+│ │ │ └── utils.ts
+│ │ └── utils.ts
+│ └── session
+│ ├── action.ts
+│ ├── index.ts
+│ ├── initialState.ts
+│ ├── reducers
+│ │ └── session.ts
+│ └── selectors
+│ ├── export.ts
+│ ├── index.ts
+│ └── list.ts
+└── store.ts
+```
+
+### LobeChat SessionStore 目录结构最佳实践
+
+在 LobeChat 应用中，由于会话管理是一个复杂的功能模块，因此我们采用了 [slice 模式](https://github.com/pmndrs/zustand/blob/main/docs/guides/slices-pattern.md) 来组织数据流。下面是 LobeChat SessionStore 的目录结构，其中每个目录和文件都有其特定的用途：
+
+```fish
+src/store/session
+├── index.ts                           # SessionStore 的聚合导出文件
+├── initialState.ts                    # 聚合了所有 slice 的 initialState
+├── selectors.ts                       # 从各个 slices 导出的 selector
+├── store.ts                           # SessionStore 的创建和使用
+├── helpers.ts                         # 辅助函数
+└── slices                             # 各个独立的功能切片
+    ├── agent                          # 助理 Slice
+    │   ├── action.ts
+    │   ├── index.ts
+    │   └── selectors.ts
+    └── session                        # 会话 Slice
+        ├── action.ts
+        ├── helpers.ts
+        ├── initialState.ts
+        └── selectors
+            ├── export.ts
+            ├── list.ts
+            └── index.ts
+
+```
+
+## SessionStore 的实现
+
+在 LobeChat 中，SessionStore 被设计为管理会话状态和逻辑的核心模块。它由多个 Slices 组成，每个 Slice 管理一部分相关的状态和逻辑。下面是一个简化的 SessionStore 的实现示例：
+
+#### store.ts
+
+```ts
+import { PersistOptions, devtools, persist, subscribeWithSelector } from 'zustand/middleware';
+import { shallow } from 'zustand/shallow';
+import { devtools } from 'zustand/middleware';
+import { createWithEqualityFn } from 'zustand/traditional';
+
+import { SessionStoreState, initialState } from './initialState';
+import { AgentAction, createAgentSlice } from './slices/agent/action';
+import { SessionAction, createSessionSlice } from './slices/session/action';
+
+//  ===============  聚合 createStoreFn ============ //
+
+export type SessionStore = SessionAction & AgentAction & SessionStoreState;
+const createStore: StateCreator<SessionStore, [['zustand/devtools', never]]> = (...parameters) => ({
+  ...initialState,
+  ...createAgentSlice(...parameters),
+  ...createSessionSlice(...parameters),
+});
+
+
+
+//  ===============  实装 useStore ============ //
+
+export const useSessionStore = createWithEqualityFn<SessionStore>()(
+  persist(
+    subscribeWithSelector(
+      devtools(createStore, {
+        name: 'LobeChat_Session' + (isDev ? '_DEV' : ''),
+      }),
+    ),
+    persistOptions,
+  ),
+  shallow,
+);
+
+```
+
+在这个 `store.ts` 文件中，我们创建了一个 `useSessionStore` 钩子，它使用 `zustand` 库来创建一个全局状态管理器。我们将 initialState 和每个 Slice 的状态和动作合并，以创建完整的 SessionStore。
+
+#### slices/session/action.ts
+
+```ts
+import { StateCreator } from 'zustand';
+
+import { SessionStore } from '@/store/session';
+
+export interface SessionActions {
+  /**
+   * A custom hook that uses SWR to fetch sessions data.
+   */
+  useFetchSessions: () => SWRResponse<any>;
+}
+
+export const createSessionSlice: StateCreator<
+  SessionStore,
+  [['zustand/devtools', never]],
+  [],
+  SessionAction
+> = (set, get) => ({
+  useFetchSessions: () => {
+    // ...初始化会话的逻辑
+  },
+  // ...其他动作的实现
+});
+```
+
+在 `action.ts` 文件中，我们定义了一个 `SessionActions` 接口来描述会话相关的动作，并且实现了一个 `useFetchSessions` 函数来创建这些动作。然后，我们将这些动作与初始状态合并，以形成会话相关的 Slice。
+
+通过这种结构分层和模块化的方法，我们可以确保 LobeChat 的 SessionStore 是清晰、可维护的，同时也便于扩展和测试。

package/contributing/State-Management/State-Management-Selectors.md

@@ -0,0 +1,68 @@
+# Data Store Selector
+
+Selectors are data retrieval modules under the LobeChat data flow development framework. Their role is to extract data from the store using specific business logic for consumption by components.
+
+Taking `src/store/plugin/selectors.ts` as an example:
+
+This TypeScript code snippet defines an object named `pluginSelectors`, which contains a series of selector functions used to retrieve data from the plugin storage state. Selectors are functions that extract and derive data from a Redux store (or similar state management library). This specific example is for managing the state related to the frontend application's plugin system.
+
+Here are some key points to note:
+
+- `enabledSchema`: A function that returns an array of `ChatCompletionFunctions` filtered based on the enabled plugin list `enabledPlugins`. It appends the plugin identifier as a prefix to the API names to ensure uniqueness and uses the `uniqBy` function from the Lodash library to remove duplicates.
+- `onlinePluginStore`: Returns the current online plugin list.
+- `pluginList`: Returns the list of plugins, including custom plugins and standard plugins.
+- `getPluginMetaById`: Returns the plugin metadata based on the plugin ID.
+- `getDevPluginById`: Returns information about the custom plugins in development.
+- `getPluginManifestById`: Returns the plugin manifest based on the plugin ID.
+- `getPluginSettingsById`: Returns the plugin settings based on the plugin ID.
+- `getPluginManifestLoadingStatus`: Returns the loading status of the plugin manifest (loading, success, or error) based on the plugin ID.
+- `isCustomPlugin`: Checks if the plugin with the given ID is a custom plugin.
+- `displayPluginList`: Returns a processed plugin list, including author, avatar, creation time, description, homepage URL, identifier, and title.
+- `hasPluginUI`: Determines if the plugin has UI components based on the plugin ID.
+
+Selectors are highly modular and maintainable. By encapsulating complex state selection logic in separate functions, they make the code more concise and intuitive when accessing state data in other parts of the application. Additionally, by using TypeScript, each function can have clear input and output types, which helps improve code reliability and development efficiency.
+
+Taking the `displayPluginList` method as an example, its code is as follows:
+
+```ts
+const pluginList = (s: PluginStoreState) => [...s.pluginList, ...s.customPluginList];
+
+const displayPluginList = (s: PluginStoreState) =>
+  pluginList(s).map((p) => ({
+    author: p.author,
+    avatar: p.meta?.avatar,
+    createAt: p.createAt,
+    desc: pluginHelpers.getPluginDesc(p.meta),
+    homepage: p.homepage,
+    identifier: p.identifier,
+    title: pluginHelpers.getPluginTitle(p.meta),
+  }));
+```
+
+- `pluginList` method: Used to retrieve the list of all plugins from the plugin state storage `PluginStoreState`. It creates a new plugin list by combining two arrays: `pluginList` and `customPluginList`.
+- `displayPluginList` method: Calls the `pluginList` method to retrieve the merged plugin list and transforms the `title` and `desc` into text displayed on the UI.
+
+In components, the final consumed data can be directly obtained by importing:
+
+```tsx | pure
+import { usePluginStore } from '@/store/plugin';
+import { pluginSelectors } from '@/store/plugin/selectors';
+
+const Render = ({ plugins }) => {
+  const list = usePluginStore(pluginSelectors.displayPluginList);
+
+  return <> ... </>;
+};
+```
+
+The benefits of implementing this approach are:
+
+1. **Decoupling and reusability**: By separating selectors from components, we can reuse these selectors across multiple components without rewriting data retrieval logic. This reduces duplicate code, improves development efficiency, and makes the codebase cleaner and easier to maintain.
+2. **Performance optimization**: Selectors can be used to compute derived data, avoiding redundant calculations in each component. When the state changes, only the selectors dependent on that part of the state will recalculate, reducing unnecessary rendering and computation.
+3. **Ease of testing**: Selectors are pure functions, relying only on the passed parameters. This means they can be tested in an isolated environment without the need to simulate the entire store or component tree.
+4. **Type safety**: As LobeChat uses TypeScript, each selector has explicit input and output type definitions. This provides developers with the advantage of auto-completion and compile-time checks, reducing runtime errors.
+5. **Maintainability**: Selectors centralize the logic for reading state, making it more intuitive to track state changes and management. If the state structure changes, only the relevant selectors need to be updated, rather than searching and replacing in multiple places throughout the codebase.
+6. **Composability**: Selectors can be composed with other selectors to create more complex selection logic. This pattern allows developers to build a hierarchy of selectors, making state selection more flexible and powerful.
+7. **Simplified component logic**: Components do not need to know the structure of the state or how to retrieve and compute the required data. Components only need to call selectors to obtain the data needed for rendering, simplifying and clarifying component logic.
+
+With this design, LobeChat developers can focus more on building the user interface and business logic without worrying about the details of data retrieval and processing. This pattern also provides better adaptability and scalability for potential future changes in state structure.

package/contributing/State-Management/State-Management-Selectors.zh-CN.md

@@ -0,0 +1,49 @@
+# 数据存储取数模块
+
+selectors 是 LobeChat 数据流研发框架下的取数模块，它的作用是从 store 中以特定特务逻辑取出数据，供组件消费使用。
+
+以 `src/store/tool/slices/plugin/selectors.ts` 为例：
+
+这个 TypeScript 代码段定义了一个名为 `pluginSelectors` 的对象，该对象包含一系列用于从插件存储状态中检索数据的选择器函数。选择器是一种从 zustand 中提取和派生数据的函数。这个特定的例子是为了管理与前端应用程序的插件系统相关的状态。
+
+下面是一些关键点的说明：
+
+- `getCustomPluginById`: 根据插件 ID 返回自定义插件信息。
+- `getInstalledPluginById`: 根据插件 ID 返回已安装插件的信息。
+- `getPluginManifestById`: 根据插件 ID 返回插件清单。
+- `getPluginMetaById`: 根据插件 ID 返回插件元数据。
+- `getPluginSettingsById`: 根据插件 ID 返回插件设置。
+- `installedCustomPluginMetaList`: 返回所有已安装的自定义插件的元数据列表。
+- `installedPluginManifestList`: 返回所有已安装插件的清单列表。
+- `installedPluginMetaList`: 返回所有已安装插件的元数据列表。
+- `installedPlugins`: 返回所有已安装插件的列表。
+- `isPluginHasUI`: 根据插件 ID 确定插件是否有 UI 组件。
+- `isPluginInstalled`: 根据插件 ID 检查插件是否已安装。
+- `storeAndInstallPluginsIdList`: 返回 store 中和已安装插件的所有 ID 列表。
+
+选择器通过将复杂的状态选择逻辑封装在单独的函数中，使得在应用程序的其他部分调用状态数据时，代码更加简洁和直观。此外，由于使用了 TypeScript，每个函数都可以具有明确的输入和输出类型，这有助于提高代码的可靠性和开发效率。
+
+在组件中，只需引入相应的选择器即可直接获取最终消费的数据：
+
+```tsx | pure
+import { useToolStore } from '@/store/tool';
+import { pluginSelectors } from '@/store/tool/selectors';
+
+const Render = () => {
+  const list = useToolStore(pluginSelectors.installedPluginMetaList);
+
+  return <> ... </>;
+};
+```
+
+这样实现的好处在于：
+
+1. **解耦和重用**：通过将选择器独立于组件，我们可以在多个组件之间复用这些选择器而不需要重写取数逻辑。这减少了重复代码，提高了开发效率，并且使得代码库更加干净和易于维护。
+2. **性能优化**：选择器可以用来计算派生数据，这样可以避免在每个组件中重复计算相同的数据。当状态发生变化时，只有依赖于这部分状态的选择器才会重新计算，从而减少不必要的渲染和计算。
+3. **易于测试**：选择器是纯函数，它们仅依赖于传入的参数。这意味着它们可以在隔离的环境中进行测试，无需模拟整个 store 或组件树。
+4. **类型安全**：由于 LobeChat 使用 TypeScript，每个选择器都有明确的输入和输出类型定义。这为开发者提供了自动完成和编译时检查的优势，减少了运行时错误。
+5. **可维护性**：选择器集中了状态的读取逻辑，使得跟踪状态的变化和管理更加直观。如果状态结构发生变化，我们只需要更新相应的选择器，而不是搜索和替换整个代码库中的多个位置。
+6. **可组合性**：选择器可以组合其他选择器，以创建更复杂的选择逻辑。这种模式允许开发者构建一个选择器层次结构，使得状态选择更加灵活和强大。
+7. **简化组件逻辑**：组件不需要知道状态的结构或如何获取和计算需要的数据。组件只需调用选择器即可获取渲染所需的数据，这使得组件逻辑变得更简单和清晰。
+
+通过这样的设计，LobeChat 的开发者可以更专注于构建用户界面和业务逻辑，而不必担心数据的获取和处理细节。这种模式也为未来可能的状态结构变更提供了更好的适应性和扩展性。

package/contributing/Upstream-Sync.md

@@ -0,0 +1,58 @@
+# Upstream Sync
+
+English | [简体中文](https://github.com/lobehub/lobe-chat/wiki/Upstream-Sync.zh-CN)
+
+## `A` Vercel / Zeabur Deployment
+
+If you have deployed your own project following the one-click deployment steps in the README, you might encounter constant prompts indicating "updates available". This is because Vercel defaults to creating a new project instead of forking this one, resulting in an inability to accurately detect updates. We suggest you redeploy using the following steps:
+
+- Remove the original repository;
+- Use the <kbd>Fork</kbd> button at the top right corner of the page to fork this project;
+- Re-select and deploy on `Vercel`.
+
+## Enabling Automatic Updates
+
+> \[!NOTE]
+>
+> If you encounter an error executing Upstream Sync, manually Sync Fork once
+
+Once you have forked the project, due to Github restrictions, you will need to manually enable Workflows on the Actions page of your forked project and activate the Upstream Sync Action. Once enabled, you can set up hourly automatic updates.
+
+![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/266985117-4d48fe7b-0412-4667-8129-b25ebcf2c9de.png)
+![](https://github-production-user-asset-6210df.s3.amazonaws.com/17870709/266985177-7677b4ce-c348-4145-9f60-829d448d5be6.png)
+
+## `B` Docker Deployment
+
+Upgrading the Docker deployment version is very simple, just redeploy the latest image of LobeChat. Here are the instructions to perform these steps:
+
+1. Stop and delete the currently running LobeChat container (assuming the name of the LobeChat container is `lobe-chat`):
+
+```fish
+docker stop lobe-chat
+docker rm lobe-chat
+```
+
+2. Pull the latest Docker image of LobeChat:
+
+```fish
+docker pull lobehub/lobe-chat
+```
+
+3. Redeploy the LobeChat container using the newly pulled image:
+
+```fish
+docker run -d -p 3210:3210 \
+  -e OPENAI_API_KEY=sk-xxxx \
+  -e OPENAI_PROXY_URL=https://api-proxy.com/v1 \
+  -e ACCESS_CODE=lobe66 \
+  --name lobe-chat \
+  lobehub/lobe-chat
+```
+
+Make sure you have sufficient permissions to stop and delete the container before executing these commands, and Docker has sufficient permissions to pull the new image.
+
+> \[!NOTE]
+>
+> If I redeploy, will my local chat history be lost?
+>
+> Don't worry, all of LobeChat's chat history is stored in your local browser. Therefore, when you redeploy LobeChat using Docker, your chat history will not be lost.