XuqmGroup-RNSDK/docs/插件脚手架.md

# RN 插件脚手架

插件创建、构建、嵌入和发布统一由 `@xuqm/rn-update` 提供的 `xuqm-rn` CLI 完成。已删除独立 `create-plugin.mjs`，宿主不得复制 SDK 脚本或为每个插件维护一套构建命令。

## 初始化宿主

```bash
pnpm exec xuqm-rn init
pnpm xuqm:doctor
```

`init` 只创建缺失的统一配置和必要脚本，不覆盖宿主已有代码。唯一插件构建清单为根目录 `xuqm.modules.json`。它与租户平台签发、宿主不可编辑的 `config.xuqmconfig` 初始化文件职责完全分离。

开发启动也使用同一 CLI，不由宿主复制 Node 包装脚本：

```bash
pnpm start
pnpm android -- --device emulator-5554
```

`xuqm-rn start/run` 始终调用宿主本地的 React Native CLI，并为子进程归一化 `NO_COLOR/FORCE_COLOR` 环境变量。

## 创建插件

```bash
pnpm exec xuqm-rn plugin create prescription
```

`moduleId` 必须：

- 以小写字母开头
- 只包含小写字母、数字和连字符
- 在 `xuqm.modules.json` 中唯一

CLI 会生成：

```text
src/plugins/prescription/
  bundle.ts
  PrescriptionScreen.tsx
```

并向 `xuqm.modules.json.modules` 增加唯一模块声明。不会修改 Babel alias、TypeScript paths、Metro offset 或增加模块专属 package script。

## 插件入口

生成的入口使用统一运行时定义：

```ts
import { definePlugin } from '@xuqm/rn-update'

import { PrescriptionScreen } from './PrescriptionScreen'

definePlugin({
  id: 'prescription',
  Component: PrescriptionScreen,
})
```

插件入口不声明版本。默认 `moduleVersion`、`commonVersionRange` 和 `minNativeApiLevel` 由 CLI 从宿主 `package.json.version`、common 模块版本和 SDK 原生 API 等级一次性解析。

## 构建与发布

```bash
pnpm exec xuqm-rn doctor
pnpm exec xuqm-rn build android --module prescription
pnpm exec xuqm-rn publish android --module prescription
```

构建全部模块并嵌入宿主：

```bash
pnpm build:android
```

生成 Android Release 安装包：

```bash
pnpm release:android
pnpm release:android -- --apk
```

Release 构建会先重新生成全部插件，不使用仓库内历史 bundle。

## 强制约束

- 不得在业务入口硬编码插件版本。
- 不得给同一插件同时维护 JSON、TS 常量和 package script 三套定义。
- 不得逐层传递 SDK 初始化、用户、token 或宿主运行时参数。
- 共通逻辑放在 common 或 update 运行时，不复制到各插件。
- 插件发布前必须通过 `xuqm-rn doctor`、宿主测试和 Release 构建。