seo-google

Google SEO APIs

直接访问 Google 自有的 SEO 数据。弥合基于爬取的分析（现有 claude-seo skills）与 Google 实时实测数据之间的差距：真实的 Chrome 用户指标、实际索引状态、搜索表现和自然流量。

所有 API 均免费。设置需要 Google Cloud 项目以及 API 密钥和/或服务账号——运行 /seo google setup 查看分步说明。

前置条件

执行任何命令前，请先检查凭据：

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run google_auth.py --check --json

配置文件：~/.config/claude-seo/google-api.json

{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "<GOOGLE_API_KEY>",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}

如果文件缺失，请阅读 references/auth-setup.md，并引导用户完成设置。

凭据等级

等级	检测条件	可用命令
0（API Key）	存在 api_key	pagespeed、crux、crux-history、youtube、nlp
1（OAuth/SA）	+ OAuth token 或 service account	等级 0 + gsc、inspect、sitemaps、index
2（完整）	+ 已配置 ga4_property_id	等级 1 + ga4、ga4-pages
3（Ads）	+ ads_developer_token + ads_customer_id	等级 2 + keywords、volume

运行命令前，务必告知检测到的等级。

快速参考

命令	功能	等级
/seo google setup	检查/配置 API 凭据	--
/seo google pagespeed <url>	PSI Lighthouse + CrUX 实测数据	0
/seo google crux <url>	仅 CrUX 实测数据（p75 指标）	0
/seo google crux-history <url>	25 周 CWV 趋势分析	0
/seo google gsc <property>	Search Console：点击次数、展示次数、CTR、排名	1
/seo google inspect <url>	URL 检查：索引状态、规范网址、爬取信息	1
/seo google inspect-batch <file>	从文件批量检查 URL	1
/seo google sitemaps <property>	GSC 站点地图状态	1
/seo google index <url>	向 Indexing API 提交 URL	1
/seo google index-batch <file>	批量提交最多 200 个 URL	1
/seo google ga4 [property-id]	GA4 自然流量报告	2
/seo google ga4-pages [property-id]	自然流量排名靠前的落地页	2
/seo google youtube <query>	YouTube 视频搜索（观看次数、点赞数、时长）	0
/seo google youtube-video <id>	YouTube 视频详情 + 热门评论	0
/seo google nlp <url-or-text>	NLP 实体提取 + 情感分析 + 分类	0
/seo google entities <url-or-text>	仅实体分析（用于 E-E-A-T）	0
/seo google keywords <seed>	使用 Google Ads Keyword Planner 获取关键词创意	3
/seo google volume <keywords>	使用 Keyword Planner 查询搜索量	3
/seo google entity <query>	Knowledge Graph 实体检查	0
/seo google safety <url>	Web Risk URL 安全检查	0
/seo google quotas	显示所有 API 的速率限制	--

---

PageSpeed + CrUX

/seo google pagespeed <url>

结合 Lighthouse 实验室数据 + CrUX 实测数据。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run pagespeed_check.py <url> --json 参考： references/pagespeed-crux-api.md（Core Web Vitals 阈值：references/crux-history-api.md） 请根据输出中的 lighthouse_version 字段报告 Lighthouse 版本，不要假定为最新版本。 默认： 同时采用移动设备 + 桌面设备策略，包含所有 Lighthouse 类别。

输出将实验室评分（Lighthouse 某一时点的数据）与实测数据（28 天的 Chrome 用户指标）合并。CrUX 会优先尝试 URL 级数据，失败时回退到来源级数据。

/seo google crux <url>

仅获取 CrUX 实测数据（不运行 Lighthouse）。速度更快。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run pagespeed_check.py <url> --crux-only --json

/seo google crux-history <url>

25 周的 CrUX 历史趋势。显示 CWV 指标是在改善、保持稳定还是恶化。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run crux_history.py <url> --json 参考： references/crux-history-api.md

输出包含各项指标的趋势方向、变化百分比和每周 p75 值。

---

Search Console

/seo google gsc <property>

Search Analytics：过去 28 天的点击次数、展示次数、CTR 和排名。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run gsc_query.py --property <property> --json 参考： references/search-console-api.md 默认值： 28 天，维度为 query、page，类型为 web，限制为 1000。

对于欧盟网站，在解读 CTR 或 GA4 数据下降前，请先阅读 references/dma-consent-mode-v2.md：DMA 和 Consent Mode v2 会改变 Search Console 和 GA4 记录的数据。

包含快速见效机会检测：展示次数较高且排名在 4-10 的查询。 totals 区块来自单独的无维度汇总查询，因为查询级别的行可能会遗漏匿名化的低流量数据。仅当 totals_complete 为 true 时，才应将汇总视为全站数据。--limit 限制返回的维度行总数，而不是每次分页请求的数量。

GSC 中的 AI 展示（2026）：

• 生成式 AI 性能报告（于 2026-06-03 发布），专门展示 AI Overviews + AI Mode 的可见度。仅包含展示次数（不包含点击次数、CTR、排名或查询）；维度包括页面、国家/地区、设备和日期（太平洋时间）；限制为 1,000 行；最新数据为初步数据；另有单独的 Discover 生成式 AI 报告。自 2026-08-31 起，全球所有网站均可使用（于 2026-06-03 起向部分网站推出）；日期支持小时、日、周和月粒度。
• 多模态搜索类型（自 2026-09-24 起在全球逐步推出）：Search results 和 Generative AI performance 报告中的筛选条件，涵盖来自 Lens、Circle to Search、图片上传和 Chrome“搜索此图片”的访问，可从界面导出。尚未验证其对应的 Search Analytics API type 值，因此不要臆造。
• AI Mode 已计入标准效果总量（Web 搜索类型），点击次数（AI Mode 中的外部链接点击）和展示次数均计入常规报告，因此无法从总量中清晰区分“传统”流量和“AI”流量。要查看仅包含展示次数的 AI 可见度，请使用生成式 AI 报告。
• 数据可靠性注意事项： GSC 日志记录错误导致 2025-05-13 至 2026-04-27 期间的展示次数、CTR 和平均排名不可靠（点击次数不受影响；修复仅对后续数据生效，不会回填）。对跨越该时间段的展示次数、CTR 和排名趋势应谨慎解读；修复后预计会出现展示次数明显下降。

平台属性（2026）： Search Console 可将经过验证的 TikTok、 Instagram、X 和 YouTube 账号作为独立属性显示。除非已通过认领的 Search 个人资料添加账号，否则请分别验证每个账号。仅将这些属性用于 Google 搜索效果分析，不要将其用作平台自带分析工具的替代品。来源： developers.google.com/search/docs/monitor-debug/analyze-social-video-content

/seo google inspect <url>

URL Inspection：来自 Google 的真实索引状态。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run gsc_inspect.py <url> --json

返回：判定结果（PASS/FAIL）、覆盖状态、robots.txt 状态、索引状态、 页面抓取状态、规范网址选择和富媒体搜索结果。（API 中的 mobileUsabilityResult 已弃用； 不要将其报告为移动设备可用性检查。）

/seo google inspect-batch <file>

从文件批量检查（每行一个 URL）。每个网站每天最多 2,000 次。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run gsc_inspect.py --batch <file> --json

/seo google sitemaps <property>

列出已提交的网站地图及其状态、错误和警告。网站地图内容报告只显示已提交的数量；对于特定 URL 是否已编入索引，应以 URL Inspection API 为准。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run gsc_query.py sitemaps --property <property> --json

---

索引编入 API

/seo google index <url>

通知 Google 某个 URL 已更新。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run indexing_notify.py <url> --json 参考： references/indexing-api.md

Indexing API 的官方适用范围是 JobPosting 和 BroadcastEvent/VideoObject 页面。务必告知用户此限制。每日配额：200 次发布请求。

/seo google index-batch <file>

从文件中批量提交 URL。跟踪配额使用情况。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run indexing_notify.py --batch <file> --json

---

GA4 流量

/seo google ga4 [property-id]

自然流量报告：每日会话数、用户数、页面浏览量、跳出率和互动度。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run ga4_report.py --property <id> --json 参考： references/ga4-data-api.md 默认值： 最近 28 天，筛选为自然搜索渠道组。

GA4「AI Assistants」渠道（约于 2026-05-13 上线）： GA4 新增了原生的 AI Assistants 默认渠道组。来自已识别 AI 助手的引荐会话会获得 medium=ai-assistant。Google 识别的来源包括 ChatGPT、Gemini、Claude、Deepseek、Copilot、Grok，且该渠道不包括 Google AI Overviews / AI Mode。如有需要，请单独核实 Perplexity；不受支持的来源可能仍归入 Referral，而且大多数 AI 会话没有引荐来源，因而会归入直接流量，所以此渠道会低估 AI 流量。仅向前生效，不会回填历史数据。

/seo google ga4-pages [property-id]

按会话数排序的自然流量热门落地页。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run ga4_report.py --property <id> --report top-pages --json

---

YouTube（视频 SEO）

一些第三方研究报告称，YouTube 提及次数与 AI 可见度之间的相关性为 0.737。请将其视为取决于研究方法的信号。免费使用，仅需 API 密钥。

/seo google youtube <query>

搜索 YouTube 视频。返回标题、频道、观看次数、点赞数和时长。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run youtube_search.py search "<query>" --json 参考： references/youtube-api.md 配额： 每次搜索 100 个单位（免费额度为每天 10,000 个单位）。

/seo google youtube-video <video_id>

视频详细信息、标签和前 10 条评论。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run youtube_search.py video <video_id> --json 配额： 2 个单位（视频详情 + 评论）。

---

NLP 内容分析

用于内部内容质量检查的 Google NLP 实体/情感分析结果。不要将其视为 Google E-E-A-T 评分。

/seo google nlp <url-or-text>

完整 NLP 分析：实体、情感和内容分类。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run nlp_analyze.py --url <url> --json 或 --text "..." 参考： references/nlp-api.md 免费额度： 每月 5,000 个单位。需要在 GCP 项目中启用结算功能。

/seo google entities <url-or-text>

仅提取实体（速度更快，配额消耗更少）。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run nlp_analyze.py --url <url> --features entities --json

---

关键词研究（Google Ads）

黄金标准的关键词搜索量数据。需要 Google Ads 账号。

/seo google keywords <seed>

根据种子词生成关键词创意。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run keyword_planner.py ideas "<seed>" --json 参考： references/keyword-planner-api.md 需要： 配置中提供 Ads 开发者令牌和客户 ID（Tier 3）。

/seo google volume <keywords>

查询指定关键词的搜索量（以逗号分隔）。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run keyword_planner.py volume "<kw1>,<kw2>" --json

---

补充功能

/seo google entity <query>

检查知识图谱实体。验证品牌是否存在。

参考： references/supplementary-apis.md 使用 Knowledge Graph Search API，并需要 API 密钥。

/seo google safety <url>

使用 Web Risk API 检查是否存在恶意软件／社会工程标记。

参考： references/supplementary-apis.md

/seo google quotas

显示速率限制表。读取 references/rate-limits-quotas.md。

---

报告

执行任何分析命令后，提供生成 PDF/HTML 报告的选项。

/seo google report <type>

生成包含图表和分析数据的专业 PDF 报告。

脚本： "${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run google_report.py --type <type> --data <json> --domain <domain> --format pdf

类型	输入	输出
cwv-audit	PSI + CrUX + CrUX History 数据	包含仪表盘、时间线、分布图的 Core Web Vitals 审计
gsc-performance	GSC 查询数据	包含查询表格和快速改进项的 Search Console 报告
indexation	批量检查数据	包含覆盖率环形图的索引状态
full	所有数据汇总	全面的 Google SEO 报告（包含所有部分）

工作流：

1. 运行数据收集命令（pagespeed、gsc、inspect-batch 等）
2. 将 JSON 输出保存到文件："${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run pagespeed_check.py <url> --json > data.json
3. 生成报告："${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run google_report.py --type cwv-audit --data data.json --domain <domain>

约定： 完成分析后，建议：“生成报告？使用 /seo google report <type>”

---

速率限制

API	每分钟	每天	身份验证
PSI v5	240 QPM	25,000 QPD	API 密钥
CrUX + History	150 QPM（共享）	无限制	API 密钥
GSC Search Analytics	1,200 QPM/站点	30M QPD	服务账号
GSC URL Inspection	600 QPM	2,000 QPD/站点	服务账号
Indexing API	380 RPM	200 次发布/天	服务账号
GA4 Data API	10 个并发	约 25K 个令牌/天	服务账号

跨技能集成

• seo-audit：有条件地启动 seo-google Agent，以获取实时 CWV 和索引数据
• seo-technical：使用 pagespeed_check.py 获取真实 CWV 实测数据
• seo-performance：CrUX 实测数据补充 Lighthouse 实验室数据
• seo-sitemap：GSC 站点地图状态显示已提交数量、错误和警告；使用 URL Inspection 确认真实索引状态
• seo-content：GSC 查询数据为关键词定位提供参考
• seo-geo：使用 GSC 生成式 AI 性能报告，以及 AI Overviews／AI Mode／Discover 的生成式 AI 纳入／排除控制项（Search 生成式 AI 属性设置，自 2026-08-31 起对所有网站开放）

输出格式

• CWV 指标：使用红绿灯评级（良好／需改进／较差）
• 性能报告：使用包含可排序列的表格
• 始终注明数据时效性
• 将报告保存为 GOOGLE-API-REPORT-{domain}.md
• Markdown/LLM 模板位于 assets/templates/：cwv-audit-report.md、gsc-performance-report.md、indexation-status-report.md；这些模板与 google_report.py 的 PDF 生成流程不同

技术说明

• INP 于 2024 年 3 月 12 日取代 FID。切勿引用 FID。
• CrUX 中的 CLS 值以字符串编码（例如 "0.05"）。脚本会处理解析。
• CrUX 返回 404 表示流量不足，并非身份验证错误。
• Search Analytics 数据延迟 2-3 天。
• CrUX 中的 round_trip_time 于 2025 年 2 月取代了 effectiveConnectionType。
• Custom Search JSON API 已停止向新客户开放（2025 年）。

错误处理

场景	操作
未配置凭据	运行 /seo google setup。列出仅需 API 密钥即可使用的 Tier 0 命令。
服务账号缺少 GSC 访问权限	报告错误。说明：将 client_email 添加到 GSC > 设置 > 用户 > 添加。
CrUX 数据不可用（404）	报告 Chrome 流量不足。建议使用 PSI 实验室数据作为备用方案。
未找到 GA4 媒体资源	报告错误。说明如何在 GA4 管理员 > 媒体资源详情中查找媒体资源 ID。
超出 Indexing API 配额	报告每日 200 次的限制。建议优先处理最重要的 URL。
速率限制（429）	等待后使用指数退避重试。报告触发限制的 API。