5.8 工作流变量（Workflow Variables）

在 Pop 的可视化工作流系统中，“变量（Variables）”是让节点之间实现 跨节点数据共享、状态记录、循环累加、条件判断、上下文存储 的核心机制。

变量系统使得你可以构建更动态、更灵活、更可编排的复杂流程。

本章节将介绍：

• 什么是工作流变量
• 变量的几种类别
• 如何在节点中读取与写入
• 在 PSL 中操作变量
• 常见使用场景
• 最佳实践与注意事项

---

🧩 一、什么是工作流变量？

工作流变量就是运行过程中全局可访问的数据存储区域。

它具有：

• 作用域跨节点
• 生命周期贯穿整个运行
• 可写入、可读取
• 适合保存中间结果、状态标记、循环累加项

在 Pop 中，变量由系统自动维护，并可通过 PSL、脚本节点、条件节点、AI 节点、HTTP 节点 等进行访问。

---

🗂 二、变量的类别

Pop 的工作流变量目前包含三大类：

类型	示例	作用
输入变量 input	input.value.title	用户输入的数据
节点输出变量 nodes	nodes[n].output.xxx	某个节点的输出结果
全局变量 globals	globals.set("key", value)	跨节点共享、可随时写入

三者关系如下：

input  →  nodes  →  globals

其中 globals 是可写的，是“核心变量存储区”。

---

🧰 三、输入变量（input）

输入变量是由入口节点统一提供的。

读取方式：

input.value.name;
input.value.file;
input.value.settings;

特点：

• 只读
• 由用户运行时提供
• 适合作为工作流的初始数据源

---

🔗 四、节点变量（nodes）

每个节点运行后，都会产生一个节点输出。

你可以通过两种方式访问：

方式 1：通过节点 ID（顺序编号）

nodes[3].output;

方式 2：通过节点序列号（推荐）

nodes.sn(12).output.result;

优势：

• 即使节点顺序变化也不会失效
• 多次运行更稳定

节点变量用于读取 上一个节点的执行结果，例如：

nodes.sn(5).output.text
nodes.sn(7).output.json.data

---

🌍 五、全局变量（globals）——最关键的变量体系

全局变量是 唯一可写入 的变量，也是“跨节点共享数据”的核心。

1. 写入变量

globals.set("summary", "生成的摘要文本");
globals.set("items", [1, 2, 3]);
globals.set("status", { step: 2, message: "OK" });

2. 读取变量

globals.value.summary;
globals.value.items;

3. 覆盖策略

多次写入会自动覆盖：

globals.set("count", globals.value.count + 1);

非常适合循环、计数、累积内容等场景。

---

✨ 六、在 PSL 中使用变量

几乎所有变量操作都可以通过 PSL 完成：

1. 读取输入

const name = input.value.name;

2. 读取其他节点输出

const data = nodes.sn(10).output.json;

3. 设置全局变量

globals.set("result", data.processed);

4. 判断变量是否存在

if (globals.value.cache) {
  return globals.value.cache;
}

---

🔄 七、变量的运行生命周期

变量在 一次工作流运行期间 持续有效：

1. 工作流开始 → 变量初始化
2. 节点依次执行 → 节点输出写入 nodes
3. 脚本、AI、逻辑节点可写入 globals
4. 工作流结束 → 返回输出参数

不会跨运行保留，并不具备永久存储能力。

---

📘 八、变量典型使用场景

✔ 1. 在不同节点间共享数据

例如：

AI 节点总结 → 写入 globals → 后续节点统一使用

✔ 2. 循环累加数据

循环节点内：globals.set("items", [...globals.value.items, newItem])

✔ 3. 缓存中间结果避免重复计算

if (globals.value.cache) return globals.value.cache;

✔ 4. 条件判断

if (globals.value.score > 60) ...

✔ 5. 汇总多个节点输出作为最终结果

globals.set("final", {
  a: nodes.sn(3).output.x,
  b: nodes.sn(7).output.y,
});

---

⚠️ 九、注意事项与最佳实践

1. 为变量命名保持一致性

推荐使用：

snake_case
或
lowerCamelCase

例如：

user_info
report_items
summaryText

2. 避免存储过大的文件内容

例如 PDF 字节、图片 Buffer 等可能导致性能下降。

建议：

• 写入文件节点保存
• 全局变量仅保存文件路径或索引号

3. 避免变量名冲突

同一工作流内不要重复使用同名变量。

4. 不要滥用变量

能通过节点连接传递的就用节点连接。

全局变量适用于：

• 条件
• 循环
• 状态共享
• 高级脚本逻辑

---

🎯 十、小结

工作流变量让 Pop 的编排能力从“线性流程”扩展到“真正的可编程自动化”。

掌握变量之后，你可以：

• 在节点间共享状态
• 实现循环、判断、缓存
• 构建复杂的数据流管道
• 更灵活地控制流程执行