seo-schema

Schema 标记分析与生成

共享数据缓存

步骤 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 时的页面级上下文

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

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

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

检测

1. 扫描页面源代码，查找 JSON-LD <script type="application/ld+json">
2. 检查 Microdata（itemscope、itemprop）
3. 检查 RDFa（typeof、property）
4. 始终优先推荐 JSON-LD 格式（这是 Google 明确表示的偏好）

验证

• 检查各架构类型的必需属性
• 根据 Google 支持的富媒体搜索结果类型进行验证
• 检查常见错误：
  • 缺少 @context
  • @type 无效
  • 数据类型错误
  • 占位文本
  • 相对 URL（应为绝对 URL）
  • 日期格式无效
• 标记已弃用的类型（见下文）

架构类型状态（截至 2026 年 2 月）

完整列表请参阅 references/schema-types.md。主要规则：

ACTIVE（可自由推荐）：

Organization、LocalBusiness、SoftwareApplication、WebApplication、Product（自 2025 年 4 月起支持 Certification 标记）、ProductGroup、Offer、Service、Article、BlogPosting、NewsArticle、Review、AggregateRating、BreadcrumbList、WebSite、WebPage、Person、ProfilePage、ContactPage、VideoObject、ImageObject、Event、JobPosting、Course、DiscussionForumPosting

VIDEO & SPECIALIZED（可自由推荐）：

BroadcastEvent、Clip、SeekToAction、SoftwareSourceCode

请参阅 schema/templates.json，获取这些类型可直接使用的 JSON-LD 模板。

JSON-LD 和 JavaScript 渲染： 根据 Google 于 2025 年 12 月发布的 JavaScript SEO 指南，通过 JavaScript 注入的结构化数据可能会延迟处理。对于有时效性的标记（尤其是 Product、Offer），请将 JSON-LD 放入初始服务器渲染的 HTML 中。

RESTRICTED（仅限特定网站）：

• FAQ：仅限政府和医疗卫生主管机构网站（2023 年 8 月起受限）

DEPRECATED（切勿推荐）：

• HowTo：富媒体搜索结果已于 2023 年 9 月移除
• SpecialAnnouncement：已于 2025 年 7 月 31 日弃用
• CourseInfo、EstimatedSalary、LearningVideo：已于 2025 年 6 月停用
• ClaimReview：已于 2025 年 6 月从富媒体搜索结果中停用
• VehicleListing：已于 2025 年 6 月从富媒体搜索结果中停用
• Practice Problem：已于 2025 年底从富媒体搜索结果中停用
• Dataset：已于 2025 年底从富媒体搜索结果中停用
• Book Actions：弃用后又恢复，截至 2026 年 2 月仍可使用（历史说明）

生成

为页面生成架构时：

1. 根据内容分析识别页面类型
2. 选择合适的架构类型
3. 生成包含所有必需属性和推荐属性的有效 JSON-LD
4. 仅包含真实且可验证的数据。使用明确标注、供用户填写的占位符
5. 在呈现输出前进行验证

常见架构模板

Organization

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "[Company Name]",
  "url": "[Website URL]",
  "logo": "[Logo URL]",
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "[Phone]",
    "contactType": "customer service"
  },
  "sameAs": [
    "[Facebook URL]",
    "[LinkedIn URL]",
    "[Twitter URL]"
  ]
}

LocalBusiness

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "[Business Name]",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "[Street]",
    "addressLocality": "[City]",
    "addressRegion": "[State]",
    "postalCode": "[ZIP]",
    "addressCountry": "US"
  },
  "telephone": "[Phone]",
  "openingHours": "Mo-Fr 09:00-17:00",
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": "[Lat]",
    "longitude": "[Long]"
  }
}

Article/BlogPosting

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "[Title]",
  "author": {
    "@type": "Person",
    "name": "[Author Name]"
  },
  "datePublished": "[YYYY-MM-DD]",
  "dateModified": "[YYYY-MM-DD]",
  "image": "[Image URL]",
  "publisher": {
    "@type": "Organization",
    "name": "[Publisher]",
    "logo": {
      "@type": "ImageObject",
      "url": "[Logo URL]"
    }
  }
}

输出

• SCHEMA-REPORT.md：检测和验证结果
• generated-schema.json：可直接使用的 JSON-LD 代码片段

验证结果

架构	类型	状态	问题
...	...	✅/⚠️/❌	...

建议

• 缺失的架构机会
• 需要修复的验证问题
• 用于实施的生成代码

错误处理

场景	操作
URL 无法访问	报告连接错误及状态码。建议验证 URL，并检查页面是否需要身份验证。
未找到 Schema 标记	报告未检测到 JSON-LD、Microdata 或 RDFa。根据页面内容分析结果，推荐适当的 Schema 类型。
JSON-LD 语法无效	解析并报告具体语法错误（缺少括号、尾随逗号、键未加引号）。提供修正后的 JSON-LD 输出。
检测到已弃用的 Schema 类型	标记已弃用的类型及其弃用日期。推荐当前的替代类型；如果没有替代类型，则建议移除。

写入共享数据缓存

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