前端平台事件目录

平台事件是宿主主动推送给插件的通知（如急停触发、直播生命周期变化）。目录是封闭的：目前只有驾驶舱的 2 个，插件不能自定义事件名，也不能用 TypeScript 类型合并扩展事件数据。

事件表

事件名	权限	宿主	事件数据	语义
`cockpit.emergency-stop`	`platform:events`	cockpit	`{timestamp, source?}`	急停已触发/受理；不保证设备最终执行成功
`cockpit.live.lifecycle`	`platform:events`	cockpit	`{phase: 'started'\|'first-frame'\|'stopped'\|'channel-changed', liveId, cameraIndex: string\|null, timestamp}`	直播通道生命周期

订阅需要 platform:events 权限（清单 permissions 声明）。

示例

// plugin.ts
const subscription = await ctx.events.on('cockpit.live.lifecycle', event => {
  if (event.payload.phase === 'first-frame') {
    // first-frame（首帧）才是逐帧处理的安全起点；started 只表示建联
    ctx.logger.info('直播首帧就绪', {liveId: event.payload.liveId})
  }
})

await subscription.dispose()  // 主动退订；插件停用时平台也会统一回收

分发语义

宿主只向已激活的插件运行时分发；不缓存、不重放订阅之前发生的事件。

驾驶舱会按当前路由设备过滤：路由上没有 droneSn，或事件携带的 SN 与当前路由不一致时不分发。

plan / project / message 宿主目前不派发平台事件。

注意：平台事件不是权威状态。急停后要查询飞行/设备状态确认结果；stopped、channel-changed 后要重新读取当前直播状态。

WebSocket 业务消息（不是平台事件）

订阅宿主已建立的共享 WebSocket 上的业务消息，接口是 ctx.ws.onBizCode，需要 platform:websocket 权限：

interface PluginWsEvent<TData> {
  bizCode: string
  subBizCode: string | null
  timestamp: number | null
  data: TData
}

const off = await ctx.ws.onBizCode('xx_confirm', msg => {
  ctx.logger.info('收到业务消息', {bizCode: msg.bizCode})
})

插件不能建连、发送或控制重连，只能只读订阅；bizCode 必须非空且无首尾空格。

常见问题

现象	原因与处理
`ctx.events.on` 报事件名不认识	目录封闭，只有上表 2 个事件名；业务消息请走 `ctx.ws.onBizCode`
订阅后收不到事件	清单没声明 `platform:events`；或事件发生在订阅前（不重放）；或被路由设备过滤
急停事件后设备还在动	事件只表示「已触发/受理」；以设备状态查询为准

事件表#

示例#

分发语义#

WebSocket 业务消息（不是平台事件）#

常见问题#

事件表

示例

分发语义

WebSocket 业务消息（不是平台事件）

常见问题