seo-firecrawl

Codex SEO 的 Firecrawl 扩展

共享数据缓存

步骤 0 -- 检查共享数据缓存：

开始收集前，检查 .seo-cache/，查看相关 SEO 技能是否已有可复用的上下文。 参考：../seo/references/shared-data-cache.md，了解架构和依赖关系图。

如果以下缓存文件存在，请检查：

• .seo-cache/site-meta.json：域名、业务类型、行业和抓取上下文

• .seo-cache/audit-scores.json：此前完整审计的优先级

• .seo-cache/pages/{url-slug}/page-analysis.json：提供 URL 时的页面级上下文

• 如果找到缓存：解析并使用明确有效的字段（注明“使用了 [date] 的缓存 [X]”）

• 如果缓存缺失、损坏或不相关：继续使用新的证据

• 如果用户说“refresh”或“re-run”：忽略缓存读取，并在写入时覆盖

此技能需要安装 Firecrawl 扩展：

./extensions/firecrawl/install.sh

检查可用性： 使用任何 Firecrawl 工具前，请检查 firecrawl_scrape 或任意 Firecrawl 工具是否可用，以确认 MCP 服务已连接。如果工具不可用，请告知用户尚未安装该扩展，并提供安装说明。

快速参考

命令	用途
/seo firecrawl crawl <url>	抓取整个网站并提取内容
/seo firecrawl map <url>	发现网站结构（仅 URL，速度快）
/seo firecrawl scrape <url>	抓取单个页面并渲染 JS
/seo firecrawl search <query> <url>	在已抓取的网站中搜索

命令

crawl -- 全站抓取

从给定 URL 开始抓取整个网站。返回所有已发现页面的内容、 元数据和链接。

MCP 工具： firecrawl_crawl

参数：

• url（必需）：抓取起始 URL
• limit：最多抓取的页面数（默认值：100，最大值：500）
• maxDepth：相对于起始 URL 的最大链接深度（默认值：3）
• includePaths：要包含的 glob 模式数组（例如，["/blog/*"]）
• excludePaths：要排除的 glob 模式数组（例如，["/admin/*", "/api/*"]）
• scrapeOptions.formats：输出格式 -- ["markdown", "html", "links"]

SEO 使用模式：

1. 全面审计抓取：抓取整个网站，提取所有页面供子 Agent 分析
2. 聚焦特定版块的抓取：使用 includePaths，仅审计 /blog/* 或 /products/*
3. 检测失效链接：使用 ["links"] 格式抓取，检查所有 href 是否返回 404
4. 内容清单：大规模提取所有页面的标题、元描述和 H1
5. SPA/JS 渲染的网站：Firecrawl 会渲染 JavaScript，解决 Issue #11 的问题

/seo audit 的编排示例：

1. firecrawl_map(url) -> get all URLs (fast, no content)
2. Filter to top 50 most important pages (homepage, key sections)
3. firecrawl_crawl(url, limit=50) -> get full content
4. Feed content to seo-technical, seo-content, seo-schema agents

成本提示：

• 免费套餐：每月 500 个点数
• 每抓取或爬取 1 个页面消耗 1 个点数
• Map 操作成本更低（每发现一个 URL 消耗 0.5 个点数）
• 大规模抓取前，务必告知用户预估的点数用量

map -- 发现网站结构

发现网站上的所有 URL，而不获取内容。速度快且节省点数。

MCP 工具： firecrawl_map

参数：

• url（必需）：要映射的网站 URL
• limit：最多发现的 URL 数（默认值：5000）
• search：可选的搜索词，用于筛选 URL

SEO 使用模式：

1. 比较站点地图：映射网站，并比较发现的 URL 与 XML 站点地图
2. 检测孤立页面：查找站点地图中存在、但没有任何页面链接到的 URL
3. 分析抓取预算：比较可编入索引的页面总数与首页链接的页面数
4. 分析 URL 模式：识别 URL 结构模式、重复项和参数冗余
5. 审计前发现：先运行 map，再对关键版块进行定向抓取

输出： URL 数组。请按以下格式呈现：

Site: example.com
Pages discovered: 342

URL Pattern Breakdown:
  /blog/*          - 128 pages (37%)
  /products/*      - 89 pages (26%)
  /category/*      - 45 pages (13%)
  /pages/*         - 32 pages (9%)
  / (root pages)   - 48 pages (14%)

scrape -- 单页深度抓取

使用完整的 JavaScript 渲染抓取单个页面。比 fetch_page.py 更全面，因为它会执行 JS 并等待动态内容加载。

MCP 工具： firecrawl_scrape

参数：

• url（必填）：要抓取的页面 URL
• formats：输出格式 -- ["markdown", "html", "links", "screenshot"]
• onlyMainContent：移除导航栏、页脚和侧边栏（默认：true）
• waitFor：等待内容加载的 CSS 选择器或毫秒数
• timeout：请求超时时间，单位为 ms（默认：30000）
• actions：抓取前的浏览器操作（点击、滚动、等待）

SEO 使用模式：

1. SPA 内容提取：抓取经 JS 渲染的 React/Vue/Angular 页面
2. 动态内容审核：检查折叠区域下方含有延迟加载内容的页面
3. 付费墙/登录检测：识别身份验证墙后方的内容
4. 主要内容提取：使用 onlyMainContent 进行简洁的 E-E-A-T 分析
5. 截图捕获：使用 screenshot 格式进行视觉分析

何时使用 scrape 而非 fetch_page.py：

场景	使用
静态 HTML 页面	fetch_page.py（无 API 费用）
经 JS 渲染的 SPA	firecrawl_scrape（渲染 JS）
需要响应标头	fetch_page.py（返回标头）
需要简洁的 markdown	firecrawl_scrape（提取效果更好）
受到速率限制/被拦截	firecrawl_scrape（可处理反机器人机制）

search -- 站点范围搜索

在网站内搜索特定内容。适合查找与某个主题相关的页面， 而无需抓取整个网站。

MCP 工具： firecrawl_search

参数：

• query（必填）：搜索查询
• url（必填）：要搜索的网站
• limit：结果数量上限（默认：10）
• scrapeOptions.formats：匹配页面的输出格式

SEO 使用模式：

1. 内容缺口验证：在网站上搜索关键词，检查是否已有相关内容
2. 内部链接机会：查找提及某个主题且可相互链接的页面
3. 重复内容检测：搜索关键短语以查找相似内容
4. 竞品内容研究：在竞品网站上搜索特定主题

跨技能集成

与 seo-audit 配合（完整审核）

在 /seo audit 期间 Firecrawl 可用时：

1. 使用 firecrawl_map 发现网站上的所有 URL
2. 与 XML 站点地图（seo-sitemap）对比，查找孤立页面或缺失页面
3. 选择重点页面进行深度分析
4. 将抓取的内容提供给所有子 Agent（技术、内容、schema、geo）
5. 报告可抓取页面总数、URL 模式和抓取深度

与 seo-technical 配合

• 损坏链接检测：抓取所有内部链接，检查是否返回 404
• 重定向链映射：跟踪所有重定向，标记超过 2 次跳转的链
• 混合内容检测：检查 HTTPS 页面上的 HTTP 资源
• 规范 URL 验证：将规范 URL 与实际 URL 对比

与 seo-sitemap 配合

• 站点地图覆盖率：站点地图中包含的已抓取页面百分比
• 孤立页面：通过抓取发现但未列入站点地图的页面
• 过时的站点地图条目：站点地图中返回 404/410 的 URL

与 seo-content 配合

• 内容提取：将简洁的 markdown 提供给 E-E-A-T 分析
• 内容单薄检测：大规模识别少于 300 个词的页面
• 重复内容：比较各页面内容以查找相似内容

与 seo-schema 配合

• Schema 提取：从所有已抓取页面中提取 JSON-LD
• Schema 覆盖率：含有结构化数据的页面百分比
• Schema 验证：批量验证提取出的 schema

错误处理

错误	原因	解决方法
FIRECRAWL_API_KEY not set	未配置 MCP	运行 ./extensions/firecrawl/install.sh
402 Payment Required	额度已用尽	在 firecrawl.dev/app 查看用量并升级套餐
429 Too Many Requests	请求频率受限	等待 60s，并降低抓取并发数
408 Timeout	页面渲染速度过慢	增大 timeout，尝试不启用 JS 渲染
403 Forbidden	网站禁止抓取	检查 robots.txt，可能需要跳过此网站

**优雅降级：**如果 Firecrawl 不可用，请告知用户并建议：

1. 使用 fetch_page.py 分析单个页面（无 API 费用）
2. 使用 WebFetch 工具获取基本 HTML
3. 安装 Firecrawl：./extensions/firecrawl/install.sh

写入共享数据缓存

完成所有工作后，如果工作流产生了可持久化的发现，请将简洁的 JSON 摘要写入 .seo-cache/。 使用 ../seo/references/shared-data-cache.md 中的架构和命名规则；至少包含 cache_type、analyzed_at、来源 URL/域名、关键发现、问题、建议和工具限制。如果 .gitignore 中尚未包含 .seo-cache/，请将其添加进去。