Astron RPA 插件开发 CLI 完全指南:从 `@rpa/cli` 安装、脚手架生成到 Module Federation 构建实战

原创2026-10-13 13:19:191,020 阅读
文章标签:RPA工作流自动化低代码桌面应用后端前端

Astron RPA 插件开发 CLI 完全指南:从 @rpa/cli 安装、脚手架生成到 Module Federation 构建实战

导读

@rpa/cli 是 Astron RPA(astron-rpa)前端插件体系的命令行工具,负责插件模板脚手架生成、开发服务器启动与生产构建。本文以 frontend/packages/cli/README.zh-CN.md 为主体,结合仓库中 src/cli、templates/template-vue、@rpa/shared 及 Web 端 PluginManager 的源码实现,完整讲解 CLI 的安装方式、三大核心命令(dev / build / create)的用法与底层原理、全局选项的调试技巧,以及如何用 rpa create 生成一个可被 Astron RPA 客户端动态加载的插件,最终带你打通"开发 → 构建 → 宿主加载"的完整链路。

背景:为什么 Astron RPA 需要一套插件 CLI

Astron RPA 前端采用 pnpm monorepo 结构(见 frontend/package.json),其中 packages/cli(即 @rpa/cli)、packages/shared(@rpa/shared,提供插件类型与 definePlugin)与 packages/web-app(宿主应用)相互协作。插件通过 Module Federation 以远程模块形式加载:CLI 负责把插件源码构建成"remote",宿主端 PluginManager 再通过 @module-federation/enhanced/runtime 的 loadRemote 动态拉取并激活插件。

因此 @rpa/cli 并不是一个通用的脚手架工具,而是 Astron RPA 插件开发生命周期(创建、开发、构建)的专用入口。它的可执行文件名为 rpa,在 package.json 中通过 "bin": { "rpa": "./bin/rpa.js" } 暴露。

一、安装 @rpa/cli

CLI 支持全局安装与项目本地安装两种方式,包管理器可选 npm 或 pnpm。

# 全局安装
npm install -g @rpa/cli
# 或
pnpm add -g @rpa/cli

# 本地安装
npm install @rpa/cli --save-dev
# 或
pnpm add @rpa/cli -D

环境前提:仓库根目录 frontend/package.json 声明 "engines": { "node": ">=22", "pnpm": ">=9" },并在 preinstall 中强制使用 pnpm(npx only-allow pnpm)。如果你是进入仓库开发,请先满足该 Node/pnpm 版本要求;在独立项目中使用时,同样建议使用 Node 22+ 以获得 Vite 7 与 @module-federation/vite 的完整支持。

在仓库内本地开发时,推荐在 packages/cli 目录先执行 pnpm install,再运行 pnpm build 生成 dist 产物后使用。

二、三大核心命令详解

CLI 的命令解析基于 cac 实现,全部命令定义在 src/cli/commands.ts 中:

const cli = cac('rpa')
cli.help().version(version)
cli.option('--debug [feat]', 'Show debug logs')
cli.command('dev', 'Start the development server')...
cli.command('build', 'build the library for production')...
cli.command('create', 'create a plugin template')...

2.1 rpa dev —— 启动开发服务器

rpa dev

该命令用于插件开发调试。执行后,源码中会调用 createBuildServer({ dev: true }),其内部逻辑(见 src/cli/vite.ts)为:

  • 以当前工作目录为根,调用 loadRpaConfig(root, 'serve', 'development') 读取用户配置;
  • 组装 Vite InlineConfig,注入 @module-federation/vite 的 federation 插件、@vitejs/plugin-vue 与 @vitejs/plugin-vue-jsx;
  • 配置 exposes: { './index': './src/index.ts' },即插件入口统一暴露为 模块名/index;
  • 以 development 模式创建并启动 Vite Dev Server,调用 viteServer.printUrls() 打印访问地址,并绑定 CLI 快捷键(bindCLIShortcuts)。

开发模式下 publicPath 不设置(使用 Vite 默认路径),因此 HMR 与本地调试都走标准 Vite 链路。你可以直接修改 src/ 下的 Vue 组件与 TS 文件,浏览器/宿主端即可热更新。

2.2 rpa build —— 构建生产库

rpa build
# 带监听模式构建
rpa build --watch

选项:

选项 说明
-w, --watch 开启监听模式,监听文件变化并自动重新构建

构建时 createBuildServer({ dev: false }) 会以 'build' 命令、production 模式执行:

  • 同样读取 rpa.config.ts 等用户配置,取 userConfig?.name || 'remote' 作为远程模块名 remoteName;
  • 关键差异在于 publicPath 被显式设置为 `rpa://extensions/${remoteName}/`,并开启 manifest: true——这正是插件产物被 Astron RPA 客户端识别、安装与加载的约定路径协议;
  • 最终调用 Vite 的 build() 产出生产包。构建配置里还设置了 build.modulePreload = false,并让 vue、vue-router 作为共享依赖(shared: ['vue', 'vue-router']),避免宿主与插件重复打包框架代码。

--watch 模式对应构建层级的监听(-w),适合持续迭代产物文件;日常交互式开发请优先使用 rpa dev。

2.3 rpa create —— 脚手架生成插件模板

rpa create
# 或指定参数
rpa create --name my-plugin --target ./packages/my-plugin

选项:

选项 说明
-n, --name [name] 插件名称
-t, --target [dir] 生成的目标目录

若未提供选项,rpa create 会启动基于 @clack/prompts 的交互式引导:

  1. 提示输入插件名称(默认值/占位符为 my-plugin);
  2. 提示输入目标目录(默认值为 path.resolve(cwd, 'packages/<name>'));
  3. 若用户中途按 Esc/Ctrl+C 取消(isCancel),输出 Operation cancelled 并退出。

非交互模式下,命令会依次做以下校验与操作(见 src/cli/commands.ts 的 create action):

  • 调用 getBuiltinTemplateDir() 定位内置模板目录(源码解析见 src/utils.ts 的 path.resolve(dirname, '../templates/template-vue')),模板即仓库中的 templates/template-vue;
  • 将目标目录的 Windows 反斜杠统一替换为正斜杠(targetDir.replace(/\\+/g, '/'));
  • 若目标目录已存在,输出 target directory already exists 并终止,防止覆盖;
  • 递归创建目录后调用 renderTemplate(templateDir, target, { name }) 完成渲染;
  • 完成后输出 plugin template created at <目标目录>。

renderTemplate(见 src/utils.ts)的处理细节值得一提:

  • 遍历模板目录时跳过 node_modules 与 dist;
  • 文件/目录名中的 {{name}} 占位符会被替换为插件名;
  • 二进制文件(png/jpg/jpeg/gif/svg/ico/webp)直接拷贝;
  • 文本文件用 EJS 渲染(ejs.render(content, data)),渲染失败时回退为纯文本拷贝并打印警告——所以模板里的 <%= name %> 这类 EJS 占位符最终会替换成真实插件名。

三、全局选项与调试日志

所有命令均支持以下全局选项:

  • --debug [feat]:显示调试日志(feat 为可选的调试命名空间);
  • --help:显示帮助信息;
  • --version:显示版本号。

--debug 的底层实现位于 src/cli/commands.ts 的 runCli() 中:它基于 debug 库启用命名空间。

if (cli.options.debug === true) {
  namespace = 'rpa:*'                                  // 全部命名空间
}
else {
  // 支持逗号分隔的多个特性
  namespace = resolveComma(toArray(cli.options.debug))
    .map(v => `rpa:${v}`)
    .join(',')
}
debug.enable(namespace)

也就是说:

  • rpa dev --debug 启用全部 rpa:* 调试日志;
  • rpa dev --debug vite 只启用 rpa:vite 命名空间;
  • rpa dev --debug vite,config 可同时启用多个命名空间(逗号分隔)。

日志输出由 src/logger.ts 提供分级支持(silent/error/warn/info),错误会以红色 ERROR 前缀输出;命令执行失败时 runCli 会捕获异常、记录日志并以退出码 1 结束进程。

四、配置文件 rpa.config.ts 与 defineConfig

CLI 遵循 Vite 的配置加载约定。loadRpaConfig(见 src/config.ts)会依次探测以下文件名并加载第一个存在的配置:

rpa.config.ts
rpa.config.js
rpa.config.mjs
rpa.config.cjs
rpa.config.mts
rpa.config.cts

配置类型 RpaConfig 即 @module-federation/vite 中 federation 插件的参数类型。CLI 对外导出 defineConfig 辅助函数(也支持传入 Promise 或函数形式),用于提供类型提示:

import { defineConfig } from '@rpa/cli'

export default defineConfig({
  name: 'my-plugin',
})

实际构建时(src/cli/vite.ts),用户配置会被展开进 federation({ shared: ['vue', 'vue-router'], ...userConfig, name: remoteName, manifest: true, publicPath: ... }),并固定暴露 './index'。因此你的 rpa.config.ts 中至少应保证 name 与产物构建要求一致,其他 Module Federation 选项(如 remotes、exposes 扩展、shared 调整)也可按需覆盖。

五、亲手跑一个插件:从 rpa create 到宿主加载

5.1 生成模板

rpa create --name hello-rpa --target ./packages/hello-rpa

生成后的目录结构大致如下(对应仓库中的 templates/template-vue):

packages/hello-rpa/
├── package.json          # name 已被替换为 hello-rpa,含 dev/build 脚本
├── rpa.config.ts         # export default defineConfig({ name: 'hello-rpa' })
├── tsconfig.json
├── index.html
└── src/
    ├── index.ts          # definePlugin 入口
    ├── main.ts           # 本地调试挂载
    └── Content.vue       # 设置页 Tab 组件

模板自带的 package.json 直接内置了两条命令,让你无需记忆 CLI 细节:

"scripts": {
  "dev": "rpa dev",
  "build": "rpa build"
}

5.2 理解模板入口 src/index.ts

模板入口使用 @rpa/shared 提供的 definePlugin 与 IPluginContext:

import type { IPluginContext } from '@rpa/shared'
import { definePlugin } from '@rpa/shared'
import { markRaw } from 'vue'
import Content from './Content.vue'

export default definePlugin({
  activate: async (_context: IPluginContext) => {
    console.log('[SimplePluginExample] 插件激活中...')
  },
  deactivate: () => {
    console.log('[SimplePluginExample] 插件停用中...')
    console.log('[SimplePluginExample] 插件停用完成')
  },
  contributes: {
    settingsTabs: [
      {
        id: 'text',
        title: '测试',
        icon: 'plugin',
        content: markRaw(Content),
      },
    ],
  },
})

其类型契约定义在 frontend/packages/shared/src/types/plugin.ts:IPluginModule 由 activate(激活)、deactivate(停用)与 contributes(贡献点)组成;当前模板演示了 settingsTabs 这一贡献点——往客户端"设置"页注册一个 Tab,其中 content 必须是 Vue 组件(用 markRaw 包裹避免被响应式代理)。definePlugin 本身只是一个类型化辅助函数(见 frontend/packages/shared/src/core/plugins.ts)。

依赖说明:模板 package.json 依赖 @rpa/shared(workspace 包)。在独立仓库外使用模板时,请将 "@rpa/shared": "workspace:*" 替换为实际可发布的版本号。

5.3 开发与构建

cd packages/hello-rpa
pnpm install
pnpm dev     # 启动开发服务器,等同 rpa dev
pnpm build   # 生产构建,等同 rpa build

构建完成后,产物的远程模块名由 rpa.config.ts 的 name 决定,入口模块路径为 ./index,publicPath 指向 rpa://extensions/<name>/,并生成 Module Federation manifest——这组约定正是宿主端加载插件所依赖的协议。

5.4 宿主端如何加载:PluginManager 侧写

Astron RPA Web 宿主通过 frontend/packages/web-app/src/plugins/extension/manager.ts 的 PluginManager 管理插件生命周期。与 CLI 构建端对应的关键逻辑:

  • 使用 createInstance 创建 Module Federation 运行时实例,并把 vue、pinia 配置为共享单例(singleton)依赖,与 CLI 构建端 shared: ['vue', 'vue-router'] 呼应;
  • loadPlugin 中通过 this.mf.registerRemotes([{ name, entry }]) 注册远程,再调用 this.mf.loadRemote(${name}/index) 获取插件默认导出——这正好对应 CLI 构建端固定的 exposes: { './index': './src/index.ts' } 与 remoteName;
  • 插件实例拥有 unloaded / loading / loaded / failed 状态机,加载有超时(默认 30 秒)与并发上限(默认 3)保护;
  • activatePlugin 会创建插件上下文(IPluginContext),执行 module.activate(context),随后把 contributes.settingsTabs 注册到客户端的设置页签中。

因此,插件能否被正确加载,取决于 CLI 构建端与宿主端对"模块名 + index 入口 + 共享依赖"三者的约定一致——这就是 rpa.config.ts 中 name 字段在整条链路里的重要性所在。

六、参与开发 @rpa/cli 本身

如果你要改进 CLI 包本身(例如调整命令、扩展模板或修改 Module Federation 配置),在 frontend/packages/cli 目录下执行:

# 安装依赖
pnpm install

# 构建 CLI(tsdown 打包)
pnpm build

# 运行类型检查
pnpm typecheck

# 开发监听模式(tsdown --watch)
pnpm dev

各脚本定义在 package.json:

"scripts": {
  "build": "tsdown",
  "typecheck": "tsc --noEmit",
  "dev": "tsdown --watch"
}

构建配置见 tsdown.config.ts:入口为 src/index.ts,输出 ESM 格式,并开启 dts sourcemap(类型声明文件)。src/index.ts 对外只导出两个公共 API:runCli(命令入口)与 defineConfig/RpaConfig(配置类型)。

七、常见问题与排错提示

  • rpa create 提示 target directory already exists:目标目录已存在时命令拒绝覆盖,请换一个目录或先移走旧目录。
  • rpa create 提示 builtin plugin template not found:说明 templates/template-vue 未随包发布或路径损坏。@rpa/cli 的 files 字段包含 bin、dist、templates(见 package.json),确保从发布包安装时这三个目录完整。
  • 调试日志不显示:检查是否使用了 --debug 且命名空间拼写正确;未带参数时启用全部 rpa:*。
  • 构建后宿主加载失败:优先核对三点——rpa.config.ts 中 name 与宿主端注册的插件名一致;src/index.ts 存在且默认导出 definePlugin(...) 的模块;publicPath 遵循 rpa://extensions/<name>/ 约定(构建端已自动设置,通常无需手动改)。
  • 依赖版本不匹配:模板中 workspace:* 的 @rpa/shared 引用只在 pnpm monorepo 内有效,独立发布插件时请改为具体版本号。

结语

@rpa/cli 用三个命令串起了 Astron RPA 插件开发的完整闭环:rpa create 提供标准模板与交互引导,rpa dev 提供 Vite + Module Federation 的开发调试体验,rpa build 产出遵循 rpa://extensions/ 协议的发布产物,最终由宿主端 PluginManager 以模块联邦方式动态加载。理解这条链路,你就能快速为 Astron RPA 编写可分发、可热更的扩展插件;而这一切的起点,就是一条 rpa create 命令。

登录后查看全文
astron-rpa