> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 插件系统的核心概念

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

***

### 2.1 XpertPlugin

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

```ts theme={null}
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）

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

```ts theme={null}
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` 方法，用于报告自身的运行状态，便于宿主系统进行统一的健康监控。

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

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

***

### 2.4 插件上下文（PluginContext）

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

```ts theme={null}
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 实现：

```ts theme={null}
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](https://docs.nestjs.com/modules) 类装饰器，用于将插件注册为 NestJS 模块，并为其附加插件元数据。

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

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

***

### 2.7 增强出口点（Enhancement Points）

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

#### IntegrationStrategy（系统集成策略）

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

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

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

装饰器：

```ts theme={null}
@IntegrationStrategyKey('Firecrawl')
@Injectable()
export class FirecrawlIntegrationStrategy implements IntegrationStrategy<FirecrawlOptions> { ... }
```

#### DocumentSourceStrategy（文档数据源策略）

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

***

### 2.8 策略注册中心

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

以 IntegrationStrategy 为例：

```ts theme={null}
@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，不是已安装插件 |

运行时能力查找顺序为：

```text theme={null}
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 安装