图形化工程项目管理 (Managing Projects in the GUI)

工程项目 (Project) 是一套已保存的全局配置预设，用于指示 Griptape Nodes 如何落盘管理物理资产、以及使用何种引擎内核版本与第三方算子库。

切换工程会立即整体切换当前会话的上下文环境：包含渲染图像与下载文件的存储位置、工程浏览器中呈现的工作流清单，以及画布上可用的算子库生态。

本文档系统介绍在图形化界面 (GUI) 中纳管工程的全流程操作：切换工程、创建新工程、查看与编辑工程细节、注销工程以及工程的打包导入与导出。关于底层的配置语法与宏模板原理，请参阅工程项目系统概览。

本文档所述的所有图形化操作均在 Project Management (工程管理) 视窗中进行。从顶部菜单栏选择 Manage → Project Management 即可唤出。

工程管理视窗概览 (The Project Management window)

Project Management 视窗默认停留在 Project List (工程列表) 视图。工程以树状结构呈现：子工程会层级缩进嵌套在父级工程下方。你当前正在使用的工程会明确打上 Active (活跃) 状态徽标。

包含活跃工程与嵌套子工程的列表视图

右上角常驻两个操作按钮：

Register Template… (注册已有工程模板)：直接指向磁盘上已经存在的 griptape-nodes-project.yml 文件并将其登记入列表；
Create New Template… (创建全新模板)：从零开始引导式创建一份全新的工程项目。

点击列表中任意工程的行卡片即可进入其详细视图，查看、修改并校验其各项配置。

极速切换工程 (Switching projects)

切换工程是日常最频繁的高频操作。除了在工程管理视窗中选中工程点击 Activate (激活) 外，最快捷的途径是使用工作流选择器中的 工程快速切换下拉框 (Project Picker)：

下拉框中实时显示当前活跃的工程名称。点击展开可快速模糊检索并一键选中目标工程；当前处于激活状态的工程右侧标有清晰的对勾。

工作流选择器中的工程快速切换下拉列表

选择新工程后，系统会弹出确认对话框，明确展示你正在离开的旧工程与即将迁入的新工程。

切换工程确认弹窗

切换工程会触发引擎热重载：你当前打开的工作流会被安全关闭（若存在未落盘的编辑改动，系统会预先提示你保存）；随后工作流浏览器会自动刷新，仅展示属于新工程的工作流工程列表。

若即将迁入的新工程包含强制的第三方算子库版本锁定，系统会首先弹出一份版本调配预览清单 (Provisioning Preview)，列出即将安装、升级或清理的库，待你审批确认后方开始切换。

算子库调配与版本锁定确认预检界面

界面随后显示进度指示器，切换完成后弹出绿色的成功气泡提示。

创建全新工程模板 (Creating a project)

点击 Create New Template… 唤起配置弹窗。对于绝大多数常规项目，创作者通常只需填写工程名称即可，其余所有项均配置了工业级合理的默认值。

新建工程模板配置对话框

顶部副标题会标注保存上下文（如 "Creating a new project template inside Default Project"）。点击高亮名称可自由指定该工程的父级工程归属。

基础配置项：

Project Name (工程名称)：在界面全局展示的人类可读显示名。这是唯一的必填字段；
Description (工程描述)：可选备注文档，阐述该工程的资产规格与用途；
Location (磁盘落盘路径)：指定 griptape-nodes-project.yml 物理文件的落盘位置。默认会自动以你的工程名称在所选路径下新建文件夹；点击文件夹图标可浏览自定义路径。

高级设置 (Advanced Settings)

展开 Advanced Settings 抽屉可深度配置底层属性：

Project ID (工程全局唯一物理 ID)：工程在底层的物理标识符。默认根据工程名称拼接随机短哈希生成。创建完成后该 ID 永久固化不可篡改；
Inherits settings from (继承自父级工程)：声明父工程。子工程会自动继承父工程的所有配置，且仅需在自身 YAML 中保存特异性的差异覆盖项。若无需继承，此处选择 Default Project 即可；
Workspace directory (工作空间物理目录)：该工程存放工作流与渲染生成资产的根目录。现代 v1 工程默认为 ./（即工程自身所在目录），形成完美的自包含绿色工程。

点击 Create。系统会自动完成文件落盘、引擎注册与热重载激活。

审查与深度编排工程配置 (Viewing and editing a project)

在工程列表中点击任意工程进入其详情面板。顶部页眉清晰呈现工程名、物理文件绝对路径（带有一键复制按钮），以及 Active 与 Unsaved changes 状态胶囊。

点击名称旁的铅笔图标可直接原地行内编辑工程的名称与描述。详情面板集中组织了该工程的所有核心模块：

1. Workspace dir (工作空间目录)

明确指定当前工程的工作空间根目录。若留空，输入框会以灰色占位符文本呈现由引擎全局推算出的计算路径，直观展示文件最终会落盘到何处。支持按操作系统一键展开 Linux、macOS 与 Windows 分流配置。

2. Libraries dir (第三方算子库目录)

将算子库的物理落盘目录独立于工作空间重定向至高速 SSD 或共享网络盘。留空则自动继承父工程的配置。

3. Directories (逻辑目录映射)

在此处集中为各个业务阶段定义逻辑目录别名（如 outputs、deliverables 等），支持按操作系统展开多平台适配，详见目录映射规范。

4. File Extension Directories (按后缀分流)

配置按文件扩展名自动分流归档的规则（例如将 .png 自动路由至 images/，将 .exr 自动路由至 renders/），详见按扩展名自动分流目录。

5. Environment (自定义环境变量)

定义归属于该工程的自定义键值对环境参数，供宏模板动态插值引用，详见环境与系统内置变量。

6. Situations (文件写入场景)

集中维护与定制具名的写入场景模板与冲突仲裁策略，详见写入场景与冲突策略。

顶部工具栏与生命周期操作

详情面板顶部常驻核心操作工具条：

Validate (静态校验)：在不保存的前提下，全面探测当前修改是否存在语法错误或命名二义性冲突；
Reload from Disk (从磁盘重新加载)：放弃当前视窗中的所有未保存草稿，强制重新从本地磁盘读取物理文件；
Save Changes (保存更改)：将所有编辑持久化刷盘写入工程 YAML；
Upgrade schema (升级工程架构规范)：仅在当前工程使用的是旧版 Schema（例如 0.x）时显式激活。升级会将工程平滑 Re-base 到引擎最新的规范体系上，系统会弹出风险确认弹窗告知潜在的影响。

注册已有工程与安全注销

注册工程：在工程列表点击 Register Template…，浏览并选中现有的 griptape-nodes-project.yml 即可完成登记；
注销工程：在工程详情页或列表行中点击垃圾桶图标，在弹出的确认框中确认。注销操作仅是从列表中解绑注销该工程，绝对不会物理删除磁盘上的任何工程文件与素材。后续随时可以通过 Register Template 重新找回。

工程资产的一键导出与导入 (Exporting and importing projects)

你可以将整套工程无缝打包封装为单一的 .zip 压缩归档文件，方便跨机器分发交付或备份归档。打包产物内聚了工程定义 YAML 与其强依赖的所有算子库，接收方解压后无需繁琐的配置即可开箱即用。

API Key 等敏感凭证绝不随包外泄

为了绝对的安全防护，模型 API Key 与密码等敏感凭据绝不会被打包进 zip 压缩包中。包内仅记录凭证的键名。接收方在导入工程后，系统会自动列出缺失的密钥清单，由接收方在自己的设置面板中单独填入。

导出工程 (Exporting)

在列表中点击工程行上的包裹图标，指定本地保存路径，系统会自动生成 <project-name>.zip 资产包，并在弹窗中清晰提示该工程依赖的凭据清单。

导入工程 (Importing)

点击列表右上角的 Import Project… 并选中 .zip 资产包。解压前，系统会呈现解包清单：展示工程原名、支持就地重命名防止冲突、展示随附的算子库列表以及运行该工程所需的 API 环境变量列表。确认解压路径后一键导入，随后即可在工程选择器中激活使用。

系统内置的只读基准：Default Project

Griptape Nodes 出厂时常驻一个内置的 Default Project (默认工程)。它是严格只读受保护的：你可以随时查看其设计规范，但严禁就地修改或覆盖。当全局没有任何其他活跃自定义工程时，系统会自动以此默认工程作为运行基线。