按扩展名自动分流目录 (File Extension Directories)
file_extension_directories 是工程模板中的一个映射配置表，用于将文件扩展名 (File Extension) 映射到特定文件夹片段，从而实现按文件类型自动路由归档。当写入场景中的宏模板引用了衍生变量 {file_extension_directory} 时，工程系统会在该表中检索文件的后缀名，并替换为对应的目录路径。
典型应用场景：在无需为每种文件类型单独编写一套场景配置的前提下，自动将图片、视频、音频和文档分别归档到 outputs/ 下各自独立的子目录中。
快速上手范例 (Quick example)
project_template_schema_version: "0.3.0"
name: "My Project"
file_extension_directories:
png: "images"
jpg: "images"
mp4: "videos"
wav: "audio"
situations:
save_node_output:
macro: "{outputs}/{file_extension_directory?:/}{node_name?:_}{file_name_base}{_index?:03}.{file_extension}"
基于上述配置，不同后缀的生成物解析效果如下：
file_extension="png" → outputs/images/Node_render.png
file_extension="mp4" → outputs/videos/Node_render.mp4
file_extension="xyz" → outputs/Node_render.xyz (未映射后缀：占位槽优雅折叠消失)
在 {file_extension_directory?:/} 中使用 ?:/ 修饰符，使得该占位槽成为可选槽，并在该变量存在有效值时自动追加后缀 / 分隔符——因此，当遇到未映射的扩展名时，文件会安全保存在场景的根目录下，而不会引发宏解析阻断报错。
两种取值形式 (Two value forms)
映射表中的取值可以是一个纯字面量名称 (Plain name)，也可以是一个宏模板 (Macro)。
1. 纯字面量名称 (Plain name)
file_extension_directories:
png: "images"
字符串会被原样照搬使用，底层不触发任何额外的宏计算。这是最常用的标准用法，具有零计算开销。
2. 宏模板值 (Macro value)
file_extension_directories:
mp4: "{outputs}/videos"
wav: "{workspace_dir}/shared/audio"
当取值包含 {...} 占位符时，在代入场景宏之前，系统会率先结合工程内置变量、逻辑目录定义以及调用方传入的上下文参数（如 node_name）完成初级宏解析。
宏模板值使得单个 file_extension_directories 配置表能够将特定类型的文件彻底重定向到完全不同的根目录——例如直接将庞大的视频文件写入局域网共享盘——而无需为每种类型单独声明独立的场景。
宏模板值允许引用的变量范围
| 变量来源 | 典型范例 | 是否可用？ |
|---|---|---|
| 系统内置变量 | {workspace_dir}, {workflow_dir}, {project_dir}, {project_name}, {static_files_dir} |
支持 |
| 逻辑目录别名 | {outputs}, {inputs}, {temp}, 以及任何自定义逻辑目录 |
支持 |
| 调用方传入的上下文 | {node_name}, {parameter_name}, {sub_dirs}, {_index} |
支持 |
| 文件名组成部分 | {file_name_base}, {file_extension} |
严禁支持 — 目录路由不属于文件名层 |
文件名相关的变量被系统刻意排除：file_extension_directories 属于目录路由层 (Routing Layer)，其唯一职责是决断文件存放于哪个文件夹；文件名细节由场景宏末尾的文件名部分负责。
运行时解析裁决流程 (How resolution works)
file_extension_directory 属于衍生变量 (Derived variable)。它既不是只读内置变量，调用方通常也无需显式传入。相反，每当场景宏模板中引用了该占位符时，工程系统会自动执行以下推导规则：
- 调用方指定写入场景并传入参数（包括当前文件的
file_extension后缀）； - 在场景宏正式解析前，触发衍生变量推导规则：
- 若调用方已经显式传入了
file_extension_directory，规则主动放弃（调用方传入值胜出）； - 否则，系统在当前工程的
file_extension_directories映射表中以大小写不敏感方式检索file_extension； - 若取值为纯文本，直接作为变量的最终值；
- 若取值为宏模板，系统会先将其展开计算为具体的物理路径字符串；
- 若调用方已经显式传入了
- 将解出的路径值注入变量池，场景宏随后按标准流程完成最终路径解析。
若检索失败（扩展名为空、未加载工程文件、遇到未映射的后缀名、或宏展开报错），该变量将直接处于未设置状态。若场景宏采用了可选语法 {file_extension_directory?:/}，它会优雅退化为无子文件夹前缀的根目录；若场景宏采用了必填语法 {file_extension_directory}，系统会因缺失必填变量而抛出阻断异常。
与场景宏的编排组合 (Interaction with the situation macro)
引擎底层并没有专门的代码强行在路径前拼接或挂载路由前缀。最终路径的生成形式完全由你在场景宏模板中所写下的结构决定：
| 场景宏书写形式 | 实际路由表现 |
|---|---|
{outputs}/{file_extension_directory?:/}{file_name_base}.{ext} |
路由表现为 {outputs} 下的相对子目录。映射表中的取值必须为相对路径。 |
{file_extension_directory?:/}{file_name_base}.{ext} |
路由直接统辖根目录。映射表中的取值可写绝对路径，从而彻底脱离 {outputs} 的层级。 |
带有绝对路径值的 {outputs}/{file_extension_directory?:/}... |
发生机械的字符串拼接 — outputs//Volumes/share/videos/foo.mp4 — 这通常不符合预期。 |
请根据你的实际资产归档架构，选用相匹配的场景宏组合形式。
增量继承与墓碑化移除 (Overlay merge behavior)
file_extension_directories 遵循与 environment 完全相同的逐项键值合并逻辑：
- 底板中存在、当前差异层未提及的后缀规则，将原封不动完整继承；
- 当前工程中声明的后缀规则，将直接覆盖替换底板中的同名后缀定义；
- 若显式将某个后缀的值赋予
null，代表将其墓碑化擦除 (Tombstoned)——底板中该扩展名的路由规则将被彻底废除。
# 继承底板原有的图片路由规则；将 mp4 重定向至共享视频盘；彻底废除 csv 的归档子文件夹
file_extension_directories:
mp4: "{workspace_dir}/shared/videos"
csv: null
调用方即时覆盖机制 (Caller override)
任何调用方算子节点都可以在传入的变量池中预先填入 file_extension_directory。当该值已经被显式定义时，衍生推导规则会自动跳过计算，直接使用调用方给定的路径。图形界面上的算子高级设置（例如在节点上临时指定一个特殊的输出子文件夹）正是通过这种机制绕过类型分类体系，同时依然完美复用同一个写入场景。
系统内置出厂默认映射 (What's in the defaults)
Griptape Nodes 内核出厂随附了完备的默认分流映射表，已预先将常见的图像、视频、音频、纯文本与 Python 源码后缀分别映射路由至 images、videos、audio、text 以及 python 专用子目录中。你可以随意覆盖单个条目、追加全新的自定义后缀，或通过 null 墓碑化注销任何不需要的默认规则。