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

> 创建问候工具，验证输入与输出，并构建可安装的插件包

Source: https://doc.fastgpt.cn/zh-CN/plugin/quick-start

本文指导你使用 `@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 初始化单工具插件：

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

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

```text
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      # 英文说明
```

进入目录并安装依赖：

```bash
cd hello-tool
pnpm install
```

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

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

```ts
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：验证输入

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

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

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

## 步骤 4：本地调试运行

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

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

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

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

## 步骤 5：构建与打包

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

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

命令执行后会在插件根目录生成 `hello-tool.pkg` 安装文件（可通过 `--output` 指定其他输出目录）。产物内容见[插件包与 SDK 参考](/zh-CN/plugin/package-reference#构建产物)。

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

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

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

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

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

## 下一步

* 深入学习单工具与工具集的进阶开发规范：[系统工具开发指南](/zh-CN/plugin/system-tool-development)
* 掌握本地联调、远程调试与打包发布渠道：[调试、打包与发布](/zh-CN/plugin/debugging-and-publishing)
* 在团队工作台中安装已生成的插件包并接入工作流：[团队安装与管理插件](/zh-CN/plugin/team-installation)