# Журнал изменений

Версии — [semver](https://semver.org/lang/ru/): до 1.0 состав шагов и материалов может меняться.

## 0.12.1 — 2026-08-26

Подстройка скилла под реальное поведение Директа и MCP по итогам живого прогона.
Баги коннектора вынесены отдельным файлом-задачей `TASK-mcp-connector-fixes.md`
(параллельный трек); правки ниже делают скилл корректным на текущем MCP.

- **Сетевые стратегии ЕПК: только автостратегии.** `MAXIMUM_COVERAGE` («максимальный охват»),
  `NETWORK_DEFAULT` и ручные ставки в сетях Директ для ЕПК отклоняет — Яндекс отключил
  ручное управление ставками в РСЯ и поиск+РСЯ ещё в 2024 году ([eLama](https://elama.ru/blog/yandeks-direkt-otklyuchaet-ruchnoe-upravlenie-stavkami-vrsya-kak-podgotovitsya-ichto-delat/)).
  Исправлено в `yandex-direct-mcp.md` (таблица стратегий, `keywordbids_set`) и
  `bidding-strategy.md`. Для сети валидны две автостратегии: «Максимум конверсий» и авто
  «Максимум кликов».
- **Ставка автотаргетинга.** В `05_campaign_structure.json` добавлено поле `autotargeting_bid`
  рядом с `autotargeting_categories`: на Поиске ЕПК автотаргетинг обязателен, отключить нельзя,
  и он может дать половину трафика группы — ставку задаём осознанно. MCP им пока не управляет,
  пункт уходит в `10_launch_log.md`. Отражено в `campaign-structure.md` и `SKILL.md` Шаг 5.
- **Дневной бюджет — от 300 ₽.** Тот же минимум, что и недельный; применяется при ручных
  ставках на Поиске. Прописано в `bidding-strategy.md`, `yandex-direct-mcp.md` (`daily_budget`)
  и `SKILL.md` Шаг 9.
- **Свежесть частотностей.** Правило читать `cache_date` в ответе `wordstat_shows_batch` и
  флагить фразы с кэшем старше года (встречается кэш 2019–2020) — расчёт бюджета по ним
  помечается ориентировочным. Добавлено в `wordstat-mcp.md`.
- **Округлённые ID.** Предупреждение, что 19-значные ID приходят от коннектора округлёнными:
  доверять им как точным нельзя, идемпотентность заливки по ID ненадёжна, состояние сверяется
  через `campaigns_get`. Добавлено в `yandex-direct-mcp.md` и `SKILL.md` Шаг 10Б.

## 0.12.0 — 2026-08-26

Сверка с реальными хостовыми MCP: описанный сервер Wordstat не совпадал с фактическим.

- **Wordstat: методика Шага 3 переписана.** Сервер `yandex-wordstat` отдаёт только
  `wordstat_shows_batch` (частотность до 1000 фраз за вызов) — ни `top_requests`, ни
  `results`/`associations`, ни регионов и динамики. Рекурсивные волны через MCP невыполнимы;
  MCP переведён в роль верификатора частотностей, расширение семантики идёт через
  `scripts/wordstat_api.py` (Cloud Search API) либо комбинаторику масок с пакетным пробивом.
  Шаг 1 стал дешевле: все маски одним вызовом вместо цикла по фразе.
- **Выбор кабинета стал явным шагом.** Новый Шаг 0.5 и Use case 0: `accounts_get`,
  гейт выбора при нескольких кабинетах, `client_login` из `_state.json` в каждом вызове.
  Раньше скилл не упоминал `client_login` вовсе и заливал в кабинет по умолчанию.
  Уточнено по коду моста: `client_login` идёт в кабинет-специфичные инструменты, а
  `accounts_get`, `forecast_bids` и `dictionaries_*` (accountAgnostic) его не принимают.
- **Правило «фильтр обязателен» распространено на отчёты.** `report_*` без `campaign_ids`
  на прокси-подключении отвечают кодом 8000. Шаг 8 звал `report_campaign` без ids — исправлено.
- **`forecast_bids` через второе подключение.** Если в сессии есть сервер в прямом
  OAuth-режиме, прогноз считается на нём, а заливка остаётся в прокси-кабинете.
- **`adimages_add`:** рантайм-проверка URL-параметра заменена на факт — параметра нет
  (сверено по схеме: `file_path`, `name`, `crop`, `crop_offset`, `dry_run`),
  картинки всегда уходят в ручную работу.
- **`dictionaries_regions`** понижен до крайней меры: 2,87 МБ ответа в контекст не помещаются.
- **Обещание автопочинки чтения в MCP 0.5.1** помечено как невыкаченное на хостовых инстансах.
- **Правило ретрая** при `gateway 502` у обоих шлюзов.

## 0.11.0 — 2026-08-19

Переход на хостовые MCP aihub.click.ru: локальный Bun и клон репозитория больше не нужны.

- **Основной путь — хостовые серверы.** `yandex-direct` (`https://direct-mcp.aihub.click.ru/mcp`) и новый `yandex-wordstat` (`https://wordstat-mcp.aihub.click.ru/mcp`). Авторизация у обоих — один API-токен click.ru (проверено прогоном: без токена 401, с недействительным — «токен недействителен»). Следствия режима Click.ru сохраняются: `forecast_bids` недоступен, песочницы нет.
- **Wordstat переехал в MCP.** Новый справочник `references/wordstat-mcp.md`: частотности масок (Шаг 1) и рекурсивный сбор семантики волнами (Шаг 3) крутятся через инструменты сервера; `scripts/wordstat_api.py` (ключ Cloud Search API) остаётся фолбеком, дальше — браузерный пробив. Цепочка приоритетов: MCP → скрипт → браузер → список от маркетолога. В `_state.json` появилось `wordstat_mcp_available` рядом с `wordstat_api_available`.
- **Установщик переписан.** `scripts/setup_yandex_direct_mcp.py` больше не требует путь к локальному репо и умеет не только Claude Desktop: цели `cursor` (`~/.cursor/mcp.json`), `cursor-project`, `claude-code` (`.mcp.json`), `claude-desktop` (мост `mcp-remote`), `all`; флаги `--dry-run`, `--remove`, `--server direct|wordstat|both`. Токен и логин подставляются из аргументов, env или `manage_credentials`.
- **Ограничение хоста для картинок.** `adimages_add` принимает `file_path` на диске сервера — файлы маркетолога хосту недоступны. Шаг 10 и Use case 5: сначала проверка URL-параметра в `tools/list`, иначе заливка без картинок и пункт ручной работы в `10_launch_log.md`.
- **Общий справочник подключения** — `docs/hosted-mcp-setup.md` в корне репозитория пакета (три сервера, таблица заголовков, конфиги трёх клиентов, проверка связи).
- **Имя скилла в `SKILL.md` — `yandex-direct-manager`** (как папка репозитория и `.skill`-архив), вместо устаревшего `yandex-direct-create-pipeline`. Автоподхват по description сохранён (`disable-model-invocation` снят).

## 0.10.0 — 2026-08-10

Слияние `aihub-139` и перенос рабочих кусков из форка генерации визуалов.

- **Шаг 8.5 больше не заглушка.** Генерация картинок (OpenAI) и видео (Replicate) с гейтами, валидация ассетов под техтребования Директа. Справочники `visual-generation.md`, `video-generation.md`, `replicate-models.md`; скрипты `generate_creative_images.py`, `generate_creative_videos.py`, `validate_assets.py`, `credentials.py` / `manage_credentials.py`.
- **`forecast_cpc.py` — два бэкенда прогноза по произвольным фразам** без MCP: прямой токен Яндекса через Live API v4 и Click.ru через временный DRAFT. Закрывает дыру Шага 2 под Click.ru, где `forecast_bids` недоступен. Ссылки на несуществующий `yandex_direct_api_call` заменены на `keywordbids_get`.
- **Тесты как обязательный гейт:** `pytest` — 151 проверка тел запросов, валидации ассетов, выбора бэкенда прогноза и генерации визуалов без обращения к сети.
- **Исправлено противоречие про заливку видео.** `video-generation.md` обещал цепочку `AdVideos.add` → `Creatives.add` → `VideoExtensionIds` «на Шаге 10 через MCP», хотя этих обёрток в MCP нет и `yandex-direct-mcp.md` прямо об этом говорил. Раздел переписан: видео добавляется к объявлению вручную через интерфейс, пункт уходит в список ручной работы `10_launch_log.md`. Сгенерированный ролик больше не выглядит как то, что зальётся само.
- **Правила чтения через MCP описаны до первого вызова.** Живой прогон сервера через прокси Click.ru нашёл два дефекта: без единого фильтра читающие инструменты отправляют пустой `SelectionCriteria` (код 8000), а список длиннее 10 кампаний отклоняется целиком (код 4001). Оба чинятся в MCP 0.5.1, но обход нужен уже сейчас — он описан в `yandex-direct-mcp.md` и в Use case 2 `mcp-account-integration.md`. Отдельно оговорено, что `adimages_get` на 0.5.0 работает только по известным хешам.
- **Фолбек Шага 2 под Click.ru проверен вживую**, а не только описан: `forecast_bids` сервер отклоняет сам с читаемым объяснением, `keywordbids_get` отдаёт полную лесенку аукциона в том формате, который разбирает `forecast_cpc.py`. Пункт 4.2 в `TODO.md` закрыт.
- **Зафиксировано решение не переносить прямую заливку через API** (`deploy_campaign.py` из форка): скилл сознательно ушёл на MCP-заливку в 0.9.0, скрипт ни разу не прогонялся даже в песочнице, а его единственная уникальная часть — загрузка видео — закрыта ручным путём. Новая часть 5 «Принятые решения» в `TODO.md`.

## 0.9.1 — 2026-08-03

Требования к среде исполнения названы явно. Раньше скилл молча предполагал, что среда умеет запускать код, порождать дочерних агентов, читать веб-страницы и звать MCP; в части мест запасной путь был написан, в части — нет, и агент в другой среде решал на ходу.

- **Новый раздел «Что нужно от среды»** в начале `SKILL.md`: обязательный минимум — чтение и запись файлов плюс диалог с пользователем; остальные семь способностей необязательны, у каждой в таблице указано, где она нужна и что делать, если её нет.
- **Ветка «если нет» дописана там, где её не было.** Главный пробел — отсутствие запуска кода: `preflight.py` стоит блокирующим гейтом перед заливкой, а что делать без него, не было сказано нигде. Теперь описана ручная сверка лимитов по `yandex-direct-specs.md`, и блокирующая роль гейта сохранена. Также дописаны ветки для отсутствия чтения веб-страниц на Шаге 7 (проверка счётчика Метрики), отсутствия поиска в интернете на Шаге 8, отсутствия браузера на Шагах 1 и 3.
- **Пометка о пропуске в артефактах.** Шаг, выполненный без необязательной способности, пишет в свой артефакт строку «пропущено: нет … — сделано вместо … Потеряно: … Как добрать: …». Сводный список всех пропусков — обязательный раздел «Пропущено из-за среды» в `10_launch_log.md`: маркетолог видит, на каких данных построена кампания, а на каких нет, до активации.
- **Названия инструментов конкретных приложений приведены как примеры.** `WebFetch`, `WebSearch`, `Task` / `subagent_type`, `claude-in-chrome`, префикс `mcp__yandex-direct__`, `computer://`-ссылки — теперь всюду с пометкой «например», а инструкция называет способность. Слово «харнесс» заменено на «среда» (`SKILL.md`, `subagents/semantics.md`).
- Оговорено, что `scripts/setup_yandex_direct_mcp.py` умеет только конфиг Claude Desktop: в других средах MCP подключает человек, а скилл идёт по ветке без live-данных, а не пытается настроить.

## 0.9.0 — 2026-07-31

Сверка с MCP-сервером `yandex-direct-mcp` 0.5.0 (50 инструментов) и переход на заливку через MCP.

- **Кампания заливается через MCP целиком.** Раньше основным путём был Директ Коммандер: скилл считал, что MCP умеет только классические объявления и не создаёт оболочку ЕПК. Обе посылки устарели — есть `ads_add_responsive` (комбинаторное объявление), `campaigns_add(campaign_type: "UNIFIED")` и `adgroups_add(group_type: "UNIFIED")`. Коммандер и xlsx остались фолбеком на случай, когда MCP не подключён.
- **Исправлены вызовы несуществующих инструментов.** Скилл в четырёх местах звал `yandex_direct_api_call` — универсального passthrough в MCP нет; заменён штатным `keywordbids_get`. Плюс опечатка `reports_campaign` вместо `report_campaign`.
- **Исправлены схемы вызовов.** `adgroups_add` и `ads_add` вызывались с массивами вместо плоских аргументов; `keywords_add` — с несуществующим параметром `bid` (ставки задаются отдельно через `keywordbids_set`); `bidmodifiers_demographics` — с дельтами вроде `-10` вместо множителей 0–1300 (мобильные вообще в другом инструменте); `campaigns_get` — с несуществующим параметром `Counters`.
- **Стратегия торгов, счётчик Метрики и ставки больше не «доделать руками».** Шаг 9 заливается как параметры API, цели привязываются через `counter_ids` и `priority_goals`, ставки выставляются через `keywordbids_set`. В `09_bidding_strategy.json` фазы описаны параметрами API вместо свободных строк; в `bidding-strategy.md` появился раздел «Маппинг в API».
- **Прогноз CPC без мутаций аккаунта.** Утверждение «прогноза по произвольным фразам нет» устарело: инструмент `forecast_bids` даёт вилку цены клика по маскам до создания кампании. Приём с временной DRAFT-кампанией ради снятия аукциона убран. Учтено ограничение: в режиме прокси Click.ru прогноз недоступен.
- **Быстрые ссылки, уточнения и отображаемая ссылка заливаются автоматически** — три пункта ручной работы из `10_launch_log.md` закрыты.
- **Сквозной `campaign_key`.** Идентификатор кампании имел четыре несовместимых формата в артефактах 05/06/07/09 — теперь один, задаётся на Шаге 5.
- **Новый `scripts/preflight.py`** — проверка лимитов Директа до первого write-вызова: длины заголовков, текстов и слов в них, отображаемая ссылка, быстрые ссылки, уточнения, наличие файлов изображений, объём минус-фраз, число ключей в группе. MCP этих проверок не делает.
- **Ценность конверсии** добавлена в `07_metrika_goals.json`: без неё `priority_goals` не принимается. Нет данных — цели не передаются, счётчик привязывается всё равно.
- Исправлен баг: `generate_ads_xlsx.py` искал `creatives.json`, тогда как артефакт называется `08_creatives.json`, — вызов из SKILL.md падал.
- Удалён мёртвый `scripts/yandex_direct_api.py`: он читал схему объявлений, которой нет с 0.8.0, и молча создавал 0 объявлений, изображая фолбек для быстрых ссылок и уточнений.
- Удалены устаревшие `references/yandex-direct-api.md` (заглушка) и `references/yandex-direct-mcp-gaps.md` (описывал MCP из 30 инструментов, большая часть пробелов закрыта). Актуальные границы MCP — в разделе «Чего MCP не умеет» справочника.
- Честный список ручной работы: автотаргетинг (обязателен в ЕПК на Поиске), Библиотека минус-фраз при переполнении лимита, пакетные стратегии, временной таргетинг, кнопка действия/цена/промоакция/карусель, видео.
- `assets/` теперь попадает в поставляемый архив: схема `08_creatives.json` нужна скиллу в рантайме.
- Тесты: 44 вместо 10, проверяют бизнес-правила лимитов, а не раскладку колонок xlsx.

## 0.8.0 — 2026-07-27

Сверка со справкой Яндекс Директа (422 статьи) и переход на единую модель объявлений.

- Исправлены устаревшие факты: актуальные названия стратегий торгов («Максимум конверсий» и семейство), пороги обучения, лимиты видео и изображений, обязательность автотаргетинга в ЕПК, правила модерации и запрещённые тематики.
- Единая модель объявлений — комбинаторное объявление ЕПК: классическая ТГО-модель удалена из скрипта сборки (площадка заморозила ТГО с 30.06.2026, автомиграция с 14.07).
- Новые справочники: юридически чувствительные тематики, импорт в Директ Коммандер, работа с Вордстатом в браузере без API-ключа.
- Пакетные стратегии, стоп-гейт по тематикам на первом шаге, обновлённые лимиты уточнений и минус-фраз.
- Тесты обновлены под единую модель (10 проходят).

## 0.7.1 — 2026-07-27

- Установщик зависимостей `install.py` с самопроверкой (Python ≥ 3.9, зависимости, smoke-тест модулей) и `requirements.txt`.
- Сборка переносимого архива скилла: `package.sh` + `scripts/package_skill.py`; архив приложен к релизу.
- Кода этапов воронки изменения не касаются.

## 0.7.0 — 2026-07-27

Первый публичный релиз.

- Полный цикл: семантика из Вордстата, разбивка НЧ/СЧ/ВЧ, минус-слова и кросс-минусация, объявления по лимитам Директа, цели Метрики, стратегия торгов, заливка кампании черновиком через MCP-мост.
- Скрипты этапов и настройка моста (`scripts/`), справочники и тесты.
- Номер версии отражает фактическую зрелость; изменения до 0.7.0 велись без журнала.