fastgpt-sdk-factory
Use when creating, reviewing, or modifying FastGPT Tool Plugins with the @fastgpt-plugin/sdk-factory TypeScript SDK, including defineTool, defineToolSet, createToolHandler, Zod input/output schemas, secretSchema, ctx.invoke host calls, and streaming tool responses.
labring · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add labring/fastgpt-plugin --skill fastgpt-sdk-factoryAbout this skill
name: fastgpt-sdk-factory description: Use when creating, reviewing, or modifying FastGPT Tool Plugins with the @fastgpt-plugin/sdk-factory TypeScript SDK, including defineTool, defineToolSet, createToolHandler, Zod input/output schemas, secretSchema, ctx.invoke host calls, and streaming tool responses.
FastGPT SDK Factory
Use this skill when working on a FastGPT Tool Plugin that imports @fastgpt-plugin/sdk-factory or the local sdk/factory package.
Core Pattern
Plugin entry files 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',
isToolParam: true
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
result: z.string().meta({
title: 'Result'
} satisfies OutputSchemaMetaType)
}),
handler: async (input) => ({
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
});
Handler Rules
- Define handlers with
createToolHandler({ inputSchema, outputSchema, secretSchema?, handler }). - Use
z.object(...)forinputSchemaandoutputSchemaso TypeScript can inferinputand return types. - Import
InputSchemaMetaType,OutputSchemaMetaType, andSecretSchemaMetaTypefrom@fastgpt-plugin/sdk-factorywhen schema metadata is used. - Add
.meta({ ... } satisfies InputSchemaMetaType)to input fields and.meta({ ... } satisfies OutputSchemaMetaType)to output fields that need UI/manifest metadata. - Set
isToolParam: truein an input field's.meta()when that field is recommended to be managed by AI; usetoolDescriptionfor the model-facing parameter description. - Add
.meta({ isSecret: true | false, ... } satisfies SecretSchemaMetaType)to everysecretSchemafield; setisSecret: truefor values that must be encrypted at rest. - Return an object that matches
outputSchema; throw errors for failed operations. - Add
secretSchemawhen plugin configuration needs secrets such as API keys. - Read secrets from
ctx.secrets; the value is typed fromsecretSchema. - Use
ctx.streamResponse({ type: 'answer', content })to emit incremental visible output before the final response. - Use
ctx.systemVaronly for FastGPT-provided runtime variables.
const secretSchema = z.object({
apiKey: z.string().meta({
title: 'API Key',
isSecret: true
} satisfies SecretSchemaMetaType)
});
const handler = createToolHandler({
inputSchema: z.object({
query: z.string().meta({
title: 'Query',
toolDescription: 'Search query',
isToolParam: true
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
answer: z.string().meta({
title: 'Answer'
} satisfies OutputSchemaMetaType)
}),
secretSchema,
handler: async (input, ctx) => {
ctx.streamResponse({
type: 'answer',
content: `Searching: ${input.query}`
});
return {
answer: `Result for ${input.query}`
};
}
});
Manifest Rules
manifest must include these fields unless the surrounding package already supplies them:
pluginId: stable unique plugin id.version: plugin version, usually semver.name: i18n object shaped as{ en, 'zh-CN' }.description: i18n object shaped as{ en, 'zh-CN' }.
Common optional fields:
versionDescriptionauthorrepoUrltutorialUrltagspermissionicontoolDescription
Use permission to declare host capabilities required by the plugin. It is an array of permission strings. Declare only the minimum permissions that the plugin actually uses. When using ctx.invoke to call host capabilities, declare the matching permission.
Supported permissions:
userInfo:read: read user information, for example throughctx.invoke.userInfo().teamInfo:read: read team information.model:read: read model information.dataset:read: read dataset information.file-upload:allow: upload files, for example throughctx.invoke.uploadFile().
Keep pluginId, child tool id, input field names, and output field names stable for compatibility.
Tool Sets
Use defineToolSet() for one plugin with multiple child tools. Put shared metadata in the top-level manifest; put each child tool's id, name, description, optional icon, optional toolDescription, and handler in children.
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().meta({
title: 'API Key',
isSecret: true
} satisfies SecretSchemaMetaType)
});
const searchHandler = createToolHandler({
inputSchema: z.object({
query: z.string().meta({
title: 'Query',
isToolParam: true
} satisfies InputSchemaMetaType)
}),
outputSchema: z.object({
items: z.array(z.string()).meta({
title: 'Items'
} satisfies OutputSchemaMetaType)
}),
secretSchema,
handler: async (input) => ({ items: [input.query] })
});
export default defineToolSet({
secretSchema,
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',
Read the complete source ↗