如何开发并安装 FastGPT V4.15 的 .pkg 格式系统工具插件【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT如果你想在 FastGPT v4.15.0 之后的版本中为工作流和 Agent 添加一个自定义系统工具目标就是把插件打包成.pkg文件并安装到部署好的 FastGPT 环境中。新版 FastGPT Plugin 服务把系统工具统一抽象为可安装、可更新、可运行隔离的插件包FastGPT 主服务通过插件服务调用工具插件代码通过fastgpt-plugin/sdk-factory描述输入、输出、密钥配置和执行逻辑。本文按“开发环境 → 创建骨架 → 实现 → 本地调试 → 远程调试 → 构建打包 → 安装到 FastGPT”的顺序走一遍完整流程内容来自仓库中的 系统工具开发指南、系统工具在线上传指南 和 团队安装与管理插件。开始前的准备版本与架构前提开发指南面向 FastGPT v4.15.0 之后的系统工具开发插件最终由.pkg文件交付给 FastGPT Plugin 服务。FastGPT 与 FastGPT Plugin 保持外置扩展的微服务部署关系插件运行在 FastGPT Plugin 服务提供的运行时中当前默认运行时是local-pool。当前稳定支持的插件类型有两种单工具tool一个插件只暴露一个工具使用defineTool()声明工具集tool-suite一个插件暴露多个相关子工具使用defineToolSet()声明。开发机环境Node.js版本满足目标插件仓库要求、pnpmfastgpt-plugin仓库使用 pnpm workspace、Git、GitHub CLIgh用于 fork、创建仓库和提交 PR。社区插件在fastgpt-community-plugins仓库中维护先 fork 并 clonegh repo fork labring/fastgpt-community-plugins --clone cd fastgpt-community-plugins pnpm install如果你是在fastgpt-plugin仓库内调试 CLI 或 SDK 本身则改为先安装依赖并构建 CLI/SDKpnpm install pnpm build:sdk-factory pnpm build:cli开发前建议先确认插件类型、pluginId全局稳定唯一发布后不变、子工具 ID、中英文名称与描述、输入输出字段、密钥结构以及外部 API 的行为这些信息会直接进入 manifest 和 schema发布后pluginId、子工具id、输入输出字段名都应保持稳定。用 CLI 创建插件骨架在fastgpt-community-plugins仓库内用fastgpt-plugin/cli创建骨架pnpx fastgpt-plugin/cli create my-tool --type tool --cwd packages/tools工具集插件用--type tool-suite也可以进入目标目录后交互式创建pnpx fastgpt-plugin/cli create按提示选择类型。创建完成后插件目录中会生成以下常见文件文件作用index.ts插件入口默认导出defineTool()或defineToolSet()。package.json插件依赖和build、build:dev、pack、test脚本。tsconfig.jsonTypeScript 配置。vitest.config.ts测试配置。README.md插件说明。logo.svg插件主图标。实现插件代码系统工具入口必须默认导出 SDK factory 实例。以单工具为例下面是开发指南中的完整示例其中example-search、1.0.0等均为文档示例值按你的插件替换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 });编码时需要遵守的核心规则输入、输出和密钥都用 Zod schema 描述输入字段补InputSchemaMetaType输出字段补OutputSchemaMetaType密钥字段补SecretSchemaMetaType敏感字段设置isSecret: true。handler 返回值必须匹配outputSchema外部 API 错误要转成可定位的信息并避免输出密钥、令牌和完整敏感响应。密钥通过secretSchema声明、用ctx.secrets读取不要把 API Key 写进代码或环境变量。需要上传文件时用ctx.invoke.uploadFile()需要展示中间进度时用ctx.streamResponse()。如果你的插件是多个共享鉴权、共享上游 API 的强相关能力比如搜索、详情、创建任务改用defineToolSet()共用信息放在顶层manifest和secretSchema每个子工具在children中声明独立id、名称、描述和 handler。图标CLI 构建时会扫描插件根目录中的图标并写入构建后的manifest.json。主插件图标文件名为logo.svg、logo.png、logo.jpg、logo.jpeg、logo.webp或logo.gif工具集子工具图标命名为childId.logo.svg等childId与children[].id完全一致子工具没有独立图标时默认复用主插件图标。同一个图标只保留一个扩展名构建后检查dist/manifest.json中的icon字段。本地调试先进入插件目录安装依赖再用 CLI 的debug命令快速验证插件逻辑和 schemacd packages/tools/my-tool pnpm install查看插件和可调试工具信息pnpx fastgpt-plugin/cli debug .执行一次单工具调试--input、--secrets为示例参数替换成你插件 schema 中定义的字段和测试值pnpx fastgpt-plugin/cli debug . --run --input {query:hello} --secrets {apiKey:test}执行工具集中的某个子工具时加--tool指定子工具 IDpnpx fastgpt-plugin/cli debug . --run --tool search --input {query:hello} --secrets {apiKey:test}输入、密钥和系统变量较大时改用文件传入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 不模拟生产子进程池、真实 Node.js IPC、网络环境、服务端超时和队列调度所以它通过之后仍需测试环境验证。远程调试接入 FastGPT 测试环境远程调试用于把本地正在开发的插件接入 FastGPT 测试环境FastGPT 页面负责鉴权并生成调试链接CLI 通过该链接建立 WSS 调试通道调试插件仅对当前调试者本人可见。前提测试环境已部署 FastGPT Plugin 服务和 Connection Gateway并且本地开发机可以访问测试环境返回的 Gateway WSS 地址。自部署时默认的 Docker Compose 部署脚本只包含 FastGPT 主服务和常规fastgpt-plugin运行环境不包含 Connection Gateway 的公网 WebSocket 接入配置需要按 远程调试功能套件配置 额外部署该功能套件仅商业版支持。生成调试链接登录 FastGPT 测试环境。进入「系统工具」页面点击「本地调试」。在弹窗中点击「生成链接」复制生成的调试链接。已有调试会话时可点击「刷新链接」生成新的 connection key旧链接会失效。调试链接只用于本地 CLI 连接测试环境不要提交到代码仓库、文档示例或聊天记录中。启动本地调试会话在插件目录或包含多个插件目录的工作区中运行fastgpt-plugin dev启动后把页面复制的调试链接粘贴到 TUI 中。CLI 会用链接中的 connection key 换取短期 WSS connect token并把本地插件挂载到 FastGPT 的调试通道。脚本或 Agent 场景可以使用非交互模式fastgpt-plugin dev --no-interactive \ --connect https://fastgpt.example.com/api/plugin/debug-channel/connection-key/exchange?connectionKeyfpg_dbg_...上例中的https://fastgpt.example.com和fpg_dbg_...是文档示例值需要替换为你测试环境的实际地址和页面生成的链接。如果只传入裸 connection key需要让 CLI 知道 exchange 接口地址FASTGPT_PLUGIN_DEBUG_CONNECT_URLhttps://fastgpt.example.com/api/plugin/debug-channel/connection-key/exchange \ fastgpt-plugin dev --no-interactive --connect fpg_dbg_...--connect成功连接后会保存 connection key后续可直接运行fastgpt-plugin dev复用本地配置TUI 中按c可重新输入并保存新的调试链接。dev未传插件目录时会自动探测当前目录当前目录存在index.ts时使用当前目录否则扫描下一层子目录也可以手动传入fastgpt-plugin dev ./plugins/getTime ./plugins/dbops --watch--watch会在本地文件变化后重新加载插件并重建远程调试会话CLI 默认开启断线重连需要关闭时加--no-reconnect。在 FastGPT 中验证CLI 显示远程调试已就绪后回到测试环境——在「系统工具」页面查看调试插件在应用、工作流或 Agent 中选择该调试工具填写密钥和输入参数发起真实调用并在 CLI 终端查看本地 handler 日志和错误信息。调试工具的source会绑定到当前登录成员其他成员默认看不到该调试插件。结束调试本地终端按CtrlC关闭当前 CLI 调试会话再次按CtrlC强制退出FastGPT 页面中的「结束调试」会撤销当前成员的 debug channel 并清理页面上的调试插件入口。链接泄露或需要重新授权时优先使用「刷新链接」。构建、检查与打包出 .pkg 文件在插件目录中依次运行测试、构建、检查和打包pnpm run test pnpm run build pnpx fastgpt-plugin/cli check --entry . --output ./dist pnpm run pack也可以显式传入目录packages/tools/my-tool为你的插件实际路径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文件。打包前对照开发指南的验证清单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 安装到 FastGPT系统插件有两级安装入口按角色选择其一系统级安装root 用户从 FastGPT 4.14.0 起root 用户可以通过 Web 界面上传和更新系统工具进行热更新安装后全系统可见。使用root账户登录 FastGPT只有 root 用户能看到并使用「导入/更新」按钮。进入系统工具配置页面。选择准备好的.pkg文件确认文件信息无误后点击「确认导入」。上传成功后页面自动刷新新工具会出现在工具列表中。约束文件类型必须是.pkg单个最大 100 MB每次最多上传 15 个文件。删除已上传的工具同样仅限 root 用户。团队级安装团队管理员/团队所有者当系统管理员已开启「团队上传插件」功能时团队插件只在当前团队内生效安装入口是工作台的「工具」页面点击「添加插件」选择「上传插件」。选择一个或多个.pkg文件也可以选择包含多个.pkg文件的.zip文件。等待系统上传并解析插件包检查插件名称、版本、权限和解析结果——解析失败的文件会单独显示错误可以修复后重试。确认安装插件会出现在团队工具列表中。上传和解析只用于预览待安装内容完成确认后插件才会正式安装到当前团队。注意团队插件不会继承同 ID 系统插件的密钥、费用、状态、版本或其他配置需要单独完成密钥和运行参数配置。普通成员只能使用已安装的插件无法安装、更新或删除看不到「上传插件」选项时通常是系统管理员关闭了「团队上传插件」功能。安装后的验证在工具列表中确认插件已出现工具需要密钥或其他运行参数时首次使用前先完成对应配置然后在应用、工作流或 Agent 的工具选择器中选择该插件填写密钥和输入参数发起一次真实调用确认输出符合outputSchema的预期行为。常见问题本地 debug 通过后还需要测试环境验证吗需要。本地 debug 用于快速验证插件逻辑和 schema测试环境验证用于确认真实安装、运行时、宿主反向调用、网络和权限行为。上架官方插件前仍需在测试环境手动安装.pkg并完成端到端测试。tool和tool-suite如何选单一能力使用tool多个共享鉴权、共享上游 API、业务上强相关的能力使用tool-suite。插件版本怎么管理manifest.version使用语义化版本修复兼容性问题升级 patch新增兼容功能升级 minor修改输入输出字段、子工具 ID 或用户配置方式时升级 major并提前评估已有工作流兼容性。限制与下一步开发指南不再以旧版config.ts、versionList和bun run build:pkg作为主要开发方式而 在线上传系统工具 文档仍描述.pkg来自 fastgpt-plugin 项目中bun run build:pkg打包后的dist/pkgs目录该说法面向 4.14.0 起的上传功能。两处文档的打包方式描述存在差异按 4.15 开发指南使用pack命令生成的.pkg上传即可。远程调试链路Plugin Server Connection Gateway Redis仅商业版支持自部署需额外维护优先在云服务版本中使用。如果插件需要被社区使用下一步是把插件目录建成独立仓库并向fastgpt-community-plugins提交 submodule 或引用更新、发起 PR官方插件还需完成代码 review、测试环境手动安装.pkg、完整功能测试外部 API、密钥配置、错误路径、并发调用和上架前安全检查重点关注 SSRF、密钥泄露、任意文件访问、命令执行和依赖风险。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考