@lobehub/chat 1.0.0 → 1.0.2

package/contributing/Basic/Chat-API.zh-CN.md

@@ -0,0 +1,174 @@
+# 会话 API 实现逻辑
+
+LobeChat 的大模型 AI 实现主要依赖于 OpenAI 的 API，包括后端的核心会话 API 和前端的集成 API。接下来，我们将分别介绍后端和前端的实现思路和代码。
+
+#### TOC
+
+- [后端实现](#后端实现)
+  - [核心会话 API](#核心会话-api)
+  - [会话结果处理](#会话结果处理)
+- [前端实现](#前端实现)
+  - [前端集成](#前端集成)
+  - [使用流式获取结果](#使用流式获取结果)
+
+## 后端实现
+
+以下代码中移除了鉴权、错误处理等逻辑，仅保留了核心的主要功能逻辑。
+
+### 核心会话 API
+
+在 `src/app/api/openai/chat/route.ts` 中，定义了一个处理 POST 请求的方法，主要负责从请求体中提取 `OpenAIChatStreamPayload` 类型的 payload，并使用 `createBizOpenAI` 函数根据请求和模型信息创建 OpenAI 实例。随后，该方法调用 `createChatCompletion` 来处理实际的会话，并返回响应结果。如果创建 OpenAI 实例过程中出现错误，则直接返回错误响应。
+
+```ts
+export const POST = async (req: Request) => {
+  const payload = (await req.json()) as OpenAIChatStreamPayload;
+
+  const openaiOrErrResponse = createBizOpenAI(req, payload.model);
+
+  // if resOrOpenAI is a Response, it means there is an error,just return it
+  if (openaiOrErrResponse instanceof Response) return openaiOrErrResponse;
+
+  return createChatCompletion({ openai: openaiOrErrResponse, payload });
+};
+```
+
+### 会话结果处理
+
+而在 `src/app/api/openai/chat/createChatCompletion.ts` 文件中，`createChatCompletion` 方法主要负责与 OpenAI API 进行交互，处理会话请求。它首先对 payload 中的消息进行预处理，然后通过 `openai.chat.completions.create` 方法发送 API 请求，并使用 `OpenAIStream` 将返回的响应转换为流式格式。如果在 API 调用过程中出现错误，方法将生成并处理相应的错误响应。
+
+```ts
+import { OpenAIStream, StreamingTextResponse } from 'ai';
+
+export const createChatCompletion = async ({ payload, openai }: CreateChatCompletionOptions) => {
+  // 预处理消息
+  const { messages, ...params } = payload;
+  // 发送 API 请求
+  try {
+    const response = await openai.chat.completions.create(
+      {
+        messages,
+        ...params,
+        stream: true,
+      } as unknown as OpenAI.ChatCompletionCreateParamsStreaming,
+      { headers: { Accept: '*/*' } },
+    );
+    const stream = OpenAIStream(response);
+    return new StreamingTextResponse(stream);
+  } catch (error) {
+    // 检查错误是否为 OpenAI APIError
+    if (error instanceof OpenAI.APIError) {
+      let errorResult: any;
+      // 如果错误是 OpenAI APIError，那么会有一个 error 对象
+      if (error.error) {
+        errorResult = error.error;
+      } else if (error.cause) {
+        errorResult = error.cause;
+      }
+      // 如果没有其他请求错误，错误对象是一个类似 Response 的对象
+      else {
+        errorResult = { headers: error.headers, stack: error.stack, status: error.status };
+      }
+      console.error(errorResult);
+      // 返回错误响应
+      return createErrorResponse(ChatErrorType.OpenAIBizError, {
+        endpoint: openai.baseURL,
+        error: errorResult,
+      });
+    }
+    console.error(error);
+    return createErrorResponse(ChatErrorType.InternalServerError, {
+      endpoint: openai.baseURL,
+      error: JSON.stringify(error),
+    });
+  }
+};
+```
+
+## 前端实现
+
+### 前端集成
+
+在 `src/services/chat.ts` 文件中，我们定义了 `ChatService` 类。这个类提供了一些方法来处理与 OpenAI 聊天 API 的交互。
+
+`createAssistantMessage` 方法用于创建一个新的助手消息。它接收一个包含插件、消息和其他参数的对象，以及一个可选的 `FetchOptions` 对象。这个方法会合并默认的代理配置和传入的参数，预处理消息和工具，然后调用 `getChatCompletion` 方法获取聊天完成任务。
+
+`getChatCompletion` 方法用于获取聊天完成任务。它接收一个 `OpenAIChatStreamPayload` 对象和一个可选的 `FetchOptions` 对象。这个方法会合并默认的代理配置和传入的参数，然后发送 POST 请求到 OpenAI 的聊天 API。
+
+`runPluginApi` 方法用于运行插件 API 并获取结果。它接收一个 `PluginRequestPayload` 对象和一个可选的 `FetchOptions` 对象。这个方法会从工具存储中获取状态，通过插件标识符获取插件设置和清单，然后发送 POST 请求到插件的网关 URL。
+
+`fetchPresetTaskResult` 方法用于获取预设任务的结果。它使用 `fetchAIFactory` 工厂函数创建一个新的函数，这个函数接收一个聊天完成任务的参数，并返回一个 Promise。当 Promise 解析时，返回的结果是聊天完成任务的结果。
+
+`processMessages` 方法用于处理聊天消息。它接收一个聊天消息数组，一个可选的模型名称，和一个可选的工具数组。这个方法会处理消息内容，将输入的 `messages` 数组映射为 `OpenAIChatMessage` 类型的数组，如果存在启用的工具，将工具的系统角色添加到系统消息中。
+
+```ts
+class ChatService {
+  // 创建一个新的助手消息
+  createAssistantMessage(params: object, fetchOptions?: FetchOptions) {
+    // 实现细节...
+  }
+
+  // 获取聊天完成任务
+  getChatCompletion(payload: OpenAIChatStreamPayload, fetchOptions?: FetchOptions) {
+    // 实现细节...
+  }
+
+  // 运行插件 API 并获取结果
+  runPluginApi(payload: PluginRequestPayload, fetchOptions?: FetchOptions) {
+    // 实现细节...
+  }
+
+  // 获取预设任务的结果
+  fetchPresetTaskResult() {
+    // 实现细节...
+  }
+
+  // 处理聊天消息
+  processMessages(messages: ChatMessage[], modelName?: string, tools?: Tool[]) {
+    // 实现细节...
+  }
+}
+```
+
+### 使用流式获取结果
+
+在 `src/utils/fetch.ts` 文件中，我们定义了 `fetchSSE` 方法，该方法使用流式方法获取数据，当读取到新的数据块时，会调用 `onMessageHandle` 回调函数处理数据块，进而实现打字机输出效果。
+
+```ts
+export const fetchSSE = async (fetchFn: () => Promise<Response>, options: FetchSSEOptions = {}) => {
+  const response = await fetchFn();
+
+  // 如果不 ok 说明有请求错误
+  if (!response.ok) {
+    const chatMessageError = await getMessageError(response);
+
+    options.onErrorHandle?.(chatMessageError);
+    return;
+  }
+
+  const returnRes = response.clone();
+
+  const data = response.body;
+
+  if (!data) return;
+  let output = '';
+  const reader = data.getReader();
+  const decoder = new TextDecoder();
+
+  let done = false;
+
+  while (!done) {
+    const { value, done: doneReading } = await reader.read();
+    done = doneReading;
+    const chunkValue = decoder.decode(value, { stream: true });
+
+    output += chunkValue;
+    options.onMessageHandle?.(chunkValue);
+  }
+
+  await options?.onFinish?.(output);
+
+  return returnRes;
+};
+```
+
+以上就是 LobeChat 会话 API 的核心实现。在理解了这些核心代码的基础上，便可以进一步扩展和优化 LobeChat 的 AI 功能。

package/contributing/Basic/Contributing-Guidelines.md

@@ -0,0 +1,83 @@
+# Code Style and Contribution Guidelines
+
+Welcome to the Code Style and Contribution Guidelines for LobeChat. This guide will help you understand our code standards and contribution process, ensuring code consistency and smooth project progression.
+
+## TOC
+
+- [Code Style](#code-style)
+  - [ESLint](#eslint)
+  - [Prettier](#prettier)
+  - [remarklint](#remarklint)
+  - [stylelint](#stylelint)
+- [Contribution Process](#contribution-process)
+  - [Gitmoji](#gitmoji)
+  - [Semantic Release](#semantic-release)
+  - [Commitlint](#commitlint)
+  - [How to Contribute](#how-to-contribute)
+
+## Code Style
+
+In LobeChat, we use the `@lobehub/lint` package to maintain a unified code style. This package incorporates configurations for `ESLint`, `Prettier`, `remarklint`, and `stylelint` to ensure that our JavaScript, Markdown, and CSS files adhere to the same coding standards.
+
+### ESLint
+
+We use ESLint to check for issues in our JavaScript code. You can find the `.eslintrc.js` file in the project's root directory, which contains our extensions and custom rules for the ESLint configuration of `@lobehub/lint`.
+
+To ensure your code aligns with the project's standards, run ESLint before committing your code.
+
+### Prettier
+
+Prettier is responsible for code formatting to maintain consistency. Our Prettier configuration can be found in `.prettierrc.js`, imported from `@lobehub/lint`.
+
+It's recommended to configure your editor to run Prettier automatically upon saving files or manually run it before committing.
+
+### remarklint
+
+For Markdown files, we use remarklint to ensure consistent document formatting. You can find the corresponding configuration file in the project.
+
+### stylelint
+
+We utilize stylelint to standardize the style of our CSS code. In the configuration file for stylelint, we have made some custom rule adjustments based on `@lobehub/lint` configuration.
+
+Ensure that your style code passes stylelint checks before committing.
+
+## Contribution Process
+
+LobeChat follows the gitmoji and semantic release as our code submission and release process.
+
+### Gitmoji
+
+When committing code, please use gitmoji to label your commit messages. This helps other contributors quickly understand the content and purpose of your submission.
+
+Gitmoji commit messages use specific emojis to represent the type or intent of the commit. Here's an example:
+
+```
+📝 Update README with contribution guidelines
+
+- Added section about code style preferences
+- Included instructions for running tests
+- Corrected typos and improved formatting
+```
+
+In this example, the 📝 emoji represents a documentation update. The commit message clearly describes the changes and provides specific details.
+
+### Semantic Release
+
+We use semantic release to automate version control and release processes. Ensure that your commit messages adhere to the semantic release specifications so that when the code is merged into the main branch, the system can automatically create a new version and release it.
+
+### Commitlint
+
+To ensure consistency in commit messages, we use `commitlint` to check the format of commit messages. You can find the relevant rules in the `.commitlintrc.js` configuration file.
+
+Before committing your code, ensure that your commit messages adhere to our standards.
+
+### How to Contribute
+
+1. Fork the project to your account.
+2. Create a new branch for development.
+3. After completing the development, ensure that your code passes the aforementioned code style checks.
+4. Commit your changes and use appropriate gitmoji to label your commit message.
+5. Create a Pull Request to the main branch of the original project.
+6. Await code review and make necessary modifications based on feedback.
+
+Thank you for following these guidelines, as they help us maintain the quality and consistency of the project. We look forward to your contributions!

package/contributing/Basic/Contributing-Guidelines.zh-CN.md

@@ -0,0 +1,85 @@
+# 代码风格与贡献指南
+
+欢迎来到 LobeChat 的代码风格与贡献指南。本指南将帮助您理解我们的代码规范和贡献流程，确保代码的一致性和项目的顺利进行。
+
+## TOC
+
+- [代码风格](#代码风格)
+  - [ESLint](#eslint)
+  - [Prettier](#prettier)
+  - [remarklint](#remarklint)
+  - [stylelint](#stylelint)
+- [贡献流程](#贡献流程)
+  - [Gitmoji](#gitmoji)
+  - [Semantic Release](#semantic-release)
+  - [Commitlint](#commitlint)
+  - [如何贡献](#如何贡献)
+
+## 代码风格
+
+在 LobeChat 中，我们使用 `@lobehub/lint` 程序包来统一代码风格。该程序包内置了 `ESLint`、`Prettier`、`remarklint` 和 `stylelint` 的配置，以确保我们的 JavaScript、Markdown 和 CSS 文件遵循相同的编码标准。
+
+### ESLint
+
+我们的项目使用 ESLint 来检查 JavaScript 代码中的问题。您可以在项目根目录下找到 `.eslintrc.js` 文件，其中包含了我们对 `@lobehub/lint` 的 ESLint 配置的扩展和自定义规则。
+
+为了与 Next.js 框架兼容，我们在配置中添加了 `plugin:@next/next/recommended`。此外，我们禁用了一些规则，以适应我们项目的特定需求。
+
+请在提交代码前运行 ESLint，以确保您的代码符合项目规范。
+
+### Prettier
+
+Prettier 负责代码格式化，以保证代码的一致性。您可以在 `.prettierrc.js` 中找到我们的 Prettier 配置，它是从 `@lobehub/lint` 导入的。
+
+在保存文件时，建议您配置您的编辑器以自动运行 Prettier，或者在提交前手动运行它。
+
+### remarklint
+
+对于 Markdown 文件，我们使用 remarklint 来确保文档格式的统一。您可以在项目中找到相应的配置文件。
+
+### stylelint
+
+我们使用 stylelint 来规范 CSS 代码的风格。在 `stylelint` 的配置文件中，我们基于 `@lobehub/lint` 的配置进行了一些自定义规则的调整。
+
+确保您的样式代码在提交前通过了 stylelint 的检查。
+
+## 贡献流程
+
+LobeChat 采用 gitmoji 和 semantic release 作为我们的代码提交和发布流程。
+
+### Gitmoji
+
+在提交代码时，请使用 gitmoji 来标注您的提交信息。这有助于其他贡献者快速理解您提交的内容和目的。
+
+Gitmoji commit messages 使用特定的 emoji 来表示提交的类型或意图。以下是一个示例：
+
+```
+📝 Update README with contribution guidelines
+
+- Added section about code style preferences
+- Included instructions for running tests
+- Corrected typos and improved formatting
+```
+
+在这个示例中，📝 emoji 代表了文档的更新。提交信息清晰地描述了更改的内容，提供了具体的细节。
+
+### Semantic Release
+
+我们使用 semantic release 来自动化版本控制和发布流程。请确保您的提交信息遵循 semantic release 的规范，这样当代码合并到主分支后，系统就可以自动创建新的版本并发布。
+
+### Commitlint
+
+为了确保提交信息的一致性，我们使用 `commitlint` 来检查提交信息格式。您可以在 `.commitlintrc.js` 配置文件中找到相关规则。
+
+在您提交代码之前，请确保您的提交信息遵循我们的规范。
+
+### 如何贡献
+
+1. Fork 项目到您的账户。
+2. 创建一个新的分支进行开发。
+3. 开发完成后，确保您的代码通过了上述的代码风格检查。
+4. 提交您的更改，并使用合适的 gitmoji 标注您的提交信息。
+5. 创建一个 Pull Request 到原项目的主分支。
+6. 等待代码审查，并根据反馈进行必要的修改。
+
+感谢您遵循这些指导原则，它们有助于我们维护项目的质量和一致性。我们期待您的贡献！

package/contributing/Basic/Feature-Development-Frontend.md

@@ -0,0 +1,126 @@
+# How to Develop a New Feature
+
+LobeChat is built on the Next.js framework and uses TypeScript as the primary development language. When developing a new feature, we need to follow a certain development process to ensure the quality and stability of the code. The general process can be divided into the following five steps:
+
+1. Routing: Define routes (`src/app`).
+2. Data Structure: Define data structures (`src/types`).
+3. Business Logic Implementation: Zustand store (`src/store`).
+4. Page Display: Write static components/pages (`src/app/<new-page>/features/<new-feature>.tsx`).
+5. Function Binding: Bind the store with page triggers (`const [state, function] = useNewStore(s => [s.state, s.function])`).
+
+Taking the "Chat Messages" feature as an example, here are the brief steps to implement this feature:
+
+#### TOC
+
+- [1. Define Routes](#1-define-routes)
+- [2. Define Data Structure](#2-define-data-structure)
+- [3. Create Zustand Store](#3-create-zustand-store)
+- [4. Create Page and Components](#4-create-page-and-components)
+- [5. Function Binding](#5-function-binding)
+
+## 1. Define Routes
+
+In the `src/app` directory, we need to define a new route to host the "Chat Messages" page. Generally, we would create a new folder under `src/app`, for example, `chat`, and create a `page.tsx` file within this folder to export a React component as the main body of the page.
+
+```tsx
+// src/app/chat/page.tsx
+import ChatPage from './features/chat';
+
+export default ChatPage;
+```
+
+## 2. Define Data Structure
+
+In the `src/types` directory, we need to define the data structure for "Chat Messages". For example, we create a `chat.ts` file and define the `ChatMessage` type within it:
+
+```ts
+// src/types/chat.ts
+
+export type ChatMessage = {
+  id: string;
+  content: string;
+  timestamp: number;
+  sender: 'user' | 'bot';
+};
+```
+
+## 3. Create Zustand Store
+
+In the `src/store` directory, we need to create a new Zustand Store to manage the state of "Chat Messages". For example, we create a `chatStore.ts` file and define a Zustand Store within it:
+
+```ts
+// src/store/chatStore.ts
+import create from 'zustand';
+
+type ChatState = {
+  messages: ChatMessage[];
+  addMessage: (message: ChatMessage) => void;
+};
+
+export const useChatStore = create<ChatState>((set) => ({
+  messages: [],
+  addMessage: (message) => set((state) => ({ messages: [...state.messages, message] })),
+}));
+```
+
+## 4. Create Page and Components
+
+In `src/app/<new-page>/features/<new-feature>.tsx`, we need to create a new page or component to display "Chat Messages". In this file, we can use the Zustand Store created earlier and Ant Design components to build the UI:
+
+```jsx
+// src/features/chat/index.tsx
+import { List, Typography } from 'antd';
+import { useChatStore } from 'src/store/chatStore';
+
+const ChatPage = () => {
+  const messages = useChatStore((state) => state.messages);
+
+  return (
+    <List
+      dataSource={messages}
+      renderItem={(message) => (
+        <List.Item>
+          <Typography.Text>{message.content}</Typography.Text>
+        </List.Item>
+      )}
+    />
+  );
+};
+
+export default ChatPage;
+```
+
+## 5. Function Binding
+
+In a page or component, we need to bind the Zustand Store's state and methods to the UI. In the example above, we have already bound the `messages` state to the `dataSource` property of the list. Now, we also need a method to add new messages. We can define this method in the Zustand Store and then use it in the page or component:
+
+```jsx
+import { Button } from 'antd';
+
+const ChatPage = () => {
+  const messages = useChatStore((state) => state.messages);
+  const addMessage = useChatStore((state) => state.addMessage);
+
+  const handleSend = () => {
+    addMessage({ id: '1', content: 'Hello, world!', timestamp: Date.now(), sender: 'user' });
+  };
+
+  return (
+    <>
+      <List
+        dataSource={messages}
+        renderItem={(message) => (
+          <List.Item>
+            <Typography.Text>{message.content}</Typography.Text>
+          </List.Item>
+        )}
+      />
+      <Button onClick={handleSend}>Send</Button>
+    </>
+  );
+};
+
+export default ChatPage;
+```
+
+The above is the step to implement the "chat message" feature in LobeChat. Of course, in the actual development of LobeChat, the business requirements and scenarios faced in real situations are far more complex than the above demo. Please develop according to the actual situation.

package/contributing/Basic/Feature-Development-Frontend.zh-CN.md

@@ -0,0 +1,126 @@
+# 如何开发一个新功能：前端实现
+
+LobeChat 基于 Next.js 框架构建，使用 TypeScript 作为主要开发语言。在开发新功能时，我们需要遵循一定的开发流程，以确保代码的质量和稳定性。大致的流程分为以下五步：
+
+1. 路由：定义路由 (`src/app`)
+2. 数据结构： 定义数据结构 ( `src/types` )
+3. 业务功能实现： zustand store (`src/store`)
+4. 页面展示：书写静态组件 / 页面 (`src/app/<new-page>/features/<new-feature>.tsx`)
+5. 功能绑定：绑定 store 与页面的触发 (`const  [state,function]= useNewStore(s=>[s.state,s.function])`)
+
+我们以 "会话消息" 功能为例，以下是实现这个功能的简要步骤：
+
+#### TOC
+
+- [1. 定义路由](#1-定义路由)
+- [2. 定义数据结构](#2-定义数据结构)
+- [3. 创建 Zustand Store](#3-创建-zustand-store)
+- [4. 创建页面与组件](#4-创建页面与组件)
+- [5. 功能绑定](#5-功能绑定)
+
+## 1. 定义路由
+
+在 `src/app` 目录下，我们需要定义一个新的路由来承载 "会话消息" 页面。一般来说，我们会在 `src/app` 下创建一个新的文件夹，例如 `chat`，并且在这个文件夹中创建 `page.tsx`文件，在该文件中导出 React 组件作为页面的主体。
+
+```tsx
+// src/app/chat/page.tsx
+import ChatPage from './features/chat';
+
+export default ChatPage;
+```
+
+## 2. 定义数据结构
+
+在 `src/types` 目录下，我们需要定义 "会话消息" 的数据结构。例如，我们创建一个 `chat.ts` 文件，并在其中定义 `ChatMessage` 类型：
+
+```ts
+// src/types/chat.ts
+
+export type ChatMessage = {
+  id: string;
+  content: string;
+  timestamp: number;
+  sender: 'user' | 'bot';
+};
+```
+
+## 3. 创建 Zustand Store
+
+在 `src/store` 目录下，我们需要创建一个新的 Zustand Store 来管理 "会话消息" 的状态。例如，我们创建一个 `chatStore.ts` 文件，并在其中定义一个 Zustand Store：
+
+```ts
+// src/store/chatStore.ts
+import create from 'zustand';
+
+type ChatState = {
+  messages: ChatMessage[];
+  addMessage: (message: ChatMessage) => void;
+};
+
+export const useChatStore = create<ChatState>((set) => ({
+  messages: [],
+  addMessage: (message) => set((state) => ({ messages: [...state.messages, message] })),
+}));
+```
+
+## 4. 创建页面与组件
+
+在 `src/app/<new-page>/features/<new-feature>.tsx` 中，我们需要创建一个新的页面或组件来显示 "会话消息"。在这个文件中，我们可以使用上面创建的 Zustand Store，以及 Ant Design 的组件来构建 UI：
+
+```jsx
+// src/features/chat/index.tsx
+import { List, Typography } from 'antd';
+import { useChatStore } from 'src/store/chatStore';
+
+const ChatPage = () => {
+  const messages = useChatStore((state) => state.messages);
+
+  return (
+    <List
+      dataSource={messages}
+      renderItem={(message) => (
+        <List.Item>
+          <Typography.Text>{message.content}</Typography.Text>
+        </List.Item>
+      )}
+    />
+  );
+};
+
+export default ChatPage;
+```
+
+## 5. 功能绑定
+
+在页面或组件中，我们需要将 Zustand Store 的状态和方法绑定到 UI 上。在上面的示例中，我们已经将 `messages` 状态绑定到了列表的 `dataSource` 属性上。现在，我们还需要一个方法来添加新的消息。我们可以在 Zustand Store 中定义这个方法，然后在页面或组件中使用它：
+
+```jsx
+import { Button } from 'antd';
+
+const ChatPage = () => {
+  const messages = useChatStore((state) => state.messages);
+  const addMessage = useChatStore((state) => state.addMessage);
+
+  const handleSend = () => {
+    addMessage({ id: '1', content: 'Hello, world!', timestamp: Date.now(), sender: 'user' });
+  };
+
+  return (
+    <>
+      <List
+        dataSource={messages}
+        renderItem={(message) => (
+          <List.Item>
+            <Typography.Text>{message.content}</Typography.Text>
+          </List.Item>
+        )}
+      />
+      <Button onClick={handleSend}>Send</Button>
+    </>
+  );
+};
+
+export default ChatPage;
+```
+
+以上就是在 LobeChat 中实现 "会话消息" 功能的步骤。当然，在 LobeChat 的实际开发中，真实场景所面临的业务诉求和场景远比上述 demo 复杂，请根据实际情况进行开发。