企业官网建设流程全解析

如何开发并安装 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（版本满足目标插件仓库要求）、pnpm（fastgpt-plugin仓库使用 pnpm workspace）、Git、GitHub CLIgh（用于 fork、创建仓库和提交 PR）。

社区插件在fastgpt-community-plugins仓库中维护，先 fork 并 clone：

gh repo fork labring/fastgpt-community-plugins --clone cd fastgpt-community-plugins pnpm install

如果你是在fastgpt-plugin仓库内调试 CLI 或 SDK 本身，则改为先安装依赖并构建 CLI/SDK：

pnpm 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），按提示选择类型。

创建完成后，插件目录中会生成以下常见文件：

实现插件代码

系统工具入口必须默认导出 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命令快速验证插件逻辑和 schema：

cd 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指定子工具 ID：

pnpx @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 接入配置，需要按 远程调试功能套件配置 额外部署（该功能套件仅商业版支持）。

生成调试链接：

1. 登录 FastGPT 测试环境。
2. 进入「系统工具」页面，点击「本地调试」。

3. 在弹窗中点击「生成链接」，复制生成的调试链接。已有调试会话时可点击「刷新链接」生成新的 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?connectionKey=fpg_dbg_..."

上例中的https://fastgpt.example.com和fpg_dbg_...是文档示例值，需要替换为你测试环境的实际地址和页面生成的链接。如果只传入裸 connection key，需要让 CLI 知道 exchange 接口地址：

FASTGPT_PLUGIN_DEBUG_CONNECT_URL=https://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会绑定到当前登录成员，其他成员默认看不到该调试插件。

结束调试：本地终端按Ctrl+C关闭当前 CLI 调试会话，再次按Ctrl+C强制退出；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 界面上传和更新系统工具进行热更新，安装后全系统可见。

1. 使用root账户登录 FastGPT（只有 root 用户能看到并使用「导入/更新」按钮）。
2. 进入系统工具配置页面。

3. 选择准备好的.pkg文件，确认文件信息无误后点击「确认导入」。上传成功后页面自动刷新，新工具会出现在工具列表中。

约束：文件类型必须是.pkg，单个最大 100 MB，每次最多上传 15 个文件。删除已上传的工具同样仅限 root 用户。

团队级安装（团队管理员/团队所有者）：当系统管理员已开启「团队上传插件」功能时，团队插件只在当前团队内生效，安装入口是工作台的「工具」页面：

1. 点击「添加插件」，选择「上传插件」。
2. 选择一个或多个.pkg文件，也可以选择包含多个.pkg文件的.zip文件。
3. 等待系统上传并解析插件包，检查插件名称、版本、权限和解析结果——解析失败的文件会单独显示错误，可以修复后重试。
4. 确认安装，插件会出现在团队工具列表中。

上传和解析只用于预览待安装内容，完成确认后插件才会正式安装到当前团队。注意团队插件不会继承同 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