Skip to content

Commit b47e60f

Browse files
arvinxxarvinxx
committed
📝 docs: 补充 api 文档
1 parent b780d0f commit b47e60f

11 files changed

Lines changed: 479 additions & 3 deletions

‎.dumirc.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import { defineConfig } from 'dumi';
2+
3+
import { homepage } from './package.json';
4+
5+
const themeConfig = {
6+
actions: [
7+
{
8+
link: homepage,
9+
openExternal: true,
10+
text: 'Github',
11+
},
12+
{
13+
link: '/components/action-icon',
14+
text: 'Get Started',
15+
type: 'primary',
16+
},
17+
],
18+
footer: 'Made with 🤯 by LobeHub',
19+
name: 'Lobe Chat Plugin SDK',
20+
socialLinks: {
21+
discord: 'https://discord.gg/AYFPHvv2jT',
22+
github: homepage,
23+
},
24+
};
25+
26+
export default defineConfig({
27+
extraBabelPlugins: ['babel-plugin-antd-style'],
28+
favicons: [
29+
'https://registry.npmmirror.com/@lobehub/assets-emoji/1.3.0/files/assets/puzzle-piece.webp',
30+
],
31+
// locales: [{ id: 'en-US', name: 'English' }],
32+
mfsu: {},
33+
npmClient: 'pnpm',
34+
outputPath: 'docs-dist',
35+
// ssr: isProduction ? {} : false,
36+
styles: [
37+
`html, body { background: transparent; }
38+
39+
@media (prefers-color-scheme: dark) {
40+
html, body { background: #000; }
41+
}`,
42+
],
43+
themeConfig,
44+
title: 'Lobe Chat Plugin SDK',
45+
});

‎docs/api/channel.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: 消息通信类型
3+
order: 10
4+
group: 前端渲染
5+
atomId: PluginChannel
6+
description: 提供了关于插件通信的消息类型的详细说明
7+
nav:
8+
title: API
9+
order: 1
10+
---
11+
12+
# PluginChannel 通信消息
13+
14+
一般来说你可能用不到 `PluginChannel` ，但如果你希望使用 LobeChat 底层的消息通信机制，你可能需要了解这些消息类型。 本文档包含了通信消息类型的详细说明。
15+
16+
## fetchPluginMessage
17+
18+
- 字面量：`'lobe-chat:fetch-plugin-message`
19+
20+
用于插件主动向 LobeChat 发起消息请求的通道
21+
22+
```ts
23+
import { PluginChannel } from '@lobehub/chat-plugin-sdk';
24+
25+
const channel = PluginChannel.fetchPluginMessage;
26+
```
27+
28+
## pluginReadyForRender
29+
30+
- 字面量：`lobe-chat:plugin-ready-for-render`
31+
32+
用于通知 LobeChat 主体，插件已准备好进行渲染的通道
33+
34+
```ts
35+
import { PluginChannel } from '@lobehub/chat-plugin-sdk';
36+
37+
const channel = PluginChannel.pluginReadyForRender;
38+
```
39+
40+
:::info
41+
主程序将会在收到此消息后，通过 `renderPlugin` 通道发送插件的信息
42+
:::
43+
44+
## renderPlugin
45+
46+
- 字面量：`'lobe-chat:render-plugin`
47+
48+
用于主程序向插件发送渲染指令的通道。
49+
50+
```ts
51+
import { PluginChannel } from '@lobehub/chat-plugin-sdk';
52+
53+
const channel = PluginChannel.pluginReadyForRender;
54+
```

‎docs/api/error.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: 服务端错误类型
3+
atomId: PluginErrorType
4+
description: 插件错误类型
5+
group: 服务端
6+
nav: API
7+
order: 100
8+
---
9+
10+
LobeChat 在插件服务请求中所有的错误类型，包括业务语义错误、客户端错误和服务端错误。
11+
12+
## 使用方式
13+
14+
搭配 `createErrorResponse` 使用：
15+
16+
```ts
17+
import { PluginErrorType } from '@lobehub/chat-plugin-sdk';
18+
19+
export default async (req: Request) => {
20+
if (req.method !== 'POST') return createErrorResponse(PluginErrorType.MethodNotAllowed);
21+
22+
// ...
23+
};
24+
```
25+
26+
## 错误类型明细
27+
28+
### 业务错误
29+
30+
| 错误类型 | 描述 |
31+
| --------------------------- | ----------------------- |
32+
| `PluginMarketIndexNotFound` | 插件市场索引解析失败 |
33+
| `PluginMarketIndexInvalid` | 插件市场索引无效 |
34+
| `PluginMetaNotFound` | 没有找到插件元数据 |
35+
| `PluginMetaInvalid` | 插件元数据无效 |
36+
| `PluginManifestNotFound` | 插件描述文件不存在 |
37+
| `PluginManifestInvalid` | 插件描述文件格式不正确 |
38+
| `PluginSettingsInvalid` | 插件设置不正确 |
39+
| `PluginApiNotFound` | 插件 API 不存在 |
40+
| `PluginApiParamsError` | 插件 API 请求入参有问题 |
41+
| `PluginServerError` | 插件服务端出错 |
42+
43+
### 客户端错误
44+
45+
| 错误类型 | 描述 |
46+
| ------------------ | ---------------------- |
47+
| `BadRequest` | 400 Bad Request |
48+
| `Unauthorized` | 401 Unauthorized |
49+
| `Forbidden` | 403 Forbidden |
50+
| `ContentNotFound` | 404 Not Found |
51+
| `MethodNotAllowed` | 405 Method Not Allowed |
52+
| `TooManyRequests` | 429 Too Many Requests |
53+
54+
### 服务端错误
55+
56+
| 错误类型 | 描述 |
57+
| --------------------- | ------------------------- |
58+
| `InternalServerError` | 500 Internal Server Error |
59+
| `BadGateway` | 502 Bad Gateway |
60+
| `ServiceUnavailable` | 503 Service Unavailable |
61+
| `GatewayTimeout` | 504 Gateway Timeout |

‎docs/api/message.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: fetchPluginMessage
3+
description: 该方法用于从插件通道获取插件消息
4+
group:
5+
title: 前端渲染
6+
order: 10
7+
nav: API
8+
---
9+
10+
该方法用于从插件通道获取插件消息。
11+
12+
## 类型
13+
14+
```ts
15+
export const fetchPluginMessage = <T = any>() => Promise<T>;
16+
```
17+
18+
## 返回值
19+
20+
一个 Promise，返回插件消息的内容。
21+
22+
### 示例
23+
24+
```ts
25+
import { fetchPluginMessage } from '@lobehub/chat-plugin-sdk';
26+
27+
fetchPluginMessage()
28+
.then((message) => {
29+
console.log(message);
30+
})
31+
.catch((error) => {
32+
console.error(error);
33+
});
34+
```
35+
36+
## 注意事项
37+
38+
- 该函数使用了浏览器的 `postMessage` 和 `addEventListener` 方法，因此需要在浏览器环境中使用；
39+
- 该函数通过插件通道向父窗口发送消息，因此调用该方法的应用必须嵌入在 LobeChat 中才能返回正确的消息；

‎docs/api/plugin-manifest.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
title: 插件描述清单 Schema
3+
group: Schema
4+
atomId: pluginManifestSchema
5+
description: 插件描述文件的 Schema
6+
nav: API
7+
---
8+
9+
## pluginManifestSchema
10+
11+
**描述**：插件的清单文件（Manifest）数据模式定义。
12+
13+
### 使用示例
14+
15+
```typescript
16+
import { pluginManifestSchema } from '@lobehub/chat-plugin-sdk';
17+
18+
const manifestData = {
19+
api: [
20+
{
21+
description: 'API 描述',
22+
name: 'API 名称',
23+
parameters: {
24+
properties: {},
25+
type: 'object',
26+
},
27+
url: 'http://example.com/api',
28+
},
29+
],
30+
gateway: 'http://example.com/gateway',
31+
identifier: 'plugin-identifier',
32+
openapi: 'http://example.com/openapi',
33+
settings: {
34+
properties: {},
35+
type: 'object',
36+
},
37+
ui: {
38+
height: 500,
39+
mode: 'iframe',
40+
url: 'http://example.com/plugin',
41+
width: 800,
42+
},
43+
};
44+
45+
const result = pluginManifestSchema.parse(manifestData);
46+
47+
console.log(result);
48+
49+
// 输出：{ api: [ { description: 'API 描述', name: 'API 名称', parameters: { properties: {}, type: 'object' }, url: 'http://example.com/api' } ], gateway: 'http://example.com/gateway', identifier: 'plugin-identifier', openapi: 'http://example.com/openapi', settings: { properties: {}, type: 'object' }, ui: { height: 500, mode: 'iframe', url: 'http://example.com/plugin', width: 800 } }
50+
```
51+
52+
## `pluginApiSchema`
53+
54+
**描述**：插件 API 的数据模式定义。
55+
56+
```typescript
57+
import { z } from 'zod';
58+
59+
const JSONSchema = z.object({
60+
properties: z.object({}),
61+
type: z.enum(['object']),
62+
});
63+
64+
const pluginApiSchema = z.object({
65+
description: z.string(),
66+
name: z.string(),
67+
parameters: JSONSchema,
68+
url: z.string().url(),
69+
});
70+
71+
export default pluginApiSchema;
72+
```
73+
74+
### 使用示例
75+
76+
```typescript
77+
import { pluginApiSchema } from '@lobehub/chat-plugin-sdk';
78+
79+
const apiData = {
80+
description: 'API 描述',
81+
name: 'API 名称',
82+
parameters: {
83+
properties: {},
84+
type: 'object',
85+
},
86+
url: 'http://example.com/api',
87+
};
88+
89+
const result = pluginApiSchema.parse(apiData);
90+
console.log(result);
91+
// 输出：{ description: 'API 描述', name: 'API 名称', parameters: { properties: {}, type: 'object' }, url: 'http://example.com/api' }
92+
```
93+
94+
## Schema 定义
95+
96+
### pluginManifestSchema
97+
98+
| 属性 | 类型 | 描述 |
99+
| ------------ | ------------------- | ----------------------- |
100+
| `api` | `pluginApiSchema[]` | 插件的 API 列表 |
101+
| `gateway` | `string` (可选) | 插件的网关 URL |
102+
| `identifier` | `string` | 插件的标识符 |
103+
| `openapi` | `string` (可选) | 插件的 OpenAPI 文档 URL |
104+
| `settings` | `JSONSchema` (可选) | 插件的设置数据定义 |
105+
| `ui` | `object` (可选) | 插件的 UI 配置 |
106+
| `ui.height` | `number` (可选) | 插件 UI 的高度 |
107+
| `ui.mode` | `'iframe'` (可选) | 插件 UI 的模式 |
108+
| `ui.url` | `string` | 插件 UI 的 URL |
109+
| `ui.width` | `number` (可选) | 插件 UI 的宽度 |
110+
111+
### pluginApiSchema
112+
113+
| 属性 | 类型 | 描述 |
114+
| ------------- | ------------ | ------------------- |
115+
| `description` | `string` | 插件 API 的描述 |
116+
| `name` | `string` | 插件 API 的名称 |
117+
| `parameters` | `JSONSchema` | 插件 API 的参数定义 |
118+
| `url` | `string` | 插件 API 的 URL |

‎docs/api/plugin-meta-index.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: 插件市场元数据 Schema
3+
group: Schema
4+
atomId: pluginMetaSchema
5+
description: 上架到插件市场中的插件元数据的数据模式定义。
6+
nav: API
7+
---
8+
9+
插件元数据的 Schema。
10+
11+
### 使用示例
12+
13+
```typescript
14+
import { pluginMetaSchema } from '@lobehub/chat-plugin-sdk';
15+
16+
const meta = {
17+
author: 'John Doe',
18+
createAt: '2022-01-01',
19+
homepage: 'http://example.com',
20+
identifier: 'plugin-identifier',
21+
manifest: 'http://example.com/manifest',
22+
meta: {
23+
avatar: 'http://example.com/avatar.png',
24+
tags: ['tag1', 'tag2'],
25+
},
26+
schemaVersion: 1,
27+
};
28+
29+
const result = pluginMetaSchema.parse(meta);
30+
31+
console.log(result);
32+
33+
// 输出：{ author: 'John Doe', createAt: '2022-01-01', homepage: 'http://example.com', identifier: 'plugin-identifier', manifest: 'http://example.com/manifest', meta: { avatar: 'http://example.com/avatar.png', tags: ['tag1', 'tag2'] }, schemaVersion: 1 }
34+
```
35+
36+
### Schema 定义
37+
38+
| 属性 | 类型 | 描述 |
39+
| --------------- | ----------------- | -------------------------------- |
40+
| `author` | `string` | 插件的作者 |
41+
| `createAt` | `string` | 插件的创建日期 |
42+
| `homepage` | `string` | 插件的主页 URL |
43+
| `identifier` | `string` | 插件的标识符 |
44+
| `manifest` | `string` | 插件描述文件的 URL |
45+
| `meta` | `object` (可选) | 插件的元数据 |
46+
| `meta.avatar` | `string` (可选) | 插件作者的头像 URL |
47+
| `meta.tags` | `string[]` (可选) | 插件的标签列表 |
48+
| `schemaVersion` | `number` | 插件元数据的数据模式定义的版本号 |

0 commit comments

Comments
 (0)