Как создать и использовать модули в Afina#

В этом гайде вы создадите простой модуль для Afina на примере расчета процента от числа, правильно подготовите его через ChatGPT или другую AI-модель, добавите в Afina и проверите результат. Также здесь собраны все базовые нюансы работы с модулями: структура файлов, теги, папки, подпись, переподписание, использование в скриптах, экспорт, импорт и безопасная работа через AI-модели.

Перед началом#

Подготовьте редактор кода для работы с файлами модуля.
Для старта удобнее всего использовать VS Code или Cursor.
Если вы планируете создавать модуль через ChatGPT или другую AI-модель, не начинайте с генерации структуры с нуля.

Модуль - это JS-код, который превращается в кастомный компонент для разработки скриптов в Afina. Проще говоря, модули нужны для задач, которые:

невозможно реализовать стандартными компонентами Afina;
или очень сложно либо неудобно делать стандартными компонентами.

Модули в Afina создаются на JavaScript. Раздел «Модули» нужен для создания, хранения, организации, импорта, экспорта и повторного использования модулей.

Модули можно создавать:

вручную, если вы знаете программирование;
или с помощью ChatGPT либо другой AI-модели.

В этом гайде акцент сделан именно на работе с AI-моделями, чтобы быстрее реализовывать простые и средние по сложности идеи.

Если у вас еще нет редактора кода, самый простой бесплатный вариант для старта - VS Code.

Не стоит просить AI-модель придумать модуль для Afina с нуля без примера реальной структуры. Чаще всего это приводит к неправильным файлам, неверному формату или ошибкам при импорте.

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

Подготовка модуля#

В этом гайде в качестве примера используется простой модуль «Процент от числа». Его логика такая:

пользователь вводит число;
пользователь вводит процент;
модуль вычисляет результат по формуле число × процент / 100;
модуль возвращает готовое значение.

Этот пример удобен тем, что на нем легко показать полный цикл работы:

создание модуля;
подготовку структуры;
генерацию кода через AI-модель;
сохранение файлов;
проверку в Afina;
экспорт и повторный импорт.

Перейдите в раздел Модули на левой навигационной панели.

На скриншоте ниже показан раздел «Модули» в левом меню Afina с пустым списком.

Раздел Модули в левом меню Afina с пустым списком модулей

Раздел «Модули» в левом сайдбаре Afina по логике работы во многом похож на раздел «Скрипты». При необходимости используйте два режима просмотра:

«Таблица» - если удобнее работать со списком, тегами, хэшем и датами;
«Папки» - если нужно разложить модули по директориям и удобнее перемещаться по структуре.

Для первого создания модуля обычно удобнее начинать с табличного режима.

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

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

Нажмите Добавить модуль.
В поле «Название» введите название модуля, например Percentage of a Number.
Включайте чекбокс «Использовать пользовательскую папку» только тогда, когда у вас уже есть файлы модуля в собственном месте на диске.
В поле «Теги» добавьте теги, например math, example, test, если хотите удобнее организовать модули.
Нажмите Сохранить.

На скриншоте ниже показано окно «Добавить модуль» с полями названия, тегов и переключателем пользовательской папки.

Если вы не укажете пользовательскую папку, Afina сохранит модуль в стандартной директории модулей внутри своей структуры данных.

Если вы создаете модуль через Custom folder, Afina может не создать стандартные файлы автоматически. В большинстве случаев для первого модуля удобнее использовать стандартную папку.

Теги можно добавлять не только при создании модуля. Для одного модуля используйте иконку добавления тега на карточке или в строке, а для нескольких модулей отметьте их чекбоксами и примените действие Установить теги в верхнем меню. Так можно добавить, заменить, очистить или удалить конкретные метки.

В режиме «Папки» можно создавать многоуровневую структуру директорий и назначать им цвета. Если удалить папку, сами модули не удаляются, а переходят в категорию «Без папки».

Нажмите иконку Открыть папку с модулем в таблице или на карточке модуля.

На скриншоте ниже показан список модулей с иконкой открытия локальной папки.

Список модулей в Afina с иконкой открытия локальной папки модуля

Откройте локальную папку модуля в редакторе кода.

На следующем скриншоте показана локальная папка модуля со списком файлов.

Локальная папка модуля со списком файлов index.js settings.json package.json и utils_22.js

Откройте файлы index.js и settings.json.

На этом скриншоте показаны файлы index.js и settings.json, открытые рядом в редакторе кода.

Файлы index.js и settings.json открыты рядом в редакторе кода

На этом этапе ваша задача не переписывать все вручную, а сначала понять:

какие файлы Afina создала автоматически;
какие из них отвечают за описание модуля;
где находится основной код;
какие служебные файлы не стоит ломать без необходимости.

Структура файлов модуля#

После создания модуля в Afina вы работаете не с одним файлом, а с небольшим проектом. Самые важные части:

settings.json - файл настроек модуля;
index.js - главный файл логики модуля;
package.json - описание зависимостей и метаданных;
package-lock.json - фиксация точных версий зависимостей;
node_modules - установленные пакеты;
utils_<id>.js или папка utils - вспомогательные функции, если они есть в структуре.

Что делает settings.json settings.json отвечает за то, какие поля ввода и параметры видит пользователь в интерфейсе Afina при использовании модуля.

Именно здесь обычно описываются:

поля input;
списки select;
checkbox;
textarea;
другие управляющие элементы.

Типовая структура одного поля может выглядеть так:

json

Что означают основные поля:

name - уникальное имя переменной, по которому код обращается к значению;
label - название, которое пользователь видит в интерфейсе;
type - тип поля;
options - список значений для select;
loadTo - куда передавать значение для дальнейшего использования в модуле;
isVisible - условие, при котором это поле должно отображаться.

Распространенные типы полей:

text;
number;
select;
checkbox;
textarea.

Если у модуля есть входные параметры, именно settings.json обычно определяет, как эти параметры будут показаны в Afina.

Что делает index.js index.js - это главный файл модуля, который взаимодействует с Afina и выполняет основную логику.

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

Не удаляйте и не переписывайте служебный IPC-блок process.on('message', ...) и process.send({ status: 'ready' }). Он нужен шаблону модуля для корректного взаимодействия с Afina.

Вы можете создавать дополнительные файлы и папки внутри модуля. Это нормально, если:

вы правильно импортируете их;
вы не ломаете основную структуру;
главная логика все равно корректно подключена к модулю.

Для чего нужны package.json, package-lock.json и node_modules package.json - это условный паспорт проекта. В нем обычно находятся:

название;
версия;
зависимости;
dev-зависимости;
служебные скрипты;
технические параметры вроде type или engines.

package-lock.json фиксирует точные версии зависимостей и нужен для одинакового воспроизведения окружения.

node_modules - это физически установленные пакеты.

Важно понимать:

node_modules обычно не добавляют в git;
эти пакеты обычно можно восстановить через npm i, если структура модуля это предусматривает;
package-lock.json обычно лучше сохранять, если вы работаете с зависимостями.

Для чего нужны utils_<id>.js или папка utils В файле вроде utils_22.js или в папке utils часто лежат уже подготовленные вспомогательные функции.

В простом примере она может вообще не понадобиться, но в более сложных модулях это нормальное место для вынесения части логики.

Подготовка AI-контекста#

Лучший подход к работе с ChatGPT или другой AI-моделью такой:

Сначала создайте пустой модуль в самой Afina.
Откройте его локальную папку.
Покажите AI-модели реальные файлы этого модуля.
Только после этого просите сгенерировать код или изменить структуру.
Подготовьте для AI-модели название и задачу модуля.
Добавьте в запрос содержимое файлов пустого модуля, которые создала Afina.
Напишите в запросе, что не нужно придумывать новый формат, а нужно изменить уже существующую структуру.
Опишите ожидаемую логику работы модуля.

Пример нормального запроса:

text

На скриншоте ниже показан запрос в ChatGPT с описанием модуля и прикрепленными файлами.

Запрос в ChatGPT с описанием модуля и прикрепленными файлами index.js settings.json package.json package-lock.json и utils_22.js

Если просто написать в ChatGPT или другой AI-модели «сделай модуль для Afina», она может сгенерировать код, который выглядит логично, но не соответствует реальной структуре вашего модуля.

Попросите AI-модель не только сгенерировать код, но и объяснить:

какой файл она изменила;
за что отвечает каждое изменение;
какие поля являются входными;
какой результат модуль возвращает;
что нужно проверить перед импортом или запуском.

Так вы сможете не просто вставить код, но и понять, что именно он делает.

Перед сохранением проверьте:

не изменилась ли базовая структура файлов;
не исчезли ли служебные поля, которые создала Afina;
остался ли на месте служебный IPC-блок process.on('message', ...) и process.send({ status: 'ready' });
одинаково ли названы сущности в файлах;
не добавила ли AI-модель лишние библиотеки или зависимости, которых у вас нет;
соответствует ли логика именно вашей задаче.

Сохранение модуля#

Замените или отредактируйте файлы index.js и settings.json в локальной папке модуля.

На скриншоте ниже показан ответ ChatGPT с объяснением изменений в файлах модуля.

На следующем скриншоте показаны обновленные файлы index.js и settings.json с полями Number и Percent в редакторе кода.

Обычно мы меняем только файлы index.js и settings.json. Работайте аккуратно:

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

Вернитесь в раздел Модули в Afina.
Нажмите иконку Обновить.

На скриншоте ниже показана кнопка обновления списка модулей в разделе «Модули».

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

Модуль или скрипт без актуальной подписи не будет работать. После ручного изменения index.js, settings.json, package.json или других файлов модуля нужно обновить список, проверить красную иконку и выполнить переподписание. Переподписание стоит делать только тогда, когда вы доверяете текущему содержимому локальной папки и понимаете, что именно было изменено.

Подпись защищает модуль от незаметных изменений в файлах и основана на цифровой подписи Ed25519. Сразу после создания модуля подпись может появиться не мгновенно, если Afina еще завершает фоновую установку зависимостей.

Использование модуля в скрипте#

Откройте нужный скрипт в среде разработки.
Перетащите блок Добавить модуль на полотно.
Нажмите на этот блок.
Выберите нужный модуль из списка.
Заполните параметры, необходимые для работы модуля.
Нажмите Сохранить.

На скриншоте ниже показан диалог «Добавить модуль» в среде разработки скрипта с выбором модуля Percentage of a Number и его параметрами.

В среде разработки скрипта открыт диалог Добавить модуль с выбором модуля Percentage of a Number и его параметрами

После этого модуль будет доступен в скрипте как отдельный компонент с собственными полями и логикой. Технически такой компонент вызывает модуль через блок executeModule и привязывается к нему по уникальному хэшу.

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

На следующем скриншоте показано контекстное меню модуля с пунктом «Начальный элемент» и переменные окружения с результатом вычисления 20.

Откройте «Переменные окружения» и убедитесь, что модуль отработал корректно.
Используйте эти переменные дальше в вашем скрипте, если результат правильный.
Откройте «Логи», если во время выполнения модуль не работает.

На скриншоте ниже показано окно логов в среде разработки скрипта с сообщениями модуля и текстом ошибки.

Если во время выполнения модуль не работает, нужно проверить логи, скопировать их и вставить в вашу AI-модель для дальнейшего решения вопроса.

Если скрипт или модуль не подписан, запуск не отработает корректно. Перед тестом проверьте, нет ли красной иконки переподписания рядом с модулем или самим скриптом.

Если модуль выполняет долгую логику, проверьте настройку «Максимальное время выполнения модуля (мс)» в разделе основных настроек Afina. Если лимит слишком маленький, Afina может принудительно остановить модуль до завершения его работы.

Экспорт и импорт модулей#

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

Экспорт через верхнюю панель

Отметьте нужный модуль чекбоксом.
Нажмите Экспорт.
Выберите экспорт выбранных модулей на локальный компьютер или в Google Drive.

Экспорт через меню строки или карточки

Нажмите иконку трех точек в строке или карточке модуля.
Выберите Экспортировать модуль.

После экспорта вы получите ZIP-архив, который может содержать:

JSON-файлы;
JS-файлы;
библиотеки;
другие связанные файлы модуля.

Экспорт в Google Drive работает только если Google Drive предварительно подключен в настройках Afina.

Импорт модуля с локального компьютера

Нажмите Импорт.
Выберите пункт импорта модулей.
В системном окне выберите ZIP-архив.
Дождитесь завершения импорта и зеленого уведомления о результате.

Импорт модуля из Google Drive

Нажмите Импорт.
Выберите импорт модулей из Google Drive.
Отметьте нужные файлы.
Нажмите Импортировать.

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

Импорт нужен, когда вы:

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

Практические нюансы#

Вот что реально помогает избегать проблем при создании модуля через AI-модель:

не просите AI-модель сгенерировать модуль без реального шаблона;
сначала создавайте пустой модуль через Afina;
давайте AI-модели только актуальные файлы, а не описание словами;
просите не менять служебную структуру без необходимости;
тестируйте модуль на простых числах с очевидным результатом;
перед серьезными изменениями делайте копию модуля;
после ручных изменений проверяйте, не нужно ли переподписание;
не обновляйте хэш без необходимости, если модуль уже используется в скриптах;
для долгих операций проверяйте лимит времени выполнения модуля.

Результат#

После выполнения этих шагов у вас будет готовый рабочий модуль для Afina с правильной структурой файлов, понятной логикой работы и проверенным результатом в скрипте. У вас также будет полный рабочий процесс для дальнейших модулей: создание, редактирование через AI-модель, проверка, переподписание, использование в скриптах, экспорт и импорт.