Skip to content

赵月辉 / fastgpt-migrated

Go to a project
Commit de43a189 by Finley Ge Committed by GitHub
Options

docs(plugin): docs for plugin intro and development (#7079) 

* Update system plugin docs to match fastgpt-plugin v1

* docs(plugin): migrate plugin docs to new directory

* docs(plugin): remove legacy plugin doc links
parent 40a8a809
Showing with 1259 additions and 900 deletions
document/content/guide/build/tools/system-plugins/dev_system_tool.en.mdx deleted 100644 → 0
---
title: How to Develop System Plugins
description: FastGPT system plugin development guide (Tools)
---
## Introduction
Starting from version 4.10.0, the FastGPT system plugin project moved to the standalone `fastgpt-plugin` repository, using a pure code approach for tool development.
After the plugin marketplace update in version 4.14.0, the system tool development process changed — please follow the latest documentation when contributing code.
You can develop and debug plugins independently in the `fastgpt-plugin` project, then submit a PR directly to FastGPT without needing to run the main FastGPT service.
Currently, system plugins only support the "Tool" type.
## Concepts
- Tool: The smallest execution unit. Each tool has a unique ID with specific inputs and outputs.
- Toolset: A collection of tools that can contain multiple tools.
In `fastgpt-plugin`, you can create one tool or toolset at a time. Each submission accepts only one tool/toolset. To develop multiple, create separate PRs.
## 1. Prepare the Development Environment
### 1.1 Install Bun
- Install [Bun](https://bun.sh/). FastGPT-plugin uses Bun as its package manager.
### 1.2 Fork the FastGPT-plugin Repository
Fork the repository at `https://github.com/labring/fastgpt-plugin`
### 1.3 Set Up the Development Scaffold
<Tabs items={['One-Click Setup via Bunx','Manual Setup']}>
<Tab value="One-Click Setup via Bunx">
Note: Due to Bun-specific APIs, you must use bunx for installation. Using npx or pnpm will cause errors.
Create a new directory and run:
```bash
bunx @fastgpt-sdk/plugin-cli
```
This creates a fastgpt-plugin directory and adds two remotes:
- upstream pointing to the official repository
- origin pointing to your fork
Uses sparse-checkout by default to avoid pulling all official plugin code.
</Tab>
<Tab value="Manual Setup">
- Initialize a `git` repository in a new local directory:
```bash
git init
```
If you have a Git SSH key configured:
```bash
git remote add origin git@github.com:[your-name]/fastgpt-plugin.git
git remote add upstream git@github.com:labring/fastgpt-plugin.git
```
Otherwise use HTTPS:
```bash
git remote add origin https://github.com/[your-name]/fastgpt-plugin.git
git remote add upstream https://github.com/labring/fastgpt-plugin.git
```
- (Optional) Use sparse-checkout to avoid pulling all plugin code. Without this, all official plugins will be pulled:
```bash
git sparse-checkout init --no-cone
git sparse-checkout add "/*" "!/modules/tool/packages/*"
git pull
```
Create a new tool:
```bash
bun i
bun run new:tool
```
</Tab>
</Tabs>
## 2. Write Tool Code
### 2.1 Tool Code Structure
Follow the prompts to choose between creating a tool or toolset, and enter a directory name (use camelCase).
System tool file structure:
```plaintext
src // Source code and processing logic
└── index.ts
test // Test cases
└── index.test.ts
config.ts // Configuration: tool name, description, type, icon, etc.
index.ts // Entry point — do not modify this file
logo.svg // Logo — replace with your tool's logo
README.md // (Optional) README with usage instructions and examples
assets/ // (Optional) Resource files such as images, audio, etc.
package.json // npm package
```
Toolset file structure:
```plaintext
children
└── tool // Same structure as a tool above, but without README and assets
config.ts
index.ts
logo.svg
README.md
assets/
package.json
```
### 2.2 Modify config.ts
- **name** and **description** fields support both Chinese and English
- **courseUrl** (optional) — Link for obtaining keys, official website, tutorial, etc. If you provide a README.md, you can include it there instead
- **author** — Developer name
- **tags** — Default tags for the tool. Available tags (enum):
- tools: Tools
- search: Search
- multimodal: Multimodal
- communication: Communication
- finance: Finance
- design: Design
- productivity: Productivity
- news: News
- entertainment: Entertainment
- social: Social
- scientific: Scientific
- other: Other
- **secretInputList** — Secret input list for configuring tool `activation information`, typically including `keys`, `Endpoint`, `Port`, etc. (see secretInputList format below)
- **versionList** (configured per tool) — For version management. Each element has:
- value: Version number (semver recommended)
- description: Description
- inputs: Input parameters (see inputs format below)
- outputs: Return values (see outputs format below)
For tools within a Toolset, `type`, `courseUrl`, and `author` are inherited from the Toolset configuration and don't need to be specified.
#### secretInputList Format
General format:
```ts
{
key: 'key', // Unique key
label: 'Frontend display label',
description: 'Frontend display description', // Optional
inputType: 'input' | 'secret' | 'switch' | 'select' | 'numberInput', // Frontend input type
// secret: Encrypted input — the value is symmetrically encrypted when saved
// switch: Toggle switch
// select: Dropdown select
// numberInput: Number input
// input: Plain text input
}
```
Here's an example from the dalle3 configuration. See [dalle3's config.ts](https://github.com/labring/fastgpt-plugin/blob/main/modules/tool/packages/dalle3/config.ts) for the full file.
```ts
{
// Other configuration
secretInputConfig: [
{
key: 'url',
label: 'Dalle3 API Base URL',
description: 'e.g., https://api.openai.com',
inputType: 'input',
required: true
},
{
key: 'authorization',
label: 'API Credential (without Bearer prefix)',
description: 'sk-xxxx',
required: true,
inputType: 'secret'
}
]
}
```
#### inputs Format
General format:
```ts
{
key: 'Unique key within this tool, matching the InputType definition in src/index.ts',
label: 'Frontend display label',
renderTypeList: [FlowNodeInputTypeEnum.input, FlowNodeInputTypeEnum.reference], // Frontend input type
valueType: WorkflowIOValueTypeEnum.string, // Data type
toolDescription: 'Description used during tool invocation' // Required if this is a tool call parameter
}
```
dalle3 inputs example:
```ts
{
//...
versionList: [
{
// Other configuration
inputs: [
{
key: 'prompt',
label: 'Drawing Prompt',
valueType: WorkflowIOValueTypeEnum.string,
renderTypeList: [FlowNodeInputTypeEnum.reference, FlowNodeInputTypeEnum.input],
toolDescription: 'Drawing prompt'
}
],
}
// ...
]
}
```
#### outputs Format
```ts
{
key: 'link', // Unique key
valueType: WorkflowIOValueTypeEnum.string, // See the Enum type definition for options
label: 'Image Access Link', // Display name
description: 'Image access link' // Description (optional)
}
```
dalle3 outputs example:
```ts
{
// ...
versionList: [
{
// ...
outputs: [
{
valueType: WorkflowIOValueTypeEnum.string,
key: 'link',
label: 'Image Access Link',
description: 'Image access link'
},
{
type: FlowNodeOutputTypeEnum.error,
valueType: WorkflowIOValueTypeEnum.string,
key: 'system_error',
label: 'Error Message'
}
]
}
],
}
```
### 2.3 Write the Processing Logic
Write your processing logic in `[your-tool-name]/src/index.ts` as the entry point. Key requirements:
1. Use zod for type definitions, exported as `InputType` and `OutputType` schemas.
2. The entry function must be named `tool`. You can define additional helper functions.
```ts
import { format } from 'date-fns';
import { z } from 'zod';
export const InputType = z.object({
formatStr: z.string().optional()
});
export const OutputType = z.object({
time: z.string()
});
export async function tool(props: z.infer<typeof InputType>): Promise<z.infer<typeof OutputType>> {
const formatStr = props.formatStr || 'yyyy-MM-dd HH:mm:ss';
return {
time: format(new Date(), formatStr)
};
}
```
The example above takes a `formatStr` (format string) and returns the current time. To install packages, run `bun install PACKAGE` from the `/modules/tools/packages/[your-tool-name]` directory.
## 4. Build / Package
Starting from FastGPT v4.14.0, system plugins are packaged as `.pkg` files. Run:
```bash
bun run build:pkg
```
This builds and packages all local plugins as `.pkg` files in the `dist/pkgs` directory.
## 5. Unit Testing
FastGPT-plugin uses Vitest as its testing framework.
### 5.1 Write Test Cases
Write test cases in `test/index.test.ts`. Run them with `bun run test index.test.ts <full-path>`.
> Note: Never include secret keys in test cases.
>
> When using AI agent tools to write test cases, the agent may modify your processing logic or even the testing framework itself.
### 5.2 View Test Coverage
Open `coverage/index.html` in a browser to view coverage for each plugin module.
To submit plugins to the official repository, you must write unit tests that achieve:
- 90%+ code coverage
- 100% function coverage
- 100% branch condition coverage
## 6. E2E (End-to-End) Testing
Simple tools may not need E2E testing. For complex tools, the review team may require it.
### 6.1 Deploy the E2E Test Environment
1. Follow [Quick Start Local Development](../../../../self-host/dev.en.mdx) to set up a local FastGPT development environment
2. Run `cd runtime && cp .env.template .env.local` to copy the environment variable template, then connect to the Minio, Mongo, and Redis instances from step 1
3. Run `bun run dev` to start the development environment, then update FastGPT's environment variables to connect to your fastgpt-plugin instance
### 6.2 Test via Scalar
Start the fastgpt-plugin development environment.
Open `http://localhost:PORT/openapi` in a browser to access the `fastgpt-plugin` OpenAPI page for API debugging. Replace PORT with your fastgpt-plugin port number.
![](/imgs/plugin-openapi.png)
First, use the `/tool/list` endpoint to get the tool list and find the `toolId` of the tool you want to debug. Then use `/tool/runStream` to run the tool and get results.
![](/imgs/plugin-openapi2.png)
### 6.3 E2E Testing in Dev Mode (with Hot Reload)
By default, fastgpt-plugin automatically loads all tools under `modules/tool/packages/` and watches for file changes with hot reload. You can use these tools directly in FastGPT.
### 6.4 Upload Tools for E2E Testing in Dev Mode (without Hot Reload)
Set the FastGPT-plugin environment variable `DISABLE_DEV_TOOLS=true` to disable automatic loading of development tools, allowing you to test tool uploads instead.
## 7. Submit Your Tool to the Official Repository
After completing all the steps above, submit a PR to the official repository at `https://github.com/labring/fastgpt-plugin`. Once reviewed and approved, your tool will be included as an official FastGPT plugin.
If you don't need official inclusion, refer to [Upload System Tool](upload_system_tool) to use it in your own FastGPT deployment.
document/content/guide/build/tools/system-plugins/dev_system_tool.mdx deleted 100644 → 0
---
title: 如何开发系统插件
description: FastGPT 系统插件开发指南（工具篇）
---
## 介绍
FastGPT 系统插件项目从 4.10.0 版本后移动到独立的`fastgpt-plugin`项目中，采用纯代码的模式进行工具编写。
在 4.14.0 版本插件市场更新后，系统工具开发流程有所改变，请依照最新文档贡献代码。
你可以在`fastgpt-plugin`项目中进行独立开发和调试好插件后，直接向 FastGPT 官方提交 PR 即可，无需运行 FastGPT 主服务。
目前系统插件仅支持“工具”这一种类型。
## 概念
- 工具(Tool)：最小的运行单元，每个工具都有唯一 ID 和特定的输入和输出。
- 工具集(Toolset)：工具的集合，可以包含多个工具。
在`fastgpt-plugin`中，你可以每次创建一个工具/工具集，每次提交时，仅接收一个工具/工具集。如需开发多个，可以创建多个 PR 进行提交。
## 1. 准备开发环境
### 1.1 安装 Bun
- 安装 [Bun](https://bun.sh/), FastGPT-plugin 使用 Bun 作为包管理器
### 1.2 Fork FastGPT-plugin 仓库
Fork 本仓库 `https://github.com/labring/fastgpt-plugin`
### 1.3 搭建开发脚手架
<Tabs items={['通过 Bunx 一键搭建','手动搭建']}>
<Tab value="通过 Bunx 一键搭建">
注意：由于使用了 bun 特有的 API，必须使用 bunx 进行安装，使用 npx/npx 等会报错
创建一个新的目录，在该目录下执行：
```bash
bunx @fastgpt-sdk/plugin-cli
```
上述命令会在当前目录下创建 fastgpt-plugin 目录，并且添加两个 remote:
- upstream 指向官方仓库
- origin 指向你自己的仓库
默认使用 sparse-checkout 避免拉取所有的官方插件代码
</Tab>
<Tab value="手动搭建">
- 本地在一个新建目录下初始化一个 `git`:
```bash
git init
```
如果配置了 Git SSH Key, 则可以：
```bash
git remote add origin git@github.com:[your-name]/fastgpt-plugin.git
git remote add upstream git@github.com:labring/fastgpt-plugin.git
```
否则使用 https:
```bash
git remote add origin https://github.com/[your-name]/fastgpt-plugin.git
git remote add upstream https://github.com/labring/fastgpt-plugin.git
```
- (可选）使用稀疏检出 (Sparse-checkout) 以避免拉取所有插件代码，如果不进行稀疏检出，则会拉取所有官方插件
```bash
git sparse-checkout init --no-cone
git sparse-checkout add "/*" "!/modules/tool/packages/*"
git pull
```
使用命令创建新工具
```bash
bun i
bun run new:tool
```
</Tab>
</Tabs>
## 2. 编写工具代码
### 2.1 工具代码结构
依据提示分别选择创建工具/工具集，以及目录名（使用 camelCase 小驼峰法命名）。
系统工具 (Tool) 文件结构如下:
```plaintext
src // 源代码，处理逻辑
└── index.ts
test // 测试样例
└── index.test.ts
config.ts // 配置，配置工具的名称、描述、类型、图标等
index.ts // 入口，不要改这个文件
logo.svg // Logo，替换成你的工具的 Logo
README.md // （可选）README 文件，用于展示工具的使用说明和示例
assets/ // （可选）assets 目录，用于存放工具的资源文件，如图片、音频等
package.json // npm 包
```
工具集(toolset) 的文件结构如下：
```plaintext
children
└── tool // 这个里面的结构就和上面的 tool 一致，但是没有 README 和 assets 目录
config.ts
index.ts
logo.svg
README.md
assets/
package.json
```
### 2.2 修改 config.ts
- **name** 和 **description** 字段为中文和英文两种语言
- **courseUrl**（可选） 密钥获取链接，或官网链接，教程链接等，如果提供 README.md，则可以写到 README 里面
- **author** 开发者名
- **tags** 工具默认的标签，有如下可选标签(枚举类型)
- tools: 工具
- search: 搜索
- multimodal: 多模态
- communication: 通讯
- finance: 金融
- design: 设计
- productivity: 生产力
- news: 新闻
- entertainment: 娱乐
- social: 社交
- scientific: 科学
- other: 其他
- **secretInputList**: 密钥输入列表，其用于配置工具的`激活信息`,通常包含`密钥`、`Endpoint`、`Port`等。(见下面的 secretInputList 参数格式)
- **versionList** (工具中配置)用于版本管理，是一个列表，其中的元素格式:
- value：版本号，建议使用 semver
- description: 描述
- 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 参数格式
一般格式:
```ts
{
key: '本工具内唯一的 key，和 src/index.ts 中的 InputType 定义相同',
label: '前端显示的 label',
renderTypeList: [FlowNodeInputTypeEnum.input, FlowNodeInputTypeEnum.reference], // 前端输入框的类型
valueType: WorkflowIOValueTypeEnum.string, // 数据类型
toolDescription: '工具调用时用到的描述' // 如果需要设置成工具调用参数，需要设置这个字段
}
```
dalle3 的 inputs 参数格式如下：
```ts
{
//...
versionList: [
{
// 其他配置
inputs: [
{
key: 'prompt',
label: '绘图提示词',
valueType: WorkflowIOValueTypeEnum.string,
renderTypeList: [FlowNodeInputTypeEnum.reference, FlowNodeInputTypeEnum.input],
toolDescription: '绘图提示词'
}
],
}
// ...
]
}
```
#### outputs 参数格式
```ts
{
key: 'link', // 唯一键值对
valueType: WorkflowIOValueTypeEnum.string, // 具体可以看这个 Enum 的类型定义
label: '图片访问链接', // 名字
description: '图片访问链接' // 描述，可选
}
```
dalle3 的 outputs 参数格式如下：
```ts
{
// ...
versionList: [
{
// ...
outputs: [
{
valueType: WorkflowIOValueTypeEnum.string,
key: 'link',
label: '图片访问链接',
description: '图片访问链接'
},
{
type: FlowNodeOutputTypeEnum.error,
valueType: WorkflowIOValueTypeEnum.string,
key: 'system_error',
label: '错误信息'
}
]
}
],
}
```
### 2.3 编写处理逻辑
在 `[your-tool-name]/src/index.ts` 为入口编写处理逻辑，需要注意：
1. 使用 zod 进行类型定义，导出为 InputType 和 OutputType 两个 Schema。
2. 入口函数为 `tool`，可以定义其他的函数。
```ts
import { format } from 'date-fns';
import { z } from 'zod';
export const InputType = z.object({
formatStr: z.string().optional()
});
export const OutputType = z.object({
time: z.string()
});
export async function tool(props: z.infer<typeof InputType>): Promise<z.infer<typeof OutputType>> {
const formatStr = props.formatStr || 'yyyy-MM-dd HH:mm:ss';
return {
time: format(new Date(), formatStr)
};
}
```
上述例子给出了一个传入 formatStr （格式化字符串）并且返回当前时间的简单样例，如需安装包，可以在`/modules/tools/packages/[your-tool-name]`路径下，使用`bun install PACKAGE` 进行安装。
## 4. 构建/打包
FastGPT v4.14.0 后，打包方式变为系统插件打包为一个 `.pkg` 文件，使用命令：
```bash
bun run build:pkg
```
将本地所有插件构建打包为 `.pkg` 文件，构建目录为 `dist/pkgs`
## 5. 单元测试
FastGPT-plugin 使用 Vitest 作为单测框架。
### 5.1 编写单测样例
在 `test/index.test.ts` 中编写测试样例，使用 `bun run test index.test.ts 完整路径` 即可运行测试。
> 注意：不要把你的 secret 密钥等写到测试样例中
>
> 使用 Agent 工具编写测试样例时，可能 Agent 工具会修改您的处理逻辑甚至修改整个测试框架的逻辑。
### 5.2 查看测试样例覆盖率（coverage)
浏览器打开 coverage/index.html 可以插件各个模块的覆盖率
提交插件给官方仓库，必须编写单元测试样例，并且达到：
- 90% 以上代码覆盖率
- 100% 函数覆盖率
- 100% 分支条件覆盖率
## 6. E2E （端到端）测试
对于简单的工具，可能并不需要进行 E2E 测试，而如果工具过于复杂，官方人员可能会要求您完成 E2E 测试。
### 6.1 部署 E2E 测试环境
1. 参考 [快速开始本地开发](../../../../self-host/dev.mdx)，在本地部署一套 FastGPT 开发环境
2. `cd runtime && cp .env.template .env.local` 复制环境变量样例文件，连接到上一步部署的 Minio, Mongo, Redis 中
3. `bun run dev` 运行开发环境，修改 FastGPT 的环境变量，连接到你刚刚启动的 fastgpt-plugin
### 6.2 从 Scalar 进行测试
运行 fastgpt-plugin 开发环境
浏览器打开`http://localhost:PORT/openapi`可进入`fastgpt-plugin`的 OpenAPI 页面，进行 API 调试。
PORT 为你的 fastgpt-plugin 的端口
![](/imgs/plugin-openapi.png)
可以先通过`/tool/list`接口，获取工具列表，找到需要调试的工具的`toolId`。紧接着，通过`/tool/runStream`来运行工具获取实际结果。
![](/imgs/plugin-openapi2.png)
### 6.3 在开发环境下 e2e 测试（有热更新）
默认情况下，fastgpt-plugin 会自动加载在 modules/tool/packages/ 下的所有工具，并自动监听文件修改并进行热更新。
可以在 FastGPT 中使用这些工具
### 6.4 在开发环境下上传工具进行 e2e 测试（没有热更新）
设置 FastGPT-plugin 的环境变量 `DISABLE_DEV_TOOLS=true` 会禁用自动加载开发环境下的工具，此时可以测试工具的上传。
## 7. 提交工具至官方目录
完毕上述所有内容后，向官方仓库 `https://github.com/labring/fastgpt-plugin` 提交 PR。
官方人员审核通过后即可收录为 FastGPT 的官方插件。
如无需官方收录，则可以参考 [上传系统工具](upload_system_tool) 在自己部署的 FastGPT 中使用。
document/content/guide/build/tools/system-plugins/meta.en.json
......@@ -2,7 +2,6 @@
"title": "System tools",
"description": "Guides for using, developing, and submitting system plugins.",
"pages": [
"dev_system_tool",
"upload_system_tool"
]
}
document/content/guide/build/tools/system-plugins/meta.json
......@@ -2,7 +2,6 @@
"title": "系统工具",
"description": "系统工具的使用、开发与提交说明。",
"pages": [
"dev_system_tool",
"upload_system_tool"
]
}
document/content/plugin/intro.en.mdx
......@@ -3,4 +3,187 @@ title: Plugin System Overview
description: FastGPT plugin system overview
---
> The plugin system documentation only applies to FastGPT plugin system version 1.0 and later.
> This document applies to FastGPT Plugin v1.0.0 and later.
## Background
FastGPT capabilities were previously maintained inside the FastGPT main service and organized as a Monorepo. System plugins also existed as a sub-repository under `FastGPT/packages/plugin`.
As the number of system tools and community contributions grew, the old structure exposed several problems:
1. System plugins had to be released together with the FastGPT main service, which slowed plugin iteration.
2. Community contributors needed to run the full FastGPT application and submit PRs directly to the main repository.
3. Custom plugins required maintaining a FastGPT fork and manually handling upgrades and merges.
4. The Next.js/webpack build model was not suitable for mounting new plugins at runtime.
System plugins have therefore been split into a standalone repository:
[FastGPT Plugin](https://github.com/labring/fastgpt-plugin)
FastGPT Plugin v1.0.0 systematically refactors the plugin project so plugin installation, version management, runtime isolation, and operations configuration share one model.
## Design Goals
The main goals of FastGPT Plugin are:
1. Decoupling and modularization: system tools, model presets, app templates, and future capabilities such as RAG algorithms, Agent strategies, and third-party integrations can evolve independently.
2. Unified plugin package protocol: `.pkg` files manage plugin installation, updates, and distribution, with extension points reserved for future plugin types.
3. Runtime isolation: plugin execution is managed by a unified runtime. Each plugin version has its own process pool, queue, and runtime configuration.
4. Lower development complexity: contributors can develop, debug, check, and package system tools independently through the CLI and SDK.
5. Plugin Marketplace: official and community plugins can be displayed and distributed through Marketplace.
## Core Concepts
| Name | Description |
| --- | --- |
| Plugin | An independent, reusable capability module. Plugins can have different types, such as tools, model presets, and dataset sources. |
| Plugin package | The packaged `.pkg` file for a plugin. All plugin types are installed, updated, and managed through plugin packages. |
| Tool | A plugin type that usually wraps third-party services, internal APIs, or local computation and can be called by workflows and Agents. |
| Tool suite | A plugin that exposes multiple related child tools while sharing plugin metadata and secret configuration. |
| Plugin Marketplace | A centralized platform where users can search, download, and install plugins. |
| Runtime | The backend implementation responsible for executing plugin code. The current default runtime is `local-pool`. |
| Pod | A single plugin child process in the local process pool. One plugin service can own multiple Pods. |
## Repository Structure
`fastgpt-plugin` is a pnpm workspace Monorepo designed with Clean Architecture and DDD as references.
```text
fastgpt-plugin/
├── apps/
│ ├── cli/ # CLI for plugin development, build, check, pack, and debug
│ ├── server/ # FastGPT Plugin HTTP service
│ └── debug-runtime-monitor/ # Local runtime monitoring and debugging panel
├── packages/
│ ├── domain/ # Domain entities, value objects, and port definitions
│ ├── usecase/ # Application use cases for plugins, tools, models, runtime, and more
│ ├── interface-adapter/ # HTTP contracts, DTOs, and auth adapters
│ ├── infrastructure/ # Hono, Mongo, S3, Redis, runtime, logging, metrics, and other implementations
│ └── shared/ # Cross-layer pure utilities
├── sdk/
│ ├── client/ # Client SDK for calling the FastGPT Plugin service
│ └── factory/ # Plugin author SDK
├── test/ # Cross-package test utilities and fixtures
└── docs/ # Project documentation
```
Core dependency direction:
- `domain` defines business concepts and ports. It is the innermost layer and does not depend on application entrypoints or infrastructure.
- `usecase` orchestrates business flows and depends on `domain` entities, value objects, and ports.
- `interface-adapter` defines HTTP contracts, DTOs, and auth inputs/outputs. It converts external protocols into structures the application can understand.
- `infrastructure` implements ports and runtime capabilities, including the HTTP framework, database, object storage, Redis, plugin runtime, logging, and metrics.
- `apps/*` are composition roots that assemble dependencies, register routes, start processes, or provide development commands.
- `sdk/*` is published for external users and provides service calls and plugin development capabilities.
For system tool development, see [System Tool Development Guide](./system-tool-development.en.mdx). For model presets, see [Add Model Presets](./model-presets.en.mdx).
## Repository Responsibilities
The FastGPT Plugin ecosystem mainly involves these repositories:
| Repository | Purpose |
| --- | --- |
| `labring/fastgpt-plugin` | Plugin service, SDK, CLI, debug monitor, and infrastructure code. |
| `fastgpt-official-plugins` | Plugins maintained or reviewed by FastGPT officials. |
| `fastgpt-community-plugins` | Community third-party plugins. |
| `fastgpt-business-plugins` | Private plugins, customer-customized plugins, and commercial delivery. |
The `fastgpt-plugin` repository only provides development, build, check, packaging, and server runtime capabilities. Specific plugin source code is usually placed in the official, community, or business plugin repositories.
## Marketplace And Usage Boundaries
FastGPT Marketplace is the plugin distribution channel for centrally displaying and distributing official and community plugins. Current boundaries:
- Marketplace is a SaaS distribution service and does not provide a private deployment version.
- Community plugins must first be submitted to the Community Plugins repository, pass basic review, and then enter Marketplace.
- The FastGPT cloud service does not yet support direct custom plugin uploads by users.
- Third-party custom plugins are currently mainly used through self-deployment or administrator upload in the business edition.
## Plugin Installation And Management
The FastGPT Plugin service is responsible for plugin package management, runtime registration, plugin call forwarding, and system-level configuration. The FastGPT main service invokes plugins through the plugin runtime interface, and the plugin service dispatches each call to the corresponding runtime.
System plugins can be installed in two main ways:
1. System-level installation: the root user uploads a `.pkg` file on the plugin management page or installs a plugin from Marketplace. The installed plugin is visible to the whole system.
2. Team-level installation: reserved for team administrators or members with plugin management permission. The plugin is visible only within that team.
After a plugin is installed, the service saves the plugin package file, parses plugin metadata, and registers the plugin with the runtime when it is enabled. System administrators can manage plugin status, system secrets, and runtime parameters.
Plugin statuses include:
- Normal: the plugin is available for normal use.
- Pending offline: existing workflows continue to run, but the plugin can no longer be added to new workflows.
- Offline: the plugin cannot be used.
System-level plugins can configure system secrets for other users in the system to reuse when invoking the plugin. Secrets are hosted by the plugin service. Callers reference them through plugin configuration and never access plaintext secrets directly.
## `.pkg` Plugin Package Protocol
New system tools no longer depend on the legacy built-in source directory `modules/tool/packages`; they are delivered through unified `.pkg` files.
Build artifacts usually include:
- `dist/index.js`
- `dist/manifest.json`
- icon files
- optional `README.md`
- optional `assets/**`
`.pkg` files are used for upload, installation, listing, and version management. Plugin metadata, input/output schemas, secret schemas, and icon assets are included in the build output for FastGPT pages, workflows, and Agents.
## local-pool Runtime
The current default runtime is the local process pool, `local-pool`. It manages Pods and request queues per plugin service.
After a plugin call enters a service, scheduling proceeds as follows:
1. Prefer an existing available Pod and dispatch the request immediately.
2. If no Pod is available and `pods + pendingPods < maxPods`, create a new Pod first and dispatch the current request after startup succeeds.
3. If `maxPods` has been reached, startup backoff is active, or a Pod cannot be created temporarily, the request enters a bounded queue.
4. When a Pod is released, startup succeeds, configuration is updated, or a crash is recovered, the queue continues to drain.
5. When queue length reaches `maxQueueSize`, new requests are rejected. Requests also fail after waiting longer than `queueTimeout`.
Each tool plugin can configure four runtime parameters:
| Parameter | Default | Description |
| --- | --- | --- |
| Minimum worker nodes | `0` | Values above `0` warm up Pods and try to keep at least this many Pods available. |
| Maximum worker nodes | `5` | The service can scale out to this limit when no Pod is available. |
| Node timeout | `120000ms` | Timeout for one plugin call inside a Pod. |
| Maximum concurrent requests per node | `10` | Maximum concurrent requests one Pod can process. |
Environment variables provide default runtime parameters and global limits:
| Environment variable | Description |
| --- | --- |
| `POOL_HEALTH_CHECK_INTERVAL` | Health check interval in milliseconds. |
| `POOL_MAX_TOTAL_PODS` | Total limit for all plugin Pods in the current server process. |
| `POOL_SERVICE_MIN_PODS` | Default minimum worker nodes for one plugin. |
| `POOL_SERVICE_MAX_PODS` | Default maximum worker nodes for one plugin. |
| `POOL_SERVICE_IDLE_TIMEOUT` | Pod idle recycle time in milliseconds. |
| `POOL_SERVICE_POD_TIMEOUT` | Execution timeout for one plugin call in milliseconds. |
| `POOL_SERVICE_MAX_CONCURRENT_REQUESTS_PER_POD` | Default maximum concurrent requests for one Pod. |
| `POOL_SERVICE_MAX_REQUESTS_PER_POD` | Maximum requests one Pod can process before replacement. |
| `POOL_SERVICE_MAX_QUEUE_SIZE` | Maximum request queue capacity for one plugin service. |
| `POOL_SERVICE_QUEUE_TIMEOUT` | Maximum time a request can wait in queue for an available Pod, in milliseconds. |
| `POOL_SERVICE_STARTUP_RETRY_BASE_DELAY` | Base delay for exponential backoff after Pod startup timeout, in milliseconds. |
| `POOL_SERVICE_STARTUP_RETRY_MAX_DELAY` | Maximum delay for exponential backoff after Pod startup timeout, in milliseconds. |
Pod startup errors are recorded and classified. Consecutive non-timeout startup failures trigger startup circuit breaking after the threshold is reached, preventing more Pods from being created. Startup timeouts are usually treated as resource pressure, enter exponential backoff, and retry later.
## Development And Distribution
System tool plugins are developed with `@fastgpt-plugin/cli` and `@fastgpt-plugin/sdk-factory`.
Developers use the CLI to create single-tool or tool-suite skeletons, and use the SDK to declare `manifest`, `inputSchema`, `outputSchema`, `secretSchema`, and handler logic. After development, run tests, build, check, and pack to generate a `.pkg` file.
Continue with [System Tool Development Guide](./system-tool-development.en.mdx) to develop system tools.
## References
- [FastGPT Plugin](https://github.com/labring/fastgpt-plugin)
- [FastGPT Plugin System Design](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/design.md)
- [FastGPT Plugin Architecture](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/architecture.md)
- [System Plugin Development Guide](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/how-to-devlop-plugin.en.md)
document/content/plugin/intro.mdx
......@@ -3,4 +3,187 @@ title: 插件系统说明
description: FastGPT 插件系统说明
---
> 插件系统文档只适用于 1.0 版本以上的 FastGPT 插件系统。
> 本文档适用于 FastGPT Plugin v1.0.0 及以上版本的插件系统。
## 背景
原先 FastGPT 的各项能力均在 FastGPT 主服务内维护，并通过 Monorepo 方式组织。系统插件也曾作为一个子仓库存在于 `FastGPT/packages/plugin` 下。
随着系统工具数量和社区贡献增加，旧结构暴露出几个问题：
1. 系统插件必须伴随 FastGPT 主服务一起发版，限制了插件迭代速度。
2. 社区贡献插件需要运行完整 FastGPT 应用，并直接向主仓库提交 PR。
3. 使用自定义插件需要维护 FastGPT fork，手动处理升级和合并。
4. Next.js/webpack 构建模型不适合在运行时挂载新插件。
因此，系统插件被拆分到独立仓库：
[FastGPT Plugin](https://github.com/labring/fastgpt-plugin)
FastGPT Plugin v1.0.0 对插件项目进行了系统性重构，目标是让插件的安装、版本管理、运行隔离和运维配置形成统一模型。
## 设计目标
FastGPT Plugin 的核心目标：
1. 解耦和模块化：系统工具、模型预设、App 模板等能力可以独立迭代，后续也能扩展 RAG 算法、Agent 策略和第三方接入。
2. 插件包统一协议：使用 `.pkg` 文件管理插件安装、更新和分发，为后续插件类型预留扩展空间。
3. 运行隔离：通过运行时统一管理插件执行，每个插件版本拥有独立进程池、队列和运行配置。
4. 降低开发复杂度：贡献系统工具时可以通过 CLI 和 SDK 独立开发、调试、检查和打包。
5. 插件市场：通过 Marketplace 集中展示和分发官方及社区插件。
## 核心概念
| 名称 | 说明 |
| --- | --- |
| 插件 | 独立、可复用的功能模块，可以有不同类型，例如工具、模型预设、知识库来源等。 |
| 插件包 | 插件打包后的 `.pkg` 文件。不同类型插件都通过插件包完成安装、更新和管理。 |
| 工具 | 一类插件，通常封装第三方服务、内部接口或本地计算逻辑，可被工作流和 Agent 调用。 |
| 工具集 | 一个插件暴露多个相关子工具，共享插件元信息和密钥配置。 |
| 插件市场 | 集中管理插件的平台，用户可以在其中搜索、下载和安装插件。 |
| 运行时 | 负责执行插件代码的后端实现，当前默认运行时是 `local-pool`。 |
| Pod | 本地进程池中的单个插件子进程。一个插件 service 可以拥有多个 Pod。 |
## 仓库结构
`fastgpt-plugin` 使用 pnpm workspace 组织 Monorepo，参考 Clean Architecture 和 DDD 分层设计。
```text
fastgpt-plugin/
├── apps/
│ ├── cli/ # 插件开发、构建、检查、打包、调试命令行
│ ├── server/ # FastGPT Plugin HTTP 服务
│ └── debug-runtime-monitor/ # 本地运行时监控调试面板
├── packages/
│ ├── domain/ # 领域实体、值对象、端口定义
│ ├── usecase/ # 插件、工具、模型、runtime 等应用用例
│ ├── interface-adapter/ # HTTP contract、DTO、鉴权适配
│ ├── infrastructure/ # Hono、Mongo、S3、Redis、运行时、日志、指标等实现
│ └── shared/ # 跨层复用的纯工具函数
├── sdk/
│ ├── client/ # 调用 FastGPT Plugin 服务的客户端 SDK
│ └── factory/ # 插件作者侧 SDK
├── test/ # 跨包测试工具与 fixtures
└── docs/ # 项目文档
```
核心依赖方向：
- `domain` 定义业务概念和端口，是最内层，不依赖应用入口和基础设施。
- `usecase` 负责编排业务流程，依赖 `domain` 的实体、值对象和端口。
- `interface-adapter` 定义 HTTP 合约、DTO、鉴权输入输出，负责把外部协议转换为应用可理解的数据结构。
- `infrastructure` 实现端口和运行环境能力，包括 HTTP 框架、数据库、对象存储、Redis、插件运行时、日志与指标。
- `apps/*` 是组合根，负责装配依赖、注册路由、启动进程或提供开发命令。
- `sdk/*` 面向外部使用者发布，提供服务调用和插件开发能力。
系统工具开发结构可以参考 [系统工具开发指南](./system-tool-development.mdx)。模型预设维护可以参考 [增加模型预设](./model-presets.mdx)。
## 仓库分工
FastGPT Plugin 生态主要涉及以下仓库：
| 仓库 | 作用 |
| --- | --- |
| `labring/fastgpt-plugin` | 插件服务、SDK、CLI、调试监视器和基础设施代码。 |
| `fastgpt-official-plugins` | 官方维护或审核通过的插件。 |
| `fastgpt-community-plugins` | 社区第三方插件。 |
| `fastgpt-business-plugins` | 私有插件、客户定制插件和商业交付插件。 |
`fastgpt-plugin` 仓库只提供开发、构建、检查、打包和服务端运行能力。具体插件源码通常放在 official、community 或 business 插件仓库中。
## 插件市场与使用边界
FastGPT Marketplace 是插件分发渠道，用于集中展示和分发官方及社区插件。当前边界如下：
- Marketplace 是 SaaS 分发服务，不提供私有化部署版本。
- 社区插件需要先提交到 Community Plugins 仓库，经基础审核后再进入 Marketplace。
- 云服务版本 FastGPT 暂未支持用户直接上传自定义插件。
- 第三方自定义插件目前主要通过自部署或商业版的管理员上传方式使用。
## 插件安装与管理
FastGPT Plugin 服务负责插件包管理、运行时注册、插件调用转发和系统级配置管理。FastGPT 主服务通过插件运行时接口调用插件，插件服务负责把调用分发到对应运行时。
系统插件安装主要有两种方式：
1. 系统级安装：root 用户在插件管理页面上传 `.pkg` 文件，或从插件市场安装。安装后全系统可见。
2. 团队级安装：预留给团队管理员或有插件管理权限的成员，仅团队内可见。
插件安装后会保存插件包文件、解析插件元信息，并在插件启用时注册到运行时。系统管理员可以管理插件状态、系统密钥和运行时参数。
插件状态包括：
- 正常：插件正常使用。
- 即将下线：不影响已有工作流运行，但无法再被新增到工作流中。
- 已下线：插件无法正常使用。
系统级插件可以配置“系统密钥”，供系统内其他用户在调用插件时复用。密钥由插件服务托管，调用方通过插件配置引用，不直接接触明文密钥。
## `.pkg` 插件包协议
新版系统工具不再依赖旧的 `modules/tool/packages` 内置源码目录，而是使用统一 `.pkg` 文件交付。
构建产物通常包含：
- `dist/index.js`
- `dist/manifest.json`
- 图标文件
- 可选的 `README.md`
- 可选的 `assets/**`
`.pkg` 文件用于上传、安装、上架和版本管理。插件元信息、输入输出 schema、密钥 schema 和图标资源都会进入构建产物，供 FastGPT 页面、工作流和 Agent 调用使用。
## local-pool 运行时
当前默认运行时是本地进程池，即 `local-pool`。它按单插件 service 维度管理 Pod 和请求队列。
一次插件调用进入 service 后，调度顺序如下：
1. 优先选择已有可用 Pod，立即派发请求。
2. 没有可用 Pod 且 `pods + pendingPods < maxPods` 时，先创建新 Pod，启动成功后派发当前请求。
3. 达到 `maxPods`、处于启动退避期或暂时无法创建 Pod 时，请求进入有界队列等待。
4. Pod 释放、创建成功、配置更新或崩溃恢复时，队列继续被消费。
5. 队列长度达到 `maxQueueSize` 后，新请求会被拒绝；请求等待超过 `queueTimeout` 后会超时失败。
每个工具插件可以单独配置 4 个运行参数：
| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| 最小工作节点数 | `0` | 大于 `0` 时会预热 Pod，并尽量维持不少于该数量的 Pod。 |
| 最大工作节点数 | `5` | 没有可用 Pod 时可扩容到该上限。 |
| 节点超时时间 | `120000ms` | 单次插件调用在 Pod 内执行的超时时间。 |
| 每节点最大并发数 | `10` | 单个 Pod 同时处理的最大并发请求数。 |
环境变量提供默认运行参数和全局限制：
| 环境变量 | 说明 |
| --- | --- |
| `POOL_HEALTH_CHECK_INTERVAL` | 健康检查间隔，单位毫秒。 |
| `POOL_MAX_TOTAL_PODS` | 当前 server 进程内所有插件 Pod 的总上限。 |
| `POOL_SERVICE_MIN_PODS` | 单插件默认最小工作节点数。 |
| `POOL_SERVICE_MAX_PODS` | 单插件默认最大工作节点数。 |
| `POOL_SERVICE_IDLE_TIMEOUT` | Pod 空闲回收时间，单位毫秒。 |
| `POOL_SERVICE_POD_TIMEOUT` | 单次插件调用执行超时时间，单位毫秒。 |
| `POOL_SERVICE_MAX_CONCURRENT_REQUESTS_PER_POD` | 单个 Pod 默认最大并发请求数。 |
| `POOL_SERVICE_MAX_REQUESTS_PER_POD` | 单个 Pod 最大处理请求数；超过后自动替换。 |
| `POOL_SERVICE_MAX_QUEUE_SIZE` | 单插件 service 请求队列最大容量。 |
| `POOL_SERVICE_QUEUE_TIMEOUT` | 请求在队列中等待可用 Pod 的最长时间，单位毫秒。 |
| `POOL_SERVICE_STARTUP_RETRY_BASE_DELAY` | Pod 启动超时后的指数退避基础延迟，单位毫秒。 |
| `POOL_SERVICE_STARTUP_RETRY_MAX_DELAY` | Pod 启动超时后的指数退避最大延迟，单位毫秒。 |
Pod 启动错误会被记录并分类。连续非超时启动失败达到阈值后会触发启动熔断，阻止继续创建 Pod；启动超时通常按资源繁忙处理，会进入指数退避后重试。
## 开发与分发
系统工具插件使用 `@fastgpt-plugin/cli` 和 `@fastgpt-plugin/sdk-factory` 开发。
开发者通过 CLI 创建单工具或工具集骨架，使用 SDK 声明 `manifest`、`inputSchema`、`outputSchema`、`secretSchema` 和 handler。插件开发完成后运行测试、构建、检查和打包，最终生成 `.pkg` 文件。
开发系统工具可以继续阅读 [系统工具开发指南](./system-tool-development.mdx)。
## 参考
- [FastGPT Plugin](https://github.com/labring/fastgpt-plugin)
- [FastGPT 插件系统设计文档](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/design.zh.md)
- [FastGPT Plugin 架构文档](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/architecture.zh.md)
- [系统插件开发指南](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/how-to-devlop-plugin.md)
document/content/plugin/system-tool-development.en.mdx
......@@ -2,3 +2,443 @@
title: System Tool Development Guide
description: FastGPT system tool development guide
---
## Introduction
This document targets system tool development after FastGPT v4.15.0. The new FastGPT Plugin service unifies system tools, model presets, and similar capabilities as installable, updatable, runtime-isolated plugin packages. A plugin is eventually delivered to the FastGPT Plugin service as a `.pkg` file.
The currently stable system tool plugin types are:
- Single tool: one plugin exposes one tool and is declared with `defineTool()`.
- Tool suite: one plugin exposes multiple related child tools and is declared with `defineToolSet()`.
System tool plugins run in the runtime provided by the FastGPT Plugin service. The FastGPT main service invokes tools through the plugin service, and plugin code uses `@fastgpt-plugin/sdk-factory` to describe input, output, secret configuration, and execution logic.
## Differences From The Legacy Mechanism
1. The deployment relationship between FastGPT and FastGPT Plugin remains an external extension model, and the overall architecture is still microservice-based.
2. The plugin package protocol upgrades from the old built-in system tool directory to a unified `.pkg` format, making installation, version management, hot updates, and future plugin type expansion easier.
3. The plugin runtime is managed by the server. The current default runtime is `local-pool`, where each plugin version has its own process pool, queue, and runtime configuration.
4. Plugin metadata, input/output schemas, secret schemas, and icon assets are included in build artifacts for use by FastGPT pages, workflows, and Agents.
5. Tool development uses `@fastgpt-plugin/cli` and `@fastgpt-plugin/sdk-factory`. The legacy `config.ts`, `versionList`, and `bun run build:pkg` flow is no longer the primary development model.
## Information To Collect Before Development
Clarify these items before coding:
| Information | Description |
| --- | --- |
| Plugin type | `tool` or `tool-suite`. |
| Plugin ID | `pluginId`, globally stable and unique. Keep it unchanged after release. |
| Child tool ID | Required for tool suites. `children[].id` stays unchanged after release. |
| Chinese and English names | `name.en` and `name.zh-CN`. |
| Chinese and English descriptions | `description.en` and `description.zh-CN`. |
| Inputs | Type, constraints, default value, UI title, and description for each field. |
| Outputs | Type, meaning, and downstream usage for each field. |
| Secrets | API Key, Base URL, username/password, and similar values, described through `secretSchema`. |
| External API | Request method, auth method, timeout, rate limit, error response, and test account. |
| File capability | Use `ctx.invoke.uploadFile()` when file upload is needed. |
| Streaming output | Use `ctx.streamResponse()` when intermediate progress should be shown to the user. |
| Test cases | Include at least success, invalid parameters, auth failure, and upstream failure. |
Missing information that affects plugin ID, auth method, billing, or listing security should be confirmed first. Other missing information can use reasonable defaults, with assumptions recorded in the submission notes.
## Developing With An Agent
When using Claude Code, Codex, or another agent tool, copy this prompt:
```plaintext
请根据以下 FastGPT 官方插件开发 Skill 开发插件：
https://raw.githubusercontent.com/labring/fastgpt-official-plugins/refs/heads/main/.agents/skills/develop-fastgpt-plugin/SKILL.md
执行要求：
1. 先读取并理解该 Skill 的完整内容，后续开发流程以该 Skill 为准。
2. 在开始编码前，收集插件名称、插件类型、中文/英文名称与描述、输入输出、密钥、外部 API、预期行为、错误处理和测试样例。
3. 如需求缺失，最多提出 3 个关键问题；如果可以合理默认，说明假设后继续推进。
4. 使用 `@fastgpt-plugin/cli` 创建插件骨架，并优先遵循仓库内已有插件的结构、命名、测试和构建方式。
5. 实现完成后运行必要验证，包括测试、构建、插件检查和打包；无法验证的项目需要说明原因。
6. 最终输出变更文件、验证结果、剩余假设和需要人工确认的外部 API 行为。
```
When developing or maintaining SDK/CLI in the `fastgpt-plugin` repository, also refer to local skills:
- `sdk/factory/skills/fastgpt-plugin-development/SKILL.md`
- `sdk/factory/skills/fastgpt-system-tool-development/SKILL.md`
- `sdk/factory/skills/fastgpt-sdk-factory/SKILL.md`
## 1. Prepare Environment
Recommended environment:
- Node.js version that satisfies the target plugin repository.
- `pnpm`; the `fastgpt-plugin` repository uses pnpm workspace.
- Git.
- GitHub CLI `gh`, used for forking, creating repositories, and submitting PRs.
When developing community plugins, first fork and clone the community repository:
```bash
gh repo fork labring/fastgpt-community-plugins --clone
cd fastgpt-community-plugins
pnpm install
```
When debugging the CLI or SDK in the `fastgpt-plugin` repository, install dependencies and build the CLI/SDK first:
```bash
pnpm install
pnpm build:sdk-factory
pnpm build:cli
```
## 2. Create Plugin Skeleton
Single-tool plugin:
```bash
pnpx @fastgpt-plugin/cli create my-tool --type tool --cwd packages/tools
```
Tool-suite plugin:
```bash
pnpx @fastgpt-plugin/cli create my-tool-suite --type tool-suite --cwd packages/tools
```
You can also enter the target directory and create interactively:
```bash
pnpx @fastgpt-plugin/cli create
```
The CLI creates the plugin directory and common files:
| File | Purpose |
| --- | --- |
| `index.ts` | Plugin entry, default-exporting `defineTool()` or `defineToolSet()`. |
| `package.json` | Plugin dependencies and `build`, `build:dev`, `pack`, and `test` scripts. |
| `tsconfig.json` | TypeScript config. |
| `vitest.config.ts` | Test config. |
| `README.md` | Plugin description. |
| `logo.svg` | Main plugin icon. |
## 3. Implement Single Tool
The system tool entry must default-export an SDK factory instance:
```ts
import {
createToolHandler,
defineTool,
type InputSchemaMetaType,
type OutputSchemaMetaType,
type SecretSchemaMetaType
} from '@fastgpt-plugin/sdk-factory';
import z from 'zod';
const secretSchema = z.object({
apiKey: z.string().min(1).meta({
title: 'API Key',
isSecret: true
} satisfies SecretSchemaMetaType)
});
const handler = createToolHandler({
inputSchema: z.object({
query: z.string().min(1).meta({
title: 'Query',
description: 'Search keyword'
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
result: z.string().meta({
title: 'Result'
} satisfies OutputSchemaMetaType)
}),
secretSchema,
handler: async (input, ctx) => {
return {
result: input.query
};
}
});
export default defineTool({
manifest: {
pluginId: 'example-search',
version: '1.0.0',
name: {
en: 'Example Search',
'zh-CN': '示例搜索'
},
description: {
en: 'Search example data',
'zh-CN': '搜索示例数据'
},
versionDescription: {
en: 'Initial version',
'zh-CN': '初始版本'
},
tags: ['tools']
},
handler
});
```
Core rules:
- Keep `pluginId`, child tool `id`, input field names, and output field names stable after publishing.
- Use `{ en, 'zh-CN' }` for `manifest.name`, `manifest.description`, and `versionDescription`.
- Describe inputs, outputs, and secrets with Zod schemas.
- Add `InputSchemaMetaType` to input fields and `OutputSchemaMetaType` to output fields.
- Add `SecretSchemaMetaType` to secret fields and set `isSecret: true` for sensitive fields.
- Handler return values must match `outputSchema`.
- Convert external API errors into actionable messages and avoid exposing secrets, tokens, or complete sensitive responses.
- Use `ctx.invoke.uploadFile()` when host file upload is needed, and prefer preserving the returned `err`.
- Use `ctx.streamResponse()` when progress should be shown to users.
## 4. Implement Tool Suite
Use `defineToolSet()` for tool suites. Put shared information in the top-level `manifest` and `secretSchema`, and declare each child tool's independent `id`, name, description, and handler in `children`.
```ts
import {
createToolHandler,
defineToolSet,
type InputSchemaMetaType,
type OutputSchemaMetaType,
type SecretSchemaMetaType
} from '@fastgpt-plugin/sdk-factory';
import z from 'zod';
const secretSchema = z.object({
apiKey: z.string().meta({
title: 'API Key',
isSecret: true
} satisfies SecretSchemaMetaType)
});
const searchHandler = createToolHandler({
inputSchema: z.object({
query: z.string().meta({
title: 'Query'
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
items: z.array(z.string()).meta({
title: 'Items'
} satisfies OutputSchemaMetaType)
}),
secretSchema,
handler: async (input) => ({ items: [input.query] })
});
const summaryHandler = createToolHandler({
inputSchema: z.object({
content: z.string().meta({
title: 'Content'
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
summary: z.string().meta({
title: 'Summary'
} satisfies OutputSchemaMetaType)
}),
secretSchema,
handler: async (input) => ({ summary: input.content.slice(0, 100) })
});
export default defineToolSet({
manifest: {
pluginId: 'text-tools',
version: '1.0.0',
name: {
en: 'Text Tools',
'zh-CN': '文本工具集'
},
description: {
en: 'Search and summarize text',
'zh-CN': '搜索和总结文本'
}
},
children: [
{
id: 'search',
name: { en: 'Search', 'zh-CN': '搜索' },
description: { en: 'Search text', 'zh-CN': '搜索文本' },
toolDescription: 'Search text by query',
handler: searchHandler
},
{
id: 'summary',
name: { en: 'Summary', 'zh-CN': '总结' },
description: { en: 'Summarize text', 'zh-CN': '总结文本' },
toolDescription: 'Summarize text content',
handler: summaryHandler
}
],
secretSchema
});
```
## 5. Icon Conventions
During build, the CLI scans icons in the plugin root and writes them into the built `manifest.json`.
| Scenario | File name |
| --- | --- |
| Main plugin icon | `logo.svg`, `logo.png`, `logo.jpg`, `logo.jpeg`, `logo.webp`, or `logo.gif` |
| Tool-suite child icon | `<childId>.logo.svg`, `<childId>.logo.png`, and similar names |
Notes:
- Put icon files in the plugin root.
- The `<childId>` of a child icon must exactly match `children[].id`.
- Keep only one extension for the same icon to avoid ambiguous scan results.
- Child tools without their own icons reuse the main plugin icon by default.
- After build, check the `icon` field in `dist/manifest.json`.
## 6. Local Debugging
Install dependencies in the plugin directory first:
```bash
cd packages/tools/my-tool
pnpm install
```
View plugin and debuggable tool information:
```bash
pnpx @fastgpt-plugin/cli debug .
```
Run one single-tool debug invocation:
```bash
pnpx @fastgpt-plugin/cli debug . --run --input '{"query":"hello"}' --secrets '{"apiKey":"test"}'
```
Run a child tool in a tool suite:
```bash
pnpx @fastgpt-plugin/cli debug . --run --tool search --input '{"query":"hello"}' --secrets '{"apiKey":"test"}'
```
Use files when input, secrets, or system variables are large:
```bash
pnpx @fastgpt-plugin/cli debug . --run --input-file input.json --secrets-file secrets.json --system-var-file system-var.json
```
Local debug boundaries:
- `ctx.invoke.uploadFile()` uses a local mock implementation and defaults to `.fastgpt-plugin-debug/uploads`.
- Local debug quickly validates plugin logic and schemas.
- Local debug does not simulate the production child-process pool, real Node.js IPC, network environment, server timeout, or queue scheduling.
- Before listing official plugins, still manually install plugins in a test environment and complete end-to-end testing.
## 7. Build, Check, And Pack
Inside a plugin directory, usually run:
```bash
pnpm run test
pnpm run build
pnpx @fastgpt-plugin/cli check --entry . --output ./dist
pnpm run pack
```
You can also pass directories explicitly:
```bash
pnpx @fastgpt-plugin/cli build --entry packages/tools/my-tool --output packages/tools/my-tool/dist --minify
pnpx @fastgpt-plugin/cli check --entry packages/tools/my-tool --output packages/tools/my-tool/dist
pnpx @fastgpt-plugin/cli pack --entry packages/tools/my-tool --dist ./dist --output packages/tools/my-tool/out
```
Build artifacts should include:
- `dist/index.js`
- `dist/manifest.json`
- icon files
- optional `README.md`
- optional `assets/**`
Packaging produces a `.pkg` file. Uploading, installation, and listing should all use that `.pkg` file.
## 8. Verification Checklist
Before submitting, confirm:
- `index.ts` default export is correct.
- `manifest.pluginId`, `manifest.version`, Chinese and English names, and descriptions are complete.
- Tool suite `children[].id` values are stable and unique.
- `inputSchema` covers all user inputs and includes required type and range constraints.
- `outputSchema` matches handler return values.
- `secretSchema` covers all secret configuration and sensitive fields set `isSecret: true`.
- External API success, failure, empty response, timeout, and auth failure are handled.
- Error messages help locate issues and do not leak secrets or sensitive responses.
- `pnpm run test` passes, or the reason it cannot be tested is documented.
- `build`, `check`, and `pack` pass.
- Icons and schemas in `dist/manifest.json` are as expected.
- `.pkg` can be installed in a test environment and complete a real invocation.
## 9. Release Flow
### Community Plugins
Community plugins usually start by creating and pushing an independent GitHub repository from the plugin directory:
```bash
cd packages/tools/my-tool
git init
git add .
git commit -m "feat: add my-tool plugin"
gh repo create --public --source=. --remote=origin --push
```
Then return to the `fastgpt-community-plugins` repository, submit the submodule or reference update, and open a PR to `labring/fastgpt-community-plugins`.
### Official Plugins
Official plugins require:
1. Code review.
2. Build, check, test, and package.
3. Manual `.pkg` installation in a test environment.
4. Complete functional testing, including external APIs, secret configuration, error paths, and concurrent calls.
5. Pre-listing security checks, focusing on SSRF, secret leakage, arbitrary file access, command execution, and dependency risk.
### Business Plugins
Business plugins are released to private repositories. Manage versions, secrets, installation packages, and acceptance records according to the customer delivery process. Security boundaries for external APIs, customer private addresses, and account secrets should be recorded separately.
If you do not need official inclusion, see [Upload System Tool](../guide/build/tools/system-plugins/upload_system_tool.en.mdx) to use the plugin in your own FastGPT deployment.
## FAQ
### How should I choose between `tool` and `tool-suite`?
Use `tool` for a single capability. Use `tool-suite` for multiple capabilities that share authentication, the same upstream API, and strong business relevance, such as search, detail, and task creation in one plugin.
### How should plugin versions be managed?
Use semantic versioning for `manifest.version`. Upgrade patch for compatible fixes, minor for compatible new features, and major when changing input/output fields, child tool IDs, or user configuration. Evaluate existing workflow compatibility before major changes.
### Can I put API keys in code or environment variables?
Plugins should declare secrets through `secretSchema` and read them through `ctx.secrets`. Real secrets should not appear in code repositories, test snapshots, error logs, or README files.
### Is a test environment still needed after local debug passes?
Yes. Local debug quickly validates plugin logic and schemas. Test environment validation confirms real installation, runtime, host reverse invocation, network, and permission behavior.
## References
- [FastGPT Plugin Repository](https://github.com/labring/fastgpt-plugin)
- [System Plugin Development Guide](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/how-to-devlop-plugin.en.md)
- [SDK Factory Guide](https://github.com/labring/fastgpt-plugin/blob/main/sdk/factory/README.en.md)
- [CLI Guide](https://github.com/labring/fastgpt-plugin/blob/main/apps/cli/README.en.md)
document/content/plugin/system-tool-development.mdx
......@@ -2,3 +2,443 @@
title: 系统工具开发指南
description: FastGPT 系统工具开发指南
---
## 介绍
本文面向 FastGPT v4.15.0 之后的系统工具开发。新版 FastGPT Plugin 服务把系统工具、模型预设等能力统一抽象为可安装、可更新、可运行隔离的插件包，插件最终以 `.pkg` 文件交付给 FastGPT Plugin 服务。
当前稳定支持的系统工具插件类型有两种：
- 单工具：一个插件只暴露一个工具，使用 `defineTool()` 声明。
- 工具集：一个插件暴露多个相关子工具，使用 `defineToolSet()` 声明。
系统工具插件运行在 FastGPT Plugin 服务提供的运行时中。FastGPT 主服务通过插件服务调用工具，插件代码通过 `@fastgpt-plugin/sdk-factory` 描述输入、输出、密钥配置和执行逻辑。
## 与旧版机制的区别
1. FastGPT 和 FastGPT Plugin 的部署关系保持外置扩展模式，整体仍然是微服务架构。
2. 插件包协议从旧的内置系统工具目录升级为统一 `.pkg` 格式，便于安装、版本管理、热更新和后续扩展其他插件类型。
3. 插件运行时由服务端统一管理，当前默认运行时是 `local-pool`，每个插件版本拥有独立进程池、队列和运行时配置。
4. 插件元信息、输入输出 schema、密钥 schema 和图标资源都会进入构建产物，供 FastGPT 页面、工作流和 Agent 调用使用。
5. 工具开发使用 `@fastgpt-plugin/cli` 和 `@fastgpt-plugin/sdk-factory`，不再以旧版 `config.ts`、`versionList` 和 `bun run build:pkg` 作为主要开发方式。
## 开发前准备
开始编码前先明确这些信息：
| 信息 | 说明 |
| --- | --- |
| 插件类型 | `tool` 或 `tool-suite`。 |
| 插件 ID | `pluginId`，全局稳定唯一，发布后保持不变。 |
| 子工具 ID | 工具集需要，`children[].id` 发布后保持不变。 |
| 中英文名称 | `name.en` 和 `name.zh-CN`。 |
| 中英文描述 | `description.en` 和 `description.zh-CN`。 |
| 输入 | 每个字段的类型、约束、默认值、UI 标题和说明。 |
| 输出 | 每个字段的类型、含义和下游使用方式。 |
| 密钥 | API Key、Base URL、账号密码等，通过 `secretSchema` 描述。 |
| 外部 API | 请求方式、鉴权方式、超时、限流、错误响应和测试账号。 |
| 文件能力 | 需要上传文件时使用 `ctx.invoke.uploadFile()`。 |
| 流式输出 | 需要展示中间进度时使用 `ctx.streamResponse()`。 |
| 测试样例 | 至少包含成功路径、参数错误、鉴权失败和上游失败。 |
影响插件 ID、鉴权方式、计费或上架安全性的信息需要先确认。其他信息可以使用合理默认值继续推进，并在提交说明中记录假设。
## 使用 Agent 开发
使用 Claude Code、Codex 或其他 Agent 工具时，可直接复制下面的提示词：
```plaintext
请根据以下 FastGPT 官方插件开发 Skill 开发插件：
https://raw.githubusercontent.com/labring/fastgpt-official-plugins/refs/heads/main/.agents/skills/develop-fastgpt-plugin/SKILL.md
执行要求：
1. 先读取并理解该 Skill 的完整内容，后续开发流程以该 Skill 为准。
2. 在开始编码前，收集插件名称、插件类型、中文/英文名称与描述、输入输出、密钥、外部 API、预期行为、错误处理和测试样例。
3. 如需求缺失，最多提出 3 个关键问题；如果可以合理默认，说明假设后继续推进。
4. 使用 `@fastgpt-plugin/cli` 创建插件骨架，并优先遵循仓库内已有插件的结构、命名、测试和构建方式。
5. 实现完成后运行必要验证，包括测试、构建、插件检查和打包；无法验证的项目需要说明原因。
6. 最终输出变更文件、验证结果、剩余假设和需要人工确认的外部 API 行为。
```
在 `fastgpt-plugin` 仓库内开发或维护 SDK/CLI 时，也可以参考本地 Skill：
- `sdk/factory/skills/fastgpt-plugin-development/SKILL.md`
- `sdk/factory/skills/fastgpt-system-tool-development/SKILL.md`
- `sdk/factory/skills/fastgpt-sdk-factory/SKILL.md`
## 1. 准备开发环境
推荐环境：
- Node.js 版本满足目标插件仓库要求。
- `pnpm`，当前 `fastgpt-plugin` 仓库使用 pnpm workspace。
- Git。
- GitHub CLI `gh`，用于 fork、创建仓库和提交 PR。
开发社区插件时，先 fork 并 clone 社区插件仓库：
```bash
gh repo fork labring/fastgpt-community-plugins --clone
cd fastgpt-community-plugins
pnpm install
```
在 `fastgpt-plugin` 仓库内调试 CLI 或 SDK 时，先安装依赖并构建 CLI/SDK：
```bash
pnpm install
pnpm build:sdk-factory
pnpm build:cli
```
## 2. 创建插件骨架
单工具插件：
```bash
pnpx @fastgpt-plugin/cli create my-tool --type tool --cwd packages/tools
```
工具集插件：
```bash
pnpx @fastgpt-plugin/cli create my-tool-suite --type tool-suite --cwd packages/tools
```
也可以进入目标目录后交互式创建：
```bash
pnpx @fastgpt-plugin/cli create
```
CLI 会创建插件目录，并生成常见文件：
| 文件 | 作用 |
| --- | --- |
| `index.ts` | 插件入口，默认导出 `defineTool()` 或 `defineToolSet()`。 |
| `package.json` | 插件依赖和 `build`、`build:dev`、`pack`、`test` 脚本。 |
| `tsconfig.json` | TypeScript 配置。 |
| `vitest.config.ts` | 测试配置。 |
| `README.md` | 插件说明。 |
| `logo.svg` | 插件主图标。 |
## 3. 实现单工具
系统工具入口必须默认导出 SDK factory 实例：
```ts
import {
createToolHandler,
defineTool,
type InputSchemaMetaType,
type OutputSchemaMetaType,
type SecretSchemaMetaType
} from '@fastgpt-plugin/sdk-factory';
import z from 'zod';
const secretSchema = z.object({
apiKey: z.string().min(1).meta({
title: 'API Key',
isSecret: true
} satisfies SecretSchemaMetaType)
});
const handler = createToolHandler({
inputSchema: z.object({
query: z.string().min(1).meta({
title: 'Query',
description: 'Search keyword'
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
result: z.string().meta({
title: 'Result'
} satisfies OutputSchemaMetaType)
}),
secretSchema,
handler: async (input, ctx) => {
return {
result: input.query
};
}
});
export default defineTool({
manifest: {
pluginId: 'example-search',
version: '1.0.0',
name: {
en: 'Example Search',
'zh-CN': '示例搜索'
},
description: {
en: 'Search example data',
'zh-CN': '搜索示例数据'
},
versionDescription: {
en: 'Initial version',
'zh-CN': '初始版本'
},
tags: ['tools']
},
handler
});
```
核心规则：
- `pluginId`、子工具 `id`、输入字段名、输出字段名发布后保持稳定。
- `manifest.name`、`manifest.description` 和 `versionDescription` 使用 `{ en, 'zh-CN' }`。
- 输入、输出和密钥都用 Zod schema 描述。
- 输入字段补充 `InputSchemaMetaType`，输出字段补充 `OutputSchemaMetaType`。
- 密钥字段补充 `SecretSchemaMetaType`，敏感字段设置 `isSecret: true`。
- handler 返回值必须匹配 `outputSchema`。
- 外部 API 错误需要转成可定位的错误信息，并避免输出密钥、令牌和完整敏感响应。
- 调用宿主文件上传能力时，使用 `ctx.invoke.uploadFile()`，并优先保留返回的 `err`。
- 展示进度时，使用 `ctx.streamResponse()`。
## 4. 实现工具集
工具集使用 `defineToolSet()`，把共用信息放在顶层 `manifest` 和 `secretSchema`，每个子工具在 `children` 中声明独立 `id`、名称、描述和 handler。
```ts
import {
createToolHandler,
defineToolSet,
type InputSchemaMetaType,
type OutputSchemaMetaType,
type SecretSchemaMetaType
} from '@fastgpt-plugin/sdk-factory';
import z from 'zod';
const secretSchema = z.object({
apiKey: z.string().meta({
title: 'API Key',
isSecret: true
} satisfies SecretSchemaMetaType)
});
const searchHandler = createToolHandler({
inputSchema: z.object({
query: z.string().meta({
title: 'Query'
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
items: z.array(z.string()).meta({
title: 'Items'
} satisfies OutputSchemaMetaType)
}),
secretSchema,
handler: async (input) => ({ items: [input.query] })
});
const summaryHandler = createToolHandler({
inputSchema: z.object({
content: z.string().meta({
title: 'Content'
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
summary: z.string().meta({
title: 'Summary'
} satisfies OutputSchemaMetaType)
}),
secretSchema,
handler: async (input) => ({ summary: input.content.slice(0, 100) })
});
export default defineToolSet({
manifest: {
pluginId: 'text-tools',
version: '1.0.0',
name: {
en: 'Text Tools',
'zh-CN': '文本工具集'
},
description: {
en: 'Search and summarize text',
'zh-CN': '搜索和总结文本'
}
},
children: [
{
id: 'search',
name: { en: 'Search', 'zh-CN': '搜索' },
description: { en: 'Search text', 'zh-CN': '搜索文本' },
toolDescription: 'Search text by query',
handler: searchHandler
},
{
id: 'summary',
name: { en: 'Summary', 'zh-CN': '总结' },
description: { en: 'Summarize text', 'zh-CN': '总结文本' },
toolDescription: 'Summarize text content',
handler: summaryHandler
}
],
secretSchema
});
```
## 5. 图标规范
CLI 构建时会扫描插件根目录中的图标并写入构建后的 `manifest.json`。
| 场景 | 文件名 |
| --- | --- |
| 主插件图标 | `logo.svg`、`logo.png`、`logo.jpg`、`logo.jpeg`、`logo.webp` 或 `logo.gif` |
| 工具集子工具图标 | `<childId>.logo.svg`、`<childId>.logo.png` 等 |
注意事项：
- 图标文件放在插件根目录。
- 子工具图标的 `<childId>` 与 `children[].id` 完全一致。
- 同一个图标只保留一个扩展名，避免扫描结果不明确。
- 子工具没有独立图标时，默认复用主插件图标。
- 构建后检查 `dist/manifest.json` 中的 `icon` 字段。
## 6. 本地调试
先进入插件目录安装依赖：
```bash
cd packages/tools/my-tool
pnpm install
```
查看插件和可调试工具信息：
```bash
pnpx @fastgpt-plugin/cli debug .
```
执行一次单工具调试：
```bash
pnpx @fastgpt-plugin/cli debug . --run --input '{"query":"hello"}' --secrets '{"apiKey":"test"}'
```
执行工具集中的某个子工具：
```bash
pnpx @fastgpt-plugin/cli debug . --run --tool search --input '{"query":"hello"}' --secrets '{"apiKey":"test"}'
```
输入、密钥和系统变量较大时，使用文件传入：
```bash
pnpx @fastgpt-plugin/cli debug . --run --input-file input.json --secrets-file secrets.json --system-var-file system-var.json
```
本地 debug 的边界：
- `ctx.invoke.uploadFile()` 使用本地虚拟实现，默认输出到 `.fastgpt-plugin-debug/uploads`。
- 本地 debug 用于快速验证插件逻辑和 schema。
- 本地 debug 不模拟生产子进程池、真实 Node.js IPC、网络环境、服务端超时和队列调度。
- 上架官方插件前仍需在测试环境中手动安装插件并完成端到端测试。
## 7. 构建、检查和打包
插件目录中通常可以直接运行：
```bash
pnpm run test
pnpm run build
pnpx @fastgpt-plugin/cli check --entry . --output ./dist
pnpm run pack
```
也可以显式传入目录：
```bash
pnpx @fastgpt-plugin/cli build --entry packages/tools/my-tool --output packages/tools/my-tool/dist --minify
pnpx @fastgpt-plugin/cli check --entry packages/tools/my-tool --output packages/tools/my-tool/dist
pnpx @fastgpt-plugin/cli pack --entry packages/tools/my-tool --dist ./dist --output packages/tools/my-tool/out
```
构建产物应包含：
- `dist/index.js`
- `dist/manifest.json`
- 图标文件
- 可选的 `README.md`
- 可选的 `assets/**`
打包后会生成 `.pkg` 文件。上传、安装和上架都应使用该 `.pkg` 文件。
## 8. 验证清单
提交前至少确认：
- `index.ts` 默认导出正确。
- `manifest.pluginId`、`manifest.version`、中英文名称和描述完整。
- 工具集的 `children[].id` 稳定且没有重复。
- `inputSchema` 覆盖所有用户输入，并有必要的类型和范围约束。
- `outputSchema` 与 handler 返回值一致。
- `secretSchema` 覆盖全部密钥配置，敏感字段设置 `isSecret: true`。
- 外部 API 的成功、失败、空响应、超时和鉴权失败都有处理。
- 错误信息可定位问题，并且不会泄露密钥或敏感响应。
- `pnpm run test` 通过，或明确说明无法测试的原因。
- `build`、`check`、`pack` 通过。
- `dist/manifest.json` 中图标和 schema 符合预期。
- `.pkg` 能在测试环境中安装并完成真实调用。
## 9. 发布流程
### 社区插件
社区插件通常先在插件目录创建并推送独立 GitHub 仓库：
```bash
cd packages/tools/my-tool
git init
git add .
git commit -m "feat: add my-tool plugin"
gh repo create --public --source=. --remote=origin --push
```
然后回到 `fastgpt-community-plugins` 仓库，提交 submodule 或引用更新，并向 `labring/fastgpt-community-plugins` 提 PR。
### 官方插件
官方插件需要完成：
1. 代码 review。
2. 构建、检查、测试和打包。
3. 在测试环境手动安装 `.pkg`。
4. 完整功能测试，包括外部 API、密钥配置、错误路径和并发调用。
5. 上架前安全检查，重点关注 SSRF、密钥泄露、任意文件访问、命令执行和依赖风险。
### 商业插件
商业插件发布到私有仓库，按客户交付流程管理版本、密钥、安装包和验收记录。对外部 API、客户私有地址和账号密钥的处理需要单独记录安全边界。
如无需官方收录，可参考 [上传系统工具](../guide/build/tools/system-plugins/upload_system_tool.mdx) 在自己部署的 FastGPT 中使用。
## 常见问题
### `tool` 和 `tool-suite` 如何选择？
单一能力使用 `tool`。多个共享鉴权、共享上游 API、业务上强相关的能力使用 `tool-suite`，例如搜索、详情、创建任务放在同一个插件中。
### 插件版本如何管理？
`manifest.version` 使用语义化版本。修复兼容性问题升级 patch，新增兼容功能升级 minor，修改输入输出字段、子工具 ID 或用户配置方式时升级 major，并提前评估已有工作流兼容性。
### 可以把 API Key 写在代码或环境变量里吗？
插件应通过 `secretSchema` 声明密钥，并通过 `ctx.secrets` 读取。代码仓库、测试快照、错误日志和 README 中都不应出现真实密钥。
### 本地 debug 通过后还需要测试环境验证吗？
需要。本地 debug 用于快速验证插件逻辑和 schema，测试环境验证用于确认真实安装、运行时、宿主反向调用、网络和权限行为。
## 参考
- [FastGPT Plugin 仓库](https://github.com/labring/fastgpt-plugin)
- [系统插件开发指南](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/how-to-devlop-plugin.md)
- [SDK Factory 使用指南](https://github.com/labring/fastgpt-plugin/blob/main/sdk/factory/README.md)
- [CLI 使用指南](https://github.com/labring/fastgpt-plugin/blob/main/apps/cli/README.md)
document/content/self-host/design/design_plugin.en.mdx deleted 100644 → 0
---
title: System Plugin Design
description: FastGPT system plugin design
---
## Background
Previously, all FastGPT features lived within the Next.js framework, organized as a Monorepo. System plugins existed as a sub-repo under FastGPT/packages/plugin.
As the user base grew, this approach revealed several limitations:
1. Although FastGPT releases weekly, system plugins had to ship alongside FastGPT, severely limiting plugin iteration speed.
2. Community contributors who wanted to add plugins had to run the entire FastGPT application and submit PRs directly to the main repo.
3. Users who wanted custom plugins had to maintain a FastGPT fork and manually handle updates and merges, increasing development complexity.
4. Due to Next.js/webpack limitations, plugins couldn't be mounted at runtime -- no hot-swapping.
## Design
We decided to extract system plugins into a separate repository:
[FastGPT-plugin](https://github.com/labring/fastgpt-plugin)
Key goals of the split:
1. Decoupling and modularization: not just system tools, but also other plugin types like Knowledge Base plugins, RAG, etc. can be hot-loaded modules.
2. Independent versioning: FastGPT-plugin can release more frequently than FastGPT, and hot-swapping enables plugin updates without a full release.
3. Lower development complexity: contributors only need to run the debug suite provided in FastGPT-plugin, without setting up the full FastGPT environment.
4. Plugin marketplace: enables a future marketplace where users can publish and discover plugins.
## Technology Stack
1. ts-rest as the RPC framework, with an SDK for the FastGPT main project to consume.
2. zod for runtime type validation.
3. bun for bundling -- each tool compiles into a single `.pkg` file for hot-swapping.
## Project Structure
- **modules**
- **tool** FastGPT system tools
- **api** API implementation logic
- **packages** System tool directory (each is a package)
- getTime
- dalle3
- ...
- **type** Type definitions
- **utils** Utilities
- **scripts** Scripts (build, create new tools)
- **sdk**: SDK definition for external consumers, published to npm
- **runtime**: Runtime express service
- **lib**: Library files with utility functions
- **test**: Tests
For system tool structure, see [How to Develop System Plugins](../../guide/build/tools/system-plugins/dev_system_tool.en.mdx).
## Technical Details
### ts-rest: Contract-Based API with Auto-Generated OpenAPI and Client
[ts-rest](https://ts-rest.com/) is a TypeScript RESTful API framework. After defining a contract, you can write handler logic, auto-generate OpenAPI specs, and export a typed client via createClient.
`tRPC` is a similar TypeScript RPC framework, but it uses a proprietary request format that makes integration with other tools inconvenient. ts-rest is essentially a thin wrapper around RESTful APIs and can directly generate OpenAPI specs.
### Zod Type Validation
We use zod for type validation. Zod provides runtime type checking along with advanced features like parameter transformation and object merging.
### Worker-Based Parallel Execution and Environment Isolation
To prevent plugins from interfering with each other while improving concurrency, FastGPT-plugin uses Worker threads for plugin execution. Each tool runs in an independent Worker when called, providing:
1. Environment isolation: each plugin runs in its own Worker process, so plugins don't affect each other.
2. Parallel processing: plugins can run concurrently, improving overall performance.
### Bundling with Bun
Bundling each plugin into a single `.pkg` file is a key design decision. This allows plugins to be distributed and loaded directly via network mounting.
## Future Plans
1. Visual development tools: provide visual plugin development and debugging tools to lower the barrier to entry.
2. Plugin marketplace: a marketplace where developers can publish and share plugins.
3. More plugin types: beyond system tools, expand to Knowledge Base plugins, model plugins, RAG plugins, and more.
document/content/self-host/design/design_plugin.mdx deleted 100644 → 0
---
title: 系统插件设计
description: FastGPT 系统插件设计方案
---
## 背景
原先 FastGPT 的各项功能均在 FastGPT 的 Next.js 的框架内，通过 Monorepo 的方式进行组织。系统插件也作为一个 sub-repo 存在于 FastGPT/packages/plugin 下。
然而随着用户的增加，这种组织模式的弊端凸显：
1. 虽然 FastGPT 以每周一次的频率进行发版，但同样，系统插件必须伴随 FastGPT 的发版而发版，极大限制了系统插件的迭代速率。
2. 如果社区希望为 FastGPT 提供插件，则需要将 FastGPT 整个应用运行起来，并且直接向主仓库发起 PR。
3. 如果社区希望使用自定义的插件，则需要维护一个 FastGPT 的 fork 版本，并且手动维护更新和代码的合并，增加了开发的难度。
4. 由于 Next.js/webpack 的限制，无法在运行时挂载新的插件，实现热插拔。
## 设计方案
因而，我们决定将系统插件拆分出来，到一个独立的 repository 中。
[FastGPT-plugin](https://github.com/labring/fastgpt-plugin)
拆分出来，主要有如下的目的：
1. 解耦合，模块化：不只是系统工具可以作为热加载的模块，也可以是其他的插件，例如知识库的插件，RAG 等等。
2. FastGPT-plugin 可以快速迭代，版本不依赖于 FastGPT：FastGPT-plugin 可以更高频率的发版，支持热插拔可以在不发版的情况下更新插件。
3. 降低开发复杂度（不需要运行 FastGPT 环境）：贡献插件时只需要独立运行 FastGPT-plugin 中提供的调试套件即可。
4. 插件市场：后续可以实现插件市场，用户可以通过插件市场发布、获取自己需要的插件。
## 技术选型
1. 使用 ts-rest 作为 RPC 框架进行交互，提供 sdk 供 FastGPT 主项目调用
2. 使用 zod 进行类型验证
3. 用 bun 进行编译，每个工具编译为单一的 `.pkg` 文件，支持热插拔。
## 项目结构
- **modules**
- **tool** FastGPT 系统工具
- **API** 接口实现逻辑
- **packages** 系统工具目录（每一个都是一个 package）
- getTime
- dalle3
- ……
- **type** 类型定义
- **utils** 工具
- **scripts** 脚本（编译、创建新工具）
- **sdk** : SDK 定义，供外部调用，发布到了 npm
- **runtime** : 运行时，express 服务
- **lib** : 库文件，提供工具函数和类库
- **test** : 测试相关
系统工具的结构可以参考 [如何开发系统插件](../../guide/build/tools/system-plugins/dev_system_tool.mdx)。
## 技术细节
### ts-rest 构建 contract，自动构建 openapi 对象，导出 client
[ts-rest](https://ts-rest.com/) 是一个 ts 的 restful API 框架。构建 contract 后，可以根据 contract 的定义
编写处理逻辑，自动生成 openapi 对象、通过 createClient 导出 client 进行请求。
类似的 `tRPC` 也是一个 ts 的 RPC 框架。然而 tRPC 使用自己的一套请求格式，导致其他工具不方便接入。而使用 ts-rest 本质就是对 RESTful API 的简单封装，也能直接生成 openapi 对象。
### zod 类型校验
我们使用 zod 来实现类型校验。zod 可以实现在运行时的类型校验，也可以提供更高级的功能，例如参数转换，对象合并等。
### 使用 worker 实现插件的并行运行以及环境隔离
为了保证插件之间不会相互干扰，同时提高并发处理能力，FastGPT-plugin 采用 Worker 线程来实现插件的执行。每个工具在被调用时都会在独立的 Worker 中运行，这带来几个重要的优势：
1. 环境隔离：每个插件都是一个独立的 Worker 进程，插件之间不会影响。
2. 并行处理：每个插件可以并行处理，提高整体性能。
### 使用 bun 进行打包
将插件 bundle 为一个单一的 `.pkg` 文件是一个重要的设计。这样可以将插件发布出来直接通过网络挂载等的形式使用。
## 未来规划
1. 可视化开发工具：提供可视化的插件开发和调试工具，降低开发门槛。
2. 插件市场：建立插件市场，允许开发者发布和分享自己的插件。
3. 更多插件类型：除了系统工具外，扩展到知识库插件、模型插件、RAG 插件等更多类型。
document/content/self-host/design/meta.en.json
{
"title": "Design Documentation",
"pages": ["dataset","design_plugin"]
"pages": ["dataset"]
}
document/content/self-host/design/meta.json
{
"title": "设计方案",
"pages": ["dataset","design_plugin"]
}
\ No newline at end of file
"pages": ["dataset"]
}
document/content/self-host/upgrading/outdated/4100.en.mdx
......@@ -54,5 +54,5 @@ PLUGIN_TOKEN=the AUTH_TOKEN value you just set
## New Features
1. Standalone system tool service with support for independent development and debugging of system tools.
2. Updated [System Tool Development Guide](../../../guide/build/tools/system-plugins/dev_system_tool.en.mdx).
3. Updated [System Tool Design Documentation](../../../guide/build/tools/system-plugins/dev_system_tool.en.mdx).
2. Updated [System Tool Development Guide](../../../plugin/system-tool-development.en.mdx).
3. Updated [Plugin System Overview](../../../plugin/intro.en.mdx).
document/content/self-host/upgrading/outdated/4100.mdx
......@@ -54,5 +54,5 @@ PLUGIN_TOKEN=刚修改的 AUTH_TOKEN 值
## 🚀 新增内容
1. 独立系统工具服务，支持系统工具独立开发和调试。
2. 更新系统工具开发指南[系统工具开发指南](../../../guide/build/tools/system-plugins/dev_system_tool.mdx)。
3. 更新[系统工具设计文档](../../../guide/build/tools/system-plugins/dev_system_tool.mdx)。
2. 更新系统工具开发指南[系统工具开发指南](../../../plugin/system-tool-development.mdx)。
3. 更新[插件系统说明](../../../plugin/intro.mdx)。
document/content/toc.en.mdx
......@@ -19,7 +19,6 @@ description: FastGPT Toc
- [/en/guide/build/publish/wechat](/en/guide/build/publish/wechat)
- [/en/guide/build/publish/wecom](/en/guide/build/publish/wecom)
- [/en/guide/build/tools/mcp_tools](/en/guide/build/tools/mcp_tools)
- [/en/guide/build/tools/system-plugins/dev_system_tool](/en/guide/build/tools/system-plugins/dev_system_tool)
- [/en/guide/build/tools/system-plugins/upload_system_tool](/en/guide/build/tools/system-plugins/upload_system_tool)
- [/en/guide/build/workflow/intro](/en/guide/build/workflow/intro)
- [/en/guide/build/workflow/nodes/ai_chat](/en/guide/build/workflow/nodes/ai_chat)
......@@ -95,7 +94,6 @@ description: FastGPT Toc
- [/en/self-host/deploy/docker](/en/self-host/deploy/docker)
- [/en/self-host/deploy/sealos](/en/self-host/deploy/sealos)
- [/en/self-host/design/dataset](/en/self-host/design/dataset)
- [/en/self-host/design/design_plugin](/en/self-host/design/design_plugin)
- [/en/self-host/dev](/en/self-host/dev)
- [/en/self-host/index](/en/self-host/index)
- [/en/self-host/migration/docker_db](/en/self-host/migration/docker_db)
......
document/content/toc.mdx
......@@ -19,7 +19,6 @@ description: FastGPT 文档目录
- [/guide/build/publish/wechat](/guide/build/publish/wechat)
- [/guide/build/publish/wecom](/guide/build/publish/wecom)
- [/guide/build/tools/mcp_tools](/guide/build/tools/mcp_tools)
- [/guide/build/tools/system-plugins/dev_system_tool](/guide/build/tools/system-plugins/dev_system_tool)
- [/guide/build/tools/system-plugins/upload_system_tool](/guide/build/tools/system-plugins/upload_system_tool)
- [/guide/build/workflow/intro](/guide/build/workflow/intro)
- [/guide/build/workflow/nodes/ai_chat](/guide/build/workflow/nodes/ai_chat)
......@@ -95,7 +94,6 @@ description: FastGPT 文档目录
- [/self-host/deploy/docker](/self-host/deploy/docker)
- [/self-host/deploy/sealos](/self-host/deploy/sealos)
- [/self-host/design/dataset](/self-host/design/dataset)
- [/self-host/design/design_plugin](/self-host/design/design_plugin)
- [/self-host/dev](/self-host/dev)
- [/self-host/index](/self-host/index)
- [/self-host/migration/docker_db](/self-host/migration/docker_db)
......
document/data/doc-last-modified.json
......@@ -33,8 +33,6 @@
"content/guide/build/publish/wecom.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/build/tools/mcp_tools.en.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/build/tools/mcp_tools.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/build/tools/system-plugins/dev_system_tool.en.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/build/tools/system-plugins/dev_system_tool.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/build/tools/system-plugins/upload_system_tool.en.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/build/tools/system-plugins/upload_system_tool.mdx": "2026-05-07T15:06:40+08:00",
"content/guide/build/workflow/intro.en.mdx": "2026-05-07T15:06:40+08:00",
......@@ -185,8 +183,6 @@
"content/self-host/deploy/sealos.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/design/dataset.en.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/design/dataset.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/design/design_plugin.en.mdx": "2026-06-04T16:10:15+08:00",
"content/self-host/design/design_plugin.mdx": "2026-06-04T16:10:15+08:00",
"content/self-host/dev.en.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/dev.mdx": "2026-04-26T21:08:47+08:00",
"content/self-host/index.en.mdx": "2026-04-26T21:08:47+08:00",
......@@ -418,4 +414,4 @@
"content/self-host/upgrading/upgrade-intruction.mdx": "2026-04-26T21:08:47+08:00",
"content/toc.en.mdx": "2026-06-04T16:10:15+08:00",
"content/toc.mdx": "2026-06-04T16:10:15+08:00"
}
\ No newline at end of file
}
projects/app/src/pages/config/tool/marketplace.tsx
......@@ -483,7 +483,7 @@ const ToolkitMarketplace = ({ marketplaceUrl }: { marketplaceUrl: string }) => {
{feConfigs?.docUrl && (
<Button
onClick={() => {
const url = getDocPath('/guide/build/tools/system-plugins/dev_system_tool');
const url = getDocPath('/plugin/system-tool-development');
if (url) {
window.open(url, '_blank');
}
......
projects/app/src/pages/dashboard/systemTool/index.tsx
......@@ -109,7 +109,7 @@ const ToolKitProvider = ({ MenuIcon }: { MenuIcon: JSX.Element }) => {
mr={4}
onClick={() =>
window.open(
getDocPath('/guide/build/tools/system-plugins/dev_system_tool'),
getDocPath('/plugin/system-tool-development'),
'_blank'
)
}
......
projects/marketplace/src/pages/index.tsx
......@@ -242,7 +242,7 @@ const ToolkitMarketplace = () => {
<Button
onClick={() => {
window.open(
'https://doc.fastgpt.io/guide/build/tools/system-plugins/dev_system_tool',
'https://doc.fastgpt.io/plugin/system-tool-development',
'_blank'
);
}}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment