# yandex-metrika-assistant

Adopt this skill: https://proskills.md/skills/other/russkih75-ctrl-yandex-metrika-assistant

Page: https://proskills.md/skills/other/russkih75-ctrl-yandex-metrika-assistant
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 11411
upstream: https://github.com/russkih75-ctrl/yandex-metrika-assistant/blob/HEAD/SKILL.md

````text
---
name: yandex-metrika-assistant
description: "OpenClaw + Яндекс.Метрика API — stat/Logs/management, OAuth, presets, UTM, цели, CSV, квоты; плагин yandex-metrika-assistant. Автор: Андрей Русских (wordprais.ru)."
homepage: "https://github.com/russkih75-ctrl/yandex-metrika-assistant"
---

# Яндекс.Метрика API — заточка под **OpenClaw**

**Автор навыка:** **Андрей Русских** — сайт **[wordprais.ru](https://wordprais.ru)** (WordPress), Telegram [@wordprais](https://t.me/wordprais), [Instagram](https://www.instagram.com/wordprais/).

Плагин: **`yandex-metrika-assistant`** (`openclaw.plugin.json` в этой папке).  
Цель: ноль сюрпризов — сначала **конфиг и секреты**, потом **правильный endpoint**, без выдуманных метрик и без утечки токена.

---

## Онбординг человека (порядок ответов агента)

**Если токена ещё нет** (пользователь только ставит навык или не настроил ключ):

1. **Сначала** дай ссылку и краткое резюме установки: **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`** (шаги OpenClaw + OAuth + куда вставить ключ).
2. **Обязательно** перечисли, какие **галочки в приложении Яндекс OAuth** нужны для Метрики (таблица из того же файла / шаг 2): статистика и чтение, создание/изменение счётчиков, при необходимости расходы, параметры пользователей, офлайн-данные.
3. Укажи **каналы поддержки автора (Андрей Русских):** [Telegram @wordprais](https://t.me/wordprais), [Instagram](https://www.instagram.com/wordprais/), сайт [wordprais.ru](https://wordprais.ru) — вопросы по установке и сценариям; **не** проси кидать токен в мессенджеры публично.
4. Затем — получение токена: **`{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`** (или ссылка `authorize` с `oauthClientId` из конфига).
5. Напомни: ключ хранить в **`oauthToken`** плагина или в **`YANDEX_METRIKA_OAUTH_TOKEN`**, не в чате.

**После того как ключ добавлен** (пользователь сообщил, что сохранил токен в конфиг, или токен уже есть в конфиге/окружении):

- Не проси продиктовать токен.
- Заверши ответ блоком **«С чего начать»** — предложи **3–5 коротких вариантов** (нумерованный список), например:
  1. Показать список счётчиков Метрики.  
  2. Визиты по дням за последние 7 дней.  
  3. Сводка по источникам трафика.  
  4. Топ страниц по просмотрам.  
  5. Конверсии по цели (если есть цели).  

Полный список идей — **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`** (раздел «После добавления ключа») и **`{baseDir}/docs/10-user-intents-matrix.md`**.

---

**Типовые формулировки пользователей** («откуда трафик», «цели», «UTM», «география», «сравни периоды», «выгрузи CSV», «сырые логи») — смотри матрицу: **`{baseDir}/docs/10-user-intents-matrix.md`** (разбивка по разделам A–J + ссылки на официальные примеры и пресеты).

---

## OpenCLaw: порядок работы (строго)

1. **Токен** брать только из:
   - настроек плагина **`oauthToken`** (см. `configSchema` в `openclaw.plugin.json`), **или**
   - переменной окружения **`YANDEX_METRIKA_OAUTH_TOKEN`** (если хост OpenClaw так настроен), **или**
   - пользователь явно передал токен **один раз** для текущей сессии — тогда использовать, но **не** повторять токен обратно в ответе и **не** вставлять в файлы репозитория.
2. Если токена **нет** — **не** вызывать API и **не** придумывать ответ Метрики. Следуй разделу **«Онбординг человека»** выше: сначала **`{baseDir}/docs/INSTALL-FOR-HUMANS-RU.md`**, галочки OAuth, контакты автора **Андрея Русских** ([Telegram @wordprais](https://t.me/wordprais), [Instagram](https://www.instagram.com/wordprais/), [wordprais.ru](https://wordprais.ru)), затем **`{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`**; при наличии **`oauthClientId`** — ссылка `authorize?response_type=token&client_id=...`.
3. **`defaultCounterId`** из конфига: если пользователь не назвал счётчик — используй это значение и **одной строкой** напиши: «использую счётчик по умолчанию из конфига OpenClaw».
4. Любые `curl`/команды в чат — только с плейсхолдером **`$env:YANDEX_METRIKA_OAUTH_TOKEN`** или «подставь токен из секрета OpenClaw», **не** вставляй токен целиком.
5. **Windows / PowerShell:** если `curl -H "Authorization: OAuth …"` даёт ошибки из‑за кавычек — используй `Invoke-RestMethod` с `-Headers @{ Authorization = 'OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN }` или заголовок через **конкатенацию** в скобках: `-H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)`. Подробно: **`{baseDir}/docs/OPENCLAW-AGENT.md`**, **`{baseDir}/docs/EXAMPLES.md`**.

---

## Быстрые рецепты (копипаста для пользователя, Windows PowerShell)

Подстановка токена из env (удобно рядом с OpenClaw):

```powershell
$env:YANDEX_METRIKA_OAUTH_TOKEN = "<секрет, не коммитить>"
$cid = "<COUNTER_ID>"
# Надёжнее без вложенных кавычек вокруг токена:
curl.exe -s -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN) `
  "https://api-metrika.yandex.net/management/v1/counters?per_page=20"
```

Отчёт «визиты за последние 7 дней» (проверь `ids` и метрики по задаче):

```powershell
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "metrics=ym:s:visits" `
  --data-urlencode "date1=7daysAgo" `
  --data-urlencode "date2=yesterday" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)
```

---

## Сценарий: «пришли ежедневную статистику по моему сайту wordprais.ru (WordPress)»

Так OpenClaw **должен** отработать запрос (и что увидит человек в ответе).

### Внутренние шаги агента

1. **Токен** — из `oauthToken` / `YANDEX_METRIKA_OAUTH_TOKEN`. Нет токена → стоп, ссылка на `{baseDir}/docs/INSTRUCTION-GET-TOKEN-RU.md`.
2. **Счётчик** — если в конфиге есть **`defaultCounterId`** и пользователь не просил другой сайт, можно спросить: «использовать счётчик по умолчанию?» или сразу использовать, если контекст однозначен.
3. Иначе: **`GET /management/v1/counters`** с **`search_string=wordprais`** (или другой фрагмент домена **моего сайта**). Если **несколько** счётчиков — перечислить `id`, `name`, `site` и **попросить выбрать** один `id`.
4. **Период** — если не сказан, предложить по умолчанию, например **вчера − 29 дней … вчера** (без «сегодня» для стабильности данных) или уточнить у пользователя.
5. **Ежедневная разбивка** — API отчётов:
   - вариант А: `GET .../stat/v1/data` с группировкой по дню визита **`dimensions=ym:s:date`**, **`metrics`** по задаче (часто `ym:s:visits`, при необходимости `ym:s:pageviews`, `ym:s:users` — имена проверять в [справочнике](https://yandex.ru/dev/metrika/ru/stat/));
   - вариант Б: `GET .../stat/v1/data/bytime` — если удобнее именно «по времени» (см. openapi в доке stat).
6. Вызвать API (или дать пользователю **одну** готовую команду с плейсхолдерами), распарсить JSON.
7. Если в ответе JSON поле `contains_sensitive_data` равно `true` — кратко предупредить про ограничение раскрытия данных.

### Как выглядит ответ человеку (шаблон)

Агент пишет **короткое резюме**, затем **таблицу или список по дням** (дата → визиты / просмотры / и т.д.), без сырого JSON на экран целиком, если пользователь не просил сырой вывод.

Пример формулировки:

- «Счётчик: **…** (`id` …), сайт **wordprais.ru** (WordPress), период **…**. Ниже визиты по дням. Данные из API Метрики, токен из конфига OpenClaw.»
- Далее строки вида: `2025-03-01 — визиты: 120`, …
- Примечание при 429: «Сработала квота отчётов; повтори через несколько минут» (`{baseDir}/docs/04-quotas.md`).

### Пример цепочки запросов (PowerShell, без секрета в логах чата)

```powershell
# 1) Найти счётчик по подстроке (пример: wordprais — домен моего сайта)
curl.exe -s -G "https://api-metrika.yandex.net/management/v1/counters" `
  --data-urlencode "search_string=wordprais" `
  --data-urlencode "per_page=50" `
  -H ('Authorization: OAuth ' + $env:YANDEX_METRIKA_OAUTH_TOKEN)

# 2) Ежедневные визиты (подставь $cid из шага 1)
curl.exe -s -G "https://api-metrika.yandex.net/stat/v1/data" `
  --data-urlencode "ids=$cid" `
  --data-urlencode "dimensions=ym:s:date" `
  --data-urlencode "metrics=ym:s:visits" `
  --data-urlencode "date1=30daysAgo" `
  --data-urlencode "date2=yesterday" `
  --data-ur
````

## File: README.md
upstream: https://github.com/russkih75-ctrl/yandex-metrika-assistant/blob/HEAD/README.md

````text
<div align="center">

[![Yandex Metrika × OpenClaw Skill — обложка репозитория](./OpenClaw-Yandex-Metrika.png)](./OpenClaw-Yandex-Metrika.png)

# Yandex Metrika Assistant

**Навык OpenClaw + документация для API Яндекс.Метрики**

**Автор:** [Андрей Русских](https://wordprais.ru) — WordPress, SEO/GEO · [wordprais.ru](https://wordprais.ru) · [@wordprais](https://t.me/wordprais) · [Instagram](https://www.instagram.com/wordprais/)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![API Docs](https://img.shields.io/badge/API-Яндекс.Метрика-red)](https://yandex.ru/dev/metrika)
[![Telegram](https://img.shields.io/badge/Telegram-@wordprais-26A5E4?logo=telegram)](https://t.me/wordprais)
[![Instagram](https://img.shields.io/badge/Instagram-@wordprais-E4405F?logo=instagram)](https://www.instagram.com/wordprais/)

*Отчёты · Logs · Счётчики и цели · OAuth · Сценарии для нейросети*

</div>

---

## Установка для человека — начните здесь

Полная пошаговая инструкция (OpenClaw → приложение OAuth → галочки Метрике → токен → **что спросить агенту после ключа**):

### [docs/INSTALL-FOR-HUMANS-RU.md](./docs/INSTALL-FOR-HUMANS-RU.md)

**Поддержка:** [Telegram @wordprais](https://t.me/wordprais) · [Instagram @wordprais](https://www.instagram.com/wordprais/) — вопросы по установке, OpenClaw, автоматизации и нейросетям.

---

## Содержание

- [Установка для человека](#установка-для-человека--начните-здесь)
- [Зачем этот репозиторий](#зачем-этот-репозиторий)
- [Кому подойдёт](#кому-подойдёт)
- [Что умеет навык](#что-умеет-навык)
- [Соответствие OpenClaw](#соответствие-openclaw)
- [Быстрый старт](#быстрый-старт)
- [Примеры применения](#примеры-применения)
- [Примеры HTTP и PowerShell](#примеры-http-и-powershell)
- [Структура проекта](#структура-проекта)
- [Конфигурация плагина](#конфигурация-плагина)
- [Безопасность](#безопасность)
- [Ссылки](#ссылки)

---

## Зачем этот репозиторий

Репозиторий объединяет:

| Компонент | Назначение |
|-----------|------------|
| **[`SKILL.md`](./SKILL.md)** | Как **нейросети** (OpenClaw) выбирать endpoint, не путать `ym:s:` / `ym:pv:`, работать с секретами и квотами |
| **`docs/`** | Сжатая справка по **официальному** API: OAuth, квоты, stat, logs, импорт, management |
| **`openclaw.plugin.json`** | Контракт плагина: токен и опции в одном месте |

Официальный источник правды по API: [**yandex.ru/dev/metrika**](https://yandex.ru/dev/metrika).

---

## Кому подойдёт

- Владельцам сайтов и маркетологам, которые хотят **спрашивать Метрику у AI** в осмысленной форме.
- Разработчикам **автоматизации** (Make.com, сценарии, cron) — готовые паттерны запросов.
- Интеграторам **OpenClaw** / агентов с доступом к shell и секретам.

---

## Что умеет навык

<details>
<summary><strong>Отчёты (Reporting API)</strong></summary>

- Таблицы `GET /stat/v1/data`, динамика `bytime`, сравнение сегментов, drilldown.
- Пресеты (`preset=`) как в веб-интерфейсе Метрики.
- Сегментация через `filters`, лимиты метрик/группировок из доки.

</details>

<details>
<summary><strong>Управление и Logs</strong></summary>

- Список счётчиков, цели, типовые `management`-операции.
- Сценарий Logs API: создание выгрузки → статус → скачивание → `clean`.

</details>

<details>
<summary><strong>Импорт и токены</strong></summary>

- Направления импорта (расходы, CRM, офлайн и т.д.) со ссылками на методы.
- Инструкция получения OAuth-токена на русском + скрипт обмена `code` → token.

</details>

Матрица «**как спросили человеком → какой API**»: [`docs/10-user-intents-matrix.md`](./docs/10-user-intents-matrix.md).

---

## Соответствие OpenClaw

Проверено по официальным разделам [**Skills**](https://docs.openclaw.ai/tools/skills#skills) и [**Plugin manifest**](https://docs.openclaw.ai/plugins/manifest):

| Требование документации | Как сделано в репозитории |
|-------------------------|---------------------------|
| Навык = каталог с **`SKILL.md`** и YAML frontmatter | Корень репозитория (или `skills/yandex-metrika-assistant/` в workspace) |
| Frontmatter: **`name`**, **`description`**; парсер — однострочные значения | `description` — **одна строка**; без многострочного `>-` |
| Пути к файлам навыка | В тексте `SKILL.md` используется **`{baseDir}/docs/...`** и **`{baseDir}/scripts/...`** ([как в доке](https://docs.openclaw.ai/tools/skills#skills)) |
| Плагин подгружает навыки | В [`openclaw.plugin.json`](./openclaw.plugin.json) указано **`"skills": ["."]`** (корень плагина = корень навыка) |
| `configSchema` у плагина | Задан JSON Schema для `oauthToken`, `defaultCounterId`, `oauthClientId` |
| Подсказки UI для секретов | **`uiHints`** для полей конфига (`sensitive` для токена) |

**Где класть файлы** (приоритет из [доки](https://docs.openclaw.ai/tools/skills#skills)):

- Workspace агента: **`/skills/<имя>/`** — высший приоритет для своих навыков.
- Или: **`~/.openclaw/skills`** — общие навыки на машине.
- Плагин: после `openclaw plugins install ./yandex-metrika-assistant` навык подхватывается из манифеста, если плагин **включён** в `plugins.entries`.

Альтернатива: `openclaw skills install …` — установка в активный workspace `skills/` ([ClawHub / CLI](https://docs.openclaw.ai/tools/clawhub)).

---

## Быстрый старт

```mermaid
flowchart LR
  A[Клонировать репозиторий] --> B[Подключить плагин OpenClaw]
  B --> C[Задать oauthToken]
  C --> D[Подключить SKILL к агенту]
  D --> E[Спрашивать Метрику в чате]
```

1. **Клонируйте** репозиторий (или скопируйте папку в каталог навыков OpenClaw):

   ```bash
   git clone https://github.com/russkih75-ctrl/yandex-metrika-assistant.git
   ```

2. Установите плагин, например: `openclaw plugins install ./yandex-metrika-assistant` (или путь к клону), включите **`yandex-metrika-assistant`** в `plugins.entries`. В манифесте объявлено **`skills": ["."]`**, чтобы OpenClaw подгрузил этот же каталог как навык.

3. В конфиге плагина задайте **`oauthToken`**. Опционально: **`defaultCounterId`**, **`oauthClientId`**.

4. Перезапустите gateway при необходимости (`openclaw gateway restart`). Новая сессия агента подхватит навык из снимка skills.

> **Альтернатива:** переменная окружения **`YANDEX_METRIKA_OAUTH_TOKEN`** (если ваш хост OpenClaw так устроен).

Токен для людей: [`docs/INSTRUCTION-GET-TOKEN-RU.md`](./docs/INSTRUCTION-GET-TOKEN-RU.md).

---

## Примеры применения

Ниже — **не код**, а сценарии: что пишет пользователь и как должен вести себя агент с подключённым навыком.

| # | Вы спрашиваете | Что делает агент |
|---|----------------|------------------|
| 1 | *«Покажи визиты по дням за последний месяц по сайту X»* | Находит счётчик (`search_string` или `defaultCounterId`), дергает `stat/v1/data` с `dimensions=ym:s:date`, выводит таблицу по дням. |
| 2 | *«На какие страницы больше всего заходят?»* | Запрос с префиксом **`ym:pv:`**: URL + просмотры, сортировка по убыванию, топ N. |
| 3 | *«Откуда трафик, сводка по источникам»* | `preset=sources_summary` или явные dimensions по источникам из справочника. |
| 4 | *«Сравни мобильный и десктоп за неделю»* | Метод сравнения сегментов `/stat/v1/data/comparison` (см. официальные примеры). |
| 5 | *«Выгрузи отчёт в Excel»* | Подсказывает запрос к `.../stat/v1/data.csv?...` с нужными параметрами. |
| 6 | *«Нужны сырые логи визитов»* | Объясняет цикл Logs API (create → poll → download → **clean**), ссылка на `docs/06-logs-api.md`. |
| 7 | *«Как получить API-ключ?»* | Объясняет, что нужен **OAuth access_token**, даёт [`INSTRUCTION-GET-TOKEN-RU.md`](./docs/INSTRUCTION-GET-TOKEN-RU.md). |

Больше формулировок («UTM», «Директ», «цели», география…) — в [**матрице намерений**](./docs/10-user-intents-matrix.md).

---

## Примеры HTTP и PowerShell

Готовые команды `curl` и настройка `$env:` — в отдельном файле:

**[docs/EXAMPLES.md](./docs/EXAMPLES.md)** — счётчики, визиты по дням, топ URL, preset, CSV.

---

## Структура проекта

```
yandex-metrika-assistant/
├── SKILL.md                 # Поведение агента OpenClaw
├── openclaw.plugin.json     # id, name, configSchema
├── README.md        
````
