SuperAPI AI 工具集

develop-fastgpt-plugin

编程与开发

查看项目

更新于 11-13 07:50

技能介绍

用途

本技能用于把技术小白的插件想法一步步变成可运行、可测试、可提交 PR 的 FastGPT 插件。它面向新手,提供从环境准备到发布提交的完整引导。

主要能力

  • 新手沟通规则:默认使用中文沟通,命令、代码标识符和文件名保持英文;每次只给用户一个小步骤,并附上可复制命令和成功标志;需求缺失时最多问三个聚焦问题,默认值明显时直接推进并说明假设;第一次出现术语时顺手解释,例如 tool 是一个可调用能力,tool-suite 是一组相关能力。
  • 安全实践:不让用户在聊天里粘贴密钥,使用 .env、本地 secret 文件或 CLI 的 --secrets-file,并确认这些文件不会进入 Git;安装、联网拉取、发布、推送、创建 PR 前说明影响,当前环境需要授权时再请求授权。
  • 总流程:准备环境;理解需求并选择插件类型;创建骨架并开发插件;本地测试和调试;发布源码/包并提交 PR。

使用方式

1. 准备环境

先检测用户机器状态:

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

缺工具时按操作系统给出安装命令:

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

再配置 GitHub 和 Git 身份:

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

已有仓库时:

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

Node 和 pnpm 版本以当前仓库 package.json 的 engines 和 packageManager 为准。在 fastgpt-community-plugins 中,不要运行不带路径的 git submodule update --init --recursive;需要某个插件时只初始化 packages/tools/<pluginId>。

2. 判断需求和插件类型

先收集刚好够用的信息:插件一句话要做什么;需要哪些输入,FastGPT 最终要得到什么输出;是否调用外部 API,这个 API 是否需要 key 或 token;这是一个动作,还是多个相关动作;给出 1-3 个例子,最好包含一个失败或边界情况。

选择插件类型:

  • tool:一个独立动作,例如查天气、文本转换、调用一个 API endpoint、计算结果。
  • tool-suite:多个相关动作,共用领域、凭证或客户端,例如 Notion 的搜索/新增/更新,CRM 的客户/订单/工单。

面向新手时优先推荐 tool;用户明确需要多个相关能力时再选 tool-suite。单工具后续可以扩展成工具集。

编码前先判断集成形态:无外部服务(纯计算、格式化、解析或本地转换);无凭证公开 API(重点处理网络错误、限流和空结果);需要凭证的 API(定义 secrets,说明 key 获取方式,严禁硬编码);文件类插件(明确上传/下载行为,并用小文件测试)。

3. 开发

创建骨架前,优先读取 CLI 使用说明:

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

没有该文件时读取 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

创建单工具:

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

创建工具集:

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

选择目标目录:在 fastgpt-official-plugins 中,默认放到 packages/tools;在本社区索引仓库中,插件应先在独立源码仓库开发,入库时再作为固定 commit 的 submodule 放到 packages/tools/<pluginId>;用户只想做本地原型时,创建到清晰命名的工作目录,并说明发布仍需要 GitHub 仓库。

生成后先读文件再改:

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

按模板结构实现:保持 package.json scripts 和依赖风格与模板一致;社区插件仓库必须能独立安装和构建,依赖使用明确版本,保留自己的 packageManager 与 pnpm-lock.yaml,不要使用 catalog: 或 workspace:;入口文件只负责 manifest、schemas 和 handler wiring;模板提供 src/ 时,把可复用运行逻辑放到 src/;保持输入/输出 schema 与用户可见配置一致;只有真实凭证才添加 secrets;添加简洁 README.md,包含用途、输入、输出、secrets、示例、本地测试命令;添加依赖前先找相邻插件或模板里已有的工具函数和模式。

4. 测试和调试

先在插件目录执行本地脚本:

pnpm test pnpm build

再执行 CLI 验证:

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>

用样例输入调试:

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

需要 secrets 时,使用本地忽略文件:

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

带新手排错时:先读完整错误信息;判断失败属于安装、TypeScript、schema/config、运行时 API、打包哪一类;每次只修一个原因,并重跑最小失败命令;样例输入保持小而稳定;生成 .pkg 后再进入发布讨论。

5. 发布和提交 PR

插件源码仓库中:

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>"

本社区索引仓库中,源码仓库推送完成后:

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

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

plugin CLI 会按 schemas/registry.ts 更新 plugins.json,并可通过 git/gh 从 submodule 自动推断 source URL 与 commit。随后运行:

pnpm run validate pnpm test

准备社区索引 PR 时,使用已有 plugin-discovery skill 生成 intake bundle。PR 应包含 registry entry 和 submodule 指针;验证结果与 policy review findings 通过 GitHub PR comment 留痕。

创建 PR 前确认:git status 只包含本次预期文件;没有提交 secrets、tokens、.env、.secrets.local.json;README.md 能让新手完成配置和测试;PR body 包含命令输出或简短验证摘要。

最终交付给用户时说明:改了哪些文件、选择的插件类型、关键假设、执行过的命令、验证结果、PR URL,以及未验证的外部 API 等剩余风险。

适用场景

  • 技术小白希望开发 FastGPT 插件但不知从何入手。
  • 需要引导完成环境安装、插件类型选择、骨架创建、开发、测试、发布和提交 PR 的全流程。
  • 需要安全地处理密钥和凭证,避免泄露。

限制

  • 本技能为向导性质,具体插件功能实现取决于用户需求。
  • 涉及外部 API 时,其可用性、收费、价格等未提供,需用户自行确认。
  • 发布到社区索引仓库需要遵循相应仓库的规范,具体规范未在资料中详细说明。