FastGPT系统工具插件的开发流程与配置说明

插件基础说明

本文面向FastGPT v4.15.0及以上版本的系统工具开发，新版插件系统将系统工具、模型预设统一抽象为可安装更新的.pkg格式插件包，支持单工具和工具集两种类型：单工具使用defineTool()声明，一个插件仅暴露一个工具；工具集使用defineToolSet()声明，可暴露多个相关子工具。插件运行在FastGPT Plugin服务的隔离运行时中，主服务通过插件服务调用工具，插件代码通过@fastgpt-plugin/sdk-factory定义输入输出、密钥配置与执行逻辑。

开发前置准备

开始开发前需明确以下核心信息：插件类型（tool或tool-suite）、全局唯一的插件ID、工具集需配置固定的子工具ID、中英文名称与描述、输入输出字段的类型约束与UI说明、密钥配置（如API Key、Base URL）、外部API调用规则与测试样例。开发环境需准备Node.js、pnpm、Git与GitHub CLI，开发社区插件时可通过gh repo fork labring/fastgpt-community-plugins --clone克隆仓库并执行pnpm install安装依赖。

快速开发步骤

创建插件骨架：单工具插件执行pnpx @fastgpt-plugin/cli create my-tool --type tool --cwd packages/tools，工具集插件替换--type为tool-suite即可。生成的目录包含入口文件index.ts、依赖配置package.json等基础文件。
实现插件逻辑：单工具插件需在index.ts中默认导出SDK实例，示例代码需导入createToolHandler、defineTool与zod库，定义密钥schema（如z.object({ apiKey: z.string().min(1).meta({ title: "API Key", isSecret: true }) })）、输入输出schema，最后编写执行逻辑，支持通过ctx.invoke.uploadFile()处理文件上传、ctx.streamResponse()实现流式输出。
验证与打包：执行pnpm test完成测试，pnpm build构建产物，pnpm pack生成最终的.pkg插件包。