본문으로 건너뛰기

레거시 호환성

NeoTavern은 기존 SillyTavern 시대 확장 기능을 위해 문서화된 계약 집합을 보존합니다. 그 API에 맞춰 작성된 플러그인이 계속 동작할 수 있게 하면서, 네이티브 Plugin SDK를 앞으로의 경로로 삼습니다.

Window 전역​

@neotavern/legacy-compat 패키지는 오래된 확장 기능이 기대하는 문서화된 window 전역을 설치합니다.

  • window.SillyTavern — getContext(), eventSource, event_types 포함.
  • window.eventSource — 레거시 이벤트 소스.
  • window.event_types — 이벤트 이름 상수.
  • window.extension_settings — 공유 확장 설정 객체.
  • window.$ 및 window.jQuery — 번들된 jQuery 인스턴스.

이 전역은 멱등하게 설치되고 브리지를 통해 호스트에 연결되므로 레거시 코드가 네이티브 코드와 같은 컨텍스트와 이벤트를 읽을 수 있습니다.

비관리 DOM 섬​

레거시 프론트엔드 확장 기능은 페이지의 일부를 소유할 것으로 기대합니다. 호스트는 이를 위해 비관리 DOM 섬을 제공합니다. React 트리 밖에서 레거시 코드가 직접 붙잡고 조작할 수 있는 안정적인 컨테이너입니다. 확장 기능이 컨테이너를 받고, 호스트가 그 주위의 나머지 애플리케이션을 처리합니다.

레거시 서버 플러그인​

레거시 서버 플러그인은 Express 호환 호스트를 통해 실행됩니다. 해당 라우트는 네이티브 백엔드 플러그인이 사용하는 것과 같은 네임스페이스인 /api/plugins/{pluginId}/... 아래에 프록시됩니다. @fastify/express 통합은 이 호환 계층 안에서만 사용됩니다. 새 코어는 Fastify 네이티브 이며 Express를 통과해 라우팅하지 않습니다.

신뢰할 수 있는 경계​

레거시 진입점은 샌드박스 우회가 아닌 신뢰 모드입니다. 이를 사용하는 패키지는 매니페스트에 legacy.frontend 또는 legacy.backend를 선언하고 legacy.trusted 권한을 요청해야 하며, 동의 UI는 강화된 경고로 표시합니다. 레거시 프론트엔드 코드는 메인 창에서 실행되고, 레거시 백엔드 코드는 자체 플러그인 네임스페이스로 범위가 지정된 Express 라우터를 받습니다. 세이프 모드는 레거시 진입점을 전혀 로드하지 않습니다. 자세한 내용은 플러그인 샌드박싱과 플러그인 매니페스트를 참조하세요.

지원되지 않는 것​

호환성은 문서화된 계약이지 보편적 동작의 약속이 아닙니다. 다음 중 하나에 의존하는 플러그인은 지원되지 않습니다.

  • 무작위 내부 CSS 클래스 이름.
  • 애플리케이션 내부의 몽키 패칭.
  • 소유하지 않은 패키지의 비공개 import.

이것들은 구현 세부 사항이며 릴리스 사이에 바뀝니다. 레거시 API가 바뀌면 변경 사항은 마이그레이션 가이드와 호환성 테스트와 함께 제공됩니다.

앞으로의 마이그레이션​

새 기능에는 네이티브 Plugin SDK가 지원되는 경로입니다. 버전이 있고, 권한이 검사되고, 샌드박스 처리되며, 호스트가 정리합니다. 레거시 호환성은 기존 확장 기능을 살려 두기 위해 존재하지, 성장시키기 위해 존재하지 않습니다. 완전한 보안과 라이프사이클 보장을 얻으려면 확장 기능을 SDK로 포팅하세요.