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

# 插件脚手架工具

> 脚本位置：`packages/update/scripts/create-plugin.mjs`  
> 最后更新：2026-06-15

---

## 概述

`create-plugin.mjs` 是 UpdateSDK 提供的插件脚手架工具，用于一键创建完整的插件骨架项目。

**功能**：

- 交互式或命令行输入插件参数
- 校验 moduleId 唯一性
- 自动生成插件文件（bundle.ts / Screen / plugin.json）
- 自动注册到宿主（pluginCatalog / debugPlugins / build scripts / metro config / babel alias / tsconfig）

---

## 用法

### 命令行模式（推荐）

```bash
node scripts/create-plugin.mjs <moduleId> [title] [subtitle] [accentColor]
```

示例：

```bash
# 完整参数
node scripts/create-plugin.mjs buz4 "IM 消息" "即时通讯业务组件" "#E74C3C"

# 最简（title/subtitle/accentColor 使用默认值）
node scripts/create-plugin.mjs buz5
```

### 交互模式

```bash
node scripts/create-plugin.mjs
```

按提示依次输入 moduleId、title、subtitle、accentColor。

---

## 参数说明

| 参数        | 必填 | 格式               | 默认值            | 说明                    |
| ----------- | ---- | ------------------ | ----------------- | ----------------------- |
| moduleId    | ✅   | `^[a-z][a-z0-9]*$` | —                 | 插件唯一标识，如 `buz4` |
| title       | ❌   | 任意文本           | = moduleId        | 插件标题                |
| subtitle    | ❌   | 任意文本           | `{title}业务组件` | 插件副标题              |
| accentColor | ❌   | CSS 颜色值         | `#0E84FA`         | 主题色                  |

---

## 自动生成的文件

### 插件目录 `src/plugins/{moduleId}/`

#### `bundle.ts` — 入口文件

```typescript
import { UpdateSDK } from "@xuqm/rn-update";
import { registerPluginFromBridge } from "@plugins/runtimeBridge";
import { Buz4Screen } from "@buz4/Buz4Screen";

// 自动注册插件版本（bundle 加载时执行）
UpdateSDK.registerPlugin({ moduleId: "buz4", version: "1.0.0" });

// 注册 UI 组件到宿主运行时
registerPluginFromBridge({
  id: "buz4",
  title: "IM 消息",
  subtitle: "即时通讯业务组件",
  accentColor: "#E74C3C",
  Component: Buz4Screen,
});
```

#### `{ModuleId}Screen.tsx` — Screen 骨架

```typescript
import { StyleSheet, Text, View } from 'react-native';

export function Buz4Screen() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>buz4</Text>
      <Text style={styles.subtitle}>TODO: 实现buz4功能</Text>
    </View>
  );
}
```

#### `plugin.json` — 插件元数据

```json
{ "moduleId": "buz4", "version": "1.0.0" }
```

---

## 自动更新的宿主文件

| 文件                            | 变更内容                                                        |
| ------------------------------- | --------------------------------------------------------------- |
| `src/app/pluginCatalog.ts`      | 添加插件目录条目（id/title/summary/accentColor）                |
| `src/bootstrap/debugPlugins.ts` | 注册 debug loader（`require('../plugins/{id}/bundle')`）        |
| `package.json`                  | 添加 `build:android:{id}` / `build:ios:{id}` 脚本，更新聚合脚本 |
| `metro.split.config.js`         | 添加 moduleId 的 offset 分支                                    |
| `babel.config.js`               | 添加 `@{id}` alias                                              |
| `tsconfig.json`                 | 添加 `@{id}/*` path mapping                                     |

---

## 唯一性校验

脚本会检查两处来确保 moduleId 唯一：

1. `src/app/pluginCatalog.ts` 中已注册的 id
2. `src/plugins/` 目录下已存在的目录名

如果 moduleId 已存在，脚本会报错并退出：

```
❌ moduleId "buz4" 已存在，请使用其他 ID
```

---

## moduleId 命名规范

- 必须以**小写字母**开头
- 只能包含**小写字母和数字**
- 推荐格式：`buz{N}`（如 `buz4`、`buz5`）

Metro module ID offset 自动计算：`buz1` → 11M，`buz2` → 12M，`buzN` → (10+N)M。

---

## 创建后的开发流程

```bash
# 1. 生成插件骨架
node scripts/create-plugin.mjs buz4 "IM 消息" "即时通讯业务组件" "#E74C3C"

# 2. 实现业务 UI
# 编辑 src/plugins/buz4/Buz4Screen.tsx

# 3. 创建子目录
mkdir -p src/plugins/buz4/services
mkdir -p src/plugins/buz4/pages

# 4. 验证
yarn validate

# 5. 构建
yarn build:android:buz4
yarn build:ios:buz4
```