Личные расширения

Личное расширение – это небольшой фрагмент кода, который добавляет в приложение Marinara кнопку, панель или вспомогательный инструмент. Professor Mari может написать его для вас, а вы решаете, будет ли оно вообще запускаться. В этом руководстве описано, как проверять, включать, экспортировать и восстанавливать расширения. Как написать собственное, смотрите в руководстве Создание личных расширений.

Виды расширений

Установка расширения, которым с вами поделились

Перед началом выполните два шага из раздела Разрешение импорта сторонних расширений. Без них кнопки импорта скрыты.

1. Откройте Settings → Addons. В блоке External Extensions нажмите Import Extension File (импортировать файл расширения) для файла .zip, .json, .css или .js либо Import Extension Folder (импортировать папку расширения) для папки.
2. Откройте новый черновик. Он выключен и показывает свой код и хеш – короткий отпечаток именно этого кода (Marinara использует SHA-256).
3. Прочитайте код и список Requested access (запрошенный доступ).
4. Нажмите Review and Run (проверить и запустить), только если вы принимаете именно эту версию. После этого расширение показывается как включенное.

Если не сработало: если кнопок импорта нет, один из двух шагов не выполнен. Не забудьте перезапустить Marinara после изменения .env.

Проверка расширения от Professor Mari

Перед началом попросите Professor Mari создать расширение. Она может сохранить код, но не может его одобрить или включить. В этом разделе нет кнопки New Draft и средств импорта.

1. Откройте Settings → Addons → Personal Extensions. Если черновиков нет, там написано: "Ask Professor Mari to create an extension for you. Nothing runs until you enable it and approve the exact code hash."
2. Откройте черновик и прочитайте код. Проверьте хеш и список Requested access.
3. Нажмите Review and Run, только если вы принимаете именно эту версию.

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

Предупреждение: Песочница ограничивает возможности кода, но не делает код надежным. Вредоносное расширение все равно может впустую тратить время процессора, пока его не остановит сторожевой таймер (таймер, который останавливает вышедший из-под контроля код), заполнить собственное хранилище до лимита или вводить вас в заблуждение записями в журнале. Расширения с полным доступом к странице намеренно отказываются от песочницы. Читайте код перед включением, а в стороннем коде проверяйте каждую строку.

Если не сработало: правки Professor Mari и любая восстановленная версия возвращают черновик в выключенное состояние. Проверьте его снова и убедитесь, что хеш в окне – тот, который вы прочитали.

Что может расширение

Браузерное расширение работает в песочнице (отгороженной области) внутри вашего браузера. Ему недоступны страница приложения Marinara, cookie, браузерное хранилище и сеть. Оно может:

• хранить данные в закрытом хранилище и писать в журнал
• добавлять кнопки, пункты меню и панели, которые Marinara рисует в вашей теме оформления
• читать идентификаторы открытого чата
• читать выбранные поля активных персонажей или персоны, только если вы одобрили эти разрешения

Полный список приведен в руководстве Создание личных расширений.

Серверное расширение работает в отдельном процессе Node (программе на компьютере-сервере) внутри песочницы операционной системы. Ему недоступны файлы приложения Marinara, ваши файлы, секреты сервера, сеть, дочерние процессы, воркеры и нативные модули.

Поддержка платформ

Браузерные расширения изолирует сам браузер, поэтому они работают везде. Серверным расширениям нужна поддерживаемая песочница операционной системы. Там, где ее нет, они остаются выключенными, и Marinara никогда не запускает их без песочницы.

Браузерные расширения изолированы на всех платформах. Внешние расширения с полным доступом к странице не изолированы нигде и всегда требуют вашего явного доверия.

Официальный образ Docker содержит Bubblewrap, но его стандартный контейнер не может создавать вложенные пространства имен и монтирования, которые нужны Bubblewrap. Marinara проверяет песочницу во время работы и оставляет серверные расширения выключенными, если контейнер ее не разрешает. О переопределении разрешений Docker и его цене для безопасности смотрите в разделе Устранение неполадок.

На Windows и Android нет поддерживаемой песочницы для процессов, поэтому серверные расширения там недоступны. Используйте браузерное расширение или запустите сервер Marinara на macOS либо на Linux с bwrap.

Разрешение импорта сторонних расширений

Импорт сторонних расширений по умолчанию заблокирован и скрыт, потому что такие расширения запускают код, написанный другими людьми. Открывают его два шага:

1. На компьютере, на котором запущена Marinara, задайте ENABLE_EXTERNAL_EXTENSIONS=true в файле .env, затем перезапустите Marinara. См. Настройки сервера: справочник.
2. Откройте Settings → Advanced → Danger Zone (дополнительно → опасная зона), прокрутите ниже элементов управления удалением данных, прочитайте предупреждение и включите Allow third-party extension imports (разрешить импорт сторонних расширений).

После этого в разделе Settings → Addons появляется блок External Extensions со средствами импорта файлов и папок. Поддерживаемые форматы:

• .personal-extension.zip и совместимые пакеты .zip
• манифесты .json
• .css
• .js, .mjs и .cjs
• .server.js, .server.mjs и .server.cjs

Импорт никогда не приносит с собой одобрение, и расширение не может включить себя само. Большинству браузерных расширений стоит оставаться в безопасной песочнице. Пакет с отметкой Full page access – другое дело:

• Его код выполняется на странице приложения Marinara без песочницы.
• Он может читать чаты и карточки, пользоваться браузерным хранилищем, отправлять сетевые запросы и обращаться к собственным API приложения Marinara.
• Включайте его, только если вы изучили именно эту версию и доверяете ей.
• Черновики Professor Mari не могут его запросить.

Старые записи, записи, импортированные вместе с профилем, сохраненные вручную и записи неизвестного происхождения тоже считаются внешними. Они остаются скрытыми, одобрить их нельзя, и они не запускаются, пока не выполнены оба шага.

Если отменить любой из двух шагов, все импортированные расширения выключаются. Повторное включение не запускает их снова. Если расширение с полным доступом к странице оставило после себя изменения, перезагрузите страницу.

Если не сработало: если средства импорта не появились, проверьте, что оба шага выполнены и что вы работаете на компьютере-сервере или сохранили секрет администратора в разделе Settings → Advanced → Admin Access (доступ администратора).

Экспорт, версии и восстановление

Чтобы скачать переносимый пакет, воспользуйтесь действием экспорта у расширения. Экспортированные и восстановленные пакеты остаются выключенными. Восстановление прежней версии тоже возвращает расширение в состояние выключенного черновика.

Settings → Addons → Extension revision history (история версий расширений) задает, сколько предыдущих версий кода хранится для каждого личного и внешнего расширения. По умолчанию – 10. Выберите значение от 0 до 10, где 0 отключает историю. При уменьшении лимита Marinara запрашивает подтверждение, прежде чем безвозвратно удалить старые версии. Текущий код, одобрения, состояние включения и сохраненные данные расширений остаются. Правки через Professor Mari подчиняются тому же лимиту.

Если расширение ведет себя не так, как надо, нажмите Disable (выключить). Если интерфейс недоступен, остановите Marinara и задайте значение "false" в поле enabled соответствующей записи installed_extensions. Никогда не задавайте approvedHash вручную.

Смежные руководства

• Создание личных расширений
• Professor Mari
• Настройки сервера: справочник
• Резервное копирование и восстановление Marinara
• Удаленный доступ: вход и список разрешенных адресов