Shop scout

shop-scout — мини-исследование закупки

Помогает агенту провести сравнение товара по российским маркетплейсам и выдать обоснованную рекомендацию: где купить, оригинал ли это, какие риски.

Что умеет

• Поиск (дискавери) — DuckDuckGo без API-ключа + per-market браузерный поиск.
• Карточки — цена/имя/рейтинг/число отзывов со всех трёх маркетов.
• Отзывы — Wildberries и Ozon (полные тексты), Yandex.Market (aggregateRating).
• Анализ — отсев мусорных отзывов, флаг подделки, бренд-матч, ранжирование.
• Отчёт — CSV + Markdown (сводка + «🏆 рекомендую» + «💰 дешевле-оригинал»
  • блок аналогов + полезные отзывы), сохраняются в папку проекта.

Установка (один раз)

bash bin/setup.sh

Ставит PHP-зависимости (composer), Node-зависимости (playwright) и браузеры playwright. Требования: PHP ≥ 8.2, composer, Node ≥ 20, google-chrome в PATH.

Основной запуск

php bin/scout.php "привод для ворот A450" \
  --markets=ozon,wb,ym --out=shopping --limit 5

• --out — папка для отчётов и кеша (по умолчанию ./shopping/). Кеш ляжет в <out>/.cache/shop-scout/ — добавьте .cache/ в .gitignore проекта.
• --markets — через запятую: ozon,wb,ym,generic.
• --limit — карточек на маркет (по умолчанию 6).

На stdout — саммари + кликабельная file://-ссылка на .md-отчёт. Рядом .csv.

Как агенту пользоваться (типовой сценарий)

1. Уточни у пользователя точное название/модель/артикул товара (не выдумывай).
2. Запусти scout.php с разумным --out (папка проекта или конкретной задачи).
3. Открой сгенерированный .md (он сам себя объясняет) и .csv при нужде.
4. Напиши рекомендацию своими словами на основе данных: где дешевле оригинал, какие жалобы на брак, какие риски. CSV/MD — это данные, вывод делает агент. Не пересказывай таблицу вслепую — выдели главное и честно скажи о сомнениях.
5. Проверяй релевантность типа товара. Дискавери иногда тащит нерелевантное (промо-товары YM, линейный привод вместо рычажного и т.п.). По имени/отзывам отсекай явно нерелевантное и сообщай пользователю.
6. Честно маркируй неизвестное: если цена не поднялась — так и скажи, не выдумывай.

Особенности по маркетам

• Wildberries, Yandex.Market — headless Chrome (chrome-php). Работают «из коробки».
• Ozon — через playwright+composer-api (subprocess к bin/ozon-playwright.mjs). Headless, без окон. Первый запрос платит ~12с за прохождение антибот-челленджа Variti, дальше 0.3–1с/карточка. Если playwright не установлен — Ozon-карточки будут помечены «нужен playwright» (запустите bin/setup.sh).

Подробности про антибот и архитектуру — в README.md (раздел «Как работает антибот Ozon»), статус адаптеров — в references/adapter-notes.md, паттерны мусорных отзывов — в references/review-junk-patterns.md.

Честно про ограничения

• genuine_flag / brand_match — эвристики, не гарантия. Сообщайте уровень уверенности.
• Anti-bot маркетов ломается. Карточки с fetch_failed исключаются из ранжирования, скил не падает целиком.
• Полные тексты отзывов — WB и Ozon. YM пока только aggregateRating (TODO).
• Срок доставки пока не поднимается (TODO).