工程定制化实战指南 (Customization Guide)

所有的定制化配置均统一集中存放在工作空间根目录下的 griptape-nodes-project.yml 文件中。你仅需声明希望做出改变的差异项——其余所有未提及的规则均会自动无损继承自系统出厂默认值。

修改默认输出目录 (`outputs`)

将所有算子节点的输出保存位置重定向至名为 renders 的文件夹：

project_template_schema_version: "0.1.0"
name: "My Project"

directories:
  outputs:
    path_macro: "renders"

此后，所有在宏模板中引用了 {outputs} 的场景都会自动保存至 renders 文件夹，而不再进入 outputs。

修改默认输入目录 (`inputs`)

project_template_schema_version: "0.1.0"
name: "My Project"

directories:
  inputs:
    path_macro: "source_files"

追加自定义逻辑目录

为向客户交付的终版资产定义专属的交付目录：

project_template_schema_version: "0.1.0"
name: "My Project"

directories:
  deliverables:
    path_macro: "client/final"

定义完成后，{deliverables} 即可作为一等公民占位符在任何场景宏模板中自由引用。

追加全新的自定义写入场景

添加一个将最终成片保存至交付目录、并在遇到重名时直接覆盖的场景：

project_template_schema_version: "0.1.0"
name: "My Project"

directories:
  deliverables:
    path_macro: "client/final"

situations:
  save_deliverable:
    macro: "{deliverables}/{workflow_name?:_}{file_name_base}.{file_extension}"
    policy:
      on_collision: overwrite
      create_dirs: true
    description: "Final deliverable for client"

覆盖修改已有系统场景

修改系统内置的 save_node_output 场景，使其在文件名中强制包含当前工作流名称：

project_template_schema_version: "0.1.0"
name: "My Project"

situations:
  save_node_output:
    macro: "{outputs}/{workflow_name:_}{file_name_base}{_index?:03}.{file_extension}"

在增量合并模型下，系统仅替换你显式书写的 macro 字段；底板中原有的 policy 策略、fallback 兜底链以及 description 描述均会被完整保留沿用。

注入自定义环境变量

集中定义用于宏模板插值计算的业务参数：

project_template_schema_version: "0.1.0"
name: "My Project"

environment:
  CLIENT_CODE: "ACME"
  SEASON: "S03"

在目录路径宏或场景宏模板中引用它们：

directories:
  outputs:
    path_macro: "{CLIENT_CODE}/{SEASON}/renders"

按扩展名自动分流归档

利用 file_extension_directories 将不同类型的文件自动归档到不同的子文件夹，而无需为每种类型单独定制场景。详细技术规范请参阅按扩展名自动分流目录。

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}"

扩展名分流同样支持宏模板。若希望将庞大的视频文件直接重定向至局域网共享盘，而其余生成物继续保留在 {outputs} 体系下，可以编写允许路由值统辖根目录的宏：

project_template_schema_version: "0.3.0"
name: "My Project"

file_extension_directories:
  png: "{outputs}/images"
  mp4: "{workspace_dir}/shared/videos"

situations:
  save_node_output:
    macro: "{file_extension_directory?:/}{node_name?:_}{file_name_base}{_index?:03}.{file_extension}"

穿透引用操作系统 Shell 环境变量

直接读取宿主操作系统中导出的系统环境变量：

project_template_schema_version: "0.1.0"
name: "My Project"

environment:
  SHARED_DRIVE: "$STUDIO_SHARED_STORAGE"

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

若操作系统的环境变量 STUDIO_SHARED_STORAGE 取值为 /mnt/studio，则 {outputs} 最终会动态解析为 /mnt/studio/renders。

综合实战完整工程配置范例

一份针对影视特效 (VFX) 生产管线的完整定制化工程文件范例：

project_template_schema_version: "0.1.0"
name: "VFX Pipeline"
description: "Customized layout for VFX production"

environment:
  SHOW_CODE: "AURORA"

directories:
  inputs:
    path_macro: "source"
  outputs:
    path_macro: "renders"
  plates:
    path_macro: "source/plates"
  deliverables:
    path_macro: "deliverables/{SHOW_CODE}"

situations:
  save_node_output:
    macro: "{outputs}/{workflow_name?:_}{file_name_base}{_index?:03}.{file_extension}"

  save_deliverable:
    macro: "{deliverables}/{workflow_name?:_}{file_name_base}.{file_extension}"
    policy:
      on_collision: overwrite
      create_dirs: true
    fallback: save_file
    description: "Final deliverable"