WPMZ 与航线预览

这两个能力都由主应用提供、四个宿主可用，但职责不同：platform:wpmz 处理航线文件（KMZ/WPMZ）的解析和受控改写，platform:wayline-preview 在公共地图上画临时航线。清单分别声明 platform:wpmz、platform:wayline-preview 权限，await ctx.capabilities.get(...) 获取并判空。

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

`platform:wpmz`：解析与改写航线文件

const wpmz = await ctx.capabilities.get('platform:wpmz')
if (!wpmz) return

方法	输入	返回
`parseCoordinates`	`{ url, referenceAltitude? }`	`Promise<readonly GeoPoint[]>`
`rewrite`	`{ target: { projectId, waylineId }, changes: { missionConfig? } }`	`Promise<{ waylineId, changed }>`

parseCoordinates 下载 KMZ，读取 wpmz/waylines.wpml 中每个航点的坐标和 executeHeight。非法点会跳过；referenceAltitude 会加到每个点的高度上，但不会修改原文件。

rewrite 当前只允许改写 missionConfig：

finishAction?: 'no-action'|'go-home'|'auto-land'|'goto-first-waypoint'

rcLost?: { behavior: 'continue' } | { behavior: 'execute-action'; action: 'go-home'|'land'|'hover' }

takeOffReference?: { longitude; latitude; altitude; aglHeight? }

限制：

只接受计划表单生成的 TaskWayline 副本；改写后必须返回原 waylineId，返回新 ID 会被拒绝。

内容没有变化时返回 changed: false，不会上传。

旧 WPMZ 缺少起飞参考点节点时会被跳过（不会创建节点）；finishAction 等必需节点缺失会失败。

下载 URL 受浏览器 CORS 和有效期影响。

计划表单内改写任务航线的推荐时机是 plan.form-extensions 的 onSubmit，不要在 validate 里产生副作用：

const wpmz = await ctx.capabilities.get('platform:wpmz')
await wpmz?.rewrite({
  target: {
    projectId: input.context.projectId,
    waylineId: input.form.wayline_uuid,
  },
  changes: { missionConfig: { finishAction: 'no-action' } },
})

`platform:wayline-preview`：地图上预览航线

const preview = await ctx.capabilities.get('platform:wayline-preview')
if (!preview) return

方法	输入	返回
`show`	`{ points, startPosition, destination }`	句柄：`update(input)`、`dispose()`

destination 为 { position, kind: 'alert' | 'home' } | null：alert 用告警点图标，home 用返航点图标。

update() 替换整份输入，不是局部修改。

多个插件的预览会并存，没有"当前航线"仲裁；退出业务时记得 dispose()。

预览不会自动把地图视野对准航线，需要自己调 platform:map 的 recenter。

终点高度为 0 时会贴地显示。

调用要求全局地图已就绪，未就绪时保留无预览降级。

集成片段

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

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

{
  "permissions": [
    "platform:http",
    "platform:wpmz",
    "platform:wayline-preview",
    "platform:map"
  ]
}

下面的 definePlugin 只示范入口逻辑组织，不是可直接替换完整工程的入口；保留生成工程的 SDK 导入路径，将能力逻辑合入已有 activate 和业务收尾，保留原有扩展贡献与界面注册。/incidents/current/route、可下载的 WPMZ 和已就绪的公共地图是业务前提。

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

interface RouteResponse {
  code: number
  data: {
    wpmzUrl: string
    start: { lng: number; lat: number; height: number }
    alert: { lng: number; lat: number; height: number }
  }
}

export default definePlugin({
  async activate (ctx) {
    const [wpmz, preview, map] = await Promise.all([
      ctx.capabilities.get('platform:wpmz'),
      ctx.capabilities.get('platform:wayline-preview'),
      ctx.capabilities.get('platform:map'),
    ])
    if (!wpmz || !preview) {
      ctx.logger.warn('航线解析或预览能力不可用')
      return
    }

    const response = await ctx.apiCall<RouteResponse>('/incidents/current/route')
    if (response.code !== 0) throw new Error('路线查询失败')
    const points = await wpmz.parseCoordinates({
      url: response.data.wpmzUrl,
      referenceAltitude: 12,
    })
    if (points.length < 2) throw new Error('WPMZ 中没有可预览的有效航点')

    const input = {
      points,
      startPosition: response.data.start,
      destination: {
        position: response.data.alert,
        kind: 'alert' as const,
      },
    }
    const handle = await preview.show(input)
    await map?.recenter({ points, padding: 48 })

    // 业务切换为返航时复用同一个预览句柄。
    async function showReturnRoute (returnPoints: typeof points) {
      await handle.update({
        points: returnPoints,
        startPosition: response.data.alert,
        destination: { position: response.data.start, kind: 'home' },
      })
      await map?.recenter({ points: returnPoints, padding: 48 })
    }
    ctx.logger.debug('返航预览更新函数已就绪', { callable: typeof showReturnRoute === 'function' })

    return {
      async dispose () {
        await handle.dispose()
      },
    }
  },
})

常见问题

现象	原因与处理
`parseCoordinates` 返回点很少	非法航点会被跳过；检查 KMZ 内容是否完整
`rewrite` 被拒绝	只接受计划表单生成的 TaskWayline 副本，且不能改变 `waylineId`
改写"成功"但文件没变	内容无变化时返回 `changed: false` 并跳过上传，属正常行为
预览互相覆盖	不会覆盖——多个预览并存；自行管理句柄的创建与释放
预览位置不在视野内	预览不自动回中，配合 `platform:map` 的 `recenter` 使用

platform:wpmz：解析与改写航线文件#

platform:wayline-preview：地图上预览航线#

集成片段#

常见问题#

`platform:wpmz`：解析与改写航线文件

`platform:wayline-preview`：地图上预览航线

集成片段

常见问题