Як створити і використовувати модулі в 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, відкриті поруч у редакторі коду.

На цьому етапі ваше завдання не переписувати все вручну, а спочатку зрозуміти:

які файли 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-модель, перевірка, перепідпис, використання у скриптах, експорт і імпорт.