快速开始：开发首个工具插件

本文指导你使用 @fastgpt-plugin/cli 与 @fastgpt-plugin/sdk-factory 在本地完成首个系统工具插件的开发全流程。

准备工作

开始前请确认本地环境已具备：

Node.js：Node.js 22（>= 22.23.2）。
pnpm：pnpm 10。
FastGPT：v4.15.0 及以上版本运行实例。
FastGPT Plugin：v1.0.0 及以上版本插件服务。
Git：用于版本控制与代码提交。

步骤 1：创建插件骨架

通过官方 CLI 初始化单工具插件：

pnpx @fastgpt-plugin/cli create hello-tool --type tool

命令执行后会在当前目录下生成 hello-tool 项目，包含如下标准目录结构：

hello-tool/
├── index.ts          # 插件入口，默认导出 defineTool
├── index.spec.ts     # 单元测试文件
├── package.json      # 构建、检查、调试与打包脚本
├── tsconfig.json     # TypeScript 配置
├── vitest.config.ts  # 测试配置
├── logo.svg          # 插件图标
├── README.md         # 默认插件说明
├── README.zh-CN.md   # 简体中文说明
└── README.en.md      # 英文说明

进入目录并安装依赖：

cd hello-tool
pnpm install

步骤 2：编写工具逻辑与 Schema

打开 index.ts，定义工具的元信息、输入 Schema、输出 Schema 以及执行处理函数：

import {
  createToolHandler,
  defineTool,
  type InputSchemaMetaType,
  type OutputSchemaMetaType
} from '@fastgpt-plugin/sdk-factory';
import z from 'zod';

const handler = createToolHandler({
  inputSchema: z.object({
    name: z
      .string()
      .min(1)
      .default('FastGPT')
      .meta({
        title: {
          en: 'User Name',
          'zh-CN': '用户名称'
        },
        description: {
          en: 'Name of the user to greet',
          'zh-CN': '输入需要问候的用户名称'
        },
        isToolParam: true
      } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    greeting: z.string().meta({
      title: '问候语'
    } satisfies OutputSchemaMetaType)
  }),
  handler: async (input) => {
    return {
      greeting: `Hello, ${input.name}!`
    };
  }
});

export default defineTool({
  manifest: {
    pluginId: 'hello-tool',
    version: '1.0.0',
    name: {
      en: 'Hello Tool',
      'zh-CN': '问候工具'
    },
    description: {
      en: 'Greet the user with a friendly message',
      'zh-CN': '输出友好的问候信息'
    },
    versionDescription: {
      en: 'Initial release',
      'zh-CN': '初始版本'
    },
    tags: ['tools']
  },
  handler
});

核心要素说明：

manifest.pluginId：全局唯一插件标识，命名建议保持全小写连字符形式。
manifest.name 与 manifest.description：支持中英文双语，FastGPT 工作台将根据当前用户语言自动展示对应文本。
inputSchema 与 outputSchema：通过 Zod 声明输入输出类型，并通过 .meta() 丰富 UI 显示属性。
handler：实际业务逻辑执行函数，返回值需与 outputSchema 结构严格匹配。

步骤 3：验证输入

在插件目录运行以下命令，检查默认值和空字符串约束：

pnpx @fastgpt-plugin/cli debug . --run --input '{}'
pnpx @fastgpt-plugin/cli debug . --run --input '{"name":""}'

第一次调用的结果应包含 "greeting": "Hello, FastGPT!"。第二次调用应报告输入校验错误，因为 name 至少需要一个字符。这两个用例分别覆盖 Schema 的默认值与无效输入行为。

步骤 4：本地调试运行

使用 CLI 本地调试命令，模拟参数输入并实时查看输出：

pnpx @fastgpt-plugin/cli debug . --run --input '{"name": "FastGPT User"}'

检查调试结果中包含以下输出：

{
  "greeting": "Hello, FastGPT User!"
}

步骤 5：构建与打包

测试通过后，执行标准构建与打包指令：

pnpm run build
pnpx @fastgpt-plugin/cli check --entry . --output ./dist
pnpm run pack

命令执行后会在插件根目录生成 hello-tool.pkg 安装文件（可通过 --output 指定其他输出目录）。产物内容见插件包与 SDK 参考。

步骤 6：在 FastGPT 中安装与调用验证

生成 .pkg 插件包后，即可在 FastGPT 中完成端到端安装与调用验收：

安装插件：
- 开源社区版：使用 root 系统管理员账号登录，进入左下角管理员 → 系统工具，点击右上角安装工具 → 从本地安装，上传刚构建的 hello-tool.pkg 并点击确认导入。
- 商业版：系统管理员可在管理员 → 系统资源 → 系统工具 → 安装工具 → 从本地安装中导入；若系统管理员已在管理员 → 系统配置 → 功能清单中开启允许团队上传插件，团队管理员或所有者也可在工作台 → 系统工具 → + 安装工具 → 从本地安装中导入。
应用配置：进入任意工作流或对话 Agent 应用的编辑画布，在工具列表中选择并添加刚安装的“问候工具”（hello-tool）。
验证执行结果：在应用调试预览中发起对话触发工具调用，并在运行详情中查看节点输出。成功输出包含：

{
  "greeting": "Hello, FastGPT!"
}

至此已完成从代码编写、本地校验、构建打包到应用调用的完整扩展交付闭环。

下一步

深入学习单工具与工具集的进阶开发规范：系统工具开发指南
掌握本地联调、远程调试与打包发布渠道：调试、打包与发布
在团队工作台中安装已生成的插件包并接入工作流：团队安装与管理插件

快速开始：开发首个工具插件

本页导航