crawl4ai-seo

crawl4ai-seo

用于网站审核和竞争对手分析的 SEO 爬虫。它回答的问题是：“页面上实际有什么内容，以及网站内部是如何构建的”。

它不能取代 SERP 工具（排名、可见度），而是通过提供页面内容和结构数据来补充这些工具。

功能

任务	描述
Site inventory	全面盘点页面：URL、status、title、H1、meta、canonical、word count
On-page audit	查找问题：title/H1 为空、标题重复、canonical 无效、内容过少
Internal linking audit	内部链接图、孤立页面（0 个入站链接）、关联较弱的页面
Navigation audit	Breadcrumbs、导航区块、菜单一致性、没有出站链接的枢纽页面
Landing comparison	根据页面内信号（title、H1、内容、链接）比较 shortlist URL
Competitor research	通过同一 pipeline 抓取竞争对手页面，并比较模板

配置

全局默认值：config/defaults.example.json，本地覆盖配置：config/defaults.json。 详情请参阅：config/README.md。

规则：defaults 中不存储具体网站或客户端参数。所有特定于网站的配置都通过 launch params 传入，并记录在 cache/jobs/<job_id>/resolved_config.json 中。

工作流

每次抓取前

1. 检查环境：

   python3 scripts/doctor.py
   

   如果 crawl4ai/playwright 尚未就绪，请停留在 seed/discovery 阶段，不要模拟抓取。

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>

脚本

Script	用途
doctor.py	检查环境：uv、Python、crawl4ai、playwright、config
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、标题层级、词数。

导航： 路径深度、breadcrumbs（文本 + URL）、导航区块数量、导航链接数量、导航 URL 示例。

链接： 内部/外部链接数量。links.ndjson 包含完整的链接图：source → target、锚文本、nofollow、same_domain。

导航审计结果

build_navigation_report.py 会自动发现：

问题	对 SEO 的影响
孤立页面（0 个入站链接）	搜索引擎找不到该页面，或无法向其传递权重
链接较少（1 个入站链接）	页面获得的链接权重极少
缺少面包屑导航	机器人和用户都没有导航路径
面包屑不一致	同一分区中存在不同的路径签名，导致层级混乱
导航模板薄弱	Hub 页面上的导航链接数量少得可疑
菜单不一致	页面缺少部分通用导航目标（模板“漂移”）
Hub 薄弱	分类/分区提供的内部链接少于 5 个
标题重复	多个页面的 title 相同，导致关键词蚕食
Canonical 不匹配	canonical 指向的不是页面自身
技术性杂项	导航层中存在登录 URL、php 端点、资源链接
已链接但未收录	网站链接到 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 контент

每个 job 相互隔离。针对不同网站并行运行是安全的。

输出规范

• stdout：仅包含预览和文件路径。
• 完整数据：仅保存在 job 文件中。
• 分析 ndjson 文件时使用 rg、head、wc -l，不要再次启动 browser。

参考资料

• 工作流示例和集成场景
• 缓存布局和输出架构