seo-ai-discovery

seo-ai-discovery（M21 — AI 发现与 Agent 端点）

发现文件会告知 Agent 和编码助手应查找的位置；这些文件都不是有文档说明的答案引擎排名或引用信号，因此每项 M21 检查结果都属于 speculative 或 directional，且模块权重为 0。Robots/UA 策略由 seo-ai-crawlers（M14）负责；Agentic Commerce 准备情况（商店中的 UCP + 商品目录 Feed）由 seo-ecommerce（M18）负责。

输入

根据调度信封中指定的 PageSnapshot 开展工作：<run_dir>/site/discovery.json 保存探测结果（/llms.txt、/llms-full.txt、/agents.md、/.well-known/ucp、/.well-known/ai-catalog.json、/sitemap_agentic_discovery.xml、/api/ucp/mcp 的状态、内容类型、字节数、原始响应正文 ≤256 KB）；<run_dir>/site/robots.json 保存 robots 交叉检查的逐个机器人判定结果；信封中的 vertical 决定 UCP 归属。audit.mjs 已输出的确定性检查结果列在 <run_dir>/findings.deterministic.json 中——不要重复输出这些 ID；只添加由模型判定的检查结果。如果直接传入 URL/路径调用，且不存在快照，则先运行 node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"，并使用打印出的快照路径。

审计

1. llms.txt — 存在（200，文本）；符合 llmstxt.org 结构：一个 H1 标题、可选的摘要引用块、包含 - [title](url): note 链接的 H2 分节；链接 URL 可访问（--deep，最多检查 25 个）；读取该文件的 AI 机器人未被 robots 禁止访问。/llms-full.txt 仅报告存在或缺失。
2. agents.md — 报告存在或缺失；如果它是平台默认文件（Shopify 会提供该文件），则注明——仅供参考。
3. UCP 配置文件（/.well-known/ucp）— 仅当 ecommerce 未启用时检查（否则由 M18 负责）：公开访问（200，无需身份验证）、JSON 格式、ucp.version 为 YYYY-MM-DD，services/capabilities 对象以反向 DNS 名称为键，值为 {version, spec, transport?, endpoint?, schema} 数组。注明声明的 dev.shopify.catalog 条目——它表示平台提供目录服务，这是平台默认配置，而非商家的选择。
4. ARD 目录（/.well-known/ai-catalog.json）— 文件存在且为可解析的 JSON。仅报告：v0.9 草案（2026-05-28），采用率接近于零。
5. Agentic 站点地图（/sitemap_agentic_discovery.xml）— 文件存在，XML 格式良好，抽样的 <loc> 条目均可访问。

修复

• 自动修复（fixable: auto）、须经披露同意且得分为 0：仅在用户明确请求时（fix --category ai-discovery，别名 llms），根据网站自身结构（站点地图 URL + 解析出的标题）生成或修复 llms.txt / llms-full.txt；写入前显示差异，并始终说明影响较低且不确定。
• 建议修复（fixable: advisory）：采用 UCP/ARD/Agentic 站点地图，以及解除对被禁止访问的发现文件的限制（robots 的写入由 M14 负责）。工具绝不会代商家编写配置文件——这些文件由平台生成。
• 绝不捏造链接目标、描述、端点或版本——应询问用户，或留下明确标记的 TODO 占位符。

验证

• node "${CLAUDE_PLUGIN_ROOT}/scripts/ai-discovery.mjs" --snapshot <pages/<slug>.json> [--deep] — 重新读取 site/discovery.json，验证 llms.txt 结构（dom_assert）、UCP/ARD JSON 格式（schema_validator）、Agentic 站点地图 XML（xml_parse）以及 robots 交叉检查（robots_parse）。
• 如果发现探测未运行（无网络、本地路径），状态为 needs_api——绝不将其误报为 pass。

发现

遵循 schema/finding.schema.json；轴为 ai；严重性 ≤2；除非另有说明，置信度为 speculative。严重性政策：5 专用于站点／模板级别的灾难性、会导致失去资格的事实；4 重大 · 3 中等 · 2 轻微 · 1 表面 · 0 仅供参考——只有处于启用类别中的 established 严重性为 5 的 fail 才能封顶评分（references/scoring-model.md）。M21 的类别权重为 0，因此无论严重性如何，此处的任何内容都不会改变或封顶任一评分。evidence.observed 逐字引用文件／探测行；verification.reproduce 是上方的命令；expected_impact 按区间表示（不得只写百分比）。ID：

• M21.llmstxt.missing（warn 1，fixable: auto） · M21.llmstxt.malformed（warn 1，fixable: auto） · M21.llmstxt.broken_links（warn 2，fixable: proposed，directional） · M21.llmstxt.blocked_for_ai_bots（warn 2，fixable: advisory，directional——文件存在，但 robots 禁止预期读取它的机器人访问）。
• M21.agents_md.present（pass 1） · M21.agents_md.missing（warn 1，fixable: advisory）。
• M21.ucp.present_valid（pass 2） · M21.ucp.invalid（warn 2，fixable: advisory） · M21.ucp.not_public（warn 2，fixable: advisory）——仅在电商未启用时适用；否则标为 not_applicable，并注明 M18 为负责人。
• M21.ai_catalog.present（pass 1） · M21.ai_catalog.invalid_json（warn 1，fixable: advisory）。
• M21.agentic_sitemap.present（pass 1） · M21.agentic_sitemap.broken_locs（warn 2，fixable: proposed，directional）。

如实说明

• Google 搜索会忽略 llms.txt——Google 的声明（2026-06-15——需核实确切日期；该声明出现在 Optimizing your website for generative AI features 中，该文档更新于 2026-07-10；而 AI features and your website 则称“没有……AI 文本文件”）。切勿将 llms.txt 描述为影响 AI Overviews／AI Mode 的手段。
• 供应商支持不完整（Anthropic 和 Perplexity 会在检索时读取；OpenAI 尚未承诺）；采用率约为 10%，且据 Ahrefs（2026 年 5 月），97% 的 llms.txt 文件没有收到任何机器人请求。该数字只能在附带引文的 rationale 中引用，绝不能放在 expected_impact 中。
• UCP、ARD 和 agentic sitemap 涉及的是 Agent 商务和资源发现，而非答案引擎引用。应报告这些内容；此处没有任何内容会改变 AI Visibility 评分。
• Shopify 商店默认提供上述所有内容（2026 年 5 月）——它们出现在 Shopify 商店中是平台默认行为，并非商家的功绩信号。