FastGPT Plugin Development Document

June 8, 2026 · View on GitHub

Language: 简体中文 | English

Common Commands

Install Dependencies

pnpm install

Build

pnpm build:sdk-factory
pnpm build:sdk-client
pnpm build:cli
pnpm build:server
pnpm build:debug-runtime-monitor

Development

pnpm dev:server
pnpm dev:cli
pnpm dev:debug-runtime-monitor

Quality Checks

pnpm test
pnpm typecheck
pnpm lint

Repository Structure

This repository is a pnpm workspace monorepo.

PathPurpose
apps/serverFastGPT Plugin HTTP service and route composition.
apps/cliPlugin create, build, check, debug, and pack CLI.
apps/debug-runtime-monitorLocal runtime monitor UI.
packages/domainEntities, value objects, and port definitions.
packages/usecaseApplication use cases for plugins, tools, models, and runtime metrics.
packages/interface-adapterHTTP contracts, DTOs, and auth adapters.
packages/infrastructureHono, Mongo, S3, Redis, static data, logging, metrics, and plugin runtime implementations.
packages/sharedCross-layer pure utilities.
sdk/clientClient SDK for calling the FastGPT Plugin service.
sdk/factorySDK for authoring tool plugins.
testShared fixtures and cross-package test utilities.

See Architecture for the full layering model.

Plugin Development

Use @fastgpt-plugin/cli and @fastgpt-plugin/sdk-factory for tool plugins.

pnpx @fastgpt-plugin/cli create my-tool --type tool --cwd packages/tools
pnpx @fastgpt-plugin/cli create my-tool-suite --type tool-suite --cwd packages/tools

Inside a plugin project:

pnpm run test
pnpm run build
pnpx @fastgpt-plugin/cli check --entry . --output ./dist
pnpm run pack

Useful references:

Development Practices

1. Use English Identifiers

Use English for variables, functions, files, and public API names. Keep legacy non-English identifiers only when required for compatibility.

2. Keep Layer Boundaries Clear

Follow the existing dependency direction:

  1. Define stable business types and ports in packages/domain.
  2. Implement orchestration in packages/usecase.
  3. Put DTOs and OpenAPI contracts in packages/interface-adapter.
  4. Implement framework, storage, runtime, and external-service details in packages/infrastructure.
  5. Wire concrete dependencies in apps/server/src/deps.ts and route files.

3. Write Tests

Use Vitest for tests. Prefer focused tests near the code being changed:

  • Usecase tests should mock ports.
  • Infrastructure tests should isolate external IO and cover serialization, error mapping, and security constraints.
  • CLI changes should cover command behavior and generated artifacts.
  • SDK changes should cover TypeScript-facing API behavior and runtime channel behavior.

4. Prefer const

Use const by default. Use let only when a variable is intentionally reassigned.

5. Avoid any

Prefer explicit types, Zod schemas, and domain value objects. Use unknown at boundaries and parse before use.

6. Keep Scope Small

Keep variables and helper functions close to where they are used. Extract helpers when they clarify business intent or remove meaningful duplication.

Model Presets

Model provider presets now live under packages/infrastructure/src/static-data/models/provider.

To add or update a model provider:

  1. Update or add the provider config in packages/infrastructure/src/static-data/models/provider/<Provider>/index.ts.
  2. Add or update the provider logo in the same directory when needed.
  3. Add channel avatars under packages/infrastructure/src/static-data/models/channel-avatar when needed.
  4. Register new providers in packages/infrastructure/src/static-data/models/index.ts.
  5. Run tests or typecheck for the affected package.

Runtime And Operations