开始和结束节点

开始节点和结束节点共同定义工作流对外暴露的参数结构：调用方按照开始节点的定义传入数据，工作流按照结束节点的定义返回结果。工作流被智能体、应用、API、任务中心或父工作流调用时，都应遵守这组契约。

开始节点

开始节点是工作流的入口，用于声明本次运行可以接收哪些输入，并把实际输入原样提供给后续节点。运行到开始节点时，系统会先按照输入结构校验数据；校验通过后不会调用模型、插件或外部服务，也不会改写输入值。

当前标准工作流允许开始节点不配置任何输入，也可以按需新增输入。截图中的 input 是配置示例，不是每个工作流都会自动生成的固定参数。

工作流与对话流的差异

类型	开始节点初始状态
标准工作流	初始可以没有输入参数；根据调用场景自行定义。
对话流	默认包含只读系统字段 USER_INPUT 和 CONVERSATION_NAME。前者表示用户本轮发送的消息，后者表示本次请求绑定的会话；不要删除、改名或修改字段类型。

输入参数

配置项	说明
变量名	输入参数的唯一名称。建议使用稳定、语义明确的英文名称，例如 query、documentId，避免发布后随意改名导致下游引用失效。
变量类型	当前系统支持基础类型、结构类型、文件和媒体类型及其数组类型，详见下表。后续节点引用变量时，引用值的类型必须与目标参数兼容。
参数描述	说明参数的业务含义、格式、单位和取值约束。工作流作为智能体技能使用时，清晰的描述也有助于模型从用户问题中识别参数。
必填	开启后，该字段会进入输入结构的必填列表。正式运行时缺少必填字段或字段类型不匹配，开始节点会以输入校验失败结束。只有所有调用入口都能稳定提供该字段时才设为必填。
默认值	编辑器会保存默认值，试运行面板会用它预填测试输入。开始节点运行时只负责校验和透传，不会自行把缺失字段替换为默认值；API、父工作流等外部调用方应显式传入正式运行所需的字段。默认值仍需符合参数类型。
子字段	Object 和 Array<Object> 可以继续定义子字段。下游引用对象子字段时，应保持字段名称和层级稳定。当前实现没有沿用旧文档“对象最多嵌套三层”的固定限制，但仍应避免难以维护的过深结构。

当前可选类型如下：

分类	类型
基础类型	String、Integer、Number、Boolean、Time
结构类型	Object、List、Array<Object>，以及基础类型对应的数组类型
文件与媒体	File、Image、Svg、Audio、Video、Voice、Doc、PPT、Excel、Txt、Code、Zip，以及对应的数组类型

一个开始节点最多可以配置 20 个顶层输入参数。对象内部可以继续定义子字段；如果字段很多，优先按稳定的业务对象分组，不要把大量无关字段堆在同一个对象中。

常见媒体输入应使用匹配的媒体类型或数组类型。若使用 URL 字符串传递文件，URL 必须能被工作流运行环境访问；不要把本机路径当作可共享的文件地址。

配置步骤

1. 选中画布上的开始节点。
2. 在“输入”区域单击“新增输入”。
3. 设置变量名、类型、描述、必填状态和默认值；顶层参数总数不要超过 20 个。
4. Object 或 Array<Object> 类型按业务结构继续添加子字段。
5. 在下游节点中引用变量，并使用真实样例试运行。

运行时语义

1. 调用方提交本次运行的输入对象。
2. 开始节点按照已保存的输入结构校验必填字段和字段类型。
3. 校验通过后，开始节点把实际输入对象原样输出，供后续节点引用。
4. 校验失败时，本次运行在入口处结束，并返回 ENTRY_INPUT_INVALID。

未在开始节点中声明的字段不属于稳定的工作流契约，下游节点也不能依靠变量选择器稳定引用这些字段。需要使用的字段应先在开始节点中明确声明。

配置建议

• 先确定调用方实际能够提供的字段，再设计开始节点参数。
• 参数名、类型和必填状态构成工作流契约；发布后变更要同步检查所有调用入口。
• 可选参数应明确空值处理方式；默认值主要用于编辑和试运行便利，正式调用仍应明确约定由谁提供字段。
• 图片、文件和对象数组要用真实样例验证，不能只验证普通字符串。
• 如果工作流会作为智能体技能使用，应把参数的业务含义、格式和示例写清楚；参数提取由调用入口或模型完成，不是开始节点自身的能力。

试运行检查

• 不传可选字段时，确认后续节点有明确的空值处理。
• 删除一个必填字段，确认开始节点能够阻止错误输入继续执行。
• 为 Integer、Boolean、Object 和数组输入故意传入错误类型，确认能够看到输入校验错误。
• 配置默认值后打开试运行面板，确认测试输入被正确预填；再从真实调用入口验证正式入参。
• 对媒体、文件、对象和对象数组使用真实样例，不要只验证字符串输入。

与旧文档的差异

旧文档内容	当前系统处理
默认提供名为 input 的参数	标准工作流可以没有输入参数；input 只在需要时自行创建。
Object 最多嵌套三层	当前编辑器和输入结构校验没有这项固定三层限制，但不建议设计过深结构。
可以把 JSON 同步到开始节点	当前开始节点界面没有 JSON 批量导入入口，只能逐项配置。节点定义元数据中虽然仍保留相关描述，但实际界面没有开放该功能。
参数描述可帮助从用户问题中提取参数	仅在工作流被智能体、应用等入口调用并由模型负责参数提取时成立；开始节点本身只校验和透传输入。

常见问题

为什么设置了默认值，API 调用仍建议显式传参？

默认值会被编辑器保存，并用于试运行面板预填；当前开始节点执行器不会在运行时主动补写缺失字段。为了让不同调用入口行为一致，正式调用应显式提供业务需要的字段。

为什么下游节点看不到调用方额外传入的字段？

变量选择器以开始节点声明的结构为契约。先在开始节点中增加字段并保存，再在下游节点中引用。

可以删除标准工作流的所有输入吗？

可以。标准工作流允许开始节点没有输入参数，适用于完全依赖固定配置、定时触发或无需外部数据的流程；对话流的只读系统字段则不应删除。

结束节点

结束节点用于声明工作流的最终输出契约。它不会调用模型、插件或外部服务，只负责收集上游结果并按配置返回。工作流必须包含结束节点，并至少存在一条从开始节点到结束节点的有效路径。

工作流与对话流的初始配置

创建方式	默认模式	初始配置
工作流	返回变量	默认不创建输出字段，可按调用方需要添加
对话流	返回文本	默认创建 output 变量并开启“流式输出”，但“回答内容”仍需填写后才能发布

切换模式时要重新确认调用方需要的数据形态。返回变量和返回文本是两套不同的最终输出协议，不是同一份结果的两种展示方式。

返回变量

返回变量模式把“输出变量”区域中配置的字段组成一个结构化对象，适合 API、父工作流、卡片或应用组件继续读取。

每个输出字段包含名称、类型和值。值可以是固定值、上游变量引用，节点定义允许的场景下也可以是文件。字段名称已填写但值为空时，发布校验会提示“输出变量值不可为空”。

运行时会保留布尔值、数字、数组和对象等数据类型，不会自动调用大模型把 JSON 总结成自然语言。当前实现也没有旧文档中“Object 最多嵌套 3 层”的固定限制；真正约束来自字段类型、下游调用方以及结束节点总输出大小。单次结束节点输出上限为 2 MiB。

输出字段可以为空，此时得到空的业务结果对象，但通常只适用于仅执行副作用、不需要返回业务数据的工作流。

每个输出字段都应引用当前执行路径可达的上游输出，并设置与实际值一致的类型。多条条件分支最终汇入同一结束节点时，应保证各分支能提供兼容的返回结构。

返回文本

返回文本模式用于拼装最终回复。此模式下，“输出变量”只是回答模板的本地变量绑定，不会同时作为结构化业务字段返回；运行结果的主要业务字段是一个名为 output 的字符串。

“回答内容”不能为空。先在“输出变量”中绑定上游值，再在回答内容中使用以下形式引用：

• 顶层变量：{{变量名}}
• 对象字段：{{变量名.子字段}}

当前运行时支持顶层变量和对象的点路径。虽然编辑器提示中展示了 {{变量名[数组索引]}}，但当前模板运行时不会解析这种数组下标写法；需要数组元素时，应先在上游节点中提取为具名输出，再在结束节点引用。

变量不存在时，模板运行时会把该位置处理为空白，而不是直接报错；对象、数组等非字符串值会序列化为 JSON 文本。发布前应通过试运行检查实际内容，避免静默产生空白回答。

流式输出的准确含义

“流式输出”开关表示调用方希望通过流式执行链路接收结果，但它不表示结束节点会自行生成内容，也不保证逐字打字机效果。

要看到流式事件，调用方需要使用支持流式响应的运行接口并持续消费 SSE 等事件；运行环境也需要启用相应的流收集配置。结束节点是在上游值就绪后渲染回答模板，因此最终回答仍可能作为一个完整数据块返回。上游大模型节点自己的流式事件与结束节点的最终返回不要混为一谈。

运行时行为与错误

模式	运行时结果	常见错误
返回变量	按输出字段映射为结构化对象，并按输出协议校验	结果不符合输出协议时为 EXIT_OUTPUT_INVALID
返回文本	渲染回答模板并返回 { "output": "..." }	配置或模板无效时为 EXIT_CONFIG_INVALID

结束节点本身不调用模型、工具或网络。若结果内容不正确，应先检查上游值、变量绑定和当前执行路径。

选择返回模式

使用场景	推荐模式	原因
API、卡片、父工作流继续处理	返回变量	字段结构稳定，便于程序读取
直接在智能体对话中回复用户	返回文本	可控制最终措辞和排版
同时需要人类可读消息和结构化字段	返回变量，并把 message 等文本作为一个明确字段	返回文本模式不会额外返回结构化字段

与旧文档的差异

旧文档说法	当前系统结论
返回变量后智能体会自动总结 JSON	结束节点不调用模型；是否总结由调用方或其他节点决定
Object 最多嵌套 3 层	当前结束节点没有该固定层数限制
开启流式输出后一定逐字显示	只声明流式交付意图，最终文本可能一次性返回
返回文本时还能把输出变量交给卡片使用	输出变量仅用于模板绑定，最终业务结果是 output 字符串

发布前检查

1. 确认开始节点到结束节点存在有效连线。
2. 返回变量模式下，逐项检查字段名、类型和值，并让各条件分支返回兼容结构。
3. 返回文本模式下，确认回答内容非空，变量名与本地绑定一致，且没有使用数组下标占位符。
4. 分别试运行正常值、空值、长文本和分支路径，检查最终输出是否符合调用方协议。
5. 输出较大对象或文件信息时，确认总结果没有超过 2 MiB。

结束节点不得返回密钥、鉴权头、内部日志或完整第三方原始响应。需要排查问题时应查看运行记录。

常见问题

为什么开始节点字段在下游找不到？

确认字段已经保存、名称和类型有效，并且下游节点位于开始节点可达的执行路径上。字段改名后，应重新选择旧引用并试运行。

为什么返回文本中的变量为空或没有被正确替换？

先确认变量已在结束节点“输出变量”区域完成绑定，并且当前执行路径确实产生了该值。当前模板支持 {{变量名}} 和 {{变量名.子字段}}，不支持 {{变量名[数组索引]}}；数组元素应先由上游节点提取。变量不存在时运行时通常会填入空白，因此必须通过试运行检查最终回答。