工作空间 (Workspace)

工作空间 (Workspace) 是创作者开展所有工程任务的根物理目录。它是底层解析与裁决所有相对文件路径的基准锚点。

配置文件层级体系 (Config files)

引擎运行时的参数配置统一记录在名为 griptape_nodes_config.json 的文件中，并在三个核心物理位置发挥作用：

文件物理路径	配置作用域与业务语义
`~/.config/griptape_nodes/griptape_nodes_config.json`	用户全局配置 (User config) — 针对当前整台宿主机的全局通用偏好基线
`<project_dir>/griptape_nodes_config.json`	工程同级配置 (Project-adjacent config) — 随工程工程文件一同分发的团队共享默认值
`<workspace_dir>/griptape_nodes_config.json`	工作空间配置 (Workspace config) — 针对当前活跃工程的个人特定本地覆盖

配置生效优先级裁决顺序 (Config resolution order)

系统按照以下层级自底向上依次加载并合并配置（后加载的配置无条件胜出覆盖前者）：

引擎内置出厂默认值 (Built-in defaults)
用户全局配置 (~/.config/griptape_nodes/griptape_nodes_config.json)
工程同级配置 (<project_dir>/griptape_nodes_config.json)
工作空间配置 (<workspace_dir>/griptape_nodes_config.json)
操作系统环境变量 (GTN_CONFIG_*)

当工作空间目录与工程所在目录恰好为同一物理路径时（独立自包含工程模式），第 3 级与第 4 级指向同一个物理文件——系统只会安全执行一次加载。

工作空间路径裁决决策流 (Workspace resolution)

当加载一个工程时，其工作空间物理根目录由以下来源严格按照优先级由高到低依次裁决——首个提供有效值的来源直接胜出判定：

工程 YAML 内部显式声明的 workspace_dir（最高优先级，详见下文）；
用户全局配置中的 project_workspaces 映射字典（按工程文件绝对路径进行本地映射）；
操作系统环境变量 GTN_CONFIG_WORKSPACE_DIRECTORY；
工程同级配置文件中的 workspace_directory 键值；
沿显式父级工程链回溯解析出的最近祖先工程的工作空间；
用户全局配置中声明的全局 workspace_directory；若皆未提供，则自动回退采用工程文件自身所在的物理文件夹（自动默认兜底）。

当工作流完全不涉及任何独立工程文件时，工作空间直接采用全局的 workspace_directory（或引擎当前工作目录下的 GriptapeNodes/ 默认子文件夹）。

按工程独立映射本地工作空间 (`project_workspaces`)

在多人协作网络中，主工程配置文件通常存放在 NAS 集中存储上。创作者可以在本机的用户全局配置中利用 project_workspaces 将远端工程映射到本机的私有本地 SSD 上：

{
  "project_workspaces": {
    "//NAS/Projects/ProjectA/griptape-nodes-project.yml": "/Users/collin/ProjectA/",
    "//NAS/Projects/ProjectB/griptape-nodes-project.yml": "/Users/collin/ProjectB/"
  }
}

字典的键为工程 YAML 文件的绝对解析路径。当引擎加载该工程时，如果命中键名，便会自动将其工作空间重定向至对应的本地路径。

工程级显式声明工作空间 (`workspace_dir`)

工程可以通过自身的 workspace_dir 字段将工作空间物理路径直接硬绑定。这是优先级最高的工作空间来源：它能够无条件覆盖用户的 project_workspaces 映射、覆盖环境变量、覆盖工程同级配置以及全局默认值。

在创建 v1 版本的现代工程时，系统会自动在 YAML 中写入 workspace_dir: "./"，这意味着 v1 工程天然是高度自包含的便携式工程——其工作空间即为其自身所在的文件夹。

该字段既可以是一个纯路径，也可以是跨操作系统的平台字典映射：

# 相对路径：基于当前工程 YAML 文件所在的物理文件夹解析
workspace_dir: "./workspace"

# 或跨操作系统平台适配字典：
workspace_dir:
  darwin: "/Volumes/fast/ProjectA"
  windows: "D:/ProjectA"
  default: "./workspace"

基于工程目录的相对路径赋予了工程完美的便携性：无论是将工程文件夹打包压缩拷贝给同事，还是上传至云端渲染农场，工作空间均会始终如影随形、自洽解析。

典型企业与个人实战场景剖析 (Example scenarios)

场景 1：单兵独立开发，无工程定义文件

无需维护任何工程 YAML。工作空间直接采用用户全局配置中的 ~/GriptapeNodes。

场景 2：便携式绿色自包含工程 (Portable Project)

工程 YAML 与配置文件并排存放在同一目录下，工作空间默认就是该目录本身。无论将工程复制到 U 盘还是移至其他机器，双击即可无缝工作，无需任何配置修改。

场景 3：集中式网络工程，本地分布式工作空间

工程文件位于 //NAS/Projects/ProjectA/griptape-nodes-project.yml。Collin 在 Mac 上将其映射为 /Users/collin/ProjectA/；James 在 Windows 上将其映射为 C:\Projects\ProjectA\。两位艺术家各自在本地享受高速本地磁盘读写，同时共享 NAS 上的集中配置与资产规范。

场景 4：影视工作室集中管线管控

工程同级配置文件直接硬编码共享工作空间 workspace_directory: //NAS/Workspaces/ProjectA/。所有未在本地单独配置的合成师自动走 NAS 集中管线；而云端无界渲染农场节点可通过 GTN_CONFIG_WORKSPACE_DIRECTORY 环境变量将其临时重定向到挂载点，无需污染 NAS 原生配置。

场景 5：开发者本地调试日志级别覆盖

工作室统一在工程同级配置中推行 log_level: "WARNING"。算法工程师本地开发需要深入排查，在个人的本地工作空间配置中写入 {"log_level": "DEBUG"}——由于工作空间配置（第 4 层）优先于工程同级配置（第 3 层），调试日志仅对该开发者一人开启，绝不波及团队其他人。

相对路径的底层解析裁决规则 (How paths resolve)

工作流内部的相对路径：工作流中的所有相对文件路径、宏解析产物，均基于工作空间目录 (Workspace Directory) 进行解析。若你的工作空间为 /Users/you/workspace/，场景宏解出的相对路径为 outputs/render_001.png，最终的绝对磁盘地址即为 /Users/you/workspace/outputs/render_001.png。
工程 YAML 内部书写的相对路径：工程 YAML 文件中书写的相对路径（例如 workspace_dir: ./workspace 或 parent_project_path），始终基于工程 YAML 文件本身所在的物理文件夹解析。
第三方算子库路径的例外：第三方库默认存放在工作空间相对路径下的 libraries 目录中，但工程可以通过 libraries_dir 字段将其独立重定向至高速共享盘，使其脱离工作空间的羁绊。
工程基准目录 ({project_dir})：存放 griptape-nodes-project.yml 的物理文件夹被暴露为系统内置变量 {project_dir}，主要充当资产回溯映射与元数据索引的兜底参考。

核心配置项速查汇总 (Summary)

配置项 / 来源	优先级与核心职能
`workspace_dir` (工程 YAML 内)	最高优先级。工程自我声明的自包含工作空间；超越一切本地映射与环境变量。
`GTN_CONFIG_WORKSPACE_DIRECTORY`	环境变量。适合 CI/CD 自动化构建与无头渲染农场会话接管。
`<workspace_dir>/griptape_nodes_config.json`	工作空间配置。创作者本地私有覆盖项，随特定工作流生效。
`<project_dir>/griptape_nodes_config.json`	工程同级配置。项目主管随工程模板分发的团队规范基线。
`project_workspaces` (全局配置内)	多工程路由映射。将不同的网络工程定向到不同的本地 SSD 磁盘。
`workspace_directory` (全局配置内)	用户全局默认值。未显式配置工程时的兜底通用工作空间。