工作流编排

工作流是 Spark Work 里一张可视化、可执行、可审计的任务图。节点描述每一步做什么，连线描述先后关系，outputKey把上一步结果写进工作流状态，条件边再按状态决定下一条路径。 图存为 workflows.graph_json，一次运行存为workflow_runs快照。

先记住这四句话

• 节点是步骤，连线是依赖，不是普通装饰线。
• 需要给下游使用的结果，必须写入outputKey。
• 路由负责选择分支；循环负责重复自己的内部子图，两者不是一回事。
• verify是失败即停止的质量门禁，不是「失败后继续分流」的判断器。

Claude SDK 执行路径会通过workflow_run真实调度节点、保存运行快照并记录失败节点； Codex / Spark 路径不给这个工具，退化为结构化执行指引，由模型按拓扑顺序推进。 要让严格节点级调度、循环次数与失败状态真正落地，请使用支持workflow_run 的运行路径。

1. 先理解工作流的运行模型

input — 节点 A：输出需求解析结果

→

Workflow stateobjective = …``route = full

→

equals full→ 节点 Bequals quick→ 节点 C

一条可执行链路由节点输出、工作流状态和条件边共同驱动。

1. 节点完成后，把文本结果写入自己配置的outputKey（状态里存的是字符串）。
2. 下游节点的输入只来自「直接连到自己、条件命中、上游带 outputKey」的那几条边； 跨级或未命中的上游值不会出现。
3. 节点有多个入边时，会等待所有未被跳过的上游完成；如果所有入边都不满足条件， 这个节点会被标记为跳过（skip），下游整段不可达的节点也一起跳过。
4. 节点失败时，执行器按节点类型和retryCount决定重试或结束整条工作流。
5. 执行是分层推进的：同一波里互不依赖的agent/subagent 节点并行派发， 原子节点串行执行，节点完成即落executions并刷新快照。

1.1 outputKey：节点之间传递结果的钥匙

连上线并不代表输出会自动传递。假设「代码调研」节点输出一份报告，应配置outputKey = research_report，后面的「编码实现」节点才能在上游输入里看到research_report。留空即视为「本节点没有输出」，运行时按无输出处理。

代码调研节点
outputKey: research_report

代码调研 ─────→ 编码实现
                 inputs.research_report

还有两条容易踩的规则：

• 条件引用必须是已声明的键：连线条件或循环退出条件里的 key， 必须是图中某个节点的outputKey或loopVar，否则保存时直接报 「工作流条件引用无效」。这样能把「键名拼错」挡在落库之前。
• 模板占位符：节点的prompt与工具节点的toolArgs支持{{key}}插值，取值为工作流状态 + 当前节点活跃上游输入。 没命中的占位符保持原样（不会变成空串），方便你发现漏配的 outputKey。

1.2 条件写在连线上，不写在节点里

选中一条连线后，在右侧检查器里配置触发条件，操作符只有 5 个：

操作符	含义	适合的数据
exists	状态键存在	是否产生过某项结果
equals	严格等于（===）指定值	路由值、状态枚举，最推荐
not_equals	严格不等于指定值	排除某种状态
truthy	转换为布尔值后为真	真正的布尔值或非空值
falsy	转换为布尔值后为假	false、0、空字符串等

比较值框里true/false存成布尔、null存成空值、 纯数字存成数值，其余按字符串——因为运行时用的是严格等值比较，类型不还原就对不上。 状态键留空的条件保存后会被忽略。

不要用 truthy / falsy 判断字符串 “true” / “false”：路由节点输出的是字符串，字符串"false"仍然是真值。建议使用pass / retry、accept / follow_up，并在条件边上配置equals。

2. 13 种节点分别做什么

kind枚举共 13 个（保存时会校验，写错类型的图会被直接拒绝）：input / plan / route / agent / subagent / skill / tool / mcp / approval / verify / review / artifact / loop。按职责分为入口与流程控制、执行、治理与交付三组。

2.1 入口、计划与流程控制

节点	作用	关键配置	典型场景
input	把用户消息解析成目标、约束和交付物（结构化 JSON）	prompt、objective、constraint、value、outputKey	所有工作流入口
plan	使用只读工具集分析并制定计划（禁写、禁执行）	Prompt、模型覆盖、outputKey	编码方案、调研计划、发布计划
route	在允许的分支值里选一个输出；也可固定输出某个分支	routeOptions、value、outputKey、出边条件	复杂/简单任务、通过/返工、接受/跟进
loop	重复执行独立的内部子图，满足退出条件后停止	body、maxIterations、loopVar、resultKey、collectAll、breakCondition	反复修复、润色、评分优化

2.2 真正执行任务

节点	作用	关键配置	典型场景
agent	派发给绑定 Agent 的完整执行链路	agentId、Prompt、模型、工具	编码、修改文件、综合执行
subagent	创建临时子代理；可同节点并发多份	agentId（可选，作为配置基底）、parallelism、工具	多角度调研、按模块并行检查
skill	创建只加载所选 Skill 的临时 worker	skillIds、Prompt	验证、搜索、设计、文档等专业步骤
tool	受限代理，或按参数确定性直调单个工具	toolIds/toolSource+toolName+toolArgs	只读检查、允许 Bash 的审计、受限编辑
mcp	受限代理使用已启用 MCP，或直调指定 MCP 工具	toolSource: 'mcp'+toolServerId+toolName	浏览器、外部文档、平台或媒体能力

agent与subagent的绑定语义不同

• agent节点在托管执行里必须绑定一个已启用的 Agent：config.agentId为空、或绑定的 Agent 不存在/已禁用，节点就以missing_agent_id失败并停止工作流。这是刻意设计——画了 agent 节点却静默落到宿主身上， 比明确报错更难排查。
• subagent节点不填agentId时，会用宿主 Agent 的配置生成一个临时 worker； 填了但绑定的 Agent 不可用，同样以missing_agent_id失败。
• parallelism ≥ 2只对subagent生效： 同一节点在一次尝试里并发 N 路独立派发，结果按--- branch N ---拼接进同一个 outputKey。

2.3 治理、验证与交付

节点	作用	关键配置	典型场景
approval	暂停工作流，等待用户批准或拒绝	审批说明、outputKey	方案确认、高风险动作前门禁
verify	在工作区执行固定命令，任一命令失败即停止	verifyCommands、retryCount	测试、类型检查、构建、diff 检查
review	用只读能力复核结果、证据与风险	复核 Prompt、模型、outputKey	代码审查、事实核验、验收分析
artifact	整理最终交付文本，可写入工作区文件	outputKey、exportPath	变更摘要、报告、release notes

3. 路由判断节点怎么配置

route — 任务复杂度路由：只输出 full 或 quick

equals full

subagent — 并行代码调研：复杂任务先调查调用链

equals quick

agent — 直接编码实现：边界清晰则快速进入执行

路由节点先输出一个受约束的分支值，再由多条条件边完成分流。

路由节点有两种工作方式：

• LLM 决策（默认，execution: 'auto'）：派发只读临时 worker， 让它从routeOptions里选一个value输出。
• 固定分支（value+execution: 'static'）： 运行时直接输出该值，不经模型，适合确定性路由。

1. 给路由节点设置outputKey，例如route_mode。
2. 在「路由分支」文本框里每行填写value | label | description； 只有唯一且非空的 value 会被接受，重复值会被丢弃。
3. 选中每条出边，配置route_mode equals 分支值；两个分支都要有出口。
4. 未命中的分支及其不可达下游会被跳过，而不是报错。

outputKey: route_mode

routeOptions:
full  | 完整调研 | 跨模块或调用链不清晰
quick | 快速实施 | 局部且边界清晰

出边 1: route_mode equals full
出边 2: route_mode equals quick

如果上游节点已经严格输出pass或retry，也可以直接在上游出边配置条件，不一定再增加路由节点。 路由更适合把一段自然语言报告归一化成有限的分支值。

4. 循环节点怎么配置

循环节点不是外层画布上的「回跳箭头」，而是一个内部保存独立 WorkflowGraph 的原子节点。 只有写入config.body 的节点会被重复执行。不要把外层执行节点连回上游形成环；外层图必须保持无环， 否则保存时就会报「工作流不允许出现循环依赖」。

选中循环节点后，在右侧「循环体子图」卡片点击编辑循环体，工作流编辑区会下钻到专属子图画布。 子图里同样有节点面板、拖拽、连线、条件边、横纵布局、缩放、小地图和检查器；完成后点击 「返回主工作流」。递归的循环体（循环里再放循环）在 v1 不被支持，编辑器会直接拦住。

Loop · 实现与自检迭代最多 4 轮

agent — 本轮修复与测试：修改代码、运行相关测试、返回完整报告

→

review — 本轮通过判断：严格输出 pass 或 retry

retry↺ 下一轮pass→ 退出循环

每一轮完整执行 body 子图；评审输出 pass 时退出，否则开始下一轮，最多执行配置的轮数。

配置	作用	示例
body	每一轮重复执行的独立子图（为空则节点直接失败：workflow_loop_empty）	agent → review
maxIterations	最大轮数，默认 5，硬上限 50（超出会被钳到区间内）	4
loopVar	写入循环状态的轮次键，从 0 开始；默认__loop_index	iteration_index
resultKey	每轮结束后作为循环节点文本的状态键；留空时取循环体里最后一个带 outputKey 的节点	iteration_report
collectAll	开启后输出每轮的聚合文本（带 iteration 分隔），关闭只输出最后一轮	false
breakCondition	每轮完成后针对循环体状态求值，命中即提前退出	verdict equals pass
outputKey	把循环最终文本写回外层工作流状态	final_iteration_report

outputKey: final_iteration_report
maxIterations: 4
loopVar: iteration_index
resultKey: iteration_report
collectAll: false
breakCondition:
  op: equals
  key: verdict
  value: pass

三个重要边界

• v1 不支持循环体里再嵌套loop（运行时会返回workflow_loop_nested）。
• 循环体节点 id 不能与外层节点重名，循环体内也不能重复，否则分别以workflow_loop_node_id_collision、workflow_loop_duplicate_node_id 失败。
• 达到最大轮数但没命中退出条件时，循环返回最后一轮结果并继续外层流程。 所以循环后应增加最终复核和验收路由。
• 循环节点本身不重试（retryCount对 loop 无效）：整条循环重跑的成本不可控。

5. 工具节点与 MCP 节点怎么调用

选中tool或mcp节点后，检查器的第一项是「调用方式」：

调用方式	tool 节点	mcp 节点	行为
受限代理	✅	✅	tool：派发临时 worker，能力收窄到所选toolIds；mcp：挂载所有已启用 MCP， 用哪个工具、传什么参数由模型决定。
内置工具直调	✅	—	锁定单个内置工具（toolSource: 'builtin'），参数已预渲染， LLM 只负责包装结果。
MCP 工具直调	✅	✅	按toolServerId+toolName原生调用，不经 LLM。
平台工具直调	✅	—	直接调用平台上已启用的自定义工具或工具包工具，运行时即时读取目录； 工具被禁用后该节点会失败。

几个必须知道的细节：

• toolIds 是「白名单」而不是「免审批名单」：一旦配置， 未选中的可限制工具会被放进disallowedTools。可选工具共 13 个：Read / Write / Edit / MultiEdit / NotebookEdit / Grep / Glob / Bash / TodoWrite / AskUserQuestion / ExitPlanMode / WebFetch / WebSearch。不选表示不额外限制。
• 只读原子节点会自动收窄：input / route / plan / review / artifact禁掉Write / Edit / MultiEdit / NotebookEdit / Bash； 即使你在这些节点上配了 toolIds，也只会取其中属于只读集的那些。
• toolArgs 支持{{key}}占位符， 用上游 outputKey 渲染出真实参数后再执行；这也是「确定性调用」能接上上游数据的原因。
• MCP 不按节点配置：能选服务器只是直调时要指定目标； 受限代理模式下挂载的是应用级全部已启用 MCP。
• 只读原子节点完全不挂 MCP：input / route / plan / review / artifact运行在空能力集上， 既不会调用外部 MCP，也拿不到项目级 Skill 提示词；这是刻意的边界，不是配置遗漏。

6. verify、retryCount 和循环不要混用

能力	解决的问题	失败后的行为
retryCount	网络抖动、偶发工具故障等技术性失败	原样重跑当前节点，范围 0~3（默认 0）
loop	质量未达标，需要根据结果继续修改	重新执行整个内部子图
verify	最终硬性命令门禁	命令非零退出即以verify_failed失败并停止工作流

verifyCommands在工作区根目录依次执行：单条命令超时 600 秒， 输出缓冲上限 20MB。数组为空时该节点不报错，直接透传默认内容。verify支持retryCount（技术性失败可重跑）；approval与loop固定不重试。

因此，不要设计成verify → route → 失败后循环：真实验证命令失败时，路由没有机会执行。 需要「测试未通过后继续修复」时，让循环内的 agent运行测试并正常返回测试报告，再由review或route输出pass / retry。循环完成后，再放置真正的verify作为最终门禁。

另外两个执行语义值得记住：approval节点在用户拒绝时直接失败并停止； 批准时附带的修改意见会拼到输出末尾，随 outputKey 流向下游。 无人值守场景（没有问询通道）下审批默认放行并记审计，不会阻塞自动化。

7. 完整示例：编码功能任务 · 全节点能力演示

下面的示例用于执行真实编码功能任务，覆盖全部 13 种节点。它把「业务质量迭代」和「最终技术门禁」分开，既能演示复杂分支， 也避免外层回路和验证失败无法分流的问题。

input · 入口 — 需求解析：目标、约束、验收标准

↓

plan — 只读实施计划：影响范围、方案、测试策略

↓

approval — 人工审批计划：用户批准后才允许改代码

↓

route — 任务复杂度路由：输出 full 或 quick

full

subagent × 2 — 并行代码调研：调用链、测试、回归风险

quick

跳过额外调研

↓（分支汇合）

agent — 主 Agent 编码实现：修改代码、更新必要文档、初步测试

↓

loop最多 4 轮修复与测试 → 只读判断 pass / retry

↓

skill — Verify Skill：证据审计

tool — 受限工具：Read / Grep / Glob / Bash

mcp — MCP 检查：相关则调用，不相关则跳过

↓（并行汇合）

verify — 真实命令质量门禁：git diff --check；失败即停止

↓

review — 最终只读复核：覆盖、证据、风险和遗留项

↓

route — 验收结论路由：accept 或 follow_up

accept

artifact — 正式交付物：完成内容、文件、验证和风险

follow_up

artifact — 未通过跟进报告：阻断证据和下一轮建议

完整编码工作流：先计划和审批，再按复杂度分流，实施后进入有限循环，最后并行审计、真实验证和验收分流。

7.1 需求、计划、审批

• 需求解析：outputKey = structured_requirement，把自然语言需求整理成结构化输入。
• 只读实施计划：outputKey = implementation_plan，只读分析代码，不提前修改。
• 人工审批计划：在可能产生大量改动之前停下来，让用户决定是否继续； 被拒绝时工作流在此停止。

7.2 复杂度分流与编码实现

「任务复杂度路由」配置full / quick两个值。full分支运行并发数为 2 的子代理调研，quick分支直接进入主 Agent。两个分支最终汇合到「主 Agent 编码实现」。 注意这个 agent 节点必须绑定一个已启用的 Agent，否则会以missing_agent_id失败。

7.3 循环修复

主 Agent 首次实现后进入循环。循环体的 Agent 检查当前工作区、修复问题并运行任务相关测试；即使测试未通过，也要正常返回iteration_report。只读 Review 根据报告严格输出pass或 retry，从而控制是否开始下一轮。

7.4 并行审计与真实门禁

循环结束后同时运行三种互补检查：

• Skill：加载验证类 Skill，检查「已经完成」的声明是否有新鲜证据。
• Tool：只开放Read / Grep / Glob / Bash，限制审计能力边界。
• MCP：受限代理模式下自动挂载应用当前已启用的 MCP（也可改成 MCP 直调）； 没有相关外部依赖时返回no_external_check_needed。

这三个节点是可选扩展，不是编码工作流的固定套餐

• Skill固定「使用什么方法论」，团队有验证规范时再选。
• Tool限制「允许用什么手段」，需要独立受限审计时再放。
• MCP连接外部系统；普通本地编码没有浏览器、官方文档、Issue 或远程平台依赖时可以删除。

三条并行分支汇合后，verify执行git diff --check。这是通用门禁；项目自己的单测、类型检查和构建命令， 应根据仓库情况追加到 verifyCommands。

7.5 最终复核与双交付物

最终 Review 汇总实现结果、循环报告、三种审计和命令输出。验收路由把自然语言复核结果归一化为accept / follow_up：通过时生成正式交付物；未通过时生成跟进报告，不会错误声称任务已经验收。 两个 artifact 都配了 outputKey；配了exportPath的那个还会把内容写进工作区文件 （必须是工作区相对路径，越界会被拒绝）。

8. 谁在驱动这张图：三种执行模式

同一张图在不同执行器上的落地强度不同，界面上的文案如下：

模式	界面文案	触发条件	行为
workflow_run	托管执行	Claude SDK 执行器 + 图里有可派发节点 + 有托管执行器 + 不是 @ 提及轮	宿主拿到workflow_run工具，运行时按依赖波次真实执行节点、落workflow_runs快照并支持断点续跑
codex_guided	引导执行	Codex 或 Spark 执行器	不暴露workflow_run，把图作为执行计划注入提示词，由模型在本轮内按拓扑顺序推进
guided	引导执行	没有工作流图、托管执行器不可用，或该轮是 @ 提及	只按节点顺序引导，不承诺节点级调度

会话级还能覆盖 Agent 的默认工作流，入口在会话输入栏的工作流选择器：

• 继承 Agent 默认（mode: 'inherit'）：用宿主 Agent 绑定的工作流。
• 本会话不使用工作流（mode: 'disabled'）。
• 指定某个工作流（mode: 'override'+workflowId）： 下拉里只列「已启用且状态为 active」的工作流。

绑定写进独立的session_workflow_bindings表（带binding_instance_id做乐观锁），不污染sessions.metadata。 会话正在跑、队列里还有消息、有未处理的审批或提问、目标进行中、或已有working状态的运行记录时，改绑定会被阻止并给出对应原因； 失败运行可以点「放弃并新建运行」，旧运行标记为 canceled，历史保留。

9. 在应用里照着配置

1. 打开左侧「工作流」（Beta），点「新建工作流」，进入编排详情。
2. 先放置外层主链：input → plan → approval → route → agent → loop。
3. 给复杂度路由增加full / quick分支，在出边上使用equals。
4. 在full分支放置subagent，把并发数设为 2，然后与 quick 分支汇合。
5. 打开循环节点右侧检查器，点「编辑循环体」，在子图画布放置agent → review 并连线，配置退出条件后返回主工作流。
6. 循环后并排放置skill / tool / mcp，再统一连接到verify。
7. 添加review → route → 两个 artifact，分别配置 accept 和 follow_up 条件。
8. 逐个检查所有需要传递结果的节点是否设置了唯一、清晰的outputKey。
9. 把状态从draft切到active保存；然后在 Agent 的「工作流」下拉里绑定它， 或在会话的工作流选择器里覆盖。
10. 用工具栏的「试跑」在编辑器内跑一次（执行的是已保存版本，走真实会话与节点级进度）， 需要回看时点「历史」。

「试跑」与「历史」都会打开右侧面板：历史面板按workflow_runs列出每次运行， 展开可看逐节点状态、错误、输出预览与耗时，运行状态只有working / completed / failed / canceled四种。

10. 保存闸门与运行错误码

工作流在保存时就会做两层校验，避免把问题留到运行期：

• 形状层：kind必须在 13 种枚举内；config是严格对象——未知字段、类型错误、超界值都会被拒绝。 边界值包括 retryCount ≤ 3、parallelism 1~8、maxIterations 1~50、prompt最长 10 万字符、 节点最多 1000 个、边最多 5000 条。
• 拓扑层：未知节点类型、有向环、条件引用未声明的状态键，三类问题都在写入前拦下， 报错里带节点标题便于定位。

会话挂载工作流或改绑定时还会跑一次预检，问题码（界面会翻译成中文）：workflow_not_found、workflow_disabled、workflow_not_active、workflow_run_snapshot_invalid、graph_cycle、invalid_condition_reference、invalid_loop_body、unsupported_node_kind、missing_agent、disabled_agent、missing_required_skill、missing_required_tool、missing_required_mcp；警告类是provider_uses_host_fallback、optional_mcp_unavailable、workflow_archived_for_existing_binding、definition_newer_than_resumable_run、bundle_dependency_unresolved。

运行期会出现的失败码，对照排查：

错误码	含义
missing_agent_id	agent / subagent 节点没绑定 Agent，或绑定的 Agent 不可用
workflow_deadlock	图里存在环，无法继续推进
verify_failed	verify 命令非零退出
workflow_loop_empty	loop 节点缺少非空的 body 子图
workflow_loop_nested	循环体里出现嵌套 loop（v1 不支持）
workflow_loop_node_id_collision	循环体节点 id 与外层节点重名
workflow_loop_duplicate_node_id	循环体内节点 id 重复
workflow_tool_invoke_failed	工具 / MCP 直调失败（例如平台工具被停用）

11. 推荐的安全默认值

• input / plan / review / artifact保持只读：这些节点运行时会自动禁掉Write / Edit / MultiEdit / NotebookEdit / Bash。
• 真正修改代码只放在agent / subagent / tool节点，且 agent 节点显式绑定 Agent。
• 高风险动作前放置approval，不要只靠 Prompt 口头约束。
• 路由值使用英文枚举，例如full / quick、pass / retry。
• 循环必须设置有限的maxIterations，并在循环后做最终验收。
• verify从稳定、通用的命令开始，再逐步增加项目测试和构建。
• 不需要的 MCP 在应用的 MCP 管理页全局停用；节点本身不再单独维护 MCP allow-list。
• 把「业务是否达标」交给 loop + review，把「技术是否通过」交给 verify，两者不要互相替代。

12. 常见配置错误

现象	常见原因	处理办法
保存时报「工作流不允许出现循环依赖」	外层画布上画了回边	删除回边，把重复步骤放进loop的 body 子图
保存时报「条件引用无效」	条件里的状态键没有任何节点声明过	先给上游节点配好outputKey，或在检查器里点「使用 xx」自动填充
保存时报不支持节点类型	手写或导入的 JSON 里kind拼错	改成 13 种合法kind之一；注意运行时会把未知 kind 静默当成 agent， 所以保存闸门特意拦下
路由只走一个分支	用 truthy 判断字符串 “false”	改用枚举字符串和equals
下游看不到上游结果	上游没有outputKey，或两者没有直接有效连线，或条件未命中	配置 outputKey 并检查条件边；必要时用{{key}}显式引用
运行一上来就 workflow_deadlock	旧数据里存了带环的图，绕过了新保存闸门	重新保存一次让校验跑起来，或在编辑器里删除成环的边
agent 节点报 missing_agent_id	节点没有绑定 Agent，或绑定的 Agent 已停用/删除	在检查器里重新选择一个启用中的 Agent
verify 失败后没有进入路由	verify 是失败即停止节点	业务判断放进循环，verify 放最终门禁
循环达到上限仍继续	最大轮数结束会返回最后结果并继续外层流程	循环后增加最终 Review 和验收路由
循环节点直接失败	body 为空、节点 ID 与外层冲突或嵌套 loop	打开循环体可视化编辑器，按错误码检查节点、连线和 ID
Agent 不能编辑文件	用了只读节点，或 toolIds 漏选编辑工具	改用 agent/subagent，或在 tool 节点的toolIds里放行 Edit / Write
MCP 节点没有目标能力	应用层没有启用对应 MCP	到 MCP 管理页启用服务后重试
以为有 workflow_run 但模型在「自己演」	当前执行器是 Codex / Spark，属于引导执行	需要节点级调度时切到 Claude SDK 执行器

速查表

项目	内容
完整编码链路	input → plan → approval → route → agent → loop → skill/tool/mcp → verify → review → route → artifact
节点种类	13 种：input / plan / route / agent / subagent / skill / tool / mcp / approval / verify / review / artifact / loop
边条件操作符	exists / equals / not_equals / truthy / falsy
retryCount	0~3，默认 0；approval 与 loop 不重试
循环语义	只重复 config.body 子图；默认 5 轮，硬上限 50；v1 不支持嵌套 loop
subagent 并发	parallelism 1~8，仅 subagent 节点生效
verify 语义	verifyCommands 在工作区依次执行，单条超时 600s，缓冲 20MB，失败即 verify_failed
状态传递	上游必须配置 outputKey；下游只接收直接命中条件的上游输出；{{key}} 可插值
执行模式	workflow_run（托管执行）/ codex_guided / guided（引导执行）
MCP	应用级已启用 MCP 自动挂载，节点不再维护 allow-list
运行记录	workflow_runs 保存状态、state、节点执行、失败节点与跳过集合

上手清单：创建「编码功能任务 · 全节点能力演示」工作流

配置需求、审批、分流、并行调研、循环修复、并行审计、真实验证和双交付物

1. 新建纵向工作流，添加 input、plan、approval、route、agent 和 loop 主链
2. 给复杂度 route 配置 full / quick 分支，并在出边上使用 equals 条件
3. 在 full 分支添加 parallelism=2 的 subagent，并与 quick 分支汇合
4. 给主 agent 节点绑定一个已启用的 Agent（否则运行时会 missing_agent_id）
5. 在 loop 的 body 子图里配置 agent → review，用 verdict equals pass 作为退出条件
6. 循环后并行添加 skill、tool 和 mcp 节点
7. 让三条审计分支汇合到 verify，并配置项目验证命令
8. 添加最终 review、accept/follow_up route 和两个 artifact（需要落盘时配 exportPath）
9. 检查每个需要传递结果的节点都有唯一的 outputKey，把状态切到 active 并保存
10. 用「试跑」验证节点级进度，再绑定到 Agent 或在会话工作流选择器里覆盖

常见问题

路由节点和循环节点有什么区别？

路由节点只选择一次后续分支，分支值受 routeOptions 约束；循环节点会重复执行自己的 body 子图，直到命中 breakCondition 或达到 maxIterations（默认 5，上限 50）。外层画布必须无环，保存时会做环检测。

为什么 agent 节点会报 missing_agent_id？

托管执行（workflow_run）不把未绑定的 agent 节点静默交给宿主：config.agentId 为空或绑定的 Agent 不存在/已禁用时，节点以 missing_agent_id 失败并停止工作流。需要「跟随宿主」时用 subagent 节点（不填 agentId 会用宿主配置生成临时 worker）。

为什么 verify 失败后不能进入 retry 分支？

verify 是硬性命令门禁，任一命令非零退出即返回 verify_failed 并停止整条工作流。需要质量迭代时，让循环内 Agent 返回测试报告，再由 Review 或 Route 输出 pass/retry；循环结束后再运行 verify。

已经连线了，下游还是看不到上游结果？

连线只建立依赖。上游必须配置 outputKey，边条件必须命中，而且下游只接收直接相连的上游输入；三者缺一都看不到。可以在 prompt 或 toolArgs 里用 {{key}} 显式引用，未命中的占位符会原样保留，便于发现漏配。

循环达到最大轮数还没通过怎么办？

循环会返回最后一轮结果并继续外层流程，不会自动失败。所以应在循环后增加最终 Review 和验收 Route，把未通过的结果送到 follow_up 产物，而不是直接交付。

MCP 节点需要逐个绑定 MCP 服务器吗？

不需要。受限代理模式下所有「已启用」的应用 MCP 自动挂载；只有在选择「MCP 工具直调」时才需要指定服务器和工具名。要减少可用能力，请在 MCP 管理页全局停用服务。