工作流变量系统 (Workflow Variables)
工作流变量 (Variable) 是一种附加在 Flow（流）层级而非隶属于单个节点的作用域命名数值。只需在流中声明一次，即可在工作流中需要该数据的任何地方随意读取或写入——甚至可以直接在节点的文本参数输入框中通过 {variable_name} 语法实现行内动态文本插值。
请勿与项目系统的路径模板宏混淆
- 路径模板宏 (Macros)：项目系统用于动态拼装磁盘文件路径的模板语法（例如
{outputs}/{file_name_base}.{file_extension}）； - 工作流变量 (Workflow Variables)：创作者在工作流内部创建并在各个节点参数之间跨引脚复用和流转的数据变量。
虽然二者在底层共享相同的 {name} / {name:spec} 插值语法与格式化修饰符，且在文本框中键入 { 时项目宏（如 workspace_dir 和 workflow_name）也会与你的自定义变量一同呈现在下拉候选中，但宏侧重于描述文件名规范，而工作流变量侧重于运行期的业务数据复用。若需要定制落盘文件路径，请参阅 路径模板宏 (Macros)。
为什么使用工作流变量？
假设你在画布的不同分支上布置了 3 个大模型提示词节点，它们都需要注入同一个客户名称或项目代号。如果采用传统引脚连线方式，你需要从源节点拉出 3 根长连线分别接入这 3 个节点，这不仅会让画布变得杂乱无章，而且一旦你希望在文本框中直接手工微调内容，长连线就会造成干扰。
工作流变量彻底免去了跨画布拉线的繁琐：只需在流的起始位置配置一次变量，即可在后续任意数量的文本框中直接书写 {project_name}。一旦修改该变量的值，整个工作流中所有引用了该变量的节点在下一次触发执行时，均会自动无缝更新为最新数值！
创建与管理变量 (Creating a variable)
在官方算子库的 Variables 节点分类中，提供了一整套专门用于变量管理的轻量算子：
- Create Variable (创建变量)：声明一个带有名称、数据类型与初始值的变量；若当前流中已存在同名变量，则直接更新其值。将任意上游节点的输出连接到该节点的
value插槽，变量的类型会自动基于该连线完成类型推导； - Set Variable (设置变量)：向变量写入新值（若目标变量尚不存在则自动创建）。其
variable_name下拉菜单会自动列出当前作用域内所有可见的已有变量，同时也提供 Create new variable（创建新变量）选项； - Set Variables from Data (从数据结构批量创建变量)：一键将 Python 字典、JSON/YAML 字符串或键值对列表解析并批量转化为多个独立变量。当你从外部 API 响应或本地配置文件解析出一个大的 JSON 对象时，使用该节点可以避免为每个字段手动串联多个 Set Variable 节点；
- Get Variable (读取变量)：将变量当前持有的值作为标准的节点引脚输出拉出，用于与那些不支持
{name}行内文本插值的特定非文本引脚（如数值滑块、图像插槽）建立物理连线； - Has Variable (变量存在性判断)：检测某个变量在当前作用域下是否存在，返回布尔值
True/False，专用于条件分支编排（例如仅在首次运行时初始化变量）。
作用域归属机制：
Create Variable与Set Variable节点默认始终在其所处的当前 Flow（流）内部创建变量（即流级作用域）。节点高级选项（Advanced）中的 Scope (作用域查找范围) 设置，控制的是该节点在寻址/读取变量时的搜索范围，而非新变量的归属创建位置。
动态状态联动机制：上述算子将变量视为活跃的运行时状态而非只读常量。Create Variable 在每次工作流或节点被调度时，均会自动将自身重置为“未就绪 (Unresolved)”，确保其最新的 value 能够被百分之百重新灌入；而 Get Variable、Set Variable 与 Has Variable 在被引擎自省时，若检测到底层变量的值已被外部（如另一个流或另一个节点）修改，会自动将自身打标为未就绪，从而无需用户手动点击触发，即可自动级联刷新整个下游计算链路。
变量作用域层级 (Scopes)
每一次针对变量的操作（创建、读取、设置、枚举），均接收一个 scope 参数，用于指定变量的寻址与搜索边界：
| 作用域枚举值 | 具体寻址行为与优先级 |
|---|---|
hierarchical（默认推荐） |
层级向上冒泡搜索：首先在当前所在流中搜索；若未找到，则沿着嵌套层级向其父级流逐层向上回溯直至顶层根流；若仍未找到，最后检查全局变量。首个命中的变量获胜生效。 |
current_flow_only |
仅限当前流：仅严格在节点所在的当前流内部寻址，彻底忽略父级流与全局变量。 |
global_only |
仅限全局变量：仅在脱离于具体流之外的全局变量池中寻址。 |
all |
全域枚举：跨越全系统所有流提取所有变量集合（主要用于在前端构建下拉选择器，而非解析单一值）。 |
在 99% 的场景下，采用默认的 hierarchical (层级模式) 是最优选择：在顶层主流中定义一次 project_name，其内部嵌套的所有子流（Sub-Flow）均能天然且直接地读取 {project_name}。若某个子流内部自行定义了一个同名的 project_name，该局部定义会在子流内部发生遮蔽 (Shadowing) 覆盖父级数值；而一旦跳出该子流，父级变量依然原封不动。
变量数据类型 (Variable Types)
变量的 type 与节点引脚上的类型标签完全一致，支持 str、int、float、bool、json 以及图像类型等。Create Variable 能够基于输入连线全自动推导数据类型。
需要特别说明的是：仅持有 str（字符串）或 int（整数）数值的变量才支持直接在文本输入框中通过 {name} 语法进行行内动态插值！ 持有图像、列表或 JSON 对象的复杂变量依然能够完美配合 Get Variable / Set Variable 进行跨节点传递，但严禁直接丢进文本框中（因为系统无法在文本行内有意义地将一张图片渲染为文字）。
文本框中的行内动态插值 (Inline Substitution)
在任何支持变量插值的节点文本输入框中，键入 { 字符，编辑器会自动弹出一个智能变量选择器，清晰按数据来源归类列出当前作用域内所有可用的变量以及项目级只读宏：
- 选择或直接手写：点击选择或手动输入
{project_name}闭合括号。在工作流执行计算时，引擎会自动提取变量实际值进行即时文本替换； - 容错防呆：如果花括号中的变量名在当前作用域内不存在，系统会原样保留该字面量文本（或者在使用了可选标记时安全降级丢弃），绝不会因为拼写手误而默默产生错误的数据；
- 局部禁用：若你的提示词本身就包含合法的花括号字面量（例如特定代码段或不需要替换的模板），可以在工作流中添加 Set Variable Substitution 节点将该流的自动替换功能全局关闭。
格式化修饰符规范 (Format Specs)
在变量名后添加冒号 :，即可追加格式化修饰符。修饰符支持从左至右链式叠加调用，完整遵循 路径宏字符串变换规范：
| 修饰符语法 | 转换处理结果 |
|---|---|
:lower |
全小写 (lowercase) |
:upper |
全大写 (UPPERCASE) |
:title |
英文单词首字母大写 (Title Case) |
:snake |
下划线蛇形命名 (snake_case) |
:pascal |
大驼峰命名 (PascalCase) |
:camel |
小驼峰命名 (camelCase) |
:screaming_snake |
全大写蛇形命名 (SCREAMING_SNAKE_CASE) |
:slug |
适用于 Web URL 的短横线连接命名 (url-safe-slug) |
:dot |
点分命名 (dot.case) |
:abbrev |
提取每个单词的首字母缩写 |
:trim |
剔除字符串首尾的多余空白字符 |
经典实战示例：
{project_name} → "Autumn Campaign"
{project_name:lower} → "autumn campaign"
{project_name:slug} → "autumn-campaign"
{project_name:snake:upper} → "AUTUMN_CAMPAIGN"
高阶防御性插值语法
- 可选修饰符
?：{project_name?}—— 当变量未定义时，自动静默渲染为空字符串，而不是将原文本{project_name?}暴露在提示词中； - 默认兜底值
|default：{project_name|untitled}—— 当变量不存在时，自动使用untitled文本进行保底插值替换。
经典实战范例：跨提示词统一项目主题名称
假设你正在搭建一个影视概念海报生成工作流，需要在多个扩散模型提示词节点中反复复用同一个主项目代号：
- 在流的最左侧放置一个 Create Variable 节点：将
variable_name设置为project_name，并在value中直接输入Autumn Campaign（无需拉线，直接输入字面量即可），类型自动保持为str； - 在第一个文生图提示词节点的文本框中输入：
A cinematic key art poster for {project_name}, dramatic lighting, wide shot - 在下游负责生成角色概念草图的第二个提示词框中输入：
Concept sketch, {project_name:slug} style guide, muted palette - 点击执行工作流。两个节点在运算时均会无缝提取到变量值：第一个节点自动解析为
Autumn Campaign，第二个节点自动解析为autumn-campaign。
后续若需要启动一个全新的“冬日企划”，只需在最开始的 Create Variable 节点上修改一次输入值，全工作流中所有引用了该变量的节点在下次执行时均会自动全面同步，无需重构任何一根连线！