seo-sitemaps

seo-sitemaps (M17)

站点地图是交给爬虫的发现契约——其中应该且只能列出规范的、可编入索引的 URL。相关标记的 Schema 规则：references/schema-tier1.md。

输入

根据调度信封中指定的 PageSnapshot 开展工作：从 <run_dir>/pages/<slug>.json 读取 parsed，并读取 <run_dir>/site/sitemaps.json（以及 site/sitemap-urls.txt）、<run_dir>/site/robots.json 和 <run_dir>/crawl.json，用于孤立页面核对和逐 URL 状态检查；对 pages/<slug>.html 使用 Grep 查找原文证据。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），以及 site/sitemaps.json 和 site/robots.json 开展工作：

1. 存在性与有效性：定位 XML 站点地图（/sitemap.xml、robots 中的 Sitemap: 行、站点地图索引）；根据 sitemaps.org Schema 将其解析为格式正确的 XML。
2. 大小限制：每个站点地图不得超过 50,000 个 URL，且解压后不得超过 50MB；如果超出，应使用站点地图索引拆分 URL 集合。
3. 扩展项：在适用时，验证 image:、video: 和 news: 命名空间条目（声明了正确的命名空间，且包含必需的子元素）。
4. lastmod 准确性：<lastmod> 必须是有效的 ISO 8601 格式，并反映实际的最后修改时间，而非每个 URL 都使用构建时间戳（这会让爬虫逐渐忽略该字段）。
5. robots 引用：robots.txt 中至少有一行绝对路径的 Sitemap:。
6. 站点地图与规范 URL 一致性：站点地图中的 URL 不得为 noindex、重定向、4xx/5xx 或非规范 URL（只能是自引用规范 URL）。与 M-indexability 交叉核对可编入索引状态。
7. 孤立页面核对：将站点地图 URL 与内部链接图进行比对——标记未出现在站点地图中的可编入索引页面，以及无法通过内部链接访问的站点地图 URL。

修复

• AUTO：生成或修复 XML 站点地图条目（使用正确的 <loc>，根据观测到的最后修改数据填写准确的 <lastmod>，并在存在媒体时添加有效的 image:/video: 扩展子元素），并在 robots.txt 中添加绝对路径的 Sitemap: 行。这些是供 fix 使用的增量式、确定性差异。
• PROPOSED：移除或拆分条目（例如，删除非规范 URL/noindex URL，或将其分片到站点地图索引中）——起草后逐项接受。
• ADVISORY：更改全站 lastmod 策略或规范 URL 决策——提供说明，绝不由工具写入。
• 绝不捏造 lastmod 时间、媒体 URL 或规范目标——应从观测数据中获取、询问用户，或根据 Schema 的 fixable 契约留下清晰标记的 TODO 占位符。

验证

• 从本次运行中读取（不联网）：读取 <run_dir>/site/sitemaps.json 和 <run_dir>/site/robots.json——爬取过程已经遍历索引、跟进 gzip 子文件，并记录了每个文件的错误。
• 重新抓取：node "${CLAUDE_PLUGIN_ROOT}/scripts/parse-robots-sitemap.mjs" --url <final_url> [--max-sitemaps 50] [--max-urls 100000] [--no-well-known]——xml_parse 方法会解析 robots.txt 和所有声明及探测到的站点地图，并检查格式正确性、大小上限、命名空间/扩展项有效性，以及规范 URL/noindex 一致性断言。--sitemap <sitemap url> 用于指定单个文件，--file <robots.txt> [--path /x] 用于解析离线 robots 文件。此脚本没有 --snapshot 模式：站点地图是站点级资源，不是页面快照。
• 当所需数据层（实时抓取站点地图/robots，或已解析的链接图）不可用时，状态为 needs_api——绝不能错误地判定为 pass。

检查结果

按 schema/finding.schema.json 输出检查结果。示例：

• M17.sitemap.missing — 在 /sitemap.xml 或 robots.txt 中未找到 XML 网站地图（状态为 fail，严重级别 3，fixable: auto，维度为 search，置信度为 established）。
• M17.robots.no_sitemap_line — 网站地图存在，但 robots.txt 中没有 Sitemap: 行（状态为 warn，严重级别 3，fixable: auto，维度为 search，置信度为 established）。
• M17.sitemap.noindex_url — 网站地图中的 <loc> 指向 noindex/非规范 URL（状态为 fail，严重级别 3，fixable: proposed，维度为 search，置信度为 established）。
• M17.sitemap.error_url — 爬取程序获取的网站地图中的某个 <loc> 返回了 4xx/5xx（状态为 fail，严重级别 3，fixable: proposed，维度为 search，置信度为 established）。
• M17.sitemap.redirected_url — 网站地图中的某个 <loc> 发生了重定向，而非直接返回最终 URL（状态为 warn，严重级别 3，fixable: proposed，维度为 search，置信度为 established）。
• M17.sitemap.missing_indexable_url — 爬取程序发现的某个可编入索引的 URL 未列入任何网站地图（状态为 warn，严重级别 3，fixable: proposed，维度为 search，置信度为 directional — 即某个链接充分的页面未通过网站地图被发现）。
• M17.sitemap.lastmod_identical — 每个 <loc> 都带有相同的 <lastmod>，因此无法通过该文件区分已更改的页面和未更改的页面（状态为 warn，严重级别 2，fixable: advisory，维度为 search，置信度为 directional）。 只有爬取程序实际获取的 <loc> 条目才会生成逐 URL 判定；从未访问过的 URL 不会被报告，而不是靠猜测补充。若本次运行未执行网站地图发现（--artifacts none / --no-sitemaps），M17.sitemap.missing 也会以 needs_api 状态输出；这与“网站地图不存在”是两回事。 依平台触发的 ID。 仅当 profile.json 指定了平台（shopify、wordpress、nextjs、nuxt、astro、gatsby、hugo）时，此模块才会输出另外 8 个 ID。它们列于 references/routing.md § 平台条件检查结果 ID，并在 references/platforms/<id>.md §10 中有详细说明。

每条检查结果：evidence.observed 会逐字引用页面/网站地图内容；verification.reproduce 是上文可运行的命令；expected_impact 按级别划分并标注置信度（不会只给出百分比）。

诚实性

• 网站地图是辅助发现的工具，不是排名信号，也不保证页面会被编入索引 — Google 将 <lastmod>、<priority> 和 <changefreq> 视为提示，并且基本忽略 <priority>/<changefreq>，因此不要承诺调整这些值能提升排名（此类策略应标注为低幅度/方向性）。
• 提交网站地图不会强制将低质量或非规范页面编入索引；相比网站地图大小，孤立页面和规范 URL 的规范性更重要。