SuperAPI AI Directory

develop-fastgpt-plugin

Coding & development

View repository

Updated 11-13 07:50

About this skill

Develop FastGPT Plugin

Use this skill to turn a non-technical beginner's plugin idea, step by step, into a runnable, testable FastGPT plugin that can be submitted as a PR.

Beginner communication rules

  • Communicate in Chinese by default; keep commands, code identifiers, and file names in English.
  • Give the user only one small step at a time, with copyable commands and success indicators.
  • When requirements are missing, ask at most three focused questions; when the default is obvious, proceed directly and state the assumption.
  • Explain terms the first time they appear:tool is a callable capability,tool-suite is a group of related capabilities.
  • Do not let the user paste secrets in the chat. Use .env, a local secret file, or the CLI's --secrets-file, and confirm that these files will not enter Git.
  • Explain the impact before installing, pulling from the network, publishing, pushing, or creating a PR; request authorization only when the current environment requires it.

Overall process

  1. Prepare the environment.
  2. Understand the requirements and choose the plugin type.
  3. Create the skeleton and develop the plugin.
  4. Test and debug locally.
  5. Publish the source code/package and submit a PR.

1. Prepare the environment

First detect the state of the user's machine:

git --version
gh --version
node -v
corepack --version
pnpm -v
pnpm fastgpt-plugin --help

When tools are missing, give installation commands by operating system:

# macOS
brew install git gh node
corepack enable
corepack prepare pnpm@10.28.2 --activate
# Windows PowerShell
winget install --id Git.Git -e
winget install --id GitHub.cli -e
winget install --id OpenJS.NodeJS.LTS -e
corepack enable
corepack prepare pnpm@10.28.2 --activate
# Ubuntu/Debian
sudo apt update
sudo apt install -y git curl nodejs npm
npm install -g corepack
corepack enable
corepack prepare pnpm@10.28.2 --activate

Then configure GitHub and Git identity:

gh auth login
gh auth status
git config --global user.name "<your-name>"
git config --global user.email "<your-email>"

If a repository already exists:

git clone --filter=blob:none --sparse <repo-url>
cd <repo>
git sparse-checkout set --no-cone '/*' '!/packages/tools/*'
pnpm install

The Node and pnpm versions follow the current repository's package.json file's engines and packageManager . In fastgpt-community-plugins , do not run git submodule update --init --recursivewithout a path; when a certain plugin is needed, only initialize packages/tools/<pluginId>。

2. Determine the requirements and plugin type

First collect just enough information:

  • What should the plugin do in one sentence?
  • What inputs are needed? What final output does FastGPT need to get?
  • Does it call an external API? Does this API require a key or token?
  • Is this one action, or multiple related actions?
  • Give 1-3 examples, preferably including a failure or edge case.

Choose the plugin type:

  • tool: a single independent action, such as checking the weather, text conversion, calling an API endpoint, or computing a result.
  • tool-suite: multiple related actions sharing a domain, credentials, or client, such as Notion's search/create/update, or a CRM's customers/orders/tickets.

For beginners, recommend toolfirst; choose tool-suiteonly when the user explicitly needs multiple related capabilities. A single tool can later be extended into a toolset.

Before coding, determine the integration form:

  • No external service: pure computation, formatting, parsing, or local conversion.
  • Credential-free public API: focus on handling network errors, rate limiting, and empty results.
  • API requiring credentials: define secrets, explain how to obtain the key, and never hardcode it.
  • File-type plugins: clarify upload/download behavior and test with small files.

3. Development

Before creating the skeleton, read the CLI usage instructions first:

sed -n '1,240p' node_modules/@fastgpt-plugin/cli/skills/cli-usage/SKILL.md

If that file does not exist, read the CLI help:

pnpm fastgpt-plugin create --help
pnpm fastgpt-plugin build --help
pnpm fastgpt-plugin check --help
pnpm fastgpt-plugin pack --help
pnpm fastgpt-plugin debug --help

Create a single tool:

pnpm fastgpt-plugin create <plugin-name> --type tool --cwd <target-parent> --description "<description>"

Create a toolset:

pnpm fastgpt-plugin create <plugin-name> --type tool-suite --cwd <target-parent> --description "<description>"

Choose the target directory:

  • In fastgpt-official-plugins , placed by default under packages/tools。
  • In this community index repository, plugins should first be developed in a standalone source repository; when adding to the index, place them as a submodule pinned to a fixed commit under packages/tools/<pluginId>。
  • When the user only wants a local prototype, create it in a clearly named working directory, and explain that publishing still requires a GitHub repository.

After generating, read the files before editing:

find <plugin-dir> -maxdepth 2 -type f | sort
sed -n '1,220p' <plugin-dir>/package.json
sed -n '1,240p' <plugin-dir>/index.ts

Implement according to the template structure:

  • Keep package.json scripts and dependency style consistent with the template.
  • Community plugin repositories must be independently installable and buildable, use explicit versions for dependencies, and keep their own packageManager and pnpm-lock.yaml, and do not use catalog: or workspace:。
  • The entry file is only responsible for the manifest, schemas, and handler wiring.
  • When the template provides src/ , put reusable runtime logic under src/。
  • Keep the input/output schema consistent with the user-visible configuration.
  • Only add secrets。
  • Add a concise README.md, including purpose, inputs, outputs, secrets, examples, and local test commands.
  • Before adding dependencies, first look for existing utility functions and patterns in adjacent plugins or templates.

4. Testing and debugging

First run the local scripts in the plugin directory:

pnpm test
pnpm build

Then run the CLI validation:

pnpm fastgpt-plugin build --entry <plugin-dir> --output <plugin-dir>/dist
pnpm fastgpt-plugin check --entry <plugin-dir> --output <plugin-dir>/dist
pnpm fastgpt-plugin pack --entry <plugin-dir> --dist <plugin-dir>/dist --output <plugin-dir>

Debug with sample input:

pnpm fastgpt-plugin debug <plugin-dir> --run --input '{"example":"value"}'

When secrets are needed, use a local ignored file:

printf '{ "apiKey": "replace-me" }\n' > .secrets.local.json
pnpm fastgpt-plugin debug <plugin-dir> --run --input-file test/input.json --secrets-file .secrets.local.json

When helping newcomers troubleshoot:

  • First read the complete error message.
  • Determine which category the failure belongs to: installation, TypeScript, schema/config, runtime API, or packaging.
  • Fix only one cause at a time, and rerun the minimal failing command.
  • Keep sample inputs small and stable.
  • Generate .pkg before moving on to publishing discussions.

5. Publishing and submitting a PR

In the plugin source repository:

git status
git checkout -b feat/<pluginId>
git add .
git commit -m "feat(<pluginId>): add FastGPT plugin"
git push -u origin feat/<pluginId>
gh pr create --title "feat(<pluginId>): add FastGPT plugin" --body "<summary>"

In this community index repository, after the source repository has been pushed:

git rev-parse HEAD
git submodule add <plugin-repo-url> packages/tools/<pluginId>

pnpm run plugin -- add --from packages/tools/<pluginId>

plugin The CLI will, according to schemas/registry.ts , update plugins.json, and can automatically infer the source URL and commit from the submodule via git/gh . Then run:

pnpm run validate
pnpm test

When preparing the community index PR, use the existing plugin-discovery skill to generate the intake bundle. The PR should include the registry entry and the submodule pointer; validation results and policy review findings are recorded via GitHub PR comments.

Before creating the PR, confirm:

  • git status contains only the files expected for this change.
  • No secrets, tokens, or.env、.secrets.local.json。
  • README.md allows newcomers to complete configuration and testing.
  • The PR body includes command output or a brief validation summary.

When delivering to the user, explain: which files were changed, the chosen plugin type, key assumptions, commands executed, validation results, the PR URL, and remaining risks such as unverified external APIs.