环境与系统内置变量 (Environment & Builtin Variables)

工程项目系统在解析物理路径宏时，融合了工程自定义环境参数 (Environment) 与系统内置只读变量 (Builtin Variables)。本手册深入剖析它们的声明方式、跨层级嵌套引用规则以及严格的优先级生效裁决梯队。

工程自定义环境参数 (Environment)

工程配置文件的 environment 代码块用于集中维护自定义的键值对参数。这些值可自由嵌入在宏模板字符串以及目录的 path_macro 属性中进行插值计算：

environment:
  RENDER_STYLE: "realistic"
  CLIENT_CODE: "ACME"

多层增量合并行为 (Overlay behavior)

当前工程文件中定义的 environment 键值会以增量方式叠加合并在系统出厂默认值（以及父级工程底板）之上： - 若键名在底板中已存在，子工程中声明的值将直接覆盖前者； - 若键名属于全新命名，则安全无损追加并排生效。

嵌套级联引用其他变量

环境参数本身就是一种轻量级的宏模板！一个环境参数的取值中可以包含大括号 {NAME}，从而动态引用系统内置常量、逻辑目录名、其他工程环境变量，乃至宿主操作系统的 Shell 环境变量：

假设启动 Griptape Nodes 的终端中预先导出了 SHARED_DRIVE=/mnt/renders，则可优雅编写：

directories:
  outputs:
    # 直接穿透引用操作系统的 Shell 环境变量——无需事先在 environment 中显式声明
    path_macro: "{SHARED_DRIVE}/outputs"

environment:
  CLIENT_CODE: "ACME"
  # 引用系统内置常量
  PROJECT_RENDERS: "{project_dir}/renders"
  # 复合编排：融合 Shell 环境变量 + 工程环境参数 + 静态字面量文本
  CLIENT_RENDERS: "{SHARED_DRIVE}/{CLIENT_CODE}/renders"

所有的变量引用均支持递归展开计算。系统在编译阶段会自动探测循环引用死锁（例如 A: "{B}" 且 B: "{A}"），一旦发生即抛出宏解析阻断错误，确保引擎绝对稳定。

兼容传统的 `$VAR` 语法及其局限性

为了向前兼容历史遗留工程，如果一个环境参数的取值严格全等于 $NAME（且前后绝无任何多余文本或后缀），在被宏模板消费时会自动读取操作系统环境变量：

environment:
  OUTPUT_ROOT: "$RENDER_FARM_SHARE"  # 宏消费时生效：{OUTPUT_ROOT} -> /mnt/renders

强烈注意历史 $VAR 语法的狭隘缺陷： 1. 只能承载纯值：一旦在周围追加任何字符（如 "$SHARED_DRIVE/outputs"），变量展开立即失效，会被当作死文本； 2. 仅在宏解析期生效，不注入进程：通过 $VAR 绑定的变量在系统写入 os.environ 时不会被展开。任何第三方子进程或算子节点通过 Python 原生 os.environ.get("OUTPUT_ROOT") 读取到的将是冷冰冰的明文字符串 "$RENDER_FARM_SHARE"； 3. 严禁嵌套编排：以 $ 开头的值无法嵌套引用其他工程变量或内置目录。

现代最佳实践：请在所有新工程中统一采用 {NAME} 语法——它语义清晰、在宏模板与操作系统 os.environ 中均能一致性展开，且在 environment 与目录 path_macro 中通用。

系统内置只读变量 (Builtin variables)

内置变量在宏执行时由引擎底层动态注入，无需且严禁由创作者在 YAML 中人为重写：

内置变量标识	数据类型	详细物理含义与解析规则
`project_dir`	物理目录	工程基准目录的绝对路径（存放 `griptape-nodes-project.yml` 的物理文件夹；若无工程文件则等价于工作空间目录）。
`workspace_dir`	物理目录	当前活跃工作空间的绝对物理路径。
`workflow_name`	纯字符串	当前正在被调度计算的工作流的工程文件名。
`workflow_dir`	物理目录	包含当前正在执行的工作流 `.py` 脚本的物理文件夹绝对路径；对于尚未落盘的新建流，代表其创建时所在的临时文件夹。
`static_files_dir`	纯字符串	存放静态打包资产的子文件夹名称（来自全局偏好，出厂默认为 `staticfiles`）。

运行时动态即刻解析

内置变量并非在工程配置文件加载时被静态固化，而是在宏模板实际被执行计算的瞬间动态解出： - workflow_name 与 workflow_dir 永远精准映射当前处于计算焦点中的具体工作流； - project_dir 忠实映射当前加载工程的物理落盘位置。

若某个宏模板中声明了必选的内置变量（例如 {workflow_name}），但在运算时外部并未挂载有效的工作流，宏解析会立即报错阻断；若声明为带问号的可选变量（{workflow_name?:_}），该代码块会自动优雅隐形。

未保存工作流的路径边缘处理

从未在磁盘上保存过的新建工作流尚未生成物理实体文件。当你在工程浏览器某个特定子文件夹中点击新建时，编辑器会将该文件夹路径告知引擎，此时 {workflow_dir} 会临时指向该文件夹。

一旦创作者首次按下 Cmd/Ctrl+S 将工作流保存到磁盘的另一个位置，{workflow_dir} 会在内存中立即跳跃重定向至新的保存目录。此前已经落盘在旧目录中的生成物不会被自动物理挪动，但后续所有基于 {workflow_dir} 生成的路径都会即刻转入新文件夹。

变量生效优先级裁决天梯 (Variable priority)

当一个宏模板被执行解析时，如果同名变量在多个层级中同时存在，系统严格按照以下优先级天梯自顶向下依次匹配判定——首个命中者直接胜出：

系统内置只读变量 (Builtin variables) — 绝对至尊优先级；绝不可能被任何外部输入、工程配置或环境变量所掩盖；
逻辑目录别名 (Directory names) — 来自工程的 directories 配置；严禁被节点参数传入的临时变量覆盖；
调用方即时传入的专属变量 (Caller-supplied variables) — 触发该宏计算的特定算子节点在代码中传出的动态上下文（如 file_name_base、file_extension 等）；
衍生变量 (Derived variables) — 引擎在宏计算前夕由上下文实时计算出的辅助参数（例如 file_extension_directory，若调用方已显式传入则尊重调用方）；
工程级变量 (Project variables) — 在工程 variables: 代码块中声明的强类型变量；
工程自定义环境变量 (Project environment variables) — 在工程 environment: 代码块中定义的键值对；
操作系统 Shell 环境变量 (Shell environment variables) — 终极兜底。启动 Griptape Nodes 的操作系统环境变量（包括 $HOME、$USER 以及自定义的导出项）。保留字与工程变量始终优先于 Shell 变量，防止宿主机的环境变量意外污染工程管线。

若调用方试图传入一个与系统内置常量或目录别名同名、但数值不符的变量，宏解析系统会立即抛出 RESERVED_NAME_COLLISION 冲突阻断异常。