crawl4ai-seo

crawl4ai-seo

サイト監査と競合分析のためのSEOクローラーです。**「ページに実際に何が掲載されていて、サイトが内部でどのように構成されているか」**を明らかにします。

SERP ツール（順位、可視性）を置き換えるものではなく、ページのコンテンツと構造に関するデータで補完します。

できること

タスク	説明
サイトインベントリ	ページの完全なインベントリ：URL、status、title、H1、meta、canonical、単語数
ページ内監査	空の title/H1、見出しの重複、無効な canonical、薄いコンテンツなどの問題を検出
内部リンク監査	内部リンクのグラフ、孤立ページ（被リンク 0 件）、関連付けが弱いページ
ナビゲーション監査	パンくずリスト、ナビゲーションブロック、メニューの一貫性、発リンクのないハブページ
ランディングページ比較	候補 URL のページ内シグナル（title、H1、コンテンツ、リンク）を比較
競合調査	同じパイプラインで競合ページを処理し、テンプレートを比較

設定

グローバルなデフォルト設定：config/defaults.example.json、ローカルのオーバーライド：config/defaults.json。 詳細：config/README.md。

ルール：defaults には特定のサイトやクライアントのパラメーターを保存しません。サイト固有の情報はすべて起動パラメーターから渡し、cache/jobs/<job_id>/resolved_config.json に記録します。

ワークフロー

クロールの前に必ず行うこと

1. 環境を確認します：

   python3 scripts/doctor.py
   

   crawl4ai/playwright の準備ができていない場合は、seed/discovery の段階で停止し、クロールを実行したように装わないでください。

2. 調査の目的を決めます：

   • サイト全体の監査 → サイトインベントリ + ナビゲーション監査
   • ランディングページの監査 → ランディングページ比較
   • 競合分析 → 競合調査
   • 内部リンクの監査 → 内部リンク監査

3. 起動パラメーターを集めます：

   • target.domain — 調査対象のドメイン
   • job.project — プロジェクト／クライアント
   • job.label — 実行ラベル

メインパイプライン

# 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>

スクリプト

スクリプト	用途
doctor.py	環境を確認：uv、Python、crawl4ai、playwright、設定
init_job.py	job を作成：job_id、launch_params.json、resolved_config.json
seed_urls.py	sitemap/robots/ファイルから URL を検出 → seed.json（crawl4ai なしで動作）
crawl_batch.py	crawl4ai でバッチクロール → pages.ndjson、links.ndjson、summary.json
compare_pages.py	ページ内シグナルに基づいてクロール済みページを表形式で比較
build_navigation_report.py	ナビゲーション監査の概要：孤立ページ、弱いハブ、パンくずリスト、メニューの不整合
common.py	共通ヘルパー（直接実行しないでください）

抽出される SEO シグナル

各ページ（pages.ndjson）から抽出される項目：

ページ内： title、description、keywords、canonical、robots、og:title、og:description、og:image、H1、見出し階層、単語数。

ナビゲーション： パスの深さ、パンくずリスト（テキスト + URL）、ナビゲーションブロック数、ナビゲーションリンク数、ナビゲーション URL のサンプル。

リンク： 内部／外部リンク数。links.ndjson には完全なグラフを記録します：source → target、アンカーテキスト、nofollow、same_domain。

ナビゲーション監査の検出結果

build_navigation_report.py は以下を自動的に検出します。

問題	SEO にとっての意味
孤立ページ（被リンク 0 件）	検索エンジンがページを見つけられない、またはページに評価を渡せません
リンクが弱いページ（被リンク 1 件）	ページが得るリンクエクイティは最小限です
パンくずリストの欠落	ボットとユーザー向けのナビゲーション階層がありません
パンくずリストの不整合	同じセクション内で異なる trail signature が使われており、階層が分かりにくくなっています
ナビゲーションテンプレートが弱い	ハブページのナビゲーションリンク数が疑わしいほど少なくなっています
メニューの不整合	ページで共通のナビゲーション先の一部が欠落しています（テンプレートが「ずれて」います）
ハブが弱い	カテゴリー／セクションからの内部リンクが 5 件未満です
タイトルの重複	同じタイトルのページが複数あり、キーワードのカニバリゼーションが発生しています
canonical の不一致	canonical が自身のページを指していません
技術的な不要要素	ログイン URL、php エンドポイント、ナビゲーション層内のアセットリンク
リンク先が sitemap に未登録	サイトが sitemap にない URL にリンクしています

他のスキルとの連携

シナリオ	連携するスキル	順序
SERP → ページ内監査	yandex-search-api	SERP から候補リストを取得 → crawl4ai で実行
オーガニック流入ページ → 監査	yandex-metrika	オーガニック流入の上位ページを取得 → ページ内の品質を確認
インデックス登録＋監査	yandex-webmaster	インデックス登録済みページとクロール済み一覧を比較
アンチブロック時のフォールバック	scrapedo-web-scraper	crawl4ai がブロックされた場合 — Scrape.do 経由でフォールバック

キャッシュレイアウト

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 контент

各ジョブは分離されています。サイトごとに並列実行しても安全です。

出力の管理

• stdout：プレビューとファイルパスのみ。
• 完全なデータ：ジョブファイルのみ。
• 分析には ndjson ファイルに対して rg、head、wc -l を使用し、ブラウザーを再度起動しないでください。

参考資料

• ワークフローのレシピと統合シナリオ
• キャッシュレイアウトと出力スキーマ