跳转至

资产与多媒体输出管理 (Assets and Outputs)

当工作流中的算子节点生成图像、渲染视频、合成音频或输出任何其他格式的文件时，这些生成资产必须精准落盘并能够被前端编辑器安全访问，以便用户在画布上即时预览缩略图并一键下载。

本文档深入解析生成文件的落盘路径规划机制、自定义存储规则，以及如何将外部素材文件（通过文件选择器或拖拽）安全载入工作流体系中。

生成文件的落盘寻址机制 (Where generated files go)

Griptape Nodes 的算子节点绝不会向硬编码的静态物理路径写入文件。每一次磁盘落盘均统一交由当前活动的 项目系统 (Project) 托管调度：项目系统定义了一组语义化的命名物理目录（如 inputs、outputs、temp 等），并定义了一系列被称为 场景策略 (Situations) 的文件持久化规则，由其动态决定特定类型的文件应当落入哪一个目录、遵循何种命名规范以及如何处理重名冲突。

在系统默认项目模板下，落盘规则如下：

  • 节点生成的最终产物（如生成的 AI 图片、渲染导出的视频、合成的音频语音）：统一通过 save_node_output 场景策略托管，自动落入项目工程的 outputs 目录；
  • 从外部导入的参考素材（从电脑外部拖拽至画布或通过文件选择器复制的文件）：统一通过 copy_external_file 场景策略托管，自动归档至项目工程的 inputs 目录；
  • 节点运算期间生成的临时暂存切片（用于多步计算且在结束后自动销毁的中间临时文件）：统一落入 temp 目录；
  • 前端编辑器生成的缩略图与即时预览缓存：自动存放在隐藏的 .griptape-nodes-previews 与 .griptape-nodes-thumbnails 缓存文件夹中。

上述物理路径均未在底层执行引擎中硬编码——它们全部派生自主工程项目配置。项目配置文件可以轻松将上述任何目录重定向至不同的存储介质（如局域网共享盘、项目特定子目录或根据跨平台操作系统动态切换路径），并自定义文件重名时的覆盖或自动递增序号策略。

详见： - 语义化目录完全参考 (Directories) —— 探索所有命名目录的规范与配置； - 落盘场景策略技术手册 (Situations) —— 了解各类文件生成时的保存规则； - 项目系统工程指南 (Project) —— 定制属于团队专属的项目模板。

编辑器如何实现文件预览与高速下载？

当后端执行引擎需要向用户呈现生成的多媒体成果或支持一键下载时，它绝不会将本地操作系统的裸物理文件路径直接抛给前端浏览器，而是通过受控的 HTTP 协议生成专用的安全访问 URL：

  • 针对工作区内部的文件：通常直接生成指向本地内置轻量静态文件服务器的高速直链（默认形如 http://localhost:8124/workspace/...）；
  • 针对工作区外部的文件、file:// 协议路径或使用了动态路径宏的文件（例如 {outputs}/render.png）：引擎会在收到请求时动态签发一个具备时效性的、受安全签名保护的临时下载 URL。

在这两种机制下，通信流程高度标准化：前端编辑器向引擎请求多媒体 URL，引擎在底层将该相对抽象路径解析到真实落盘物理位置，浏览器随后通过该 URL 异步拉取流式渲染数据或触发文件保存。这些 URL 完全由系统按需动态签发，生命周期极短，且严禁在工作流会话之外对外长久传播。

提示：关于 staticfiles 目录
你可能会在工作区根目录下留意到一个名为 staticfiles 的文件夹（其确切名称由系统的 static_files_directory 配置项决定）。这是历史早期旧版本节点所采用的传统存储路径。现代官方算子库中的绝大多数节点均已全面拥抱上述基于项目系统的模块化目录标准；仅在显式调用引擎底层静态文件 API 时，文件才会降级写入该文件夹。

向工作流中导入外部素材文件 (Uploads & Drag-and-Drop)

将外部参考素材（如垫图参考照片、原声视频素材、长文本语料）导入工作流的过程，在底层实际上是上述下载机制的反向镜像操作：

当你将本地电脑上的文件直接拖拽到某个算子节点上，或点击节点的文件选择器选中文件时，前端编辑器会自动将该文件上传并注入到项目系统中。文件在后端的实际归档位置完全由项目的 copy_external_file 场景策略统一裁决：

在默认项目规范下： 1. 文件被自动复制保存至项目工程的 inputs 目录下； 2. 若文件格式能够被系统自动识别，它会被智能分类存入对应的子文件夹中（如 images/、videos/、audio/、text/）； 3. 若目录下已存在同名文件，系统默认绝不会执行无脑覆盖，而是自动在文件名末尾追加自增序号后缀（例如 photo_001.png），确保历史输入资产的安全。

在底层架构上，前端浏览器与本地文件系统之间严格遵守两步安全交接协议：前端编辑器首先向后端引擎申请一个一次性的安全上传 URL，随后通过 HTTP PUT 请求将文件的二进制字节流传输注入到该端点中。

延伸阅读