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 11 additions and 188 deletions
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/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