udmin/docs/variable-node-usage.md

变量赋值节点：表达式/引用直输 使用文档

一、功能概述

• 变量节点的右值支持三种取值方式：
  • 常量（constant）：数字、字符串、对象、数组等，原样作为值。
  • 引用（ref）：通过路径引用上下文或其他节点的输出。
  • 表达式（expression）：使用 Rhai 表达式，运行时计算出值。
• 新增“快捷语法”直输能力：即便右值选择为“常量”，也可直接在输入框里写：
  • 表达式直输：以 ctx. 或 ctx[ 开头的字符串按 Rhai 表达式求值。
  • 引用直输：以 ${...} 包裹的字符串按“引用路径”解析。

二、使用入口

• 打开画布，选择“变量”节点，在右侧侧边栏的“赋值行”进行编辑。
• 侧边栏顶部会有一段提示文字，说明三种取值方式与两种快捷语法。
• 相关代码位置：
  • 前端：frontend/src/flows/nodes/variable/form-meta.tsx
  • 后端：backend/src/flow/executors/variable.rs

三、如何输入右值

• 方式一：常量（默认）
  • 直接输入数字、字符串、对象、数组，例如：0、"hello"、{"a":1}、[1,2,3]。
  • 支持“快捷语法”，见下文。
• 方式二：引用（ref）
  • 切换右值类型为“引用”，通过路径选择器选择 ctx 中已有字段或其他节点输出。
  • 推荐用于团队协作时提升可读性。
• 方式三：表达式（expression）
  • 切换右值类型为“表达式”，输入 Rhai 表达式，运行时计算。
  • 适合需要计算或条件逻辑的场景。

四、快捷语法（在“常量”输入框中也可直输）

• 表达式直输（运行时按 Rhai 表达式执行）
  • 触发规则：字符串以 ctx. 或 ctx[ 开头。
  • 示例：
    • ctx["user_n"]
    • ctx.user.profile.name
    • (ctx["score"] ?? 0) + 1
• 引用直输（运行时按引用路径取值）
  • 触发规则：字符串以 ${ 开始且以 } 结束。
  • 示例：
    • ${user_n}（引用顶层 ctx.user_n）
    • ${nodes.order_node.result.id}（引用某节点的输出字段）
    • ${orders[0].id}（支持数组下标）

五、路径与表达式说明

• ctx 注入
  • 表达式求值时，会自动注入 ctx（流程上下文），可通过点号或中括号访问。
  • 支持典型的运算与空值处理（如 ??）、算术、比较等。
• 引用路径（${...}）
  • 推荐使用规范路径：顶层字段如 ${a.b}，节点输出如 ${nodes.node_id.some_field}。
  • 支持数组访问：${arr[0].name}。
  • 仅在完整匹配以 ${ 开始并以 } 结束时触发引用直输。
• 节点输出引用建议
  • 使用 ${nodes.<nodeId>.<字段>} 的规范形式。
  • 避免模糊/非规范路径，便于协作和排障。

六、歧义与转义

• 如需输入“字面量字符串”而非触发快捷语法：
  • 对于以 ctx. 或 ctx[ 开头的文本：在前面加引号或任意非 c 字符，例如 'ctx[1]' 或前面加一个空格。
  • 对于包含 ${...} 的文本：只要整串文本不同时满足“以 ${ 开头且以 } 结束”，就不会触发引用直输；或者在外层再包一层引号，如 "abc ${x} def"。
• 简单记忆：只有“整串文本”完全匹配触发条件，才会被识别为快捷语法；否则按原样作为字符串。

七、常见示例

• 从上下文读取用户名：
  • 左值：user_name；右值（常量输入框直输）：ctx["user_n"]。
• 从节点输出读取订单 ID：
  • 左值：first_order_id；右值（常量输入框直输）：${nodes.order_node.result.orders[0].id}。
• 进行加一计算：
  • 左值：score_plus_one；右值（常量输入框直输）：(ctx["score"] ?? 0) + 1。
• 传统方式（非快捷语法）：
  • 切换到“引用”类型，选择路径 a.b。
  • 切换到“表达式”类型，输入 (ctx["a"] ?? 0) + 1。

八、最佳实践

• 简单取值：优先用“引用”类型或 ${...} 快捷语法。
• 复杂逻辑：使用“表达式”类型，便于维护与问题定位。
• 协作/导出可读性：更倾向使用“引用/表达式”类型（而非快捷语法），或在保存时做规范化（如后续启用）。

九、导出/保存行为

• 本次为“运行时增强”：
  • 在“常量”输入框中写的 ctx[...] 或 ${...}，保存/导出时仍表现为普通字符串。
  • 运行时自动识别并解析执行。
• 如需“保存即规范化”（将快捷语法转换为标准的 ref/expression 类型），可作为后续可选功能启用。

十、常见问题排查

• 变量值为空或错误：
  • 检查 ctx 中是否存在对应字段（例如 ctx.user_n 是否在上游节点或初始上下文中设定）。
  • 检查节点 ID 与输出字段拼写（如 nodes.<nodeId>）。
  • 表达式报错多为语法或空值访问，建议在“表达式”类型中尝试以便定位。
• 表达式返回类型：
  • 应返回可序列化 JSON 值（字符串、数值、布尔、对象、数组或 null）。
• 查看结果：
  • 在变量节点右侧“输出”面板或下游节点输入位置查看结果。

十一、版本信息

• 新增：在“常量”输入框中支持表达式/引用快捷直输。
• 兼容：不影响既有流程配置与执行。