Простыми словами: из чего он состоит, что за что отвечает, как проходит одно сообщение от клиента до ответа, что бот умеет, чего пока не умеет и где это всё крутить.
В углу сайта висит кнопка чата. Клиент пишет вопрос — отвечает не человек, а ИИ-модель Claude (Anthropic), которой мы дали роль консультанта-визажиста ENCANTO. У бота есть «руки»: он умеет искать в живом каталоге Shopify, открывать карточку товара, класть товар в корзину клиента и читать правила магазина. Всё, что касается доставки, возврата, оплаты и бренда, он знает из нашей базы знаний. Ничего не выдумывает: товары и цены — только те, что вернул Shopify в момент вопроса.
То, что видит клиент. Живёт внутри темы Shopify как блок приложения — включается один раз и показывается на всех страницах и языках сайта.
extensions/chat-bubble/assets/chat.js, chat.cssНебольшое приложение в Амстердаме. Получает сообщение от виджета, собирает инструкцию для ИИ, вызывает Claude и Shopify, отдаёт ответ обратно по частям.
Мозг и данные. Мы не храним каталог и не учим модель — всё берётся по запросу.
/api/ucp/mcp) — поиск по каталогу, карточка товара, корзина. Новый протокол Shopify 2026 года; старый API теперь отдаёт только правила магазина/api/mcp) — политики магазина и FAQ/.well-known/ucpОбычный ответ без поиска — 3–10 секунд. С поиском по каталогу — 10–18 секунд (два обращения к модели: сначала решить, что искать, потом написать ответ).
| Источник | Что там | Где менять |
|---|---|---|
| Кто он, факты бренда, FAQ, примеры | Роль и голос бренда, факты и запреты («ручки выдержаны 20 лет», «не обещать рост волос»), база знаний вопрос-ответ, примеры идеальных ответов — редактирует мерчант во вкладке Knowledge в апке, применяется со следующего сообщения, без деплоя. Есть «Reset to default» | Админка Shopify → апка → Knowledge |
| Общие правила поведения | Тон, длина ответа, не больше 3 товаров, один уточняющий вопрос, сравнения с брендами, медицинские советы, эмодзи, когда давать почту — логика продукта, одинаковая для всех магазинов | app/prompts/fields/behavioral-rules.md (в коде) |
| Живые данные магазина | Тарифы доставки по странам и зонам с условиями бесплатной доставки, маркеты (страны и валюты), тексты политик (возврат) — бот сам читает их из настроек Shopify раз в час и после нажатия «Refresh now» в Settings. Меняете тариф в админке → бот знает через час, без деплоя. Именно так вскрылось, что страница политики доставки на сайте устарела: реальные тарифы — Испания 7 €, Франция 8 €, Андорра 6 € | Shopify admin → Settings → Shipping and delivery / Markets / Policies; код: app/services/store-knowledge.server.js |
| Знания о магазине (в коде) | Сроки обработки и доставки, способы оплаты (Klarna и др. в Shopify не читаются), факты о бренде (2017, Украина/Корея, 30+ стран, ручки выдержаны 20 лет), размер каталога, чего нет в ассортименте. Тарифы тут только как запасной вариант на случай, если Shopify недоступен | app/prompts/knowledge/faq.js, shipping-policies.js |
| Подробные FAQ по категориям | Как ухаживать за кистями, волокна, палетки — длинные справки, бот берёт из них только нужное | app/prompts/knowledge/product-faqs/ |
| Живые данные Shopify | Товары, цены, скидки, наличие, корзина — запрашиваются в момент вопроса. У нас не хранятся | Админка Shopify (карточки товаров, коллекции Best Seller и Sale) |
| Настройки в апке (Settings) | Email поддержки, порог бесплатной доставки, окно возврата и обмена — мерчант правит сам в админке Shopify → Apps → encanto-chat-agent → Settings; там же видно, что подтянулось из магазина | Админка Shopify → апка → Settings |
read_orders, мерчант должен переодобритьПравим код в репозитории → flyctl deploy --remote-only --app shop-chat-agent-encanto-prod. Через 2–3 минуты в проде. Тексты про бренд и FAQ деплоя не требуют — они во вкладке Knowledge.
Правим extensions/chat-bubble → shopify app deploy. Shopify раздаёт новую версию на все страницы сам. Важно: у расширения фиксированный uid, тема ссылается на него — менять нельзя.
Ничего деплоить не надо: новый товар, цена или скидка — у бота сразу (он спрашивает Shopify каждый раз); новый тариф доставки, страна или текст политики — в течение часа или сразу после «Refresh now» в Settings апки.
Два уровня. Массовый прогон — скрипт шлёт боту серии вопросов (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. Экраны в админке (Analytics, Conversations, Settings, Debug) — наши страницы из того же репозитория (app/routes/app.*.jsx), встроены через App Bridge, деплоятся вместе с сервером |
| Доступы | Team Pro → проект CTR → раздел «Fly.io — хостинг чат-бота» (только админ) |
| Инструкция «как работаем / как поставить в другой магазин» | Team Pro → Довідник → вкладка «Shopify app development usefull» |
| Статусы доработок | Google Drive → «не выполненные задачи.xlsx» → лист «Бот» |
shopify app config link).