节点放对了，流程仍可能运行失败。常见原因不是模型能力不足，而是变量选错、数据类型不一致、某条分支没有输出，或者下游读取了已经变化的结构。把每个节点当成一个有明确输入输出的小函数，调试会简单很多。

变量引用要看来源和类型

选择变量时同时确认三件事：它来自哪个节点，字段名称是什么，类型是否符合当前输入。文本、数字、对象、文件和数组不能因为界面都能“选中”就互相替代。

例如文档提取器通常输出文本，参数提取器可能输出多个独立字段，Iteration 输出的是一组结果。下游 LLM 可以读取文本上下文，但 IF/ELSE 比较数字时需要真正的数字类型，不能依赖字符串碰巧看起来像数字。

节点改名不会改变变量含义，但删除字段、调整结构化输出或替换上游节点后，应逐个检查下游引用。不要只看连线仍然存在。

分支结束前先统一结构

同一个 IF/ELSE 的成功分支返回对象，失败分支返回纯文本，下游就很难统一处理。可以让每条分支都生成相同结构：

{
  "status": "success | failed",
  "message": "面向用户的说明",
  "data": null
}

再使用 Variable Aggregator 汇合互斥分支的同类变量。聚合器只负责选择实际运行分支的结果，不负责修复类型差异。若需要把多个并行结果合并成列表或长文本，应使用代码、模板或专门的列表处理。

每个节点只承担一种责任

一个 LLM 节点同时做分类、抽取、检索判断、内容生成和格式化，测试失败时很难知道是哪一步出了问题。把它拆成问题分类器、知识检索、LLM 和模板，虽然节点数量增加，但每一步都能单独观察和替换。

也不要走向另一个极端：简单的两行格式化不需要一个 Code 节点，固定条件不需要 LLM。流程应当以可理解为目标，而不是以节点最少或最多为目标。

从单节点测试开始

调试顺序可以固定下来：

  1. 使用一份最小、可重复的输入运行流程。
  2. 查看第一个异常节点的实际输入，而不是只看最终报错。
  3. 单独运行该节点，检查输出字段、类型和空值。
  4. 修改后重跑当前节点，再继续下游。
  5. 最后用成功、失败和边界样本做端到端测试。

接口节点要查看状态码与响应体；知识检索要查看命中的片段；Agent 要查看每次工具调用；LLM 要比较提示词、上下文和结构化输出。缓存的上游变量适合快速调试，但发布前必须重新运行完整流程，避免测试结果依赖旧数据。

发布前做一次连线审计

检查所有入口字段是否被使用、所有分支是否能到达结束节点、所有外部请求是否有失败路线、所有聚合变量是否类型一致、所有输出是否来自当前节点。再用空输入、超长输入、错误文件、接口超时和知识未命中做测试。

工作流的可靠性往往来自这些看似普通的连接。模型可以容忍语言模糊，程序不会替你猜错位的变量；先把数据流接清楚，才有资格讨论提示词效果。