Разрешения плагинов

Разрешения — это механизм, с помощью которого пользователи решают, что может делать плагин: от чтения истории чата до выполнения сетевых запросов.

Модель разрешений

Разрешение — это строка, называющая возможность. Объявление его в манифесте — это запрос, а не автоматический доступ: пользователь должен подтвердить каждое запрошенное разрешение, прежде чем плагин станет активным, а хост обеспечивает выдачу в каждой точке использования.

Встроенный набор — стабильный версионируемый контракт:

Разрешение	Что оно даёт
chat.read	Чтение сообщений чата и их метаданных
chat.write	Создание или изменение сообщений чата
characters.read	Чтение персонажей и карточек персонажей
characters.write	Создание или изменение персонажей
lorebook.read	Чтение записей лорбука
lorebook.write	Создание или изменение записей лорбука
prompt.inspect	Просмотр собранного промпта
prompt.modify	Изменение промпта или пост-обработка вывода генерации
providers.register	Регистрация адаптеров провайдеров и токенизаторов
ui.toolbar	Добавление действий панели инструментов
ui.sidebar	Добавление панелей боковой панели
ui.messageActions	Добавление действий сообщений
ui.shell	Добавление контента в слоты оболочки
clipboard.read	Чтение буфера обмена
clipboard.write	Запись в буфер обмена
notifications	Показ уведомлений
server.routes	Монтирование backend-маршрутов
legacy.trusted	Выполнение документированного устаревшего кода SillyTavern в доверенном контексте

Ограниченные разрешения

Некоторые разрешения несут область действия, записываемую как kind:scope:

• network:<hostname> — разрешение выполнять запросы к конкретному хосту, например network:api.example.com. Запросы к хостам, не получившим разрешение, отклоняются.
• network:* — подстановочный знак, разрешающий запросы к любому хосту. Хост трактует его как полный сетевой доступ, а экран согласия показывает его с усиленным предупреждением. Предпочитайте перечислять конкретные хосты; публикация плагинов, запрашивающих подстановочный знак, не рекомендуется.
• files:plugin — чтение и запись внутри собственного каталога данных плагина.
• files:user-selected — доступ к файлам, которые пользователь явно выбрал.

hasPermission проверяет выданный набор против требуемого разрешения, а parsePermission разбивает строку kind:scope на части. Функция validatePermissions отклоняет некорректные строки, такие как пустые, дублирующиеся или неизвестные разрешения.

Как обеспечиваются выдачи

Объявления разрешения недостаточно; хост применяет выдачу в точке обеспечения:

• Регистрации UI проверяют разрешения ui.* перед монтированием.
• Маршруты проверяют server.routes.
• Проверяемый fetch проверяет network:<host>.
• Виртуальная файловая система проверяет files:*.
• API провайдеров и контекста проверяют providers.register и prompt.modify.

Ядро возможностей (пространство имён kernel пакета @neotavern/plugin-sdk) — общий слой, который проверяет выдачи и в веб-хосте, и на сервере, поэтому браузер и backend всегда видят одни и те же эффективные права. Выдачи хранятся с монотонно возрастающей ревизией, доставляются в песочницу во время bootstrap-рукопожатия и могут быть отозваны в рантайме. Выполняющиеся операции завершаются с ошибкой CAPABILITY_REVOKED, а открытые дескрипторы закрываются хостом.

Согласие и повторное согласие при обновлении

Установка показывает полный список запрошенных разрешений. Плагин остаётся в состоянии needs-consent, пока вы не подтвердите каждое разрешение, а UI показывает список зависимостей, когда пакет поставляет npm-зависимости.

Обновление плагина — это новая установка для проверки разрешений: хост вычисляет разницу между предыдущим и новым манифестом с помощью diffPermissions. Если обновление добавляет разрешения:

• рантайм плагина немедленно отключается;
• пользователю предлагается дать согласие на новые разрешения;
• плагин остаётся отключённым, пока согласие не будет получено.

Удаление разрешений никогда не требует согласия. Общее правило: набор выданных разрешений никогда не растёт без явного решения пользователя. Полный список констант и хелперов разрешений см. в генерируемом справочнике Plugin SDK.