Проверки и расписание

Инструменты цены и запуска

Получение цены не запускает проверку. Каждой из шести операций соответствует пара инструментов.

Для цены и запуска проект передаётся явно в project_id. Используйте одинаковую выборку в обоих вызовах.

Параметры выборки

• Позиции: можно ограничить регионы проекта, группы, папки или один запрос. Если ограничения не заданы, цена считается по проекту.
• Аудит: kind=indexing — индексация, kind=watcher — Радар, kind=sitemap — генерация карты сайта. Для карты нужен max_pages.
• Частотность: volumes задаёт поисковик, регион и вид частоты; for_visibility используется для частоты, необходимой при расчёте видимости. Без этих параметров используется базовая частота в включённых регионах Яндекса проекта.
• Релевантные страницы: можно выбрать регионы проекта, группы и папки.
• Кластеризация: используется регион выдачи с region_key; проверка перестраивает группы проекта. Новые группы-кластеры создаются выключенными.
• Подбор: исходные фразы, поисковик и регион. Найденные запросы сразу добавляются в проект, в новые группы либо в указанную группу. Новые группы создаются выключенными. Уже имеющиеся запросы повторно не добавляются.

Условия ручного запуска

Перед запуском должны выполняться все условия:

1. Токену MCP выдано право на нужный инструмент *_check_run.
2. В настройках включено «Разрешить платные проверки».
3. Агент получил актуальную цену через парный *_check_price и показал её вам.
4. После вашего согласия агент передаёт цену в confirm_price вместе с явным проектом и той же выборкой.
5. Свежая цена перед запуском не превышает подтверждённую цену и «Потолок цены одного запуска, ₽», если он установлен.

При росте цены плагин возвращает price_changed: нужно показать новую стоимость и получить новое согласие. При снижении запуск выполняется по меньшей цене. Если Топвизор вернул цену 0, её тоже нужно подтвердить: передать confirm_price=0 и выполнить остальные условия запуска.

Флаг confirm=true не заменяет confirm_price у ручного платного запуска. Сам плагин проверяет переданное число; получение человеческого согласия перед его подстановкой — обязанность агента.

Если цену получить или однозначно разобрать не удалось, запуск не выполняется (price_unavailable). При превышении потолка возвращается price_over_limit: сузьте выборку или измените ограничение в настройках.

Агент показывает стоимость проверки семи запросов и сообщает о постановке съёма в очередь после согласия.

Защита от повторов и пробный прогон

Та же нормализованная выборка блокируется от повторного запуска на 10 минут (recently_started). Проверяйте ход и списания вместо повторного запуска.

Параметр dry_run=true у инструментов запуска проверяет условия без запуска и списания. При блокирующем условии возвращаются would_start: false и blockers. Такой прогон не создаёт отметку о запуске.

Если связь оборвалась после отправки запуска, ответ go_outcome_unknown означает, что запуск мог состояться. Сначала прочитайте состояние и операции по счёту.

Как дождаться результата

Для асинхронных проверок вызывайте topvisor_audit_check_status с соответствующим kind:

Опрос рекомендуется делать не чаще раза в минуту. Ориентируйтесь на finished, а не только на процент. Состояние относится к проекту: проверку мог запустить другой клиент или расписание.

Подбор запросов (collect) выполняется синхронно и возвращает созданные группы сразу. Отслеживать его через инструмент состояния не нужно.

Подготовка аудита

Чтобы запускать индексацию или Радар, страницы должны быть включены в соответствующие проверки.

1. Прочитайте страницы через topvisor_audit_pages_list и настройки через topvisor_audit_settings_get.
2. Если страниц нет, подготовьте их добавление через topvisor_audit_pages_create с urls либо sitemap_url и нужными флагами indexing / watcher.
3. Для существующих страниц используйте topvisor_audit_pages_update.
4. После подтверждения изменений получите цену и отдельно подтвердите запуск.

Цена 0 вместе с ошибкой Топвизора 5001 может означать, что страницы не включены в проверки. Генерация карты сайта добавляет ссылки в проект, но участие страниц в индексации и Радаре включается отдельно. Изменения Радара доступны начиная со второй проверки.

Автозапуск по расписанию

Через topvisor_schedule_get можно прочитать расписание четырёх видов: positions, volumes, indexing, watcher.

Для включения или изменения используется topvisor_schedule_update:

daily нельзя сочетать с другими днями. Запуски «каждый час» и «каждые N минут» инструмент не принимает. Часовой пояс из кода инструмента не определяется: перед включением уточните время в кабинете Топвизора.

Без confirm=true инструмент возвращает предпросмотр с текущим и новым расписанием, ценой запуска и оценкой расходов в месяц. Для получения этого предпросмотра флажок платных проверок уже должен быть включён. После вашего согласия агент передаёт confirm=true и confirm_price.

Месячная сумма — оценка: для ежедневного запуска код берёт 30 запусков, для выбранного дня недели — 4,3, для числа месяца или последнего дня — один. Для запуска после обновления Яндекса сумма заранее не определяется. Оценка не является ограничением расходов.

Потолок плагина проверяется при сохранении расписания. Дальше Топвизор запускает проверки и списывает средства самостоятельно, без нового вызова плагина и без запроса подтверждения каждого списания.

Как выключить автозапуск

Используйте topvisor_schedule_delete с явными project_id, kind и подтверждением confirm=true после предпросмотра. Для этого нужно право токена на выключение расписания, но не требуется включать платные проверки в настройках. Ручные запуски не затрагиваются.

Снятие флажка «Разрешить платные проверки» не выключает уже сохранённое расписание в Топвизоре.

При partial_failure в ответе настройки расписание могло включиться, а дополнительные параметры — не сохраниться. Перечитайте его через topvisor_schedule_get; при необходимости выключите до исправления.

Примеры просьб к агенту

Узнай цену съёма позиций выбранного проекта в нужном регионе.
Покажи проект, выборку и стоимость. Запускай только после моего согласия.

Проверь, включены ли страницы проекта в индексацию и Радар.
Подготовь недостающие настройки, согласуй изменения, затем отдельно
покажи цену проверок. После запуска дождись результата.

Подготовь ежедневный съём позиций в 09:00.
Покажи текущее расписание, цену одного запуска и оценку за месяц.
Без моего подтверждения расписание не включай.