seo-schema-jsonld

seo-schema-jsonld（M5）

结构化数据是提升传统富媒体搜索结果和 AI 引用效果的最高杠杆信号。参考：references/schema-tier1.md。模板：schema/jsonld-templates/。

输入

根据调度信封中指定的 PageSnapshot 开展工作：从 <run_dir>/pages/<slug>.json 读取 parsed（jsonld[]、microdata_items、headings[]、images[]）；使用 Grep 在 pages/<slug>.html 中查找原文证据；站点产物位于 <run_dir>/site/{robots.json,sitemaps.json,discovery.json}。audit.mjs 已输出的确定性检查结果列于 <run_dir>/findings.deterministic.json 中——不要重新输出这些 ID；仅添加由模型判断的检查结果。如果直接通过 URL/路径调用，且不存在快照，则先运行 node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"，并使用打印出的快照路径。

审计

基于 PageSnapshot 开展工作（当 render.used 不是 none 时使用 parsed_rendered，否则使用 parsed）：

1. 检测每个 <script type="application/ld+json"> 块；解析 JSON；记录任何内联 microdata/RDFa（标记为迁移到 JSON-LD）。
2. 验证每个块：JSON 是否有效、@type 是否可识别，以及是否具备 references/schema-tier1.md 中要求和推荐的属性。
3. 完整性（对照页面内容与垂直领域）：例如，文章页面应包含具有 author（Person）、datePublished、dateModified、image、publisher 的 Article/BlogPosting；产品页面应包含 Product + Offer（price、priceCurrency、availability）。
4. 实体规范性：稳定的 @id、@graph 链接、sameAs（将 sameAs 审计详情留给 M6/seo-entity-linking）。
5. 日期一致性：Schema 中的 datePublished/dateModified 应与可见日期一致（与 M13 交叉核对）。
6. 弃用说明：如果存在 FAQPage/HowTo，不要将其报告为富媒体搜索结果优势——标记为已弃用于 SERP（AI 仍可解析）。

修复（可修复：自动）

对于缺失/不完整的 Tier-1 类型，根据页面内容推断并生成完整、有效的 JSON-LD 块：

• 从 <article>、<h1>、作者署名、日期、主图生成 Article/BlogPosting。
• 从页脚/联系信息/Logo 生成 Organization/WebSite。
• 从产品 DOM 生成 Product+Offer（名称、图片、价格、币种、供应情况）。
• 从面包屑导航生成 BreadcrumbList。
• 生成包含资质字段的 Person（作者），资质信息由用户提供。 使用带稳定 @id 的单个 @graph。补入缺失的 dateModified/@id。该块是供 fix（AUTO）使用的差异。绝不编造价格、日期、评分或 sameAs 身份链接——应询问用户，或留下明确标注的 TODO 占位符供用户填写。

验证

• 离线：node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-jsonld.mjs" --snapshot <pages/<slug>.json>（或 --url <u>）——根据模板检查 JSON 有效性和必需属性。
• Tier 1：使用 Google Rich Results Test / schema.org validator 确认是否符合资格。不可用时，状态应为 needs_api，而不是 pass。

调查结果

根据 schema/finding.schema.json 输出调查结果。严重程度策略：5 级仅用于网站／模板范围内的灾难性、会导致失去资格的事实；4 级为重大 · 3 级为中等 · 2 级为轻微 · 1 级为外观问题 · 0 级为信息性——且只有活动类别中已确认的 5 级 fail 才能限制评分（references/scoring-model.md）。示例：

• M5.article.missing — 编辑页面没有 Article schema（fail，严重程度 4，fixable: auto，轴 both，置信度 established）。
• M5.product.missing_offer_price — 产品页面上的 Product 没有 Offer.price（fail，严重程度 4，fixable: auto，轴 both，置信度 established）。这里只统计声明了产品的节点（lib/jsonld.mjs classifyProductNodes）：hasVariant 成员属于其 ProductGroup，评论的 itemReviewed 以及 isSimilarTo／isRelatedTo 节点指向其他位置声明的商品，而仅包含嵌套 url/name 的节点是指针——这些都不属于本页面缺失的标记。
• M5.jsonld.invalid_json — ld+json 区块无法解析，因此其中所有类型都不可见（fail，严重程度 4，fixable: auto，轴 both，置信度 established）。
• M5.jsonld.contradicts_page — 标记的值（价格、评分、日期、作者）与页面显示的内容不一致（fail，严重程度 4，fixable: proposed，轴 both，置信度 established）。
• M5.faqpage.deprecated_richresult — 存在 FAQPage（warn，严重程度 1，fixable: advisory，轴 ai，置信度 established；理由引用了 Google 移除 FAQ 富媒体搜索结果的说明；不计为一项成果）。 依平台触发的 ID。 仅当 profile.json 指定平台（shopify、wordpress）时，本模块才会额外输出 4 个 ID。详见 references/routing.md § 依平台触发的调查结果 ID，以及 references/platforms/<id>.md §10。

每项调查结果：evidence.observed 引用页面上的实际内容；verification.reproduce 是上文可运行的命令；expected_impact 按区间划分并标注置信度（不能只给出百分比）。

诚实性

• Google 没有为其 AI 功能记录任何特殊的 schema.org 类型、属性或“AI schema”。 AI Overviews／AI Mode 的资格取决于页面是否已编入索引且符合摘要资格（M14），而非标记。已有文档说明、因此属于 established 的是：结构化数据必须有效且与页面可见内容一致，才能被使用——无论用于富媒体搜索结果，还是 Google 获取的商家／企业数据。应将 schema 工作表述为“让页面可供机器读取且内容可信”，而不是“解锁 AI 引用”。
• FAQPage／HowTo：仍可解析，但没有 Google 富媒体搜索结果——如果已存在就保留，不要为了获得 SERP 功能而添加。
• 不要标记页面上不可见的内容，并确保 schema 与任何产品 Feed 保持一致；虚构或不匹配的值会招致人工处置和拒批，而非带来成果。
• 有效区块是基础门槛，而非排名杠杆：将正确 schema 的存在报告为资格条件，绝不要将其描述为可预测排名位置变化。