VK Реклама — аудит и анализ (только чтение)
Два режима над одним кабинетом:
- Глубокий аудит — разовая диагностика за период →
АУДИТ_<slug>.html с находками по приоритету.
- Быстрый анализ — «как вчера/неделя» → 5–10 строк в чат, только аномалии.
Скилл ничего не меняет в кабинете. Скрипты ходят в MCP через белый список инструментов чтения
(scripts/mcp_client.py). Ты на пути A вызываешь только инструменты чтения: *_list, *_get,
vk_ads_statistics_*, vk_ads_auth_check, vk_ads_account_info, vk_ads_accounts_list. Просьбу «поправь»,
«выключи», «создай» передай в vk-ads-manager: находки сформулированы как действия.
Просят изменить кабинет — прямой отказ, одним сообщением:
- Прямо, первой фразой: «Нет, я только читаю кабинет и не могу поставить кампанию на
паузу». Назови действие словами пользователя.
- Где это сделать: паузу, правку, создание — агент запуска VK Рекламы (vk-ads-manager)
после вашего «ОК» или вы сами в кабинете ads.vk.ru; удаление и запуск — только вы в кабинете.
- Что можешь вместо: передать находку агенту запуска или показать, на чём она основана, —
вопросом.
- Стоп. Не продолжай аудит и не переходи к следующему шагу, пока человек не ответит.
Инструмента нет среди доступных или вызов отклонён (forbidden, not allowed, permission,
403) — тоже отказ, а не сбой: не повторяй и не обходи, скажи человеку, что не получилось
прочитать, и запиши это в ограничения отчёта.
Ты не считаешь. Все числа — из dataset.json и findings.json, их считают скрипты. Твоя работа —
маршрут, вопросы, выводы словами и гейт.
Проверка версии (один раз за разговор, до выбора режима)
Прочитай VERSION рядом с этим файлом и одним запросом загрузи
https://raw.githubusercontent.com/ai-hub-open/vk-ads-audit/main/VERSION.
- Совпадает или загрузить не вышло — молча работай дальше.
- На GitHub новее (semver) — одним сообщением: вышла X (у тебя Y),
CHANGELOG; обновление:
Claude Code —
/plugin marketplace update ai-hub-open и перезапуск; архив — скачать vk-ads-audit.skill из
релизов. Спроси: обновиться или продолжить.
Файлы скилла сам не скачивай и не заменяй.
Режим
| Запрос |
Режим |
| «аудит», «разбери кабинет», «почему дорого», «что отключить», «найди точки роста» |
Глубокий аудит |
| «как у нас», «сводка за вчера», «как прошла неделя», один конкретный вопрос |
Быстрый анализ |
Не уверен — спроси одним вопросом.
Где что лежит
Скрипты — в папке скилла, запуск python -m scripts.<имя> только оттуда. Рабочая папка —
<папка пользователя>/vk-audits/<slug>-<YYYY-MM-DD>/, не внутри скилла; --workspace всегда абсолютный.
Скрипты сами откажутся работать с папкой внутри скилла. Ниже <ws> — этот абсолютный путь.
Повторный прогон — всегда новая рабочая папка (<slug>-<YYYY-MM-DD>-2). Папку с заполненным raw/
не переиспользуй: сбор откажется (код 4), а ручное дописывание в чужой raw/ смешает данные разных прогонов.
Запуска кода в среде нет — скилл работать не может (вся арифметика в скриптах): скажи об этом прямо.
Глубокий аудит
Шаг 0. Охват
- Кабинет:
vk_ads_accounts_list; несколько — покажи список, зафиксируй account_id.
- Период: по умолчанию 30 последних полных дней (до вчера), минимум 14. Период всегда заканчивается
не позже вчерашнего дня. VK хранит дневную статистику 366 дней: начало периода раньше — скажи пользователю
доступную дату (путь B сам остановится с кодом 2 и назовёт её; ответ
WRONG_DATE тоже разбирай так, а не показывай сырым).
- Целевой CPA/CPL: спроси один раз. Нет — опорный CPA считается по медиане кабинета, в отчёте пометка.
- Создай
<ws>, запиши _state.json: {"mode","account_id","date_from","date_to","target_cpa"}.
Шаг 1. Предполётка (только чтение)
vk_ads_auth_check, vk_ads_account_info (баланс, валюта, id пользователя).
- Путь. В claude.ai и Claude Desktop у коннектора vk-ads нет персональной ссылки подключения — там сбор всегда идёт
путём A (ты вызываешь MCP сам и кладёшь ответы в
raw/); ссылку у пользователя в этих средах не спрашивай и
collect --probe не запускай. Путь B — только там, где скрипты ходят в сеть сами (Claude Code, терминал) и ссылка
есть: python -m scripts.collect --probe --account-id <ID>.
- Код 0 → путь B.
- Код 2 «ссылка не сохранена» → в Claude Code спроси у пользователя персональную ссылку подключения MCP
(вид
https://…/c/<токен>), сохрани: python -m scripts.credentials set --url <ссылка>, повтори probe.
В чате ссылку не повторяй. Нет ссылки или probe снова 2 («путь B не работает») → путь A.
- Расход за период (путь A; путь B делает это сам, пишет расход в
collect_log.json и при 0 ₽ без живых групп
выходит с кодом 5): один вызов
vk_ads_statistics_day(entity="users", ids=<id пользователя из account_info>, date_from, date_to, metrics="base").
На пути A ответ положи в <ws>/raw/ как обычный вызов (vk_ads_statistics_day__NNN.json, entity: "users"):
по нему отчёт отличит «кабинет потратил 0 ₽» от «0 ₽ у живых групп». Расход 0 ₽ — вызови vk_ads_campaigns_list
(строка 2 references/mcp-read-tools.md): живых групп нет (все deleted или с ARCHIVED) — скажи пользователю, что
кабинет не откручивает, и предложи другой кабинет; сбор и отчёт не начинай. Живые группы есть — собирай дальше:
отчёт выйдет с плашкой «0 ₽», скажи об этом пользователю и предложи другой период.
- Метрика: есть ли коннектор Метрики; если да — какой счётчик (спроси или найди по домену посадочных).
- Запиши выбор в
_state.json, в чат одной строкой: «Путь B, Метрика: счётчик N» или что недоступно.
Шаг 2. Сбор
Путь B: python -m scripts.collect --workspace <ws> --account-id <ID> --date-from D --date-to D.
Если дата конца позже вчера, скрипт сам сдвинет её и скажет об этом. Коды выхода:
| Код |
Что значит |
Что делать |
| 0 |
сбор выполнен, возможно частично |
ошибки отдельных вызовов — в collect_log.json (errors), они сами попадут в ограничения; сбор не повторяй вслепую |
| 2 |
нет ссылки, probe не прошёл, неверные даты, период пуст после сдвига или старше истории VK (~366 дней) |
исправь ввод или переходи на путь A; про историю — назови пользователю доступную дату из сообщения |
| 3 |
критический сбой: список кампаний не получен, описи кабинета нет |
покажи причину из collect_log.json; путь A — только в новой рабочей папке |
| 4 |
raw/ уже не пуст |
возьми новую рабочую папку, старую не чисти и не дописывай |
| 5 |
расход за период 0 и живых групп нет: собраны только списки кампаний и групп |
скажи пользователю и предложи другой кабинет (0 ₽ при живых группах — код 0, отчёт с плашкой) |
401. HTTP 401 в выводе probe/collect или в ошибке collect_log.json — ссылка подключения недействительна
или истекла: попроси у пользователя новую, python -m scripts.credentials set --url <ссылка>, повтори probe. На
молчаливый переход на путь A из-за 401 не соглашайся. 401 или ошибка авторизации на пути A — попроси переавторизовать
коннектор vk-ads и остановись.
Журнал collect_log.json пишется всегда; при падении посреди сбора в нём поле aborted.
Путь A — ты кладёшь ответы инструментов в <ws>/raw/ по формату scripts/raw_store.py:
файл <инструмент>__<NNN>.json = {"tool": ..., "arguments": {...}, "response": <ответ целиком, без правок>}.
NNN — целое число; tool в содержимом совпадает с именем в названии файла. Для списков можно по файлу на
страницу либо один общий файл {"items": [...]} — но не оба сразу (дубли с разным содержимым останавливают
нормализацию); ответ списка — объект с массивом items.
В raw/ только такие файлы — любой другой файл (заметки, черновики) ломает проверку.
Сбой — не данные: ответ-ошибку в raw/ не клади (isError, {"error": true, …}): проверка его отвергнет, сбой запиши в collect_log.json.
Порядок и поля — references/mcp-read-tools.md; выполни строки 1–6 его таблицы, включая сегменты,
списки аудиторий и пиксели (без пикселей проверка пикселя пропускается). Сегменты — с
fields=id,name,pass_condition,flags,relations,relations_count,created,updated: по связям (relations) скрипты
определяют слой (пиксель, база — тёплый, ключевые фразы — холодный); сервер отверг fields — повтори без них. На пути A: кампании, группы и статистика по дням
(vk_ads_statistics_day, entity=campaigns, пачки ≤ 50 id, все группы кроме удалённых — архивные тоже, их расход
входит в итоги); объявления (vk_ads_banners_list; для архивных групп не вызывай) и их статистика по дням
(entity=banners) — только у 5 групп с наибольшим расходом; у дней metrics="base". Итоги периода считаются суммой дней:
vk_ads_statistics_summary — только за всё время, даты не передавай (с датами MCP откажет), metrics="base,uniques".
Строка 7 (сводка групп) необязательна: она даёт охват и
частоту только группам, созданным внутри периода; без неё частота «не определена», выгорание молчит, отчёт честно скажет.
Большой ответ (Claude Desktop сохраняет его файлом, например список из десятков групп ≈ 260 КБ) руками не вставляй и
не пересказывай: python -m scripts.raw_store import --workspace <ws> --tool <инструмент> --arguments '<json аргументов вызова>' --from <путь к файлу> (в PowerShell удобнее --arguments-file <файл с json>). Команда сама проверит JSON и
отказывает по-русски на обрезанном или нетекстовом файле — тогда повтори вызов с меньшей выборкой (limit, offset).
Любой неудавшийся вызов инструмента запиши в <ws>/collect_log.json в том же виде, что пишет сбор:
{"mode": "deep"|"quick", "date_from": "D", "date_to": "D", "calls": [{"tool": "...", "arguments": {...}, "ok": false, "error": "..."}], "errors": N, "critical": false} (critical: true, если не получен
vk_ads_campaigns_list). vk_ads_users_lists_list с code: zero_quota (MCP 0.12.0 — HTTP 403) или 429 с limits с нулём — это не перегрузка, а нет прав:
повторять не надо, запиши вызов с "no_access": true — отчёт скажет «нет доступа к базам клиентов». Отчёт сам вынесет эти сбои в «Ограничения» — молча пропущенный вызов хуже записанного. Сбой, после которого тот же
вызов (тот же инструмент и те же аргументы) прошёл и лежит в raw/, отчёт сам не покажет — запись о нём не удаляй.
После — python -m scripts.raw_store check --workspace <ws> (код 3 — исправь названные файлы и повтори) до шага 3.
Шаг 3. Нормализация
python -m scripts.normalize --workspace <ws> --date-from D --date-to D [--target-cpa N] --path A|B
Код 3 — остановись, dataset.json не записан. Причины и что делать:
Нет живых групп, а статистика по архивным не получена (no_stats): есть ли расход, неизвестно — покажи причину из
collect_log.json и повтори сбор статистики в новой рабочей папке; «расхода нет» пользователю не говори.
Проверка здравого смысла не пройдена: покажи пользователю строки из sanity.json и скажи, что отчёт на таких
числах строить нельзя. ctr_units значит, что формат ответа VK изменился (ctr у VK уже в процентах), — это
повод для задачи разработчикам. Расхождение сводки и дней аудит больше не блокирует: итоги берутся из дней.
«raw/ не разобран» — файлы нарушают формат; запусти raw_store check и исправь.
«✗ metrika.json: …» — см. шаг 4.
Код 5 — остановись, dataset.json не записан: в кабинете нет живых групп (все удалены или в архиве) и расхода по
ним за период нет. Отчёт не строй, diagnose не запускай. Скажи пользователю одной фразой: «В кабинете сейчас нет живых
групп — все удалены или в архиве, и за период по ним нет расхода, проверять нечего» — и предложи другой кабинет (если их
несколько) или вернуться, когда группы заработают. Живые группы есть, а их расход за период 0 ₽ — нормализация проходит
и предупреждает: отчёт строится с крупной плашкой вверху (проверены только настройки). Текст плашки — как в
references/report-template.md: «Расход кабинета за период 0 ₽» (только если предполётка подтвердила 0 ₽),
«Живые группы за период не откручивали; X ₽ пришлось на удалённые группы», «Расход кабинета за период X ₽, у живых групп 0 ₽ —
разложить разницу по группам не удалось» или «Расход живых групп за период 0 ₽» (расход кабинета не проверялся).
Перескажи пользователю текст плашки и предложи другой период.
Шаг 4. Метрика (если подключена)
По references/metrika-vk.md собери <ws>/metrika.json и обязательно запиши в него date_from и date_to
(период аудита). Затем повтори Шаг 3 — нормализация подхватит файл. Проверка строгая: при строке
«✗ metrika.json: …» исправь файл по сообщению и снова запусти normalize. Не получается — удали
metrika.json и иди без Метрики, это уйдёт в ограничения.
Шаг 5. Диагностика
python -m scripts.diagnose --workspace <ws> → findings.json: находки (findings), чек-лист блоков A–G с баллами
(checklist) и вопросы к клиенту (questions). Нет dataset.json — код 2, вернись к шагу 3.
Правила, статусы и пороги — references/diagnostic-rules.md, references/thresholds.json.
Чек-лист отвечает «настроено ли» (✅ / ❌ / «—» / ❓), находки — «сколько стоит и что делать».
Статус «—» — данных нет или нечего проверять (нет активных групп или объявлений — «нечего проверять», не «нет данных»); ❓ — воронка подписки, лид-формы или Senler не используется и её
сначала уточняем у клиента (не ошибка). В балл они не входят.
Шаг 6. Гейт
В чат 5–10 строк: общий балл («n / m»; нет живых групп — total пуст, вместо балла «кабинет не откручивает»), баллы блоков A–G, топ находок (уровень, объект, ₽, действие) из
findings.json. Затем вопросы к клиенту: те, что в questions помечены important («важно для вашего кабинета»),
задай клиенту сразу, по одному (список — references/client-questions.md); остальные покажет отчёт.
Ответы на funnel_subscription / funnel_leadform / funnel_senler запиши в <ws>/client_answers.json:
{"funnel_leadform": {"verdict": "na" | "potential", "answer": "<слова клиента>"}} (na — воронка клиенту не
подходит, potential — подходит, но не используется; критерии — references/client-questions.md; ответ
неясен — не записывай). Затем снова python -m scripts.diagnose --workspace <ws> — чек-лист и вопросы пересоберутся
(na / 🟢 вместо ❓, при potential — находка «Потенциал роста»); ✅ и ❌ ответ не меняет.
Повторный запуск перезаписывает findings.json, поэтому client_note впиши после него. Ответ клиента, объясняющий конкретную находку, впиши в неё полем "client_note": "<текст клиента>", числа не правь;
отчёт покажет её с пометкой «Объяснено клиентом». Общий ответ — в сводку. И один вопрос: «Есть контекст, который
меняет вывод? Например, группа тестовая, сезон, акция». Затем шаг 7.
Шаг 7. Отчёт
python -m scripts.render_report --workspace <ws> --slug <slug> → <ws>/АУДИТ_<slug>.html: чек-лист с баллами,
находки, вопросы к клиенту, ограничения (в том числе «Не проверено «…»: …»).
Покажи файл способом, который есть в среде, и дай сводку 5–10 строк; есть предупреждение «Кабинет менялся после
конца периода» — скажи, что статусы и бюджеты в отчёте на дату сбора. Структура отчёта —
references/report-template.md. Предложи передать действия в vk-ads-manager.
Быстрый анализ
- Создай новую рабочую папку (каждый прогон — новая). Охват: кабинет, день (по умолчанию вчера; сегодняшний и будущие дни скрипт отвергнет), целевой CPA если известен.
- Предполётка как в Шаге 1, без Метрики.
- Путь B:
python -m scripts.collect --workspace <ws> --account-id <ID> --mode quick --date-from <день−7> --date-to <день>
(коды выхода те же, что в Шаге 2);
путь A: vk_ads_ad_plans_list, vk_ads_campaigns_list (поля из references/mcp-read-tools.md) и vk_ads_statistics_day по живым группам
за те же 8 дней → raw/, затем raw_store check.
python -m scripts.normalize --workspace <ws> --date-from <день−7> --date-to <день> --path A|B (код 5 — живых групп
нет, расхода нет: скажи пользователю, быстрый анализ не делай)
python -m scripts.quick --workspace <ws> --day <день> [--target-cpa N] — выведи его строки как есть.
Флаги ставятся только активным группам (паузные входят в итоги). Нет данных за день — скрипт выведет заголовок
и «нет данных»: передай это пользователю, не домысливай. Код 2 — неверный день или нет dataset.json.
- Есть аномалии — предложи глубокий аудит; сам не запускай.
Ограничения
Всегда входят в отчёт — references/limitations.md. Плюс недобранное в прогоне: путь A, нет Метрики,
не собраны объявления, статистика или пиксели, ошибки и обрыв сбора. Молча упрощённый результат хуже
честно недобранного.
Стиль
- Один вопрос за раз. Артефакт — в файл, в чат — сводка 5–10 строк.
- Новая просьба важнее плана: сообщение посреди аудита — сначала ответ на него, а не следующий
шаг. Просьба изменить кабинет — прямой отказ (в начале файла) и стоп.
- Не выдумывай причин: «не знаю, данных нет» лучше догадки. Гипотеза — помечай как гипотезу.
- Действие находки — что сделать, а не как в интерфейсе: шаги кабинета, названия пунктов и периоды не
придумывай. Ориентир из методики (например, бюджет «2 × CPA») подавай как ориентир, с оговоркой из
action, а не как требование VK; ограничение бюджета, названное пользователем, важнее ориентира.
- Деньги — в рублях, CTR — в процентах; сырые значения API не показывай.
Возобновление
Только по просьбе продолжить; сообщение с другой просьбой — сначала ответ на неё.
«Продолжаем аудит VK» → найди последнюю vk-audits/*/_state.json, по наличию файлов
(raw/, dataset.json, findings.json, АУДИТ_*.html) продолжи с первого незавершённого шага.
Если raw/ уже заполнен, заново не собирай: продолжай с нормализации.
1---2name: "vk-ads-audit"3description: "Аудит и анализ кабинета VK Рекламы (ads.vk.ru) только на чтение через MCP vk-ads, опционально с Метрикой. ГЛУБОКИЙ АУДИТ — структура кампаний, групп и объявлений, расход и результат, слив без конверсий, CPA выше цели, низкий CTR, выгорание креативов, голодание автостратегий, гигиена (пустые группы, отклонённые объявления, бюджеты, дубли таргетингов, пиксель), лидеры для масштабирования → HTML-отчёт с приоритетами и ограничениями. БЫСТРЫЙ АНАЛИЗ — сводка за вчера или неделю, аномалии в 10 строк. Триггеры: «аудит VK», «разбери кабинет VK», «почему дорогой лид в VK», «что отключить в VK», «как у нас в VK», «сводка VK за вчера», «как прошла неделя в VK». НЕ для создания и правки кампаний — это vk-ads-manager."4metadata:5 source: https://skillmd.com/skills/ai-hub-open/vk-ads-audit6---78# VK Реклама — аудит и анализ (только чтение)910Два режима над одним кабинетом:1112- **Глубокий аудит** — разовая диагностика за период → `АУДИТ_<slug>.html` с находками по приоритету.13- **Быстрый анализ** — «как вчера/неделя» → 5–10 строк в чат, только аномалии.1415**Скилл ничего не меняет в кабинете.** Скрипты ходят в MCP через белый список инструментов чтения16(`scripts/mcp_client.py`). Ты на пути A вызываешь **только** инструменты чтения: `*_list`, `*_get`,17`vk_ads_statistics_*`, `vk_ads_auth_check`, `vk_ads_account_info`, `vk_ads_accounts_list`. Просьбу «поправь»,18«выключи», «создай» передай в vk-ads-manager: находки сформулированы как действия.1920**Просят изменить кабинет — прямой отказ, одним сообщением:**21221. **Прямо, первой фразой:** «Нет, я только читаю кабинет и не могу поставить кампанию на23 паузу». Назови действие словами пользователя.242. **Где это сделать:** паузу, правку, создание — агент запуска VK Рекламы (vk-ads-manager)25 после вашего «ОК» или вы сами в кабинете ads.vk.ru; удаление и запуск — только вы в кабинете.263. **Что можешь вместо:** передать находку агенту запуска или показать, на чём она основана, —27 вопросом.284. **Стоп.** Не продолжай аудит и не переходи к следующему шагу, пока человек не ответит.2930Инструмента нет среди доступных или вызов отклонён (`forbidden`, `not allowed`, `permission`,31`403`) — тоже отказ, а не сбой: не повторяй и не обходи, скажи человеку, что не получилось32прочитать, и запиши это в ограничения отчёта.3334**Ты не считаешь.** Все числа — из `dataset.json` и `findings.json`, их считают скрипты. Твоя работа —35маршрут, вопросы, выводы словами и гейт.3637## Проверка версии (один раз за разговор, до выбора режима)3839Прочитай `VERSION` рядом с этим файлом и одним запросом загрузи40`https://raw.githubusercontent.com/ai-hub-open/vk-ads-audit/main/VERSION`.4142- Совпадает или загрузить не вышло — молча работай дальше.43- На GitHub новее (semver) — одним сообщением: вышла X (у тебя Y),44 [CHANGELOG](https://github.com/ai-hub-open/vk-ads-audit/blob/main/CHANGELOG.md); обновление:45 Claude Code — `/plugin marketplace update ai-hub-open` и перезапуск; архив — скачать `vk-ads-audit.skill` из46 [релизов](https://github.com/ai-hub-open/vk-ads-audit/releases/latest). Спроси: обновиться или продолжить.4748Файлы скилла сам не скачивай и не заменяй.4950## Режим5152| Запрос | Режим |53|---|---|54| «аудит», «разбери кабинет», «почему дорого», «что отключить», «найди точки роста» | Глубокий аудит |55| «как у нас», «сводка за вчера», «как прошла неделя», один конкретный вопрос | Быстрый анализ |5657Не уверен — спроси одним вопросом.5859## Где что лежит6061Скрипты — в папке скилла, запуск `python -m scripts.<имя>` только оттуда. Рабочая папка —62`<папка пользователя>/vk-audits/<slug>-<YYYY-MM-DD>/`, **не внутри скилла**; `--workspace` всегда абсолютный.63Скрипты сами откажутся работать с папкой внутри скилла. Ниже `<ws>` — этот абсолютный путь.6465**Повторный прогон — всегда новая рабочая папка** (`<slug>-<YYYY-MM-DD>-2`). Папку с заполненным `raw/`66не переиспользуй: сбор откажется (код 4), а ручное дописывание в чужой `raw/` смешает данные разных прогонов.6768Запуска кода в среде нет — скилл работать не может (вся арифметика в скриптах): скажи об этом прямо.6970---7172# Глубокий аудит7374## Шаг 0. Охват75761. Кабинет: `vk_ads_accounts_list`; несколько — покажи список, зафиксируй `account_id`.772. Период: по умолчанию 30 последних полных дней (до вчера), минимум 14. Период всегда заканчивается78 не позже вчерашнего дня. VK хранит дневную статистику 366 дней: начало периода раньше — скажи пользователю79 доступную дату (путь B сам остановится с кодом 2 и назовёт её; ответ `WRONG_DATE` тоже разбирай так, а не показывай сырым).803. Целевой CPA/CPL: спроси один раз. Нет — опорный CPA считается по медиане кабинета, в отчёте пометка.814. Создай `<ws>`, запиши `_state.json`: `{"mode","account_id","date_from","date_to","target_cpa"}`.8283## Шаг 1. Предполётка (только чтение)84851. `vk_ads_auth_check`, `vk_ads_account_info` (баланс, валюта, id пользователя).862. Путь. **В claude.ai и Claude Desktop у коннектора vk-ads нет персональной ссылки подключения — там сбор всегда идёт87 путём A (ты вызываешь MCP сам и кладёшь ответы в `raw/`); ссылку у пользователя в этих средах не спрашивай и88 `collect --probe` не запускай.** Путь B — только там, где скрипты ходят в сеть сами (Claude Code, терминал) и ссылка89 есть: `python -m scripts.collect --probe --account-id <ID>`.90 - Код 0 → путь B.91 - Код 2 «ссылка не сохранена» → в Claude Code спроси у пользователя персональную ссылку подключения MCP92 (вид `https://…/c/<токен>`), сохрани: `python -m scripts.credentials set --url <ссылка>`, повтори probe.93 В чате ссылку не повторяй. Нет ссылки или probe снова 2 («путь B не работает») → путь A.943. Расход за период (путь A; путь B делает это сам, пишет расход в `collect_log.json` и при 0 ₽ без живых групп95 выходит с кодом 5): один вызов96 `vk_ads_statistics_day(entity="users", ids=<id пользователя из account_info>, date_from, date_to, metrics="base")`.97 На пути A ответ положи в `<ws>/raw/` как обычный вызов (`vk_ads_statistics_day__NNN.json`, `entity: "users"`):98 по нему отчёт отличит «кабинет потратил 0 ₽» от «0 ₽ у живых групп». Расход 0 ₽ — вызови `vk_ads_campaigns_list`99 (строка 2 `references/mcp-read-tools.md`): живых групп нет (все `deleted` или с `ARCHIVED`) — скажи пользователю, что100 кабинет не откручивает, и предложи другой кабинет; сбор и отчёт не начинай. Живые группы есть — собирай дальше:101 отчёт выйдет с плашкой «0 ₽», скажи об этом пользователю и предложи другой период.1024. Метрика: есть ли коннектор Метрики; если да — какой счётчик (спроси или найди по домену посадочных).1035. Запиши выбор в `_state.json`, в чат одной строкой: «Путь B, Метрика: счётчик N» или что недоступно.104105## Шаг 2. Сбор106107**Путь B:** `python -m scripts.collect --workspace <ws> --account-id <ID> --date-from D --date-to D`.108Если дата конца позже вчера, скрипт сам сдвинет её и скажет об этом. Коды выхода:109110| Код | Что значит | Что делать |111|---|---|---|112| 0 | сбор выполнен, возможно частично | ошибки отдельных вызовов — в `collect_log.json` (`errors`), они сами попадут в ограничения; сбор не повторяй вслепую |113| 2 | нет ссылки, probe не прошёл, неверные даты, период пуст после сдвига или старше истории VK (~366 дней) | исправь ввод или переходи на путь A; про историю — назови пользователю доступную дату из сообщения |114| 3 | критический сбой: список кампаний не получен, описи кабинета нет | покажи причину из `collect_log.json`; путь A — только в новой рабочей папке |115| 4 | `raw/` уже не пуст | возьми новую рабочую папку, старую не чисти и не дописывай |116| 5 | расход за период 0 и живых групп нет: собраны только списки кампаний и групп | скажи пользователю и предложи другой кабинет (0 ₽ при живых группах — код 0, отчёт с плашкой) |117118**401.** `HTTP 401` в выводе probe/collect или в ошибке `collect_log.json` — ссылка подключения недействительна119или истекла: попроси у пользователя новую, `python -m scripts.credentials set --url <ссылка>`, повтори probe. На120молчаливый переход на путь A из-за 401 не соглашайся. 401 или ошибка авторизации на пути A — попроси переавторизовать121коннектор vk-ads и остановись.122123Журнал `collect_log.json` пишется всегда; при падении посреди сбора в нём поле `aborted`.124125**Путь A** — ты кладёшь ответы инструментов в `<ws>/raw/` по формату `scripts/raw_store.py`:126файл `<инструмент>__<NNN>.json` = `{"tool": ..., "arguments": {...}, "response": <ответ целиком, без правок>}`.127`NNN` — целое число; `tool` в содержимом совпадает с именем в названии файла. Для списков можно по файлу на128страницу либо один общий файл `{"items": [...]}` — но не оба сразу (дубли с разным содержимым останавливают129нормализацию); ответ списка — объект с массивом `items`.130**В `raw/` только такие файлы** — любой другой файл (заметки, черновики) ломает проверку.131Сбой — не данные: **ответ-ошибку в `raw/` не клади** (`isError`, `{"error": true, …}`): проверка его отвергнет, сбой запиши в `collect_log.json`.132Порядок и поля — `references/mcp-read-tools.md`; выполни строки 1–6 его таблицы, включая сегменты,133списки аудиторий и пиксели (без пикселей проверка пикселя пропускается). Сегменты — с134`fields=id,name,pass_condition,flags,relations,relations_count,created,updated`: по связям (`relations`) скрипты135определяют слой (пиксель, база — тёплый, ключевые фразы — холодный); сервер отверг `fields` — повтори без них. На пути A: кампании, группы и статистика по дням136(`vk_ads_statistics_day`, `entity=campaigns`, пачки ≤ 50 id, все группы кроме удалённых — архивные тоже, их расход137входит в итоги); объявления (`vk_ads_banners_list`; для архивных групп не вызывай) и их статистика по дням138(`entity=banners`) — только у 5 групп с наибольшим расходом; у дней `metrics="base"`. **Итоги периода считаются суммой дней:139`vk_ads_statistics_summary` — только за всё время, даты не передавай (с датами MCP откажет), `metrics="base,uniques"`.**140Строка 7 (сводка групп) необязательна: она даёт охват и141частоту только группам, созданным внутри периода; без неё частота «не определена», выгорание молчит, отчёт честно скажет.142**Большой ответ (Claude Desktop сохраняет его файлом, например список из десятков групп ≈ 260 КБ) руками не вставляй и143не пересказывай:** `python -m scripts.raw_store import --workspace <ws> --tool <инструмент> --arguments '<json аргументов144вызова>' --from <путь к файлу>` (в PowerShell удобнее `--arguments-file <файл с json>`). Команда сама проверит JSON и145отказывает по-русски на обрезанном или нетекстовом файле — тогда повтори вызов с меньшей выборкой (`limit`, `offset`).146Любой неудавшийся вызов инструмента запиши в `<ws>/collect_log.json` в том же виде, что пишет сбор:147`{"mode": "deep"|"quick", "date_from": "D", "date_to": "D", "calls": [{"tool": "...", "arguments": {...},148"ok": false, "error": "..."}], "errors": N, "critical": false}` (`critical: true`, если не получен149`vk_ads_campaigns_list`). `vk_ads_users_lists_list` с `code: zero_quota` (MCP 0.12.0 — HTTP 403) или 429 с `limits` с нулём — это не перегрузка, а нет прав:150повторять не надо, запиши вызов с `"no_access": true` — отчёт скажет «нет доступа к базам клиентов». Отчёт сам вынесет эти сбои в «Ограничения» — молча пропущенный вызов хуже записанного. Сбой, после которого тот же151вызов (тот же инструмент и те же аргументы) прошёл и лежит в `raw/`, отчёт сам не покажет — запись о нём не удаляй.152После — `python -m scripts.raw_store check --workspace <ws>` (код 3 — исправь названные файлы и повтори) до шага 3.153154## Шаг 3. Нормализация155156`python -m scripts.normalize --workspace <ws> --date-from D --date-to D [--target-cpa N] --path A|B`157158Код 3 — **остановись**, `dataset.json` не записан. Причины и что делать:159160- Нет живых групп, а статистика по архивным не получена (`no_stats`): есть ли расход, неизвестно — покажи причину из161 `collect_log.json` и повтори сбор статистики в новой рабочей папке; «расхода нет» пользователю не говори.162163- Проверка здравого смысла не пройдена: покажи пользователю строки из `sanity.json` и скажи, что отчёт на таких164 числах строить нельзя. `ctr_units` значит, что формат ответа VK изменился (`ctr` у VK уже в процентах), — это165 повод для задачи разработчикам. Расхождение сводки и дней аудит больше не блокирует: итоги берутся из дней.166- «raw/ не разобран» — файлы нарушают формат; запусти `raw_store check` и исправь.167- «✗ metrika.json: …» — см. шаг 4.168169Код 5 — **остановись**, `dataset.json` не записан: в кабинете нет живых групп (все удалены или в архиве) и расхода по170ним за период нет. Отчёт не строй, diagnose не запускай. Скажи пользователю одной фразой: «В кабинете сейчас нет живых171групп — все удалены или в архиве, и за период по ним нет расхода, проверять нечего» — и предложи другой кабинет (если их172несколько) или вернуться, когда группы заработают. Живые группы есть, а их расход за период 0 ₽ — нормализация проходит173и предупреждает: отчёт строится с крупной плашкой вверху (проверены только настройки). Текст плашки — как в174`references/report-template.md`: «Расход кабинета за период 0 ₽» (только если предполётка подтвердила 0 ₽),175«Живые группы за период не откручивали; X ₽ пришлось на удалённые группы», «Расход кабинета за период X ₽, у живых групп 0 ₽ —176разложить разницу по группам не удалось» или «Расход живых групп за период 0 ₽» (расход кабинета не проверялся).177Перескажи пользователю текст плашки и предложи другой период.178179## Шаг 4. Метрика (если подключена)180181По `references/metrika-vk.md` собери `<ws>/metrika.json` и обязательно запиши в него `date_from` и `date_to`182(период аудита). Затем повтори Шаг 3 — нормализация подхватит файл. Проверка строгая: при строке183«✗ metrika.json: …» исправь файл по сообщению и снова запусти normalize. Не получается — удали184`metrika.json` и иди без Метрики, это уйдёт в ограничения.185186## Шаг 5. Диагностика187188`python -m scripts.diagnose --workspace <ws>` → `findings.json`: находки (`findings`), чек-лист блоков A–G с баллами189(`checklist`) и вопросы к клиенту (`questions`). Нет `dataset.json` — код 2, вернись к шагу 3.190Правила, статусы и пороги — `references/diagnostic-rules.md`, `references/thresholds.json`.191Чек-лист отвечает «настроено ли» (✅ / ❌ / «—» / ❓), находки — «сколько стоит и что делать».192Статус «—» — данных нет или нечего проверять (нет активных групп или объявлений — «нечего проверять», не «нет данных»); ❓ — воронка подписки, лид-формы или Senler не используется и её193сначала уточняем у клиента (не ошибка). В балл они не входят.194195## Шаг 6. Гейт196197В чат 5–10 строк: общий балл («n / m»; нет живых групп — `total` пуст, вместо балла «кабинет не откручивает»), баллы блоков A–G, топ находок (уровень, объект, ₽, действие) из198`findings.json`. Затем вопросы к клиенту: те, что в `questions` помечены `important` («важно для вашего кабинета»),199задай клиенту сразу, по одному (список — `references/client-questions.md`); остальные покажет отчёт.200Ответы на `funnel_subscription` / `funnel_leadform` / `funnel_senler` запиши в `<ws>/client_answers.json`:201`{"funnel_leadform": {"verdict": "na" | "potential", "answer": "<слова клиента>"}}` (`na` — воронка клиенту не202подходит, `potential` — подходит, но не используется; критерии — `references/client-questions.md`; ответ203неясен — не записывай). Затем снова `python -m scripts.diagnose --workspace <ws>` — чек-лист и вопросы пересоберутся204(`na` / 🟢 вместо ❓, при `potential` — находка «Потенциал роста»); ✅ и ❌ ответ не меняет.205Повторный запуск перезаписывает `findings.json`, поэтому `client_note` впиши после него. Ответ клиента, объясняющий конкретную находку, впиши в неё полем `"client_note": "<текст клиента>"`, числа не правь;206отчёт покажет её с пометкой «Объяснено клиентом». Общий ответ — в сводку. И один вопрос: «Есть контекст, который207меняет вывод? Например, группа тестовая, сезон, акция». Затем шаг 7.208209## Шаг 7. Отчёт210211`python -m scripts.render_report --workspace <ws> --slug <slug>` → `<ws>/АУДИТ_<slug>.html`: чек-лист с баллами,212находки, вопросы к клиенту, ограничения (в том числе «Не проверено «…»: …»).213Покажи файл способом, который есть в среде, и дай сводку 5–10 строк; есть предупреждение «Кабинет менялся после214конца периода» — скажи, что статусы и бюджеты в отчёте на дату сбора. Структура отчёта —215`references/report-template.md`. Предложи передать действия в vk-ads-manager.216217---218219# Быстрый анализ2202211. Создай новую рабочую папку (каждый прогон — новая). Охват: кабинет, день (по умолчанию вчера; сегодняшний и будущие дни скрипт отвергнет), целевой CPA если известен.2222. Предполётка как в Шаге 1, без Метрики.2233. Путь B: `python -m scripts.collect --workspace <ws> --account-id <ID> --mode quick --date-from <день−7> --date-to <день>`224 (коды выхода те же, что в Шаге 2);225 путь A: `vk_ads_ad_plans_list`, `vk_ads_campaigns_list` (поля из `references/mcp-read-tools.md`) и `vk_ads_statistics_day` по живым группам226 за те же 8 дней → `raw/`, затем `raw_store check`.2274. `python -m scripts.normalize --workspace <ws> --date-from <день−7> --date-to <день> --path A|B` (код 5 — живых групп228 нет, расхода нет: скажи пользователю, быстрый анализ не делай)2295. `python -m scripts.quick --workspace <ws> --day <день> [--target-cpa N]` — выведи его строки как есть.230 Флаги ставятся только активным группам (паузные входят в итоги). Нет данных за день — скрипт выведет заголовок231 и «нет данных»: передай это пользователю, не домысливай. Код 2 — неверный день или нет `dataset.json`.2326. Есть аномалии — предложи глубокий аудит; сам не запускай.233234---235236# Ограничения237238Всегда входят в отчёт — `references/limitations.md`. Плюс недобранное в прогоне: путь A, нет Метрики,239не собраны объявления, статистика или пиксели, ошибки и обрыв сбора. Молча упрощённый результат хуже240честно недобранного.241242# Стиль243244- Один вопрос за раз. Артефакт — в файл, в чат — сводка 5–10 строк.245- Новая просьба важнее плана: сообщение посреди аудита — сначала ответ на него, а не следующий246 шаг. Просьба изменить кабинет — прямой отказ (в начале файла) и стоп.247- Не выдумывай причин: «не знаю, данных нет» лучше догадки. Гипотеза — помечай как гипотезу.248- Действие находки — что сделать, а не как в интерфейсе: шаги кабинета, названия пунктов и периоды не249 придумывай. Ориентир из методики (например, бюджет «2 × CPA») подавай как ориентир, с оговоркой из250 `action`, а не как требование VK; ограничение бюджета, названное пользователем, важнее ориентира.251- Деньги — в рублях, CTR — в процентах; сырые значения API не показывай.252253# Возобновление254255Только по просьбе продолжить; сообщение с другой просьбой — сначала ответ на неё.256257«Продолжаем аудит VK» → найди последнюю `vk-audits/*/_state.json`, по наличию файлов258(`raw/`, `dataset.json`, `findings.json`, `АУДИТ_*.html`) продолжи с первого незавершённого шага.259Если `raw/` уже заполнен, заново не собирай: продолжай с нормализации.