插件是什么

插件化是在司空（FH2）上承载二次开发业务的方式。插件可以把自定义的界面和操作放进用户已经在使用的页面：在驾驶舱添加工具栏按钮、侧面板和直播覆盖层，在飞行计划表单中补充业务配置，在项目页面添加侧边栏入口和工作区，在消息中心用卡片承载业务操作。

前端插件使用 TypeScript 与 Vue 3，通过宿主（Host）提供的扩展点接入页面；后端插件按平台定义的清单、接口与流程运行，承担接口处理、事件消费、数据存储和流程编排。前端、后端可以单独交付，也可以组合成全栈插件。插件可用的宿主能力、扩展点与接口范围由平台契约决定，不在契约内的能力不能通过文档约定获得。平台定位和请求链路见 产品简介。

插件在司空中的位置

上图是从业务视角看一个插件接入司空后的位置：

• 前端成员运行在司空前端宿主里，通过宿主扩展点出现在驾驶舱、计划库、项目页和消息中心四个页面，并调用宿主提供的项目、地图、设备、相机、遥测和通知能力。
• 后端成员运行在插件后端运行时里。前端通过 ctx.apiCall 调用后端 Handler，请求经插件网关进入业务逻辑；事件由流程引擎处理，数据、媒体、航线、通知和受管出网由能力沙箱统一提供。
• 司空平台服务仍然独立运行：插件可以按契约下发飞行任务、存取媒体、读写事件，平台也可以把外部警情接入插件；消息推送通过宿主的消息通道更新页面。
• 开发工具链（fh2-plugin CLI + SDK）负责创建工程、本地调试、类型生成和构建打包，插件以构建产物的形式安装装载。

插件能做什么

宿主	用户可见位置	典型能力
驾驶舱 cockpit	工具栏按钮、侧面板、直播覆盖层、子画面页签	示教航线、巡逻进度、车辆照片、现场处置入口
计划库 plan	飞行计划表单中的业务填写区域	业务参数随计划一起校验、提交，并写入 biz_ext
项目页面 project	左侧导航入口、插件工作区与路由	业务列表、签收派遣、与地图联动
消息 message	消息中心告警弹层中的自定义卡片	设备与路线选择、一键派遣

三类典型业务（违停巡逻、事故快处、现场问题）的前后端分工、用户旅途和共同边界，见 典型场景。

你会完成什么

在本地驾驶舱打开一个插件面板，点击计数按钮，把面板标题改成自己的文字，最后完成校验和打包。整个过程在本地模拟页面中进行，不需要真实设备或司空账号，也不需要在前端、后端和全栈教程之间跳转。

三条路线怎么选

路线	适合的情况	完成后得到什么
第一个插件	第一次接触插件开发	创建工程，在本地驾驶舱打开面板，修改并打包
后端插件	主要写服务端逻辑	创建后端成员，写 HTTP 接口并在本地模拟器调用
全栈闭环	要把前后端接起来	完成“表单 → 接口 → 存储 → 刷新读回”的闭环

三条路线共用同一套开发者工具和工程结构，收尾都是同一套「校验 → 构建 → 打包」，做完一条后其他路线可以直接复用工程；总览见 快速开始总览。打包出来的是安装包，上传、安装和回滚见 安装、升级与回滚。

需要多步执行、等待信号或下发任务时，再看 流程编排练习（DAG）；已有工程查具体问题，看 开发指南。

准备工作

• 插件开发工具源码包（下称开发者工具），SDK 与 Toolchain 随同一份源码提供，git clone 或下载 ZIP 解压
• Node.js 20.19 或更高版本、pnpm、浏览器和编辑器
• 可写目录、能下载第三方依赖的网络，以及空闲端口 5176

开发者工具目录中应包含 package.json、pnpm-lock.yaml 和 public-distribution.json；安装和构建会写入这个目录，请保留固定路径供工程依赖使用，不要修改锁文件。

五个步骤

步骤	做什么	完成标志
1. 准备开发工具	在开发者工具根目录安装依赖、构建工具链，并定义一个指向源码的 fh2-plugin 短命令。	终端能输出版本号，与发版说明一致。
2. 创建工作区	在开发者工具目录之外执行 fh2-plugin create，工程类型选择完整能力工作区。	生成含前后端示例的工作区，并完成依赖安装与类型复验。
3. 启动本地驾驶舱	在工作区根执行 pnpm exec fh2-plugin dev cockpit --root ./exp_hello，打开终端打印的完整地址。	在开发工具栏启用插件，点击按钮打开示例面板，计数从 0 变为 1。
4. 修改面板标题	修改 HelloPanel.vue 中的一行标题。	保存后前端重建，页面自动刷新并显示新标题。
5. 校验、构建并打包	停止 dev 命令，依次执行生成、校验、测试、构建和打包脚本。	前后端成员各自产出 dist/，并生成发布用的 ZIP 包。

第 4 步的改动示例

打开 exp_hello/frontend/exp_hello_frontend/src/views/hello-panel/HelloPanel.vue，只改标题一行，其余文件保持原样：

<h2>我的第一个插件 View</h2>

改为：

<h2>你好，这是我的插件</h2>

保存后等待前端重建成功，页面会自动刷新；如果面板收起，重新点击「打开示例面板」。刷新后计数从 0 开始是正常的，模板只保存前端内存状态。

第 5 步的命令

在工作区根依次执行，任一命令失败时先处理错误再继续：

pnpm run generate
pnpm run validate
pnpm run test
pnpm -r --if-present run tsc
pnpm -r --if-present run lint
pnpm run build
pnpm run pack

全部成功后，打包结果位于 exp_hello/release/exp_hello_package.zip，包内应包含 packages.json、能力目录和前后端运行产物，不包含 node_modules。

完成以后

• 判断自己的业务能做成什么样：典型场景
• 扩展前端或配套后端：详细开发方案
• 让 AI 一起开发：AI 开发 Skill
• 启动失败或改动没生效：快速入门排错、调试与测试

完整教程

快速开始总览、第一个插件。