插件系统的核心概念

在 Xpert AI 插件系统中，所有插件均遵循统一的接口规范与生命周期管理。通过一组核心概念，开发者可以轻松扩展宿主系统的能力，而无需修改核心代码。

2.1 XpertPlugin

XpertPlugin 是插件的核心入口接口，定义了插件的元信息（meta）、配置（config）、生命周期方法和模块注册逻辑。

export interface XpertPlugin<TConfig extends object = any> 
  extends PluginLifecycle, PluginHealth {
  meta: PluginMeta;                       // 插件元信息
  config?: PluginConfigSpec<TConfig>;     // 插件配置
  register(ctx: PluginContext<TConfig>): DynamicModule; // 注册插件模块
}

meta：插件的基本元信息，包括 name、version、category、icon、description 等。
config：定义插件所需的配置 Schema（基于 zod），支持默认值与 UI 表单渲染。
register：返回 DynamicModule，用于将插件挂载到主应用（可选择设为全局）。

2.2 插件生命周期（PluginLifecycle）

插件系统为每个插件提供完整的生命周期钩子，方便开发者在不同阶段执行初始化或清理逻辑。

export interface PluginLifecycle {
  onInit?(ctx: PluginContext): Promise<void> | void;   // 模块注册完成后调用
  onStart?(ctx: PluginContext): Promise<void> | void;  // 应用启动后调用（对外服务可用）
  onStop?(ctx: PluginContext): Promise<void> | void;   // 应用优雅停机时调用
}

onInit：适合做资源初始化（如加载配置、注册资源池）。
onStart：适合启动后台任务、开启服务监听。
onStop：适合清理资源、关闭连接、释放缓存。

2.3 插件健康检查（PluginHealth）

插件可实现 checkHealth 方法，用于报告自身的运行状态，便于宿主系统进行统一的健康监控。

export interface PluginHealth {
  checkHealth?(ctx: PluginContext): Promise<{ status: 'up' | 'down'; details?: any }> 
}

status：运行状态（up 或 down）
details：可选的依赖检查详情，如 API 连通性、数据库状态

2.4 插件上下文（PluginContext）

PluginContext 提供了插件在运行时访问宿主系统的能力，包括应用上下文、日志服务和配置。

export interface PluginContext<TConfig extends object = any> {
  app: INestApplicationContext;   // Nest 运行时上下文
  logger: PluginLogger;           // SDK 提供的日志包装
  config: TConfig;                // 校验合并后的最终配置
  resolve<TInput, TResult>(token: any): TResult; // 依赖注入解析
}

app：NestJS 的 INestApplicationContext，允许访问依赖注入容器。
logger：统一日志接口，支持 debug、log、warn、error。
config：经过 zod 校验和合并默认值后的最终配置对象。
resolve：从 NestJS 容器中获取其他 Provider。

2.5 插件配置（PluginConfigSpec）

每个插件可定义一份配置规范，用于约束和校验配置参数，通常通过 zod Schema 实现：

export interface PluginConfigSpec<T extends object = any> {
  schema?: ZodSchema<T>;       // 配置校验 Schema
  defaults?: Partial<T>;       // 默认配置
}

支持 类型安全（zod 类型推导）
支持 默认值 与 安全输入（如 API Key 的密钥输入）
宿主系统会根据该 Schema 自动渲染配置 UI

2.6 XpertServerPlugin 装饰器

@XpertServerPlugin 是一个增强的 Nestjs Module 类装饰器，用于将插件注册为 NestJS 模块，并为其附加插件元数据。

@XpertServerPlugin({
  imports: [ /* 子模块 */ ],
  providers: [ /* 服务、策略 */ ],
  controllers: [ /* 控制器 */ ],
  entities: [ /* 数据库实体 */ ],
})
export class FirecrawlPlugin { ... }

实际上基于 NestJS 的 @Module 装饰器扩展而来
支持注册子模块、服务、控制器、实体等
插件因此成为一个完整的 NestJS 动态模块

2.7 增强出口点（Enhancement Points）

增强出口点是插件扩展宿主系统的关键机制。宿主系统会定义一系列策略接口（Strategy），插件通过实现这些接口并打上装饰器，就能被系统自动发现并注册。

IntegrationStrategy（系统集成策略）

用于对接外部系统或 API 服务，例如 Firecrawl、OpenAI 等。

export interface IntegrationStrategy<T = unknown> {
  meta: TIntegrationProvider;  
  execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>;
}

meta：集成提供者的元信息（名称、描述、icon 等）
execute：执行具体的集成逻辑（例如调用外部 API）

装饰器：

@IntegrationStrategyKey('Firecrawl')
@Injectable()
export class FirecrawlIntegrationStrategy implements IntegrationStrategy<FirecrawlOptions> { ... }

DocumentSourceStrategy（文档数据源策略）

用于接入新的数据源，例如网页爬虫、文件解析、数据库。插件只需实现对应接口，即可让智能体/BI 使用该数据源。

2.8 策略注册中心

所有策略类（Integration、DocumentSource 等）通过 装饰器 + NestJS 依赖注入 的方式注册到 策略注册中心（Registry）。以 IntegrationStrategy 为例：

@Injectable()
export class IntegrationStrategyRegistry 
  extends BaseStrategyRegistry<IntegrationStrategy> {
  constructor(discoveryService: DiscoveryService, reflector: Reflector) {
    super(INTEGRATION_STRATEGY, discoveryService, reflector);
  }
}

IntegrationStrategyRegistry 会自动发现打上 @IntegrationStrategyKey 的类
插件无需手动注册策略，只要实现接口并装饰即可被系统识别

2.9 插件资源与初始化目标

插件除了提供代码扩展点，还可以声明可初始化的资源。宿主会在插件已加载后，直接从插件包读取当前资源定义，并在插件页提供初始化入口。资源按初始化目标分为两类：

Workspace：面向工作空间初始化，适用于 Skills、MCP 和 Apps
Xpert：面向已有 Xpert 初始化，适用于 Hooks

资源初始化时，宿主会把资源定义映射成实际运行时对象，并记录当前安装状态、运行时对象标识、定义版本以及是否需要更新。这样一来：

已初始化资源会被识别为已安装，不会重复出现在可选列表里
插件包更新后，如果资源定义变化，系统可以提示该资源存在可更新版本
资源状态可以随宿主重载实时刷新，而不依赖旧的静态缓存

assets/ 只用于包内展示、截图、图标等元数据，不作为可初始化资源。

2.10 插件 Scope 与 Level

插件 scope 决定插件实例安装在哪里，以及谁可以看到或管理它。插件 level 描述插件提供的是哪一类平台能力。两者相关，但不是同一个概念。常见 scope：

Scope	Scope key	谁可见	典型用途
Organization	`<organizationId>`	单个组织	普通业务插件、组织级集成、自定义工作流
Tenant global	`global` 或 `tenant:<tenantId>:global`	同一租户内的所有组织	某个租户共享的默认能力
System global	`system:global`	所有租户	提供系统级模块、实体或默认能力的平台单例插件
Built-in global	`builtin:global`	所有租户	宿主代码内置 Provider fallback，不是已安装插件

运行时能力查找顺序为：

organization -> tenant-global -> system-global -> builtin-global

这意味着 organization 插件可以覆盖 tenant-global 插件，tenant-global 插件可以覆盖 system 插件，而 system 插件只能覆盖宿主内置 Provider。只有当插件必须作为平台单例存在时，才使用 meta.level = 'system'。典型场景包括定义系统级数据库实体，或提供不能在多个租户中重复安装的系统模块。System 插件采用特殊管理规则：

只能由 Default tenant 中的 Super Admin 安装或更新。
宿主只会把它保存为 system:global 下的一份单例；重复安装会更新同一个实例。
普通租户可以看到并使用它提供的能力，但不能在自己的组织视图中安装、卸载或配置系统实例。

大多数插件应保持默认的 organization level。即使插件能力在租户内可见，插件自己的业务数据也仍应在可用时按 tenant 和 organization 进行隔离。

📌 小结：

XpertPlugin 定义了插件的元信息、配置与生命周期
XpertServerPlugin 将插件注册为 NestJS 模块
增强出口点（Strategy） 是插件扩展宿主系统功能的核心
所有插件都通过 生命周期 + 策略接口 + 配置 Schema 形成可扩展、可维护的模块
插件资源可按 Workspace / Xpert 两种目标初始化，并在宿主中保持可追踪的安装状态
插件 scope 控制可见性和管理边界；system 插件是平台单例，只能从 Default tenant 安装

默认

触发器

集成

飞书文档示例

插件系统的核心概念

2.1 XpertPlugin

2.2 插件生命周期（PluginLifecycle）

2.3 插件健康检查（PluginHealth）

2.4 插件上下文（PluginContext）

2.5 插件配置（PluginConfigSpec）

2.6 XpertServerPlugin 装饰器

2.7 增强出口点（Enhancement Points）

IntegrationStrategy（系统集成策略）

DocumentSourceStrategy（文档数据源策略）

2.8 策略注册中心

2.9 插件资源与初始化目标

2.10 插件 Scope 与 Level

​2.1 XpertPlugin

​2.2 插件生命周期（PluginLifecycle）

​2.3 插件健康检查（PluginHealth）

​2.4 插件上下文（PluginContext）

​2.5 插件配置（PluginConfigSpec）

​2.6 XpertServerPlugin 装饰器

​2.7 增强出口点（Enhancement Points）

​IntegrationStrategy（系统集成策略）

​DocumentSourceStrategy（文档数据源策略）

​2.8 策略注册中心

​2.9 插件资源与初始化目标

​2.10 插件 Scope 与 Level

2.1 XpertPlugin

2.2 插件生命周期（PluginLifecycle）

2.3 插件健康检查（PluginHealth）

2.4 插件上下文（PluginContext）

2.5 插件配置（PluginConfigSpec）

2.6 XpertServerPlugin 装饰器

2.7 增强出口点（Enhancement Points）

IntegrationStrategy（系统集成策略）

DocumentSourceStrategy（文档数据源策略）

2.8 策略注册中心

2.9 插件资源与初始化目标

2.10 插件 Scope 与 Level