AI-справка

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

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

Правило простое: помещается в один файл — AI-справка, требует самого магазина — AI-помощник.

Что это

Встроена в редактор. Работает с любой моделью, совместимой с API OpenAI: в поставке есть примеры для Groq, Google, OpenAI и OpenRouter, но список свободный — подключить можно любого совместимого провайдера, указав адрес и ключ.

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

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

Настройка агентов

«Настройки редактора → Агенты AI-справки». Таблица агентов, под ней — поле системного промпта для выбранной строки.

Колонка Что задаёт
Быстрая справка агент попадает в меню F1
Анализ файла агент попадает в меню Shift + F1
Название произвольное имя, под которым агент виден в меню выбора
Модель идентификатор модели у провайдера
Адрес endpoint, совместимый с OpenAI (.../chat/completions)
Ключ API-ключ провайдера
Таймаут сколько ждать ответа, секунд
Температура разброс ответов, от 0 до 1

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

У всех поставляемых агентов промпт начинается с описания платформы — что перед моделью не проект на фреймворке, а юнит Melbis: php-файл, манифест рядом, виды .htm, обращение к движку через MELBIS(), теги {MELBIS:...} вместо Smarty, многоуровневый кеш. Там же прямой запрет предлагать привычки Laravel и Symfony и выдумывать имена методов, и адрес документации — melbis.com/help/en, — чтобы модель, когда не уверена, называла раздел, а не сочиняла API.

Это не справочник: научить модель платформе одним абзацем нельзя, да и не нужно. Задача абзаца — задать рамку, в которой она перестаёт отвечать «как про обычный PHP». Со временем нужда в нём будет отпадать: документация Melbis открыта, и новые модели знают её уже сами.

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

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

Уровни в названиях

Junior, Middle и Senior в именах поставляемых агентов — это соглашение поставки, а не механизм платформы: платформа читает только модель, адрес и ключ.

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

Ключи провайдеров

Вызов из редактора

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

F1 — быстрая справка

Отправляет слово под курсором, а если есть выделение — выделенный фрагмент. Ответ приходит размеченным и показывается в панели AI-справки. Это основной режим: встретили незнакомую функцию — поставили курсор, нажали F1.

Агенты берутся из тех, что отмечены в колонке «Быстрая справка».

Ctrl + F1 — запрос с уточнением

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

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

Shift + F1 — анализ файла

Отправляет файл целиком, с проставленными номерами строк. К промпту при этом дописывается требование вернуть строго один JSON-объект заданной формы:

{result:[{
    line_start:  номер начальной строки фрагмента,
    line_end:    номер последней строки,
    type:        ERROR | WARNING | NOTICE,
    description: описание,
    replace:     готовый код на замену
    }]}

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

Именно из-за строгого формата ответа в этот режим ставят модели посильнее: слабая модель охотно сбивается на пояснения вокруг JSON, и разбор не удаётся. Если ответ разобрать не получилось, среда сообщит об ошибке формата.

Агенты берутся из отмеченных в колонке «Анализ файла».

Уточняющий вопрос

После ответа в режимах F1 и Ctrl + F1 доступна кнопка уточнения. Она переносит предыдущий запрос вместе с полученным ответом в контекст нового вопроса — так короткая справка превращается в диалог, и агент помнит, о чём шла речь. Каждое уточнение накапливает контекст, поэтому длинные цепочки стоит начинать заново, а не наращивать бесконечно.

Практические замечания

Температура. Для работы с кодом её снижают: у поставляемых агентов анализа стоит 0,2, у справочных — 1. Чем ниже значение, тем предсказуемее и суше ответ; для поиска ошибок это то, что нужно.

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

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