agentic-commerce-readiness

Magento 2 的 AI Agent 就绪度

ExpandingWeb_AgentReadiness 可在 Magento 2 / Adobe Commerce 商店的管理后台中运行八项公开的 Agent 就绪度检查，并统计你的店面已收到的 AI Agent 流量（GPTBot、ClaudeBot、PerplexityBot，……）。

这是 Expanding Web 推出的 Agentic Commerce Suite 的免费开源版本，采用 MIT 许可。默认情况下，任何数据都不会离开你的商店（参见隐私）。

八项检查

检查 ID、语义和结果表述均与 https://expandingweb.com/#scan 上的公开扫描器一致——在管理后台、公开扫描和季度基准中，分数代表的含义相同。

ID	检查项	通过条件
UCP-01	/.well-known/ucp 配置文件	该路径下存在配置文件，且通过 Universal Commerce Protocol 规范（版本 2026-04-08）的验证。
MCP-01	广告的 MCP 端点可访问	UCP 配置文件指定的 MCP 端点（或 <link rel="mcp">）能响应 initialize 握手，并列出至少一个工具。若配置文件广告的端点不可用，则检查不通过。
BOT-01	面向 AI 购物爬虫的 robots.txt 策略	面向 Agent 所用爬虫（GPTBot、ClaudeBot、PerplexityBot、OAI-SearchBot、ChatGPT-User、Claude-User、Applebot-Extended、Amazonbot、Bingbot、meta-externalagent、CCBot）的策略允许它们读取商品 URL，而不只是主页；主页也未设置 noindex/noai 指令。
AGENT-01	边缘节点向 AI Agent 用户代理提供服务	robots.txt 声明的是策略，边缘节点体现的才是真实情况。扫描器会使用 GPTBot 和 ClaudeBot 的身份抓取主页，并检查 CDN 或防火墙是否向这些用户代理返回 401/403/429/503，或触发机器人验证。
CRAWL-01	搜索和分面 URL 的爬取限制	目录搜索和分层导航会生成无限多个不同的 URL，且每个都是缓存未命中；此项检查会确认 robots.txt 是否为每个 AI 爬虫（而不只是 *）限制这些 URL（/catalogsearch/result/、/search、查询字符串 URL）。
LLMS-01	存在 /llms.txt	网站根目录下存在为大模型编写的纯文本索引。
FEED-01	商品结构化数据完整性	抽样的商品页面（最多三个）在 27 个属性的加权评分中至少获得 16 / 35 分。Agent 无法完成交易所必需的八项信息——名称、图片、GTIN、价格、货币、库存情况、配送详情、退货政策——按双倍分值计算；可能产生误导的值（GS1 校验位错误、价格非数字、priceValidUntil 已过期）不得分。
SCHEMA-01	Product、Offer、AggregateRating JSON-LD	商品页面包含有效的商品 JSON-LD，其中带有报价；如果存在评论，还需包含聚合评分。

结果说明：

• 分数是通过的检查数除以适用的检查数。这是就绪度指标，不是排名预测——没人能保证内容会出现在 AI 答案中，本模块也不作此承诺。
• 如果某项检查无法运行（没有可供抽样的商品目录、边缘节点拒绝访问某个路径、60 秒预算用尽），就会显示 N/A。这不会影响分数。
• 已阻止（扫描在检查开始前停止）表示商店的边缘节点拒绝了扫描器本身的用户代理；无法访问表示没有收到任何响应。这两种情况都不会被报告为八项检查全部失败，但所有真实 Agent 都会遇到同样的阻碍，因此通常应优先修复边缘规则。

数据来源：在 2026 年第 3 季度对 1,867 家 Magento 商店进行的基准测试中，33.9% 的商店八项检查全部未通过；仅看 SCHEMA-01，54% 可访问的商品页面没有 Product+Offer JSON-LD。

安装

composer require expandingwebcom/module-agent-readiness
bin/magento module:enable ExpandingWeb_AgentReadiness
bin/magento setup:upgrade
bin/magento cache:flush

要求：Magento Open Source / Adobe Commerce 2.4.6 或更高版本、PHP 8.2 或更高版本、guzzlehttp/guzzle 7（已包含在 Magento 中）。模块会创建两个表：expw_readiness_scan 和 expw_readiness_daily。bin/magento module:uninstall ExpandingWeb_AgentReadiness 会删除这两个表以及所有 expw_readiness/* 配置值。

该模块可以与 Agentic Commerce Suite 一起安装——表、配置路径、路由、ACL ID 和 cron 任务不会冲突。

在管理后台中

• Marketing → AI Agent Readiness → Readiness Dashboard：以评分仪表盘显示最近一次扫描，并为每项检查显示一行结果（简短结论、严重程度，以及折叠在 Technical details 下的扫描器完整技术结论）、一个 Run scan now 按钮，以及 Agent 流量卡片。
• Stores → Configuration → ExpandingWeb → AI Agent Readiness：启用或停用计数、保留期限、每日 cron 扫描，以及 TLS 验证。

扫描会在你自己的服务器上针对默认商店视图的基本 URL 运行，从外部逐项检查——与 Agent 会执行的请求相同：/、/robots.txt、/.well-known/ucp、/llms.txt、/sitemap.xml、最多三个商品页面、分别以 GPTBot 和 ClaudeBot 身份再次请求首页，以及在某个配置文件声明了端点时执行 MCP 握手。时间预算：总计 60 秒，每次请求 5 秒，每个响应 2 MB。Cron expw_readiness_scan 会在服务器时间每天 03:15 运行；保留最近 400 次扫描。

Run scan now 为同步操作：管理后台的 POST 请求会等待扫描完成，因此 PHP-FPM 的请求超时时间需要超过 60 秒。

Agent 流量计数器的工作原理及其无法检测的内容

controller_action_predispatch 上的观察器会将请求的 User-Agent 与已知 AI Agent 令牌列表（Model/Tracking/AgentDetector：OAI-SearchBot、ChatGPT-User、GPTBot、Claude-User、Claude-SearchBot、ClaudeBot、Perplexity-User、PerplexityBot、Google-Extended、Applebot-Extended、Amazonbot、Meta-ExternalAgent、Bytespider、CCBot、Bingbot）进行匹配；匹配成功后，会在 expw_readiness_daily 中为每个 (day, agent, store view) 插入或更新一行。对于其余 99.x% 的请求，除一次子字符串扫描外，不会进行任何处理。“Day” 使用商店配置的时区。超过保留期限（默认为 400 天）的行会在每晚清理。令牌列表已编译到模块中，并随模块版本更新——要支持新 Agent，必须发布新版本，不会在运行时下载。

仪表盘会显示每个 Agent 过去 7/30/90 天的总数、与此前 30 天相比的变化，以及 14 天趋势图。

该计数是下限，而非总数，原因有两个，仪表盘会在数字旁说明：

1. 归因依据是声明的 user-agent。使用浏览器 user-agent 的 Agent 无法被检测到。
2. 观察器在 PHP 中运行。完全由 Varnish 或内置整页缓存提供的页面不会到达 PHP，因此不会统计 Agent 的缓存命中。在命中率较高的商店中，计数器主要看到缓存未命中——首次访问、未缓存的 URL，以及所有绕过缓存的请求。

如需完整统计，请在边缘层（CDN 或 Web 服务器日志）计数。本模块特意不提供边缘日志解析器。

隐私

本模块只会向你自己的商店发起请求：

• 自检会请求你自己的店面 URL（如上所列），使用的 User-Agent 为 ExpandingWebAgentReadiness/1.0.0 (+https://expandingweb.com/; readiness self-scan)。唯一例外是 MCP-01：如果你的 UCP 配置文件声明了位于其他主机的 MCP 端点，握手请求会发送到该端点——因为配置文件就是这样告知 Agent 的。
• Agent 流量计数器会读取请求的 User-Agent 标头，并将一个整数写入你自己的数据库。不会存储 IP 地址、URL 或标头。
• 扫描结果和计数保存在你的数据库中，且仅显示在你的管理后台。仪表盘中指向 Agentic Commerce Suite 的链接是一个不带参数的静态 URL——不会携带任何关于你商店的信息。

没有遥测、许可证检查、Agent 列表下载或自动回传。

让检查与公开扫描器保持同步

Model/Scanner/Scanner.php 和 Model/Scanner/UcpProfile.php 是生成的，并非手动维护：bin/port-scanner.php 会将公开扫描器的源代码（位于 expandingweb.com 仓库的 app/Agentic/Scanner.php，该仓库不公开）移植到本模块的命名空间，并将上游修订版本记录在 Model/Scanner/.upstream-hash 中。该脚本会严格应用五项有意作出的差异——命名空间和严格类型、使用 ScanHttp 替代公开扫描器中经过 SSRF 加固的客户端（此处唯一的目标是你自己的基础 URL，它可以是私有地址）、第 1 阶段按顺序而非并发获取、使用 60 秒而非 15 秒的时限（没人会等着 cron 任务），以及在 MCP clientInfo 和 robots.txt 匹配中使用扫描器自身的身份；如果上游结构发生变化，脚本就会拒绝运行。

原因就在于这个承诺：对于同一家店铺，公开扫描、基准测试和店内扫描必须给出相同的结论。每季度两次手动合并 1,800 行代码，会让这个承诺悄然失效，因此文件中带有 CI 强制执行的 DO NOT EDIT BY HAND 标记。发现某项检查行为异常？请提交问题，并提供触发该问题的店铺结构；修复会先合并到上游，然后重新移植。请参阅 CONTRIBUTING.md。

本模块不包含的内容

商家 Feed 联合分发（OpenAI、Perplexity、Google Merchant Center）、Product/Offer/ProductGroup JSON-LD 修复、Agent 端点（/llms.txt、/.well-known/ucp、MCP 服务、Agent 产品 Feed、结账会话）、Agent 漏斗和收入风险分析、AI 可见度与声量份额探测以及竞争对手分析，均属于付费层：Agentic Commerce Suite。本模块负责诊断；Suite 负责修复。

面向 Agent 和 MCP 客户端

Expanding Web 自有的 MCP 服务列于官方 MCP 注册表：com.expandingweb/agentic-commerce-readiness（扫描店铺、读取商品报价、开启结账会话）和 com.expandingweb/nord-trail-store（可供查看的参考级 Agent 就绪店面）。两者都通过 POST 使用 JSON-RPC 2.0，与本模块的检查预期在商家店铺上发现的形式相同。

开发

ln -s /path/to/agent-readiness app/code/ExpandingWeb/AgentReadiness
bin/magento module:enable ExpandingWeb_AgentReadiness && bin/magento setup:upgrade

测试、静态分析和编码规范：请参阅 CONTRIBUTING.md。版本历史：CHANGELOG.md。