che-direct-analytics-skill

Собирает и рассчитывает данные Директа и Метрики раздельно, сверяет периоды, KPI и аномалии. Применяется для диагностики кампаний, ключей, CPA/ROAS/CTR и атрибуции; не распределяет неизвестную выручку

SKILL.md

GitHub

CHE_direct-analytics-skill — che-direct-analytics-skill

Границы и принцип работы

Навык только читает API и локальный SQLite-кэш. Он никогда не меняет кампании, ставки, бюджеты или цели. Любое предложенное действие — черновик для проверки аналитиком.

Директ и Метрика — параллельные источники. CrossSourceROAS рассчитывается только по явно сопоставленным строкам: выручка Метрики ÷ расход Директа. Подписывай оба источника, период и правило сопоставления; это межисточниковая оценка. Неатрибутированная выручка остаётся отдельной строкой и никогда не распределяется по расходу.

Настройка проекта

Проверь ~/.direct_analytics/{project}/config.json. Для нового проекта:

python scripts/setup.py --new

Помимо OAuth-токенов, зафиксируй data contract:

  • REPORT_TIMEZONE — IANA timezone отчёта;
  • UTM_SOURCE и UTM_MEDIUM — фильтр трафика Директа, обычно yandex и cpc;
  • UTM_CAMPAIGN_MAPPING — campaign_id или campaign_name;
  • ATTRIBUTION_MODE — только parallel в первой версии;
  • GUARDRAILS — проектные цели и min_abs_delta для алертов;
  • MONITOR_METRICS и COHORT_RULES — список контролируемых KPI и regex-правила внутренних когорт.

Не добавляй универсальные пороги CPA/ROAS: они должны быть заданы в конкретном проекте и иметь бизнес-смысл.

Сбор фактов

python scripts/collect.py --project NAME --date_from 2026-08-01 --date_to 2026-08-07
python scripts/collect.py --project NAME --scope keyword --scope ad --date_from D --date_to D
  • По умолчанию собирается core: campaign, device, region, placement, adnetwork.
  • keyword и ad собираются только отдельными Direct Reports и только по явному --scope.
  • Все данные сохраняются по завершённым дням. Пустой день — валидный факт; ошибка API — complete=false и будет повторно запрошена при следующем запуске.
  • --refresh инвалидирует и пересобирает весь выбранный диапазон.
  • Collector печатает contract, покрытие дат, свежесть и ошибки. Успешный выход не является доказательством production-эффекта — только успешного чтения API.

Аналитика и reconciliation

python scripts/analyze.py --project NAME --period 7d --dim campaign --compare prev_period --format json
python scripts/analyze.py --project NAME --dim keyword --date_from D --date_to D
python scripts/analyze.py --project NAME --dim campaign --anomaly

Доступные разрезы: campaign, device, region, keyword, placement, ad, day, adnetwork.

campaign и day читают reconciliation; поэтому могут показать Direct KPI, Метрика KPI и подписанные cross-source показатели. Остальные разрезы показывают только нативные Direct KPI, пока для них не настроено совместимое зерно Метрики. Если нужный scope отсутствует, analyze.py подскажет точную команду сбора.

--anomaly применяет только GUARDRAILS проекта. Он не содержит скрытых глобальных правил и не рекомендует автоматическое отключение площадок.

Диагностика и feedback

python scripts/diagnose.py --project NAME --metric MetrikaRevenue \
  --date_from 2026-08-01 --date_to 2026-08-07 --compare prev_period --format json

python scripts/diagnose.py feedback --project NAME --run-id RUN_ID \
  --verdict confirmed --actual-cause "Campaign was paused" \
  --action-outcome "No change was applied"

diagnose.py возвращает diagnosis_record:

  • data-status, coverage, timezone и правила атрибуции;
  • trigger и сравниваемые периоды;
  • воронку показы → клики → визиты/цели → транзакции/выручка;
  • confirmed_causes только с прямым системным доказательством;
  • likely_drivers как численный вклад, не как причинное утверждение;
  • hypotheses и следующий read-only тест;
  • draft-действие с явным требованием approval для любого изменения кабинета.

Human feedback хранит confirmed, partial или refuted, фактическую причину и результат действия. Он предназначен для измерения калибровки, не для неявного обучения модели.

Monitor, бенчмарки и dashboards

python scripts/monitor.py --project NAME --date 2026-08-10 --format json
python scripts/benchmark.py --project NAME --period 30d --format html
python scripts/dashboard.py --project NAME --spec report-spec.json --format html

Monitor использует четыре предыдущих сопоставимых дня недели за 28 дней, median и MAD. High alert требует одновременно статистической аномалии, проектной материальности и полного data-quality gate. При недостаточной истории возвращается baseline_insufficient. Доставка ограничена CLI + JSON/HTML: n8n, Telegram и scheduler не входят в навык.

benchmark.py строит только внутренние когорты и показывает n, p25, median, p75. Внешний market benchmark не создаётся.

LLM может превратить естественный запрос в ReportSpec, но dashboard.py принимает лишь JSON со списком зарегистрированных metrics, dimension, period либо date_from/date_to и chart из table|line|bar. Ответ всегда содержит исходный query-spec и data-status.

Пример:

{
  "dimension": "campaign",
  "metrics": ["Cost", "MetrikaRevenue", "CrossSourceROAS"],
  "period": "30d",
  "chart": "bar",
  "top": 10
}

Quality gate

Перед результатом применить evals/shared.csv, evals/skill-specific.csv и evals/judge_prompt.md. Арифметику, зерно данных, coverage, filters, reconciliation, нулевые знаменатели и baseline проверяет код; LLM оценивает только трассируемость и интерпретацию. Не вычислять общий балл.

Запуск локального test gate:

PYTHONPYCACHEPREFIX=/tmp/directanalytics-pycache \
python3 -m unittest discover -s tests -v

Shadow-mode до запуска мониторинга

Для десяти исторических отклонений аналитик сохраняет confirmed, partial или refuted через diagnose.py feedback. В каждом run_id обязательны complete data-status и evidence trail. Локальный gate не обучает модель и не запускает мониторинг:

python scripts/shadow_gate.py --project NAME --minimum-cases 10 --format json

Он считает долю подтверждённых диагнозов, false-certainty для явных confirmed_cause, precision high-priority кейсов (если они промаркированы) и медианное время до human verdict. Пока gate не passed, реальный запуск монитора запрещён процессом; CLI сам не создаёт расписание или доставку.

Навигация по ресурсам

Зависимости

Python-зависимости: requirements.txt. Использовать разрешённое изолированное окружение; при отсутствии зависимостей раскрыть ограничение.

Среда и входы

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

Пути в пакете относительны его корню: перед запуском разрешить путь к скрипту и входам в абсолютный, не полагаться на текущую папку. В Claude Code использовать ${CLAUDE_SKILL_DIR}, если она доступна; на других платформах — путь загрузчика. Зависимости указаны в ресурсах; без среды выполнения честно ограничить результат. Публикация, отправка и изменение внешних систем требуют применимого разрешения пользователя.

Авторство

Методолог навыка — Любовь Черемисина. Лицензия оригинальной методологии и кода этого пакета — MIT.

Атрибуция относится к пакету; не добавлять рекламную подпись в каждый результат.

Ресурсы по необходимости