> ## 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.

# 发布与使用

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

## 发布插件

在 monorepo 根目录执行：

```bash theme={null}
# 构建插件
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` 来声明启用的插件列表。多个插件用逗号分隔：

```bash theme={null}
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系统后在系统设置[插件页面](https://app.xpertai.cn/settings/plugins)中查看已加载的插件列表。

## 安装 Scope

已安装插件都有明确 scope：

* **Organization 插件** 安装到当前组织，可在该组织中管理。
* **Tenant-global 插件** 由当前租户内的所有组织共享。
* **System 插件** 声明 `meta.level = 'system'`，全平台只安装一份，scope 为 `system:global`。

System 插件是平台单例。它只能由 Default tenant 中的 Super Admin 安装或更新。其他租户可以看到并使用 system 插件提供的能力，但不能在自己的组织或租户视图中安装、卸载或配置系统实例。

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

```text theme={null}
organization -> tenant-global -> system-global -> built-in
```

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

## 初始化插件资源

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

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

资源目标分两类：

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

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

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

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