rp-engine transform节点实战：用Rhai沙箱脚本引擎实现无LLM调用的纯计算节点

🎯rp-engine是一个用 Rust 编写的 YAML 原生 Agent 工作流执行引擎，而它内置的transform 节点是整个工作流里最容易被忽略的“省钱利器”——通过Rhai 沙箱脚本引擎执行纯计算逻辑，全程零 LLM 调用、零 I/O，让你的工作流在数据清洗、字段拼装、去重统计等场景下既快又稳。

为什么需要 transform 节点？

一个典型的 Agent 工作流里，generate节点（调用大模型）往往是成本和延迟的大头。但很多环节其实根本不需要模型参与：

• 把上游查询结果去重、排序、拼接
• 拼装下游 API 或 LLM 请求体（payload）
• 生成时间戳、UUID、JSON 字符串
• 做简单的数学计算或字段映射

如果把这些小事交给 LLM，既浪费 token 又可能出错。rp-engine 的transform 节点正是为解决这个问题设计的：它是一个纯计算节点，内置的Rhai 脚本引擎在完全隔离的沙箱中运行你的脚本，不联网、不读写文件、不做系统调用，执行完把结果交给下游节点继续流转。

💡 一句话理解：能用脚本算出来的，就别花钱问模型。

transform 节点的核心机制

transform 节点的执行逻辑全部集中在 src/nodes/transform.rs 中，工作流程可以概括为 4 步：

1. 加载脚本：节点配置支持两种方式——内联script（直接写在 YAML 里，优先级更高）或file（按名称引用脚本文件，详见下文）
2. 注入变量：variables中声明的变量会从工作流状态中解析，注入为 Rhai 全局变量；同时还会注入一个_vars映射，包含所有已解析变量的集合
3. 沙箱执行：脚本在 Rhai 解释器中运行，官方规范中明确写明了沙箱边界：无文件 I/O、无网络访问、无系统调用，且限制单次脚本最多100,000 次操作、字符串上限1MB、数组/映射上限10,000 项
4. 输出转换：脚本最后一个表达式的值就是节点输出。如果返回的是映射（Map），每个键直接成为输出字段；否则会被包装为{"result": 值}

Rhai 引擎的创建与安全限制在 transform.rs 的create_rhai_engine中可以看到：

// Limit script execution to prevent abuse engine.set_max_operations(100_000); engine.set_max_string_size(1_048_576); // 1MB engine.set_max_array_size(10_000); engine.set_max_map_size(10_000);

这种“限流 + 无副作用”的设计，意味着即使 YAML 由外部用户提交，transform 脚本也不可能耗尽引擎资源或触碰宿主系统。

快速上手：三步写出第一个 transform 节点

1️⃣ 准备 Rhai 脚本文件

脚本放在启动时通过transforms_dir指定的目录中（见 src/engine/builder.rs 的transforms_dir配置项）。比如新建transforms/build_payload.rhai：

// 变量 'user_name' 和 'history' 会从节点配置注入 let greeting = "Hello, " + user_name; let unique_history = unique(history); // 返回 map —— 每个键都会成为节点输出字段 #{ "greeting": greeting, "message_count": history.len(), "unique_history": unique_history, "timestamp": now(), "request_id": uuid() }

2️⃣ 在 YAML 工作流中声明节点

参考官方规范 docs/FLOW_SPEC.md 中transform一节的定义：

- id: build_payload type: transform config: file: "build_payload" # 脚本名，加载 transforms/build_payload.rhai variables: # 可选：注入为 Rhai 全局变量 user_name: start.name history: load_history.rows

3️⃣ 构建引擎并运行

在 Rust 侧初始化引擎时指定脚本目录即可：

let engine = Engine::builder() .transforms_dir("./transforms") .build()?;

执行后，下游节点就可以通过build_payload.greeting、build_payload.request_id等路径读取这些输出字段了。

📌 小技巧：如果只是简单计算，甚至可以把脚本直接写在节点配置里（script字段），无需单独维护.rhai文件。两者同时存在时，内联script优先。

内置函数一览：常用能力开箱即用

引擎在 transform.rs 中为所有 transform 脚本注册了 4 个内置函数，覆盖日常计算的高频需求：

配合 Rhai 本身的数组、映射、字符串操作能力，一个 transform 脚本基本可以替代一段 20 行的 Python 数据处理代码——而且它运行在 Rust 进程内，启动即执行，毫秒级完成。

_vars：让一个脚本适配任意变量组合

上面的示例脚本是“定制”的：它依赖user_name、history这两个注入变量。如果你希望同一个脚本能处理任意变量组合，可以改用引擎自动注入的_vars映射——它包含本次节点解析出的全部变量。

docs/FLOW_SPEC.md 中给出的通用写法：

// _vars 是包含所有已解析变量的 map，适配任意变量组合 #{ "json_string": json_encode(_vars), "json_object": _vars }

这个技巧在“通用 JSON 汇聚节点”场景下非常实用：不管上游有多少个字段，下游拿到的永远是结构一致的输出。相关行为在 transform.rs 中实现，单元测试test_transform_vars_aggregation也验证了这一点。

常见场景与最佳实践

✅ 推荐用法

• LLM 前置清洗：data_connector查库后，先用 transform 去重/截断，再喂给generate节点，直接省 token
• 请求体拼装：用json_encode(_vars)一把梭构造下游 API 的入参
• 幂等与追踪：uuid()生成请求 ID，now()打时间戳，方便日志检索

⚠️ 注意事项

• 脚本名写错会报错：file指向的脚本必须存在于transforms_dir目录，否则会报Transform script 'xxx' not found并列出所有可用脚本名
• 纯计算，别想 I/O：Rhai 沙箱内没有文件、网络能力，需要外部数据请通过variables从工作流状态注入
• 脚本出错会中断节点：如1 / 0这类运行时错误会抛出Script 'xxx' execution failed，节点执行失败并终止该分支

相关文件索引

想深入源码或规范，可以从这几个入口读起：

• 📄 完整 YAML 规范（含所有节点类型）：docs/FLOW_SPEC.md
• 📄 transform 节点执行器实现：src/nodes/transform.rs
• 📄 引擎构建器（脚本目录加载逻辑）：src/engine/builder.rs
• 📄 更多可运行示例：examples/

小结：rp-engine 的 transform 节点用 Rhai 沙箱把“纯计算”从 LLM 中剥离出来——零成本、零网络、可限流、可复用。下次设计工作流时，先问问自己：这一步真的需要大模型吗？如果答案是否定的，一个 transform 节点就足够了。 🚀