Простыми словами: из чего он состоит, что за что отвечает, как проходит одно сообщение от клиента до ответа, что бот умеет, чего пока не умеет и где это всё крутить.
В углу сайта висит кнопка чата. Клиент пишет вопрос — отвечает не человек, а ИИ-модель Claude (Anthropic), которой мы дали роль консультанта-визажиста ENCANTO. У бота есть «руки»: он умеет искать в живом каталоге Shopify, открывать карточку товара, класть товар в корзину клиента и читать правила магазина. Всё, что касается доставки, возврата, оплаты и бренда, он знает из нашей базы знаний. Ничего не выдумывает: товары и цены — только те, что вернул Shopify в момент вопроса.
Три части системы
1 · на сайте
Виджет
То, что видит клиент. Живёт внутри темы Shopify как блок приложения — включается один раз и показывается на всех страницах и языках сайта.
Кнопка чата, окно, три стартовые кнопки: Доставка, Возврат и обмен, Помочь подобрать
Показывает ответ по мере набора (стриминг), карточки товаров с фото, ценой и кнопкой «В корзину»
Перед каждым сообщением читает корзину клиента и передаёт её боту; после ответа обновляет значок корзины
11 языков интерфейса, язык берётся из версии сайта
Небольшое приложение в Амстердаме. Получает сообщение от виджета, собирает инструкцию для ИИ, вызывает Claude и Shopify, отдаёт ответ обратно по частям.
Собирает «системную инструкцию»: роль, правила, знания, настройки магазина, дата, страна и язык покупателя, id его корзины
Переводит запросы ИИ к Shopify и обратно, чистит и сжимает данные
Хранит историю диалогов в SQLite на диске сервера, бэкап в S3 каждые несколько секунд (Litestream)
Аккаунт Fly — клиентский (биллинг у CTR), доступы в Team Pro → проект CTR
3 · внешние сервисы
Claude и Shopify
Мозг и данные. Мы не храним каталог и не учим модель — всё берётся по запросу.
Claude API (модель claude-sonnet-4-6) — понимает вопрос, решает, что искать, пишет ответ на языке клиента
Shopify UCP (/api/ucp/mcp) — поиск по каталогу, карточка товара, корзина. Новый протокол Shopify 2026 года; старый API теперь отдаёт только правила магазина
Shopify MCP (/api/mcp) — политики магазина и FAQ
Shopify требует от бота «паспорт агента» — публичный JSON-профиль, мы отдаём его с сервера по адресу /.well-known/ucp
Как это связано
клиент
Пишет в чат«Покажи кисти для тональной основы»
виджет
Отправляет на сервертекст + id диалога + токен корзины + страница, страна, язык
сервер
Собирает инструкциюроль, правила, знания, дата, корзина → вызывает Claude
claude
Думает и действуетпросит сервер выполнить поиск в Shopify, получает 8–10 товаров, пишет ответ
виджет
Показываеттекст по частям, карточки товаров, обновлённую корзину
→ POST /chat
→ system prompt
⇄ Shopify UCP
→ поток событий (SSE)
✓
Одно сообщение по шагам
Клиент пишет «Добавь первую в корзину».
виджет · читает /cart.js, чтобы знать текущую корзину
Сервер достаёт историю диалога из базы, чистит служебные поля, добавляет новое сообщение.
сервер · SQLite
Сервер собирает инструкцию для модели: кто она, как отвечать, что запрещено, знания по доставке/возврату/оплате, сегодняшняя дата, страна и язык покупателя, id корзины, список доступных «инструментов».
Claude решает, что нужно действие, и просит: «update_cart, добавить вариант 57612100141381, 1 шт».
claude · tool use
Сервер выполняет действие в Shopify. Если корзина уже существует — обновляет её через UCP. Если корзина пустая (у Shopify тогда ещё нет настоящей корзины) — сервер даёт команду виджету, и виджет сам добавляет товар в корзину браузера.
Результат возвращается модели в сжатом виде: что добавлено, ссылка на оформление заказа.
сервер → claude
Claude пишет ответ на языке клиента: что добавлено, цена, ссылка «перейти к оформлению», одно предложение допродажи.
claude · стриминг
Виджет показывает текст по мере набора, обновляет значок корзины, а сервер сохраняет ответ в историю.
виджет + сервер
Обычный ответ без поиска — 3–10 секунд. С поиском по каталогу — 10–18 секунд (два обращения к модели: сначала решить, что искать, потом написать ответ).
Откуда бот знает, что говорить
Источник
Что там
Где менять
Роль и правила
Кто он, тон, длина ответа, что запрещено (сравнения с брендами, выдуманные товары, медицинские советы, лишние эмодзи), когда давать почту, как вести подбор
Тарифы доставки по странам, сроки, порог бесплатной доставки, возврат и обмен, способы оплаты, факты о бренде (2017, Украина/Корея, 30+ стран, ручки выдержаны 20 лет), размер каталога, чего нет в ассортименте
Правило номер один в инструкции: назвать товар, цену или цифру можно только если она пришла из Shopify или лежит в базе знаний. Нет данных — бот честно говорит об этом и предлагает ближайшую реальную альтернативу.
Что бот умеет сейчас
Продажа и подбор
Поиск по живому каталогу с карточками (фото, цена, кнопка)
Подбор: один уточняющий вопрос → 2–3 варианта с ценой
Хиты продаж из коллекции Best Seller, скидки из Sale
Корзина: добавить, изменить количество, ссылка на оформление
«Добавь палетку и кисть» без уточнений — сам выбирает бестселлеры
Допродажа и добор до бесплатной доставки
Возражение по цене — через срок службы 8–10 лет, без скидок
Консультация и сервис
Доставка по странам, сроки, порог 49 €, острова и исключения
Возврат и обмен 14 дней, кто платит, что делать при браке
Оплата: карты, PayPal, Apple/Google Pay, Klarna, Shop Pay и другие
Техника нанесения и уход — коротко, до 7 шагов
Подростки 14–17, чувствительная кожа, тест на сгибе локтя
Опт, счёт для компании, рекламация — собирает детали, почту даёт один раз
Отвечает на языке клиента, несколько вопросов — нумерованным списком
Чего пока не умеет
Ждёт материалы клиента
Названия оттенков палеток и карандаша
Составы INCI, тальк, аллергены — пока отправляет на упаковку
Условия опта, CPNP/CPSR, скидки визажистам
Порядок нанесения для бровей, уход за палетками и ресницами
Нужны решения или отдельные задачи
Статус заказа по номеру — приложению нужно право read_orders, мерчант должен переодобрить
Отзывы Judge.me, подарочная упаковка, передача живому менеджеру, GDPR-описание — новые задачи в таблице
Скорость: с поиском 10–18 с при цели ТЗ 15 с
Срок обмена: сейчас 14 дней как на сайте, в ТЗ было 30 — решение за клиентом
Как это обновляется
сервер
Промпт, знания, логика
Правим файлы в репозитории → flyctl deploy --remote-only --app shop-chat-agent-encanto-prod. Через 2–3 минуты новая версия в проде. Виджет трогать не нужно.
виджет
Кнопки, переводы, внешний вид
Правим extensions/chat-bubble → shopify app deploy. Shopify раздаёт новую версию на все страницы сам. Важно: у расширения фиксированный uid, тема ссылается на него — менять нельзя.
shopify
Товары и коллекции
Ничего деплоить не надо: новый товар, цена или скидка появляются у бота сразу, потому что он спрашивает Shopify каждый раз.
Как проверяем
Два уровня. Массовый прогон — скрипт шлёт боту серии вопросов (12 вопросов ТЗ × 5 языков + сценарии по строкам таблицы, 86 диалогов) и собирает ответы, время, ошибки, лишние эмодзи, английские вставки, служебные слова. Живой тест — Playwright открывает encantoshop.es, кликает кнопку чата, проходит подбор → карточки → корзина и сверяет корзину Shopify. После правок статусы переносим в таблицу «не выполненные задачи», лист «Бот».
Логи сервера: flyctl logs --app shop-chat-agent-encanto-prod — видно каждое обращение к Shopify и расход токенов по диалогу.
Где что лежит
Что
Где
Код
github.com/mile-development/shop-chat-agent-encanto, ветка master. Внутри CLAUDE.md — техническая шпаргалка по деплою и архитектуре
Сервер
Fly.io, приложение shop-chat-agent-encanto-prod, регион ams; рядом blog-generate (генератор блога, отдельный продукт)
Приложение Shopify
Partner-апка encanto-chat-agent, установлена на encantoshop.es; виджет — theme app extension chat-bubble
Доступы
Team Pro → проект CTR → раздел «Fly.io — хостинг чат-бота» (только админ)
Инструкция «как работаем / как поставить в другой магазин»
Team Pro → Довідник → вкладка «Shopify app development usefull»
Статусы доработок
Google Drive → «не выполненные задачи.xlsx» → лист «Бот»
Как поставить такого бота другому клиенту
Форк репозитория и своя Partner-апка Shopify (shopify app config link).
Свой сервер на Fly: новое приложение, диск для базы, секреты (ключ Claude, ключи апки, адрес сервера).
Переписать знания под бренд: роль, факты, тарифы доставки с сайта клиента, FAQ. Каталог подключать не нужно — он берётся из Shopify автоматически.
Установить апку в магазин и включить блок чата в теме (цвет, приветствие — в редакторе темы).
Прогнать тесты — те же скрипты, только с другим доменом.