seo-ecommerce

seo-ecommerce (M18)

条件式电商模块：仅在检测到电商信号时运行，随后审查：（a）用于搜索的产品结构化数据；（b）AI 购物 Agent 是否真的能够读取并操作商店。参考：references/schema-tier1.md（Product + Offer、Review/AggregateRating 行）。特定平台的标识符——包括 Shopify 的 Catalog 和 UCP 默认值——位于 references/platforms/shopify.md，并由平台条件检查项输出，而非在此处输出。

输入

根据调度信封中指定的 PageSnapshot 执行：从 <run_dir>/pages/<slug>.json 读取 parsed（jsonld[]、metas[]、text_sample），并从信封读取 vertical——电商门控条件由此处决定；<run_dir>/site/discovery.json 包含对 /.well-known/ucp 和 /api/ucp/mcp 的探测结果（状态、content-type、正文）；<run_dir>/profile.json 指明平台。对 pages/<slug>.html 执行 Grep，以查找逐字证据；站点产物位于 <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. 电商门控：检测电商信号（价格/货币文本、加入购物车/购买控件、Product/Offer schema、og:type=product）。如果没有任何信号，所有 M18 发现均为 not_applicable（严重程度 0）——不要强行要求非电商页面添加产品 schema。
2. Product + Offer：Product 包含 name、image；Offer 包含 price、priceCurrency、availability（schema.org/InStock 等）。详见 references/schema-tier1.md。
3. AggregateRating / Review：如果页面上明确展示了评分，则应有 AggregateRating（ratingValue、reviewCount/bestRating）和/或 Review（author）。绝不要标记页面上未展示的评分。
4. 页面 → schema → 商品 Feed 一致性：schema 中的 price/priceCurrency/availability 必须与页面可见值和商家 Feed 相符。不一致可能导致商品被拒，并失去丰富搜索结果。
5. 分面导航：筛选/排序 URL（?color=、?sort=）应指向规范化的简洁产品/类别 URL，或设置为 noindex，以避免索引膨胀和重复内容稀释。
6. 变体 / ProductGroup：包含多个变体的产品应使用带有 hasVariant 和 variesBy 的 ProductGroup，而不是按每个 SKU 创建重复的独立 Product 区块。

Agentic commerce 准备情况（仅限电商）

购物 Agent 不会像购物者那样浏览商品页：它们会查找机器可读的商家资料、允许它们枚举的商品目录，以及字段可解析的数据源。仅当启用电商垂直领域时才会运行这些检查，并将结果填入 M18 的条件式 AI 类别（权重 6），与搜索类别并列。

7. UCP 商家资料 — /.well-known/ucp 必须可公开访问（200，无需身份验证），且为有效 JSON，其中 ucp.version 格式为 YYYY-MM-DD，services/capabilities 为对象，以反向 DNS 名称为键，并映射到 {version, spec, transport?, endpoint?, schema} 数组。对于非电商垂直领域的商店，此文件归 M21（seo-ai-discovery）负责；对于电商商店，则归 M18 负责。
8. 商品目录资格 — 对每个抽样商品，检查商品目录列出该商品所需的属性：标题、至少一张图片、大于零的价格、稳定且可识别的商品 URL，以及商品在店面中未被隐藏或标记为不可用。报告每件商品的结果，而不是给出单一判定。
9. Agentic 结账数据源（ACP） — 用户通过 --feed <path> 提供数据源时，对其进行 lint 检查：必填字段、以金额加货币代码形式书写的价格（"79.99 USD"）、取值属于允许枚举的可用性字段、通过 mod-10 校验的 GTIN、绝对 URL，以及无重复的 item_id。未提供数据源时，结果为 needs_api，绝不能判定为通过。
10. 数据源 ↔ 页面价格 — 有数据源时，将其中的价格和可用性与渲染后的页面及 schema 进行比对。三个来源，一个真相。
11. Merchant Center / 平台提示 — 已验证的商家数据源是 Google 获取权威商品数据的方式；注明是否可能存在此类数据源（仅有结构化数据不算数据源），以及平台是否声明了商品目录集成。

修复

• AUTO（fixable: auto）：根据 DOM 推断信息（名称、图片、价格、货币、可用性、可见评分），生成完整且有效的 Product/Offer/AggregateRating JSON-LD，并放入带稳定 @id 的单个 @graph 中。该代码块作为 fix 的 diff。
• PROPOSED（fixable: proposed）：针对分面 URL 添加规范链接/noindex 标签、重构 ProductGroup，以及修正数据源字段——这些均为草案，需逐项接受。
• ADVISORY（fixable: advisory）：页面、schema 与数据源之间的价格/可用性不匹配；发布 UCP 资料；加入商品目录。商店后端、数据源和平台才是事实来源，因此工具绝不会写入这些内容。绝不臆造价格、货币、可用性、评分、GTIN 或端点——应询问用户，或留下明确标注的 TODO 占位符。

验证

• 离线：node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-jsonld.mjs" --snapshot <pages/<slug>.json>（或 --url <u>）（schema_validator）——验证 JSON 有效性及必需的 Product/Offer 属性。
• 数据源 lint：node "${CLAUDE_PLUGIN_ROOT}/scripts/acp-feed-lint.mjs" --feed <path>（JSONL、CSV 或 TSV）——检查必填字段、价格格式、可用性枚举、GTIN mod-10、绝对 URL、重复的 item_id（schema_validator）。
• UCP/商品目录探测：node "${CLAUDE_PLUGIN_ROOT}/scripts/ai-discovery.mjs" --snapshot <pages/<slug>.json> 会重新读取 site/discovery.json 并验证资料结构（schema_validator）。
• 第 1 级：Google Rich Results Test / schema.org validator（rich_results_api），用于判断是否符合商家列表资格。
• 所需级别（数据源、API、商家账户）不可用时，状态为 needs_api，绝不能错误地判定为 pass。

发现

按 schema/finding.schema.json 输出发现。对于非电商页面，每个 id 均为 not_applicable，严重性为 0。严重性策略：5 仅用于站点／模板级别可能造成灾难性后果并导致资格丧失的事实；4 重大 · 3 中等 · 2 轻微 · 1 表面 · 0 信息性——且只有处于启用类别中的 established 严重性 5 fail 才能限制评分（references/scoring-model.md）。

产品数据 — 维度 both：

• M18.offer.missing_price — 产品缺少 Offer.price／priceCurrency（fail，严重性 4，fixable: auto，置信度 established）。
• M18.offer.price_feed_mismatch — schema 价格与页面或 feed 中的价格不一致（warn，严重性 3，fixable: advisory，置信度 directional；未提供 feed 时为 needs_api）。
• M18.facets.uncanonicalized — 可索引的分面 URL 既无 canonical，也无 noindex（warn，严重性 3，fixable: proposed，置信度 directional）。
• M18.variants.no_productgroup — 使用每个 SKU 各自重复的 Product 块，而非 ProductGroup + hasVariant（warn，严重性 3，fixable: proposed，置信度 directional）。仅统计声明：若页面已使用 hasVariant 对变体建模，则无论列出多少变体，都不会触发此项。
• Catalog 资格判断针对 ProductGroup 本身；若该组没有自己的报价，则根据变体的报价定价——若组内各变体均有价格，则不属于“缺少价格”。

Agentic 商务就绪度 — 仅限电商：

• M18.agentic.ucp_profile_missing — 商店没有 /.well-known/ucp（warn，严重性 3，维度 ai，fixable: advisory，置信度 directional）。
• M18.agentic.ucp_profile_invalid — 配置文件存在，但版本、services 或 capabilities 的结构无法解析（warn，严重性 3，维度 ai，fixable: advisory，置信度 directional）。
• M18.agentic.ucp_not_public — 配置文件需要身份验证、重定向到登录页面，或内容类型不是 JSON，因此 Agent 无法读取（fail，严重性 3，维度 ai，fixable: advisory，置信度 directional）。
• M18.agentic.catalog_eligibility — 逐产品目录检查：标题、图片、价格 > 0、可识别的 URL 和可见的店面状态全部满足时为 pass；缺少其中一项时为 warn；产品完全无法上架时为 fail（严重性 3，维度 both，fixable: proposed，置信度 directional）。
• M18.agentic.acp_feed_errors — feed lint 检查失败项，每种错误类别一行，并包含出错行（fail，严重性 3，维度 both，fixable: proposed，置信度 directional；未提供 --feed 时一律为 needs_api）。
• M18.agentic.feed_page_price_mismatch — feed 价格或库存情况与渲染后的页面不一致（warn，严重性 3，维度 both，fixable: advisory，置信度 directional）。
• M18.agentic.merchant_center_hint — 已验证的 Merchant feed 是将权威产品数据传至 Google 购物和 AI 界面的文档说明路径（pass，严重性 1，维度 both，fixable: advisory，置信度 established；仅提供信息——我们无法查看商家账号）。
• M18.agentic.shopify_catalog_declared — 平台在其 UCP 配置文件中声明了目录集成（pass，严重性 1，维度 ai，置信度 directional——这是平台默认设置，不代表商家资质）。

每条发现：evidence.observed 引用页面、配置文件或 feed 行中的原文（例如，渲染出的价格文本、出错的 ?filter= URL、item_id 和列）；verification.reproduce 是可运行的命令；expected_impact 必须标注影响区间和置信度（不得只给出百分比）。

诚实性

• AggregateRating/Review 标记不保证获得星级富媒体搜索结果——Google 会酌情展示，并受政策限制；切勿仅凭标记就承诺会显示星级。
• 规范化分面 URL 可减少抓取和索引浪费，但不是直接的排名因素——只能视为 directional，不能保证会带来提升。
• Agentic commerce 尚处早期，相关文档也参差不齐。 UCP、目录登记规则和 Agentic 结账都是供应商项目，变化很快，而且没有供应商会发布“就绪度评分”。所有 M18.agentic.* 发现均为 directional——该组中唯一 established 的说法是：商家 Feed 是权威产品数据的文档化渠道。
• 在 Shopify 上，/.well-known/ucp、agents.md 和 Agentic 发现文件默认提供。它们出现在 Shopify 商店中是平台默认设置，并不能证明商家做了任何操作；它们未出现在非 Shopify 商店中属于缺失项，而非失败。
• Feed 检查失败反映的是文件的问题，而非商店的排名。报告行、字段和规则；不要推算营收或曝光量。
• Schema 必须与页面可见内容和 Feed 严格一致。捏造或与 Feed 不匹配的值可能导致商家不获批准，而非带来好处——并且绝不能编造 GTIN。