1. Руководство пользователя › 1.5 Проектирование › AI-компоненты

Окно «Проектирование → AI-компоненты» — всё, что магазин даёт AI-помощнику, на трёх вкладках:

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

Как помощник всем этим пользуется — «AI-помощник». Окно редактируется в режиме блокировки: правки применяются кнопками «Сохранить» / «Сохранить и выйти» (см. «Три режима работы с данными»). Открыть окно позволяет право «Проектирование → AI-компоненты → Получить», сохранить — «Сохранить».

AI-инструменты

Всё, что AI-помощник умеет, одинаково в любом магазине Melbis: файлы, данные, деревья, витрина. AI-инструменты — исключение: их пишет владелец под свой магазин. Завести товар так, как заводит его именно он, с его проверкой дублей и его расчётом цены; закрыть заказ по его правилам.

Список инструментов — данные, а не код: заведённая строка появляется у помощника со следующим подключением, и обновлять для этого ни программу, ни движок не нужно.

Инструмент стоит завести, когда видно одно из двух:

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

Слева «Каталог инструментов», справа «Команды инструмента» выбранного, а под ними у выбранной команды две вкладки: «Параметры команды» и «Права на команду».

Каталог устроен как остальные деревья программы: разделы-папки для группировки, признак группы ставится кнопкой на панели. Папка инструментом не является — у неё нет ни команд, ни разрешений, и помощнику она не видна.

Команду можно перенести в другой инструмент: строки, перетащенные из таблицы команд на инструмент в каталоге, переезжают к нему. Папка их не принимает.

Карточка инструмента

Поле	Что задаёт
Наименование	имя строки в каталоге; помощник видит его как название инструмента
Модуль	имя файла модуля в папке `units`; им же помощник зовёт инструмент
Описание для AI-помощника	что инструмент делает и когда его звать

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

Модуль готовит разработчик — как устроен такой модуль, описано в разделе «AI-инструменты» руководства разработчика.

Команды

Поле	Что задаёт
Команда	слово, которым помощник называет одно дело инструмента
Описание для AI-помощника	что команда делает, когда её звать и чего она не делает

Порядок строк задаётся стрелками — в этом же порядке команды видит помощник.

Имя команды — это имя функции модуля, которая её выполняет: CmdList, CmdAdd, CmdUpdate, CmdRemove. Приставка Cmd отличает команду от внутренних функций модуля, которых помощник не видит.

Список команд — ещё и защита от выдумки: слово, которого инструмент не объявлял, движок отбивает сразу и перечисляет в ответе объявленные.

Поля команды тоже объявляются здесь, по строке на поле: имя, описание, тип (число, строка, да/нет, день, час, json, поток строк, файлы), обязательность и значение по умолчанию. По этим строкам движок сам проверяет каждый вызов до модуля: лишнее поле, пропущенное обязательное или число, присланное словом, возвращаются отказом — разработчику модуля эта рутина не достаётся вовсе.

К типу можно дописать /json — тогда поле принимает и одно значение, и список: int/json для «одного товара или сразу нескольких», float/json для диапазона цены, datetime/json для «с такого дня по такой». Каждое значение списка движок проверяет тем же типом, поэтому список остаётся таким же защищённым, как одиночное значение.

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

Права

Право выдаётся на команду — отметкой на пересечении «команда × сотрудник или группа». Сколько у инструмента команд, столько отдельных разрешений: можно позволить читать список, не позволяя добавлять и менять. Права сотрудника и его групп складываются.

Права раздаются людям, а не помощнику. Помощник работает от имени сотрудника, который его запустил (см. «AI-помощник»), и грант считается по этому человеку. Отсюда и то, что один и тот же инструмент у разных сотрудников умеет разное.

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

Перечень инструментов и команд помощник видит целиком, независимо от прав, — и про невыданную команду отвечает адресом, а не «доступа нет»: какая команда какого инструмента и где её выдают. Этот адрес и стоит передать администратору как есть. Сотрудник, которому разрешено сохранять настройки AI, владеет всеми командами автоматически — о чём и говорит сноска под таблицами разрешений.

Готовые инструменты

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

Пара примеров, как это выглядит:

Планировщик — агент ставит задачу от имени сотрудника, и она появляется у исполнителя как новая (см. «Планировщик»);
Цены — читает и меняет ценовые поля товара ровно теми же колонками, что окно цен программы;
Профили — рецепты производных картинок, те самые, что в программе задаются в редакторе изображений, — обычными словами вместо XML (см. «Файлы»);
Импорт товаров и Импорт файлов — пара для партии: помощник готовит данные файлом (парсер сайта, прайс, выгрузка) и заводит разом сотни товаров с характеристиками, а вторым вызовом раскладывает фотографии, попутно вырезая производные картинки по профилю. Товары рождаются скрытыми и «нет в наличии» — партию сперва смотрят, потом открывают покупателю.

Они же служат образцами для разработки собственных.

AI-память

Заметки, которые помощник ведёт о магазине: правила работы, распоряжения сотрудников, решения и их причины. Помощник читает их в начале работы, поэтому следующая сессия — на другом компьютере, в другом приложении — начинается не с нуля. Здесь видна вся память: кто может открыть окно, видит заметки всех сотрудников.

Слева дерево «Пользователи»: «Все пользователи», под ним группы, в каждой — её сотрудники. Узел решает, чья заметка:

Узел	Чья заметка	Кто пишет
«Все пользователи»	для всех сотрудников	администратор, в этом окне
группа	для сотрудников группы, основной или дополнительной	администратор, в этом окне
сотрудник	его собственная	помощник этого сотрудника, с его согласия; администратор — здесь

Справа «Заметки» выбранного узла, строки окрашены по типу, под таблицей — текст текущей заметки. Порядок меняют «Переместить вверх» и «Переместить вниз».

Передать заметку — перетащить её из таблицы на другой узел дерева: заметка переедет туда. С нажатым Ctrl она скопируется — так правило, которое помощник записал одному сотруднику, отдают всей группе, а у автора оно остаётся.

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

Карточка заметки

Поле	Что задаёт
Тип	вид заметки, см. ниже
Категория	свободные слова, по которым заметки группируются; список предлагает уже занятые, можно вписать новые
Время	когда заметку правили последний раз; ставится само
Название	короткое имя заметки
Описание для AI-помощника	одна строка о том, про что заметка
Текст заметки	сама заметка; двойной щелчок открывает визуальный редактор, вторая кнопка поля — исходный HTML

Чья это заметка, в карточке не задаётся: это узел дерева, под которым её добавили.

Помощник читает память в два приёма: сначала названия и описания всех заметок, потом текст тех, что относятся к делу. Поэтому описание пишется для этого выбора — о чём заметка, а не её пересказ.

Тип	Что это
Критическое	что соблюдается в каждой сессии; такие заметки помощник читает до любой другой работы
Приказ	распоряжение сотрудника
Навык	как работать с этим человеком
По умолчанию	всё остальное

Свои типы добавляют в «Реестре настроек», на закладке «Базовые настройки»; помощник считает их как «По умолчанию».

Когда заметки расходятся, «Критическое», «Приказ» и «Навык» старше остальных типов, а среди них заметка для всех старше групповой, групповая — старше своей.

AI-репозиторий

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

Слева «Разделы репозитория» — дерево с обычными действиями: добавить раздел или подраздел, редактировать, удалить, переместить, перетащить ветку. Папка (признак группы) только группирует разделы: ни тем, ни прав у неё нет. Новый подраздел получает копию прав родителя, дальше их правят отдельно.

Карточка раздела

Поле	Что задаёт
Тип	«Персональный» — рабочие данные помощника одного сотрудника; «Общий» — то, что нужно помощникам всех сотрудников; «По умолчанию» — без отметки
Наименование	имя раздела в дереве
Ключ	короткое имя, по которому помощник может найти раздел
Описание для AI-помощника	для чего раздел: по нему помощник решает, что сюда класть

Тип ничего не ограничивает: кто видит раздел, решают его права.

Права доступа

Вкладка «Права доступа» выбранного раздела: «Разрешения для групп пользователей» и «Разрешения для пользователей», по шесть флажков в строке. Щелчок по ячейке ставит или снимает флажок.

Флажок	Что разрешает помощнику
Темы — Список	видеть темы раздела
Темы — Создание	заводить новые темы
Темы — Изменение	менять название, описание и параметры любой темы раздела
Темы — Удаление	удалять любую тему вместе со всеми её записями
Данные — Чтение	читать записи тем
Данные — Запись	добавлять записи

Права сотрудника и его групп — основной и дополнительных — складываются. Раздел без единого флажка помощнику не виден. Сотруднику с правом сохранять это окно открыты все разделы со всеми флажками. Строка, в которой сняты все флажки, убирается при сохранении окна.

Флажки решают, какое действие пройдёт внутри раздела. Сам же репозиторий помощнику открывают права ветки «AI-помощник → Репозиторий» у сотрудника (см. «Пользователи и права доступа»).

Личный раздел сотрудника. Заведите раздел с типом «Персональный», в описании назовите, чей он, и дайте права только этому сотруднику. Если личные разделы есть у всех, одна заметка памяти для всех может сказать помощникам, как искать свой: например, «Персональный» раздел с ключом, равным номеру (ID) сотрудника.

Темы и данные

Вкладка «Темы и данные» показывает, что помощники написали в выбранный раздел. С сервера всё приходит по кнопкам:

«Получить темы раздела» — таблица «Темы»: тема, описание и параметры — свободные слова, по которым тему находят;
«Получить данные темы» — записи выбранной темы в таблице «Данные».

Запись не меняется: каждая новая добавляется к теме, последняя — то, на чём тема стоит сейчас, ранние — её история. Поэтому «Получить данные темы» докачивает только записи новее уже полученных, а текст записи приходит, когда на неё встаёт курсор.

У записи три вкладки:

«Сводка» — время; пользователь — сотрудник, чей помощник писал; автор — сам помощник: модель и её настройки; комментарий — одна строка о том, что запись изменила;
«Содержимое» — всё состояние темы;
«Приложение» — данные к записи, которые помощник читает, только когда они нужны.

Содержимое и приложение показываются как текст, как скрипт (с подсветкой Python) или как HTML-документ — вид выбирается в списке.

Смотреть темы и записи позволяют права «Проектирование → AI-компоненты → Репозиторий → Получить темы» и «Получить данные». Флажки разделов действуют на помощников, а не на это окно.

Экспорт

Кнопка «Экспорт» на панели каталога инструментов собирает все инструменты с командами и полями, их модули и библиотеки в один архив <магазин> tools <дата>.zip. Так набор инструментов переносят в другой магазин или хранят про запас. Разрешения в архив не входят — они про людей этого магазина; память и репозиторий тоже.

Архив собирает сервер из того, что на него уже отправлено: несохранённые правки окна в архив не войдут, о чём программа и предупреждает. Нужно право «Проектирование → AI-компоненты → Экспорт».

Загрузки обратно нет, и это решение: в каждом магазине инструменты дорабатывают под себя, поэтому архив не накатывают, а сравнивают с магазином. Отдайте архив помощнику и попросите перенести разошедшееся — он сверит и перенесёт точечно.