name	shop-scout
description	Мини-исследование закупки — найти товар на российских маркетплейсах (Ozon, Wildberries, Yandex.Market), сравнить цены/рейтинги/отзывы, отсеять мусорные отзывы и подозрения на подделку, выбрать самый дешёвый оригинал и самый рекомендуемый (баланс цена/качество). Использовать, когда пользователь просит «найти подешевле», «сравнить цены», «где купить», «стоит ли брать», «не подделка ли» для конкретного товара. Результат — CSV + Markdown-отчёт в папку проекта.
license	MIT

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.

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

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

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

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).

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

Что умеет

Поиск (дискавери) — DuckDuckGo без API-ключа + per-market браузерный поиск.

Карточки — цена/имя/рейтинг/число отзывов со всех трёх маркетов.

Отзывы — Wildberries и Ozon (полные тексты), Yandex.Market (aggregateRating).

Анализ — отсев мусорных отзывов, флаг подделки, бренд-матч, ранжирование.

Отчёт — CSV + Markdown (сводка + «🏆 рекомендую» + «💰 дешевле-оригинал»

блок аналогов + полезные отзывы), сохраняются в папку проекта.

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

bash bin/setup.sh

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

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.

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

Уточни у пользователя точное название/модель/артикул товара (не выдумывай).

Запусти scout.php с разумным --out (папка проекта или конкретной задачи).

Открой сгенерированный .md (он сам себя объясняет) и .csv при нужде.

Напиши рекомендацию своими словами на основе данных: где дешевле оригинал, какие жалобы на брак, какие риски. CSV/MD — это данные, вывод делает агент. Не пересказывай таблицу вслепую — выдели главное и честно скажи о сомнениях.

Проверяй релевантность типа товара. Дискавери иногда тащит нерелевантное (промо-товары YM, линейный привод вместо рычажного и т.п.). По имени/отзывам отсекай явно нерелевантное и сообщай пользователю.

Честно маркируй неизвестное: если цена не поднялась — так и скажи, не выдумывай.

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

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).

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

genuine_flag / brand_match — эвристики, не гарантия. Сообщайте уровень уверенности.

Anti-bot маркетов ломается. Карточки с fetch_failed исключаются из ранжирования, скил не падает целиком.

Полные тексты отзывов — WB и Ozon. YM пока только aggregateRating (TODO).

Срок доставки пока не поднимается (TODO).