发布与使用

插件开发完成后，最后一步是发布到 npm 并在宿主系统（Xpert AI）中启用。

​

发布插件

在 monorepo 根目录执行：

# 构建插件
npx nx build my-plugin

# 使用 monorepo 的 release 流程
npx nx release

# 或者手动发布到 npm
npx nx run @xpert-ai/my-plugin:nx-release-publish --access public --otp=<one-time-password-if-needed>

发布成功后，你会在 npm 上得到一个可安装的包，例如：

@xpert-ai/my-plugin

​

使用插件

在 Xpert AI 宿主系统中，通过环境变量 PLUGINS 来声明启用的插件列表。多个插件用逗号分隔：

PLUGINS=@xpert-ai/my-plugin1,@xpert-ai/my-plugin2

当宿主启动时，会自动解析 PLUGINS 环境变量并按顺序加载这些插件。

注意事项：

• 宿主项目通过 npm/yarn/pnpm 安装（npm install @xpert-ai/my-plugin） 环境变量中配置插件包列表。
• 插件的 meta.name 必须与 npm package name 保持一致。
• 如果插件未能正确加载，请检查日志中是否有 register 或 onPluginBootstrap 的输出。
• 在启动XpertAI系统后在系统设置插件页面中查看已加载的插件列表。

​

安装 Scope

已安装插件都有明确的 level 和 scope。Level 决定能力及生命周期，scope 决定安装位置：

Level	安装 Scope	谁可以管理	谁可以使用
organization	当前 organization，或当前 tenant 的 global scope	对应作用域管理员	当前组织，或当前 tenant
tenant	global 或 tenant:<tenantId>:global	所属 tenant 的 Super Admin	仅所属 tenant
system	system:global	Default tenant 的 Super Admin	所有 tenant

这里的 tenant level 不只是把普通插件安装到 tenant-global scope。它表示插件可以注册 Controller、TypeORM Entity 和进程级 Provider 等 system-level 技术能力，但产品归属和访问边界只限一个 tenant。

​

安装 Tenant-level 插件

安装前确认插件运行时 meta 与 package.json 都声明了相同的 level 和命名空间：

{
  "xpert": {
    "plugin": {
      "level": "tenant",
      "artifactNamespace": "contract_review"
    }
  }
}

安装流程：

1. 使用目标 tenant 的 Super Admin 登录。
2. 进入 tenant 管理作用域的插件页面并安装插件包。
3. 安装成功后按照页面提示重启 API 服务。
4. 重启后回到目标 tenant，确认插件状态、配置、工作台和 API 可用。
5. 切换到另一个 tenant，确认插件列表和业务入口不可见；直接访问插件 API 应返回无权访问。

Tenant-level 插件采用以下保护规则：

• 同名插件只能归属于一个 tenant，不能在另一个 tenant 再安装一份。
• 安装与更新只暂存制品，重启 API 后才会装载新的 Controller、Entity 和 Provider。
• 卸载先停用持久化注册，重启 API 后才完成运行时卸载。
• 已锁定到某个 tenant 的插件配置只能由该 tenant 的 Super Admin 管理。
• artifactNamespace 必须稳定，避免表名、路由和注册表标识与其他进程级插件冲突。

​

从 System Level 迁移到 Tenant Level

不能在旧 system 注册仍生效时直接把同一插件改成 tenant level，否则两份进程级模块可能同时注册。正确迁移顺序是：

1. 在 Default tenant 中由 Super Admin 卸载旧的 system 插件。
2. 重启 API，确认旧运行时模块已经卸载。
3. 发布或准备声明 level = 'tenant' 的新插件版本。
4. 使用目标 tenant 的 Super Admin 安装新版本。
5. 再次重启 API，完成 tenant-level 插件激活。
6. 在目标 tenant 验证业务数据和配置，并执行一次跨 tenant 隔离检查。

迁移前应备份旧插件配置。System 实例与 tenant 实例具有不同的归属和 scope，平台不会自动把所有 system 配置复制到目标 tenant。

运行时插件能力按以下顺序解析：

organization -> tenant-global -> system-global -> built-in

因此 organization 或 tenant 插件可以按需覆盖系统默认能力，但不会创建第二份 system 实例。

​

初始化插件资源

插件被宿主加载后，不只是“启用”这么简单，还可以把插件包内声明的资源初始化到对应运行时目标中。

在系统设置的插件页里，已安装插件卡片上会提供资源初始化入口。点击后会打开资源初始化弹窗，宿主会实时读取当前插件包中的资源定义，而不是依赖一份静态缓存列表。

资源目标分两类：

• Workspace：初始化到工作空间，可用于 Skills、MCP 和 Apps
• Xpert：初始化到已有的 Xpert，可用于 Hooks

初始化弹窗会按资源类型分组展示，并显示当前状态：

• 已初始化的资源会显示为已安装，不能重复选择
• 插件包内容更新后，若资源定义发生变化，系统会提示可更新状态
• assets/ 只作为包元数据和展示内容，不作为可初始化资源

完成初始化后，宿主会把资源绑定到真实运行时对象，并在当前工作空间或 Xpert 中更新对应的中间件、工具集或连接配置。