📝 docs: update plugin docs

lobehub · Dec 30, 2023 · 1495501 · 1495501
1 parent 99f0afb
commit 1495501
Show file tree

Hide file tree

Showing 13 changed files with 132 additions and 14 deletions.
diff --git a/docs/api/channel.zh-CN.md b/docs/api/channel.zh-CN.md
@@ -9,6 +9,8 @@ description: 提供了关于插件通信的消息类型的详细说明
 nav:
   title: API
   order: 1
+apiHeader:
+  pkg: '@lobehub/chat-plugin-sdk'
 ---
 
 # PluginChannel 通信消息

diff --git a/docs/api/request.zh-CN.md → ...get-plugin-settings-from-request.zh-CN.md b/docs/api/request.zh-CN.md → ...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
@@ -6,7 +6,6 @@ group:
   order: 10
 apiHeader:
   pkg: '@lobehub/chat-plugin-sdk/client'
-nav: API
 ---
 
 该实例包含插件侧与 LobeChat 交互的所有关键方法。

diff --git a/docs/api/error.zh-CN.md → docs/api/plugin-error-type.zh-CN.md b/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 在插件服务请求中所有的错误类型，包括业务语义错误、客户端错误和服务端错误。

diff --git 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.zh-CN.md b/docs/api/plugin-meta-index.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/guides/communication-mechanisms.zh-CN.md b/docs/guides/communication-mechanisms.zh-CN.md
@@ -1,7 +1,53 @@
 ---
-title: 插件通信机制
+title: 插件通信
 group: 基本概念
 order: 3
 ---
 
-# 插件通信机制
+# 插件通信机制概述
+
+## 服务端通信
+
+针对 `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 主体进行互动。
diff --git a/docs/guides/default-plugin.zh-CN.md b/docs/guides/default-plugin.zh-CN.md
@@ -17,3 +17,15 @@ order: 0
 ![search-engine](https://github.com/lobehub/lobe-chat/assets/28616219/573a905f-6df4-476b-8e1e-6c3098808ef8)
 
 以及所有兼容的 OpenAI ChatGPT 插件均为 `default` 类型。
+
+## 如何选择
+
+在开发 LobeChat 插件时，选择正确的插件类型对于实现预期的用户体验至关重要。下面是一个指南，可以帮助你根据不同的场景和需求选择最合适的插件类型。
+
+如果你的需求符合以下场景，可以选择 `default` 插件：
+
+- 你希望插件的内容能够被 GPT 进行总结或进一步处理。
+- 你的插件需要简单的后端处理，并且希望与 GPT 的回复紧密结合。
+- 你需要的插件主要用于内容展示，可能需要自定义前端展示，但不涉及用户与插件的交互操作（例如点击确认按钮等）；
+
+例如，一个网站内容摘要插件，用户提供一个链接，插件返回摘要信息，然后由 GPT 进行解读或补充。
diff --git a/docs/guides/markdown-plugin.zh-CN.md b/docs/guides/markdown-plugin.zh-CN.md
@@ -11,3 +11,14 @@ order: 2
 `Markdown` 插件类型允许插件返回 Markdown 格式的内容直接显示在聊天中。这种渲染方式适用于结果明确，不需要再次发送给 AI 进行处理的场景。例如，当用户询问某个特定信息时，插件可以直接返回一个包含答案的 Markdown 消息，而不需要额外的 AI 总结过程。此外，与这种类型搭配的配置可以设置为不再触发 AI 消息，这样就可以避免不必要的 AI 调用。
 
 ![clothes](https://github.com/lobehub/lobe-chat/assets/28616219/7077a4d4-5b0f-4d4e-b332-d79b7df2b411)
+
+## 如何选择
+
+如果你的需求符合以下场景，可以选择 `markdown` 插件：
+
+- 你需要快速返回明确的、格式化的文本结果。
+- 你不需要复杂的前端交互，但希望结果能够支持 Markdown 格式的丰富展示。
+- 你希望避免不必要的 AI 总结或处理，直接将结果展示给用户。
+- 你的插件是为了解答简单且明确的查询，例如时间查询、人名查询等。
+
+例如，一个查询当前时间的插件，用户询问 “现在北京时间几点？” 插件返回一个格式化的 Markdown 消息，显示当前时间。
diff --git a/docs/guides/openapi.zh-CN.md b/docs/guides/openapi.zh-CN.md
@@ -5,3 +5,36 @@ order: 4
 ---
 
 # OpenAPI
+
+LobeChat 的插件机制支持 OpenAPI 规范，这是一个用于定义和描述 RESTful APIs 的标准。通过使用 OpenAPI，开发者可以创建一个明确的、与语言无关的 API 描述，以促进 API 的正确实现和使用。以下是 LobeChat 对 OpenAPI 支持的简介内容：
+
+## LobeChat 插件兼容性
+
+LobeChat 的插件系统完全兼容 OpenAPI 文档。这意味着，当你创建一个 LobeChat 插件时，你只需按照以下步骤进行，就可以将一个 OpenAPI 服务转换为一个会话插件：
+
+1. **构建 API** - 开发你的服务 API，确保它能够处理来自 LobeChat 的请求并返回适当的响应。
+2. **OpenAPI 文档** - 使用 OpenAPI 规范（YAML 或 JSON 格式）来描述你的 API。这个文档应该详细说明你的 API 的各个端点、参数、响应格式等。
+3. **创建插件清单** - 创建一个 LobeChat 的 `manifest.json` 插件清单文件，该文件包含了插件的元数据，如插件的名称、描述等，最关键的则是在 `openapi` 字段中填写你的 OpenAPI 文档的 URL。
+
+## OpenAPI 规范
+
+OpenAPI 规范是一个标准，用于描述 RESTful API 的结构和行为。这个规范允许开发者定义如下内容：
+
+- API 的基本信息（如标题、描述和版本）
+- API 服务器的 URL
+- 可用的端点（路径）和操作（如 GET、POST、PUT、DELETE）
+- 每个操作的输入和输出参数
+- 认证方法（如无认证、HTTP 基本认证、OAuth2）
+- 通用的响应消息和错误代码
+
+你可以从这里查看 [天气插件](https://github.com/steven-tey/weathergpt) 的 OpenAPI 文档示例： [openapi.json](https://weathergpt.vercel.app/openapi.json)。
+
+关于 OpenAPI 的详细介绍，可以查阅 [OpenAPI 规范](https://swagger.io/specification/)。
+
+## 使用 OpenAPI 与 LobeChat 集成
+
+当你的 API 和插件清单文件准备好后，你可以将其与 LobeChat 集成。在 LobeChat UI 中，用户可以安装你的插件，并通过 OpenAPI 文档中定义的端点与你的服务交互。你的 OpenAPI 文档将指导 LobeChat 如何与你的 API 通信，确保正确解释和处理请求和响应。
+
+例如 AskYourPDF 插件：
+
+我们努力在 LobeChat 的插件机制上实现与 OpenAPI 的集成，以确保你的服务可以无缝地与 LobeChat 集成，提供丰富的用户体验。通过遵循 OpenAPI 规范，你可以确保你的 API 文档准确、一致，并且易于使用。
diff --git a/docs/guides/plugin-invoke.zh-CN.md b/docs/guides/plugin-invoke.zh-CN.md
@@ -65,11 +65,8 @@ Host: plugin.example.com
 Content-Type: application/json
 
 {
-  "function": "queryWeatherForecast",
-  "arguments": {
-    "city": "用户所在城市",
-    "date": "明天的日期"
-  }
+  "city": "用户所在城市",
+  "date": "明天的日期"
 }
 ```
 

diff --git a/docs/guides/plugin-type.zh-CN.md b/docs/guides/plugin-type.zh-CN.md
@@ -1,5 +1,5 @@
 ---
-title: 插件类型
+title: LobeChat 插件类型
 group: 基本概念
 order: 2
 ---

diff --git a/docs/guides/standalone-plugin.zh-CN.md b/docs/guides/standalone-plugin.zh-CN.md
@@ -13,3 +13,16 @@ order: 2
 例如：官方实现的时钟插件就是标准的 Standalone 插件，该插件的特点是不包含任何后端 API，由纯前端实现。
 
 <video src="https://github.com/lobehub/lobe-chat/assets/28616219/206b4c94-4674-4007-ac4f-450b9778d7f6" width="100%" autoplay mute ></video>
+
+## 如何选择
+
+在开发 LobeChat 插件时，选择正确的插件类型对于实现预期的用户体验至关重要。下面是一个指南，可以帮助你根据不同的场景和需求选择最合适的插件类型。
+
+如果你的需求符合以下场景，建议选择 `standalone` 插件：
+
+- 你的插件需要提供复杂的、富交互的用户体验。
+- 你希望完全控制交互逻辑，甚至包括是否触发后续的 AI 消息。
+- 你的插件是一个独立的应用，可能包含表单、游戏或其他复杂功能。
+- 你需要完全自定义的前端展示，并且希望能够通过程序控制 AI 的行为。
+
+例如，一个在线预订系统的插件，用户可以通过表单选择日期和时间，提交后插件处理预订并反馈结果。