Интерфейс чата сайта
Обновлено
Назначение
В коде плагина есть PHP-интерфейс agentMcpSiteChat для интеграции с каналом сайта. Он принимает текстовые сообщения, готовит ответ и возвращает результат вызывающей стороне. Это интерфейс для разработчика: данный плагин не предоставляет готовый виджет посетителя, Smarty-хелпер или страницу настройки источников сайта.
Доставка сообщений посетителю, выбор поселений и источников, расписание выполнения и учёт бюджета канала должны обеспечиваться интеграцией. Сам agentMcpSiteChat не отправляет сообщения CRM.
Подготовка
Загрузите плагин перед обращением к его классам:
wa('mcp')->getPlugin('agent');Нужен общий агент с настроенной разрешённой моделью и сотрудник исполнения с доступом к MCP, плагину, выбранному агенту и CRM. Контекст содержит role_id — ID агента, executor_id — ID сотрудника, skills — явный массив ключей справочников, instructions — инструкции канала (до 3000 символов). Источники задаются доверенной серверной конфигурацией sources, а не параметрами посетителя.
Проверка готовности с уже подготовленным контекстом:
$is_available = agentMcpSiteChat::available($context);Методы
| Метод | Назначение |
|---|---|
available(array $context = []): bool |
Проверка выбранного агента, исполнителя и модели |
roles(): array |
Список общих агентов с настроенной разрешённой моделью; без промптов и ключей |
skills(): array |
Оглавление справочников без полных текстов; служебный справочник канала не включается |
enqueue(int $crm_conversation_id, array $new_messages, array $context): int |
Импорт новых текстовых сообщений и создание хода; возвращает ID хода |
advance(int $run_id, float $budget_sec, callable $reserve, ?callable $settle = null): array |
Выполнение отрезка хода с обязательным резервированием и учётом расхода |
result(int $run_id): array |
Получение состояния, текста ответа и расхода |
cancel(int $run_id): void |
Запрос отмены хода канала сайта |
purge(int $crm_id): bool |
Удаление связанного разговора; может вернуть false, если выполняющийся ход ещё мешает удалению |
enqueue() вызывается под именной блокировкой CRM, вне транзакции вызывающей стороны. Каждое сообщение содержит устойчивый положительный id, direction (IN или OUT), строку text; для исходящих можно передать operator_name. В одной пачке — не более 1000 сообщений, повторяющиеся ID внутри пачки не допускаются.
advance() принимает бюджет начала новых запросов в секундах: больше 0 и не больше 55. Несмотря на значение null в сигнатуре, обработчик $settle обязателен. $reserve получает оценку расхода и должен атомарно разрешить или отклонить резерв; $settle учитывает фактический расход после принятого резерва. Восстановление резервов при авариях должен обеспечивать канал. Запускать выполнение без такого учёта нельзя.
result() возвращает поля state, reply, handoff_reason, tokens, error. Помимо обычного завершения возможны передача оператору (handoff) и завершение вопроса вне тематики (offtopic). Обработку этих состояний реализует вызывающий канал.
Инструменты публичных знаний
У канала сайта отдельный список инструментов: обычный реестр MCP ему не передаётся. Нужны соответствующие приложения, выбранные публичные поселения и разрешённые элементы источников.
| Инструмент | Источник и назначение |
|---|---|
site_search_docs |
Поиск по разрешённой документации приложения «Код» |
site_get_doc |
Чтение найденной статьи документации по ID |
site_search_faq |
Поиск по разрешённым публичным разделам FAQ приложения «Поддержка» |
site_search_hub |
Поиск по разрешённым публичным хабам |
site_get_hub_topic |
Чтение найденной темы по ID |
site_search_products |
Поиск публичных товаров выбранной витрины Магазина |
site_get_product |
Чтение товара по публичному URL из результатов поиска |
agent_read_skill |
Чтение явно разрешённого справочника |
request_operator |
Возврат состояния передачи оператору с причиной |
mark_offtopic |
Завершение вопроса вне тематики с коротким ответом |
В sources используются ключи code, faq, hub, shop. Для выбранного маршрута передаются route.domain и route.url; разрешённые элементы ограничиваются списками projects, categories или hubs соответствующего источника. Конфигурация должна формироваться сервером и проверяться интеграцией. Недоступный источник исключается из набора инструментов.
Канал не получает инструменты заказов и контактов из роли MCP, произвольное чтение URL, рисование, просмотр картинок или изменение справочников. В обычных личных чатах сохраняется обычный набор инструментов агента. Текст канала и найденные публичные знания передаются выбранной модели для подготовки ответа.