项目设备能力

platform:devices 返回当前项目下"机场 + 飞机 + 网关"的设备快照，供插件做设备筛选、派遣候选判断等。清单声明 platform:devices 权限，代码里 await ctx.capabilities.get('platform:devices') 获取并判空。四个宿主都可获取，但依赖登录态、项目权限和拓扑接口，失败时会 Reject。

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

const devices = await ctx.capabilities.get('platform:devices')
if (!devices) {
  ctx.logger.warn('设备能力不可用')
  return
}
const groups = await devices.getProjectDevices({ projectId })

方法清单

方法	输入	返回
`getProjectDevices`	`{ projectId: string }`	`Promise<readonly PlatformProjectDevice[]>`

返回字段

每个 PlatformProjectDevice 是一组相关设备：

字段	类型与语义
`aircraft`	飞机信息或 `null`
`dock`	机场信息或 `null`
`gateway`	网关设备或 `null`；网联飞机为飞机自身，否则通常是父设备

通用身份字段（PlatformDeviceIdentity）：

sn: string

model: { id, name }。稳定 id 取值：dock、dock-2、dock-3、dock-4、m30、m30t、m3d、m3td、m4d、m4td、m5td、matrice-400、unknown

callsign: string|null

connectionState: 'online'|'offline'|'unknown'

机场额外字段：position: GeoPoint|null、operatingState。operatingState 取值：

idle|on-site-debugging|remote-debugging|upgrading|executing-task|uncalibrated|low-power|emergency-stop|battery-swap|log-fetching|offline|unknown

。

归一化约定

宿主已把底层拓扑数据整理过，使用时注意：

位置缺失返回 null；机场可能回退到离线前位置；缺高度时为 0。

飞机在舱且自身离线时，会根据机场子设备状态推导为 shutdown-in-dock、starting-up 或 not-connected。

舱内关机/开机中取机场充电电量，其他状态取飞机自身电量；异常值 255 归一为 null。

未知机型一律 unknown，业务判断使用上表列出的稳定 model.id。

该能力只描述设备，不判断"可派遣"：业务上仍要检查在线状态、位置、电量、工作状态和后端规则。

集成片段

先按第一个前端插件建立可运行工程。下面不是完整的 fh2-plugin.json，不可整份替换：将 permissions 去重合并到现有清单，保留现有宿主扩展、界面声明/注册和入口。权限不会触发激活；清单若只有 extensions: []，activate() 不会执行。

合并到 fh2-plugin.json 的字段：

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

下面的 definePlugin 只示范入口逻辑组织，不是可直接替换完整工程的入口；保留生成工程的 SDK 导入路径，将能力逻辑合入已有项目宿主的 activate，保留项目宿主扩展贡献与界面注册。项目宿主接入见项目侧栏扩展；读取设备还需有效项目 ID 和拓扑接口权限。

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

export default definePlugin({
  async activate (ctx) {
    const devices = await ctx.capabilities.get('platform:devices')
    const project = await ctx.capabilities.get('project:context')
    if (!devices || !project) {
      ctx.logger.warn('设备列表只在具备项目上下文和设备提供方时启用')
      return
    }

    const { projectId } = await project.getState()
    if (!projectId) {
      ctx.logger.warn('当前没有有效项目')
      return
    }

    try {
      const groups = await devices.getProjectDevices({ projectId })
      const candidates = groups.filter(({ aircraft, dock, gateway }) => {
        return aircraft?.connectionState === 'online'
          && aircraft.position !== null
          && (aircraft.batteryPercent ?? 0) >= 30
          && aircraft.operatingState === 'standby'
          && gateway?.connectionState === 'online'
          && (dock === null || dock.operatingState === 'idle')
      })
      ctx.logger.info('可派遣设备候选', {
        devices: candidates.map(item => ({
          droneSn: item.aircraft!.sn,
          gatewaySn: item.gateway!.sn,
          model: item.aircraft!.model.id,
        })),
      })
    } catch (error) {
      ctx.logger.error('项目设备加载失败', {
        message: error instanceof Error ? error.message : String(error),
      })
    }
  },
})

project:context 只在项目宿主提供（见项目上下文）；platform:devices 本身在其他宿主也能用，只要业务已安全拿到 projectId。

常见问题

现象	原因与处理
`getProjectDevices` 抛错	拓扑接口无权限、业务错误或项目已切换；捕获并停止后续流程
拿到的设备比预期少	缺角色的组也会返回（对应字段为 `null`），自行按需过滤
机型显示不对	展示用 `callsign ?? sn`，业务判断用稳定 `model.id`，不要用展示名
电量显示为空	异常值已归一为 `null`，展示时留空即可，不要当 0 处理

方法清单#

返回字段#

归一化约定#

集成片段#

常见问题#

方法清单

返回字段

归一化约定

集成片段

常见问题