前端宿主、扩展点与能力

这一页解释前端插件的三个核心概念：宿主（插件跑在哪个页面）、扩展点（插件能占据页面的哪些位置）、宿主能力（插件能调用前端的哪些功能）。后端的能力注入、allowlist 和脚本沙箱见后端运行时、入口与权限。

宿主

宿主就是承载插件的页面。司空里有四个宿主：

宿主	页面	提供的扩展点
`cockpit`	驾驶舱	8 个（工具栏按钮、菜单栏、直播覆盖层、左下角面板、左面板、子直播页签、飞控操作、右键菜单）
`project`	项目	项目侧边栏入口 + 自定义页面
`plan`	计划	飞行计划表单扩展
`message`	消息	告警弹层

写入口代码时用 ctx.host.id 判断当前在哪个宿主里，各宿主各写各的逻辑：

fh2-plugin-sdk 是插件开发 SDK 的文档逻辑模块名；实际导入路径保留生成工程的配置，见环境准备。

import { definePlugin } from 'fh2-plugin-sdk'

export default definePlugin({
  async activate(ctx) {
    if (ctx.host.id === 'cockpit') {
      // 驾驶舱的逻辑
    } else if (ctx.host.id === 'project') {
      // 项目页的逻辑
    }
  },
})

扩展点

扩展点是宿主在页面上预留的位置。插件声明"我要在这个位置放一个东西"，宿主负责把它挂上去。你不能往扩展点以外的地方放界面。

以项目侧边栏为例，清单里这样声明：

{
  "extensions": [
    { "id": "project-entry", "point": "project.sidebar-actions", "path": "/plugin-demo", "position": 50 }
  ]
}

然后在入口代码里提交这个扩展的具体内容：

await ctx.extensions.contribute('project-entry', {
  icon: 'plugin',
  label: '插件示例',
  disabled: false,
  showBadge: false,
  render: () => demoView.get(ctx),   // demoView 是 definePluginView 契约对象，见「界面与状态」一页
})

注意分工：path、position 这类安装时就确定的配置写在清单里；label、disabled、render 这类运行时会变的状态和回调在代码里提交。把后者写进清单会被校验拒绝。

每个扩展点的完整字段说明见扩展点目录。

能力

能力是宿主提供给插件调用的功能，比如地图打点、打开弹窗、读取当前项目信息。完整目录见能力目录。用能力分三步：

第 1 步：清单里声明权限。

{
  "permissions": ["project:context", "platform:map"]
}

第 2 步：代码里获取能力调用方。

const project = await ctx.capabilities.get('project:context')

第 3 步：判空再使用。

if (!project) {
  // 当前宿主没提供这个能力（比如插件没装在项目页），走降级逻辑
  ctx.logger.warn('project:context 在当前宿主不可用')
  return
}
const state = await project.getState()
const { projectId } = state

undefined 是正常情况，不是报错——同一个插件可能被装到多个页面，某个页面没有这个能力很常见。每次获取后都必须判空。

四个基础能力不经过 capabilities.get()，直接用 ctx 上的对应成员：

能力	用法
`platform:http`	`ctx.apiCall(...)`
`platform:events`	`ctx.events.on(...)`
`platform:websocket`	`ctx.ws.onBizCode(...)`
`platform:storage`	`ctx.storage` / `ctx.blobs`

验证

改完清单记得生成类型并校验：

校验会把"清单里写了运行时字段""viewId 指向不存在的界面"这类问题当场报出来。

后端不是这一套

后端插件不通过 ctx.capabilities.get() 获取能力，也没有 extensions。它用 handlers/、events/、adapters/ 声明入口，用 allowlist 申报能力，平台把能力作为全局对象注入。不要把前端权限、后端权限和业务能力扩展混为一谈。

前端宿主、扩展点与能力

宿主#

扩展点#

能力#

验证#

后端不是这一套#

宿主

扩展点

能力

验证

后端不是这一套