엔진 및 라이브러리 버전 고정 (Pinning engine and library versions)

이 가이드는 프로젝트를 배포하고 검증된 엔진 버전 및 검증된 라이브러리 버전 세트에서 프로젝트가 실행되도록 해야 하는 관리자를 위한 것입니다. 버전 고정(Pinning)을 사용하면 프로젝트가 신뢰할 수 있는 단일 소스(Source of truth)가 됩니다. 사용자가 프로젝트를 활성화할 때 호환되지 않는 버전에서는 엔진 실행이 차단되고 고정된 각 라이브러리를 프로젝트가 선언한 버전으로 프로비저닝합니다.

두 고정 설정은 모두 프로젝트 인접 설정(project-adjacent config)인 프로젝트의 griptape-nodes-project.yml 옆에 위치한 griptape_nodes_config.json에 저장됩니다. 프로젝트 YAML 자체에는 버전 데이터가 포함되지 않으며 인접 구성에 포함됩니다. 이 파일이 사용자 설정 위에 어떻게 계층화되는지에 대해서는 워크스페이스를 참조하세요.

/MyProject/
  griptape-nodes-project.yml      <- 프로젝트 (여기에는 버전 고정이 없음)
  griptape_nodes_config.json      <- 엔진 + 라이브러리 고정 설정이 여기에 위치함

두 파일을 함께 배포하세요. 인접 설정은 사용자의 전역 설정보다는 상위에, 워크스페이스 설정보다는 하위에 계층화되므로 고정 설정이 사용자의 시스템 전체 설정에 영구적으로 반영되지 않으면서 프로젝트를 활성화하는 모든 사용자에게 적용됩니다.

엔진 버전 고정

requires_engine을 PEP 440 버전 지정자로 설정합니다. 프로젝트가 활성화될 때 실행 중인 엔진의 버전이 지정자를 충족해야 하며, 그렇지 않으면 활성화가 차단됩니다.

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

지정자는 실행 중인 엔진의 버전과 비교됩니다.
불일치 시 활성화가 차단됩니다. 프로젝트가 로드되지 않으며 실행 중인 버전과 요구되는 버전을 알리는 메시지가 사용자에게 표시됩니다.
엔진 검사를 완전히 건너뛰려면 키를 생략하거나 null로 설정하세요.

동작이 변경될 수 있는 향후 메이저 엔진 릴리스에서 프로젝트가 암묵적으로 활성화되지 않도록 개방형 하한선 대신 범위가 제한된 범위(>=0.80,<1.0)를 사용하세요.

라이브러리 버전 고정

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 소스입니다. 전체 URL 또는 `user/repo` 축약형이며 선택적으로 `@branch\\|tag\\|commit` 접미사를 가집니다. `@ref`가 없으면 저장소의 기본 브랜치를 사용합니다.
`version`	아니오	설치된 라이브러리가 충족해야 하는 PEP 440 지정자입니다(예: `==0.79.0`, `>=1.2,<2`). 소스로만 고정하려면 생략합니다.
`name`	아니오	라이브러리의 매니페스트 `name`입니다. 설정된 경우 재다운로드가 필요한지 결정하기 위해 설치된 사본을 이름으로 일치시킵니다.

클론하는 소스와 강제하는 버전이 서로 달라지지 않도록 git_url 참조와 version을 모두 동일한 릴리스로 고정하세요(예: @v0.79.0 및 ==0.79.0).

다운로드된 라이브러리만 덮어씀

libraries_to_download에 나열된 라이브러리만이 고정 조건을 충족하기 위해 엔진이 덮어쓰는(overwrite) 유일한 종류입니다. 단순히 등록만 된 라이브러리(경로별로 libraries_to_register에 나열됨)는 있는 그대로 로드되며 프로젝트 활성화에 의해 절대 덮어쓰이지 않습니다. 프로젝트가 라이브러리 버전을 강제할 수 있도록 하려면 등록 목록뿐만 아니라 다운로드 목록에도 라이브러리가 있어야 합니다.

라이브러리를 libraries_to_register에도 추가할 필요는 없습니다. 다운로드가 성공한 후 엔진이 확인된 매니페스트 경로를 등록 목록에 자동으로 추가하므로 다운로드 후 로드 체인이 자체적으로 작동합니다.

다운로드 저장 위치

libraries_to_download는 설치할 대상과 버전을 정의하며, libraries_dir(프로젝트 YAML의 필드)은 해당 라이브러리가 설치되고 확인되는 위치를 정의합니다. 두 설정이 조합되어 고정된 각 다운로드가 프로젝트의 확인된 라이브러리 디렉터리에 프로비저닝됩니다. 프로젝트가 libraries_dir을 선언하지 않은 경우(부모로부터 상속받지도 않은 경우) 다운로드는 워크스페이스 기준 libraries 디렉터리에 저장됩니다. 프로젝트 트리 전체에서 공유되는 libraries_dir을 사용하면 부모가 한 번 다운로드한 고정 라이브러리를 모든 자식이 다시 다운로드하지 않고 재사용할 수 있습니다.

활성화 시 일어나는 일

사용자가 고정된 프로젝트를 활성화하면 엔진은 각 libraries_to_download 항목을 설치된 항목과 비교하고 다음 중 하나를 계획합니다:

계획	조건	결과
SKIP	설치된 버전이 이미 고정 조건을 충족함	아무것도 변경되지 않습니다.
INSTALL	라이브러리가 아직 설치되지 않음	고정된 소스를 클론합니다. 비파괴적(Non-destructive) 작업입니다.
OVERWRITE	조건을 충족하지 않는 다른 버전이 설치되어 있음	로컬 라이브러리 디렉터리를 삭제하고 고정 버전을 다시 클론합니다. 파괴적(Destructive) 작업.

파괴적인 OVERWRITE가 실행되기 전에 편집기는 전체 계획의 읽기 전용 미리보기(preview)를 표시하고 사용자가 승인할 때까지 대기합니다. 거부하면 안전하게 아무 작업도 수행하지 않으며, 이전 프로젝트가 활성 상태로 유지되고 라이브러리 파일은 변경되지 않습니다. 또한 미리보기는 엔진 버전 불일치(requires_engine)를 보고하며 실행 중인 엔진이 고정 조건을 충족할 수 없는 경우 승인을 차단합니다.

구체적인 예시

엔진 >=0.80,<1.0을 요구하고 표준 라이브러리를 0.79.0으로 고정하는 프로젝트:

/MyProject/griptape-nodes-project.yml

"project_template_schema_version": "1.0.0"
"name": "my-pinned-project"
"description": "Runs on engine 0.80-0.x with the standard library pinned to 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이 클론되고 등록됩니다.
재활성화 (0.79.0이 이미 존재함) — 고정 조건이 충족되므로 계획은 SKIP이 됩니다.
다른 버전이 설치되어 있음 (예: 이전 프로젝트에서 0.78.0을 남겨둠) — 0.78.0은 ==0.79.0을 충족하지 않으므로 계획은 파괴적인 OVERWRITE가 됩니다: 미리보기 모달에 표시되고 승인 시 로컬 라이브러리 디렉터리가 삭제되고 v0.79.0이 다시 클론됩니다.

참고 사항 및 주의점

단순 문자열도 계속 작동합니다. 기존의 "libraries_to_download": ["user/repo"] 목록은 버전 강제 없이 소스에서 계속 클론합니다. 객체 형태만 version을 강제합니다.
사용자별 오버라이드가 우선합니다. 사용자의 워크스페이스 설정은 프로젝트 인접 설정보다 상위에 위치합니다(워크스페이스 참조). 사용자는 로컬에서 고정 설정을 오버라이드할 수 있습니다. 고정 설정은 프로젝트와 함께 배포되는 기본값이며 강제 잠금이 아닙니다.
CLI 대안. 헤드리스 엔진을 자동화하는 관리자는 griptape-nodes libraries download <git_url>로 라이브러리를 클론하고 griptape-nodes libraries sync로 업데이트할 수 있습니다. 라이브러리 및 명령줄 인터페이스 참조를 확인하세요. 위의 선언적 구성은 프로젝트와 함께 동일한 고정 설정을 제공하는 이식 가능한 방법입니다.