构建一个稳健的扣子工作流（Workflow），必须掌握五大核心规范：严格定义输入契约、利用 Condition+Loop 实现有限次重试、所有变量显式引用、将高频逻辑封装为子工作流、并在每个节点后部署错误降级路径。这套方法论并非纸上谈兵，而是源自真实业务压力的实战经验——分支混乱、重试失控、变量传错、超时崩溃等问题，往往不在测试环境暴露，只有在用户量攀升时才会集中爆发。

下面逐个拆解这些核心规范。

明确工作流边界与输入契约

第一步，在开始节点上仅定义【必需的变量】，例如 user_id、query_text、timestamp。若多定义一个变量，后续每个节点都需要处理其空值或默认值，导致逻辑分支无谓增加。这一步看似简单，实则是许多混乱的根源。

第二步，为每个输入变量明确指定类型和约束。例如 query_text 为 string 类型，长度限制 500 字符，超出则截断并记录 warning 日志。若在此步骤偷懒，LLM 节点可能因超长输入直接报错中断，且错误信息无法指明具体哪个字段越界。

第三步，所有非结构化输入（例如用户粘贴的网页 HTML、截图 OCR 文本）应统一通过 Code 节点进行预清洗：剥离无关标签、合并换行、过滤控制字符。切勿指望 LLM 节点能自行“理解”脏数据，它只会将噪声当作语义一并消化，导致输出质量不可控。

用 Condition + Loop 组合实现安全重试机制

方案一：当 HTTP 节点调用外部 API 失败时，必须搭配 Loop 节点进行重试。Loop 的最大次数设置为 3，超时时间设为 8 秒。扣子默认重试无上限，一次网络抖动就可能触发无限循环，导致 token 和计费双双失控。

方案二：Condition 节点判断 HTTP 返回状态码是否为 2xx，若不是则进入失败分支。失败分支中必须包含一个 Code 节点，将 error_code、retry_count、原始响应体记录到日志变量，然后将该变量传递给 Loop 节点作为继续条件。若遗漏日志记录，故障排查时将面对一片空白的运行记录。

具体操作很简单：将 Loop 节点拖到 Condition 的“否”出口即可。但关键在于 Loop 的“继续条件”表达式必须写成 {{log.retry_count < 3}}，而非 {{response.status != 200}}——后者在首次失败后永远为真，直接导致死循环。

变量传递必须显式声明，杜绝隐式引用

每个节点的输入框中，所有变量必须写成 {{xxx}} 格式，即使只有一个变量。扣子虽然允许省略双大括号直接写变量名，但一旦某节点输出字段改名，所有未加 {{}} 的下游节点将静默失效：不报错、不警告，输出为空字符串。

特别注意：LLM 节点的 prompt 字段中如需插入变量，必须使用 {{input}} 这种格式，不能写成 $input 或 {input}。其他写法会被当作纯文本传给模型，导致模型看到“$user_name”而不是张三的名字。

Code 节点返回 JSON 时，确保 key 名与下游节点期望完全一致，大小写、下划线、空格都不能有偏差。例如上游返回 {"product_name": "iPhone"}，下游却用 {{productname}} 引用，结果就是空值穿透整条链路。

子工作流封装高频复用逻辑

第一步：识别重复模式。当你在三个以上工作流中都编写了“提取手机号+校验格式+脱敏前四位”的 Code 节点时，这就是封装信号。

第二步：新建一个独立工作流，仅保留开始→Code→结束三个节点。在 Code 中编写完整逻辑，输出固定为 { "phone_masked": "138****1234", "is_valid": true }。

第三步：在原工作流中删除那些 Code 节点，在对应位置插入 Plugin 节点，选择“调用工作流”，填入刚建好的子工作流 ID，并映射输入变量 {{raw_text}} → {{input}}。

第四步：所有调用该子工作流的地方，统一更新输出引用为 {{sub_workflow.phone_masked}}。此后只需修改子工作流一次，即可全局生效。

注意：子工作流的开始节点变量名必须与调用方映射关系严格匹配。例如子工作流期待 input，你就不能传 text_content，否则整个子流程将无法获取输入，静默返回空对象。

生产环境必须开启错误捕获与降级路径

在每个 LLM 节点后立即接一个 Condition 节点，判断 {{llm_node.output_text}} 是否为空字符串，或包含关键词“抱歉”“无法回答”“内容受限”。若是，则走降级分支，返回预设的兜底话术，例如“当前问题较复杂，已转人工处理，请稍候”。

在每个 Image 节点后加一个 Condition，判断 {{image_node.image_url}} 是否以 https:// 开头。若不是，则说明生图失败，跳转至备用方案：返回一张通用占位图 URL，并附带文字说明“AI 正在优化画面，请稍后再试”。

所有降级分支最终必须汇聚到同一个结束节点，且该节点输出字段命名与主路径一致，例如都称为 final_response。否则前端解析时会因字段缺失而报错。