FastGPT 系统工具开发规范 Skill

FastGPT 系统工具开发规范

在编写 FastGPT 系统工具插件时使用这个 skill。目标是指导代理用 @fastgpt-plugin/sdk-factory 写出符合 FastGPT 约定的系统工具，并用 @fastgpt-plugin/cli 创建、构建、检查和打包。

使用工具

同时参考这些能力：

fastgpt-sdk-factory: 处理 defineTool()、defineToolSet()、createToolHandler()、Zod schema、secretSchema、ctx.invoke、ctx.streamResponse() 等 SDK 写法。
cli-usage: 使用 @fastgpt-plugin/cli 的 create、build、check、pack 命令。

常用命令：

npx @fastgpt-plugin/cli create <plugin-name> --type tool --cwd <target-directory>

npx @fastgpt-plugin/cli create <plugin-name> --type tool-suite --cwd <target-directory>

npx @fastgpt-plugin/cli build --entry <plugin-directory> --output <plugin-directory>/dist

npx @fastgpt-plugin/cli check --entry <plugin-directory> --output <plugin-directory>/dist

npx @fastgpt-plugin/cli pack --entry <plugin-directory> --dist <plugin-directory>/dist --output <plugin-directory>/out

系统工具包含内容

一个系统工具目录通常包含：

index.ts: 系统工具入口，默认导出 defineTool() 或 defineToolSet() 的返回值。
package.json: 声明依赖和 build、build:dev、pack、test 脚本。
logo.<ext>: 主工具头像，必须放在工具根目录。
README.md: 工具用途、输入、输出、密钥配置和使用说明。
assets/: 可选资源目录，例如图标或示例资源。
dist/: CLI 构建输出目录，包含 index.js、manifest.json 和必要资源。
out/: CLI 打包输出目录，通常包含 .pkg 文件。

依赖建议：

运行依赖：@fastgpt-plugin/sdk-factory、zod。
开发依赖：@fastgpt-plugin/cli、typescript、vitest。

系统工具写法

入口文件必须默认导出 SDK factory 实例：

单工具使用 defineTool()。
多个相关工具组成一个插件时使用 defineToolSet()。
每个 handler 用 createToolHandler() 定义。
inputSchema 和 outputSchema 使用 z.object(...)。
inputSchema 字段使用 .meta({ ... } satisfies InputSchemaMetaType)。
inputSchema 字段需要被工具调用自动填参时，必须在 .meta() 中设置 toolDescription；未设置时该字段只能由用户手动指定。
outputSchema 字段使用 .meta({ ... } satisfies OutputSchemaMetaType)。
secretSchema 字段使用 .meta({ isSecret: true | false, ... } satisfies SecretSchemaMetaType)；需要加密存储的字段标记为 isSecret: true。
handler 返回值必须匹配 outputSchema。

manifest 至少包含：

pluginId: 稳定唯一工具 ID。
version: 工具版本。
name: { en, 'zh-CN' } 格式。
description: { en, 'zh-CN' } 格式。

常用可选字段：

versionDescription
author
repoUrl
tutorialUrl
tags
permission
icon
toolDescription

permission 用于声明插件运行时需要的宿主能力，类型为权限字符串数组。只声明当前插件实际使用的最小权限；没有使用对应能力时不要添加。使用 ctx.invoke 反向调用宿主能力时，必须声明对应权限。

当前可用权限：

userInfo:read: 读取用户信息，例如调用 ctx.invoke.userInfo()。
teamInfo:read: 读取团队信息。
model:read: 读取模型信息。
dataset:read: 读取知识库信息。
file-upload:allow: 上传文件，例如调用 ctx.invoke.uploadFile()。

兼容性要求：

pluginId、工具 id、输入字段名、输出字段名对外使用后保持稳定。
用户配置的密钥、API Key、Base URL 等使用 secretSchema 描述，通过 ctx.secrets 读取。
错误信息应能帮助定位问题，同时避免暴露密钥、令牌和完整上游敏感响应。
需要向用户展示执行进度时使用 ctx.streamResponse()。
需要生成文件时使用 ctx.invoke.uploadFile()，并在 manifest.permission 中声明 file-upload:allow；收到 [result, err] 的 err 时保留原始 err，避免覆盖反向调用的宿主错误信息。

头像规范

CLI 构建时会自动扫描系统工具根目录中的头像文件，并写入 manifest.icon 或子工具 icon 字段。工具代码里通常不用手写 icon。

命名方式：

主工具头像：logo.<ext>，例如 logo.svg、logo.png。
工具集子工具头像：<childId>.logo.<ext>，例如子工具 id 为 search 时使用 search.logo.svg。
子工具没有独立头像时，CLI 会复用主工具头像。

格式限制：

支持扩展名：.svg、.png、.jpg、.jpeg、.webp、.gif。
头像文件必须放在系统工具根目录，不能放在 assets/ 后再通过 manifest 引用。
childId 必须和 defineToolSet({ children }) 中的子工具 id 完全一致。
避免使用空格、中文或特殊符号作为头像文件名的一部分。
logo.* 和 <childId>.logo.* 只保留一个匹配文件，避免不同扩展名同时存在导致扫描结果不明确。
build 后检查 dist/manifest.json 中的 icon 字段是否指向已复制到 dist/ 的头像文件。

单工具模板

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

const handler = createToolHandler({
  inputSchema: z.object({
    text: z.string().min(1).meta({
      title: 'Text',
      toolDescription: 'Text to normalize'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    result: z.string().meta({
      title: 'Result'
    } satisfies OutputSchemaMetaType)
  }),
  handler: async (input) => {
    return {
      result: input.text.trim()
    };
  }
});

export default defineTool({
  manifest: {
    pluginId: 'text-normalizer',
    version: '1.0.0',
    name: {
      en: 'Text Normalizer',
      'zh-CN': '文本规范化'
    },
    description: {
      en: 'Normalize input text',
      'zh-CN': '规范化输入文本'
    },
    versionDescription: {
      en: 'Initial version',
      'zh-CN': '初始版本'
    },
    permission: []
  },
  handler
});

工具集模板

import {
  createToolHandler,
  defineToolSet,
  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 searchHandler = createToolHandler({
  inputSchema: z.object({
    query: z.string().min(1).meta({
      title: 'Query',
      toolDescription: 'Search query'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    items: z.array(z.string()).meta({
      title: 'Items'
    } satisfies OutputSchemaMetaType)
  }),
  secretSchema,
  handler: async (input, ctx) => {
    ctx.streamResponse({
      type: 'answer',
      content: `Searching: ${input.query}`
    });

    return {
      items: []
    };
  }
});

export default defineToolSet({
  secretSchema,
  manifest: {
    pluginId: 'example-search-tools',
    version: '1.0.0',
    name: {
      en: 'Example Search Tools',
      'zh-CN': '示例搜索工具集'
    },
    description: {
      en: 'Search public example data',
      'zh-CN': '搜索公开示例数据'
    },
    permission: []
  },
  children: [
    {
      id: 'search',
      name: {
        en: 'Search',
        'zh-CN': '搜索'
      },
      description: {
        en: 'Search by query',
        'zh-CN': '按查询搜索'
      },
      toolDescription: 'Search public example data by query',
      handler: searchHandler
    }
  ]
});

验证重点

index.ts 默认导出正确。
manifest 字段完整，国际化字段包含 en 和 zh-CN。
permission 只包含插件实际使用的权限，且权限值来自当前支持的枚举。
使用 ctx.invoke 时已在 manifest.permission 声明对应权限，例如上传文件声明 file-upload:allow。
Zod schema 覆盖全部用户可见输入和输出；需要工具调用自动填参的输入字段包含 toolDescription。
handler 成功路径返回值与 outputSchema 一致。
外部调用失败、空响应、超时、鉴权失败都有明确错误。
密钥配置只通过 secretSchema 和 ctx.secrets 处理。
系统工具根目录存在 logo.<ext>。
工具集子工具头像按 <childId>.logo.<ext> 命名，或确认复用主头像。
build 后存在 dist/index.js 和 dist/manifest.json。
check 通过后再执行 pack。

Agent Skills: FastGPT 系统工具开发规范

Install this agent skill to your local

Skill Files