Skip to content

README.md

Latest commit

 

History

History
334 lines (281 loc) · 9.65 KB

README.md

File metadata and controls

334 lines (281 loc) · 9.65 KB
Raw

FastGPT Plugin SDK Factory

语言：简体中文 | English

用于构建 FastGPT Tool Plugin 的 TypeScript SDK。它把插件声明、输入输出校验、密钥配置、运行时通信和流式响应封装成少量 API，让工具开发者专注于业务逻辑。

TypeScript SDK for building FastGPT Tool Plugins. It wraps plugin metadata, input/output validation, secret configuration, runtime communication, and streaming responses behind a small API surface so tool authors can focus on business logic.

安装 / Installation

pnpm add @fastgpt-plugin/sdk-factory zod

在 monorepo 内开发时可直接使用 workspace 依赖。

When developing inside this monorepo, use the workspace dependency directly.

快速开始 / Quick Start

插件入口文件需要默认导出 defineTool() 或 defineToolSet() 返回的实例。

The plugin entry file must default-export the instance returned by defineTool() or defineToolSet().

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().meta({
      title: 'Text'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    result: z.string().meta({
      title: 'Result'
    } satisfies OutputSchemaMetaType)
  }),
  handler: async (input) => {
    return {
      result: input.text.toUpperCase()
    };
  }
});

export default defineTool({
  manifest: {
    pluginId: 'uppercase',
    version: '1.0.0',
    name: {
      en: 'Uppercase',
      'zh-CN': '转大写'
    },
    description: {
      en: 'Convert text to uppercase',
      'zh-CN': '将文本转换为大写'
    },
    versionDescription: {
      en: 'Initial version',
      'zh-CN': '初始版本'
    },
    tags: ['tools']
  },
  handler
});

API / API

createToolHandler(definition)

定义工具处理器，并通过 Zod schema 推导 input、output 和 secrets 类型。

Defines a tool handler and infers input, output, and secrets types from Zod schemas.

const handler = createToolHandler({
  inputSchema: z.object({
    query: z.string().meta({
      title: 'Query'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    answer: z.string().meta({
      title: 'Answer'
    } satisfies OutputSchemaMetaType)
  }),
  secretSchema: z.object({
    apiKey: z.string().meta({
      title: 'API Key',
      isSecret: true
    } satisfies SecretSchemaMetaType)
  }),
  handler: async (input, ctx) => {
    ctx.streamResponse({
      type: 'answer',
      content: `Searching: ${input.query}`
    });

    return {
      answer: `Result for ${input.query} with ${ctx.secrets?.apiKey}`
    };
  }
});

处理器上下文包含：

The handler context includes:

字段 / Field 说明 / Description
systemVar FastGPT 注入的系统变量。System variables injected by FastGPT.
secrets 按 secretSchema 校验后的密钥配置。Secret values validated by secretSchema.
invoke 反向调用宿主能力的客户端，例如上传文件。Client for invoking host capabilities, such as file upload.
streamResponse 发送流式工具回答。Sends streaming tool answers.

defineTool(options)

定义单个工具插件。manifest 描述插件基础信息，handler 是工具执行逻辑。

Defines a single-tool plugin. manifest describes the plugin metadata, and handler contains the execution logic.

export default defineTool({
  manifest,
  handler
});

defineToolSet(options)

定义一个包含多个子工具的工具集。所有子工具共用顶层 manifest，每个子工具拥有独立的 id、名称、描述和 handler。

Defines a tool set with multiple child tools. All child tools share the top-level manifest; each child tool has its own id, name, description, and handler.

const searchHandler = createToolHandler({
  inputSchema: z.object({
    query: z.string().meta({
      title: 'Query'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    items: z.array(z.string()).meta({
      title: 'Items'
    } satisfies OutputSchemaMetaType)
  }),
  handler: async (input) => ({ items: [input.query] })
});

const summaryHandler = createToolHandler({
  inputSchema: z.object({
    content: z.string().meta({
      title: 'Content'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    summary: z.string().meta({
      title: 'Summary'
    } satisfies OutputSchemaMetaType)
  }),
  handler: async (input) => ({ summary: input.content.slice(0, 100) })
});

export default defineToolSet({
  manifest: {
    pluginId: 'text-tools',
    version: '1.0.0',
    name: {
      en: 'Text Tools',
      'zh-CN': '文本工具集'
    },
    description: {
      en: 'Search and summarize text',
      'zh-CN': '搜索和总结文本'
    }
  },
  children: [
    {
      id: 'search',
      name: {
        en: 'Search',
        'zh-CN': '搜索'
      },
      description: {
        en: 'Search text',
        'zh-CN': '搜索文本'
      },
      toolDescription: 'Search text by query',
      handler: searchHandler
    },
    {
      id: 'summary',
      name: {
        en: 'Summary',
        'zh-CN': '总结'
      },
      description: {
        en: 'Summarize text',
        'zh-CN': '总结文本'
      },
      toolDescription: 'Summarize text content',
      handler: summaryHandler
    }
  ]
});

Manifest / 插件声明

manifest 使用中英文国际化字段，常用字段如下：

manifest uses bilingual i18n fields. Common fields:

字段 / Field 必填 / Required 说明 / Description
pluginId 是 / Yes 插件唯一 ID。Unique plugin ID.
version 是 / Yes 插件版本。Plugin version.
name 是 / Yes 插件名称，格式为 { en, 'zh-CN' }。Plugin name in { en, 'zh-CN' } format.
description 是 / Yes 插件描述，格式为 { en, 'zh-CN' }。Plugin description in { en, 'zh-CN' } format.
versionDescription 否 / No 版本说明。Version description.
author 否 / No 作者。Author.
repoUrl 否 / No 仓库地址。Repository URL.
tutorialUrl 否 / No 教程地址。Tutorial URL.
tags 否 / No 插件标签。Plugin tags.
permission 否 / No 插件权限声明。Plugin permission declarations.
icon 否 / No 插件图标；构建流程可自动补齐。Plugin icon; the build pipeline can fill it automatically.
toolDescription 否 / No 面向模型的工具说明；构建流程可自动补齐。Tool description for the model; the build pipeline can fill it automatically.

Secret 配置 / Secret Configuration

单工具可在 handler 内声明 secretSchema。工具集可在 defineToolSet() 顶层声明共用 secretSchema。

A single tool can declare secretSchema in its handler. A tool set can declare a shared secretSchema at the top level of defineToolSet().

Schema 字段元数据通过 Zod .meta() 写入构建后的 JSON Schema。输入字段使用 InputSchemaMetaType，输出字段使用 OutputSchemaMetaType，密钥字段使用 SecretSchemaMetaType。secretSchema 的每个字段都要包含 isSecret，需要加密存储时设为 true。

Schema field metadata is written into the built JSON Schema through Zod .meta(). Use InputSchemaMetaType for input fields, OutputSchemaMetaType for output fields, and SecretSchemaMetaType for secret fields. Every secretSchema field must include isSecret; set it to true for values that need encrypted storage.

const secretSchema = z.object({
  apiKey: z.string().meta({
    title: 'API Key',
    isSecret: true
  } satisfies SecretSchemaMetaType),
  baseURL: z.url().meta({
    title: 'Base URL',
    isSecret: false
  } satisfies SecretSchemaMetaType)
});

const handler = createToolHandler({
  inputSchema: z.object({
    prompt: z.string().meta({
      title: 'Prompt'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    text: z.string().meta({
      title: 'Text'
    } satisfies OutputSchemaMetaType)
  }),
  secretSchema,
  handler: async (input, ctx) => {
    return {
      text: `${input.prompt}:${ctx.secrets?.apiKey}`
    };
  }
});

反向调用 / Host Invocation

ctx.invoke 用于调用 FastGPT 宿主能力。目前 SDK 提供文件上传能力。

Use ctx.invoke to call FastGPT host capabilities. The SDK currently exposes file upload.

const handler = createToolHandler({
  inputSchema: z.object({
    content: z.string().meta({
      title: 'Content'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    accessURL: z.string().meta({
      title: 'Access URL'
    } satisfies OutputSchemaMetaType),
    fileName: z.string().meta({
      title: 'File Name'
    } satisfies OutputSchemaMetaType),
    size: z.number().meta({
      title: 'Size'
    } satisfies OutputSchemaMetaType)
  }),
  handler: async (input, { invoke }) => {
    const [result, err] = await invoke.uploadFile({
      fileName: 'result.txt',
      contentType: 'text/plain',
      file: Buffer.from(input.content, 'utf-8')
    });

    if (err) {
      throw err;
    }
    if (!result) {
      throw new Error('Failed to upload file');
    }

    return {
      accessURL: result.accessURL,
      fileName: result.fileName,
      size: result.size
    };
  }
});

构建 / Build

pnpm --filter @fastgpt-plugin/sdk-factory build

构建后包入口为 dist/index.js，类型声明为 dist/index.d.ts。

After build, the package entry is dist/index.js and type declarations are emitted to dist/index.d.ts.