From ce3403cacdd36836f2074a0d06821d2ec22c609e Mon Sep 17 00:00:00 2001 From: arvinxx Date: Fri, 29 Dec 2023 21:59:13 +0800 Subject: [PATCH 1/9] :memo: docs: update docs --- docs/guides/plugin-invoke.zh-CN.md | 118 +++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/guides/plugin-invoke.zh-CN.md diff --git a/docs/guides/plugin-invoke.zh-CN.md b/docs/guides/plugin-invoke.zh-CN.md new file mode 100644 index 0000000..6dadb95 --- /dev/null +++ b/docs/guides/plugin-invoke.zh-CN.md @@ -0,0 +1,118 @@ +--- +title: LobeChat 插件触发机制 +description: 如何通过 Function Call 触发 LobeChat 插件 +--- + +# LobeChat 插件触发流程 + +LobeChat 插件系统通过 [Function Call 机制](https://sspai.com/post/81986)来触发插件，使得聊天机器人能够与外部 API 进行互动，以增强用户体验。以下是插件触发流程的详细说明。 + +## Function Call 基本原理 + +Function Call 是一项允许开发者在 GPT 模型中描述函数的新功能，使得模型能够智能地生成调用这些函数所需的 JSON 参数。这种机制通过提高与外部工具和 API 的连接可靠性来扩展大模型的能力。 + +## 插件触发步骤 + +1. **用户输入**：用户向 LobeChat 提出请求，如查询天气或添加待办事项。 +2. **意图识别**：模型分析用户的输入，确定是否需调用一个插件来应对请求。 +3. **生成 Function Call**：如果需要插件介入，模型会生成一个包含必要参数的 Function Call 请求。 +4. **发送请求**：LobeChat 将 Function Call 以 API 请求的形式发送到指定的插件服务端。 +5. **处理请求**：插件服务端接收到 Function Call 请求，处理该请求，并准备响应数据。 +6. **返回响应**：插件服务端将处理后的数据以 JSON 格式返回给 LobeChat。 +7. **模型处理插件响应**：模型接收到插件的响应数据，并根据这些数据继续与用户进行交互。 + +## 示例流程：天气预报插件 + +以下是一个详细的天气预报插件触发流程，包括基于 OpenAI 数据结构的 JSON 请求和响应示例。 + +### 1. 用户询问 + +用户向 LobeChat 提出了以下请求： + +```json +{ + "content": "我明天的户外活动会受天气影响吗？", + "role": "user" +} +``` + +### 2. 模型生成 Function Call + +模型识别到用户想要了解明天的天气情况，并生成一个 Function Call，请求天气预报插件提供数据： + +```json +{ + "content": { + "arguments": { + "city": "用户所在城市", + "date": "明天的日期" + } + }, + "name": "queryWeatherForecast", + "role": "function" +} +``` + +### 3. LobeChat 发送 API 请求 + +LobeChat 将上述 Function Call 转换为对天气预报插件的 API 请求： + +```http +POST /weather-forecast HTTP/1.1 +Host: plugin.example.com +Content-Type: application/json + +{ + "function": "queryWeatherForecast", + "arguments": { + "city": "用户所在城市", + "date": "明天的日期" + } +} +``` + +### 4. 插件处理请求并返回数据 + +天气预报插件处理请求，并返回明天的天气预报数据： + +```json +{ + "content": { + "forecast": { + "city": "用户所在城市", + "date": "明天的日期", + "condition": "晴", + "temperature": { + "high": 25, + "low": 18 + }, + "advice": "温度适宜，适合户外活动。建议穿着轻便，带上太阳镜。" + } + }, + "name": "queryWeatherForecast", + "role": "function" +} +``` + +### 5. 模型接收响应并与用户交互 + +模型接收到插件的响应后，根据返回的数据与用户进行交互： + +```json +{ + "content": "根据插件提供的天气预报，明天您所在城市的天气是晴朗，最高气温25度，最低气温18度。温度适宜，很适合进行户外活动。建议穿着轻便，并带上太阳镜。", + "role": "assistant" +} +``` + +用户将看到模型的响应，并根据建议做好相应的准备。 + +## 注意事项 + +- Function Call 的设计需要精确地反映用户的意图和所需的参数。 +- 插件必须能够安全、高效地处理来自 LobeChat 的请求，并提供准确的响应。 +- OpenAI 的新版实现中，Function Call 的实现已经更新为 tool_calls。LobeChat 已完成兼容适配，以适应新版实现。 + +## 结论 + +Function Call 机制为 LobeChat 插件提供了一种灵活且高效的工具触发机制，使得 LobeChat 助理能够以更为智能的方式与外部服务进行交互。这种机制不仅提升了用户体验，还为开发者提供了广阔的创新空间。 From c6e34725a83e5f8af51a5d101aa473ce42fad582 Mon Sep 17 00:00:00 2001 From: arvinxx Date: Fri, 29 Dec 2023 23:22:21 +0800 Subject: [PATCH 2/9] :memo: docs: update plugin docs --- ...-manifest.md => define-plugin-manifest.md} | 0 docs/guides/define-plugin-manifest.zh-CN.md | 156 +++++++++++++++++ docs/guides/intro.zh-CN.md | 4 +- docs/guides/plugin-invoke.zh-CN.md | 4 +- docs/guides/plugin-manifest.zh-CN.md | 162 ++++++------------ docs/guides/plugin-type.zh-CN.md | 81 +++++++++ docs/guides/submit-market.zh-CN.md | 2 +- 7 files changed, 294 insertions(+), 115 deletions(-) rename docs/guides/{plugin-manifest.md => define-plugin-manifest.md} (100%) create mode 100644 docs/guides/define-plugin-manifest.zh-CN.md create mode 100644 docs/guides/plugin-type.zh-CN.md diff --git a/docs/guides/plugin-manifest.md b/docs/guides/define-plugin-manifest.md similarity index 100% rename from docs/guides/plugin-manifest.md rename to docs/guides/define-plugin-manifest.md diff --git a/docs/guides/define-plugin-manifest.zh-CN.md b/docs/guides/define-plugin-manifest.zh-CN.md new file mode 100644 index 0000000..5c53e5a --- /dev/null +++ b/docs/guides/define-plugin-manifest.zh-CN.md @@ -0,0 +1,156 @@ +--- +title: 定义插件描述清单 +group: + title: 插件开发 + order: 2 +order: 1 +--- + +# manifest 定义 + +manifest 聚合了插件功能如何实现的信息。核心的字段为 `api` 与 `ui`，分别描述了插件的服务端接口能力与前端渲染的界面地址。 + +以我们提供的模板中的 [manifest](https://github.com/lobehub/chat-plugin-template/blob/main/public/manifest-dev.json) 为例： + +```json +{ + "$schema": "../node_modules/@lobehub/chat-plugin-sdk/schema.json", + "api": [ + { + "url": "http://localhost:3400/api/clothes", + "name": "recommendClothes", + "description": "根据用户的心情，给用户推荐他有的衣服", + "parameters": { + "properties": { + "mood": { + "description": "用户当前的心情，可选值有：开心（happy）, 难过（sad）,生气 （anger）,害怕（fear）,惊喜（ surprise）,厌恶 （disgust）", + "enums": ["happy", "sad", "anger", "fear", "surprise", "disgust"], + "type": "string" + }, + "gender": { + "type": "string", + "enum": ["man", "woman"], + "description": "对话用户的性别，需要询问用户后才知道这个信息" + } + }, + "required": ["mood", "gender"], + "type": "object" + } + } + ], + "gateway": "http://localhost:3400/api/gateway", + "identifier": "chat-plugin-template", + "ui": { + "url": "http://localhost:3400", + "height": 200 + }, + "version": "1" +} +``` + +在这份 manifest 中，主要包含了以下几个部分： + +## `identifier` + +这是插件的唯一标识符，用来区分不同的插件，这个字段需要全局唯一。 + +## `api` + +这是一个数组，包含了插件所提供的所有 API 接口信息。每个接口都包含了 url、name、description 和 parameters 字段，均为必填项。 + +其中 `description` 和 `parameters` 两个字段，将会作为 [Function Call](https://sspai.com/post/81986) 的 `functions` 参数发送给 gpt，示例如下： + +```json +{ + "functions": [ + { + "name": "realtimeWeather", + "description": "获取当前天气情况", + "parameters": { + "type": "object", + "properties": { + "city": { + "description": "城市名称", + "type": "string" + } + }, + "required": ["city"] + } + } + ], + "messages": [ + { + "role": "user", + "content": "我明天应该穿什么？" + }, + { + "role": "assistant", + "content": "请告诉你所在的城市？" + }, + { + "role": "user", + "content": "杭州" + } + ] +} +``` + +其中，parameters 需要符合 [JSON Schema](https://json-schema.org/) 规范，可以使用下述方式进行校验： + +```ts +import { z } from 'zod'; + +const JSONSchema = z.object({ + properties: z.object({}), + type: z.enum(['object']), +}); +``` + +在我们提供的模板示例中，api 对应的接口名为 `recommendClothes` ，这个接口的功能是根据用户的心情和性别来推荐衣服。接口的参数包括用户的心情和性别，这两个参数都是必填项。 + +## `ui` + +这个字段包含了插件的用户界面信息，指明了 LobeChat 从哪个地址加载插件的前端界面。由于 LobeChat 插件界面加载是基于 iframe 实现的，因此可以按需指定插件界面的高度、宽度。 + +## `gateway` + +这个字段指定了 LobeChat 查询 api 接口的网关。LobeChat 默认的插件网关是云端服务，而自定义插件的请求需要发送给本地服务的，因此通过在 manifest 中指定网关，LobeChat 将会直接请求这个地址，进而访问到本地的插件服务，发布到线上的插件可以不用指定该字段。 + +## API 与 Schema + +关于 manifest 各个字段的完整介绍，参见：[manifest](/api/plugin-manifest)。 + +## JSON 类型提示 + +SDK 提供了 manifest 的 JSON Schema 定义，它可以用于在编写 `manifest.json` 文件时为 IDE 提供类型信息和智能提示。 + +使用时你只需为 JSON 配置文件声明 `$schema` 字段来指向 schema 定义文件即可，以 [lobehub/chat-plugin-template](https://github.com/lobehub/chat-plugin-template/blob/main/public/manifest-dev.json) 为例，它的项目结构为： + +```plaintext +lobehub/chat-plugin-template +├── CHANGELOG.md +├── node_modules +├── README.md +├── src +├── public +│ ├── foo.json +│ ├── manifest-dev.json +│ └── manifest-standalone.json +└── package.json +``` + +那么 `manifest-dev.json` 的 `$schema` 字段可以配置为这样的相对路径： + +```json filename=manifest-dev.json +{ + "$schema": "../node_modules/@lobehub/chat-plugin-sdk/schema.json", + "api": [], + "gateway": "http://localhost:3400/api/gateway", + "identifier": "plugin-identifier", + "ui": { + "url": "http://localhost:3400", + "height": 200 + }, + "version": "1" +} +``` diff --git a/docs/guides/intro.zh-CN.md b/docs/guides/intro.zh-CN.md index 248ad5a..a06026b 100644 --- a/docs/guides/intro.zh-CN.md +++ b/docs/guides/intro.zh-CN.md @@ -1,6 +1,8 @@ --- title: 简介 -group: 快速上手 +group: + title: 快速上手 + order: 0 nav: title: 指南 order: 1 diff --git a/docs/guides/plugin-invoke.zh-CN.md b/docs/guides/plugin-invoke.zh-CN.md index 6dadb95..85a71ee 100644 --- a/docs/guides/plugin-invoke.zh-CN.md +++ b/docs/guides/plugin-invoke.zh-CN.md @@ -1,6 +1,8 @@ --- -title: LobeChat 插件触发机制 +title: 插件触发机制 description: 如何通过 Function Call 触发 LobeChat 插件 +group: 基本概念 +order: 3 --- # LobeChat 插件触发流程 diff --git a/docs/guides/plugin-manifest.zh-CN.md b/docs/guides/plugin-manifest.zh-CN.md index 14dc269..7a82fd1 100644 --- a/docs/guides/plugin-manifest.zh-CN.md +++ b/docs/guides/plugin-manifest.zh-CN.md @@ -1,14 +1,59 @@ --- -title: 定义插件描述清单 -group: 插件开发 +title: 插件 Manifest +group: + title: 基本概念 + order: 1 order: 1 --- -# manifest 定义 +# 插件 Manifest -manifest 聚合了插件功能如何实现的信息。核心的字段为 `api` 与 `ui`，分别描述了插件的服务端接口能力与前端渲染的界面地址。 +LobeChat 插件 Manifest 是一个关键的配置文件，它用于描述和定义一个 LobeChat 插件的基本信息和行为。Manifest 文件作为插件的 “身份证”，为 LobeChat 平台提供了如何处理和集成该插件的必要信息。 -以我们提供的模板中的 [manifest](https://github.com/lobehub/chat-plugin-template/blob/main/public/manifest-dev.json) 为例： +## 简介 + +Manifest 文件通常是以 JSON 格式提供的，以确保 LobeChat 平台能够正确解析和使用插件： + +- **标识插件**: Manifest 包含了插件的唯一标识符 ( `identifier` )，这个标识符用于在 LobeChat 平台中区分不同的插件。 +- **配置元数据**: 插件的元数据 ( `meta` )，如标题、描述、标签和头像，用于在 LobeChat 的用户界面中展示插件的信息，帮助用户理解插件的用途。 +- **设定插件描述**: 通过指定系统设定 ( `systemRole` )，我们可以设定插件的描述信息，以便模型能够更好地理解插件的功能和用途。 +- **定义接口**: 通过在 Manifest 中声明 API 接口 ( `api` )，插件可以清晰地告诉 LobeChat 平台它能够提供哪些功能和服务。 +- **指定 UI 展示**: 插件的 UI 配置 ( `ui` ) 决定了插件如何在 LobeChat 中显示，包括其模式、尺寸和加载的 URL。 + +## Manifest Schema + +LobeChat 的插件系统允许开发者使用 Manifest 文件定义插件的配置和行为。 下面是 Manifest 文件的详细结构说明。 + +manifest 是一个 JSON 文件，其中包含以下字段： + +```typescript +{ + "api": Array, // 插件 API 的定义数组 + "author": String, // 插件作者，可选 + "createAt": String, // 插件创建日期，可选 + "gateway": String, // 插件网关地址，可选 + "homepage": String, // 插件主页 URL，可选 + "identifier": String, // 插件唯一标识符 + "meta": { // 插件元数据 + "avatar": String, // 插件头像 URL，可选 + "description": String, // 插件描述，可选 + "tags": Array, // 插件标签数组，可选 + "title": String // 描述插件的标题，可选 + }, + "openapi": String, // 插件 OpenAPI 规范 URL，可选 + "settings": JSONSchema, // 插件设置的 JSON Schema，可选 + "systemRole": String, // 插件系统角色，可选 + "type": Enum['default', 'markdown', 'standalone'], // 插件类型，可选 + "ui": { // 插件 UI 配置，可选 + "height": Number, // UI 高度，可选 + "mode": Enum['iframe', 'module'], // UI 模式，可选 + "url": String, // UI 地址 + "width": Number // UI 宽度，可选 + } +} +``` + +一个示例如下： ```json { @@ -45,110 +90,3 @@ manifest 聚合了插件功能如何实现的信息。核心的字段为 `api` "version": "1" } ``` - -在这份 manifest 中，主要包含了以下几个部分： - -## `identifier` - -这是插件的唯一标识符，用来区分不同的插件，这个字段需要全局唯一。 - -## `api` - -这是一个数组，包含了插件所提供的所有 API 接口信息。每个接口都包含了 url、name、description 和 parameters 字段，均为必填项。 - -其中 `description` 和 `parameters` 两个字段，将会作为 [Function Call](https://sspai.com/post/81986) 的 `functions` 参数发送给 gpt，示例如下： - -```json -{ - "functions": [ - { - "name": "realtimeWeather", - "description": "获取当前天气情况", - "parameters": { - "type": "object", - "properties": { - "city": { - "description": "城市名称", - "type": "string" - } - }, - "required": ["city"] - } - } - ], - "messages": [ - { - "role": "user", - "content": "我明天应该穿什么？" - }, - { - "role": "assistant", - "content": "请告诉你所在的城市？" - }, - { - "role": "user", - "content": "杭州" - } - ] -} -``` - -其中，parameters 需要符合 [JSON Schema](https://json-schema.org/) 规范，可以使用下述方式进行校验： - -```ts -import { z } from 'zod'; - -const JSONSchema = z.object({ - properties: z.object({}), - type: z.enum(['object']), -}); -``` - -在我们提供的模板示例中，api 对应的接口名为 `recommendClothes` ，这个接口的功能是根据用户的心情和性别来推荐衣服。接口的参数包括用户的心情和性别，这两个参数都是必填项。 - -## `ui` - -这个字段包含了插件的用户界面信息，指明了 LobeChat 从哪个地址加载插件的前端界面。由于 LobeChat 插件界面加载是基于 iframe 实现的，因此可以按需指定插件界面的高度、宽度。 - -## `gateway` - -这个字段指定了 LobeChat 查询 api 接口的网关。LobeChat 默认的插件网关是云端服务，而自定义插件的请求需要发送给本地服务的，因此通过在 manifest 中指定网关，LobeChat 将会直接请求这个地址，进而访问到本地的插件服务，发布到线上的插件可以不用指定该字段。 - -## API 与 Schema - -关于 manifest 各个字段的完整介绍，参见：[manifest](/api/plugin-manifest)。 - -## JSON 类型提示 - -SDK 提供了 manifest 的 JSON Schema 定义，它可以用于在编写 `manifest.json` 文件时为 IDE 提供类型信息和智能提示。 - -使用时你只需为 JSON 配置文件声明 `$schema` 字段来指向 schema 定义文件即可，以 [lobehub/chat-plugin-template](https://github.com/lobehub/chat-plugin-template/blob/main/public/manifest-dev.json) 为例，它的项目结构为： - -```plaintext -lobehub/chat-plugin-template -├── CHANGELOG.md -├── node_modules -├── README.md -├── src -├── public -│ ├── foo.json -│ ├── manifest-dev.json -│ └── manifest-standalone.json -└── package.json -``` - -那么 `manifest-dev.json` 的 `$schema` 字段可以配置为这样的相对路径： - -```json filename=manifest-dev.json -{ - "$schema": "../node_modules/@lobehub/chat-plugin-sdk/schema.json", - "api": [], - "gateway": "http://localhost:3400/api/gateway", - "identifier": "plugin-identifier", - "ui": { - "url": "http://localhost:3400", - "height": 200 - }, - "version": "1" -} -``` diff --git a/docs/guides/plugin-type.zh-CN.md b/docs/guides/plugin-type.zh-CN.md new file mode 100644 index 0000000..f519c29 --- /dev/null +++ b/docs/guides/plugin-type.zh-CN.md @@ -0,0 +1,81 @@ +--- +title: 插件类型 +group: 基本概念 +order: 2 +--- + +# LobeChat 插件类型 + +LobeChat 的插件机制为开发者提供了强大的扩展能力，允许在聊天中嵌入自定义的功能和交互。目前，LobeChat 支持三种类型的插件：`default`、`markdown` 和 `standalone`。以下是这三类插件的简要介绍： + +## Default 插件 + +`default` 插件是默认的插件类型，它们主要用于纯后端驱动插件与展示型的插件，没有编辑、删除等富交互能力。它们适用于不需要复杂用户交互，且主要依赖 GPT 进行内容总结的场景。 + +例如官方实现的网站爬虫插件： + +![web-crawler](https://github.com/lobehub/lobe-chat/assets/28616219/8a7191af-da07-4419-a0a1-37792b5c0c51) + +搜索引擎插件： + +![search-engine](https://github.com/lobehub/lobe-chat/assets/28616219/573a905f-6df4-476b-8e1e-6c3098808ef8) + +以及所有兼容的 OpenAI ChatGPT 插件均为 `default` 类型。 + +## Markdown 插件 + +`Markdown` 插件类型允许插件返回 Markdown 格式的内容直接显示在聊天中。这种渲染方式适用于结果明确，不需要再次发送给 AI 进行处理的场景。例如，当用户询问某个特定信息时，插件可以直接返回一个包含答案的 Markdown 消息，而不需要额外的 AI 总结过程。此外，与这种类型搭配的配置可以设置为不再触发 AI 消息，这样就可以避免不必要的 AI 调用。 + +![clothes](https://github.com/lobehub/lobe-chat/assets/28616219/7077a4d4-5b0f-4d4e-b332-d79b7df2b411) + +## Standalone 插件 + +`standalone` 插件类型是为了支持复杂交互而设计的。这类插件可以完全控制交互逻辑，并且以独立的应用的形态运行。它们适合于需要丰富用户交互的场景，例如表单填写、游戏或其他需要多步骤操作的应用。`standalone` 插件可以通过自行控制来决定是否触发 AI 消息，甚至可以通过程序化的方式来触发 AI 回复。 + +`standalone` 类型的插件正是 LobeChat 与 ChatGPT 插件系统的最大差别，正因为该类插件的存在，我们才能够通过插件实现更加复杂的会话交互体验。 + +例如：官方实现的时钟插件就是标准的 Standalone 插件，该插件的特点是不包含任何后端 API，由纯前端实现。 + + + +## 如何选择 + +在开发 LobeChat 插件时，选择正确的插件类型对于实现预期的用户体验至关重要。下面是一个指南，可以帮助你根据不同的场景和需求选择最合适的插件类型。 + +### Default 插件 + +选择 `default` 插件，如果你的需求符合以下场景： + +- 你希望插件的内容能够被 GPT 进行总结或进一步处理。 +- 你的插件需要简单的后端处理，并且希望与 GPT 的回复紧密结合。 +- 你需要的插件主要用于内容展示，可能需要自定义前端展示，但不涉及用户与插件的交互操作（例如点击确认按钮等）； + +例如，一个网站内容摘要插件，用户提供一个链接，插件返回摘要信息，然后由 GPT 进行解读或补充。 + +### Markdown 插件 + +选择 `markdown` 插件，如果你的需求符合以下场景： + +- 你需要快速返回明确的、格式化的文本结果。 +- 你不需要复杂的前端交互，但希望结果能够支持 Markdown 格式的丰富展示。 +- 你希望避免不必要的 AI 总结或处理，直接将结果展示给用户。 +- 你的插件是为了解答简单且明确的查询，例如时间查询、人名查询等。 + +例如，一个查询当前时间的插件，用户询问 “现在北京时间几点？” 插件返回一个格式化的 Markdown 消息，显示当前时间。 + +### Standalone 插件 + +选择 `standalone` 插件，如果你的需求符合以下场景： + +- 你的插件需要提供复杂的、富交互的用户体验。 +- 你希望完全控制交互逻辑，甚至包括是否触发后续的 AI 消息。 +- 你的插件是一个独立的应用，可能包含表单、游戏或其他复杂功能。 +- 你需要完全自定义的前端展示，并且希望能够通过程序控制 AI 的行为。 + +例如，一个在线预订系统的插件，用户可以通过表单选择日期和时间，提交后插件处理预订并反馈结果。 + +在选择插件类型时，考虑用户交互的复杂度、对 AI 的依赖程度以及展示内容的需求。每种插件类型都有其特定的优势和使用场景，合理地选择可以帮助你更好地满足用户的需求并提供出色的聊天体验。 + +## 总结 + +通过这三种插件类型，LobeChat 为开发者提供了灵活的插件开发选择，从而可以创建从简单展示到复杂交互都能涵盖的聊天体验。作为开发者，你可以根据自身需求和场景，选择最合适的插件类型进行开发，以提高用户的互动性和满意度。 diff --git a/docs/guides/submit-market.zh-CN.md b/docs/guides/submit-market.zh-CN.md index 0f30841..6738687 100644 --- a/docs/guides/submit-market.zh-CN.md +++ b/docs/guides/submit-market.zh-CN.md @@ -2,7 +2,7 @@ title: 上架插件市场 group: title: 插件发布 - order: 2 + order: 20 --- ## 上架插件市场 From 65212fbe3d8daf0b4da3c3760e5a014ad2a5f2d9 Mon Sep 17 00:00:00 2001 From: arvinxx Date: Sat, 30 Dec 2023 00:02:18 +0800 Subject: [PATCH 3/9] :memo: docs: update plugin docs --- docs/guides/client-sdk.zh-CN.md | 7 ++ docs/guides/communication-mechanisms.zh-CN.md | 7 ++ docs/guides/default-plugin.zh-CN.md | 19 ++++++ docs/guides/js-server.zh-CN.md | 7 ++ docs/guides/markdown-plugin.zh-CN.md | 13 ++++ docs/guides/openapi-schema.zh-CN.md | 7 ++ docs/guides/openapi.zh-CN.md | 7 ++ docs/guides/plugin-fontend.zh-CN.md | 9 +++ docs/guides/plugin-invoke.zh-CN.md | 4 +- docs/guides/plugin-manifest.zh-CN.md | 3 + docs/guides/plugin-server.zh-CN.md | 66 ++----------------- docs/guides/python-server.zh-CN.md | 7 ++ docs/guides/server-auth.zh-CN.md | 7 ++ docs/guides/server-gateway.zh-CN.md | 7 ++ docs/guides/standalone-plugin.zh-CN.md | 15 +++++ .../define-plugin-manifest.md | 0 .../define-plugin-manifest.zh-CN.md | 0 docs/{guides => quick-start}/get-start.md | 0 .../get-start.zh-CN.md | 5 +- docs/{guides => quick-start}/intro.md | 0 docs/{guides => quick-start}/intro.zh-CN.md | 2 +- docs/{guides => quick-start}/plugin-server.md | 0 docs/quick-start/plugin-server.zh-CN.md | 64 ++++++++++++++++++ .../plugin-settings.md | 0 .../plugin-settings.zh-CN.md | 0 docs/{guides => quick-start}/plugin-ui.md | 0 .../plugin-ui.zh-CN.md | 0 docs/{guides => quick-start}/submit-market.md | 0 .../submit-market.zh-CN.md | 0 docs/{guides => quick-start}/template.md | 0 .../{guides => quick-start}/template.zh-CN.md | 1 + 31 files changed, 191 insertions(+), 66 deletions(-) create mode 100644 docs/guides/client-sdk.zh-CN.md create mode 100644 docs/guides/communication-mechanisms.zh-CN.md create mode 100644 docs/guides/default-plugin.zh-CN.md create mode 100644 docs/guides/js-server.zh-CN.md create mode 100644 docs/guides/markdown-plugin.zh-CN.md create mode 100644 docs/guides/openapi-schema.zh-CN.md create mode 100644 docs/guides/openapi.zh-CN.md create mode 100644 docs/guides/plugin-fontend.zh-CN.md create mode 100644 docs/guides/python-server.zh-CN.md create mode 100644 docs/guides/server-auth.zh-CN.md create mode 100644 docs/guides/server-gateway.zh-CN.md create mode 100644 docs/guides/standalone-plugin.zh-CN.md rename docs/{guides => quick-start}/define-plugin-manifest.md (100%) rename docs/{guides => quick-start}/define-plugin-manifest.zh-CN.md (100%) rename docs/{guides => quick-start}/get-start.md (100%) rename docs/{guides => quick-start}/get-start.zh-CN.md (98%) rename docs/{guides => quick-start}/intro.md (100%) rename docs/{guides => quick-start}/intro.zh-CN.md (99%) rename docs/{guides => quick-start}/plugin-server.md (100%) create mode 100644 docs/quick-start/plugin-server.zh-CN.md rename docs/{guides => quick-start}/plugin-settings.md (100%) rename docs/{guides => quick-start}/plugin-settings.zh-CN.md (100%) 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 (100%) rename docs/{guides => quick-start}/submit-market.zh-CN.md (100%) rename docs/{guides => quick-start}/template.md (100%) rename docs/{guides => quick-start}/template.zh-CN.md (99%) diff --git a/docs/guides/client-sdk.zh-CN.md b/docs/guides/client-sdk.zh-CN.md new file mode 100644 index 0000000..f5b9aa7 --- /dev/null +++ b/docs/guides/client-sdk.zh-CN.md @@ -0,0 +1,7 @@ +--- +title: 客户端 SDK +group: 插件前端 +order: 2 +--- + +# 客户端 SDK diff --git a/docs/guides/communication-mechanisms.zh-CN.md b/docs/guides/communication-mechanisms.zh-CN.md new file mode 100644 index 0000000..6c25c7d --- /dev/null +++ b/docs/guides/communication-mechanisms.zh-CN.md @@ -0,0 +1,7 @@ +--- +title: 插件通信机制 +group: 基本概念 +order: 3 +--- + +# OpenAPI diff --git a/docs/guides/default-plugin.zh-CN.md b/docs/guides/default-plugin.zh-CN.md new file mode 100644 index 0000000..98bcfbb --- /dev/null +++ b/docs/guides/default-plugin.zh-CN.md @@ -0,0 +1,19 @@ +--- +title: 默认类型插件 +group: 插件类型 +order: 0 +--- + +# Default 类型插件 + +`default` 插件是默认的插件类型，它们主要用于纯后端驱动插件与展示型的插件，没有编辑、删除等富交互能力。它们适用于不需要复杂用户交互，且主要依赖 GPT 进行内容总结的场景。 + +例如官方实现的网站爬虫插件： + +![web-crawler](https://github.com/lobehub/lobe-chat/assets/28616219/8a7191af-da07-4419-a0a1-37792b5c0c51) + +搜索引擎插件： + +![search-engine](https://github.com/lobehub/lobe-chat/assets/28616219/573a905f-6df4-476b-8e1e-6c3098808ef8) + +以及所有兼容的 OpenAI ChatGPT 插件均为 `default` 类型。 diff --git a/docs/guides/js-server.zh-CN.md b/docs/guides/js-server.zh-CN.md new file mode 100644 index 0000000..9b322e7 --- /dev/null +++ b/docs/guides/js-server.zh-CN.md @@ -0,0 +1,7 @@ +--- +title: JavaScript 服务端 +group: 插件服务端 +order: 6 +--- + +# OpenAPI diff --git a/docs/guides/markdown-plugin.zh-CN.md b/docs/guides/markdown-plugin.zh-CN.md new file mode 100644 index 0000000..ff5cbfc --- /dev/null +++ b/docs/guides/markdown-plugin.zh-CN.md @@ -0,0 +1,13 @@ +--- +title: Markdown 类型插件 +group: + title: 插件类型 + order: 1 +order: 2 +--- + +# Markdown 类型插件 + +`Markdown` 插件类型允许插件返回 Markdown 格式的内容直接显示在聊天中。这种渲染方式适用于结果明确，不需要再次发送给 AI 进行处理的场景。例如，当用户询问某个特定信息时，插件可以直接返回一个包含答案的 Markdown 消息，而不需要额外的 AI 总结过程。此外，与这种类型搭配的配置可以设置为不再触发 AI 消息，这样就可以避免不必要的 AI 调用。 + +![clothes](https://github.com/lobehub/lobe-chat/assets/28616219/7077a4d4-5b0f-4d4e-b332-d79b7df2b411) diff --git a/docs/guides/openapi-schema.zh-CN.md b/docs/guides/openapi-schema.zh-CN.md new file mode 100644 index 0000000..283b3d7 --- /dev/null +++ b/docs/guides/openapi-schema.zh-CN.md @@ -0,0 +1,7 @@ +--- +title: OpenAPI Schema +group: 插件服务端 +order: 4 +--- + +# OpenAPI Schema diff --git a/docs/guides/openapi.zh-CN.md b/docs/guides/openapi.zh-CN.md new file mode 100644 index 0000000..811f2bb --- /dev/null +++ b/docs/guides/openapi.zh-CN.md @@ -0,0 +1,7 @@ +--- +title: OpenAPI +group: 基本概念 +order: 4 +--- + +# OpenAPI diff --git a/docs/guides/plugin-fontend.zh-CN.md b/docs/guides/plugin-fontend.zh-CN.md new file mode 100644 index 0000000..5104811 --- /dev/null +++ b/docs/guides/plugin-fontend.zh-CN.md @@ -0,0 +1,9 @@ +--- +title: 前端实现概述 +group: + title: 插件前端 + order: 4 +order: 0 +--- + +# OpenAPI diff --git a/docs/guides/plugin-invoke.zh-CN.md b/docs/guides/plugin-invoke.zh-CN.md index 85a71ee..6a2023e 100644 --- a/docs/guides/plugin-invoke.zh-CN.md +++ b/docs/guides/plugin-invoke.zh-CN.md @@ -5,9 +5,9 @@ group: 基本概念 order: 3 --- -# LobeChat 插件触发流程 +# LobeChat 插件触发机制 -LobeChat 插件系统通过 [Function Call 机制](https://sspai.com/post/81986)来触发插件，使得聊天机器人能够与外部 API 进行互动，以增强用户体验。以下是插件触发流程的详细说明。 +LobeChat 插件系统通过 [Function Call 机制](https://sspai.com/post/81986) 来触发插件，使得聊天机器人能够与外部 API 进行互动，以增强用户体验。以下是插件触发流程的详细说明。 ## Function Call 基本原理 diff --git a/docs/guides/plugin-manifest.zh-CN.md b/docs/guides/plugin-manifest.zh-CN.md index 7a82fd1..1a54575 100644 --- a/docs/guides/plugin-manifest.zh-CN.md +++ b/docs/guides/plugin-manifest.zh-CN.md @@ -2,6 +2,9 @@ title: 插件 Manifest group: title: 基本概念 + order: 0 +nav: + title: 完全指南 order: 1 order: 1 --- diff --git a/docs/guides/plugin-server.zh-CN.md b/docs/guides/plugin-server.zh-CN.md index 8934e39..2d50579 100644 --- a/docs/guides/plugin-server.zh-CN.md +++ b/docs/guides/plugin-server.zh-CN.md @@ -1,64 +1,8 @@ --- -title: 服务端开发 -group: 插件开发 -order: 1 +title: 服务端实现概述 +group: + title: 插件服务端 + order: 3 --- -# 插件的服务端开发 - -服务端只需要实现 manifest 中描述的 api 接口即可。在模板中，我们使用了 vercel 的 [Edge Runtime](https://nextjs.org/docs/pages/api-reference/edge) 作为服务，免去运维成本。 - -## api 实现 - -针对 Edge Runtime ，我们在 `@lobehub/chat-plugin-sdk` 提供了 `createErrorResponse` 方法，用于快速返回错误响应。目前提供的错误类型详见：[PluginErrorType](/api/error)。 - -模板中的 clothes 接口实现如下： - -```ts -export default async (req: Request) => { - if (req.method !== 'POST') return createErrorResponse(PluginErrorType.MethodNotAllowed); - - const { gender, mood } = (await req.json()) as RequestData; - - const clothes = gender === 'man' ? manClothes : womanClothes; - - const result: ResponseData = { - clothes: clothes[mood] || [], - mood, - today: Date.now(), - }; - - return new Response(JSON.stringify(result)); -}; -``` - -其中 `maniClothes` 和 `womanClothes` 是写死的 mock 数据，在实际场景中，可以替换为数据库请求。 - -## gateway - -由于 LobeChat 默认的插件网关是云端服务（），云端服务通过 manifest 上的 api 地址发送请求，以解决跨域问题。 - -而针对自定义插件，插件的请求需要发送给本地服务的， 因此通过在 manifest 中指定网关 ()，LobeChat 将会直接请求该地址，然后只需要在该地址下创建一个网关实现即可。 - -```ts -import { createLobeChatPluginGateway } from '@lobehub/chat-plugins-gateway'; - -export const config = { - runtime: 'edge', -}; - -export default async createLobeChatPluginGateway(); -``` - -[`@lobehub/chat-plugins-gateway`](https://github.com/lobehub/chat-plugins-gateway) 包含了 LobeChat 中插件网关的[实现](https://github.com/lobehub/lobe-chat/blob/main/src/pages/api/plugins.api.ts)，你可以直接使用该包创建网关，进而让 LobeChat 访问到本地的插件服务。 - -## 其他服务端实现示例 - -由于插件的服务端侧支持任意框架、任意语言的实现，在这里提供一些实现示例以供参考： - -- Vercel Node.Js 运行时服务端实现：[chat-plugin-web-crawler](https://github.com/lobehub/chat-plugin-web-crawler/blob/main/api/v1/index.ts) -- 欢迎贡献 - -## 支持 OpenAPI Manifest - -除了使用 api 字段定义插件的服务端以外，我们还计划支持 OpenAPI 规范来描述插件的功能，这样可以更方便的使用已有的 OpenAPI 工具来形成插件服务。该能力将在[lobehub/chat-plugin-sdk#13](https://github.com/lobehub/chat-plugin-sdk/issues/13) 中跟进。 +# OpenAPI diff --git a/docs/guides/python-server.zh-CN.md b/docs/guides/python-server.zh-CN.md new file mode 100644 index 0000000..031ff2d --- /dev/null +++ b/docs/guides/python-server.zh-CN.md @@ -0,0 +1,7 @@ +--- +title: Python 服务端 +group: 插件服务端 +order: 5 +--- + +# OpenAPI diff --git a/docs/guides/server-auth.zh-CN.md b/docs/guides/server-auth.zh-CN.md new file mode 100644 index 0000000..6c4c5c1 --- /dev/null +++ b/docs/guides/server-auth.zh-CN.md @@ -0,0 +1,7 @@ +--- +title: 服务端鉴权 +group: 插件服务端 +order: 5 +--- + +# OpenAPI diff --git a/docs/guides/server-gateway.zh-CN.md b/docs/guides/server-gateway.zh-CN.md new file mode 100644 index 0000000..3fb5594 --- /dev/null +++ b/docs/guides/server-gateway.zh-CN.md @@ -0,0 +1,7 @@ +--- +title: 插件网关 +group: 插件服务端 +order: 4 +--- + +# OpenAPI diff --git a/docs/guides/standalone-plugin.zh-CN.md b/docs/guides/standalone-plugin.zh-CN.md new file mode 100644 index 0000000..b526b81 --- /dev/null +++ b/docs/guides/standalone-plugin.zh-CN.md @@ -0,0 +1,15 @@ +--- +title: Standalone 类型插件 +group: 插件类型 +order: 2 +--- + +# Standalone 插件 + +`standalone` 插件类型是为了支持复杂交互而设计的。这类插件可以完全控制交互逻辑，并且以独立的应用的形态运行。它们适合于需要丰富用户交互的场景，例如表单填写、游戏或其他需要多步骤操作的应用。`standalone` 插件可以通过自行控制来决定是否触发 AI 消息，甚至可以通过程序化的方式来触发 AI 回复。 + +`standalone` 类型的插件正是 LobeChat 与 ChatGPT 插件系统的最大差别，正因为该类插件的存在，我们才能够通过插件实现更加复杂的会话交互体验。 + +例如：官方实现的时钟插件就是标准的 Standalone 插件，该插件的特点是不包含任何后端 API，由纯前端实现。 + + diff --git a/docs/guides/define-plugin-manifest.md b/docs/quick-start/define-plugin-manifest.md similarity index 100% rename from docs/guides/define-plugin-manifest.md rename to docs/quick-start/define-plugin-manifest.md diff --git a/docs/guides/define-plugin-manifest.zh-CN.md b/docs/quick-start/define-plugin-manifest.zh-CN.md similarity index 100% rename from docs/guides/define-plugin-manifest.zh-CN.md rename to docs/quick-start/define-plugin-manifest.zh-CN.md diff --git a/docs/guides/get-start.md b/docs/quick-start/get-start.md similarity index 100% rename from docs/guides/get-start.md rename to docs/quick-start/get-start.md diff --git a/docs/guides/get-start.zh-CN.md b/docs/quick-start/get-start.zh-CN.md similarity index 98% rename from docs/guides/get-start.zh-CN.md rename to docs/quick-start/get-start.zh-CN.md index ece2160..0098dca 100644 --- a/docs/guides/get-start.zh-CN.md +++ b/docs/quick-start/get-start.zh-CN.md @@ -1,9 +1,10 @@ --- -title: 快速上手 +title: 3 分钟上手 group: 快速上手 +order: 1 --- -# 快速上手 +# 3 分钟快速上手 本篇将会介绍如何在 LobeChat 中快速添加和使用一个自定义插件。 diff --git a/docs/guides/intro.md b/docs/quick-start/intro.md similarity index 100% rename from docs/guides/intro.md rename to docs/quick-start/intro.md diff --git a/docs/guides/intro.zh-CN.md b/docs/quick-start/intro.zh-CN.md similarity index 99% rename from docs/guides/intro.zh-CN.md rename to docs/quick-start/intro.zh-CN.md index a06026b..2f86d37 100644 --- a/docs/guides/intro.zh-CN.md +++ b/docs/quick-start/intro.zh-CN.md @@ -4,7 +4,7 @@ group: title: 快速上手 order: 0 nav: - title: 指南 + title: 快速上手 order: 1 --- diff --git a/docs/guides/plugin-server.md b/docs/quick-start/plugin-server.md similarity index 100% rename from docs/guides/plugin-server.md rename to docs/quick-start/plugin-server.md diff --git a/docs/quick-start/plugin-server.zh-CN.md b/docs/quick-start/plugin-server.zh-CN.md new file mode 100644 index 0000000..8934e39 --- /dev/null +++ b/docs/quick-start/plugin-server.zh-CN.md @@ -0,0 +1,64 @@ +--- +title: 服务端开发 +group: 插件开发 +order: 1 +--- + +# 插件的服务端开发 + +服务端只需要实现 manifest 中描述的 api 接口即可。在模板中，我们使用了 vercel 的 [Edge Runtime](https://nextjs.org/docs/pages/api-reference/edge) 作为服务，免去运维成本。 + +## api 实现 + +针对 Edge Runtime ，我们在 `@lobehub/chat-plugin-sdk` 提供了 `createErrorResponse` 方法，用于快速返回错误响应。目前提供的错误类型详见：[PluginErrorType](/api/error)。 + +模板中的 clothes 接口实现如下： + +```ts +export default async (req: Request) => { + if (req.method !== 'POST') return createErrorResponse(PluginErrorType.MethodNotAllowed); + + const { gender, mood } = (await req.json()) as RequestData; + + const clothes = gender === 'man' ? manClothes : womanClothes; + + const result: ResponseData = { + clothes: clothes[mood] || [], + mood, + today: Date.now(), + }; + + return new Response(JSON.stringify(result)); +}; +``` + +其中 `maniClothes` 和 `womanClothes` 是写死的 mock 数据，在实际场景中，可以替换为数据库请求。 + +## gateway + +由于 LobeChat 默认的插件网关是云端服务（），云端服务通过 manifest 上的 api 地址发送请求，以解决跨域问题。 + +而针对自定义插件，插件的请求需要发送给本地服务的， 因此通过在 manifest 中指定网关 ()，LobeChat 将会直接请求该地址，然后只需要在该地址下创建一个网关实现即可。 + +```ts +import { createLobeChatPluginGateway } from '@lobehub/chat-plugins-gateway'; + +export const config = { + runtime: 'edge', +}; + +export default async createLobeChatPluginGateway(); +``` + +[`@lobehub/chat-plugins-gateway`](https://github.com/lobehub/chat-plugins-gateway) 包含了 LobeChat 中插件网关的[实现](https://github.com/lobehub/lobe-chat/blob/main/src/pages/api/plugins.api.ts)，你可以直接使用该包创建网关，进而让 LobeChat 访问到本地的插件服务。 + +## 其他服务端实现示例 + +由于插件的服务端侧支持任意框架、任意语言的实现，在这里提供一些实现示例以供参考： + +- Vercel Node.Js 运行时服务端实现：[chat-plugin-web-crawler](https://github.com/lobehub/chat-plugin-web-crawler/blob/main/api/v1/index.ts) +- 欢迎贡献 + +## 支持 OpenAPI Manifest + +除了使用 api 字段定义插件的服务端以外，我们还计划支持 OpenAPI 规范来描述插件的功能，这样可以更方便的使用已有的 OpenAPI 工具来形成插件服务。该能力将在[lobehub/chat-plugin-sdk#13](https://github.com/lobehub/chat-plugin-sdk/issues/13) 中跟进。 diff --git a/docs/guides/plugin-settings.md b/docs/quick-start/plugin-settings.md similarity index 100% rename from docs/guides/plugin-settings.md rename to docs/quick-start/plugin-settings.md diff --git a/docs/guides/plugin-settings.zh-CN.md b/docs/quick-start/plugin-settings.zh-CN.md similarity index 100% rename from docs/guides/plugin-settings.zh-CN.md rename to docs/quick-start/plugin-settings.zh-CN.md diff --git a/docs/guides/plugin-ui.md b/docs/quick-start/plugin-ui.md similarity index 100% rename from docs/guides/plugin-ui.md rename to docs/quick-start/plugin-ui.md diff --git a/docs/guides/plugin-ui.zh-CN.md b/docs/quick-start/plugin-ui.zh-CN.md similarity index 100% rename from docs/guides/plugin-ui.zh-CN.md rename to docs/quick-start/plugin-ui.zh-CN.md diff --git a/docs/guides/submit-market.md b/docs/quick-start/submit-market.md similarity index 100% rename from docs/guides/submit-market.md rename to docs/quick-start/submit-market.md diff --git a/docs/guides/submit-market.zh-CN.md b/docs/quick-start/submit-market.zh-CN.md similarity index 100% rename from docs/guides/submit-market.zh-CN.md rename to docs/quick-start/submit-market.zh-CN.md diff --git a/docs/guides/template.md b/docs/quick-start/template.md similarity index 100% rename from docs/guides/template.md rename to docs/quick-start/template.md diff --git a/docs/guides/template.zh-CN.md b/docs/quick-start/template.zh-CN.md similarity index 99% rename from docs/guides/template.zh-CN.md rename to docs/quick-start/template.zh-CN.md index 534c45d..c97ad33 100644 --- a/docs/guides/template.zh-CN.md +++ b/docs/quick-start/template.zh-CN.md @@ -1,6 +1,7 @@ --- title: 研发模板 group: 快速上手 +order: 10 --- # 研发模板 From 99f0afbf3c4dcf69a5923a83944d71caf6e2abf7 Mon Sep 17 00:00:00 2001 From: arvinxx Date: Sat, 30 Dec 2023 00:07:14 +0800 Subject: [PATCH 4/9] :memo: docs: update plugin docs --- docs/guides/communication-mechanisms.zh-CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/communication-mechanisms.zh-CN.md b/docs/guides/communication-mechanisms.zh-CN.md index 6c25c7d..024a4d6 100644 --- a/docs/guides/communication-mechanisms.zh-CN.md +++ b/docs/guides/communication-mechanisms.zh-CN.md @@ -4,4 +4,4 @@ group: 基本概念 order: 3 --- -# OpenAPI +# 插件通信机制 From 1495501492494b6dcb9f79cff21e450e903a0710 Mon Sep 17 00:00:00 2001 From: arvinxx Date: Sat, 30 Dec 2023 15:20:27 +0800 Subject: [PATCH 5/9] :memo: docs: update plugin docs --- docs/api/channel.zh-CN.md | 2 + ...get-plugin-settings-from-request.zh-CN.md} | 3 +- docs/api/lobe-chat-client.zh-CN.md | 1 - ...or.zh-CN.md => plugin-error-type.zh-CN.md} | 6 ++- docs/api/plugin-manifest.zh-CN.md | 3 +- docs/api/plugin-meta-index.zh-CN.md | 3 +- docs/guides/communication-mechanisms.zh-CN.md | 50 ++++++++++++++++++- docs/guides/default-plugin.zh-CN.md | 12 +++++ docs/guides/markdown-plugin.zh-CN.md | 11 ++++ docs/guides/openapi.zh-CN.md | 33 ++++++++++++ docs/guides/plugin-invoke.zh-CN.md | 7 +-- docs/guides/plugin-type.zh-CN.md | 2 +- docs/guides/standalone-plugin.zh-CN.md | 13 +++++ 13 files changed, 132 insertions(+), 14 deletions(-) rename docs/api/{request.zh-CN.md => get-plugin-settings-from-request.zh-CN.md} (95%) rename docs/api/{error.zh-CN.md => plugin-error-type.zh-CN.md} (94%) diff --git a/docs/api/channel.zh-CN.md b/docs/api/channel.zh-CN.md index c9deb16..0ef335f 100644 --- 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 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/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..06e7ccd 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.zh-CN.md b/docs/api/plugin-meta-index.zh-CN.md index 6424667..78af917 100644 --- 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 index 024a4d6..07957ef 100644 --- 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 的主体可以与嵌入其中的插件（通常是通过`