插件系统概览

Vome 插件以 .vome 为分发格式（ZIP，扩展名改为 .vome）。安装后由宿主 Service 解压、注册钩子或挂载微前端，无需单独进程或端口。

开发入口是三套脚手架（与开发框架的 Service / Admin / Web / UniApp 文档同级拆分）：

脚手架	类型	包内容	文档
plugin-service	纯后端	`module.json` + `server/`	钩子、`invoke`、打包 · 源码下载
plugin-front	纯前端	`module.json` + `web/`	菜单、`wujie`、打包 · 源码下载
plugin-full	全栈	`module.json` + `server/` + `web/`	上两者合集 · 源码下载

Admin「插件开发」页默认走 Gitee 脚手架 ZIP（vome-core → pluginDev）。

包内至少满足其一：server/index.js（钩子）、web/index.html（微应用）。有 hook 时必须带 server/。

怎么选脚手架

场景	选用
只提供服务端能力（上传、短信、支付钩子、内部 API）	plugin-service
只要 Admin 里多一个管理页（无独立后端逻辑）	plugin-front
既要钩子/接口，又要 Admin 管理页	plugin-full

与 vome-core 的关系

插件复用 core 的扩展面，不是把整套 Service / Admin 打进 .vome。

能力	service	front	full
`BasePlugin` / `ready` / config / cache	✓	—	✓
`invoke` 公开方法	✓	—	✓
`handlers` + `/admin/ext/{key}/…`	✓	—	✓
微应用 `web/` + menus + wujie	—	✓	✓
主题同步（透明底 + CSS 变量 + bus）	—	✓ 强制	✓ 强制
语种同步（跟随 Admin，`vome-host-locale`）	—	✓ 强制	✓ 强制
同域 `hostRequest`（Bearer + `/dev` 前缀）	—	✓	✓
可选 EPS `bootHostEps` + `service.*`	—	✓	✓
前端调本插件 ext 网关	—	—	✓
宿主 IoC / 声明式 CRUD / Repository	✗（写在宿主 service）	✗	✗
默认打入整包 `vome-core/admin` CRUD UI	—	不推荐	不推荐

脚手架已内置示例：

service / full：ping、echo、GET /admin/ext/{key}/hello
front / full：hostRequest → /admin/base/auth/me；可选 EPS 探测
full 微应用：还可调 …/hello

详细边界见各脚手架开发指南（service / full）与 plugin-front 开发指南。

清单 `module.json`（共用）

字段	必填	说明
`name`	是	显示名称
`key`	是	唯一标识，`[a-zA-Z0-9_-]+`，不可为 `plugin`
`version`	是	语义化版本
`description` / `author` / `logo` / `readme`	否	元信息
`hook`	否	钩子槽名；同槽位只能启用一个插件
`singleton`	否	`true` 复用单例；`false` 每次 `getInstance` 新建
`config.@local` / `config.@prod`	否	分环境配置，
`routes`	否	扩展路由 `{ method, path, handler, perms?, summary? }[]`
`menus`	否	Admin 菜单；有微应用时 `appKey` 通常等于 `key`

安装与落盘

bun run pack → release/{key}.vome
Admin → 扩展插件 → 上传安装（POST /admin/base/module/install）
宿主写入 base_plugin_info（含纯前端）+ 可选菜单；列表中启用

已安装模块目录（相对宿主 service 工作目录，可随项目/部署包拷贝）：

.vome/{md5(keys)}/modules/{key}/

内容	路径
钩子脚本	`server/index.js`（发布包为混淆 CJS）
微应用静态资源	`web/`
浏览器访问	`GET /vome/apps/{key}/`（wujie + 主题同步）

元数据在表 base_plugin_info。

调用后端插件（宿主 Service）

import { Inject, Provide } from '@core/server'
import { PluginInfoService } from '../base/service/plugin'

@Provide()
export class YourService {
  @Inject()
  plugin: PluginInfoService

  async demo() {
    const inst = await this.plugin.getInstance('scaffold-demo') // hook 或 key
    await (inst as { ping: () => Promise<unknown> }).ping()

    await this.plugin.invoke('scaffold-demo', 'ping')
  }
}

API	说明
`getInstance(key)`	按 `keyName` 或 `hook` 找已启用插件
`invoke(key, method, ...args)`	调用实例公开方法
`getConfig(key)`	当前环境合并后的配置

须已安装且启用。混淆后公开方法名须加入脚手架仓库 scripts/obfuscator.options.ts 的 reservedNames（见 plugin-service 打包）。

上传与发布

本地/内网：Admin 插件管理上传 .vome 即可（见各脚手架「安装」页）
官方签封：市场下载包带 market.sig；付费可带 market.lic。宿主生产构建（--define SEAT_ENFORCE:true）安装时验签 + license + 席位；bun run dev 不强制。自研无签名包仍可装。
市场发布上传：见发布 — 流程与签发包由市场服务端写入 market.sig，作者本地 pack 不必手写签名文件

详见 Service 插件门禁。

禁止事项

key 命名为 plugin
将 node_modules 打进 .vome（后端用 bun build --packages=bundle）
混淆后未保留公开方法名导致 invoke 失效
前端 vite 的 base 不用相对路径 ./（会导致 wujie 下资源 404）

插件系统概览 ​

怎么选脚手架 ​

与 vome-core 的关系 ​

清单 module.json（共用） ​

安装与落盘 ​

调用后端插件（宿主 Service） ​

上传与发布 ​

禁止事项 ​