飞行任务与违停巡逻

后端插件要下发飞行任务、查任务进度、建巡逻会话、让飞机返航时，用的不是 JS 能力对象，而是流程 JSON 里的平台受控步（action）。平台在这些步骤上做审计和风控，脚本本身拿不到任何飞行函数——这是刻意的安全设计。

四个受控步

动作（`action`）	作用	对应审计能力（流程元数据）
`dispatch_mission`	按航线创建飞行任务	`device.mission:execute`
`query_flight_task`	查询任务状态（可长轮询）	`flight_task.detail:read`
`spawn_agent`	为任务创建巡逻会话	`agent.session:create`
`return_home`	命令飞机返航	`device.flight:return_home`

⚠️ 表里的审计能力名是流程校验用的元数据，不能写进脚本 allowlist（写了装载失败）。它们也不对应任何可调用的 JS 对象。

部署依赖

这四个步骤需要部署方接通能力提供方，且成组生效。插件声明了这些步骤不代表提供方已就绪；测试前请部署方确认各组接入的是实际服务还是模拟服务。

能力组	必须同时就绪	缺失时行为
飞行任务	任务创建服务、任务查询服务	整组使用模拟结果：下发返回模拟任务号，查询返回模拟终态
违停巡逻	巡逻会话创建服务、返航服务	整组使用模拟结果：建会话返回 `skipped=patrol_not_configured`

所以"流程跑通了"不等于"真的下发了任务"。测试环境验收要由部署方确认接入状态，并用任务和设备的权威状态验证结果，不能只看模拟返回值。两组互相独立，一组缺失不影响另一组。

dispatch_mission：下发任务

inputs  = { waylineUuid, dockSn, projectUuid, lat?, lng?, recordId? }
outputs = { allowed, reasons, droneId, missionId? }

{
  "id": "dispatch",
  "action": "dispatch_mission",
  "inputs": {
    "waylineUuid": { "from": "steps.pick.waylineUuid" },
    "dockSn": { "from": "steps.pick.dockSn" },
    "projectUuid": { "from": "steps.pick.projectUuid" },
    "recordId": { "from": "trigger.eventId" }
  }
}

要点：

按 dockSn（机场 SN）选机场，不接收插件指定飞机（droneId 由平台返回）。

创建成功只表示任务已落库，下发设备是异步的——必须接 query_flight_task 确认。

创建任务不是幂等的更新或插入操作：重放可能多建任务。这一步被平台固定为不可重试，不要在流程里放宽重试。

query_flight_task：查询任务

inputs  = { missionId, untilStatusIn?: number[], everySec?: number }
outputs = { taskStatus, taskName, taskType, beginAt, endAt, workflowUuid,
            currentWaypointIndex, totalWaypoints, exceptions, pollTimedOut? }

不给 untilStatusIn 时只查一次；给了就轮询到指定状态为止。

everySec 最小 5 秒（更小会被退回默认 15 秒）；轮询期间有心跳，超时前返回最后状态并置 pollTimedOut: true，不抛错。

状态是数字：过程态 0/2/9/10，终态 1/4/5/7/8。状态字面量由你的流程维护，下游枚举变化时要人工核对。

spawn_agent：创建巡逻会话

inputs  = { taskUuid, projectUuid, dockSn, waylineUuid, flightId }
outputs = { sessionId, droneSn, containerName, drcAcquired, skipped, skipReason }

机场被占等业务分支返回 skipped=true 且 sessionId 为空——这不是错误，下游步骤要用 when 检查 sessionId 是否存在再决定走哪条路。

return_home：返航

inputs  = { sessionId, flightId?, dockSn? }
outputs = { accepted, controlReleased }

{
  "id": "return",
  "action": "return_home",
  "trigger": "allDone",
  "needs": ["patrol"],
  "inputs": { "sessionId": { "from": "steps.spawn.sessionId" } },
  "when": { "field": "steps.spawn.sessionId", "op": "present" }
}

⚠️ 下游即使 HTTP 200，只要返回 accepted=false（比如没有控制权，指令没发出去，飞机可能还在天上），这一步就按失败处理并触发告警——这是有意的安全语义，不要捕获后当成功。

幂等与安全

步骤	幂等性	注意
`dispatch_mission`	不可重试（重放可能多建任务）	靠上游业务 ID 去重
`query_flight_task`	只读幂等	默认重试安全
`spawn_agent`	按不可重试处理	下游可能"杀掉重起"
`return_home`	不可重试	`accepted=false` 必须当失败

插件不得绕过受控步骤直接调用下游飞行服务；部署方负责服务接入与访问控制。

步骤在后端运行时启动时装配，配置变化后由部署方重启。

涉及真实飞行的验证只在隔离项目和已获审批的设备上执行；模拟返回值不能作为设备完成证据。

流程 JSON 的写法（inputs 引用、when 条件、needs 依赖）见流程编排。

常见问题

现象	原因与处理
任务"下发成功"但飞机没动	创建≠下发；接 `query_flight_task` 轮询终态
流程结束但没有实际任务	下游服务未接通，可能整组使用模拟结果；请部署方确认接入状态，并查询权威任务状态
巡逻会话 `sessionId` 为空	机场被占等业务分支，`skipped=true`；用 `when` 分流
`return_home` 步骤失败但 HTTP 是 200	`accepted=false`：指令没被接受，当失败处理并告警
把 `device.mission:execute` 写进 allowlist 后起不来	审计能力名不是脚本权限名；从 allowlist 里删掉

飞行任务与违停巡逻

四个受控步#

部署依赖#

dispatch_mission：下发任务#

query_flight_task：查询任务#

spawn_agent：创建巡逻会话#

return_home：返航#

幂等与安全#

常见问题#