组合工作流
把工具编排成固定步骤,了解计划、运行和暂停后的处置。
编排组合工作流
工作流把已登记的工具编排成固定步骤,适合「查询、判断、再办理」这类多步流程。打开「接口与工具(联枢) › 编排与触发 › 工作流」,点「新增工作流」。「编排与触发」组下有七个页签:工作流、计划与执行、批量计划、事件触发、轮询代替推送、延时启动、定时任务。
基本设置
新增工作流是一个单独的页面:左侧是步骤列表,右侧填「基本信息」和「输入契约」,底部有「保存工作流」「校验」「取消」,点「返回工作流列表」回到列表。
| 字段 | 说明 |
|---|---|
| 名称、说明 | 名称必填。 |
| 工作流输入 JSON Schema | Agent 生成计划时按它提供输入,根节点是 object,支持的子集与工具契约相同。 |
| 运行整体期限(小时,可选) | 包含所有等待时间。留空为 720 小时(30 天),这也是上限。超过期限后的处理见「整体期限与超期提醒」。 |
| 审批有效期(分钟,可选) | 1 到 10080。留空时按档位取默认值。 |
| 启用 | 勾选后,获授权的 Agent 才能生成计划。 |
步骤和参数绑定
一个工作流最多 30 步。每一步有「步骤编号」和「类型」:「调用工具」「定时等待」「等待事件」「人工审批」「延时启动下一段」。调用工具的步骤要选一个工具,再设置「参数绑定」,每条绑定写明:
- 写入参数位置:工具参数里的 JSON Pointer,留空表示整个参数。
- 来源:「字面值」(一个 JSON 值)、「工作流输入」(读输入里的某个位置)或「前序步骤输出」(读之前某一步输出里的某个位置)。「缺失时跳过」可以让缺失的值不写入。
绑定只按 JSON Pointer 复制值。工作流不执行代码,也没有表达式语言。指针最多 12 层,单步参数最多 32000 字节。后续步骤绑定到的前序输出,是已经按该工具的返回字段和脱敏设置处理过的结果。
执行条件
任何一步都可以点「添加执行条件」,最多 5 条,全部成立才执行,否则这一步记为「未执行」,它的输出不存在。每条条件读工作流输入或前序步骤的输出,判断方式有「等于」「不等于」「存在」「属于其中之一」。条件之间只有「并且」,没有「或者」。
等待步骤
等待步骤没有工具和参数绑定,不需要授权,也不需要审批。有三种:
| 类型 | 设置 | 什么时候继续 |
|---|---|---|
| 定时等待 | 「等待一段时间」(秒数,最长 30 天),或「等到某个时间」(ISO 时间,取自输入或前序步骤输出) | 到时继续。到期推进由定时器检查时完成 |
| 等待事件 | 事件类型、关联键(字面值、输入或前序输出)、最长等待、超时后 | 收到事件类型和关联键都相同的入站事件。事件内容成为这一步的输出,形如 {event: {source, event_id, type, key, payload}},后续步骤可以引用 |
| 人工审批 | 审批标题、最长等待、超时后,可勾选「只允许发起者所在单位链上的人员审批」 | 持有这个工作流「审批」授权的人员在 Nexus 审批页决定,任一人批准即可。发起者本人和平台管理员不能审批。结果在 /event/payload/decision(approved 或 rejected),后面的写步骤应加执行条件 |
事件和人工审批两种必须设置「最长等待」(秒,最长 30 天),「超时后」选「运行失败」或「暂停,等待管理员处理」。原系统有自己的审批流时,应优先在原系统审批,再把结果推送成事件,人工审批只在原系统没有审批流时使用。另有一种「延时启动下一段」,见「轮询与延时启动」一节。
等待步骤受整体期限约束:「等到某个时间」超过整体期限时,这一步直接失败;事件和人工审批的最长等待,取设置值与剩余期限中较小的一个。
保存前校验
点「校验」,联枢逐条列出问题的位置,例如步骤编号重复、工具不存在、绑定了本步或之后的步骤、工具契约不接受的目标字段、无效的字面值。通过后点「保存工作流」。每次保存记录一版修订,「查看修订历史」可以逐字段比较。保存修改后,涉及这个工作流的已有计划会失效,需要重新生成。
审批档位
工作流的审批档位取各步骤工具中最高的一档。全是「授权后直接调用」的工具,工作流就直接可执行;有「需要本人确认」或「需要他人审批」的工具,整个计划就按那一档申请审批。写操作本身不再隐含要审批。列表的「审批」列会显示结果。
计划、运行与暂停处置
工作流的使用分计划和运行两段,Agent 用三个操作完成。
| 操作 | 做什么 |
|---|---|
workflow.plan | 按输入契约校验输入,把能确定的步骤参数按工具契约校验,然后冻结一份计划,记下步骤、工具和连接的版本、工作流版本、调用者的授权版本和指纹。不调用上游。全部直接调用时计划有效 10 分钟,状态为「可执行」;否则状态为「待审批」,同时向 Nexus Core 申请审批 |
workflow.run | 只有原计划者能执行,必须带 Idempotency-Key,每个计划只执行一次。执行前按当前授权重新鉴权,计划过期或相关配置、授权变了,返回 APPROVAL_STALE,要重新生成计划。受理后立即返回 running,运行在后台逐步推进,用 workflow.plan.get 读进度 |
workflow.plan.get | 读取本人计划的状态和各步结果,不执行,不重试 |
每一步都是一次普通的工具调用,有自己的调用请求和调用日志,计入该工具的限额,结果按工具的设置处理。每一步之前再次鉴权并核对版本。任一步失败就停止,状态为「失败」,或者因为限额拒绝而为「超出限额」。超过 48KB 的步骤输出只保存在该步的调用请求里,可以用 request.get 读取。
后台持久运行与断点续跑
- 每一步成功后写入检查点。服务重启后,执行中的运行从检查点继续。
- 中断时正在执行的那一步,已经完成的直接记录,读步骤重新执行,写步骤不重发,运行暂停为「写操作结果未知」。
- 等待中的运行处于「等待中」,到时或收到事件后自动继续。
写步骤结果不明时
写步骤发出后没有确认结果(进程中断、上游超时),这一步标记为「结果待核验」,联枢不会自动重发,以免重复写入。运行停下来,要先到原系统核实实际有没有生效。工具声明了幂等键的写步骤,可以在核实后选择「重试该步」,带同一个幂等键再发一次,由上游保证只生效一次。没有声明幂等键的,只能核实后标记成功,或者终止。
暂停与处置
运行会因为四种原因暂停:写操作结果未知;等待超时(「超时后」选了暂停);配置已变更(下一步的工具或连接在运行中被修改或停用,这一步不执行);身份失效(发起者已停用、没有有效的 Key、不再持有工作流的运行授权或某一步工具的调用授权,或暂时读不到核心)。
| 暂停原因 | 有权的人在审批页可以 |
|---|---|
| 写操作结果未知 | 「重试该步」(限声明了幂等键的写步骤),或「核实后标记成功」(必须写说明,运行从下一步继续,这一步不再发送),或终止 |
| 等待超时 | 不再等待并继续(必须写说明),或终止 |
| 配置已变更 | 工作流定义本身没变时,按新配置继续,或终止 |
| 身份失效 | 重新确认身份后继续,或终止 |
处置只能由人在 Nexus 审批页完成:他人审批档的计划,发给持有工作流「审批」授权的人员;本人确认或直接调用档的计划,发给发起 Agent 的归属人员。平台管理员只能在「计划与执行」里「终止」,终止不会回滚已经执行的步骤。Agent 永远不能处置。没有人能处置时,运行保持暂停,管理员只能终止。
批量办理
workflow.plan_batch:一次提供 1 到 200 条工作流输入,服务端为每条冻结一个独立计划,组成一个批次。任一条输入无效,整批拒绝并指出是第几条。inputs_json最多 30000 字符,名单大时用result_ref。名单来自数脉查询结果时,也可以改传result_ref,名单不经过对话。- 批次档位取批内最高的一档,需要审批时整批只申请一次审批,审批页以表格展示各条输入(最多 500 行)。批次里的计划不能单独审批,也不能用
workflow.run单独执行。 workflow.run_batch必须带 Idempotency-Key,同一批次只执行一次。每条计划是独立的运行,后台同时执行 4 条,单条失败、暂停或等待不影响其他条。用workflow.batch.get查看按状态的计数和每条的状态。
在「接口与工具(联枢) › 编排与触发 › 计划与执行」可以按状态、发起者筛选计划,核对每一步冻结的参数,撤销已批准但还没执行的计划或终止暂停的运行。「接口与工具(联枢) › 编排与触发 › 批量计划」列出批次,可以整批撤销尚未执行的计划。
整体期限与超期提醒
运行的整体期限默认也是上限 720 小时,包含等待时间。已暂停的运行超过期限后不会自行结束,联枢会把它标记为超期,计划上带 overdue,并写入审计事件 workflow.overdue。「计划与执行」页顶部会提示超期的运行数,可以筛选「已超期」。等待中的运行超过期限,会直接停止,状态为失败。