claude-seo 索引状态报告：基于 Google Search Console URL Inspection API 的批量索引审计模板与实战指南

导读

本文围绕 claude-seo 项目中用于生成 URL 索引状态报告的官方模板（skills/seo-google/assets/templates/indexation-status-report.md）展开，说明该模板如何承接 Search Console URL Inspection API 的实时数据，将"URL 是否被 Google 索引"这一核心事实结构化为可读、可交接、可归档的报告。读完本文，你将掌握从批量 URL 检查（gsc_inspect.py）到索引报告生成（google_report.py --type indexation）的完整调用链，理解 PASS/FAIL/NEUTRAL 判定、canonical 冲突、常见索引问题等字段的业务含义，并能直接套用模板产出标准化的索引审计报告。

一、模板定位：把"索引事实"变成可交付报告

在 SEO 工作流中，"某个 URL 到底有没有被 Google 索引"是一个必须由 Google 官方数据回答的问题。claude-seo 的 seo-google 技能用 Search Console URL Inspection API 获取这一事实，而本模板则负责把 API 返回的原始 JSON 转译为人类可读的 Markdown 报告。

模板的核心数据流是：

1. 通过scripts/gsc_inspect.py对单条或批量 URL 发起 URL Inspection 请求；
2. 拿到包含verdict（PASS/FAIL/NEUTRAL 等）、coverage state、canonical、rich results 的结构化结果；
3. 按本模板的六个区块（Summary、Detailed Results、Canonical Mismatches、Common Issues、Rich Results Detected）组织输出；
4. 可选地交给scripts/google_report.py --type indexation生成带环形图（donut chart）的 PDF 报告。

技能文档在 skills/seo-google/SKILL.md 中明确了一个重要原则：Sitemaps 只能告诉你"提交了多少 URL"，URL Inspection API 才是索引状态的"事实来源"（indexation truth）。本模板正是这一原则在交付层的落地——它记录的不是"我们提交了多少"，而是"Google 实际收录了多少"。

二、模板骨架逐节解析

模板全文共 42 行，结构紧凑，共六个数据区块外加页脚。下面逐节说明其业务含义与填写方式。

1. 头部元信息

**Property:** {property} **URLs Inspected:** {total_urls}

• Property：被检查的 Search Console 资源，格式为sc-domain:example.com或https://www.example.com/。gsc_inspect.py在未显式传--site-url时，会从配置文件~/.config/claude-seo/google-api.json的default_property字段读取（见 scripts/gsc_inspect.py）。
• URLs Inspected：本批次实际检查的 URL 总数。需要特别注意批量上限：gsc_inspect.py中定义了DAILY_LIMIT = 2000，超过该数量的批次会被截断并给出警告（见 scripts/gsc_inspect.py）。

2. Summary 汇总表

这四类统计与gsc_inspect.py中batch_inspect()的 summary 逻辑一一对应（见 scripts/gsc_inspect.py）：

• Indexed (PASS)：API 返回的verdict == "PASS"，即该 URL 已被 Google 索引；
• Not Indexed (FAIL)：verdict == "FAIL"，未被索引，需在 Detailed Results 中定位原因；
• Neutral：verdict为NEUTRAL或其他非 PASS/FAIL 值（如VERDICT_UNSPECIFIED、PARTIAL）；
• Errors：请求本身失败（权限不足、限流、URL 不属于该资源等），此时inspection.get("error")非空。

Percentage 建议按count / total_urls * 100计算并保留一位小数。在 PDF 生成端，google_report.py还会额外给出索引率（Index Rate），并按阈值着色：≥90% 显示为 success-box（绿色），70%–90% 为 highlight，低于 70% 为 critical-box（红色），实现一眼判断健康度（见 scripts/google_report.py）。

3. Detailed Results 明细表

这是全报告信息密度最高的表。每一行对应gsc_inspect.py中inspect_url()返回的一个结果对象，其字段直接映射到 URL Inspection API 的indexStatusResult（参见 skills/seo-google/references/search-console-api.md）：

gsc_inspect.py还会解析robotsTxtState（ALLOWED/DISALLOWED）、indexingState（INDEXING_ALLOWED/BLOCKED_BY_META_TAG/BLOCKED_BY_HTTP_HEADER）、crawledAs（DESKTOP/MOBILE）与referringUrls，这些字段在排查 FAIL 时可作为辅助证据（见 scripts/gsc_inspect.py）。

4. Canonical Mismatches 冲突清单

此区块专门列出用户声明的 canonical 与 Google 选定的 canonical 不一致的 URL。判定逻辑在gsc_inspect.py中实现：match = googleCanonical == userCanonical，当两边都非空且不相等时即为冲突（见 scripts/gsc_inspect.py）。

Canonical 冲突通常是以下原因之一：

• 页面声明的 canonical 指向 301 重定向链路的中间跳；
• 两个页面互相声明对方为 canonical（循环引用）；
• 站点未声明 canonical，Google 自行推断（此时 userCanonical 可能为空，需在报告中标注为 N/A 并人工核对）；
• 参数化 URL 处理不当，导致 Google 合并了不同的 URL 变体。

冲突列表应单独成表，因为它在优先级上高于一般的 FAIL 明细——即使一个 URL 已通过 PASS，canonical 错误也可能导致流量和排名信号流向错误的页面。

5. Common Issues 问题聚合表

该表把 Detailed Results 中的 FAIL 按根因聚合。建议从以下维度归类（与 URL Inspection API 返回的状态字段对应）：

Priority 字段建议使用 High / Medium / Low 三级：能直接解释大量 FAIL 的根因（如全站 noindex）为 High，偶发的抓取错误为 Medium，单一页面问题为 Low。

6. Rich Results Detected 富结果清单

此区块来自 API 的richResultsResult对象。gsc_inspect.py会解析detectedItems，输出每个检测到的富结果类型（如 FAQPage、HowTo、Product 等）及其包含的条目与问题列表（见 scripts/gsc_inspect.py）。这可以帮助你判断结构化数据是否真正被 Google 识别，而不仅是"验证通过"。

7. 页脚：数据边界与时效

*URL Inspection API: 2,000 inspections/day per site, 600/min.* *Generated {timestamp} via Google Search Console URL Inspection API.*

页脚是报告严谨性的体现：

• 明确数据来源为 GSC URL Inspection API；
• 提示配额边界：每站点每天 2,000 次、每分钟 600 次。更完整的配额表见 skills/seo-google/references/rate-limits-quotas.md（项目级上限为 10,000,000 QPD / 15,000 QPM，可在多个站点间共享）；
• 记录生成时间戳，方便日后对比多轮审计结果，观察索引状态随时间的变化。

三、数据生产链路：从命令到模板的完整调用链

模板不是手工填写的，而是由命令链自动产出的。完整的链路如下：

步骤 1：单条检查（用于快速验证）

python3 scripts/gsc_inspect.py https://example.com/page --json

不带--site-url时会读取配置中的default_property。单条模式的终端输出会展示 Verdict、Coverage、Robots.txt、Indexing、Page Fetch、Last Crawl、Canonical 及 Rich Results 等信息（见 scripts/gsc_inspect.py）。

步骤 2：批量检查（用于生成报告）

python3 scripts/gsc_inspect.py --batch urls.txt --site-url sc-domain:example.com --json > inspect-data.json

批量模式要求urls.txt每行一个 URL。脚本内置两层保护：

• 日配额截断：超过 2,000 个 URL 时自动截断并告警；
• 节流延迟：默认每次请求间隔delay=1.0秒（可用--delay调整），把请求速率压到 600 QPM 限值以内（见 scripts/gsc_inspect.py）。

批量结果 JSON 中的summary字段结构为{pass, fail, neutral, error}四个计数，正是模板 Summary 表的数据来源。

步骤 3：生成 PDF 报告（可选增强）

python3 scripts/google_report.py --type indexation --data inspect-data.json --domain example.com

google_report.py的indexation报告类型会渲染一个"Indexation Status"章节（见 scripts/google_report.py），包括：

• 由chart_index_status()生成的索引状态环形图，四象限配色（绿=Indexed、红=Not Indexed、灰=Neutral、暗=Error），中心标注 URL 总数（见 scripts/google_report.py）；
• Indexed / Not Indexed 两张指标卡（metric card）；
• 索引率及分级着色提示；
• 逐 URL 结果表（URL、Verdict、Coverage State、Last Crawl）。

技能层面对应命令为/seo google inspect-batch <file>与/seo google report indexation，完整工作流参见 skills/seo-google/SKILL.md 的 Reports 一节。

四、判定口径与字段语义：为什么不能只看 Verdict

报告的价值在于"可解释的失败"，而不仅是"失败的个数"。模板的 Detailed Results 表保留 Coverage State 与 Fetch State 两列，正是为了区分以下常见场景：

1. FAIL + Blocked by robots.txt：不是内容问题，是抓取策略问题；
2. FAIL + Soft 404：页面存在但返回 200，内容不足以被识别为有效页面；
3. FAIL + Crawled - currently not indexed：Google 已抓取但认为质量/权重不足，需要内容与外链层面提升；
4. FAIL + Server error：纯技术故障，修复服务器即可；
5. NEUTRAL：判定未明确（如刚提交或正在处理），不应等同于失败。

这些区分直接决定 Common Issues 表中 Action 列的写法。只有把 Verdict 与 Coverage State / Fetch State 组合阅读，报告才能指导下一步具体操作，而不是停留于"有 N 个 URL 没被收录"。

另一个容易误读的点：CrUX 的 404 与 URL Inspection 的 404 语义不同。URL Inspection 的NOT_FOUND表示 URL 本身返回 404；而 CrUX API 的 404 表示流量不足、无数据——两者不要混用（参见 skills/seo-google/SKILL.md 的 Technical Notes）。

五、配额、认证与错误处理：保证审计跑得完、跑得准

认证前置条件

URL Inspection API 需要服务账号（Service Account）而非仅 API Key，对应 seo-google 技能的 Tier 1。认证步骤见 skills/seo-google/references/auth-setup.md：创建 GCP 项目 → 启用 Google Search Console API → 创建服务账号 → 在 GSC 的"设置 > 用户和权限"中添加服务账号的client_email（读权限设为 Full 即可，使用 Indexing API 才需要 Owner）。

配额约束速查

"Per site" 与 "Per project" 的差别很关键：2,000/天是按 GSC 资源维度计算，10M/天是按 GCP 项目维度共享。如果你的 GCP 项目下有多个 GSC 资源，总额度是 10M，但每个站点单独受 2,000/天约束（见 skills/seo-google/references/rate-limits-quotas.md）。

常见错误与处理

gsc_inspect.py对三类高频错误做了内建识别（见 scripts/gsc_inspect.py）：

碰到 429 时，若响应头带Retry-After则以其值为准；批量脚本默认的 1 秒delay已经考虑了 QPM 上限，日常 2,000 以内的审计通常不会触雷。

六、Sitemaps 与 URL Inspection 的分工：避免报告口径错乱

模板页脚只引用 URL Inspection API，这是有意为之。seo-google 技能和对应测试（tests/test_gsc_query.py）反复强调一个口径问题：

• Sitemaps API只能返回submitted（提交数量）、errors、warnings等，反映的是"提交动作"而非"收录结果"；
• URL Inspection API返回的是 Google 当前的索引判定，是唯一的索引事实来源。

因此，一套严谨的索引审计应该双轨并用：先用/seo google sitemaps <property>查看提交状态与报错，再用inspect-batch对关键 URL 逐一核实真实收录情况。报告中不要混用两种口径——Sitemap 的"已提交"不等于"已索引"，这正是本模板把 Summary 严格限定在 PASS/FAIL/NEUTRAL/Errors 四类的原因。

七、实战工作流：一套可复用的索引审计 SOP

综合模板与源码，一套完整的索引审计流程如下：

1. 准备 URL 清单：导出站点的核心页面、新增页面、疑似问题页面，写入urls.txt（每行一个，去重），控制在 2,000 个以内；
2. 确认认证：python3 scripts/google_auth.py --check --json验证服务账号可用；
3. 批量检查：python3 scripts/gsc_inspect.py --batch urls.txt --json > inspect-data.json；
4. 按模板整理报告：将 JSON 中的summary填入 Summary 表，将results展开为 Detailed Results 表，从canonical.match == False的记录生成 Canonical Mismatches 表，按根因聚合 FAIL 生成 Common Issues 表，从rich_results.detected_items生成 Rich Results 表；
5. 生成 PDF（可选）：python3 scripts/google_report.py --type indexation --data inspect-data.json --domain example.com，获得带环形图的可交付报告；
6. 归档与对比：按 skills/seo-google/SKILL.md 的约定保存为GOOGLE-API-REPORT-{domain}.md，留存时间戳以便与下一轮审计对比。

八、模板的扩展方向

• 按页面类型拆分：对每个 URL 标注页面类型（首页/品类页/文章页），在 Summary 之外再输出按类型分组的索引率，帮助定位"哪类页面未被收录"；
• 与 CWV 数据联动：seo-google 技能同时具备 PageSpeed/CrUX 数据能力，可在报告中对"已索引但性能差"的 URL 附加 Core Web Vitals 状态，形成"索引 + 体验"复合审计；
• 问题自动分类脚本：当前 Common Issues 的归类仍以人工/Agent 判断为主，可以基于coverageState、pageFetchState、robotsTxtState的组合编写聚合逻辑，将模板中的 Issue/Count/Priority/Action 全自动生成。

结语

indexation-status-report 模板虽短，却是 seo-google 技能中"索引审计"能力的交付骨架：上游对接 URL Inspection API 的实时判定，下游支撑google_report.py的 PDF 可视化，中间以 PASS/FAIL/NEUTRAL/Errors 四分类、canonical 冲突与富结果三个视角组织证据。无论你是用它做一次性批量审计，还是把它固化为周期性索引健康度巡检的标准报告，都可以直接以本模板为起点，配合gsc_inspect.py与google_report.py快速落地一套可追溯、可对比、可交接的索引状态报告体系。