流程编排语言
dev 不执行流程，目标环境还须确认插件版本、持久化设施和能力提供方。1.0.0、后端契约 1.1.0 为范围。重试导出的说明与当前执行规则仍有差异，见重试边界；不能仅凭版本号或本地校验通过推断目标部署采用了同一策略。顶层结构
steps 不是可交付的完整流程。{
"name": "accident-response-cascade",
"description": "事故联动处置",
"trigger": {"stream": {"match": {"event_type": "traffic.accident"}}},
"steps": []
}| 字段 | 必填 | 说明 |
|---|---|---|
name | ✅ | 流程的运行身份（跨包唯一），不是文件名 |
description | 说明 | |
trigger | ✅ | 触发器，见 流程触发器参考 |
steps | ✅ | 步骤数组，见下文 |
步骤（FlowStep）
dispatch_mission 是单次尝试动作，不能照抄其中的 maxAttempts: 3；用于该动作时须设为 1 或省略，并补齐动作所需输入及上游步骤。{
"id": "dispatch",
"needs": ["ack"],
"action": "dispatch_mission",
"inputs": {"waylineUuid": {"from": "trigger.waylineUuid"}},
"when": {"field": "steps.ack.confirmed", "op": "eq", "value": true},
"timeoutSec": 60,
"maxAttempts": 3
}| 字段 | 说明 |
|---|---|
id | 步骤标识，流程内唯一 |
needs | 依赖的步骤 ID（有向无环图的边）；数组顺序只影响排序稳定性 |
trigger | 依赖达成条件：allSucceeded（默认，全部成功才执行）或 allDone（上游有终态就执行，适合收尾；其自身失败只记日志） |
action | 动作：平台受控步（如 dispatch_mission）或 run_script；plugin.<名> 为已登记的插件自定义动作 |
inputs | 每项 {"const": ...} 或 {"from": "路径"}，二选一 |
when | 执行条件，见下文 |
delaySec | 延迟执行秒数 |
await / callback | 等待信号声明，见下文 |
timeoutSec | 单步超时（最大 3600；默认 30 秒，非幂等步 60 秒） |
maxAttempts | 最大尝试次数，含首次执行；未写或为 0 时使用动作基线。非幂等动作固定 1 次，其余动作的显式正值可调整，当前执行上限为 20；见下文 |
重试边界
5 次尝试包含首次执行，最多发生 4 次重试。| 动作 | 默认最大尝试次数 | 首次退避 / 倍率 | 显式调整 |
|---|---|---|---|
run_script，包括经该动作执行的只读判定 | 5 | 60 秒 / 2 | 正值可收紧或放宽，执行时钳到 20 |
| 其他可重试动作 | 5 | 1 秒 / 2 | 正值可收紧或放宽，执行时钳到 20 |
dispatch_mission、spawn_agent、return_home | 1 | 不重试 | 不能放宽；大于 1 的声明会被后端发布校验拒绝 |
run_script 的重试会重新执行整段脚本，不是从上一次能力调用之后继续。已经成功的外部写入不会因此回滚；脚本须显式接入 run.idempotencyKey 并按业务唯一键去重。契约错误、业务结果不重试，其他错误按有效步骤策略处理，见错误模型。run_script 的首次退避写成 1 秒，并把所有动作的尝试次数描述为“只能收紧”。这两项不能当作当前执行保证；目标部署的规则由部署方核对。上述默认值也不承诺固定总等待窗口，执行耗时、取消和实际重试策略都会影响最终时长。输入路径（from）
| 路径根 | 内容 |
|---|---|
trigger.* | 触发输入（开放：声明是最低承诺，不限制额外字段） |
steps.<id>.* | 前序步骤的输出；只能读 needs 传递闭包内的步骤 |
steps.<id>.$state | 步骤终态：succeeded / failed / skipped / timedOut / interrupted |
run.now | 流程确定性时间（UTC RFC3339，重试不变） |
run.idempotencyKey | 本步幂等键 <流程ID>:<步骤ID> |
run.intervalSec | 仅 schedule 触发时存在 |
run_script 额外要求 inputs.script 为非空字符串 const（引用清单 scripts[] 里声明的脚本名）。等待信号（await / callback）
{
"id": "wait-confirm",
"action": "wait_signal",
"await": {
"signal": "acknowledge",
"timeoutSec": 3600,
"provides": [{"key": "confirmed", "type": "bool"}]
}
}| 字段 | 说明 |
|---|---|
signal | 信号名；由调用方通过平台信号 API 投递 |
timeoutSec / timeoutSecFrom | 二选一；字面量 ≤0 表示无限等待，动态值取不到或 ≤0 立即超时，超 3600 钳为 3600 |
provides / optional | 必填 / 可缺的信号数据键，类型 string/number/bool/object/array |
extraKeys | 'reject'（默认）或 'allow'：多余键是拒绝还是放行 |
interruptedBy | 可中断本等待的信号 |
条件（when）
{"field": "...", "op": "...", "value": ...}，op 为 eq / ne / in / exists / blank / present。{"and": [...]} 或 {"or": [...]}；三种形态三选一。blank 视 null、缺失、空串、0、false 为空；present 相反。平台受控步（受控动作）
动作（action） | 关键输入 | 输出 |
|---|---|---|
dispatch_mission | waylineUuid、dockSn、projectUuid 必填 | allowed, reasons, droneId, missionId |
query_flight_task | missionId 必填；untilStatusIn/everySec 可选 | 任务状态、名称、类型、时间、航点等 |
spawn_agent | taskUuid, projectUuid, dockSn, waylineUuid, flightId | sessionId, droneSn, drcAcquired, skipped… |
return_home | sessionId 必填 | accepted, controlReleased |
update_event_status | status 必填 | eventStatus |
wait_signal | 由 await 描述 | 信号数据 |
run_script | script（const）+ 脚本 io.inputs | 由脚本 io.outputs 决定 |
最小示例
workflows/capture-process.json：{
"name": "capture-process",
"steps": [
{
"id": "process",
"action": "run_script",
"timeoutSec": 30,
"maxAttempts": 1,
"inputs": {
"script": {"const": "process-capture"},
"event_id": {"from": "trigger.event_id"},
"idempotencyKey": {"from": "run.idempotencyKey"}
}
}
],
"trigger": {"job": {"seed": ["event_id"]}}
}常见问题
| 现象 | 原因与处理 |
|---|---|
| 装载报流程校验失败 | 常见原因：inputs 同时写了 from 和 const、needs 指向不存在的步骤、run_script 的脚本名没在清单 scripts[] 声明 |
| 步骤一直不执行 | 上游没达成 trigger 条件（默认 allSucceeded）；或 when 条件不满足被跳过（终态 skipped） |
| 信号等不到 | 检查 await.signal 名称与投递方一致；看 steps.<id>.$state 是否 timedOut |
| 想在流程里直接调飞行接口 | 做不到；用受控步 dispatch_mission 等 |
修改于 2026-10-22 03:40:05