Инструкция: отчётность для Директа через ИИ

Еженедельный PDF-отчёт по Яндекс Директу можно собирать через ИИ-агента (Cursor или другую агентную среду): токен API Директа, Telegram-бот, готовый промпт и запуск по расписанию. Ниже — пошаговая инструкция с экрана эфира «Автоматизация отчётности для Яндекс Директ через ИИ» (Роман Скороходов, Константин Горбунов).

Смежные материалы AdPump про API Яндекс Директа: OAuth и доступ, Reports API, сервисы v5, кампании, ключи и ставки, сценарии автоматизации.

Про API Яндекс Метрики: введение, возможности, OAuth и архитектура, Reports API на практике, цели, доступы к счётчику.

Содержание

1. Кто проводил эфир
2. Что разберём
3. Что получите на выходе
4. Что понадобится
5. Шаг 1. OAuth-приложение Директа
6. Шаг 2. Заявка на API в самом Директе
7. Шаг 3. Токен после одобрения
8. Нюансы API: что не отдаётся
9. Telegram-бот и chat_id
10. Промпт пайплайна
11. GitHub, облако и расписание
12. Чек-лист
13. Частые вопросы
14. Курс «Монстры Маркетинга»

---

1. Кто проводил эфир

Роман Скороходов — владелец маркетингового агентства. 70% клиентов — строительные компании; работа по СЗФО, ЦФО, Поволжью, Уралу и Югу России. Средний ежемесячный бюджет клиентов: 30+ млн ₽ под управлением в 2025–2026. Рекомендованный специалист от Яндекса, куратор-эксперт курса «Монстры Маркетинга», команда агентства — 8 человек.

Где найти после эфира: vk.com/dada__etoya, @vjobindirect.

Константин Горбунов — контекстная реклама с 2011 года, основатель агентства Monster Context (2013), спикер конференций Яндекс, Суровый Питерский SMM, Инфоконференция, Race, Monster Traffic. Программа «Монстры Маркетинга»: 30+ потоков, 3500+ учеников. Автор YouTube-канала по интернет-маркетингу (27 тыс. подписчиков), создатель сервиса AdPump. 20 000+ часов практики по Яндекс Директ и Google Ads.

---

2. Что разберём

1. Как получить API-токен от кабинета Яндекс Директ.
2. Нюансы при работе с API Яндекс Директ.
3. Токен Telegram-бота для автоматической отправки отчётов клиенту по расписанию.
4. Промпт пайплайна отчётности.
5. Выгрузка проекта на облако или сервер с настройкой расписания.

---

3. Что получите на выходе

ИИ собирает скрипт, который раз в неделю:

• выгружает статистику кампаний из API Директа;
• добавляет отказы и глубину из Метрики (metrika:read);
• сравнивает снимок настроек с прошлой неделей;
• собирает PDF и шлёт его в чат с клиентом через Telegram-бота.

---

4. Что понадобится

---

5. Шаг 1. Создать OAuth-приложение

Это не страница заявки в Директе. Сначала приложение на oauth.yandex.ru. Войдите под логином агентства (главный представитель или тот, на кого заведён доступ).

1. Тип приложения: «Для доступа к API или отладки» — не «для авторизации пользователей».
2. Название: например MC Weekly Reports.
3. Почта — рабочая, на неё придёт ответ по заявке.
4. В блоке «Доступ к данным» добавьте ровно два пункта:
   • Использование API Яндекс Директа (direct:api) — OAuth Директа
   • Получение статистики, чтение параметров своих и доверенных счётчиков (metrika:read) — OAuth Метрики. Без этого в отчёте не будет отказов и глубины.
5. Нажмите «Создать приложение».
6. Сохраните ClientID и Client secret. Список приложений: oauth.yandex.ru.

Подробнее про токены и заголовки: OAuth в API Директа и OAuth в API Метрики.

---

6. Шаг 2. Заявка в самом Директе

Это не oauth.yandex.ru. Откройте список заявок API (Настройки API → Мои заявки).

Если страница не открывается: сначала примите соглашение API в настройках Директа. Для входа в Директ Про должна быть хотя бы одна кампания.

1. Нажмите «Новая заявка».
2. В списке выберите тот ClientID, который только что создали.
3. В описании напишите: «агентская выгрузка статистики и еженедельные PDF-отчёты клиентам, без управления ставками».
4. Язык — Python, протокол JSON, основная функция — получение статистики и отчётов. Приложите пример PDF-отчёта, если есть.
5. Отправьте. Смотрят до 7 дней, статус там же: одобрена / отклонена / на рассмотрении. На практике часто одобряют за 10–15 минут.

---

7. Шаг 3. Токен — только после «одобрена»

Подставьте свой ClientID в ссылку и откройте её под тем аккаунтом, которому выдаёте доступ:

https://oauth.yandex.ru/authorize?response_type=token&client_id=СЮДА_CLIENT_ID

После согласия Яндекс покажет страницу с токеном (адрес вроде oauth.yandex.ru/verification_code). Скопируйте токен и храните в .env, не в репозитории.

---

8. Нюансы API: что реально можно получить

Журнал из интерфейса Директа («История изменений») через API не отдаётся. Сервис Changes даёт только флаги, что какой-то блок трогали:

Чтобы написать в отчёте «добавили минусы в кампанию X», нужно самим снять снимок (Campaigns.get, Keywords.get, минусы, бюджет, стратегия) и сравнить с прошлым своим снимком. Без прошлого снимка ИИ не должна выдумывать формулировки. Обзор сервисов — API Директа v5.

Для качественной еженедельной выжимки нужны 1–2 недели накопления снимков «до / после» — затем ИИ пишет текст отчёта на их основе.

---

9. Telegram-бот и chat_id клиента

Шаг 1. Откройте официального BotFather:

• Telegram на телефоне или десктопе.
• Поиск: @BotFather — только аккаунт с галочкой.
• Прямая ссылка: t.me/BotFather → Start.

Шаг 2. Создайте нового бота («Create a New Bot»). Username обязательно заканчивается на bot (например otchet_agency_bot). Скопируйте API Token — это ключ отправки сообщений. Не публикуйте его.

Шаг 3. Добавьте бота в чат с клиентом и выдайте ему админ-права (иначе он может не смочь отправлять PDF в группу).

Шаг 4. Скопируйте chat_id этого чата и передайте ИИ — сюда бот будет слать отчёты по конкретному клиенту. В некоторых клиентах Telegram ID виден как Peer ID. С других устройств (среди Windows и Android) добавьте в чат @Getmyid_bot и возьмите Current chat ID.

---

10. Промпт: собери пайплайн отчётности

Скопируйте весь блок в новый чат агента. Агент не начинает кодить, пока не получит ответы на бриф (ниша, сайт, токен Директа, цели Метрики, Telegram, chat_id). Можно скачать .md

# Промпт: собери агентный пайплайн еженедельной отчётности Яндекс Директа

Скопируй всё ниже в новый чат агента. Агент **не начинает кодить**, пока не получит ответы на бриф.

---

Ты — старший инженер и директор агентной системы. Твоя задача: с нуля собрать **полноценный автоматический пайплайн еженедельной отчётности по Яндекс Директу**.

Результат прогона: PDF «Standard+» за прошлую календарную неделю (пн–вс) + отправка этого PDF в Telegram-чат клиента. Директор в чате только запускает одну команду и **сам не считает цифры, не пишет текст и не рисует PDF руками**.

Язык системы, файлов, PDF, skills и комментариев — **русский**. Собирай систему с нуля по этому промпту, без опоры на чужой репозиторий.

---

## 0. Жёсткий стоп: сначала бриф, потом система

**Запрещено** создавать папки, писать код, ставить зависимости, ходить в API, придумывать цели, нишу, сайт или токены — пока человек не ответил на все пункты ниже.

Если чего-то нет — задай вопросы списком и **жди**. Не подставляй «заглушки вместо токена». Не угадывай GoalId. Не бери chat_id из головы.

Спроси ровно это (нумерация фиксированная):

1. **Ниша** — чем занимается клиент, какой оффер, какая география, сезонность.
2. **Сайт клиента** — основной домен и посадочные, куда ведёт реклама. Нужен, чтобы потом опознать цель «страница спасибо» (URL вроде `/thanks`, `/thank-you`, «благодар»).
3. **API-токен Яндекс Директа** — OAuth access_token представителя кабинета (не `client_credentials` приложения). Плюс логин кабинета (`Client-Login`) и тип: прямой рекламодатель (`Type: CLIENT`) или агентство.
4. **Цели Яндекс Метрики, на которые оптимизируются рекламные кампании.** Нужны: id цели, название, что считается заявкой (обычно страница спасибо / бронь), отдельно телефон, мессенджер, автоцели. Если человек даёт только названия — агент после допуска в API сверяет их с каталогом Метрики и со `Campaigns.get` (`BiddingStrategy.GoalId`, `PriorityGoals`, `CounterIds`), но **не начинает сборку**, пока человек не назвал хотя бы главную цель-заявку.
5. **Токен Telegram-бота**, который будет слать PDF клиенту (`TELEGRAM_BOT_TOKEN` от BotFather).
6. **chat_id Telegram-чата с клиентом** (`TELEGRAM_CHAT_ID`). Это id чата/группы, куда уходит отчёт, не username бота.

После ответов:

- положи секреты **только** в локальный `.env` (не в skills, не в handoff, не в PDF, не в git-историю без явной просьбы человека);
- запиши нишу, сайт, логин, GoalId и роли целей в `memory/clients/roster.yaml` **без токенов**.

Пока пункты 1–6 не закрыты — ответь только уточнениями.

---

## 1. Обязательный skill для PDF — поставь и прочитай целиком

Любая работа с PDF в этой системе идёт **только** через официальный skill Anthropic `pdf`. Не рисуй PDF «из головы» и не подключай случайный HTML-to-PDF, пока не прочитаешь skill.

Ссылки (поставь skill, затем открой `SKILL.md` и справочники):

- Каталог: https://skills.sh/anthropics/skills/pdf
- Репозиторий skill: https://github.com/anthropics/skills/tree/main/skills/pdf
- Файл инструкций: https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md
- Корневой репозиторий skills: https://github.com/anthropics/skills

Установка:

```bash
npx skills add https://github.com/anthropics/skills --skill pdf
```

После установки **прочитай целиком**:

- `SKILL.md` — когда какой инструмент (reportlab / pypdf / pdfplumber);
- разделы про **создание PDF через reportlab** (canvas + Platypus);
- запрет Unicode-подстрочных символов в reportlab (рисуются чёрными квадратами) — для сумм это не нужно, но правило skill соблюдать;
- как проверять готовый PDF: извлечь текст/таблицы (`pdfplumber` / `pdftotext -layout`) и **открыть сам файл глазами**, не верить только логу «PDF записан».

Для еженедельного отчёта генератор — **reportlab + canvas**, формат A4. Не WeasyPrint, не fpdf, не «скриншот HTML».

---

## 2. Обязательно изучи всю документацию API Яндекс Директа до кода

**Не пиши collector, пока не прочитаешь документацию.** Поверхностного «я знаю Директ» недостаточно. Агент обязан открыть первоисточник, пройти индекс и выписать рабочие эндпоинты, заголовки, лимиты, коды ответов Reports и нюансы денег.

### Главные входы

- Портал API: https://yandex.ru/dev/direct
- **Полный индекс для агентов (читать целиком, затем раскрывать каждую нужную страницу):** https://yandex.ru/dev/direct/doc/ru/llms.txt
- Регистрация приложения и доступ: https://yandex.ru/dev/direct/doc/ru/concepts/register
- Заголовки запросов: https://yandex.ru/dev/direct/doc/ru/headers
- Типы кабинетов (`CLIENT` / агентство): https://yandex.ru/dev/direct/doc/ru/type
- Практика агентства: https://yandex.ru/dev/direct/doc/ru/best-practice/agency

От `llms.txt` обязательно дойти до разделов:

- JSON API v5 / актуальная версия **v501**: сервисы, формат запроса/ответа, объекты `result` / `error`;
- **Reports** — типы отчётов, поля, `DateRangeType`, `Goals`, `AttributionModels`, TSV, poll `200/201/202`, лимиты очереди;
- **Campaigns.get** — стратегия, `GoalId`, `PriorityGoals`, `CounterIds`, State/Status;
- **Changes.checkCampaigns** / `Changes.check` — что API реально отдаёт (флаги SELF/CHILDREN/STAT), а чего в нём **нет**;
- **Ads.get**, **Keywords.get** — для снимка, не для фантазий про минусацию;
- лимиты баллов / units, песочница;
- ошибка **`58`**: заявка на API не одобрена — live-запросы запрещены, только фикстура.

Баланс в v5 **отсутствует**. Для карточки «Остаток» читай Live v4:

- `https://api.direct.yandex.ru/live/v4/json/`
- метод `AccountManagement`, `Action: Get`, поле `Amount` уже в валюте кабинета, не в микросах.

Цели Метрики (каталог названий и URL-условий):

- Management API: `https://api-metrika.yandex.net/management/v1/counter/{id}/goals`
- Документация Метрики: https://yandex.ru/dev/metrika/ru/management/openapi/goal

Изучив документы, **запиши контракт** в `shared/direct-api.md` своими словами: таблица «зачем → URL → поля», заголовки, poll Reports, лимиты, период недели, какие отчёты качаем. Код писать только после этого файла.

### Боевые URL (не песочница, если человек дал боевой токен)

| Зачем | URL |
|---|---|
| Reports | `https://api.direct.yandex.com/json/v501/reports` |
| Остальные сервисы v5 | `https://api.direct.yandex.com/json/v501/{service}` |
| Песочница | `https://api-sandbox.direct.yandex.com/json/v5/...` (у Reports в sandbox — одна кампания на запрос) |
| Баланс | Live v4 `AccountManagement` |

### Заголовки

```text
Authorization: Bearer <токен>
Accept-Language: ru
```

Если это **агентство** — на каждый кабинет кроме `AgencyClients.get` обязателен заголовок `Client-Login: <логин_главного_представителя_клиента>` и `Use-Operator-Units: true`. Логин в roster = главный представитель, не любой делегат.

Если это **прямой рекламодатель** (`Type: CLIENT`, один кабинет) — `AgencyClients.get` не вызывать. Логин кабинета всё равно хранить: он нужен для баланса Live v4 (`Logins: [...]`).

Токен — OAuth пользователя/представителя. Получение: `https://oauth.yandex.ru/authorize?response_type=token&client_id=<ID_приложения>`. Для каталога целей удобно, чтобы у того же OAuth было право `metrika:read`. Отдельный `YANDEX_METRIKA_TOKEN` — запасной, не обязательный, если счётчик привязан к кампаниям.

---

## 3. Контракт цифр — без этого PDF врёт

Заучить и проверить тестом. Это баги, которые уже ловили в бою.

### Деньги

- Reports: `IncludeVAT: YES`, `IncludeDiscount: NO`, `returnMoneyInMicros: false`.
- Если забыть `returnMoneyInMicros: false` — все суммы × 1 000 000.
- Формат отчёта: `Format: TSV`, `skipReportHeader: true`, `skipReportSummary: true`, `processingMode: auto`.
- `ReportName` уникален в кабинете: `weekly-{client}-{period}-{unix}`.
- В PDF: разделитель тысяч — пробел, копейки через запятую, символ `₽`. Не «руб.», не `RUB`.

### Период

- Еженедельный отчёт = **прошлая календарная неделя пн–вс**.
- В Reports: `DateRangeType: LAST_WEEK`.
- WoW: второй запрос `CUSTOM_DATE` на неделю −2 (`DateFrom` / `DateTo` только при `CUSTOM_DATE`).
- Статистика Директа может доезжать до 3 суток. Для `LAST_WEEK` в понедельник неделя уже закрыта.
- Поисковые запросы (`Query`) — только за последние 180 дней.
- Имя файла и заголовок PDF берут даты **недели отчёта**, не дату прогона.

### Poll Reports

| HTTP | Смысл |
|---|---|
| 200 | TSV в теле |
| 201 | в очереди, ждать `retryIn` |
| 202 | ещё считается, повторить тот же запрос |
| 400 | параметры или лимит очереди |
| 500 | один повтор, потом стоп |

Лимиты: не больше **20** запросов Reports за 10 секунд на пользователя; в очереди не больше **5** офлайн-отчётов; готовый отчёт живёт **5 часов**. `SEARCH_QUERY_PERFORMANCE_REPORT` всегда офлайн. **Кабинеты не параллелить.**

### Какие отчёты качать

| Файл | ReportType | Зачем |
|---|---|---|
| `account.tsv` | `ACCOUNT_PERFORMANCE_REPORT` | показы, клики, CTR, расход, CPC, отказы, глубина, конверсии |
| `network.tsv` | `CUSTOM_REPORT` + `AdNetworkType` | Поиск vs РСЯ (`SEARCH` / `AD_NETWORK`) |
| `campaigns.tsv` | `CAMPAIGN_PERFORMANCE_REPORT` | расход и конверсии по РК |
| `queries.tsv` | `SEARCH_QUERY_PERFORMANCE_REPORT` | запросы, опционально |

`BounceRate` и `AvgPageviews` уже приходят **из Reports**, если у кампании указан `CounterIds`. Отдельный токен Метрики для таблицы Standard+ не обязателен.

Roistat / h-lead / Битрикс в эти TSV **не приедут**. Не пиши «звонки Roistat», если `conversion_source` не `roistat`.

---

## 4. Цели: главная ловушка всего пайплайна

Поле `Conversions` в кабинете и в `ACCOUNT_PERFORMANCE_REPORT` без параметра `Goals` — это **сумма всех целей** (микроконверсии, автоцели, вовлечённость). На живых кабинетах это часто тысячи «конверсий» при сотне реальных заявок.

**В шапку и в строку «заявки» эта сумма запрещена.**

Правильный контур:

1. `Campaigns.get` → `CounterIds`, `PriorityGoals`, `BiddingStrategy.GoalId`.
2. Каталог целей Метрики по счётчику.
3. Классификация по имени / type / URL:
   - **thanks** — страница спасибо / бронь / `thanks` / «благодар» — **это заявки**;
   - **phone** — клик по телефону (`type=phone` или «телефон» в названии);
   - **messenger** — переход в мессенджер;
   - **autogoal** — автоцель «отправил контактные данные» и подобный шум.
4. В Reports передавать `Goals: [id, …]` (до 10) и `AttributionModels: ["AUTO"]`. Тогда приходят колонки `Conversions_<id>_AUTO` и `CostPerConversion_<id>_AUTO`.
5. GoalId **12** = вовлечённые сессии, **13** = все ключевые цели. Это **не** цели Метрики и **не** заявки. В параметр `Goals` их не класть. Если стратегия стоит на 12/13 — брать первую цель из `PriorityGoals`.
6. Автоцель «отправил контактные данные» **не** ставить третьей карточкой в шапке вместо мессенджера/телефона.
7. CPL шапки и таблицы = `расход / заявки_thanks`, не расход / сумма всех конверсий.

Человек в брифе назвал цели — сверь их с API. Если оптимизация кампаний стоит на другой цели, чем «спасибо», это факт для аудитора, но **клиентская «заявка» в PDF всё равно страница спасибо**, пока человек явно не скажет иначе.

---

## 5. Changelog: не выдумывать минусацию

`Changes.checkCampaigns` возвращает только флаги `SELF` / `CHILDREN` / `STAT` (и иногда stat-границу). Это **не** история изменений из веб-интерфейса Директа. Минус-фразы, правки объявлений и смены ставок из этого метода **недостаются**.

Поэтому:

- снимок недели: `Campaigns.get` + при необходимости `Ads.get` / `Keywords.get` (State, Name, стратегия, дневной бюджет);
- diff с прошлым снимком → только проверяемые факты (кампания ON→OFF, переименовали, сменился GoalId);
- **минусацию не писать**, если в снимке нет исчезнувших/добавленных минус-фраз;
- `STAT` — это корректировка статистики Яндексом, не «мы поменяли РК»;
- UI «История изменений» в API нет — не обещать её в отчёте.

---

## 6. Архитектура пайплайна

Директор **не** считает, **не** пишет `copy.json`, **не** рисует PDF, **не** шлёт Telegram руками. Одна команда:

```bash
python3 scripts/run_pipeline.py
```

Без повторного похода в Директ (уже есть `raw/`):

```bash
python3 scripts/run_pipeline.py --skip-collect
```

Цепочка ролей. Каждая роль — скрипт + skill + короткий `.cursor/agents/<role>.md`. Вложенных Task нет. QA FAIL → стоп, PDF не собирать.

```text
① intake.py          → intake.json          (не ходить в API)
② collect_reports.py → raw/*.tsv, snapshot  (не писать комментарий клиенту)
③ changelog.py       → changelog.json       (не выдумывать минусацию)
④ normalize.py       → metrics.json         (не менять смысл цифр)
⑤ analyst.py         → analysis.json        (не писать текст клиенту)
⑥ auditor.py         → audit.json           (не править кабинет)
⑦ writer.py          → copy.json            (новые цифры не из входа — запрещены)
⑧ qa.py              → qa.json PASS|FAIL    (текст сам не чинит)
⑨ render_pdf.py      → PDF                  (не отправляет)
⑩ dispatcher.py      → Telegram             (нет бота/chat_id → skip, не падать)
⑪ ledger.py          → memory/ledger.jsonl
```

Перед прогоном — `scripts/doctor.py`: reportlab, шрифт с кириллицей и `₽`, roster, токен (WARN если пуст, не падать — фикстура должна жить).

Секреты: `.env` локально. В skills и handoff токенов нет.

---

## 7. Макет PDF Standard+ — визуал, который уже согласован с заказчиком

Формат A4, 1–2 страницы. Без отдельных графиков и «истории бренда» на каждого клиента. Не одно сплошное полотно текста.

Палитра:

- шапка / шапка таблиц: `#1B3A5F`
- заголовки блоков: `#2C5282`
- фон карточек и зебры: `#F4F7FB`
- линии: `#D0D7E2`
- рост «хорошо»: `#1B7F3A`
- рост «плохо»: `#C53030` (для CPC, CPL, отказов рост — красный)
- приглушённый текст: `#5A6A7A`

### Шрифт — отдельный баг, который уже ловили

Arial / Arial Bold **не содержат глиф рубля U+20BD**. В PDF вместо `₽` рисуются **пустые квадраты**.

На macOS брать **PT Sans** из `/System/Library/Fonts/Supplemental/PTSans.ttc`:

- Regular — индекс `0`
- Bold — индекс `7`

`TTFont(..., subfontIndex=...)`. На Linux/Windows — положить PT Sans `.ttf` в репозиторий (`assets/fonts/`) и зарегистрировать их. Перед сдачей обязательно открыть PDF и проверить, что `₽` и кириллица живые.

Не использовать Unicode-подстрочные индексы в reportlab (правило pdf-skill: чёрные квадраты).

### Страница 1, сверху вниз

1. Синяя шапка: «Недельный отчет по работе Директа (ДД.ММ.ГГ - ДД.ММ.ГГ)» и **имя клиента** второй строкой.
2. Строку **«Ориентир оптимизации»** под именем **не писать**.
3. Карточки в одном ряду: **Потрачено**, **Остаток**, затем три цели — **страница спасибо / телефон / мессенджер**. Не агрегат всех конверсий. Не автоцель «отправил контакт» в шапке.
4. Таблица WoW «Общая статистика по аккаунту за прошедшую неделю»: показы, клики, кликабельность, ср. цена клика, отказы %, ср. глубина, **заявки (спасибо)**, **CPL (спасибо)**. Колонки: метрика / прошлая неделя / текущая / % к пр. неделе.
5. Дельта: зелёный рост для заявок/кликов/показов; красный рост для CPC / CPL / отказов.
6. Нет данных Поиск/РСЯ — писать **«нет данных»**, не ноль.
7. Таблица **«Расход по рекламным кампаниям»** — **до** блока «Работа с рекламной». Группы **Поиск** и **РСЯ**. Строка = `CampaignId` + название. Колонки **только**: расход, заявки (спасибо), стоимость заявки. **Без** показов, кликов, CTR, CPC.
8. «Работа с рекламной» — только короткие буллеты (`copy.facts`). Без подписи «Факты за неделю». Без блока «Почему сдвинулись цифры». `copy.why` всегда `[]`. QA **FAIL**, если `why` не пустой.
9. Один буллет = одна мысль (кампания / стратегия / действие из changelog). Не пересказывать таблицу кампаний абзацем.
10. «Нужно от клиента» — только если есть реальная просьба.
11. Баланс **только в шапке**, внизу страницы не дублировать.
12. Воду «традиционно провожу анализ директа и метрики» — запретить в QA.

### Страница 2

Только таблица целей WoW: спасибо, телефон, мессенджер, автоцель (CPL по каждой). **Не дублировать** таблицу кампаний второй раз.

### Имя файла

Не `report.pdf`. Русские слова через нижнее подчёркивание + две даты недели `ДД.ММ.ГГ`:

```text
Отчет_по_кабинету_Яндекс_Директ_01.01.26_07.01.26.pdf
```

Шаблон: `Отчет_по_кабинету_Яндекс_Директ_{from}_{to}.pdf`. Даты из `metrics.period_from` / `period_to`.

---

## 8. Telegram

`dispatcher` шлёт **документ**, не картинку. Caption: `Недельный отчёт Директа · {Имя клиента}`.

Если нет `TELEGRAM_BOT_TOKEN` или `TELEGRAM_CHAT_ID` — **skip**, пайплайн не падает, PDF остаётся в `runs/<сегодня>/<client-id>/`.

Кириллическое имя файла в multipart иначе превращается обратно в `report.pdf`. Обязательно:

- `filename="{русское_имя.pdf}"`
- и `filename*=UTF-8''` + URL-encode имени (RFC 2231).

Не логировать токен бота. Не класть токен в `dispatch.json`.

---

## 9. Writer и QA

`copy.json`:

```json
{ "facts": ["пункт", "пункт"], "why": [], "need_from_client": [] }
```

QA **FAIL** если:

- цифра в тексте отсутствует в `metrics.json` / `analysis.json`;
- слово «минусация» без факта в changelog;
- вода «традиционно» / «анализ директа и метрики»;
- агрегат всех целей выдан за заявки;
- «звонки Roistat» при чужом источнике;
- период или имя клиента не те;
- CPL не сходится с `расход / thanks` (±1 ₽);
- в «работе с рекламной» нет пунктов;
- `why` не пустой.

QA текст сам не чинит — возвращает `qa.json` с `errors`. Директор после FAIL не пакует PDF.

---

## 10. Что собрать в репозитории

```text
.env / .env.example
AGENTS.md
scripts/          intake, collect_reports, changelog, normalize, analyst,
                  auditor, writer, qa, render_pdf, dispatcher, ledger,
                  run_pipeline, doctor, direct_client, metrika_client, goals
skills/<role>-direct-report/SKILL.md
.cursor/agents/<role>.md
.cursor/rules/    оркестратор: директор не считает и не рисует PDF
shared/direct-api.md
shared/report-template.md
shared/pipeline-task-map.md
memory/clients/roster.yaml
memory/ledger.jsonl
runs/             в .gitignore
fixtures/         хотя бы один прогон без live API
```

Директор запускает только `python3 scripts/run_pipeline.py`. После первого живого прогона сверь PDF с кабинетом Директа глазами: расход, остаток, заявки-спасибо, CPL, Поиск/РСЯ.

---

## 11. Порядок работы агента (не нарушать)

1. Задать вопросы 1–6 и **остановиться**.
2. Когда ответы есть — поставить и прочитать skill PDF по ссылкам из раздела 1.
3. Открыть https://yandex.ru/dev/direct и **целиком** https://yandex.ru/dev/direct/doc/ru/llms.txt, затем страницы Reports, Campaigns, Changes, headers, type, Live v4, Метрика goals. Законспектировать в `shared/direct-api.md`.
4. Собрать каркас, контракты, скрипты, skills.
5. Нарисовать PDF по макету раздела 7, имя файла — раздел 7.
6. Прогнать `doctor` + фикстуру без live.
7. Живой прогон по токену из брифа. Сверить цифры с кабинетом.
8. Отправить PDF в указанный chat_id. Показать человеку путь к файлу и подтверждение Telegram.

Если на шаге 3 документация противоречит памяти модели — **побеждает документация Яндекса**, не память.

После того как локально отчёт собирается, выгрузите код в закрытый GitHub и поставьте расписание — следующий раздел.

---

11. GitHub, облако и крон

Подойдёт любое облако или свой сервер. В эфире разбирали Cursor Automations — они входят в подписку. Тот же цикл работает в других агентных системах: закрытый репозиторий + расписание.

1. Подключите GitHub в Cursor: cursor.com/dashboard/integrations → Settings → Integrations → GitHub.

Выгрузите весь проект в закрытый репозиторий GitHub (бесплатный аккаунт можно зарегистрировать через Google). Промпт агенту:

Выгрузи мне весь проект в закрытый репозиторий GitHub. Токены и секреты не коммить.

Затем откройте Cloud Agents и выберите репозиторий, который собрал агент.

Расписание: cursor.com/automations → New Automation. Пример: каждый понедельник в 09:00, промпт «собери еженедельный отчёт и отправь в Telegram».

---

12. Чек-лист

• OAuth-приложение: тип «для API», скоупы direct:api и metrika:read.
• Заявка в Директе в статусе «одобрена», токен получен.
• Telegram-бот в чате клиента с админ-правами, chat_id известен.
• Первый тестовый PDF ушёл в чат вручную, без крона.
• Снимки состояния кампаний сохраняются между запусками.
• Репозиторий закрытый, токены только в секретах окружения.
• Крон стоит на нужный день/час (пример: пн 09:00 Москва).

---

13. Частые вопросы

Можно ли без Cursor? Да. Промпт и схема те же: API → PDF → Telegram. Вместо Automations — cron на VPS, GitHub Actions или другой планировщик.

Почему в отчёте нет отказов? В приложении нет скоупа metrika:read. Добавьте его и выпишите токен заново. См. OAuth Метрики и Reports API Метрики.

ИИ пишет «добавили минусы», хотя не добавляли. Нет прошлого снимка. Пока снимков мало — в отчёте только цифры, без выдуманных действий.

Где документация API? Каталог API Директа, отчёты Директа, каталог Метрики, API Метрики.

---

14. Курс «Монстры Маркетинга»

33-й поток курса по Яндекс Директу — для тех, кто хочет расти в доходе, чеках и клиентах. 20 000+ часов практики, 3 000+ выпускников, новая программа 2026.

В новом потоке:

• уроки про ИИ в работе директолога;
• часть уроков — пошаговые инструкции со скриншотами;
• блок с ответами на частые вопросы;
• новые уроки по аналитике РК;
• прямые эфиры с разбором реальных РК;
• обратная связь по ДЗ по существу.

Бонусы: для всех тарифов — курс «Директ с нуля» (2026); к тарифам «Мастер» и «Эксперт» — интенсив «Рабочие стратегии Директа 2026».

Ранний доступ к 33-му потоку: оставьте заявку на консультацию (и фиксируйте цену). На ММ чем ближе к старту, тем дороже.

Сайт: web.monster-marketing.ru. Вопросы — менеджеру Анне @Aleskerova_Anetta. Звонки с номера +79968153913.

---

Материал по эфиру Романа Скороходова и Константина Горбунова. Контакты Романа: @vjobindirect, vk.com/dada__etoya.