工作流编排

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

三种执行器在有可派发节点时都会通过 workflow_run 真实调度节点、保存运行快照并记录失败节点（claude-sdk 走进程内 SDK server， Codex / Spark 走 HTTP MCP 桥）；没有托管执行器时退化为结构化执行指引，由模型按拓扑顺序推进。 要让严格节点级调度、循环次数与失败状态真正落地，请确认运行路径支持 workflow_run。

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

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 个：

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

2. 13 种节点分别做什么

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

2.1 入口、计划与流程控制

2.2 真正执行任务

2.3 治理、验证与交付

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

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

• 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 不被支持，编辑器会直接拦住。

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

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

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

几个必须知道的细节：

• 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 和循环不要混用

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

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

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

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

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

7.1 需求、计划、审批

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

7.2 复杂度分流与编码实现

「任务复杂度路由」配置 full / quick 两个值。full 分支运行并发数为 2 的子代理调研，quick 分支直接进入主 Agent。两个分支最终汇合到「主 Agent 编码实现」。 注意这个 agent 节点建议显式绑定一个已启用的 Agent，未绑定时运行会回退使用会话当前 Agent 执行（进度里如实展示实际执行者）。

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。

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

7.5 最终复核与双交付物

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

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

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

会话级还能覆盖 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。

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

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. 常见配置错误