Back to Details

seo-ai-discovery

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

seo-ai-discovery (M21 — AI discovery & agent endpoints)

seo-ai-discovery (M21 — AI 发现与 Agent 端点)

Discovery files tell agents and coding assistants where to look; none of them is a documented answer-engine ranking or citation signal, so every M21 finding is 
speculative
or 
directional
and the module's weight is 0. Robots/UA posture lives in 
seo-ai-crawlers
(M14); agentic-commerce readiness (UCP + catalog feeds on stores) lives in 
seo-ecommerce
(M18).
发现文件会告诉 Agent 和编程助手应从哪里查找信息；这些文件均未被记录为答案引擎（answer-engine）的排名或引用信号，因此 M21 的所有发现均为 
speculative
或 
directional
，该模块的权重为 0。Robots/UA 策略归 
seo-ai-crawlers
（M14）负责；商店的 Agent 商务就绪状态（UCP + catalog feeds）归 
seo-ecommerce
（M18）负责。

Inputs

Inputs

Work from the PageSnapshot named in your dispatch envelope: 
<run_dir>/site/discovery.json
holds the probe results (status, content-type, bytes, raw bodies ≤256 KB) for 
/llms.txt
, 
/llms-full.txt
, 
/agents.md
, 
/.well-known/ucp
, 
/.well-known/ai-catalog.json
, 
/sitemap_agentic_discovery.xml
, 
/api/ucp/mcp
; 
<run_dir>/site/robots.json
holds the per-bot verdicts for the robots cross-check; 
vertical
in the envelope decides UCP ownership. Deterministic findings already emitted by 
audit.mjs
are listed in 
<run_dir>/findings.deterministic.json
— do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run 
node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"
and use the printed snapshot path.
使用调度信封（dispatch envelope）中指定的 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
的探测结果（状态、content-type、字节数、≤256 KB 的原始响应体）；
<run_dir>/site/robots.json
保存用于 robots 交叉核查的按 bot 判定结果；信封中的 
vertical
决定 UCP 的归属。
audit.mjs
已输出的确定性发现列于 
<run_dir>/findings.deterministic.json
——不要重复输出这些 id；只添加模型判定发现。如果直接使用 URL/路径调用且不存在快照，请先运行 
node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"
，并使用输出的快照路径。

Audits

Audits

  1. llms.txt — present (200, text); llmstxt.org structure: one H1 title, optional summary blockquote, H2 sections of 
    - [title](url): note
    links; linked URLs resolve (
    --deep
    , ≤25 checked); the file is not disallowed in robots to the AI bots that would read it. 
    /llms-full.txt
    is reported present/absent only.
  2. agents.md — present/absent; note when it is a platform default (Shopify ships one) — informational.
  3. UCP profile (
    /.well-known/ucp
    ) — only when 
    ecommerce
    is not active     (M18 owns it otherwise): public (200, no auth), JSON, 
    ucp.version
    as 
    YYYY-MM-DD
    , 
    services
    /
    capabilities
    objects keyed by reverse-DNS names → arrays of 
    {version, spec, transport?, endpoint?, schema}
    . Note a declared 
    dev.shopify.catalog
    entry — it says the platform exposes a catalog service, which is a platform default, not a merchant decision.
  4. ARD catalog (
    /.well-known/ai-catalog.json
    ) — present and parseable JSON. Report-only: v0.9 draft (2026-05-28), near-zero adoption.
  5. Agentic sitemap (
    /sitemap_agentic_discovery.xml
    ) — present, well-formed XML, sampled 
    <loc>
    entries resolve.
  1. llms.txt — 存在（200，text）；符合 llmstxt.org 结构：包含一个 H1 标题、可选的摘要引用块，以及由 
    - [title](url): note
    链接组成的 H2 分节；链接 URL 均可正常解析（
    --deep
    ，最多检查 25 个）；robots 未禁止会读取该文件的 AI bots。
    /llms-full.txt
    仅报告存在或不存在。
  2. agents.md — 存在或不存在；注明是否为平台默认文件（Shopify 会自带一份）——仅供参考。
  3. UCP 配置（
    /.well-known/ucp
    ）— 仅当 
    ecommerce
    未启用时检查    （否则由 M18 负责）：可公开访问（200，无 auth）、JSON 格式，
    ucp.version
    为 
    YYYY-MM-DD
    ，
    services
    /
    capabilities
    是以反向 DNS 名称为键的对象 → 值为 
    {version, spec, transport?, endpoint?, schema}
    的数组。注明声明的 
    dev.shopify.catalog
    条目——它表示平台公开了 catalog 服务，这属于平台默认行为，而非商户的决策。
  4. ARD catalog（
    /.well-known/ai-catalog.json
    ）— 存在且是可解析的 JSON。仅作报告：v0.9 草案（2026-05-28），采用率接近于零。
  5. Agentic sitemap（
    /sitemap_agentic_discovery.xml
    ）— 存在、XML 格式正确，抽样检查的 
    <loc>
    条目均可正常解析。

Fixes

Fixes

  • AUTO (
    fixable: auto
    ), disclosure-gated and scored 0: generate or repair 
    llms.txt
    / 
    llms-full.txt
    from the site's own structure (sitemap URLs + parsed titles) only on explicit request (
    fix --category ai-discovery
    , alias 
    llms
    ), shown as a diff before writing, always with the disclosure that impact is low/uncertain.
  • ADVISORY (
    fixable: advisory
    ): UCP/ARD/agentic-sitemap adoption, and unblocking a disallowed discovery file (the robots write belongs to M14). The tool never authors a merchant profile — platforms generate those.
  • Never fabricate link targets, descriptions, endpoints, or versions — ask the user or leave a clearly-marked 
    TODO
    placeholder.
  • AUTO（
    fixable: auto
    ），需披露确认且计分为 0：仅在明确请求时（
    fix --category ai-discovery
    ，别名 
    llms
    ），根据站点自身结构（sitemap URL + 解析出的标题）生成或修复 
    llms.txt
    / 
    llms-full.txt
    ，写入前以 diff 形式展示，并始终附带影响较低或不确定的披露说明。
  • ADVISORY（
    fixable: advisory
    ）：关于 UCP/ARD/agentic-sitemap 的采用，以及解除对被 robots 禁止的发现文件的封锁（robots 写入归 M14）。该工具绝不编写商户配置——此类文件由平台生成。
  • 绝不捏造链接目标、描述、端点或版本——应询问用户，或保留明确标记的 
    TODO
    占位符。

Verification

Verification

  • node "${CLAUDE_PLUGIN_ROOT}/scripts/ai-discovery.mjs" --snapshot <pages/<slug>.json> [--deep]
    — re-reads 
    site/discovery.json
    , validates llms.txt structure (
    dom_assert
    ), UCP/ARD JSON shape (
    schema_validator
    ), agentic-sitemap XML (
    xml_parse
    ), and the robots cross-check (
    robots_parse
    ).
  • When the discovery probes did not run (no network, local path), status is 
    needs_api
    — never a false 
    pass
    .
  • 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-sitemap XML（
    xml_parse
    ）以及 robots 交叉核查（
    robots_parse
    ）。
  • 当发现探测未运行时（无网络、本地路径），状态为 
    needs_api
    ——绝不能误报为 
    pass
    。

Findings

Findings

Conform to 
schema/finding.schema.json
; axis 
ai
; severity ≤2; confidence 
speculative
unless noted. Severity policy: 5 is reserved for catastrophic, eligibility-killing facts at site/template scope; 4 major · 3 moderate · 2 minor · 1 cosmetic · 0 informational — and only an 
established
severity-5 
fail
in an active category can cap a score (
references/scoring-model.md
). M21's category weight is 0, so nothing here can move or cap either score whatever its severity. 
evidence.observed
quotes the file/probe line verbatim; 
verification.reproduce
is the command above; 
expected_impact
is banded (no naked %). Ids:
  • 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
    — file exists but robots disallows it to the bots meant to read it).
  • 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
    ) — only when ecommerce is inactive; otherwise 
    not_applicable
    naming M18 as owner.
  • 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
    ).
遵循 
schema/finding.schema.json
；
axis
为 
ai
；
severity
≤2；除非另有说明，
confidence
为 
speculative
。Severity 策略：5 仅保留给站点或模板范围内具有灾难性后果、可能使资格归零的事实；4 为重大 · 3 为中等 · 2 为轻微 · 1 为表面性问题 · 0 为信息性——且只有活跃分类中一个 
established
、severity-5 的 
fail
才能给分数封顶（
references/scoring-model.md
）。M21 的分类权重为 0，因此无论 severity 如何，此处的内容都无法提高或封顶任一分数。
evidence.observed
逐字引用文件或探测行；
verification.reproduce
为上述命令；
expected_impact
使用分级区间（不得出现裸百分比）。Ids：
  • 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 禁止了应读取它的 bots）。
  • 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
    ）——仅当 ecommerce 未启用时适用；否则使用 
    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
    ）。

Honesty

Honesty

  • Google Search ignores llms.txt — Google's statement (2026-06-15 — TO-VERIFY the exact date; it appears in Optimizing your website for generative AI features, updated 2026-07-10, and AI features and your website says "no … AI text files"). Never present llms.txt as an AI Overviews / AI Mode lever.
  • Vendor support is partial (Anthropic and Perplexity read it in retrieval; OpenAI uncommitted); adoption is ~10% and, per Ahrefs (May 2026), 97% of llms.txt files received zero bot requests. Quote that figure only in 
    rationale
    with the citation — never in 
    expected_impact
    .
  • UCP, ARD, and the agentic sitemap concern agent commerce and resource discovery, not answer-engine citation. Report them; nothing here moves the AI Visibility score.
  • Shopify stores ship all of these by default (May 2026) — their presence on a Shopify store is a platform default, not a merchant merit signal.
  • Google Search 会忽略 llms.txt——Google 的声明（2026-06-15——待核实（TO-VERIFY）确切日期；它出现在 Optimizing your website for generative AI features（优化网站以提升生成式 AI 功能）中，该文档更新于 2026-07-10；AI features and your website（AI 功能与你的网站）也称“没有……AI 文本文件”（“no … AI text files”））。绝不能将 llms.txt 描述为提升 AI Overviews / AI Mode 表现的杠杆。
  • 厂商仅提供部分支持（Anthropic 和 Perplexity 会在检索时读取它；OpenAI 尚未明确承诺支持）；采用率约为 10%，且据 Ahrefs（2026 年 5 月）的数据，97% 的 llms.txt 文件没有收到任何 bot 请求。只能在 
    rationale
    中引用该数据并附上引用来源——绝不能放在 
    expected_impact
    中。
  • UCP、ARD 和 agentic sitemap 关注的是 Agent 商务和资源发现，而非答案引擎引用。报告这些项目；这里没有任何内容会影响 AI Visibility 分数。
  • Shopify 商店默认会提供上述所有文件与端点（2026 年 5 月）——它们出现在 Shopify 商店中属于平台默认行为，而不是商户自身能力或优势的信号。