目录映射规范 (Directories)

目录映射规范 (Directories) 是指将一个人类可读的逻辑名称映射为具体的磁盘物理路径。你无需在工程的各处宏模板与节点参数中硬编码诸如 outputs/renders 之类的物理路径，而是为其赋予一个统一的具名别名（例如 outputs），并在宏模板中直接引用该别名。后续若需要迁移输出路径，只需在单一配置中心修改该目录的映射定义即可全局即时生效。

---

系统内置的预置目录 (Default directories)

系统出厂默认定义了六大基准目录：

逻辑目录别名	默认相对路径	业务语义与存储场景
inputs	inputs	引入工程的外部素材资产——包含上传文件、复制素材与网络下载的切片。
outputs	outputs	工作流执行调度期间，由算子节点渲染生成并最终持久化落盘的文件。
temp	temp	运行时临时暂存碎片文件；在两次生成之间或会话重启时可安全清空擦除。
griptape-nodes-previews	.griptape-nodes-previews	生成的预览缩略图与流式代理切片；物理路径镜像复刻源文件的目录层级树。
griptape-nodes-metadata	.griptape-nodes-metadata	为工程资产生成的伴生 Sidecar 元数据文件；物理路径镜像复刻源文件层级。
griptape-nodes-thumbnails	.griptape-nodes-thumbnails	在工程浏览器界面中呈现的工作流卡片封面主缩略图。

所有系统内置目录出厂时均采用相对路径，默认基于当前工程的基准目录进行相对解析。

---

在宏模板中引用目录别名

任何已定义的目录别名，均可直接作为具名变量嵌入在宏模板中。当宏被引擎解析时，工程系统会自动将该目录别名替换为其绑定的具体磁盘物理路径：

模板字符串:  {outputs}/{file_name_base}.{file_extension}
             ↓
解析落地路径: outputs/my_image.png

创作者无需手动向宏传递这些目录值——它们完全由系统底层自动注入。所有目录别名均为系统绝对保留字：如果你试图向宏中传递一个与目录重名的自定义变量，系统会明确阻断并抛出异常，以杜绝歧义覆盖风险。

---

自定义修改目录物理路径

在你的 griptape-nodes-project.yml 配置文件中即可轻松重写默认目录：

project_template_schema_version: "0.1.0"
name: "My Project"

directories:
  outputs:
    path_macro: "renders/final"

配置生效后，工程内所有宏模板中的 {outputs} 都会自动解析为 renders/final，彻底替换出厂默认的 outputs。

---

目录注释描述 (Directory descriptions)

每个目录定义均支持附加可选的 description 字段——用纯文本向团队阐述该目录的设立初衷与资产规范。这些说明会直接呈现在工程图形化管理视窗中，使手写维护的 YAML 拥有极高的可读性：

directories:
  outputs:
    path_macro: "renders/final"
    description: "准备直接向客户正式交付的最终成品渲染序列帧。"

description 为可选字段，缺省默认值为 null。若希望在当前子模板中清空从基础模板或父级工程继承而来的旧注释，显式将其声明为 null 即可：

directories:
  outputs:
    description: null

---

追加扩展新目录 (Adding new directories)

如果预置的六个目录无法满足复杂的生产管线，你可以自由追加全新的目录别名：

directories:
  deliverables:
    path_macro: "client_deliverables"

一旦声明成功，{deliverables} 即可作为标准变量在所有宏模板与场景中随意插值。

---

在目录路径中使用宏与环境变量

path_macro 字段不仅支持常规相对路径，还全面支持波浪号（~）主目录展开、宏变量插值以及系统环境变量穿透：

directories:
  downloads:
    path_macro: "~/Downloads"

该配置会将 downloads 逻辑目录自动映射到当前操作系统的用户下载文件夹，抹平不同操作系统的底层绝对路径差异。

directories:
  outputs:
    path_macro: "$OUTPUT_BASE/renders"

如果操作系统或工程 environment 代码块中定义了 $OUTPUT_BASE，路径在动态解析时会自动读取并替换该环境变量。

你甚至可以在目录配置中引用引擎系统内置变量：

directories:
  outputs:
    path_macro: "{workflow_dir}/renders"

这使得 outputs 渲染目录不再锚定在工程根目录下，而是自动紧随当前正在执行的工作流 .py 脚本所在的子文件夹动态就地生成。

---

跨操作系统多平台路径适配 (Per-platform paths)

在工业级生产环境中，团队成员往往横跨 Linux、macOS 与 Windows。当需要将共享存储或本地高速缓存挂载在不同系统上时，path_macro 允许声明为按操作系统分流的字典映射：

directories:
  scratch:
    path_macro:
      linux: "/mnt/fast-scratch"
      darwin: "/Volumes/scratch"
      windows: "D:/scratch"
      default: "{workspace_dir}/scratch"

在运行时，引擎会自动探测当前操作系统的内核平台标识（linux、darwin 或 windows）。若当前平台在字典中未显式声明，则自动回退至 default 兜底项。这四项键名中必须至少显式声明一项，否则工程模板在加载校验时会报错。

directories:
  models:
    path_macro:
      darwin: "~/Library/Caches/models"
      default: "{workspace_dir}/.models"

多平台路径内部同样完整支持波浪号展开、环境变量插值与宏替换语法。

继承覆盖时的原子替换特性

在多层父子工程继承合并时，平台字典具备原子替换特性 (Atomic Replacement)：子模板中声明的平台字典会完全覆盖替换父级工程中的整个 path_macro 块，而不会按键逐个合并。若想在重写某一系统的路径时保留其他系统的值，请在子模板中完整列出需要保留的所有平台键值。

---

系统保留字与命名冲突防御 (Reserved names)

所有目录别名在全局变量命名空间内均受到严格的保留字保护。你绝不能在宏计算调用中传入与目录别名同名的自定义变量——若发生碰撞，系统会抛出明确异常拦截。这从根本上杜绝了因变量名命名冲突而不慎篡改物理存储目录的灾难性隐患。

此外，系统内置常量变量（project_dir、workspace_dir、workflow_name、workflow_dir、static_files_dir）同样属于严禁篡改的系统绝对保留字，详见 环境与系统内置变量手册。