From 74d20a2069dd61e6050214e17299c49a45f964da Mon Sep 17 00:00:00 2001 From: Arvin Xu Date: Mon, 1 Jan 2024 18:05:38 +0800 Subject: [PATCH] :memo: docs: add plugin docs for the new third stage (#39) * :memo: docs: update docs * :memo: docs: update plugin docs * :memo: docs: update plugin docs * :memo: docs: update plugin docs * :memo: docs: update plugin docs * :memo: docs: update plugin docs * :memo: docs: add plugin docs * :memo: docs: add plugin en docs * :memo: docs: fix plugin docs --- .dumirc.ts | 2 +- ...md => get-plugin-settings-from-request.md} | 4 +- ...get-plugin-settings-from-request.zh-CN.md} | 3 +- docs/api/lobe-chat-client.zh-CN.md | 1 - docs/api/{channel.md => plugin-channel.md} | 4 +- ...annel.zh-CN.md => plugin-channel.zh-CN.md} | 6 +- docs/api/{error.md => plugin-error-type.md} | 2 +- ...or.zh-CN.md => plugin-error-type.zh-CN.md} | 6 +- docs/api/plugin-manifest.zh-CN.md | 3 +- ...gin-meta-index.md => plugin-meta-store.md} | 5 +- ...ex.zh-CN.md => plugin-meta-store.zh-CN.md} | 3 +- docs/changelog.md | 4 +- docs/changelog.zh-CN.md | 9 + docs/guides/client-sdk.md | 45 +++++ docs/guides/client-sdk.zh-CN.md | 45 +++++ docs/guides/communication-mechanisms.md | 53 ++++++ docs/guides/communication-mechanisms.zh-CN.md | 53 ++++++ docs/guides/default-plugin.md | 33 ++++ docs/guides/default-plugin.zh-CN.md | 33 ++++ docs/guides/js-server.md | 81 +++++++++ docs/guides/js-server.zh-CN.md | 81 +++++++++ docs/guides/markdown-plugin.md | 60 +++++++ docs/guides/markdown-plugin.zh-CN.md | 58 ++++++ docs/guides/openapi-schema.md | 51 ++++++ docs/guides/openapi-schema.zh-CN.md | 51 ++++++ docs/guides/openapi.md | 40 +++++ docs/guides/openapi.zh-CN.md | 40 +++++ docs/guides/plugin-fontend.md | 79 ++++++++ docs/guides/plugin-fontend.zh-CN.md | 79 ++++++++ docs/guides/plugin-invoke.md | 117 ++++++++++++ docs/guides/plugin-invoke.zh-CN.md | 117 ++++++++++++ docs/guides/plugin-manifest.md | 169 ++++++------------ docs/guides/plugin-manifest.zh-CN.md | 165 ++++++----------- docs/guides/plugin-server.md | 73 +++----- docs/guides/plugin-server.zh-CN.md | 73 +++----- docs/guides/plugin-type.md | 81 +++++++++ docs/guides/plugin-type.zh-CN.md | 81 +++++++++ docs/guides/python-server.md | 28 +++ docs/guides/python-server.zh-CN.md | 28 +++ docs/guides/server-auth.md | 59 ++++++ docs/guides/server-auth.zh-CN.md | 59 ++++++ docs/guides/server-gateway.md | 76 ++++++++ docs/guides/server-gateway.zh-CN.md | 76 ++++++++ docs/guides/standalone-plugin.md | 78 ++++++++ docs/guides/standalone-plugin.zh-CN.md | 78 ++++++++ docs/quick-start/define-plugin-manifest.md | 154 ++++++++++++++++ .../define-plugin-manifest.zh-CN.md | 156 ++++++++++++++++ docs/{guides => quick-start}/get-start.md | 1 + .../get-start.zh-CN.md | 5 +- docs/{guides => quick-start}/intro.md | 3 +- docs/{guides => quick-start}/intro.zh-CN.md | 6 +- docs/quick-start/plugin-server.md | 64 +++++++ docs/quick-start/plugin-server.zh-CN.md | 64 +++++++ .../plugin-settings.md | 2 +- .../plugin-settings.zh-CN.md | 2 +- docs/{guides => quick-start}/plugin-ui.md | 0 .../plugin-ui.zh-CN.md | 0 docs/{guides => quick-start}/submit-market.md | 6 +- .../submit-market.zh-CN.md | 8 +- docs/{guides => quick-start}/template.md | 1 + .../{guides => quick-start}/template.zh-CN.md | 1 + 61 files changed, 2412 insertions(+), 353 deletions(-) rename docs/api/{request.md => get-plugin-settings-from-request.md} (94%) rename docs/api/{request.zh-CN.md => get-plugin-settings-from-request.zh-CN.md} (95%) rename docs/api/{channel.md => plugin-channel.md} (98%) rename docs/api/{channel.zh-CN.md => plugin-channel.zh-CN.md} (97%) rename docs/api/{error.md => plugin-error-type.md} (98%) rename docs/api/{error.zh-CN.md => plugin-error-type.zh-CN.md} (94%) rename docs/api/{plugin-meta-index.md => plugin-meta-store.md} (93%) rename docs/api/{plugin-meta-index.zh-CN.md => plugin-meta-store.zh-CN.md} (97%) create mode 100644 docs/changelog.zh-CN.md create mode 100644 docs/guides/client-sdk.md create mode 100644 docs/guides/client-sdk.zh-CN.md create mode 100644 docs/guides/communication-mechanisms.md create mode 100644 docs/guides/communication-mechanisms.zh-CN.md create mode 100644 docs/guides/default-plugin.md create mode 100644 docs/guides/default-plugin.zh-CN.md create mode 100644 docs/guides/js-server.md create mode 100644 docs/guides/js-server.zh-CN.md create mode 100644 docs/guides/markdown-plugin.md create mode 100644 docs/guides/markdown-plugin.zh-CN.md create mode 100644 docs/guides/openapi-schema.md create mode 100644 docs/guides/openapi-schema.zh-CN.md create mode 100644 docs/guides/openapi.md create mode 100644 docs/guides/openapi.zh-CN.md create mode 100644 docs/guides/plugin-fontend.md create mode 100644 docs/guides/plugin-fontend.zh-CN.md create mode 100644 docs/guides/plugin-invoke.md create mode 100644 docs/guides/plugin-invoke.zh-CN.md create mode 100644 docs/guides/plugin-type.md create mode 100644 docs/guides/plugin-type.zh-CN.md create mode 100644 docs/guides/python-server.md create mode 100644 docs/guides/python-server.zh-CN.md create mode 100644 docs/guides/server-auth.md create mode 100644 docs/guides/server-auth.zh-CN.md create mode 100644 docs/guides/server-gateway.md create mode 100644 docs/guides/server-gateway.zh-CN.md create mode 100644 docs/guides/standalone-plugin.md create mode 100644 docs/guides/standalone-plugin.zh-CN.md create mode 100644 docs/quick-start/define-plugin-manifest.md create mode 100644 docs/quick-start/define-plugin-manifest.zh-CN.md rename docs/{guides => quick-start}/get-start.md (99%) rename docs/{guides => quick-start}/get-start.zh-CN.md (98%) rename docs/{guides => quick-start}/intro.md (99%) rename docs/{guides => quick-start}/intro.zh-CN.md (97%) create mode 100644 docs/quick-start/plugin-server.md create mode 100644 docs/quick-start/plugin-server.zh-CN.md rename docs/{guides => quick-start}/plugin-settings.md (99%) rename docs/{guides => quick-start}/plugin-settings.zh-CN.md (99%) rename docs/{guides => quick-start}/plugin-ui.md (100%) rename docs/{guides => quick-start}/plugin-ui.zh-CN.md (100%) rename docs/{guides => quick-start}/submit-market.md (91%) rename docs/{guides => quick-start}/submit-market.zh-CN.md (93%) rename docs/{guides => quick-start}/template.md (99%) rename docs/{guides => quick-start}/template.zh-CN.md (99%) diff --git a/.dumirc.ts b/.dumirc.ts index 0ce1325..d6d6142 100644 --- a/.dumirc.ts +++ b/.dumirc.ts @@ -12,7 +12,7 @@ const themeConfig = { text: 'Github', }, { - link: '/guides/intro', + link: '/quick-start/intro', text: 'Get Started', type: 'primary', }, diff --git a/docs/api/request.md b/docs/api/get-plugin-settings-from-request.md similarity index 94% rename from docs/api/request.md rename to docs/api/get-plugin-settings-from-request.md index e349f6e..e23b327 100644 --- a/docs/api/request.md +++ b/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 --- diff --git a/docs/api/request.zh-CN.md b/docs/api/get-plugin-settings-from-request.zh-CN.md similarity index 95% rename from docs/api/request.zh-CN.md rename to docs/api/get-plugin-settings-from-request.zh-CN.md index 99afb90..0ec95f9 100644 --- a/docs/api/request.zh-CN.md +++ b/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' --- 用于从请求中获取插件设置字符串。 diff --git a/docs/api/lobe-chat-client.zh-CN.md b/docs/api/lobe-chat-client.zh-CN.md index c500083..0fb0924 100644 --- a/docs/api/lobe-chat-client.zh-CN.md +++ b/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 交互的所有关键方法。 diff --git a/docs/api/channel.md b/docs/api/plugin-channel.md similarity index 98% rename from docs/api/channel.md rename to docs/api/plugin-channel.md index 7fe359f..59734b0 100644 --- a/docs/api/channel.md +++ b/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 diff --git a/docs/api/channel.zh-CN.md b/docs/api/plugin-channel.zh-CN.md similarity index 97% rename from docs/api/channel.zh-CN.md rename to docs/api/plugin-channel.zh-CN.md index c9deb16..d88f6c5 100644 --- a/docs/api/channel.zh-CN.md +++ b/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 通信消息 diff --git a/docs/api/error.md b/docs/api/plugin-error-type.md similarity index 98% rename from docs/api/error.md rename to docs/api/plugin-error-type.md index e925d65..b9603ad 100644 --- a/docs/api/error.md +++ b/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 diff --git a/docs/api/error.zh-CN.md b/docs/api/plugin-error-type.zh-CN.md similarity index 94% rename from docs/api/error.zh-CN.md rename to docs/api/plugin-error-type.zh-CN.md index 348ec2f..0f45df7 100644 --- a/docs/api/error.zh-CN.md +++ b/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 在插件服务请求中所有的错误类型，包括业务语义错误、客户端错误和服务端错误。 diff --git a/docs/api/plugin-manifest.zh-CN.md b/docs/api/plugin-manifest.zh-CN.md index accc6c5..300b7d7 100644 --- a/docs/api/plugin-manifest.zh-CN.md +++ b/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 diff --git a/docs/api/plugin-meta-index.md b/docs/api/plugin-meta-store.md similarity index 93% rename from docs/api/plugin-meta-index.md rename to docs/api/plugin-meta-store.md index 95fa6fc..5e994ef 100644 --- a/docs/api/plugin-meta-index.md +++ b/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. diff --git a/docs/api/plugin-meta-index.zh-CN.md b/docs/api/plugin-meta-store.zh-CN.md similarity index 97% rename from docs/api/plugin-meta-index.zh-CN.md rename to docs/api/plugin-meta-store.zh-CN.md index 6424667..78af917 100644 --- a/docs/api/plugin-meta-index.zh-CN.md +++ b/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。 diff --git a/docs/changelog.md b/docs/changelog.md index cc32c8f..6660760 100644 --- a/docs/changelog.md +++ b/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 --- diff --git a/docs/changelog.zh-CN.md b/docs/changelog.zh-CN.md new file mode 100644 index 0000000..cc32c8f --- /dev/null +++ b/docs/changelog.zh-CN.md @@ -0,0 +1,9 @@ +--- +title: 更新日志 +description: New updates and improvements to @lobehub/chat-plugin-sdk +nav: + title: 更新日志 + order: 999 +--- + + diff --git a/docs/guides/client-sdk.md b/docs/guides/client-sdk.md new file mode 100644 index 0000000..435fd6f --- /dev/null +++ b/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). diff --git a/docs/guides/client-sdk.zh-CN.md b/docs/guides/client-sdk.zh-CN.md new file mode 100644 index 0000000..4ea91a9 --- /dev/null +++ b/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)。 diff --git a/docs/guides/communication-mechanisms.md b/docs/guides/communication-mechanisms.md new file mode 100644 index 0000000..bf5de4a --- /dev/null +++ b/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 `