跳转至

工程项目系统 (Project System)

工程项目系统 (Project System) 负责掌控创作者在 Griptape Nodes 中工作时，所有本地文件的组织归档、重命名与落盘策略。每当一个算子节点保存一张生成图、拷贝一份用户上传的素材或从远程下载 URL 媒体切片时，工程项目系统都会在底层精准裁决该文件应该落盘到磁盘的哪个具体目录中、以及应该使用何种规范命名。

为什么需要工程项目系统？ (Why it exists)

如果没有工程项目系统，用户每进行一次文件落盘或媒体读取，都必须在节点参数中手动硬编码写死绝对物理路径。这在跨机器协同、团队资产流转或大批量生成时极其脆弱。

工程项目系统使用名为 宏 (Macros) 的动态命名模板与名为 场景 (Situations) 的文件写入情景，彻底终结了硬编码路径的痛点。这使得创作者或制片主管可以在全局单一配置文件中统一制定整套工程的文件存储规范，画布上凡是涉及文件写入的每一个算子节点都会自动严格遵循该规范。

各组件层级关系剖析 (How the pieces fit together)

在本地磁盘上的典型目录结构如下：

workspace/                         ← 工作空间根目录 (所有工程与相对路径的基准锚点)
  griptape-nodes-project.yml       ← 可选：你的工程级自定义配置文件
  my_workflow/                     ← 工作流工程文件夹
    inputs/                        ← 默认的素材输入暂存目录
    outputs/                       ← 默认的渲染成果输出目录
    temp/                          ← 默认的中间过程临时目录
    .griptape-nodes-previews/      ← 默认的流式预览缩略图目录

系统的核心概念拓扑架构为：

workspace (工作空间)
  └── project template (工程模板)
        ├── situations (场景：定义各写入情景的落地路径与同名冲突策略)
        ├── directories (目录：逻辑别名 → 磁盘相对路径的映射映射表)
        ├── variables (变量：工程级变量，可在节点与宏中穿透插值替换)
        └── environment (环境：用于宏拼接组合的自定义键值对环境参数)
  • Workspace (工作空间)：当前工程所有文件操作的根物理目录。在全局偏好设置中显式配置；
  • Project template (工程模板)：治理与约束当前工程的顶层配置文件。在引擎冷启动时按序加载——首先加载引擎内置的系统出厂默认值，然后级联解析通过 parent_project_path 声明的任何 父级工程模板，最后应用当前工程自身 griptape-nodes-project.yml 中的覆盖配置。工程模板是用户掌控文件归档落盘与命名规范的核心利器；
  • Situations (场景)：对文件读取或写入特定情景的具名抽象（例如保存节点输出、导入外部素材等）。每个场景绑定了一个生成文件物理路径的宏模板，以及用于定义目标同名文件已存在时如何仲裁的冲突策略；
  • Directories (目录)：逻辑别名到物理路径的映射字典。每个目录配置持有一个短别名（例如 outputs），可以在宏模板中作为变量直接引用。该别名在磁盘上映射为真实的物理路径——出厂默认将 outputs 映射为 outputs/ 子文件夹。目录路径支持相对或绝对路径，且自身支持嵌套宏变量或系统环境变量；
  • Variables (工程变量)：归属于当前工程的强类型具名值（字符串或整数），支持在节点参数与宏模板中以 {VAR} 语法穿透替换。可将其标记为运行时可写，允许合成师在前端画布运行时动态修改，并能自动反写回写进工程配置文件中持久化；
  • Environment (环境键值)：一组可供宏模板动态引用的自定义键值对；
  • Macros (宏)：在场景与目录配置中用于动态计算生成最终具体物理文件路径的模板字符串语法。

本章文档导航 (Pages in this section)