artwist-polyakov/crawl4ai-seo

crawl4ai-seo

SEO-краулер для аудита сайтов и конкурентного анализа. Отвечает на вопрос: "что реально лежит на страницах и как сайт устроен изнутри".

Не заменяет SERP-инструменты (позиции, видимость) — дополняет их данными о содержимом и структуре страниц.

Что умеет

| Задача | Описание | |--------|----------| | Site inventory | Полная инвентаризация страниц: URL, status, title, H1, meta, canonical, word count | | On-page audit | Поиск проблем: пустые title/H1, дубли заголовков, битые canonical, thin content | | Internal linking audit | Граф внутренних ссылок, orphan pages (0 входящих), слабо связанные страницы | | Navigation audit | Breadcrumbs, nav-блоки, menu consistency, hub-страницы без исходящих ссылок | | Landing comparison | Сравнение shortlist URL по on-page сигналам (title, H1, content, links) | | Competitor research | Прогон страниц конкурентов через тот же pipeline, сравнение шаблонов |

Config

Глобальные defaults: config/defaults.example.json, локальный override — config/defaults.json. Подробности: config/README.md.

Правило: в defaults не храним конкретный сайт или параметры клиента. Всё site-specific приходит через launch params и фиксируется в cache/jobs/<job_id>/resolved_config.json.

Workflow

Перед любым crawl

1. Проверь окружение:

   python3 scripts/doctor.py
   

   Если crawl4ai/playwright не готовы — остановись на seed/discovery, не имитируй crawl.

2. Определи цель исследования:

   • Полный аудит сайта → site inventory + navigation audit
   • Аудит лендингов → landing comparison
   • Анализ конкурентов → competitor research
   • Аудит перелинковки → internal linking audit

3. Собери launch params:

   • target.domain — домен исследования
   • job.project — проект/клиент
   • job.label — метка запуска

Основной pipeline

# 1. Создать job
python3 scripts/init_job.py --domain https://example.com --project client-a --label full-audit

# 2. Собрать seed URL из sitemap/robots
python3 scripts/seed_urls.py --job-id <job_id>

# 3. Запустить crawl
uv run --script scripts/crawl_batch.py --job-id <job_id>

# 4. Построить навигационный отчёт
python3 scripts/build_navigation_report.py \
  --seed-job-id <seed_job_id> \
  --crawl-job-id <crawl_job_id> \
  --report-dir reports/<project>/<label>

# 5. Сравнить страницы
python3 scripts/compare_pages.py --job-id <job_id>

Быстрый вариант (без отдельного init)

python3 scripts/seed_urls.py --domain https://example.com --project client-a --label quick-check
uv run --script scripts/crawl_batch.py --job-id <job_id>

Scripts

| Script | Назначение | |--------|-----------| | doctor.py | Проверка окружения: uv, Python, crawl4ai, playwright, config | | init_job.py | Создание job: job_id, launch_params.json, resolved_config.json | | seed_urls.py | Discovery URL из sitemap/robots/файла → seed.json (работает без crawl4ai) | | crawl_batch.py | Batch crawl через crawl4ai → pages.ndjson, links.ndjson, summary.json | | compare_pages.py | Табличное сравнение crawled pages по on-page сигналам | | build_navigation_report.py | Сводный навигационный аудит: orphans, weak hubs, breadcrumbs, menu drift | | common.py | Shared helpers (не запускать напрямую) |

Extracted SEO Signals

На каждую страницу (pages.ndjson) извлекаются:

On-page: title, description, keywords, canonical, robots, og:title, og:description, og:image, H1, headings hierarchy, word count.

Navigation: path depth, breadcrumbs (texts + URLs), nav blocks count, nav links count, nav URLs sample.

Links: internal/external links count. В links.ndjson — полный граф: source → target, anchor text, nofollow, same_domain.

Navigation Audit Findings

build_navigation_report.py автоматически находит:

| Проблема | Что значит для SEO | |----------|-------------------| | Orphan pages (0 входящих ссылок) | Поисковик не найдёт страницу или не передаст ей вес | | Weakly linked (1 входящая) | Страница получает минимум link equity | | Missing breadcrumbs | Нет навигационной цепочки для бота и пользователя | | Breadcrumb inconsistency | Разные trail signatures в одной секции — путаница в иерархии | | Weak nav template | Hub-страница с подозрительно малым числом nav-ссылок | | Menu inconsistency | Страницы теряют часть common nav targets (шаблон "дрейфует") | | Weak hubs | Категория/раздел отдаёт <5 внутренних ссылок | | Duplicate titles | Несколько страниц с одинаковым title — каннибализация | | Canonical mismatches | canonical указывает не на себя | | Technical junk | login-URL, php endpoints, asset-ссылки в навигационном слое | | Linked-not-seeded | Сайт линкует URL, которых нет в sitemap |

Связка с другими скиллами

| Сценарий | Скилл-партнёр | Порядок | |----------|--------------|---------| | SERP → on-page audit | yandex-search-api | Получи shortlist из SERP → прогони через crawl4ai | | Organic landings → audit | yandex-metrika | Возьми top organic pages → проверь on-page quality | | Индексация + audit | yandex-webmaster | Сравни indexed pages с crawled inventory | | Anti-block fallback | scrapedo-web-scraper | При блокировке crawl4ai — fallback через Scrape.do |

Cache Layout

cache/jobs/<job_id>/
  launch_params.json      # raw params этого запуска
  resolved_config.json    # effective config после merge defaults + params
  manifest.json           # operational state и artifact paths
  seed.json               # seed URLs и метаданные discovery
  pages.ndjson            # одна запись на страницу
  links.ndjson            # одна запись на link edge
  summary.json            # компактная сводка
  markdown/               # сохранённый markdown контент

Каждый job изолирован. Параллельные запуски по разным сайтам безопасны.

Output Hygiene

• stdout: только preview и пути к файлам.
• Полные данные: только в job files.
• Для анализа используй rg, head, wc -l по ndjson-файлам, не поднимай browser повторно.

References

• Workflow recipes and integration scenarios
• Cache layout and output schema