写入场景与冲突策略 (Situations)

场景 (Situation) 是指对工程中某种具体文件读写情景的具名抽象。它负责定义：

文件存储位置：通过宏模板 (Macro Template) 动态解析计算目标路径；
同名碰撞冲突仲裁：当目标位置已存在同名物理文件时如何处理（通过冲突策略 Collision Policy）；
容错兜底机制：当当前场景的宏解析失败时（例如缺失了必要的变量），系统应当转入哪个备选兜底场景 (Fallback Situation)。

当一个算子节点需要向磁盘落盘数据时，它只需声明自己处于哪种场景下（例如 save_node_output 节点输出保存场景），工程项目系统便会在底层自动调用该场景绑定的宏模板并严格执行其冲突仲裁策略。

同名文件冲突策略 (Collision policies)

冲突策略名称	行为表现与落盘机制
`create_new`	自增序号，绝不覆盖。在文件名中递增数字计数器，直至寻找到磁盘上尚未占用的新路径。宏模板中可以显式声明 `{_index?:NN}`（可选序号：首张图不加后缀，重名时才追加 `001`、`002`...）或 `{_index:NN}`（必选序号：从首张图开始即打上固定位宽的序号）。若宏中未显式包含任何索引插槽，系统在碰撞时会自动自增追加 `_1`、`_2` 等后缀。
`overwrite`	静默覆盖。若目标路径已存在同名旧文件，直接就地无损替换，不产生任何拦截弹窗。
`fail`	报错阻断。若目标路径已存在同名文件，立即终止本次运算并向控制台报告错误。

参数 create_dirs 控制是否自动递归创建中间缺失的父级目录（true 等价于终端的 mkdir -p 行为；若设为 false 则在父目录不存在时报错阻断）。

容错兜底回退链 (Fallbacks)

场景配置允许指定 fallback 字段。如果主场景无法解析其宏模板（例如某些上游动态变量缺失），系统会自动尝试使用该兜底场景进行路径计算。预置的 save_file 是整个系统最基础的极简兜底场景。

系统预置的核心场景清单 (Default situations)

1. `save_file`（基础通用兜底）

macro:  {file_name_base}{_index?:03}.{file_extension}
policy: create_new, create_dirs: true

在工程根目录（或调用方上下文指定的目录）下保存文件的通用兜底场景。{_index?:03} 属于带前导零补齐的可选索引——首个文件不带序号，重名碰撞时自动追加 001、002 等序号。

2. `copy_external_file`（引入外部素材）

macro:    {inputs}/{node_name?:_}{parameter_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

当创作者将外部文件拖拽扔进画布或通过文件选择器加载时触发。文件会被统一复制转存至 inputs 文件夹内，并自动附带节点名与参数名作为可选前缀，清晰溯源资产归属。

3. `download_url`（远程 URL 抓取）

macro:    {inputs}/{sanitized_url}
policy:   overwrite, create_dirs: true
fallback: save_file

当节点从远程网络下载文件时触发。URL 会被自动脱敏净化为合法安全的文件名落盘至 inputs 目录；相同 URL 下载的文件默认直接覆盖，避免重复堆叠冗余垃圾。

4. `save_node_output`（常规节点渲染输出）

macro:    {outputs}/{sub_dirs?:/}{node_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

几乎所有生图、生视频与文件导出节点最核心的默认场景。文件自动存入 outputs 目录；支持通过 {sub_dirs?:/} 建立多级子文件夹，并以节点名称作为前缀。

5. `save_output_directory`（按批次归档目录）

macro:  {outputs}/{sub_dirs?:/}{dir_name}_v{###}
policy: create_new, create_dirs: true

当节点需要将一整批成果写入专属文件夹（而非散落在外）时触发。每次执行均会新建一个带自增版本号的独立文件夹（如 outputs/renders_v001、outputs/renders_v002），永远不会覆盖历史执行批次。

6. `save_file_sequence`（图像序列帧输出）

macro:  {outputs}/{file_extension_directory?:/}{sub_dirs?:/}{file_name_base}_v{###}/{file_name_base}.####.{file_extension}
policy: create_new, create_dirs: true

影视工业标准序列帧写入场景（例如从视频中提取连续帧）。每次运行都会生成独立版本目录，且目录内的每一帧画面均遵循严格的帧序列编号：

大括号内的 {###} 代表外层文件夹的版本序列号；
裸露在大括号外部的 #### 代表该批次内每一帧的真实时间轴帧编号。详见图像序列帧手册。

7. `save_preview`（流式预览图）

macro:    {previews}/{drive_volume_mount?:/}{source_relative_path?:/}{source_file_name}.{preview_format}
policy:   overwrite, create_dirs: true
fallback: save_file

负责生成轻量缩略预览图。预览图会严格镜像复刻源素材的物理目录层级，确保每个源素材在隐藏的 .griptape-nodes-previews 目录中有且仅有一张对应的缩略图。

8. `save_static_file`（工作流静态依赖资源）

macro:    {workflow_dir?:/}{static_files_dir}/{file_name_base}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

用于保存内嵌进工作流工程中的静态打包资源。

9. `save_temp_file`（过程临时碎片）

macro:    {temp}/{node_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

用于节点在复杂运算中间转存的高耗能临时大文件（例如色彩空间转换中间的 EXR 帧缓冲）。运算收尾后由节点负责清理。

10. `save_workflow`（保存工作流工程文件）

macro:    {workspace_dir}/{sub_dirs?:/}{file_name_base}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

每次保存当前工作流、克隆模板或分叉工作流时触发。默认直接保存在工作空间根目录下并静默覆盖。

11. `create_versioned_workflow`（另存为版本化工作流快照）

macro:    {workspace_dir}/{sub_dirs?:/}{file_name_base}_v{_index:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

在编辑器中执行 Save As New Version (Alt+Shift+S) 时触发。每次保存均会自动在文件名末尾自增三位序号（如 my_workflow_v001.py、my_workflow_v002.py），形成防篡改的版本快照序列。

算子节点如何绑定与消费场景

节点的场景归属由该节点的代码作者在底层固化声明，节点界面上默认不会出现“选择场景”的下拉框。节点通常只暴露出一个名为 Output File 的文件名参数框，而场景默默在背后掌舵。

节点参数框中的纯文本字符串会被引擎自动拆解为 file_name_base（文件名主体）与 file_extension（扩展名后缀），其余路径全部交由场景的宏模板拼接。因此，在节点中输入 render.png，在 save_node_output 场景下最终生成的是 outputs/ImageGen_render.png，而不是落盘在根目录。

将单个节点的输出强制重定向至他处

通常直接输入纯文件名即可满足规范。若需要对某单一节点进行路径特例化控制，支持两种高级输入方式：

相对子路径：输入 lighting/pass_a/render.png，系统会保留该场景的基础目录，将其智能嵌套存入 outputs/lighting/pass_a/ 中；
绝对物理路径：输入 /mnt/studio/renders/render.png 或 C:\renders\render.png。此时你直接锁死了物理磁盘地址，工程系统将跳过宏模板计算——不再附加 outputs 目录前缀，不再追加节点名前缀。但场景的同名冲突策略依然生效（若重名依然会自增 _1 保全历史资产）并负责递归创建缺失目录。

硬编码绝对路径的副作用

输入绝对路径会使当前节点脱离工程项目系统的跨平台保护：该路径是为你本地这台电脑绑定的，工作流分享给其他同事或放到云端执行时会直接抛出找不到盘符或路径不存在的致命报错。若需统一修改存储路径，请始终在工程配置文件中编辑对应的场景宏。

探测节点背后使用的场景

将鼠标光标悬停在节点的输出文件名参数文本框上，悬浮工具提示会清晰显示其绑定的场景标识：

Output filename (uses 'save_node_output' situation template)

单节点场景参数临时覆盖：File Output Settings 节点

若需要在不修改工程配置 YAML 的前提下临时为单个节点重写场景或覆盖策略：

点击文件名参数右侧的齿轮 (Cog) 图标。系统会自动就地生成一个 File Output Settings (文件输出设置) 辅助节点并自动连入该参数端口：

Situation：自由切换为任意其他场景；
Macro：就地微调当前这一路输出的路径宏模板；
If File Exists：就地调整冲突策略（Increment Version 递增版本 / Overwrite Existing 覆盖 / Abort 报错终止）；
Auto Create Path：是否自动创建中间目录。

此处做出的任何变动仅对与其相连的单一节点生效。若希望全流全局生效，请在工程配置文件中编辑场景定义。

写入场景与冲突策略 (Situations)

同名文件冲突策略 (Collision policies)

容错兜底回退链 (Fallbacks)

系统预置的核心场景清单 (Default situations)

1. save_file（基础通用兜底）

2. copy_external_file（引入外部素材）

3. download_url（远程 URL 抓取）

4. save_node_output（常规节点渲染输出）

5. save_output_directory（按批次归档目录）

6. save_file_sequence（图像序列帧输出）

7. save_preview（流式预览图）

8. save_static_file（工作流静态依赖资源）

9. save_temp_file（过程临时碎片）

10. save_workflow（保存工作流工程文件）

11. create_versioned_workflow（另存为版本化工作流快照）