工程级变量 (Project Variables)

在工程配置文件的 variables 节点中，可以声明归属于当前工程的强类型具名变量。它们深度融入到与工作流变量完全相同的 {VAR} 插值替换语法体系中，既可以在前端画布的各个算子节点参数文本框中直接引用，也可以在底层的宏模板中作为占位符消费。

variables:
  shot_code:
    value: sc042
  frame_start:
    value: 1001
    type: int
  facility:
    value: mtl
    permission: read_only

字段规范参考 (Fields)

字段名称	是否必填	默认值	详细规范与业务语义
`value`	是	—	变量的初始数值。必须与声明的 `type` 类型严格相符，仅支持字符串或整型数字。
`type`	否	`str`	强类型约束：`str`（字符串）或 `int`（整数）。声明了 `type: int` 却赋予带引号的字符串会在工程加载期报错阻断。
`permission`	否	`read_write`	访问权限控制：`read_write`（读写均可：支持在运行期动态修改并自动反写回盘持久化）；`read_only`（只读保护：严禁在运行期被篡改，仅能通过手动编辑 YAML 修改）。`write_only` 目前已被语法接收，但尚未实施严格的读取遮蔽（详见下方警告）。

不支持布尔型 (bool) 或浮点型 (float) 作为工程变量。只有字符串与整型数值能够直接插入 {VAR} 占位符。

关于 write_only 写入专用的安全提示

声明为 write_only 的变量允许像 read_write 一样在运行期写入，但当前内核版本尚未实现在读取时的星号遮蔽掩码——目前在界面展示与宏替换时依然会如实暴露明文。切勿使用它来存储 API Key 等绝对敏感的机密。针对敏感凭证的完全保护将在后续专属的 Secrets 模块中正式上线。

工程变量的查找与生效优先级 (How project variables resolve)

当工作流或宏模板中出现 {VAR} 占位符时，系统按照作用域距离自内向外层层逐级检索匹配，内层胜出：

工作流局部变量 (Workflow/Flow variables) — 在当前工作流变量面板中创建的局部变量；
工程级变量 (Project variables) — 当前 variables: 节点声明的变量，以及工程内置常量与逻辑目录名；
全局环境变量 (Global variables)。

在工程这一层级内部，系统内置常量与逻辑目录名具有绝对无条件的最高优先级。如果你在 variables: 中声明了一个名为 workspace_dir 或与某个逻辑目录同名的变量，系统会在加载期发出警告并强行无视你的变量——请始终选用不冲突的业务名称。

目录名与内置常量属于系统保留字：引擎会严格拒绝将任何工作流变量或全局变量重命名为这些名字。

运行期动态反写与持久化 (Runtime writes and persistence)

被标记为 read_write 的工程变量允许在引擎运行期间动态变更——无论是在前端变量面板中手动修改，还是由专门负责设置变量的算子节点在计算中动态写入。

每次成功的写入都会立即静默回写并持久化保存进磁盘上的工程 YAML 文件中，使得最新状态能够无损跨会话留存。

写入时引擎会进行严格的强类型校验：如果向一个 type: int 的变量赋予纯文本字符串，操作会被立即拒绝并报错，绝不发生静默的非安全类型强制转换。

被标记为 read_only 的变量会严格拒绝任何运行期的写入指令。若需调整其值，必须手动编辑工程 YAML 文件并重新加载工程。

工程变量在宏模板中的层级地位

在物理路径宏解析（如场景中的 macro 或目录中的 path_macro）过程中，工程变量深度参与解析，其生效优先级如下：

系统内置常量变量 ({workflow_name}, {workspace_dir} 等)
逻辑目录别名 ({outputs}, {inputs} 等)
调用方在代码中即时传入的专属参数 (file_name_base, file_extension 等)
工程级变量 (Project variables)（即本章所定义的变量）
工程自定义环境变量 (environment:)
操作系统 Shell 环境变量

详细的优先级权衡讨论请参阅环境与系统内置变量手册。

父子工程继承与墓碑化删除 (Inheritance)

当工程声明了父工程时，变量会按名称逐项执行合并：

子工程中同名的变量条目会完全替换覆盖父工程中的条目；
若希望在子工程中彻底移除父工程定义的某个变量，在子工程中将其值显式设为 null 即可打上墓碑标记 (Tombstone)：

# child griptape-nodes-project.yml
variables:
  shot_code:
    value: sc099      # 覆盖父工程的 shot_code 取值
  facility: null       # 彻底移除继承自父工程的 facility 变量

父工程中存在、且子工程未提及的变量，将被原封不动完整继承。

在运行期通过界面删除一个继承而来的变量，系统会自动将带有 null 墓碑标记的条目反写进当前子工程的 YAML 中，确保重启后依然维持移除状态。

架构选型指引：何时使用 `variables`，何时使用 `environment`？

工程配置文件同时提供了 variables: 与 environment: 两个代码块，二者服务于截然不同的业务对象：

variables (工程变量)：属于引擎的一等公民变量。它们会直观呈现在界面的变量面板与下拉选择器中，具备显式的数据类型与读写权限控制，支持运行期动态修改与持久化反写，并全面参与算子节点文本输入控件中的 {VAR} 占位替换；
environment (环境参数)：专门用于底层宏模板的路径拼接与操作系统环境变量导出。它们纯粹由字符串键值对构成，不支持在前端运行期动态写入，也不会呈现在算子节点的普通变量候选框中。

工程经验法则：凡是需要面向合成师、艺术家在前端交互查看或在运行期动态调参的属性，请声明在 variables: 中；凡是纯粹用于底层控制输出文件夹路由、机器标识等幕后路径拼接的常量，请放置在 environment: 中。