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

## 一、功能概述
- 变量节点的右值支持三种取值方式：
  - 常量（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`）。
- 查看结果：
  - 在变量节点右侧“输出”面板或下游节点输入位置查看结果。

## 十一、版本信息
- 新增：在“常量”输入框中支持表达式/引用快捷直输。
- 兼容：不影响既有流程配置与执行。