# Пакет для Яндекс Директ

`yandex-direct-manager` — скилл, который проводит от брифа до новой кампании в Яндекс Директе. ИИ-агент собирает семантику, строит структуру, готовит минус-слова и объявления, проектирует цели Метрики и стратегию торгов, а затем создаёт доступную часть кампании в черновике.

> **Активация всегда остаётся за человеком.** Скилл не включает рекламу и не начинает расходовать бюджет.

Фокус — создание новой кампании. Исследование рынка, выбор канала и ведение уже работающих кампаний в пакет не входят.

## На чём стоит маршрут

Собрать кампанию можно и разговором с языковой моделью. Разница в том, что модель выдаст широкую семантику, назовёт правдоподобную цену клика и не заметит, что две кампании начали торговаться друг против друга. Маршрут пакета устроен так, чтобы эти ошибки не проходили дальше того шага, где возникают:

- **Семантика держится в своём угле.** Сбор идёт не по общей выдаче, а от масок отстройки, построенных из УТП: сужающие слова, синонимы, товарозаменители. Рекурсивные волны ограничены порогами частотности и стоп-условием на долю нового — набор прекращается, когда перестаёт приносить целевые фразы.
- **У цены клика всегда указан источник** — история аккаунта, данные живого аукциона или отраслевой справочник. Прикидка запрещена прямо: непроверенная частотность помечается, а не выдаётся за факт.
- **Кросс-минусация строится между кампаниями,** а не только внутри. Это то место, где обычно теряют деньги: без неё кампании перекупают друг у друга один и тот же запрос.
- **Цели Метрики проектируются до создания.** Набор конверсий согласуется с маркетологом, и только потом заводится, — иначе стратегия торгов оптимизируется под случайное событие.
- **Есть безусловные остановки.** Нет счётчика Метрики на сайте или тематика попадает в лицензируемые и запрещённые — маршрут прекращается, а не обходит проверку.

Методики этапов лежат в [`references/`](references/) — двадцать справочников с порогами, формулами и требованиями площадки. Их видно целиком до установки.

## Как проходит работа

Скилл создаёт рабочую папку кампании, каждый шаг сохраняет результат отдельным файлом, и этот файл становится входом для следующего. Маршрут делится на четыре части.

**Семантика.** Бриф, маски отстройки, прогноз необходимого объёма и цены клика, рекурсивный сбор из Вордстата, кластеризация по частотности и каналам Поиск и РСЯ. Сбор вынесен в отдельный рабочий поток, чтобы тысячи фраз не заполняли основной разговор.

**Структура.** Разбиение на кампании и группы по углам позиционирования, три уровня минус-слов и матрица кросс-минусов, проектирование целей Метрики.

**Материалы.** Заголовки и тексты в лимитах площадки и требованиях модерации, проверка перед загрузкой. Изображения и короткие видео для РСЯ агент генерирует при заданных ключах сервисов генерации; без них готовит техническое задание.

**Загрузка.** Стратегия торгов по фазам, создание кампании в черновике через MCP-серверы Директа и Вордстата и список того, что осталось завершить в кабинете.

На узловых развилках агент показывает решение и ждёт подтверждения: бриф, маски, прогноз, структура, минус-слова, цели, объявления, стратегия и сама загрузка проходят через маркетолога.

## Что входит в пакет

| Путь | Содержимое |
|---|---|
| [`SKILL.md`](SKILL.md) | маршрут работы |
| [`references/`](references/) | 20 методических справочников по этапам |
| [`subagents/`](subagents/) | отдельный поток сбора и кластеризации семантики |
| [`scripts/`](scripts/) | сбор семантики, оценка цены клика, проверка лимитов, генерация материалов и таблиц |
| [`docs/`](docs/) | подключение MCP-серверов Директа и Вордстата |

Если библиотек для XLSX и DOCX нет, генераторы сохраняют CSV и Markdown.

## Что делает агент, а что остаётся человеку

**Агент:**

- собирает семантику и оценивает CPC по доступным данным;
- кластеризует ключи и строит структуру;
- готовит минус-слова, цели, объявления и стратегию торгов;
- создаёт поддерживаемые сущности в черновике;
- собирает медиаплан и файлы для ручной загрузки.

**Человек:**

- подтверждает бриф, маски, прогноз, структуру, минус-слова, цели, объявления и стратегию;
- устанавливает счётчик Метрики и коллтрекинг;
- добавляет изображения и недоступные через MCP настройки;
- передаёт токены доступа;
- проверяет кампанию и вручную активирует показы.

## Ограничения

- Пакет не ведёт и не оптимизирует работающие кампании.
- Он не выбирает рекламный канал и не разрабатывает стратегию бренда.
- Он не проводит исследование конкурентов, не строит портреты аудитории и не проверяет посадочную страницу как отдельную задачу.
- Без доступа к Вордстату данные о частотности помечаются как непроверенные.
- Визуалы РСЯ и комбинаторных объявлений агент генерирует при заданных ключах сервисов генерации, иначе готовит техническое задание; загрузка файлов в кабинет ручная.
- Стратегию торгов, привязку целей Метрики, быстрые ссылки, уточнения и часть форматов может потребоваться завершить вручную — это зависит от подключённого MCP-сервера.
- Офлайн-конверсии из CRM и коллтрекинга требуют отдельной интеграции.
- Скилл работает на русском языке.

## Требования

Обязательно:

- ИИ-агент, который умеет работать с файлами проекта;
- аккаунт в Яндекс Директе.

Для вспомогательных скриптов нужен Python 3.9 или новее.

Необязательно:

- доступ к хостовым MCP `yandex-direct` и `yandex-wordstat` (aihub.click.ru, один API-токен click.ru) — основной путь для live-данных, сбора семантики и заливки;
- ключ Yandex Cloud Search API — фолбек сбора семантики, когда MCP не подключён;
- OAuth-токен Яндекс Метрики для создания целей;
- OAuth-токен Яндекс Директа — только для локального фолбек-режима MCP-сервера.

Без ключей пакет сохраняет готовые файлы для ручной работы через Директ Коммандер и интерфейс Директа.

## Установка

### Клонирование

```bash
git clone https://github.com/ai-hub-open/yandex-direct-manager.git
cd yandex-direct-manager
python install.py
```

`install.py` проверит версию Python, поставит зависимости и прогонит самопроверку модулей; при проблеме укажет, что именно чинить. Альтернативы: готовый архив `yandex-direct-manager.skill` из [релизов](https://github.com/ai-hub-open/yandex-direct-manager/releases) (распаковать и запустить `python install.py` внутри) или **Code → Download ZIP**.

В пакете один файл `SKILL.md` — в корне. `subagents/semantics.md` — вспомогательная инструкция; переименовывать её в `SKILL.md` не нужно.

### Claude Code

```bash
# macOS / Linux
cp -r yandex-direct-manager ~/.claude/skills/

# Windows PowerShell
Copy-Item -Recurse yandex-direct-manager "$env:USERPROFILE\.claude\skills\"
```

После перезапуска агента достаточно попросить его собрать рекламную кампанию в Яндекс Директе.

### Среда с загрузкой скиллов

1. Папка `yandex-direct-manager` упаковывается в ZIP.
2. Архив загружается в разделе скиллов.
3. Пакет включается в списке.

### Среда без отдельной функции скиллов

Содержимое `SKILL.md` добавляется в инструкции проекта, файлы из `references/` и `assets/` загружаются рядом. Если среда не запускает локальные скрипты, предложенные команды выполняются вручную, а результат возвращается в диалог.

## Ключи и доступы

**Основной путь — хостовые MCP aihub.click.ru.** Один API-токен click.ru покрывает Директ и Вордстат, ключи Яндекса не нужны:

```bash
python -m scripts.setup_yandex_direct_mcp \
  --token <CLICK_RU_TOKEN> --client-login <ЛОГИН_ДИРЕКТА> --target all
```

Подробности — в [`docs/hosted-mcp-setup.md`](docs/hosted-mcp-setup.md) и `references/yandex-direct-mcp.md` → «Подключение».

Переменные ниже — для фолбек-режимов без MCP. Создайте `.env` из шаблона:

```bash
cp .env.example .env
```

| Переменная | Назначение |
|---|---|
| `WORDSTAT_API_KEY` | доступ к Yandex Cloud Search API |
| `WORDSTAT_FOLDER_ID` | идентификатор каталога Yandex Cloud |
| `YANDEX_DIRECT_TOKEN` | доступ к API Яндекс Директа |
| `OPENAI_API_KEY` | генерация изображений на Шаге 8.5 (необязательно) |
| `REPLICATE_API_TOKEN` | генерация видео на Шаге 8.5 (необязательно) |

Файл `.env` находится в `.gitignore`. Не добавляйте его в репозиторий и не передавайте вместе с результатами кампании.

Проверка подключения к Вордстату:

```bash
python -m scripts.wordstat_api --check
```

## Необязательные зависимости

Ставятся автоматически при `python install.py`; вручную:

```bash
pip install -r requirements.txt
```

- без `openpyxl` таблица объявлений сохраняется в CSV;
- без `python-docx` медиаплан сохраняется в Markdown.

## Тесты

Мок-тесты — обязательный гейт перед мержем. Сеть не трогают: OpenAI, Replicate и Директ подменяются. Реальные ключи в `~/.yandex-direct-manager` не читаются.

```bash
pip install -r requirements-dev.txt
pytest
```

Новый скрипт в `scripts/` — новый файл `tests/test_<module>.py` по образцу `test_preflight.py`: бизнес-правило, а не формулировка сообщения.

## Безопасность

- секреты хранятся только в `.env` или переменных окружения;
- рабочая папка `direct-campaigns/` исключена из Git;
- начинайте проверку API в песочнице;
- перед запуском проверьте сайт, Метрику, коллтрекинг, бюджет и маркировку рекламы;
- активация кампании выполняется только вручную.

## Частые вопросы

**Нужны ли Python и API-ключи?**
Нет. Без них пакет работает в ручном режиме и готовит файлы для загрузки через Директ Коммандер.

**Почему кампания не запустилась после загрузки?**
Так задумано: она остаётся выключенной. Проверьте настройки и активируйте её вручную.

**Агент не видит файл из `references/`.**
В среде с доступом к папке он прочитает файл сам. В другой среде справочники загружаются в проект или передаются в диалог по одному.