引擎与算子库版本锁定 (Version Pinning)

本文档面向需要对外分发工程项目、且必须确保该工程严格运行在已知受信任的引擎内核版本与已知受信任的第三方算子库集合下的系统管理员或技术主管。

版本锁定机制将工程项目本身确立为单一真实信任源 (Single Source of Truth)：当用户激活该工程时，如果宿主机运行的引擎内核版本不兼容，引擎将严格拒绝运行；并自动将项目声明的所有算子库精准调配至锁定的版本。

配置文件存放规范

所有的版本锁定配置均存放于工程同级配置文件 (Project-Adjacent Config) 中——即紧邻工程 griptape-nodes-project.yml 放置的 griptape_nodes_config.json 文件。工程 YAML 本身不承载版本数据，全部交由同级 JSON 配置文件接管：

/MyProject/
  griptape-nodes-project.yml      <- 工程定义文件 (此处不写版本锁定)
  griptape_nodes_config.json      <- 引擎内核与算子库版本锁定声明在此处

请务必将这两个文件打包一同分发。由于工程同级配置的加载优先级高于用户的全局配置、但低于特定工作空间配置，因此你的版本锁定规则会对激活该工程的所有创作者无感生效，同时又不会污染他们机器全局的软件环境。

锁定引擎内核版本 (Pin the engine version)

在配置中将 requires_engine 声明为符合 PEP 440 版本规范的表达式。当工程被激活时，正在运行的引擎内核版本必须严格满足该约束，否则激活将被系统强行阻断：

{
  "app_events": {
    "on_app_initialization_complete": {
      "requires_engine": ">=0.80,<1.0"
    }
  }
}

版本表达式会与当前正在运行的引擎版本进行比对；
若发生版本不匹配，系统会阻断工程激活：工程拒绝加载，并在界面上向用户明确展示当前运行的内核版本与工程所要求的版本范围；
省略该键（或显式设为 null）将完全跳过引擎版本校验。

强烈建议使用带闭合上限的有界区间（如 >=0.80,<1.0）而非无界的开区间，以防工程在未来发生重大底层架构变更的引擎主版本下因静默激活而崩溃。

锁定算子库版本 (Pin library versions)

libraries_to_download 数组集中声明了引擎在工程激活时代为拉取纳管的算子库列表。每一项既可以是裸 Git URL 字符串（传统行为：从源码克隆，不强加版本约束），也可以是一个结构化的版本锁定对象：

{
  "app_events": {
    "on_app_initialization_complete": {
      "libraries_to_download": [
        {
          "name": "Griptape Nodes Library",
          "version": "==0.79.0",
          "git_url": "griptape-ai/griptape-nodes-library-standard@v0.79.0"
        }
      ]
    }
  }
}

字段名称	是否必填	语义与规范说明
`git_url`	是	形式为 `url@ref` 的 Git 源：完整 Git URL 或 `user/repo` 简写，可附带可选的 `@branch\\|tag\\|commit` 后缀。若省略 `@ref`，则默认拉取仓库的主分支。
`version`	否	已安装算子库必须满足的 PEP 440 版本约束表达式（例如 `==0.79.0`、`>=1.2,<2`）。省略此项则仅按 Git 源码引用锁定。
`name`	否	算子库元数据清单中声明的 `name` 别名。提供此项时，系统会优先按名字比对已安装的副本以决定是否需要重新下载。

建议将 git_url 的 Git Ref 引用与 version 版本号同时精准锚定至同一发行版（例如 @v0.79.0 搭配 ==0.79.0），确保代码克隆源与版本校验绝不发生漂移脱节。

破坏性覆盖仅针对已下载库

libraries_to_download 中声明的库，是引擎为了满足版本锁定唯一允许就地物理覆盖的算子库类型。而仅仅被注册挂载的本地开发库（在 libraries_to_register 中通过绝对路径引入的库）永远保持原样加载，绝对不会被工程激活破坏性覆盖。因此若希望工程拥有强制收敛版本的能力，必须将其声明在下载列表中。

下载成功后，引擎会自动将解析出的清单路径追加至注册列表中，无需手动在 libraries_to_register 中重复配置。

算子库物理落盘路径

libraries_to_download 决定了安装什么以及强制锁定在哪个版本；
工程 YAML 中的 libraries_dir 决定了这些库在磁盘上的物理存放根目录。

二者有机组合：若工程未声明独立的 libraries_dir，下载项默认存放在工作空间相对路径下的 libraries 目录中。而在大型工程树中，所有子工程可以共享父级工程的 libraries_dir，从而实现父级下载一次后所有子项目全局秒级复用，杜绝重复下载占用磁盘。

激活阶段的生命周期与审计决策树

当创作者在前端激活一个包含版本锁定的工程时，引擎会严谨比对 libraries_to_download 中的每一项与本地已安装的实体状态，并生成一份裁决计划：

决策执行动作	触发判定条件	实际产生的影响
SKIP (跳过)	本地已安装的版本已经完美满足版本锁定约束	状态完好，不产生任何网络或磁盘变动。
INSTALL (安装)	本地尚未安装该算子库	从远端安全克隆锁定的源。非破坏性操作。
OVERWRITE (破坏性覆盖)	本地已存在该库，但版本不满足当前约束（例如版本过旧或过新）	将本地该库的目录彻底物理擦除并重新克隆目标版本。具有物理破坏性。

在执行任何可能带来数据丢失的 OVERWRITE 操作之前，编辑器会自动弹出一份只读的操作预检预览清单 (Plan Preview)，必须等待创作者手动确认授权后方可执行。若用户拒绝授权，系统会安全回退为无害空操作：维持先前的工程激活状态，磁盘文件丝毫未损。若此时检测到引擎内核版本不匹配，弹窗中会直接置灰并禁止授权。

完整生产级实战范例

要求引擎内核必须满足 >=0.80,<1.0 且将标准算子库强锁定至 0.79.0 的工程配置：

/MyProject/griptape-nodes-project.yml：

"project_template_schema_version": "1.0.0"
"name": "my-pinned-project"
"description": "严格运行在 0.80-0.x 引擎内核上，且标准算子库强锁定为 0.79.0 的工程项目。"

/MyProject/griptape_nodes_config.json：

{
  "app_events": {
    "on_app_initialization_complete": {
      "requires_engine": ">=0.80,<1.0",
      "libraries_to_download": [
        {
          "name": "Griptape Nodes Library",
          "version": "==0.79.0",
          "git_url": "griptape-ai/griptape-nodes-library-standard@v0.79.0"
        }
      ]
    }
  }
}

激活执行流：

内核版本校验：若运行中的引擎内核版本不在 >=0.80,<1.0 区间内，立即弹窗阻断激活；
全新机器首次运行：本地未发现标准库，裁决为 INSTALL：拉取并注册 v0.79.0；
二次激活：已就绪且版本相符，裁决为 SKIP；
版本漂移情况：若其他工程此前将该库升级为了 0.80.0，此时不满足 ==0.79.0，系统判定为 OVERWRITE：弹出风险预检弹窗，经用户审批后自动清理重装为 0.79.0。

运维避坑指南 (Notes and gotchas)

纯字符串简写仍然受支持：传统的 "libraries_to_download": ["user/repo"] 纯字符串列表仍然被兼容，它会从源码克隆但不执行版本强校验；只有对象形式才会激活强校验。
本地工作空间配置拥有更高优先级：创作者本地工作空间配置的加载优先级高于工程同级配置（详见工作空间配置层级手册）。如果用户在本地显式声明了同名覆盖，以用户本地设置优先；工程同级配置本质上是随项目分发的一套强规范推荐基线。
无界面 CLI 自动化运维：在没有图形化界面的云端渲染农场或 CI/CD 流水线上，管理员可通过终端命令执行同步：gtn libraries download <git_url> 与 gtn libraries sync，详见命令行工具参考。