📝 docs: add plugin docs for the new third stage

.dumirc.ts

@@ -12,7 +12,7 @@ const themeConfig = {
       text: 'Github',
     },
     {
-      link: '/guides/intro',
+      link: '/quick-start/intro',
       text: 'Get Started',
       type: 'primary',
     },

docs/api/request.md → docs/api/get-plugin-settings-from-request.md

@@ -1,8 +1,8 @@
 ---
 title: getPluginSettingsFromRequest
-description: 从请求中获取插件设置
+description: get plugin settings from request
 group:
-  title: 服务端
+  title: Server
   order: 1
 nav: API
 ---

docs/api/request.zh-CN.md → docs/api/get-plugin-settings-from-request.zh-CN.md

@@ -4,7 +4,8 @@ description: 从请求中获取插件设置
 group:
   title: 服务端
   order: 1
-nav: API
+apiHeader:
+  pkg: '@lobehub/chat-plugin-sdk'
 ---
 
 用于从请求中获取插件设置字符串。

docs/api/lobe-chat-client.zh-CN.md

@@ -6,7 +6,6 @@ group:
   order: 10
 apiHeader:
   pkg: '@lobehub/chat-plugin-sdk/client'
-nav: API
 ---
 
 该实例包含插件侧与 LobeChat 交互的所有关键方法。

docs/api/channel.md → docs/api/plugin-channel.md

@@ -1,5 +1,5 @@
 ---
-title: Message Communication Types
+title: PluginChannel
 order: 10
 group:
   title: Miscellaneous
@@ -8,7 +8,7 @@ atomId: PluginChannel
 description: Provides detailed explanations of message types for plugin communication
 nav:
   title: API
-  order: 1
+  order: 100
 ---
 
 # PluginChannel Communication Messages

docs/api/channel.zh-CN.md → docs/api/plugin-channel.zh-CN.md

@@ -1,5 +1,5 @@
 ---
-title: 消息通信类型
+title: PluginChannel 消息通信类型
 order: 10
 group:
   title: 杂项
@@ -8,7 +8,9 @@ atomId: PluginChannel
 description: 提供了关于插件通信的消息类型的详细说明
 nav:
   title: API
-  order: 1
+  order: 100
+apiHeader:
+  pkg: '@lobehub/chat-plugin-sdk'
 ---
 
 # PluginChannel 通信消息

docs/api/error.md → docs/api/plugin-error-type.md

@@ -1,5 +1,5 @@
 ---
-title: Server Error Type
+title: Plugin Error Type
 atomId: PluginErrorType
 description: Plugin error types
 group: Server

docs/api/error.zh-CN.md → docs/api/plugin-error-type.zh-CN.md

@@ -1,10 +1,12 @@
 ---
-title: 服务端错误类型
+title: PluginErrorType 服务端错误类型
 atomId: PluginErrorType
-description: 插件错误类型
+description: 服务端错误类型
 group: 服务端
 nav: API
 order: 100
+apiHeader:
+  pkg: '@lobehub/chat-plugin-sdk'
 ---
 
 LobeChat 在插件服务请求中所有的错误类型，包括业务语义错误、客户端错误和服务端错误。

docs/api/plugin-manifest.zh-CN.md

@@ -3,7 +3,8 @@ title: 插件描述清单 Schema
 group: Schema
 atomId: pluginManifestSchema
 description: 插件描述文件的 Schema
-nav: API
+apiHeader:
+  pkg: '@lobehub/chat-plugin-sdk'
 ---
 
 ## pluginManifestSchema

docs/api/plugin-meta-index.md → docs/api/plugin-meta-store.md

@@ -1,9 +1,8 @@
 ---
-title: 插件市场元数据 Schema
+title: pluginMetaSchema
 group: Schema
 atomId: pluginMetaSchema
-description: 上架到插件市场中的插件元数据的数据模式定义。
-nav: API
+description: Schema for plugin meta data
 ---
 
 Schema for plugin metadata.

docs/api/plugin-meta-index.zh-CN.md → docs/api/plugin-meta-store.zh-CN.md

@@ -3,7 +3,8 @@ title: 插件市场元数据 Schema
 group: Schema
 atomId: pluginMetaSchema
 description: 上架到插件市场中的插件元数据的数据模式定义。
-nav: API
+apiHeader:
+  pkg: '@lobehub/chat-plugin-sdk'
 ---
 
 插件元数据的 Schema。

docs/changelog.md

@@ -1,8 +1,8 @@
 ---
-title: 更新日志
+title: Changelog
 description: New updates and improvements to @lobehub/chat-plugin-sdk
 nav:
-  title: 更新日志
+  title: Changelog
   order: 999
 ---
 

docs/changelog.zh-CN.md

@@ -0,0 +1,9 @@
+---
+title: 更新日志
+description: New updates and improvements to @lobehub/chat-plugin-sdk
+nav:
+  title: 更新日志
+  order: 999
+---
+
+<embed src="../CHANGELOG.md"></embed>

docs/guides/client-sdk.md

@@ -0,0 +1,45 @@
+---
+title: Client SDK
+group: Plugin Frontend
+order: 2
+---
+
+# LobeChat Client SDK
+
+The LobeChat Client SDK is a frontend development toolkit provided to plugin developers, allowing plugins to communicate efficiently and securely with the LobeChat application. Through this SDK, developers can easily access data passed to the plugin by LobeChat, send messages, update plugin status, and manage plugin configuration information.
+
+The core functionality of the SDK is to encapsulate all the underlying communication logic required to interact with LobeChat, including using the browser's `postMessage` and `addEventListener` methods for cross-window communication. This means that developers do not need to delve into complex communication protocols and can focus on implementing plugin functionality.
+
+## Usage Example
+
+### Obtaining Plugin Initialization Information
+
+When the plugin is loaded, developers may need to obtain the initialization parameters and configuration passed by LobeChat. Using the LobeChat Client SDK, this can be easily accomplished with the following lines of code:
+
+```javascript
+import { lobeChat } from '@lobehub/chat-plugin-sdk/client';
+
+// Obtain initialization information
+lobeChat.getPluginPayload().then((payload) => {
+  console.log('Plugin Name:', payload.name);
+  console.log('Plugin Arguments:', payload.arguments);
+  console.log('Plugin Settings:', payload.settings);
+});
+```
+
+### Updating Plugin Message Content
+
+If the plugin needs to send messages during interaction with the user, it can use the methods provided by the SDK to update the message content:
+
+```javascript
+import { lobeChat } from '@lobehub/chat-plugin-sdk/client';
+
+// Send message content
+lobeChat.setPluginMessage('Welcome to using our plugin!');
+```
+
+The LobeChat Client SDK is a powerful assistant for plugin developers, providing a complete, concise, and powerful set of tools to implement various interactive features of LobeChat plugins. With these tools, developers can focus more on innovation and enhancing user experience without worrying about the implementation details of communication mechanisms.
+
+## API
+
+For the complete usage API of the LobeChat Client SDK, please refer to: [LobeChat Client SDK API Documentation](/en-US/api/lobe-chat-client).

docs/guides/client-sdk.zh-CN.md

@@ -0,0 +1,45 @@
+---
+title: 客户端 SDK
+group: 插件前端
+order: 2
+---
+
+# LobeChat 客户端 SDK
+
+LobeChat Client SDK 是一套提供给插件开发者的前端开发工具包，它允许插件与 LobeChat 应用进行高效、安全的通信。通过这个 SDK，开发者可以轻松地获取 LobeChat 传递给插件的数据、发送消息、更新插件状态以及管理插件的配置信息等。
+
+SDK 的核心功能是封装了与 LobeChat 交互所需的所有底层通信逻辑，这包括使用浏览器的 `postMessage` 和 `addEventListener` 方法进行跨窗口通信。这意味着开发者不需要深入了解复杂的通信协议，就可以专注于插件功能的实现。
+
+## 使用示例
+
+### 获取插件初始化信息
+
+当插件加载完成时，开发者可能需要获取 LobeChat 传递的初始化参数和配置。使用 LobeChat Client SDK，这可以通过以下几行代码轻松完成：
+
+```javascript
+import { lobeChat } from '@lobehub/chat-plugin-sdk/client';
+
+// 获取初始化信息
+lobeChat.getPluginPayload().then((payload) => {
+  console.log('插件名称:', payload.name);
+  console.log('插件参数:', payload.arguments);
+  console.log('插件设置:', payload.settings);
+});
+```
+
+### 更新插件消息内容
+
+如果插件需要在与用户的交互中发送消息，可以使用 SDK 提供的方法来更新消息内容：
+
+```javascript
+import { lobeChat } from '@lobehub/chat-plugin-sdk/client';
+
+// 发送消息内容
+lobeChat.setPluginMessage('欢迎使用我们的插件！');
+```
+
+LobeChat Client SDK 是插件开发者的得力助手，提供了一套完整、简洁且强大的工具，用以实现 LobeChat 插件的各种交互功能。通过这些工具，开发者可以更专注于创新和提升用户体验，而无需担心通信机制的实现细节。
+
+## API
+
+关于 LobeChat Client SDK 的完整使用 API，可以查阅：[LobeChat Client SDK API 文档](/zh-CN/api/lobe-chat-client)。

docs/guides/communication-mechanisms.md

@@ -0,0 +1,53 @@
+---
+title: Plugin Communication
+group: Concepts
+order: 4
+---
+
+# Overview of Plugin Communication Mechanism
+
+## Server Communication
+
+For plugins of type `default` and `markdown`, you need to provide a backend service (standalone plugins can be pure frontend applications) to exchange data and process requests with the LobeChat core.
+
+The following will introduce the implementation principles and key details of server communication between the LobeChat core and plugins.
+
+### Plugin Server Communication Process
+
+The server communication between the LobeChat core and plugins is coordinated through a middleware layer, namely the [Plugin Gateway](https://github.com/lobehub/chat-plugins-gateway), to ensure the security and flexibility of communication. It also provides a standardized protocol to manage requests and responses.
+
+1. **Request Initialization**: The LobeChat core sends a request to the Gateway via HTTP POST, carrying a `PluginRequestPayload` containing the plugin identifier, API name, parameters, and other information.
+2. **Gateway Processing**: Upon receiving the request, the Gateway parses the `PluginRequestPayload` in the request body and performs parameter validation.
+3. **Request Handling and Response**: After successful validation, the Gateway calls the plugin's server based on the API name and parameters in the request, obtains the response, encapsulates the processing result as response data, and sends it back to the LobeChat core via HTTP response.
+4. **Error Handling**: If an error occurs during request processing, the Gateway generates an error response, including the error type and message, and returns it to the LobeChat core.
+
+### Gateway Communication Implementation Details
+
+The following are key implementation details of the LobeChat plugin server:
+
+- **Request Payload Processing**: The Gateway determines the plugin's identity by parsing the `identifier` in the `PluginRequestPayload` and executes the corresponding API logic based on the `apiName`.
+- **Plugin Manifest Retrieval**: If the request payload does not include the plugin manifest, the Gateway retrieves it from the [Plugin Store Index](https://github.com/lobehub/lobe-chat-plugins) to ensure correct identification and functionality of the plugin.
+- **Parameter Validation**: The Gateway validates the parameters in the request based on the API parameter pattern defined in the plugin manifest to ensure their validity and security.
+- **Setting Handling**: The Gateway adds the plugin's requested settings to the request header, allowing the plugin to retrieve the settings, such as API keys or other authentication information, using the `getPluginSettingsFromRequest` method.
+- **OpenAPI Support**: If the plugin manifest specifies an [OpenAPI manifest](/zh-CN/guides/openapi), the Gateway will utilize `SwaggerClient` to interact with third-party services defined in the OpenAPI specification.
+
+### Error Handling
+
+Error handling in server communication is crucial. The Gateway defines various error types, such as `PluginErrorType.MethodNotAllowed` indicating an unsupported request method, and `PluginErrorType.PluginGatewayError` indicating a gateway error, ensuring clear error feedback to the LobeChat core in case of issues. For detailed error types, please refer to: [Server Error Types](/zh-CN/api/error)
+
+## Frontend Communication
+
+The frontend communication between the LobeChat core and plugins is based on the HTML5 `window.postMessage` API, which allows secure communication between pages from different origins. In this mechanism, the LobeChat core can securely exchange information with embedded plugins (usually through `<iframe>` embedding).
+
+### Frontend Communication Process
+
+The following is an overview of the communication process:
+
+1. **Initialization of Communication**: When the plugin is loaded and ready to interact with the LobeChat core, it can use the `lobeChat.getPluginPayload()` method to obtain initialization data. Behind the scenes, the plugin listens for the `message` event, waiting for the initialization message from the LobeChat core, and upon receiving it, returns the parsed plugin parameters, name, settings, and status.
+2. **Receiving Plugin Payload**: The plugin receives initialization data from the LobeChat core by calling the `lobeChat.getPluginPayload()` method. This method internally listens for the `message` event, waiting for and processing the message containing the required plugin data sent by the LobeChat core.
+3. **Retrieving and Updating Basic Information**: The plugin can call methods such as `lobeChat.setPluginSettings(settings)`, `lobeChat.setPluginMessage(content)`, `lobeChat.setPluginState(key, value)` to update settings, message content, and plugin state.
+4. **Custom Trigger Actions**: For standalone plugins, custom control of AI message triggering and assistant message creation can be achieved using methods like `lobeChat.triggerAIMessage(id)` and \`lobeChat.createAssistantMessage(content), providing a richer product experience.
+
+In summary, communication between LobeChat and plugins is achieved through asynchronous message exchange using the `postMessage` API. The plugin can request data, receive data, update state, trigger messages, etc., while the LobeChat core is responsible for responding to these requests and providing the required data. This mechanism allows plugins to operate independently and effectively communicate with the LobeChat core.
+
+Additionally, we provide the `lobeChat` method in the SDK to simplify plugin frontend communication. Through the series of methods provided by `lobeChat`, communication details are abstracted, enabling plugins to interact with the LobeChat core using a concise API.

docs/guides/communication-mechanisms.zh-CN.md

@@ -0,0 +1,53 @@
+---
+title: 插件通信
+group: 基本概念
+order: 4
+---
+
+# 插件通信机制概述
+
+## 服务端通信
+
+针对 `default` 和 `markdown`类型的插件，你需要提供一个后端服务（standalone 类型的插件可以为纯前端应用），进而与 LobeChat 主体进行数据交换和处理请求。
+
+下面会介绍 LobeChat 主体和插件的服务端通信的实现原理与关键细节。
+
+### 插件服务端通信流程
+
+LobeChat 主体与插件的服务端通信通过一个中间件层，即 [Plugin Gateway](https://github.com/lobehub/chat-plugins-gateway)，来协调 LobeChat 主体与插件后端服务之间的通信。这一机制确保了通信的安全性和灵活性，同时提供了一套标准化的协议来管理请求和响应。
+
+1. **请求初始化**：LobeChat 主体通过 HTTP POST 请求向 Gateway 发送请求，携带着包含插件标识符、API 名称、参数等信息的 `PluginRequestPayload`。
+2. **Gateway 处理**：Gateway 接收到请求后，解析请求体中的 `PluginRequestPayload`，并进行参数校验。
+3. **处理与响应请求**：验证通过后，Gateway 根据请求中的 API 名称和参数去调用插件的服务端，获得响应结果后将处理结果封装为响应数据，通过 HTTP 响应发送回 LobeChat 主体。
+4. **错误处理**：如果在处理请求的过程中发生错误，Gateway 会生成错误响应，包括错误类型和错误信息，返回给 LobeChat 主体。
+
+### Gateway 通信实现细节
+
+以下是 LobeChat 插件服务端的关键实现细节：
+
+- **请求负载处理**：Gateway 通过解析 `PluginRequestPayload` 中的 `identifier` 来确定插件身份，并根据 `apiName` 执行相应的 API 逻辑。
+- **插件清单获取**：如果请求负载中不包含插件清单 (`manifest`)，Gateway 将从 [插件商店索引](https://github.com/lobehub/lobe-chat-plugins) 中获取，保证插件的正确识别和功能实现。
+- **参数校验**：Gateway 会根据插件清单中定义的 API 参数模式对请求中的参数进行校验，确保参数的有效性和安全性。
+- **设置处理**：Gateway 会通过将插件请求的设置信息，添加到请求头中，在插件侧可以通过 [getPluginSettingsFromRequest](/zh-CN/api/request) 方法获取插件设置，例如 API 密钥或其他认证信息进行校验。
+- **OpenAPI 支持**：如果插件清单指定了 [OpenAPI 清单](/zh-CN/guides/openapi)，Gateway 将会利用 `SwaggerClient` 与定义在 OpenAPI 规范中的第三方服务进行交互。
+
+### 错误处理
+
+服务端通信中的错误处理是一个重要的方面。Gateway 中定义了多种错误类型，例如 `PluginErrorType.MethodNotAllowed` 表示不支持的请求方法，`PluginErrorType.PluginGatewayError` 表示网关错误等。每种错误类型都有对应的处理逻辑，确保在出现问题时，可以向 LobeChat 主体提供清晰的错误反馈。关于错误的详细类型，请查阅：[服务端错误类型](/zh-CN/api/error)
+
+## 前端通信
+
+LobeChat 主体和插件的前端通信实现是基于 HTML5 的`window.postMessage` API，该 API 允许不同来源的页面之间安全地进行通信。在这种机制下，LobeChat 的主体可以与嵌入其中的插件（通常是通过`<iframe>`嵌入）安全地传递信息。
+
+### 前端通信流程
+
+以下是通信流程的概述：
+
+1. **初始化通信**：当插件加载完成并准备好与 LobeChat 主体进行交互时，可以通过 `lobeChat.getPluginPayload()` 方法来获取初始化数据。这一过程背后是插件监听 `message` 事件，等待来自 LobeChat 主体的初始化消息，并在接收到该消息时返回解析后的插件参数、名称、设置和状态。
+2. **接收插件载荷**：插件通过调用 `lobeChat.getPluginPayload()` 方法接收来自 LobeChat 主体的初始化数据。这一方法内部监听 `message` 事件，等待并处理 LobeChat 主体发送的包含插件所需数据的消息。
+3. **获取、更新基础信息**：插件可以调用 `lobeChat.setPluginSettings(settings)`、`lobeChat.setPluginMessage(content)`、`lobeChat.setPluginState(key, value)` 等方法来更新设置、消息内容和插件状态。
+4. **自定义触发动作**：针对 standalone 插件，可以利用通过 `lobeChat.triggerAIMessage(id)` 和 `lobeChat.createAssistantMessage(content)` 等方法自定义控制 AI 消息的触发、助理消息的创建，进而提供更加丰富的产品体验。
+
+总结来说，LobeChat 和插件之间的通信是通过`postMessage` API 进行异步消息交换来实现的，插件可以请求数据、接收数据、更新状态、触发消息等，而 LobeChat 主体则负责响应这些请求并提供所需的数据。这种机制允许插件以独立的方式运行并与 LobeChat 主体进行有效的双向通信。
+
+同时，我们在 SDK 中提供了 `lobeChat` 方法简化插件前端通信的开发。 通过 `lobeChat` 提供的一系列方法与 LobeChat 主体进行交互，这些方法和 Hooks 抽象了通信的细节，使得插件能够以简洁的 API 调用来与 LobeChat 主体进行互动。

docs/guides/default-plugin.md

@@ -0,0 +1,33 @@
+---
+title: Default Type Plugin
+group: Plugin Types
+order: 0
+---
+
+# Default Type Plugin
+
+The `default` plugin is the default type of plugin, mainly used for pure backend-driven plugins and display-oriented plugins, without rich interactive capabilities such as editing or deletion. They are suitable for scenarios that do not require complex user interaction and mainly rely on GPT for content summarization.
+
+For example, the officially implemented website crawler plugin:
+
+![web-crawler](https://github.com/lobehub/lobe-chat/assets/28616219/8a7191af-da07-4419-a0a1-37792b5c0c51)
+
+Search engine plugin:
+
+![search-engine](https://github.com/lobehub/lobe-chat/assets/28616219/573a905f-6df4-476b-8e1e-6c3098808ef8)
+
+And all compatible OpenAI ChatGPT plugins are of the `default` type.
+
+## How to Choose
+
+By default, we recommend choosing the `default` type plugin because default plugins cover common mainstream scenarios, such as:
+
+- You want the plugin's content to be summarized or further processed by GPT.
+- Your plugin requires simple backend processing and tight integration with GPT's responses.
+- The plugin you need is mainly used for content display, may require custom frontend display, but does not involve user interaction with the plugin (such as clicking confirm buttons);
+
+For example, a website content summarization plugin, where the user provides a link, and the plugin returns summary information, which is then interpreted or supplemented by GPT.
+
+## Developing Default Plugins
+
+The [tutorial](/zh-CN/quick-start/define-plugin-manifest) in the quick start has already introduced the development process of default plugins, so it will not be repeated here.