docs: update plugin guide (#5345)

* docs: update plugin guide * update: docker compose * chore: update bussiness contact info
2025-10-14 07:00:47 +00:00 · 2025-07-30 22:30:03 +08:00
parent 6c37776de1
commit e0c21a949c
13 changed files with 170 additions and 200 deletions
--- a/document/README.md
+++ b/document/README.md
@@ -76,7 +76,7 @@ import FastGPTLink from '@/components/docs/linkFastGPT'; #FastGPT跳转链接组
 {
  "title": "FastGPT Docs",
  "root": true,
-  "pages": ["[Handshake][联系我们](https://fael3z0zfze.feishu.cn/share/base/form/shrcnRxj3utrzjywsom96Px4sud)","index","guide","development","FAQ","shopping_cart","community","hello"], #"hello"原本没有，此外，这里的顺序就是最后文档的展示顺序，现在"hello"文档将会在`introduction`的最后展示
+  "pages": ["[Handshake][联系我们](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc)","index","guide","development","FAQ","shopping_cart","community","hello"], #"hello"原本没有，此外，这里的顺序就是最后文档的展示顺序，现在"hello"文档将会在`introduction`的最后展示
  "order": 1
 }
 ```
@@ -87,8 +87,8 @@ import FastGPTLink from '@/components/docs/linkFastGPT'; #FastGPT跳转链接组

 # ps

-`meta.json`的`"pages"`中的`"[Handshake][联系我们](https://fael3z0zfze.feishu.cn/share/base/form/shrcnRxj3utrzjywsom96Px4sud)"`这个字段是目录的链接形式，表现效果为，点击后跳转到对应的url。
+`meta.json`的`"pages"`中的`"[Handshake][联系我们](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc)"`这个字段是目录的链接形式，表现效果为，点击后跳转到对应的url。

 ![](./public/readme/link.png)

-最后，如果依然有问题，可以进入`https://fumadocs.dev/docs/ui`官网，询问官网提供的ai来了解文档框架的使用。
+最后，如果依然有问题，可以进入`https://fumadocs.dev/docs/ui`官网，询问官网提供的ai来了解文档框架的使用。
--- a/document/content/docs/introduction/guide/plugins/dev_system_tool.mdx
+++ b/document/content/docs/introduction/guide/plugins/dev_system_tool.mdx
@@ -30,9 +30,9 @@ FastGPT 系统工具项目从 4.10.0 版本后移动到独立的`fastgpt-plugin`
 bun run new:tool
 ```

-依据提示分别选择创建工具/工具集，以及目录名（小驼峰命名）。
+依据提示分别选择创建工具/工具集，以及目录名（使用 camelCase 小驼峰法命名）。

-执行完后，系统会在 `packages/tool/packages/[your-tool-name]`下生成一个工具/工具集的目录。
+执行完后，系统会在 `modules/tool/packages/[your-tool-name]`下生成一个工具/工具集的目录。

 系统工具 (Tool) 文件结构如下:

@@ -61,23 +61,71 @@ package.json
 ### 2.2 修改 config.ts

 - **name** 和 **description** 字段为中文和英文两种语言
- **courseUrl** 密钥获取链接，或官网链接。
+- **courseUrl** 密钥获取链接，或官网链接，教程链接等。
 - **author** 开发者名
 - **type** 为枚举类型，目前有:
 	- tools: 工具
 	- search: 搜索
 	- multimodal: 多模态
 	- communication: 通讯
+	- finance: 金融
+	- design: 设计
+	- productivity: 生产力
+	- news: 新闻
+	- entertainment: 娱乐
+	- social: 社交
+	- scientific: 科学
 	- other: 其他
+- **secretInputList**: 密钥输入列表，其用于配置工具的`激活信息`,通常包含`密钥`、`Endpoint`、`Port`等。(见下面的 secretInputList 参数格式)
 - **versionList** (工具中配置)用于版本管理，是一个列表，其中的元素格式:
 	- value：版本号，建议使用 semver
 	- description: 描述
-	- inputs 入参
-	- outputs 返回值
- **children**：（工具集 toolset 配置），需要将 tool import 后手动写入。
+	- inputs 入参（见下面的 inputs 参数格式）
+	- outputs 返回值 (见下面的 outputs 参数格式)

 对于 ToolSet 下的 tool 来说，无需填写 `type`、`courseUrl`、`author`，这几个字段会继承 ToolSet 的配置。

+#### secretInputList 参数格式
+
+一般格式:
+```ts
+{
+  key: 'key', // 唯一键
+  label: '前端显示的 label',
+  description: '前端显示的 description', // 可选
+  inputType: 'input' | 'secret' | 'switch' | 'select' | 'numberInput', // 前端输入框的类型
+  // secret: 密钥输入框，密钥将在保存时进行对称加密保存在节点内或数据库中
+  // switch: 开关
+  // select: 下拉选择框
+  // numberInput: 数字输入框
+  // input: 普通输入框
+}
+```
+
+下面的例子是 dalle3 的相关配置：可以参考 [dalle3 的 config.ts](https://github.com/labring/fastgpt-plugin/blob/main/modules/tool/packages/dalle3/config.ts)
+
+```ts
+{
+  // 其他配置
+  secretInputConfig: [
+    {
+      key: 'url',
+      label: 'Dalle3 接口基础地址',
+      description: '例如：https://api.openai.com',
+      inputType: 'input',
+      required: true
+    },
+    {
+      key: 'authorization',
+      label: '接口凭证（不需要 Bearer）',
+      description: 'sk-xxxx',
+      required: true,
+      inputType: 'secret'
+    }
+  ]
+}
+```
+
 #### inputs 参数格式

 一般格式:
@@ -92,42 +140,30 @@ package.json
 }
 ```

-有一个特殊的 key `'system_input_config'`，其用于配置工具的`激活信息`,通常包含`密钥`、`Endpoint`、`Port`等。
-
-配置中`inputType=secret`的数据，将会通过对称加密的方式保存，以保证安全性。
-
-**参考 dalle3**:
-
-```
-"inputs": [
-  {
-    key: 'system_input_config', // 必须为这个值
-    label: '', // 为空即可
-    inputList: [
+dalle3 的 inputs 参数格式如下：
+```ts
+{
+//...
+  versionList: [
    {
-      key: 'url',
-      label: 'Dalle3 接口基础地址',
-      description: '例如：https://api.openai.com',
-      required: true,
-      inputType: 'input'
-    },
-    {
-      key: 'authorization',
-      label: '接口凭证（不需要 Bearer）',
-      description: 'sk-xxxx',
-      required: true,
-      inputType: 'secret'
+      // 其他配置
+      inputs: [
+        {
+          key: 'prompt',
+          label: '绘图提示词',
+          valueType: WorkflowIOValueTypeEnum.string,
+          renderTypeList: [FlowNodeInputTypeEnum.reference, FlowNodeInputTypeEnum.input],
+          toolDescription: '绘图提示词'
+        }
+      ],
    }
-    ],
-    renderTypeList: [FlowNodeInputTypeEnum.hidden], // 必须为这个值
-    valueType: WorkflowIOValueTypeEnum.object // 必须为这个值
-  },
-....
-]
+    // ...
+  ]
+}
 ```

 #### outputs 参数格式
-```
+```ts
 {
  key: 'link', // 唯一键值对
  valueType: WorkflowIOValueTypeEnum.string, // 具体可以看这个 Enum 的类型定义
@@ -136,6 +172,34 @@ package.json
 }
 ```

+dalle3 的 outputs 参数格式如下：
+
+
+```ts
+{
+  // ...
+  versionList: [
+    {
+      // ...
+      outputs: [
+        {
+          valueType: WorkflowIOValueTypeEnum.string,
+          key: 'link',
+          label: '图片访问链接',
+          description: '图片访问链接'
+        },
+        {
+          type: FlowNodeOutputTypeEnum.error,
+          valueType: WorkflowIOValueTypeEnum.string,
+          key: 'system_error',
+          label: '错误信息'
+        }
+      ]
+    }
+  ],
+}
+```
+
 ## 2. 编写处理逻辑

 在 `[your-tool-name]/src/index.ts` 为入口编写处理逻辑，需要注意：
@@ -164,7 +228,7 @@ export async function tool(props: z.infer<typeof InputType>): Promise<z.infer<ty
 }
 ```

-上述例子给出了一个传入 formatStr （格式化字符串）并且返回当前时间的简单样例，如需安装包，可以在`/packages/tools/packages/[your-tool-name]`路径下，使用`bun install PACKAGE` 进行安装。
+上述例子给出了一个传入 formatStr （格式化字符串）并且返回当前时间的简单样例，如需安装包，可以在`/modules/tools/packages/[your-tool-name]`路径下，使用`bun install PACKAGE` 进行安装。

 ## 3. 调试

@@ -172,13 +236,13 @@ export async function tool(props: z.infer<typeof InputType>): Promise<z.infer<ty

 在 `test/index.test.ts` 中编写测试样例，使用 `bun run test index.test.ts完整路径` 即可运行测试。

-### 从 OpenAPI 文件进行测试
+### 从 Scalar 进行测试

 浏览器打开`localhost:3000/openapi`可进入`fastgpt-plugin`的 OpenAPI 页面，进行 API 调试。

 ![](/imgs/plugin-openapi.png)

-可以先通过`/tool/list`接口，获取工具列表，找到需要调试的工具的`toolId`。紧接着，通过`/tool/run`来运行工具获取实际结果。
+可以先通过`/tool/list`接口，获取工具列表，找到需要调试的工具的`toolId`。紧接着，通过`/tool/runStream`来运行工具获取实际结果。

 ![](/imgs/plugin-openapi2.png)

@@ -193,4 +257,3 @@ export async function tool(props: z.infer<typeof InputType>): Promise<z.infer<ty
 完毕上述所有内容后，向官方仓库 `https://github.com/labring/fastgpt-plugin` 提交 PR。官方人员审核通过后即可收录为 FastGPT 的官方插件。

 如无需官方收录，可自行对该项目进行 Docker 打包，并替换官方镜像即可。
-
--- a/document/content/docs/introduction/guide/plugins/how_to_submit_system_plugin.mdx
+++ b/document/content/docs/introduction/guide/plugins/how_to_submit_system_plugin.mdx
@@ -1,114 +0,0 @@
---
-title: 如何提交系统插件
-description: FastGPT 系统插件提交指南
---
-
-> 如何向 FastGPT 社区提交系统插件
-
-## 系统插件原则
-
- 尽可能的轻量简洁，以解决实际问题的工具为主
- 不允许有密集 cpu 计算，不会占用大量内存占用或网络消耗
- 不允许操作数据库
- 不允许往固定的私人地址发送请求(不包含请求某些在线服务，例如 gapier, firecrawl等)
- 不允许使用私人包，可使用主流的开源包
-
-## 什么插件可以合并
-
-由于目前未采用按需安装的模式，合并进仓库的插件会全部展示给用户使用。
-
-为了控制插件的质量以及避免数量过多带来的繁琐，并不是所有的插件都会被合并到开源仓库中，你可以提前 PR 与我们沟通插件的内容。
-
-后续实现插件按需安装后，我们会允许更多的社区插件合入。
-
-## 如何写一个系统插件 - 初步
-
-FastGPT 系统插件和用户工作台的插件效果是一致的，所以你需要提前了解“插件”的定义和功能。
-
-在 FastGPT 中，插件是一种特殊的工作流，它允许你将一个工作流封装起来，并自定义入口参数和出口参数，类似于代码里的 “子函数”。
-
-1. ### 跑通 FastGPT dev 环境
-
-需要在 dev 环境下执行下面的操作。
-
-1. ### 在 FastGPT 工作台中，创建一个插件
-
-选择基础模板即可。
-
-![](/imgs/plugin_submission1.png)
-
-1. ### 创建系统插件配置
-
-系统插件配置以及自定义代码，都会在 **packages/plugins** 目录下。
-
-1. 在 **packages/plugins/src** 下，复制一份 **template** 目录，并修改名字。
-2. 打开目录里面的 template.json 文件，配置如下：
-3. 目录还有一个 index.ts 文件，下文再提。
-
-```typescript
-{
-  "author": "填写你的名字", 
-  "version": "当前系统版本号",
-  "name": "插件名",
-  "avatar": "插件头像，需要配成 icon 格式。直接把 logo 图在 pr 评论区提交即可，我们会帮你加入。",
-  "intro": " 插件的描述，这个描述会影响工具调用",
-  "showStatus": false, // 是否在对话过程展示状态
-  "weight": 10, // 排序权重，均默认 10
-
-  "isTool": true, // 是否作为工具调用节点
-  "templateType": "tools", // 都填写 tools 即可，由官方来分类
-
-  "workflow": { // 这个对象先不管，待会直接粘贴导出的工作流即可
-    "nodes": [],
-    "edges": []
-  }
-}
-```
-
-1. 打开 **packages/plugins/register** 文件，注册你的插件。在 list 数组中，加入一个你插件目录的名字，如下图的例子。如需构建插件组（带目录），可参考 DuckDuckGo 插件。
-
-无需额外写代码的插件，直接放在 staticPluginList 内，需要在项目内额外写代码的，写在 packagePluginList 中。
-
-![](/imgs/plugin_submission2.png)
-
-1. ### 完成工作流编排并测试
-
-完成工作流编排后，可以点击右上角的发布，并在其他工作流中引入进行测试（此时属于团队插件）。
-
-1. ### 复制配置到 template.json
-
-鼠标放置在左上角插件的头像和名称上，会出现对于下拉框操作，可以导出工作流配置。
-
-导出的配置，会自动到剪切板，可以直接到 template.json 文件中粘贴使用，替换步骤 2 中，**workflow** 的值。
-
-![](/imgs/plugin_submission3.png)
-
-1. ### 验证插件是否加载成功
-
-刷新页面，打开系统插件，看其是否成功加载，并将其添加到工作流中使用。
-
-![](/imgs/plugin_submission4.png)
-
-1. ### 提交 PR
-
-如果你觉得你的插件需要提交到开源仓库，可以通过 PR 形式向我们提交。
-
- 写清楚插件的介绍和功能
- 配上插件运行的效果图
- 插件参数填写说明，需要在 PR 中写清楚。例如，有些插件需要去某个提供商申请 key，需要附上对应的地址和教材，后续我们会加入到文档中。
-
-## 写一个复杂的系统插件 - 进阶
-
-这一章会介绍如何增加一些无法单纯通过编排实现的插件。因为可能需要用到网络请求或第三方包。
-
-上一章提到，在插件的 **template** 目录下，还有一个 **index.ts** 文件，这个文件就是用来执行一些插件的代码的。你可以通过在 HTTP 节点中的 URL，填写插件的名字，即可触发该方法，下面以 **duckduckgo/search** 这个插件为例：
-
-![](/imgs/plugin_submission5.png)
-
-![](/imgs/plugin_submission6.png)
-
-![](/imgs/plugin_submission7.png)
-
-参考上面 3 张图片，当 HTTP 节点的 URL 为系统插件注册的名字时，该请求不会以 HTTP 形式发送，而是会请求到 index.ts 文件中的 main 方法。出入参则对应了 body 和自定义输出的字段名。
-
-由于目前插件会默认插件输出均作为“工具调用”的结果，无法单独指定某些字段作为工具输出，所以，请避免插件的自定义输出携带大量说明字段。
--- a/document/content/docs/introduction/meta.json
+++ b/document/content/docs/introduction/meta.json
@@ -2,7 +2,7 @@
  "title": "FastGPT Docs",
  "root": true,
  "pages": [
-    "[Handshake][联系我们](https://fael3z0zfze.feishu.cn/share/base/form/shrcnRxj3utrzjywsom96Px4sud)",
+    "[Handshake][联系我们](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc)",
    "index",
    "guide",
    "development",
--- a/document/content/docs/introduction/shopping_cart/intro.mdx
+++ b/document/content/docs/introduction/shopping_cart/intro.mdx
@@ -34,7 +34,7 @@ FastGPT 商业版是基于 FastGPT 开源版的增强版本，增加了一些独

 ## 商业版软件价格

-FastGPT 商业版软件根据不同的部署方式，分为 3 类收费模式。下面列举各种部署方式一些常规内容，如仍有问题，可[联系咨询](https://fael3z0zfze.feishu.cn/share/base/form/shrcnRxj3utrzjywsom96Px4sud)
+FastGPT 商业版软件根据不同的部署方式，分为 3 类收费模式。下面列举各种部署方式一些常规内容，如仍有问题，可[联系咨询](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc)

 **共有服务**

@@ -48,7 +48,7 @@ FastGPT 商业版软件根据不同的部署方式，分为 3 类收费模式。
 | ---- | ---- | ---- | ---- |
 | Sealos全托管 |  1. 有效期内免费升级。<br />2. 免运维服务&数据库。 |  半天  | 10000元起/月（3个月起）<br />或<br />120000元起/年<br />8C32G 资源，额外资源另外收费。  |
 | Sealos全托管（多节点） |  1. 有效期内免费升级。<br />2. 免运维服务&数据库。 |  半天  | 22000元起/月（3个月起）<br />或<br />264000元起/年<br />32C128G 资源，额外资源另外收费。  |
-| 自有服务器部署 |  1. 6个版本免费升级支持。 | 14天内 | 具体价格和优惠可[联系咨询](https://fael3z0zfze.feishu.cn/share/base/form/shrcnRxj3utrzjywsom96Px4sud) |
+| 自有服务器部署 |  1. 6个版本免费升级支持。 | 14天内 | 具体价格和优惠可[联系咨询](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc) |

 <Alert icon="🤖" context="success">
 - 6个版本的升级服务不是指只能用 6 个版本，而是指依赖 FastGPT 团队提供的升级服务。大部分时候，建议自行升级，也不麻烦。
@@ -60,7 +60,7 @@ FastGPT 商业版软件根据不同的部署方式，分为 3 类收费模式。

 ## 联系方式

-请填写[咨询问卷](https://fael3z0zfze.feishu.cn/share/base/form/shrcnRxj3utrzjywsom96Px4sud)，我们会尽快与您联系。
+请填写[咨询问卷](https://fael3z0zfze.feishu.cn/share/base/form/shrcnjJWtKqjOI9NbQTzhNyzljc)，我们会尽快与您联系。


 ## 技术支持
@@ -102,4 +102,4 @@ Sealos 云服务属于按量计费，下面是它的价格表：

 | | | |
 | ---- | ---- | ---- |
-| ![alt text](/imgs/image-55.png) | ![alt text](/imgs/image-56.png) | ![alt text](/imgs/image-57.png) |
+| ![alt text](/imgs/image-55.png) | ![alt text](/imgs/image-56.png) | ![alt text](/imgs/image-57.png) |
--- a/document/data/doc-last-modified.json
+++ b/document/data/doc-last-modified.json
@@ -155,7 +155,7 @@
  "document/content/docs/introduction/guide/knowledge_base/websync.mdx": "2025-07-23T21:35:03+08:00",
  "document/content/docs/introduction/guide/knowledge_base/yuque_dataset.mdx": "2025-07-23T21:35:03+08:00",
  "document/content/docs/introduction/guide/plugins/bing_search_plugin.mdx": "2025-07-23T21:35:03+08:00",
-  "document/content/docs/introduction/guide/plugins/dev_system_tool.mdx": "2025-07-23T21:35:03+08:00",
+  "document/content/docs/introduction/guide/plugins/dev_system_tool.mdx": "2025-07-30T15:02:01+08:00",
  "document/content/docs/introduction/guide/plugins/doc2x_plugin_guide.mdx": "2025-07-23T21:35:03+08:00",
  "document/content/docs/introduction/guide/plugins/google_search_plugin_guide.mdx": "2025-07-23T21:35:03+08:00",
  "document/content/docs/introduction/guide/plugins/how_to_submit_system_plugin.mdx": "2025-07-23T21:35:03+08:00",
@@ -187,4 +187,4 @@
  "document/content/docs/use-cases/external-integration/official_account.mdx": "2025-07-23T21:35:03+08:00",
  "document/content/docs/use-cases/external-integration/openapi.mdx": "2025-07-23T21:35:03+08:00",
  "document/content/docs/use-cases/index.mdx": "2025-07-24T14:23:04+08:00"
-}
+}