扣子工作流变量传递与全局变量使用指南

扣子工作流中的变量流转，核心只需三步：全局变量在智能体设置中定义后，必须通过变量节点显式引入；局部变量依赖输出映射与JSONPath路径（例如$.data.name）进行传递；大模型节点的输出务必先清洗再解析JSON，否则极易引发数据断流。

要实现扣子工作流内稳定可靠的数据传递，关键在于理清变量的来源、去向与传递机制——并非所有节点都能直接访问全局变量，也不是所有输出都能被下游自动识别。

全局变量的配置入口

进入智能体编辑页，点击左上角的齿轮「设置」图标，在弹出菜单中选择「全局变量」标签页。点击「+ 添加变量」，依次填写变量名（必须以字母开头，仅包含字母、数字、下划线，长度限制1–20字符）和初始值。例如，将【user_role】设为"guest"，【api_timeout】设为3000。

注意：此处配置的变量对当前智能体下所有工作流均生效，但不会自动注入任何节点内部——必须借助变量节点显式引入才能使用。

变量节点：将全局变量“拉入”工作流

方法一：拖拽一个「变量」节点到画布，在右侧配置面板中，「操作类型」选择「读取」→「变量名」填写刚才在设置中定义的名称（如user_role）→「输出参数名」设为workflow_role（该名称供后续节点引用）。

方法二：若需在工作流中动态修改某个值并写回全局作用域，可在变量节点将「操作类型」选为「设置」→「变量名」仍填user_role→「输入参数」绑定上游节点的输出，例如{{代码节点.output.new_role}}。

此步骤不可省略。没有变量节点，即便在设置中罗列了一百个全局变量，工作流中的LLM、代码、插件节点也无法感知它们的存在。

局部变量传递：依赖连线与上下文路径

第一步：确认上游节点已开启「输出变量映射」。例如API节点返回{ "data": { "id": 123, "name": "Alice" } }，需在该节点配置中手动指定输出路径为$.data。

第二步：在下游节点的输入框中点击「+」→选择「引用变量」→展开树形结构，找到对应节点名→展开其输出字段，勾选$.data.name即可完成值传递。

第三步：若在代码节点中处理嵌套结构，必须使用标准的JSONPath表达式。写成data.name会引发报错；只能使用$.data.name或直接绑定整个$.data对象后再用Python解析。

常见错误：两个并行分支各自修改同一个全局变量，未加锁也未设置合并策略，后执行的分支会直接覆盖前一个值。

大模型输出变量的特殊处理

大模型节点的output始终为字符串类型，即使Prompt要求返回JSON数组，实际收到的可能是"```json[{'a':1}]```"这类带包裹标记的文本。

因此，在后续的代码节点中，第一行必须进行清洗与解析：

let cleaned = {{大模型节点.output}}.replace(/```jsons*/gi, '').replace(/```s*/g, '').trim();
const parsed = JSON.parse(cleaned);

若不执行此步骤，直接对parsed[0]取值会得到"{"字符而非对象——这是超过60%的数据断裂问题的根源。