Core Concepts of the Plugin System
In the Xpert AI plugin system, all plugins follow a unified interface specification and lifecycle management. Through a set of core concepts, developers can easily extend the host system's capabilities without modifying the core code.
2.1 XpertPlugin
XpertPlugin is the main entry interface for plugins, defining plugin metadata (meta), configuration (config), lifecycle methods, and module registration logic.
export interface XpertPlugin<TConfig extends object = any>
extends PluginLifecycle, PluginHealth {
meta: PluginMeta; // Plugin metadata
config?: PluginConfigSpec<TConfig>; // Plugin configuration
register(ctx: PluginContext<TConfig>): DynamicModule; // Register plugin module
}
- meta: Basic plugin metadata, including
name,version,category,icon,description, etc. - config: Defines the plugin's configuration schema (based on
zod), supporting default values and UI form rendering. - register: Returns a
DynamicModuleto mount the plugin to the main application (optionally as global).
2.2 Plugin Lifecycle
The plugin system provides a complete set of lifecycle hooks for each plugin, allowing developers to execute initialization or cleanup logic at different stages.
export interface PluginLifecycle {
onInit?(ctx: PluginContext): Promise<void> | void; // Called after module registration
onStart?(ctx: PluginContext): Promise<void> | void; // Called after app startup (services available)
onStop?(ctx: PluginContext): Promise<void> | void; // Called during graceful shutdown
}
- onInit: Suitable for resource initialization (e.g., loading configs, registering resource pools).
- onStart: Suitable for starting background tasks or service listeners.
- onStop: Suitable for cleaning up resources, closing connections, releasing caches.
2.3 Plugin Health Check
Plugins can implement the checkHealth method to report their running status, enabling unified health monitoring by the host system.
export interface PluginHealth {
checkHealth?(ctx: PluginContext): Promise<{ status: 'up' | 'down'; details?: any }>
}
- status: Running status (
upordown) - details: Optional dependency check details, such as API connectivity or database status
2.4 Plugin Context
PluginContext provides plugins with runtime access to the host system, including application context, logging service, and configuration.
export interface PluginContext<TConfig extends object = any> {
app: INestApplicationContext; // Nest runtime context
logger: PluginLogger; // SDK-provided logging wrapper
config: TConfig; // Final validated and merged config
resolve<TInput, TResult>(token: any): TResult; // Dependency injection resolver
}
- app: NestJS's
INestApplicationContext, allowing access to the DI container. - logger: Unified logging interface, supporting
debug,log,warn,error. - config: Final config object after zod validation and merging defaults.
- resolve: Retrieve other providers from the NestJS container.
2.5 Plugin Configuration Specification
Each plugin can define a configuration specification to constrain and validate config parameters, usually implemented via a zod schema:
export interface PluginConfigSpec<T extends object = any> {
schema?: ZodSchema<T>; // Config validation schema
defaults?: Partial<T>; // Default config
}
- Supports type safety (zod type inference)
- Supports default values and secure input (e.g., API key secrets)
- The host system automatically renders the config UI based on the schema
2.6 XpertServerPlugin Decorator
@XpertServerPlugin is an enhanced Nestjs Module class decorator, used to register plugins as NestJS modules and attach plugin metadata.
@XpertServerPlugin({
imports: [ /* submodules */ ],
providers: [ /* services, strategies */ ],
controllers: [ /* controllers */ ],
entities: [ /* database entities */ ],
})
export class FirecrawlPlugin { ... }
- Essentially extends NestJS's
@Moduledecorator - Supports registering submodules, services, controllers, entities, etc.
- The plugin thus becomes a complete NestJS dynamic module
2.7 Enhancement Points
Enhancement points are the key mechanism for plugins to extend the host system. The host system defines a series of strategy interfaces, and plugins can implement these interfaces and use decorators to be automatically discovered and registered.
IntegrationStrategy
Used to connect external systems or API services, such as Firecrawl, OpenAI, etc.
export interface IntegrationStrategy<T = unknown> {
meta: TIntegrationProvider;
execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>;
}
- meta: Metadata for the integration provider (name, description, icon, etc.)
- execute: Executes the integration logic (e.g., calling external APIs)
Decorator:
@IntegrationStrategyKey('Firecrawl')
@Injectable()
export class FirecrawlIntegrationStrategy implements IntegrationStrategy<FirecrawlOptions> { ... }
DocumentSourceStrategy
Used to connect new data sources, such as web crawlers, file parsers, databases. Plugins only need to implement the corresponding interface to make the data source available to agents/BI.
2.8 Strategy Registry
All strategy classes (Integration, DocumentSource, etc.) are registered to the strategy registry via decorators + NestJS dependency injection.
For example, IntegrationStrategy:
@Injectable()
export class IntegrationStrategyRegistry
extends BaseStrategyRegistry<IntegrationStrategy> {
constructor(discoveryService: DiscoveryService, reflector: Reflector) {
super(INTEGRATION_STRATEGY, discoveryService, reflector);
}
}
IntegrationStrategyRegistryautomatically discovers classes decorated with@IntegrationStrategyKey- Plugins do not need to manually register strategies; implementing the interface and using the decorator is enough for system recognition
📌 Summary:
XpertPlugindefines plugin metadata, configuration, and lifecycleXpertServerPluginregisters plugins as NestJS modules- Enhancement points (Strategy) are the core for plugins to extend host system functionality
- All plugins form extensible and maintainable modules via lifecycle + strategy interfaces + config schema