多宿主插件实战

这是一份集成说明，不是完整工程：讲同一个插件怎样在驾驶舱、计划、消息和项目四个宿主分发代码，再通过服务交换数据。先完成一个单宿主练习，按实际需求增加第二个宿主；不要一次复制下面的清单就期待四处界面全部出现。

fh2-plugin-sdk 是插件开发 SDK；下文模块名用于说明，实际导入路径保留生成工程配置。模块名不表示已发布的 npm 包名。

这个示例做什么

一个插件包，四个宿主各挂一个功能；每个宿主只加载自己的那部分代码。

总入口按 ctx.host.id 分发到各宿主的激活逻辑，互不干扰。

演示插件内跨宿主通信的标准方式：跨宿主通信服务（类型化契约），而不是直接 import 另一个宿主的运行对象。

关键代码讲解

清单：同时声明多个宿主的扩展点

fh2-plugin.json：

{
  "id": "exp_multi_host",
  "name": "多宿主示例",
  "version": "0.1.0",
  "entry": "./plugin.js",
  "extensions": [
    { "id": "hello-action", "point": "cockpit.ui.toolbar-actions" },
    { "id": "hello-panel", "point": "cockpit.ui.left-panel" },
    { "id": "hello-plan", "point": "plan.form-extensions", "planType": "all" },
    { "id": "hello-message", "point": "message.alert-popups" },
    { "id": "hello-project", "point": "project.sidebar-actions", "path": "/hello-project" }
  ],
  "views": {
    "hello-cockpit": { "entry": "./views/hello-cockpit.js" },
    "hello-plan": { "entry": "./views/hello-plan.js" },
    "hello-message": { "entry": "./views/hello-message.js" },
    "hello-project": { "entry": "./views/hello-project.js" }
  }
}

各宿主贡献的具体写法见前面的单宿主示例：驾驶舱按钮、计划表单、消息告警、项目侧边栏。

总入口：只做分发

// src/plugin.ts
import { definePlugin } from 'fh2-plugin-sdk'

export default definePlugin({
  async activate (ctx) {
    switch (ctx.host.id) {
      case 'cockpit':
        return (await import('./hosts/cockpit/activate')).activate(ctx)
      case 'plan':
        return (await import('./hosts/plan/activate')).activate(ctx)
      case 'message':
        return (await import('./hosts/message/activate')).activate(ctx)
      case 'project':
        return (await import('./hosts/project/activate')).activate(ctx)
      default:
        ctx.logger.warn(`[multi-host] 未知宿主: ${ctx.host.id}，跳过激活`)
        return undefined
    }
  },
})

要点：

总入口不导入 Vue、不访问 DOM，保持轻量。

每个宿主的逻辑放在独立文件里动态导入，避免一个宿主加载其他宿主的组件和能力。

每个宿主是独立运行时、独立激活：卸载驾驶舱不影响另外三个宿主。

跨宿主通信服务

先声明契约：

// src/services/hello-dispatch.ts
import { definePluginService } from 'fh2-plugin-sdk'

export interface HelloDispatchInput {
  readonly executionId: string
  readonly title: string
}

export interface HelloDispatchService {
  presentDispatch (input: HelloDispatchInput): { readonly accepted: boolean }
}

export const helloDispatchService = definePluginService<HelloDispatchService>('hello-dispatch')

提供方（比如消息宿主激活时）：

// src/hosts/message/activate.ts
import { helloDispatchService } from '../../services/hello-dispatch'

export async function activate (ctx) {
  // ...注册告警卡片（写法见消息告警示例）

  await ctx.services.provide(helloDispatchService, {
    presentDispatch (input) {
      ctx.logger.info('收到派遣展示请求', { executionId: input.executionId })
      return { accepted: true }
    },
  })
}

消费方（任何宿主）：

const client = await ctx.services.connect(helloDispatchService)
const result = await client.presentDispatch({ executionId: 'e-1', title: '警情派遣' })

要点：

服务按契约通信，方法都是 Promise。connect() 返回稳定逻辑 Client，不等待具体 Provider；Provider 缺席或卸载时，业务方法抛 SERVICE_UNAVAILABLE，事件订阅在 Provider 重建后自动恢复。

宿主之间不要共享模块级可变状态：每个宿主是独立运行时，直接共享状态会错乱。需要共享就走跨宿主通信服务，或者各自从后端读权威数据。

怎样组装并验证

先完成环境准备，再创建工程。保留生成工程的依赖、构建配置和实际 SDK 导入路径，按本页合并清单并修改业务实现；新增文件的 SDK 导入路径沿用模板。按单宿主示例补齐四份激活逻辑、界面契约、入口和组件后，可在本地调试页面验证分发与跨宿主通信服务；各宿主的真实业务边界仍以单宿主示例为准。

在确认的业务父目录运行创建向导，选择「1=前端插件」，Plugin ID 输入 exp_multi_host，其余项按默认值确认并选择立即安装。命令只要求终端能直接运行 fh2-plugin；未注册全局 CLI 时，把它替换为开发者工具目录中 packages/fh2-plugin-toolchain/bin/fh2-plugin.mjs 的实际路径：

验证步骤：

默认团队页只有项目和消息宿主；进入计划表单后再验证计划贡献，进入虚拟驾驶舱后再验证驾驶舱贡献。四个宿主不同时显示在一个页面上。

在对应页面分别验证按钮、面板、告警卡和侧栏；每个宿主只应显示自己声明的贡献。上方清单的界面 ID 必须与实际文件、注册契约一致。

在顶部工具栏打开「Host」，卸载当前已挂载的驾驶舱；项目和消息仍保持挂载。此时计划宿主不在当前页面拓扑中，不应要求它保持挂载。

点击实际入口「恢复页面 Host」，只补回当前页面缺少的宿主；已经挂载的项不重载。重新打开对应界面，确认没有重复贡献。

逐个卸载已挂载宿主，在诊断面板核对相关资源释放。示例需要你补齐四份激活与界面文件；本页不以清单校验成功证明这些业务已接线。

常见问题

现象	原因与处理
只有驾驶舱生效	总入口的 switch 没覆盖其他宿主，或清单没声明对应扩展点
某个宿主失败被当成整个插件失败	多宿主插件可以处于"部分降级"状态；看健康状态里的 `activeHosts / failedHosts`
宿主之间状态错乱	有代码在宿主间直接共享模块级状态；改用跨宿主通信服务或后端权威数据
跨宿主通信服务调用没反应	Provider 缺席时 `connect()` 仍可成功，业务方法会抛 `SERVICE_UNAVAILABLE`；核对服务 ID 与契约，或等 Provider 重建后重试业务方法
部分宿主行为不一致	项目/消息/计划宿主是 iframe 隔离运行时，检查跨运行时序列化和 CSP

延伸阅读

多宿主插件：宿主路由与生命周期详解。

跨宿主通信服务：provide / connect 完整说明。

宿主与能力模型：四个宿主分别提供哪些能力。

这个示例做什么#

关键代码讲解#

清单：同时声明多个宿主的扩展点#

总入口：只做分发#

跨宿主通信服务#

怎样组装并验证#

常见问题#

延伸阅读#