Zator: Специализированный язык программирования для построения генеративных пайплайнов через KoboldCpp и StableDiffusion

Введение: Когда простота становится стратегией

В эпоху бурного развития генеративного искусственного интеллекта разработчики, дизайнеры и создатели контента сталкиваются с парадоксальной проблемой: несмотря на доступность мощных моделей вроде Stable Diffusion и больших языковых моделей через KoboldCpp, процесс создания воспроизводимых, автоматизированных пайплайнов остается удивительно сложным. Традиционные подходы требуют написания десятков строк шаблонного кода для обработки HTTP-запросов, парсинга JSON-ответов, управления файлами и постобработки результатов. Именно эту проблему решает Zator — специализированный язык программирования, созданный не для универсальных задач, а для одной четко определенной цели: превратить сложные генеративные сценарии в лаконичные, читаемые и легко поддерживаемые скрипты.

Философия Zator коренится в принципе доменной специализации. Вместо того чтобы пытаться стать еще одним универсальным языком вроде Python или JavaScript, его авторы сделали ставку на глубокую интеграцию с экосистемой KoboldCpp — популярным фреймворком для локального запуска больших языковых моделей с встроенной поддержкой Stable Diffusion. Результатом стал инструмент, который позволяет описать полный цикл создания контента — от генерации текстовой истории до создания иллюстраций, их постобработки и сохранения — в 10–15 строках кода, без единой строчки для работы с сетевыми запросами или обработки бинарных данных.

«Специализированный язык программирования для создания и обработки AI-генерируемого контента (текста и изображений) с использованием API KoboldCpp. Язык предоставляет простой и интуитивно понятный синтаксис для построения генеративных пайплайнов с минимальным количеством кода, а также включает встроенные функции для постобработки изображений и выполнения системных команд» — официальное описание из документации проекта (версия 0.0.2).

Что нового в версии 0.0.2 (от 20 февраля 2026 года):

Функция	Описание	Значение для разработчика
Пользовательские функции	Поддержка def с параметрами (до 10)	Модульность и переиспользование кода
HTTP-запросы	Функция request() для внешних API	Интеграция с Telegram, Discord и другими сервисами
Системные команды	Функция exec_cmd() для выполнения команд оболочки	Автоматизация файловых операций и системных задач
Импорт файлов	Директива #import для подключения модулей	Разделение кода на библиотеки и основные скрипты
Кроссплатформенность	Поддержка Windows, Linux, macOS	Работа на любой операционной системе
Улучшенные f-строки	Подстановка переменных во всех функциях	Динамическое формирование промптов и путей

Эта философия делает Zator уникальным в своем классе. Он не претендует на замену профессиональных инструментов вроде Python с библиотеками transformers или diffusers, но предлагает нечто иное: язык описания генеративных намерений. Когда разработчик пишет var img = generate_img("портрет эльфа", context, 512, 512), он не думает о том, как сформировать POST-запрос к /sdapi/v1/txt2img, как обработать base64-кодировку изображения или как сохранить его в PNG — он просто описывает желаемый результат. Вся техническая сложность инкапсулирована внутри интерпретатора, позволяя пользователю сосредоточиться на творчестве.

Для кого создан Zator? Прежде всего — для тех, кто хочет быстро экспериментировать с генеративными моделями без погружения в глубины системного программирования:

• Геймдизайнеры, которым нужно массово генерировать ассеты для игр (персонажи, иконки, текстуры)

• Писатели и сценаристы, желающие автоматизировать создание иллюстраций к своим произведениям

• Контент-мейкеры, строящие воспроизводимые пайплайны для социальных сетей

• Новички в мире ИИ, которым сложно освоить сложные фреймворки, но которые хотят сразу получить результат

• Автоматизаторы, желающие интегрировать AI-генерацию с внешними сервисами (Telegram-боты, веб-хуки)

Важно понимать: Zator — это не «упрощенный Python». Это доменно-ориентированный язык (DSL), спроектированный вокруг конкретной задачи. Его сила — в ограничениях. Отказ от универсальности позволил создать инструмент с минимальным порогом входа и максимальной выразительностью в своей нише. В этой статье мы детально разберем архитектуру, синтаксис и практические сценарии применения Zator версии 0.0.2, покажем, как за 5 минут создать скрипт для генерации игровых персонажей с автоматической обрезкой фона, и честно обсудим ограничения, которые делают этот язык специализированным, а не универсальным решением.

---

Архитектура Zator: Интеграция как основа дизайна

Глубокая связка с экосистемой KoboldCpp

Ключевая архитектурная особенность Zator — его неразрывная связь с сервером KoboldCpp. В отличие от многих языков, которые могут работать автономно или с различными бэкендами, Zator изначально спроектирован как клиентский слой поверх API KoboldCpp. Эта архитектурная связка определяет как возможности, так и ограничения языка.

Интерпретатор Zator (zator.exe / бинарный файл) не содержит в себе никаких моделей машинного обучения. Он представляет собой легковесный движок, который:

1. Парсит скрипты с расширением .zator

2. Выполняет синтаксический анализ и управление потоком выполнения

3. При вызове функций generate_text() или generate_img() автоматически формирует и отправляет HTTP-запросы к соответствующим эндпоинтам KoboldCpp

4. Обрабатывает ответы сервера, извлекая сгенерированный контент

5. Предоставляет встроенные функции для постобработки изображений (на основе библиотеки libpng)

6. Выполняет системные команды через exec_cmd() (требует наличия curl для HTTP-запросов)

Схема взаимодействия выглядит следующим образом:

┌─────────────────┐     ┌──────────────────┐     ┌──────────────────────┐
│   Скрипт Zator  │────▶│  Интерпретатор   │────▶│   KoboldCpp Server   │
│  (your_script.  │     │    (zator)       │     │  (localhost:5001)    │
│     zator)      │     └──────────────────┘     └───────────┬──────────┘
└─────────────────┘                                          │
                                                             ▼
                                                    ┌──────────────────────┐
                                                    │  Stable Diffusion /  │
                                                    │   LLM Models (GPU)   │
                                                    └──────────────────────┘
                                                             │
                                                             ▼
                                                    ┌──────────────────────┐
                                                    │   Внешние API        │
                                                    │ (Telegram, Web, etc) │
                                                    └──────────────────────┘

Эта архитектура имеет критически важное следствие: для выполнения любого скрипта Zator требуется предварительно запущенный сервер KoboldCpp с активированными API. По умолчанию интерпретатор ожидает, что сервер доступен по адресу http://localhost:5001, но этот параметр можно изменить через переменную server в скрипте:

server = "http://192.168.1.100:5001"  # Подключение к удаленному серверу

Такая зависимость от внешнего сервиса — осознанный компромисс. С одной стороны, она делает невозможным «автономную» работу без настройки дополнительного ПО. С другой — позволяет мгновенно получать доступ ко всей мощи экосистемы KoboldCpp: поддержке десятков моделей, тонкой настройке параметров генерации, кэшированию контекста и другим продвинутым функциям, которые не пришлось бы реализовывать заново в самом языке.

Два ключевых API-эндпоинта

Вся функциональность генерации контента в Zator построена вокруг двух эндпоинтов KoboldCpp:

1. /api/v1/generate — для генерации текста

При вызове generate_text(prompt, context, max_tokens) интерпретатор формирует JSON-запрос с полным набором параметров:

{
  "max_length": max_tokens,
  "max_context_length": 2048,
  "temperature": 0.7,
  "top_p": 0.9,
  "top_k": 100,
  "rep_pen": 1.1,
  "use_default_badwordsids": false
}

Эти параметры определяют поведение генерации:

Параметр	Описание	Значение по умолчанию	Влияние на результат
temperature	Креативность (0.0–1.0)	0.7	Высокие значения → более неожиданные тексты
top_p	Ядерная выборка (0.0–1.0)	0.9	Ограничивает выбор токенов до вероятностного «ядра»
top_k	Ограничение выборки	100	Меньшие значения → более фокусированный текст
rep_pen	Пенальти за повторение	1.1	Высокие значения уменьшают повторы
max_context_length	Макс. длина контекста	2048	Ограничивает объем «памяти» модели

2. /sdapi/v1/txt2img — для генерации изображений

Вызов generate_img(prompt, context, width, height) преобразуется в запрос с параметрами:

{
  "prompt": "...",
  "negative_prompt": "ugly, deformed, noisy, blurry, distorted",
  "width": 512,
  "height": 512,
  "sampler_name": "Euler a",
  "steps": 20,
  "cfg_scale": 7.0,
  "seed": -1
}

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

Встроенная обработка изображений: Почему это важно

Одна из самых сильных сторон архитектуры Zator — наличие нативных функций для постобработки изображений. В отличие от подхода «сгенерировал — сохранил — обработал во внешнем редакторе», язык позволяет выполнять базовую графическую обработку прямо в пайплайне:

Функция	Описание	Применение
chroma_key_crop()	Хромакей-обработка с обрезкой	Создание спрайтов с прозрачным фоном
scale_to()	Масштабирование (nearest neighbor)	Создание иконок без размытия

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

Типы данных как отражение домена

Архитектура типовой системы Zator напрямую отражает его специализацию. Вместо универсальных типов (строки, числа, массивы, объекты) язык поддерживает ровно три типа, соответствующих этапам генеративного пайплайна:

Тип	Описание	Пример использования
VAR_STRING	Текстовые данные: промпты, сгенерированный текст, контекст	var story = generate_text("Напишите историю...", context, 200)
VAR_INT	Целочисленные значения: размеры изображений, счетчики, параметры	var width = 512
VAR_IMAGE	Внутреннее представление изображения в памяти интерпретатора	var portrait = generate_img("Портрет...", context, 512, 512)

Такая минималистичная типизация — не недостаток, а осознанный дизайн. Она:

• Упрощает обучение (новичку не нужно запоминать десятки типов)

• Предотвращает ошибки (невозможно передать изображение туда, где ожидается текст)

• Отражает реальные этапы работы с генеративным контентом

Особый интерес представляет тип VAR_IMAGE. Это не просто байтовый массив или путь к файлу — это дескриптор изображения в памяти интерпретатора, который автоматически преобразуется в нужный формат при сохранении через save_img(). Такой подход позволяет цепочечно применять функции обработки (chroma_key_crop → scale_to) без промежуточной записи на диск.

Архитектурные ограничения как следствие специализации

Глубокая интеграция с KoboldCpp накладывает и определенные ограничения, которые являются не «багами», а следствием архитектурных решений:

Ограничение	Причина	Обходной путь
Зависимость от внешнего сервера	Архитектурный выбор	Создание инструкции по настройке среды
Циклы без вложенности	Упрощение парсера	Разбиение задачи на несколько скриптов
Одна команда в условии (без {})	Упрощение синтаксиса	Использование скобок для блоков
Рекурсия заблокирована	Защита от бесконечных циклов	Использование итеративных подходов
Требуется curl для request()	Внешняя зависимость	Установка curl в систему

Эти ограничения не делают Zator «неполноценным» языком — они отражают его позиционирование как инструмента для конкретных задач. Как отвертка не предназначена для забивания гвоздей, так и Zator не создан для написания веб-серверов или сложных алгоритмов. Его ценность — в идеальной адаптации к своей нише.

---

Системные требования и настройка среды: Пошаговое руководство

Минимальные и рекомендуемые требования

Прежде чем приступить к написанию скриптов, необходимо подготовить среду выполнения. Zator версии 0.0.2 является кроссплатформенным инструментом:

Компонент	Требование	Примечание
Операционная система	Windows 10/11, Linux, macOS	Кроссплатформенная поддержка в версии 0.0.2
Сервер ИИ	KoboldCpp с активированными API	Обязательно эндпоинты /api/v1/generate и /sdapi/v1/txt2img
Графический ускоритель	NVIDIA GPU с 4+ ГБ VRAM (рекомендуется)	Для генерации изображений через Stable Diffusion
Библиотеки	libpng, zlib, curl	Требуются для обработки изображений и HTTP-запросов
Дисковое пространство	Место под интерпретатор + модели	Модели требуют 2–7 ГБ каждая

Важно понимать: требования к железу определяются не самим Zator, а сервером KoboldCpp, с которым он взаимодействует. Интерпретатор Zator — это легковесное приложение, потребляющее минимум ресурсов. Основная нагрузка ложится на KoboldCpp и подключенные к нему модели.

Установка и настройка KoboldCpp: Критически важный этап

Поскольку Zator полностью зависит от KoboldCpp, правильная настройка сервера — залог успешной работы.

Шаг 1: Скачивание KoboldCpp

1. Перейдите на официальную страницу релизов: https://github.com/LostRuins/koboldcpp/releases

2. Скачайте последнюю версию для вашей ОС

3. Сохраните исполняемый файл в отдельную папку

Шаг 2: Подготовка моделей

1. Для генерации текста: скачайте LLM в формате GGUF (например, Mistral-7B-Instruct-v0.2-Q4_K_M.gguf)

2. Для генерации изображений: скачайте модель Stable Diffusion (например, sd_xl_base_1.0.safetensors)

3. Поместите модели в соответствующие папки относительно исполняемого файла KoboldCpp

Шаг 3: Запуск сервера с правильными флагами

koboldcpp.exe ^
--model "path/to/model.gguf" ^
--sd-model "path/to/sd_model.safetensors" ^
--api ^
--sdapi ^
--port 5001

Ключевые флаги:

• --api — включает эндпоинт /api/v1/generate для текстовой генерации

• --sdapi — включает эндпоинт /sdapi/v1/txt2img для генерации изображений

• --port — определяет порт сервера (по умолчанию 5001)

Шаг 4: Проверка работоспособности

curl http://localhost:5001/api/v1/model

Если сервер работает, вы получите JSON с информацией о загруженной модели.

Установка интерпретатора Zator

1. Скачайте последнюю версию интерпретатора с официального сайта

2. Поместите файл в удобную директорию

3. Добавьте директорию в переменную среды PATH (опционально)

Проверка установки:

zator --version

Структура проекта

Все пути в скриптах Zator являются относительными к директории запускаемого скрипта:

my_project/
├── scripts/
│   └── main.zator
├── characters/
├── stories/
├── utils.zator
└── api_calls.zator

---

Синтаксис языка Zator: Минимализм как принцип

Комментарии и роль контекста

Синтаксис Zator спроектирован с акцентом на читаемость и минимизацию «шума». Комментарии используют знак #:

# Это однострочный комментарий
# Комментарии игнорируются интерпретатором и служат для документирования кода
var important_value = 42  # Комментарий после кода тоже допустим

Ключевая синтаксическая особенность Zator — глобальная переменная context. В отличие от обычных переменных, объявляемых через var, контекст задается напрямую и влияет на все последующие вызовы генерации:

context = "Вы — писатель фэнтези, специализирующийся на коротких историях о приключениях."
var story = generate_text("Напишите историю о драконе.", context, 200)
# Промпт, отправленный в KoboldCpp, будет:
# "Вы — писатель фэнтези... Напишите историю о драконе."

Контекст выполняет несколько важных функций:

1. Определяет роль модели — задает «личность» ИИ (писатель, дизайнер, поэт)

2. Устанавливает стиль — указывает на предпочтительный жанр, тон, уровень детализации

3. Обеспечивает согласованность — при генерации последовательных фрагментов контекст сохраняется между вызовами

Типы данных и объявление переменных

Zator поддерживает строго три типа данных:

Текстовые переменные (VAR_STRING)

var greeting = "Привет, мир!"  # Простая строка
var username = "Алексей"       # Переменная для хранения имени
var story = generate_text("Напишите короткую историю о кобольде", context, 200)

Целочисленные переменные (VAR_INT)

var counter = 42        # Простое число
var score = 85          # Оценка или рейтинг
var image_width = 512   # Размер изображения
var doubled = counter * 2  # 84

Важное ограничение: Дробные числа не поддерживаются. Все вычисления выполняются в целочисленной арифметике.

Переменные изображений (VAR_IMAGE)

var portrait = generate_img("Портрет эльфа", context, 512, 512)
# Нельзя объявить изображение напрямую — это вызовет ошибку

F-строки: Сердце выразительности Zator

Одна из самых мощных особенностей Zator версии 0.0.2 — повсеместная поддержка форматированных строк (F-строк). Синтаксис: {имя_переменной}:

var name = "Элара"
var race = "эльфийка"
var greeting = "Привет, {name}! Рад знакомству с {race}."
print(greeting)
# Выведет: "Привет, Элара! Рад знакомству с эльфийка."

Где работают F-строки в версии 0.0.2

Место использования	Пример
В присваиваниях	var x = "Привет, {name}"
В ��ргументах функций	print("Привет, {name}")
В путях к файлам	save_img(img, "characters/{name}.png")
В контексте и промптах	context = "Вы — {profession}"
В параметрах функций	call greet("{prefix} Артур")
В request() и exec_cmd()	exec_cmd("cat {filename}")

Экранирование фигурных скобок

Для вывода литеральных фигурных скобок используйте обратный слеш:

var text = "Используйте \{variable\} для подстановки"
print(text)  # Выведет: "Используйте {variable} для подстановки"

Управляющие конструкции

Условные операторы

if score > 80 {
    print("Отличный результат!")
} else if score > 60 {
    print("Хороший результат!")
} else {
    print("Нужно улучшить результат.")
}

# Поддержка двух условий, соединенных 'and'
if score > 80 and level == "expert" {
    print("Отличный результат для эксперта!")
}

Поддерживаемые операторы сравнения:

Оператор	Описание	Типы данных
==	Равно	Строки и числа
!=	Не равно	Строки и числа
>	Больше	Только целые числа
<	Меньше	Только целые числа
>=	Больше или равно	Только целые числа
<=	Меньше или равно	Только целые числа

Важно: Условные блоки поддерживают несколько команд внутри скобок {}. Без скобок поддерживается только одна команда.

Циклы

var countdown = 5
repeat 10 {
    countdown = countdown - 1
    print("Осталось времени: {countdown}")
    if countdown <= 0 {
        print("Цикл прерван досрочно")
        break
    }
}

Особенности циклов:

• Синтаксис repeat N { ... } выполняет блок ровно N раз

• Поддерживается оператор break для досрочного выхода

• Не поддерживаются вложенные циклы — попытка разместить repeat внутри другого repeat вызовет ошибку

• Циклы не имеют встроенной переменной-счетчика — ее нужно объявлять и инкрементировать вручную

Пользовательские функции (Новое в 0.0.2)

Функции позволяют группировать код и повторно использовать его. Поддерживаются параметры как в Python.

Синтаксис определения

def function_name(param1, param2, ...) {
    # тело функции
}

Синтаксис вызова

call function_name(arg1, arg2, ...)

Примеры использования

Без параметров:

def greet {
    print("Привет, мир!\n")
}
call greet()

С одним параметром:

def greet_user(name) {
    print("Привет, {name}!\n")
}
call greet_user("Алексей")
call greet_user("Мария")

С несколькими параметрами:

def create_character(name, char_class, background) {
    var prompt = "Портрет персонажа: {name}, класс: {char_class}, {background}"
    var character = generate_img(prompt, context, 512, 512)
    save_img(character, "characters/{name}.png")
    print("Персонаж {name} создан!\n")
}

call create_character("Гаррет", "Вор", "тёмный переулок")
call create_character("Элеонора", "Маг", "башня волшебника")

С f-строками в аргументах:

var prefix = "Сэр "
call greet_user("{prefix} Артур")

Параметры функций

Характеристика	Описание
Максимум параметров	До 10 на функцию
Передача	По значению (копируются в локальные переменные)
Поддержка f-строк	Да, в параметрах
Тип	Строка (автоматическое преобразование из int)

Ограничения функций

• Рекурсия обнаруживается и блокируется (защита от бесконечного цикла)

• Параметры функции становятся локальными переменными на время выполнения

• При вложенных вызовах значения параметров сохраняются и восстанавливаются

Импорт файлов (Новое в 0.0.2)

Команда #import позволяет включить код из другого .zator файла в текущий скрипт:

#import "utils.zator"
#import "api_calls.zator"

# Используем функции или переменные из импортированных файлов
call some_util_function

Пример структуры с импортом:

Файл utils.zator:

def log_message(msg) {
    print("[LOG] {msg}")
}

Файл main.zator:

#import "utils.zator"

call log_message("Запуск скрипта")
# ... основной код ...
call log_message("Завершение")

---

Встроенные функции: Мощь в трех строках кода

Функции генерации контента

generate_text(prompt, context, max_tokens)

Генерирует текст через LLM.

var result = generate_text(prompt, context, max_tokens)

Параметры:

Параметр	Тип	Описание
prompt	VAR_STRING	Текстовый запрос к модели
context	VAR_STRING	Глобальный контекст
max_tokens	VAR_INT	Максимальное количество токенов

Пример:

context = "Вы — писатель фэнтези."
var story = generate_text("Напишите историю о драконе.", context, 200)
save_txt(story, "stories/dragon.txt")

generate_img(prompt, context, width, height)

Генерирует изображение через Stable Diffusion.

var image = generate_img(prompt, context, width, height)

Параметры:

Параметр	Тип	Описание
prompt	VAR_STRING	Описание изображения
context	VAR_STRING	Контекст для уточнения стиля
width	VAR_INT	Ширина в пикселях (кратно 64)
height	VAR_INT	Высота в пикселях (кратно 64)

Пример:

context = "Вы — дизайнер игровых персонажей."
var character_img = generate_img("Кобольд-маг, зеленый фон", context, 512, 512)
save_img(character_img, "characters/cobold_mag.png")

Рекомендации:

• Размеры должны быть кратны 64 пикселям для лучшей совместимости с VRAM

• Для персонажей используйте соотношение 1:1 (512×512)

• Для пейзажей — 16:9 или 3:2 (768×512, 1024×683)

Функции обработки изображений

chroma_key_crop(source_image, x, y[, tolerance])

Обрезает изображение по цвету пикселя в координатах (x, y).

var cropped = chroma_key_crop(source_image, x, y[, tolerance])

Параметры:

Параметр	Тип	Описание
source_image	VAR_IMAGE	Исходное изображение
x	VAR_INT	Координата X пикселя цвета фона
y	VAR_INT	Координата Y пикселя цвета фона
tolerance	VAR_INT	Допуск в процентах (0.0-100.0), по умолчанию 0.0

Пример:

var photo = generate_img("Фотография на зеленом фоне", context, 512, 512)
var subject = chroma_key_crop(photo, 10, 10, 5.0)
save_img(subject, "output/subject.png")

Рекомендации:

• Всегда генерируйте объекты на чистом однотонном фоне (зеленый #00FF00 или синий #0000FF)

• Выбирайте координаты (x, y) в углах изображения, где гарантированно находится фон

• Начинайте с низкого tolerance (1.0–3.0%) и увеличивайте только при необходимости

scale_to(source_image, width, height)

Масштабирует изображение (алгоритм nearest neighbor).

var scaled = scale_to(source_image, width, height)

Параметры:

Параметр	Тип	Описание
source_image	VAR_IMAGE	Исходное изображение
width	VAR_INT	Целевая ширина
height	VAR_INT	Целевая высота

Пример:

var icon = scale_to(subject, 128, 128)
save_img(icon, "output/icon.png")

Важно: Масштабирование следует выполнять после хромакей-обработки.

Работа с файлами

save_txt(variable, "path")

Сохраняет текст в файл.

save_txt(story, "stories/my_story.txt")

save_img(variable, "path")

Сохраняет изображение в PNG.

save_img(img, "images/landscape.png")

Особенности:

• Все пути относительные к директории скрипта

• Изображения сохраняются в формате PNG

• Директории создаются автоматически при необходимости

input(variable)

Читает строку из stdin.

print("Введите ваше имя:")
input(username)
print("Здравствуйте, {username}!")

Важные особенности:

• Функция не принимает приглашение к вводу как аргумент

• Для отображения приглашения нужно использовать отдельный вызов print()

• Ввод завершается нажатием клавиши Enter

HTTP-запросы (Новое в 0.0.2)

request(url, method, response [, body])

Выполняет HTTP-запрос к внешнему API.

var response
request(url, method, response [, body])

Параметры:

Параметр	Тип	Описание
url	VAR_STRING	Адрес конечной точки API
method	VAR_STRING	HTTP-метод (GET, POST, PUT, DELETE)
response	VAR_STRING	Переменная для ответа сервера
body	VAR_STRING	Тело запроса (для POST и PUT)

Пример GET-запроса:

var response
request("https://api.example.com/status", "GET", response)
print(response)

Пример POST-запроса (Telegram Bot):

var token = "YOUR_BOT_TOKEN"
var chat_id = "YOUR_CHAT_ID"
var message = "Hello from Zator!"

var json_body = "{ \"chat_id\": \"{chat_id}\", \"text\": \"{message}\" }"
var api_url = "https://api.telegram.org/bot{token}/sendMessage"

var response
request(api_url, "POST", response, json_body)
print("Telegram API response: {response}")

Требование: Наличие установленной библиотеки curl в системе.

Системные команды (Новое в 0.0.2)

exec_cmd("command") или exec_cmd("command", output_var)

Выполняет команды командной строки.

var output = exec_cmd("command")
# или
exec_cmd("command", output_var)

Параметры:

Параметр	Тип	Описание
command	VAR_STRING	Команда для выполнения (поддерживает f-строки)
output_var	VAR_STRING	Переменная для сохранения вывода

Примеры:

Получение списка файлов:

var files = exec_cmd("ls -la")
print("Files: {files}")

Команда с переменной:

var filename = "data.txt"
var content = exec_cmd("cat {filename}")
print("Content: {content}")

Альтернативный синтаксис:

exec_cmd("pwd", current_dir)
print("Directory: {current_dir}")

Конвейеры команд:

var process_info = exec_cmd("ps aux | grep {filename} | head -5")
print("Process info: {process_info}")

⚠️ Предупреждение о безопасности:
Используйте exec_cmd с осторожностью, особенно с пользовательским вводом, чтобы избежать инъекций команд.

Вспомогательные функции

emit_c("path")

Сохраняет встроенный пример C-кода в указанный путь.

emit_c("embedded/example.c")

---

Практические туториалы: От первого скрипта к реальному пайплайну

Туториал 1: Генерация персонажа с обработкой

context = "Вы — дизайнер игровых персонажей."

# Генерация
var character_img = generate_img("Кобольд-маг, зеленый фон", context, 512, 512)

# Обработка
var character_cropped = chroma_key_crop(character_img, 10, 10, 3.0)
var character_icon = scale_to(character_cropped, 64, 64)

# Сохранение
save_img(character_cropped, "characters/cobold_mag.png")
save_img(character_icon, "characters/icons/cobold_mag.png")

print("Персонаж успешно создан!")

Туториал 2: Использование функций и импорта

Файл utils.zator:

def log_message(msg) {
    print("[LOG] {msg}")
}

Файл main.zator:

#import "utils.zator"

call log_message("Запуск скрипта")
# ... основной код ...
call log_message("Завершение")

Туториал 3: Внешний API (Telegram Bot)

var token = "YOUR_BOT_TOKEN"
var chat_id = "YOUR_CHAT_ID"
var message = "Hello from Zator!"

# Формируем тело запроса
var json_body = "{ \"chat_id\": \"{chat_id}\", \"text\": \"{message}\" }"
var api_url = "https://api.telegram.org/bot{token}/sendMessage"

var response
request(api_url, "POST", response, json_body)
print("Telegram API response: {response}")

Туториал 4: Системные команды

# Проверка файла
var check = exec_cmd("test -f data.txt && echo 'exists' || echo 'missing'")

if check == "exists" {
    var content = exec_cmd("cat data.txt")
    print("Content: {content}")
} else {
    print("File not found!")
}

# Информация о системе
var os_info = exec_cmd("uname -a")
print("OS: {os_info}")

Туториал 5: Интерактивный генератор контента

context = "Вы — помощник по созданию контента."

print("Введите своё имя:")
input(username)
print("Привет, {username}! Выберите тип контента:")
print("1 — Текстовая история")
print("2 — Изображение персонажа")
input(choice)

if choice == "1" {
    print("Введите тему истории:")
    input(theme)
    var prompt = "Напишите короткую историю на тему '{theme}' в стиле фэнтези."
    var tokens = 250
    var content = generate_text(prompt, context, tokens)
    print("\nВаша история:\n{content}")

    print("\nСохранить в файл? (да/нет)")
    input(save_choice)
    if save_choice == "да" {
        save_txt(content, "stories/{username}_{theme}.txt")
    }
}

if choice == "2" {
    print("Введите описание персонажа:")
    input(description)
    var prompt = "Портрет персонажа: {description}, цифровое искусство"
    var character_img = generate_img(prompt, context, 512, 512)
    save_img(character_img, "characters/{username}_character.png")
    print("Изображение сохранено!")
}

---

Сравнительный анализ и ограничения

Zator против Python

Критерий	Zator (0.0.2)	Python
Количество строк	Минимальное (DSL)	Требует бойлерплейта
Функции	Поддерживаются (до 10 параметров)	Полная поддержка
HTTP/Система	Встроенные request, exec_cmd	Требуется requests, subprocess
Платформы	Windows, Linux, macOS	Кроссплатформенно
Гибкость	Ограничена доменом	Универсальный
Зависимости	KoboldCpp + curl	Множество библиотек
Порог входа	Низкий	Средний/Высокий

Таблица применения

Сценарий	Рекомендация	Обоснование
Массовая генерация игровых ассетов	✅ Идеально	Встроенные функции хромакей и масштабирования
Создание иллюстраций к тексту	✅ Отлично	Простая интеграция текстовой и визуальной генерации
Прототипирование пайплайнов	✅ Идеально	Минимальный код для быстрой проверки идей
Сложные алгоритмы обработки	⚠️ Ограниченно	Отсутствие вложенных циклов и функций
Веб-приложения	❌ Не подходит	Отсутствие веб-фреймворков
Интеграция с облачными сервисами	✅ Поддерживается	Через request() и exec_cmd()

Текущие ограничения (Версия 0.0.2)

Ограничение	Описание	Обходной путь
Циклы без вложенности	Нельзя помещать repeat внутрь repeat	Разбиение на несколько скриптов
Условия без {}	Только одна команда	Использовать скобки для блоков
Рекурсия заблокирована	Защита от бесконечных циклов	Итеративные подходы
Требуется curl	Для функции request()	Установка curl в систему
Безопасность exec_cmd	Риск инъекций команд	Валидация пользовательского ввода
Нет массивов	Отсутствие структур данных	Использование отдельных переменных

Планы развития

1. Поддержка вложенных условных блоков — устранение текущего ограничения

2. Функции для наложения изображений — комбинирование нескольких изображений

3. Интеграция с другими AI API — DALL-E, Midjourney и другие сервисы

4. Оптимизация памяти — работа с большими изображениями

5. Встроенный JSON-парсер — упрощение работы с API

6. Поддержка массивов и списков — структуры данных для сложных сценариев

---

История версий

Версия	Дата	Изменения
0.0.2	2026-02-20	Функции, параметры функций, импорт библиотек, HTTP-запросы, exec_cmd, исправлен порядок выполнения, кроссплатформенность
0.0.1	2025-12-15	Добавлена обработка изображений (chroma_key, scale)
0.0.0	2025-10-01	Первая версия с генерацией текста и изображений

---

Заключение

Zator версии 0.0.2 представляет собой зрелый инструмент для автоматизации генеративных пайплайнов. Добавление поддержки функций, HTTP-запросов и системных команд в этой версии превращает его из простого скриптового языка в мощную платформу для интеграции AI-моделей в рабочие процессы.

Ключевые преимущества версии 0.0.2:

• Модульность — пользовательские функции и импорт файлов позволяют создавать переиспользуемые библиотеки

• Интеграция — HTTP-запросы открывают доступ к внешним API (Telegram, Discord, веб-сервисы)

• Автоматизация — системные команды позволяют управлять файлами и процессами ОС

• Кроссплатформенность — работа на Windows, Linux и macOS

• Удобство — улучшенная поддержка f-строк во всех функциях

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

---

Полезные ресурсы

• Официальный сайт: http://zapor.2bd.net

• GitHub репозиторий: https://github.com/4ds-dev/zator

• KoboldCpp: https://github.com/LostRuins/koboldcpp

• Stable Diffusion: https://stability.ai/

Статья актуализирована на основе документации версии 0.0.2 от 20 февраля 2026 года.