Плагины

Плагины — это механизм расширения Creatium Max с помощью кода. Каждый плагин — это набор TypeScript-файлов, которые выполняются в изолированной среде и добавляют в проект новые возможности.

Каждый плагин работает в изолированной песочнице Deno — плагины не имеют доступа к базе данных проекта, файлам других плагинов и системным ресурсам сервера.

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

Самый простой способ создать плагин - это загрузить шаблон попросить ИИ-агента (Claude Code, Codex, Cursor и тд.) сделать нужный вам функционал. В архиве шаблона есть все нужные инструкции и вся документация, которая может потребоваться агенту.

Но можно использовать и обычный ChatGPT, которому достаточно основу функции прислать, чтобы он сделал всю работу.

typescript
export default async function (req: Request): Promise<Response> {
  // Напиши функцию отправки письма на почту
}

Структура плагина

my-plugin/

CLAUDE.md и AGENTS.md - документация по структуре плагина для ИИ агентов
deno.json - информация о плагине
migrate.ts - скрипт обновления плагина (если нужно)
api/

public/

…публично доступные ендпоинты

admin/

…ендпоинты, доступные только админам

actions/

…действия, доступные в редакторе сценариев

cron/

…скрипты, запускаемые по расписанию

static/

public/

…статические файлы, доступные публично

admin/

index.html - главная страницы интерфейса плагина в админке
…статические файлы, доступные только админам

storage/

data.db - файл базы данных sqlite
…хранилище файлов (uploads, временные файлы и тд)

/deno.json

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

markdown
{
    "name": "my-plugin",
    "version": "0.0.1",
    "title": "Мой плагин"
}

/api - HTTP ендпоинты

В папках /api/public и /api/admin лежат публично доступные ендпоинты. public досупны для любых запросов, admin только тем, кто авторизован в /cr-admin.

Каждый ендпоинт - это функция, которая на вход получает Request, а возвращает Response.

typescript
export default async function (req: Request): Promise<Response> {
  return Response.json({ message: "Hello, world!" });
}

Название файла напрямую отражается в URL. Файл /api/public/hello.ts доступен по адресу https://example.com/cr-plugin/my-plugin/api/public/hello.

/actions - действия для сценариев

В папке /actions находятся функции, которые автоматически подключаются в редактор сценариев, и которые могут быть вызваны из любого сценария. Формат такой же, как в /api, но работа только с JSON в обе стороны.

Чтобы в редакторе сценариев отображались именованные поля с описаниями, можно использовать JSON Schema в экспорте config.input.

typescript
export const config = {
  title: "Отправить письмо",
  input: {
    description: "Отправляет письмо на указанный адрес",
    type: "object",
    properties: {
      text: {
        description: "Полный текст письма",
        type: "string"
      },
      subject: {
        description: "Тема письма",
        type: "string"
      },
      email: {
        description: "Кому отправить?",
        type: "string"
      }
    },
    required: [ "text", "subject", "email" ]
  }
}

Если схема указана, она в том числе будет использоваться и для валидации входящих значений.

/cron - задачи по расписанию

В папке /cron находятся функции, которые переодически выполняются по указанному расписанию.

Запуск каждую минуту:

typescript
export const config = {
  schedule: "* * * * *"
}

Каждый день в 8 утра:

typescript
export const config = {
  schedule: "0 8 * * *"
}

И так далее. Это стандартный формат crontab.

/static - статические файлы

В папках /static/public и /static/admin лежат статические файлы, которые доступны всем и только админам, соответственно.

Если есть файл /static/admin/index.html, то он используется в качестве главной страницы плагина в админке.

/storage - постоянное хранилище файлов и баз данных

В этой папке скрипты плагина могут сохранять файлы любого формата. Это единственная папка, доступная для редактирования.

В ней же можно хранить файлы SQLite (с расширением .db или .sqlite), например /storage/data.db, и работать с ними, используя node:sqlite в Deno.

Админ интерфейс

Главная страницы плагина в админке - это /static/admin/index.html, которая показывается при открытии плагина.

Все, что внутри /static/admin и /api/admin доступно только после авторизации в админке проекта /cr-admin, то есть дополнительно слои безопасности добавлять не нужно.

Сессии и пользователи

Ендпоинты в /api получают на вход 2 HTTP-заголовка: X-Cre-Session-Id и X-Cre-Member-Id, которые невозможно подменить. В этих заголовках передаются идентификаторы сессии и пользователя из таблиц “Сессии” и “Пользователи” в базе данных проекта.

Используя эти заголовки можно делать функционал, привязанный к посетителям и пользователям.

Ограничения

Чтобы один плагин не мог нагрузить сервер и замедлить весь проект, на среду выполнения плагинов установлены аппаратные ограничения: 0.5 CPU, 512MB RAM.

Эти ограничения обеспечивают стабильность: даже если плагин содержит бесконечный цикл или утечку памяти, проект продолжит работу.

Таймауты

По умолчанию все скрипты (api, actions) имеют таймаут в 30 секунд, а задачи по расписанию (cron) - 5 минут. Эти значения можно изменить в config.timeout.

typescript
export const config = {
  timeout: 120 // 2 минуты
}