计划库表单扩展

plan.form-extensions 让插件在飞行计划表单里加一块自定义区域：新建/复制计划时显示你的开关或配置，用户点确定时你的校验和提交逻辑会参与流程。这是扩展点，在清单 extensions 里声明，运行时用 ctx.extensions.contribute() 提交。

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

提交语义（先读这个）

模式	渲染 UI	validate	onSubmit	onEditSubmit
`create` / `copy`	✅	✅	✅	不调用
`edit`	❌ 不渲染	❌	❌	✅ 只调用这个
airport-test / workflow-*	❌	❌	❌	❌

即：新建和复制时你的界面、校验、补丁全流程参与；编辑已有计划时不渲染任何 UI，也不调 validate/onSubmit，只对实现了 onEditSubmit 的扩展按顺序调用它。编辑场景的数据在 form.biz_ext 里，插件要自己判断归属。

字段清单

字段	层	说明
`anchor`	清单，可选	`form-end`（默认）或 `task-strategy:after`
`planType`	清单，必填	`all` / `normal` / `atob` / `manual`；`all` 匹配全部
`render()`	代码，必填	返回扩展区域界面
`validate(input)`	代码，必填	返回 `{ valid: true }` 或 `{ valid: false, message }`
`onSubmit(input)`	代码，必填	返回 `Record<string, PluginValue>` 字段补丁
`onEditSubmit(input)`	代码，可选	编辑模式的隐藏提交钩子，返回 `void`

静态字段（anchor、planType）只写清单，不传给 contribute()。

界面位置：task-strategy:after 在任务策略配置区之后；form-end 在所有原生字段之后、取消/确定按钮之前。anchor 只影响界面位置，不影响校验和提交顺序。

`biz_ext` 规则

onSubmit 最常见的用途是往任务的 biz_ext 写入插件自己的业务数据。约束：

单插件最多 1 个顶层 key；同一任务最多 1 个插件声明非空 biz_ext（互斥，冲突会整体阻断提交）。

key 长度 ≤ 64 字符；整体 JSON 大小 ≤ 4KB（当前按字符串长度 4096 计算，含中文时留足余量）。

{ biz_ext: {} } 视为未声明归属。

补丁 key 与原生字段或其他插件冲突时，整个提交被阻断，不要返回 name、task_type 等原生字段。

完整冲突规则、校验顺序见校验、提交与 biz_ext。

提交入参结构

interface PlanFormSubmitInput {
  context: {
    projectId: string
    mode: 'create' | 'copy'
    planType: 'normal' | 'atob' | 'manual'
    isMultiWayline: boolean
  }
  form: PlanFormDraft
}

PlanFormEditSubmitInput.context.mode 固定为 edit。PlanFormDraft 常用字段（只读）：

核心：name、task_type、repeat_type、wayline_uuid、sn、landing_dock_sn、connect_sn?、out_of_control_action_in_flight、media_folder_id_paths

时间与重复：interval?、month?、dom?、dow?、wom?、begin_at?、end_at?、latest_begin_at?、time_zone?、continuous_task_periods? 等

航线与飞行：wayline_precision_type?、rth_altitude?、min_battery_capacity?、resumable_status?、breakpoint_resume_mode?、rth_mode?、wayline_list?、not_exceed_agl_enabled? 等

设备：device_type?、signal_type?、drone_sn?、payload_index?、wayline_start_position? 等

其他：biz_ext?、tags?、labels? 等

wayline_list 单项含 wayline_uuid、wayline_duration、wayline_distance、total_waypoints、wayline_name；wayline_start_position 含 longitude、latitude、height?。

注意：task_type 是数字枚举（1 立即、2 定时重复、3 单次定时、4 重复子任务、5 连续、6 连续子任务、7 机场试飞）；repeat_type 同样是数字（0 不重复、1 秒、2 分钟、3 小时、4 天、5 周、6 按日期月、7 按星期月、8 年）。直接比较数字，不要自己重新解释。

可照抄示例

fh2-plugin.json：

{
  "id": "exp_quality_plan",
  "name": "质检计划",
  "version": "1.0.0",
  "entry": "./plugin.js",
  "permissions": ["plan:form-context"],
  "extensions": [
    {
      "id": "quality-form",
      "point": "plan.form-extensions",
      "planType": "normal",
      "anchor": "task-strategy:after"
    }
  ],
  "views": {
    "quality-form": { "entry": "./views/quality-form.js" }
  }
}

// src/hosts/plan/activate.ts —— 在入口 plugin.ts 的计划宿主分支里调用（见「入口与生命周期」）
import { createViewState, definePluginView } from 'fh2-plugin-sdk'
import type { PluginContext } from 'fh2-plugin-sdk'
import type { PlanFormContextState } from 'fh2-plugin-sdk'

interface QualityFormContract {
  state: { enabled: boolean; contextAvailable: boolean }
  methods: { setEnabled(input: { enabled: boolean }): void }
}
const qualityForm = definePluginView<QualityFormContract>('quality-form')
const BIZ_KEY = 'quality-inspection'

export async function activatePlan (ctx: PluginContext) {
  const state = createViewState<QualityFormContract['state']>({
    enabled: false,
    contextAvailable: false,
  })
  const formContext = await ctx.capabilities.get('plan:form-context')
  let currentFormInstanceId = ''
  function applyContext (next: PlanFormContextState) {
    if (!next.available) {
      state.update(current => ({ ...current, contextAvailable: false }))
      return
    }
    const newForm = Boolean(
      next.formInstanceId && next.formInstanceId !== currentFormInstanceId,
    )
    if (newForm) currentFormInstanceId = next.formInstanceId ?? ''
    state.update(current => ({
      contextAvailable: true,
      enabled: newForm
        ? Boolean(next.sourceBizExt && BIZ_KEY in next.sourceBizExt)
        : current.enabled,
    }))
  }
  if (formContext) applyContext(await formContext.getState())
  const contextSubscription = formContext
    ? await formContext.onStateChanged(applyContext)
    : undefined

  await qualityForm.handle(ctx, {
    state,
    methods: {
      setEnabled: ({ enabled }) => {
        state.update(current => current.contextAvailable
          ? { ...current, enabled }
          : current)
      },
    },
  })

  await ctx.extensions.contribute('quality-form', {
    render: () => qualityForm.get(ctx),
    validate: async ({ context, form }) => {
      if (!state.get().enabled) return { valid: true }
      if (context.isMultiWayline) {
        return { valid: false, message: '质检任务暂不支持多航线' }
      }
      if (!form.wayline_uuid) {
        return { valid: false, message: '请先选择航线' }
      }
      return { valid: true }
    },
    onSubmit: async () => state.get().enabled
      ? { biz_ext: { [BIZ_KEY]: { version: 1 } } }
      : {},
    onEditSubmit: async ({ form }) => {
      if (!form.biz_ext || !(BIZ_KEY in form.biz_ext)) return
      ctx.logger.info('正在编辑本插件拥有的质检任务')
    },
  })

  return {
    async dispose () {
      await contextSubscription?.dispose()
    },
  }
}

完整示例见计划表单扩展示例。

常见问题

现象	原因与处理
编辑计划时插件区域不显示	设计如此：edit 模式不渲染 UI，只调 `onEditSubmit`
点确定后提示字段冲突	`onSubmit` 返回的 key 撞了原生字段或其他插件；只返回 `biz_ext` 等自有 key
复制计划后数据丢了	`sourceBizExt` 只用于初始化界面；提交时必须在 `onSubmit` 重新写入
校验通过但任务没建成	两个插件都写了非空 `biz_ext` 会整体阻断；只保留一个归属
`validate` 里的网络校验拖慢提交	校验必须无副作用、快速返回；耗时检查放到 `onSubmit` 并保证幂等
界面渲染了但 planType 不匹配	`planType` 是清单静态字段；确认清单声明与目标计划类型一致

提交语义（先读这个）#

字段清单#

biz_ext 规则#

提交入参结构#