产品简介

FH2 插件开发手册

司空（FH2）插件是一种由平台独立加载、可独立版本化的业务扩展包。它把一项业务接到用户已经熟悉的页面上，也可以把业务逻辑放到服务端执行；前端界面、后端接口、流程和数据可以作为一个能力一起开发、构建和交付。

适用范围：插件化只在私有化部署的司空中提供，公有云版司空不包含插件底座。本手册的环境准备、扩展点、打包与安装流程都以私有化司空为目标环境。

插件化底座面向司空自身的深度改造与定制。 与主要用于控制司空、或将司空能力集成到外部系统的开放接口不同，插件可以直接扩展司空的页面内容、交互和业务流程。例如，在驾驶舱加入行业操作面板、在计划表单加入业务字段、在项目页提供专属工作区，并连接配套后端。定制通过已开放的扩展点和能力完成。

插件化底座技术架构

插件围绕一个明确的业务目标组织：

前端成员：在项目、消息、计划或驾驶舱页面增加按钮、表单、卡片、列表或面板。

后端成员：提供 HTTP 接口、消费平台事件、执行流程作业，读写数据或连接外部系统。

共享契约：前后端共同使用的输入、输出和错误约定。

清单与产物：清单声明身份、入口和权限；构建后生成宿主可装载的产物。

一个业务能力可以只包含前端成员，也可以只包含后端成员，或者两者都有。前后端是独立插件，身份不同；前端调用后端时使用后端插件的身份。

插件化底座负责把这些成员的开发、运行和安装连接起来：

开发工具与 SDK：创建工程、声明接口、生成类型，校验并构建前后端产物。

司空宿主与前端插件：宿主提供扩展点和能力；插件提交按钮、面板、表单等内容，由宿主显示和管理生命周期。

插件网关与后端运行时：前端通过受管通道调用后端；后端处理接口、事件、流程和数据。

行业包与管理平台：前后端成员随能力打包，安装后分别由前端宿主和后端运行时加载。

各部分如何连接、请求与事件如何流转，见平台架构。

前端能做什么

司空前端提供四类宿主（Host），插件通过扩展点进入这些页面：

宿主	用户可以做什么	插件典型贡献
`cockpit` 驾驶舱	在直播旁操作、查看任务和照片	工具栏按钮、进度面板、目标列表、照片页签
`plan` 计划库	新建或复制飞行任务时填写业务信息	表单区域、校验、提交补丁
`project` 项目页面	从侧边栏进入业务列表或工作区	项目入口、插件路由、工作区
`message` 消息中心	在告警弹层处理业务消息	自定义告警卡片、卡片内操作

插件使用宿主能力读取项目、地图、设备、相机、遥测等数据。能力必须在清单中声明，运行时先获取再判空；拿不到时应该隐藏或降级，而不是绕过宿主。

前端插件不只是“往页面里塞一个 Vue 组件”。插件入口（Entry）是完整的前端运行时：它可以在驾驶舱读取遥测和控制权、订阅机载 AI 的逐帧检测结果（时间来自 SEI）、在直播画面上覆盖自己的 Canvas 做标注，并基于这些状态做业务判断。变道抓拍就是典型：它一边在直播画面上绘制实线/导流区，一边用 cockpit:detection 的逐帧目标和 cockpit:scene-geometry 做同帧投影与压线判断，命中后再用 cockpit:camera 截取当前直播帧作为证据。完整链路见交通抓拍的前端运行链。

后端能做什么

后端插件运行在服务端 Worker 中，主要提供四类能力：

HTTP 接口：给前端或其他系统调用，处理业务读写。

事件消费：订阅平台消息，处理媒体生成、状态变化等异步事件。

流程编排：用步骤、依赖和等待信号组织长流程；下发任务、返航等高风险动作只通过流程受控步执行。

数据与连接：读写数据存储、缓存，调用受管出网和平台连接器，向前端发送通知。

后端脚本跑在受控沙箱里，不是 Node.js 进程：只能用清单里申报过的能力，没申报的对象拿不到；飞行控制这类高风险动作也不能直接调，要下发任务得走流程。

一次请求如何走完

用户操作
  → 前端界面（View）
  → 插件入口（Entry）调用 ctx.apiCall
  → 插件网关
  → 后端 HTTP 接口
  → 数据存储 / 外部连接
  → 返回前端，更新界面

异步链路则是：平台消息 → 后端事件回调或流程 → 写入状态/发送通知 → 前端轮询或订阅后更新。完整架构和失败边界见平台架构。

适合与不适合

适合做成插件的需求通常满足：

有明确的页面入口，或者只需要后端接口和异步处理。

能通过公开扩展点、宿主能力和后端 API 完成。

可以独立安装、停用和升级，不修改司空源码。

不适合的情况：

需要绕过扩展点和受管能力，直接改宿主页面 DOM、读写宿主内部状态或拿登录凭据。

需要绕过受管网络、直接操作飞行控制或访问未开放的能力。

必须改司空产品源码才能实现，不能作为独立插件交付。

从哪里开始

首次使用开发工具时，先完成环境准备，再进入前端、后端或全栈练习；使用 AI 时先按安装页准备 Skill。

你的情况	建议入口	完成后能做什么
先看一个能操作的插件	第一个插件	创建工程，在本地驾驶舱打开面板，修改并打包
主要写服务端逻辑	后端插件	创建后端成员，写 HTTP 接口并在本地模拟器调用
要把前后端接起来	全栈闭环	完成“表单 → 接口 → 存储 → 刷新读回”的闭环
想让 AI 辅助实现	用 AI 开始	描述需求、确认方案、让 AI 改代码并执行检查
已有工程，查具体问题	开发指南	按概念、能力、调试、示例和 API 查找

先判断需求像不像插件，读典型场景；需要精确接口时，查API 参考。

下载 SDK 与开发工具

源码与 SDK 在同一个仓库：github.com/dji-sdk/FlightHub-2-Plugin。

源码解压后，SDK 位于 packages/fh2-plugin-sdk/，Toolchain 位于 packages/fh2-plugin-toolchain/，Skill 位于 skills/fh2-plugin-dev/，无需另找 SDK 下载包或同名 npm 包。在源码目录初始化工具后，创建插件工程时会自动接入本地 SDK。完整步骤见环境准备；Skill 安装见安装与复验。

环境依赖

本机准备以下环境即可开始；版本变化、已知限制和兼容矩阵见发版说明。

项目	要求
插件开发工具	完整源码（GitHub 下载或 clone），保留目录结构并按环境准备初始化
Node.js	20.19 或更高（推荐 22 LTS 及以上）
pnpm	随 Node.js 提供的 Corepack 自动准备（10.15.0），不用全局安装
浏览器	用于本地调试页面和 Web IDE

插件化底座技术架构#

前端能做什么#

后端能做什么#

一次请求如何走完#

适合与不适合#

从哪里开始#

下载 SDK 与开发工具#

环境依赖#