Обзор Plugin SDK

Plugin SDK — это версионируемый публичный API, с помощью которого плагины расширяют NeoTavern, охватывающий как UI на стороне браузера, так и backend на стороне сервера.

Что такое Plugin SDK

Плагины — это ZIP-пакеты (.stplugin), которые поставляют манифест, необязательные frontend- и backend-точки входа и ресурсы. Они расширяют приложение только через пакет @neotavern/plugin-sdk — никогда не импортируя Fastify, React, Zustand, TanStack Query, соединение SQLite или внутренние компоненты напрямую. Это детали реализации хоста, которые меняются без предупреждения.

SDK версионируется (apiVersion в манифесте), чтобы плагины продолжали работать при обновлениях приложения. Хост обеспечивает контракт: всё, что вы регистрируете через SDK, очищается при отключении плагина, а всё, что вам могло бы понадобиться из внутренних модулей, сознательно не раскрывается.

Разделение frontend и backend

У плагина две необязательные половины:

• Frontend — браузерная ESM-точка входа, которая получает FrontendPluginApi в своём вызове activate(). Она регистрирует поверхности UI, такие как действия панели инструментов, действия сообщений, слэш-команды и панели настроек, и слушает события приложения.
• Backend — ESM-точка входа Node.js, которая получает ServerPluginApi. Она монтирует маршруты в /api/plugins/{pluginId}/, читает и записывает изолированное хранилище, выполняет сетевые вызовы с проверкой разрешений и регистрирует провайдеров и стратегии контекст-шифтинга.

Обе половины необязательны. Плагину, который только добавляет кнопку на панель инструментов, backend не нужен; плагину, который только обслуживает API, фронтенд не нужен. Каждая регистрация возвращает функцию очистки, и рантайм собирает их, чтобы при деактивации ничего не оставалось.

Создание плагина

Импортируйте definePlugin из @neotavern/plugin-sdk и экспортируйте определение с функцией activate(api):

import { definePlugin } from '@neotavern/plugin-sdk';

export default definePlugin({
  activate(api) {
    const unregister = api.ui.messageActions.register({
      id: 'example.greet',
      title: 'Greet',
      run: ({ message }) => console.log(message.messageId),
    });
    api.events.on('chat.opened', ({ chatId }) => console.log(chatId));
  },
});

Генерируемый справочник Plugin SDK документирует каждый экспортированный тип и функцию с точной сигнатурой.

Следующие шаги

• Манифест — структура пакета и схема plugin.json.
• Разрешения — модель разрешений и поток согласия.
• Frontend API — регистрация поверхностей UI и событий.
• Backend API — маршруты, хранилище и серверные абстракции.
• Жизненный цикл — установка, включение, отключение и гарантии очистки.
• Песочница — модель безопасности для недоверенного кода.