seo-schema

示例输出：examples/seo-schema-budgetbytes-slow-cooker-chicken-noodle-soup-20260514/SCHEMA.md

Schema 标记

检测、验证并为页面生成 Schema.org JSON-LD。输出可直接粘贴的 <script> 代码块，用户可将其放入自己的 CMS 或页面模板中；此外还会提供一份验证报告，说明当前页面已有的内容和存在的问题。

前置条件

• 检测/验证路径必需： mcp__firecrawl-mcp__firecrawl_scrape（用于访问原始 HTML）。WebFetch 只返回 Markdown——在技能看到任何 <script type="application/ld+json"> 代码块之前，这些代码块就已被移除。没有 Firecrawl 时，技能仍可通过意图检测生成新的 Schema（步骤 4–6），但无法检测或验证页面上已有的内容（步骤 2–3、7）。
• 可选：SE Ranking MCP 服务（在步骤 7 中用于对标竞争对手的 Schema）。
• 用户提供：目标 URL。如果 URL 模式无法明确判断页面意图，也可以提供提示（“这是一个产品页面”“这是一个操作指南”）。

流程

1. 获取 HTML：使用 mcp__firecrawl-mcp__firecrawl_scrape（首选），否则采用降级方案

   • 费用说明。 Firecrawl：目标 URL 消耗 1 个额度；如果执行步骤 7（竞争对手对标），则额外消耗 10 个额度（每个排名前 10 的 SERP 结果消耗 1 个）。用户可以传入 --no-firecrawl，强制采用降级路径（仅生成模式）以节省额度。
   • **如果 Firecrawl 可用：**抓取目标 URL。对于 SPA，传入 waitFor: 2000（或主内容的 CSS 选择器），以捕获 JS 渲染后的 DOM。步骤 2 中使用响应的 html 解析 JSON-LD，使用 metadata 交叉核对 canonical/robots 信息。
   • **如果 Firecrawl 不可用：**完全跳过步骤 2、3 和 7（这些步骤都需要原始 HTML）。仍会执行步骤 4–6——技能将进入“仅生成”模式，根据意图检测生成推荐的 JSON-LD 代码块，但不会与页面现有内容进行比较。在 SCHEMA.md 中明确说明：现有 Schema 检测：已跳过——此操作需要 Firecrawl（WebFetch 只返回 markdown）。请通过 extensions/firecrawl/install.sh 安装。
   • 即使使用 Firecrawl：如果 JSON-LD 代码块仅在 JS 渲染后才出现，也要在输出中标明：“并非所有爬虫都能检测到 JS 渲染的 Schema——请尽可能在服务器端渲染 JSON-LD。”

2. 检测现有 Schema（需要步骤 1 中的 Firecrawl HTML）

   • 从返回的 html 中提取每个 <script type="application/ld+json"> 代码块。
   • 将每个代码块解析为 JSON。报告语法错误。
   • 列出检测到的每个 @type。
   • 同时检测 Microdata（itemscope/itemprop）和 RDFa（typeof/property）——标记为旧格式，并建议迁移到 JSON-LD（这是 Google 明确表示的首选格式）。
   • **如果步骤 1 采用降级方案：**跳过此步骤。在 01-detected.md 中记录 现有 Schema 检测已跳过。

3. 根据 Google 规范验证

   • 加载 references/google-rich-results.md。
   • 对每个检测到的 @type，检查必需和推荐属性。
   • 指出常见错误：缺少 @context、日期不符合 ISO 8601、价格使用数字而非字符串、availability 使用纯文本而非 schema.org URL、电话号码不符合国际格式。

4. 检测页面意图

   • 根据 URL 模式（/blog/、/products/、/contact/、/how-to/、/faq/）。
   • 根据 <title> 和 <h1> 的语气。
   • 根据内容信号（编号步骤列表 → HowTo；可见的问答内容块 → FAQPage；价格 + 购买按钮 → Product；地址 + 营业时间 → LocalBusiness）。
   • 如果检测到多种意图，则为每种意图生成 Schema。

5. 生成缺失的 JSON-LD

   • 对于每个检测到但没有匹配有效架构的意图，从 templates/ 加载相关模板：
     • article.json — 用于编辑或博客内容
     • product.json — 用于产品／SKU 页面
     • local-business.json — 用于实体店落地页
     • faq-page.json — 用于明确的问答区块（仅限政府／健康领域许可名单，参见 references/google-rich-results.md）
     • breadcrumb-list.json — 用于带有面包屑导航的页面
   • 根据实时 HTML 填充模板字段（title → headline，h2 → mainEntity 问题等）。
   • 将无法自动填充的字段标记为 {REPLACE: ...}，以便用户知道需要补全。
   • 不要生成 HowTo — Google 已于 2023 年 9 月停用 HowTo 富媒体搜索结果（移动端和桌面端均如此）。该架构仍可用于语义清晰度，但预期不会带来任何富媒体搜索结果提升；应在建议理由中说明这一点，而不要将 HowTo 视为当前可用选项。

6. 验证生成的 JSON-LD

   • 使用步骤 3 中相同的验证标准，重新验证生成的区块。
   • 指出仍标记为 {REPLACE: ...} 的必填字段。

7. 可选：对照 SERP 顶部结果进行基准分析 DATA_getSerpResults + mcp__firecrawl-mcp__firecrawl_scrape

   • 确定页面的主要关键词（来自 <title> 或用户输入）。
   • 获取自然搜索结果前 10 名。
   • **如果 Firecrawl 可用：**抓取前 10 名中的每个结果（消耗 10 个 Firecrawl 积分）。对于每个结果，从返回的 html 中解析 JSON-LD 区块并列出检测到的 @type。这样得到的是实际架构数据，而非根据 Markdown 推断的结果。
   • **如果 Firecrawl 不可用：**跳过基准分析——WebFetch 的 Markdown 会剥除所有架构区块，因此通过它进行任何“检测”都只是猜测。在 04-competitor-benchmark.md 中写入 Competitor benchmark skipped — Firecrawl required to read JSON-LD from competitor pages.。
   • 指出“前 10 名中至少有 6 个使用、但此页面缺失的架构类型”。这是高价值补充列表。（仅在运行了基准分析时生成。）

8. 整合 SCHEMA.md

   • 验证报告（现有架构，逐区块标明通过／失败）。
   • 建议添加项（说明理由，并关联到步骤 4 的检测或步骤 7 的基准分析）。
   • 可直接粘贴的生成版 <script> 区块。

输出格式

创建文件夹 seo-schema-{target-slug}-{YYYYMMDD}/，其中包含：

seo-schema-{target-slug}-{YYYYMMDD}/
├── 01-detected.md           (existing schema, validation results)
├── 02-recommended.md        (which types this page should add and why)
├── 03-generated/
│   ├── article.jsonld
│   ├── faq-page.jsonld
│   └── ... (per generated type)
├── 04-competitor-benchmark.md  (only if step 7 ran)
└── SCHEMA.md                (deliverable: paste-ready blocks + install instructions)

SCHEMA.md 按以下结构编写：

# Schema Markup: {URL}

> Snapshot dated {YYYY-MM-DD}.

## Currently present
- `Article` — valid ✓
- `BreadcrumbList` — invalid ✗ (missing `position` on item 2)
- ...

## Recommended additions
- `FAQPage` — page has 6 visible Q&A blocks but no FAQ schema. Adding this is eligible for FAQ rich results (subject to Google's 2024+ tightening — see references/google-rich-results.md).
- `HowTo` — ...

## Paste these into the `<head>` of the page

### FAQPage
\`\`\`html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [...]
}
</script>
\`\`\`

### ... (per generated block)

## Validation pass
- All generated blocks parse cleanly ✓
- All required fields filled ({n} {REPLACE: ...} placeholders remain — see below)
- {REPLACE: ...} placeholders to fill manually:
  - article.jsonld → `image` (need a hero image URL ≥ 1200×800)
  - ...

## Install
1. Copy each `<script>` block above.
2. Paste into the `<head>` of the relevant page (or the global `<head>` template, gated by page type).
3. Test with [Google's Rich Results Test](https://search.google.com/test/rich-results).
4. Submit the URL to GSC for re-indexing if changes are critical.

提示

• JSON-LD 应放在 <head> 或 <body> 顶部，不要埋得太深。
• 发布前，使用 Google 的 Rich Results Test 测试每个生成的区块。步骤 3/6 中的验证遵循已发布的规范，但 Google 的实际测试才是权威依据。
• references/google-rich-results.md 带有日期。如果运行此技能时该文件已超过 6 个月，应在输出中标明其内容可能过时，并建议用户根据当前文档进行核实。
• 不要为页面上不可见的内容添加标记。 Google 会惩罚隐藏内容架构。如果页面上实际上没有可见的常见问题解答，就不要生成 FAQPage 架构。
• 对于 Article 架构，image 为必填项。如果页面没有明显的主视觉图片，应保留 {REPLACE: hero image URL} 占位符，不要猜测。
• 此技能在 SE Ranking 侧主要执行只读操作：除非请求执行步骤 7（竞争对手基准分析），否则不消耗 SE Ranking 积分；执行该步骤会为 DATA_getSerpResults 额外消耗约 5–10 个 SE Ranking 积分。Firecrawl 费用另计：目标 URL 消耗 1 个积分，运行步骤 7 时额外消耗 10 个积分。
• **部署后验证：**将生成的架构粘贴到 CMS 并重新部署后，再对同一 URL 运行此技能——新一轮运行的“当前存在”部分会反映实时状态，并确认架构确实已渲染（而不是还留在 CMS 中、尚未推送）。临时替代方法：对该 URL 调用 seo-firecrawl，并在 META.md 中搜索预期的 @type。