seo-agent-readiness

seo-agent-readiness（M22 — Agent 就绪度）

Google 的 Optimizing your website for generative AI features 指南指向“面向 Agent 的网站最佳实践”（web.dev Build agent-friendly websites）：Agent 通过页面的无障碍树操作页面，因此，未命名、非语义化或仅由脚本控制的控件对它们来说不可见。本模块会检查其中可静态检查的部分，并指出其余部分。替代文本属于 M9，锚文本质量属于 M10，渲染属于 M4——引用这些模块，绝不要重复输出其内容。

输入

根据调度信封中指定的 PageSnapshot 操作：从 <run_dir>/pages/<slug>.json 读取 parsed（anchors[]、forms、iframes、scripts[]、landmarks）；当 render.used 不为 none 时，优先使用 parsed_rendered；对 pages/<slug>.html（或 .rendered.html）执行 Grep，将问题元素作为原文证据。audit.mjs 已输出的确定性发现列在 <run_dir>/findings.deterministic.json 中——不要重复输出这些 ID；仅添加由模型判断的发现。如果直接使用 URL/路径调用且不存在快照，请先运行 node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"，并使用打印出的快照路径。

审计

1. 语义化控件——在 div/span 上实现交互行为（使用 onclick、role="button"、tabindex + 处理程序），而不是使用 <button> / <a href>；计入控件总数。
2. 已命名的按钮——没有文本内容、aria-label、aria-labelledby、title 或 value 的 <button>、role="button"、input[type=button|submit]。
3. 已命名的链接——可访问名称为空的 <a href>（仅图标、内部包含没有 alt 的图片）。通用与描述性锚文本的区分归 M10 处理。
4. 带标签的表单控件——缺少 <label for>、外层 <label>、aria-label 或 aria-labelledby 的 input/select/textarea（仅有占位符不算）。
5. href="javascript:"（以及带处理程序的 href="#"）——只能通过脚本实现的导航。
6. iframe 中的主要内容——主要文章/产品内容位于 <iframe> 中；Agent 和爬虫只能看到外层页面。
7. WebMCP——在内联/链接脚本中检查 navigator.modelContext：如存在则作为信息性内容报告。这是 W3C 社区组草案（2026-04-23），目前处于 Chrome origin trial 阶段——绝不要将其作为建议。
8. 无法静态检查——cursor: pointer、目标尺寸（web.dev 建议 > 8px²）、透明覆盖层 / 屏幕外点击拦截器。请明确列为 not_checkable_static；Tier 1 通过 Lighthouse 的“Agentic browsing”类别（M150+）涵盖这些内容。

修复

• PROPOSED（fixable: proposed）：将 div[onclick] 替换为 <button type="button">，为未命名控件添加 aria-label/可见文本，为表单控件添加 <label for>，将 href="javascript:" 替换为真实 URL 或 <button>——按项提供差异，因为这些修改会涉及模板和事件绑定。
• ADVISORY（fixable: advisory）：将主要内容移出 iframe、修改框架组件、处理覆盖层/目标尺寸问题、采用 WebMCP。
• 绝不臆造周边内容无法佐证的标签或链接文本——请保留清晰标注的 TODO 占位符，或提出询问。

验证

• node "${CLAUDE_PLUGIN_ROOT}/scripts/agent-readiness.mjs" --snapshot <pages/<slug>.json>——列出每项检查的计数及问题元素（方法为 dom_assert）。
• Tier 1，需用户同意（请先询问——此操作会下载并启动浏览器）：npx lighthouse <url> --output=json --output-path <run_dir>/lighthouse.json，并读取 agentic-browsing 类别（类别 ID 需根据已安装的 Lighthouse 版本核实）。仅在用户同意且 Chrome 可用时运行；否则 M22.lighthouse.agentic_browsing 保持 needs_api。
• 当页面由客户端渲染但未渲染时（render.needed && render.used === "none"），控件检查只针对外层页面运行：说明此限制；若外层页面为空，则保留 needs_api。

发现

符合 schema/finding.schema.json；轴为 ai；每个 ID 的置信度均为 directional；严重程度 ≤3。严重程度政策：5 仅用于网站/模板级别的灾难性、会导致失去资格的事实；4 重大 · 3 中等 · 2 轻微 · 1 表面 · 0 信息性——且只有活动类别中 established 的严重程度为 5 的 fail 才能封顶评分（references/scoring-model.md）。M22 中没有任何内容是 established，因此这里没有任何内容会封顶评分。evidence.observed 原样引用元素（选择器 + 外层标签），verification.reproduce 是上面的命令，expected_impact 按等级区间表示（不得只给出百分比）。

• M22.controls.non_semantic_interactive — div/span 点击处理程序充当控件（warn 3；当这类控件占多数或用于触发主要操作时为 fail 3；fixable: proposed）。
• M22.controls.button_without_name（warn 2，fixable: proposed） · M22.links.empty_name（warn 2，fixable: proposed） · M22.links.href_javascript（warn 2，fixable: proposed）。
• M22.forms.unlabeled_controls（warn 3，fixable: proposed） · M22.content.iframe_primary（warn 2，fixable: advisory）。
• M22.lighthouse.agentic_browsing（严重程度 3；除非已运行需经同意的测试，否则为 needs_api；测试完成后根据评分给出 pass/warn/fail）。
• M22.static.not_checkable（not_applicable，严重程度 0——列出光标/目标尺寸/遮罩项和 Tier 1 路径） · M22.semantics.ok（pass 3——控件、名称和标签均无问题）。
• M22.webmcp.present（pass，严重程度 0，信息性——仅报告是否存在）。

诚信

• Agent 就绪度仅为 方向性判断：Google 推荐适合 Agent 使用的做法；没有供应商记录过排名或引用效果。绝不标为 established，绝不使用严重程度 4–5，也绝不封顶评分。
• 这些主要是可访问性基础（名称 / 角色 / 值），只是有了新的使用者；应将修复描述为同时消除辅助技术和 Agent 的使用障碍，而不是“AI SEO”。
• Lighthouse 的 Agentic 类别属于实验室工具；绿色评分不能证明 Agent 已在页面上完成任务。WebMCP 是起源试验阶段的草案——报告其是否存在，不提出建议。