seo-google

示例输出：examples/seo-google-quickstart-20260514/README.md

Google SEO API

直接访问 Google 自有的 SEO 数据。弥合基于爬取的分析（目录中的其他工具）与 Google 实时实地数据之间的差距：真实 Chrome 用户指标、真实索引状态、搜索表现和自然流量。

所有 API 均免费。设置需要一个带有 API 密钥和／或服务账号的 Google Cloud 项目——运行 setup 命令获取分步说明，或直接阅读 references/auth-setup.md。

改编自 AgriciDaniel/claude-seo 的 seo-google 技能（MIT）。脚本、参考资料和命令接口与上游实现保持一致。配置路径统一置于 ~/.config/seo-skills/ 下，以便与原项目共存。

前提条件

• **必需：**Python 3.10+ 和 Google API 客户端库。通过 bash extensions/google/install.sh 安装。
• **必需：**至少需要一个 Google API 密钥（Tier 0）。要获得完整覆盖，还需要一个 Google Cloud 服务账号（Tier 1+），并可选配置 GA4 资源 ID（Tier 2）和 Google Ads 开发者令牌（Tier 3）。
• 配置文件：~/.config/seo-skills/google-api.json。

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

python scripts/google_auth.py --check --json

配置文件格式（~/.config/seo-skills/google-api.json）：

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

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

凭据层级

层级	检测方式	可用命令
0 (API 密钥)	存在 api_key	pagespeed、crux、crux-history、youtube、nlp、entity、safety
1 (OAuth/SA)	+ OAuth 令牌或服务账号	Tier 0 + gsc、inspect、sitemaps、index
2 (完整)	+ 已配置 ga4_property_id	Tier 1 + ga4、ga4-pages、ga4-referrals、ga4-channel-mix、ga4-properties
3 (Ads)	+ ads_developer_token + ads_customer_id	Tier 2 + keywords、volume

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

快速参考

命令	功能	层级
setup	检查／配置 API 凭据	--
pagespeed <url>	PSI Lighthouse + CrUX 实地数据	0
crux <url>	仅 CrUX 实地数据（p75 指标）	0
crux-history <url>	25 周 CWV 趋势分析	0
gsc <property>	Search Console：点击次数、展示次数、CTR、排名	1
inspect <url>	URL 检查：索引状态、规范网址、抓取信息	1
inspect-batch <file>	从文件批量检查 URL	1
sitemaps <property>	GSC 站点地图状态	1
index <url>	向 Indexing API 提交 URL	1
index-batch <file>	批量提交最多 200 个 URL	1
ga4 [property-id]	GA4 自然流量报告	2
ga4-pages [property-id]	自然流量排名靠前的落地页	2
ga4-referrals [property-id]	按来源划分的引荐会话——默认显示 AI 助手	2
ga4-channel-mix [property-id]	按渠道组划分的会话（Direct / Organic / Referral / Paid …）	2
ga4-properties	列出服务账号可读取的所有 GA4 账号和资源	2
youtube <query>	YouTube 视频搜索（观看次数、点赞数、时长）	0
youtube-video <id>	YouTube 视频详情和热门评论	0
nlp <url-or-text>	NLP 实体提取 + 情感分析 + 分类	0
entities <url-or-text>	仅实体分析（用于 E-E-A-T）	0
keywords <seed>	使用 Google Ads Keyword Planner 获取关键词建议	3
volume <keywords>	使用 Keyword Planner 查询搜索量	3
entity <query>	Knowledge Graph 实体检查	0
safety <url>	Web Risk URL 安全检查	0
quotas	显示所有 API 的速率限制	--
report <type>	根据收集的 JSON 生成 PDF/HTML/XLSX 报告	--

---

PageSpeed + CrUX

pagespeed <url>

Lighthouse 实验室数据 + CrUX 实际用户数据的综合结果。

脚本： python scripts/pagespeed_check.py <url> --json 参考： references/pagespeed-crux-api.md 默认： 同时使用移动端和桌面端策略，并包含所有 Lighthouse 类别。

输出将实验室评分（某个时间点的 Lighthouse 数据）与实际用户数据（Chrome 用户 28 天指标）合并。CrUX 会先尝试 URL 级数据，若没有则回退到源站级数据。

crux <url>

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

脚本： python scripts/pagespeed_check.py <url> --crux-only --json

crux-history <url>

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

脚本： python scripts/crux_history.py <url> --json 参考： references/pagespeed-crux-api.md

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

---

Search Console

gsc <property>

搜索分析：过去 28 天的点击次数、展示次数、CTR 和排名。

脚本： python scripts/gsc_query.py --property <property> --json 参考： references/search-console-api.md 默认： 28 天，维度=query,page，类型=web，限制=1000。

包含快速见效机会检测：排名在 4-10 且展示次数较高的查询。

筛选： --device {desktop,mobile,tablet}、--country <ISO3>、--page <url-or-substring>（默认使用 contains 匹配；传入 --page-match equals 可进行精确 URL 匹配）。组合使用可按 URL 分析查询：--page /blog/best-ai-seo-tools/ --dimensions query。

AI Overview / AI Mode： --ai-overview（或 --ai-mode）可将结果筛选为 Google 展示了包含你某个 URL 的 AI Overview / AI Mode SERP 的查询。这是 Google 官方提供的 “我们是否被 AI Overview 引用？” 答案——点击次数、展示次数、CTR 和平均排名均直接来自 GSC。与 --dimensions query,page 组合可查看哪些查询和页面获得了 AI Overview 展示；也可与 --page /post/ 组合，将范围限定为单个 URL。对于其他外观类型（RICH_RESULT、REVIEW_SNIPPET 等），请使用 --search-appearance <value>。

inspect <url>

URL 检查：获取 Google 提供的实际索引状态。

脚本： python scripts/gsc_inspect.py <url> --json

返回：判定结果（PASS/FAIL）、覆盖状态、robots.txt 状态、索引状态、网页抓取状态、规范网址选择、移动设备易用性和富媒体搜索结果。

inspect-batch <file>

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

脚本： python scripts/gsc_inspect.py --batch <file> --json

sitemaps <property>

列出已提交的网站地图及其状态、错误和警告。

脚本： python scripts/gsc_query.py sitemaps --property <property> --json

---

Indexing API

index <url>

通知 Google 某个 URL 已更新。

脚本： python scripts/indexing_notify.py <url> --json 参考： references/indexing-api.md

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

index-batch <file>

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

脚本： python scripts/indexing_notify.py --batch <file> --json

---

GA4 Traffic

所有 GA4 报告都可选用 --page <path-or-url> 标志，将报告范围限定为单个着陆页（与 GA4 的 landingPage 维度进行精确匹配；完整 URL 会自动去除域名，仅保留路径）。当问题是“这篇帖子表现如何？”而非全站表现时，请使用此标志。

--report organic 和 --report top-pages 支持 --channel <name|all>：默认值为 organic（自然搜索）；传入 all 可移除渠道筛选（跨所有流量来源查看整页每周趋势时必须使用），也可原样传入任意 GA4 默认渠道组，例如 Direct、Referral、Paid Search、Organic Social 等。

ga4 [property-id]

按日统计的流量报告：会话数、用户数、页面浏览量、跳出率、互动度。

脚本： python scripts/ga4_report.py --property <id> --json 参考： references/ga4-data-api.md 默认值： 28 天，筛选范围为 Organic Search 渠道组。传入 --channel all 可查看未筛选的流量。

当大部分流量来自 Direct 或 Referral，而非 Organic 时，全渠道版本可以回答“这篇文章的流量每周是如何增长的？”——这是 AI 引用内容的典型情况。示例：--report organic --page /blog/best-ai-seo-tools/ --channel all --days 99。

ga4-pages [property-id]

按会话数对所选渠道的热门落地页进行排名（默认渠道为 Organic Search；使用 --channel all 可查看所有来源的全站热门页面）。

脚本： python scripts/ga4_report.py --property <id> --report top-pages --json

ga4-referrals [property-id]

按 sessionSource 拆分 Referral 会话。默认使用精心整理的 AI 助手主机名列表——OpenAI（chatgpt.com、chat.openai.com）、Anthropic（claude.ai）、Google （gemini.google.com、bard.google.com）、Microsoft（copilot.microsoft.com）、Perplexity （perplexity.ai）、Alibaba/Qwen（chat.qwen.ai、qwen.com、tongyi.aliyun.com）、Mistral （chat.mistral.ai）、DeepSeek（chat.deepseek.com）、xAI/Grok（grok.com、x.ai），以及 you.com / phind.com / poe.com——因此，只需运行一条命令即可回答“AI 助手实际上给我们带来了多少流量？”这个问题。可将此数据与 seo-ai-search-share-of-voice 和 seo-geo 中的 AI 可见度数据进行对照，作为现实检验——引荐流量衡量的是用户在 AI 聊天中分享你链接的情况，而非 AI 是否主动引用你。

脚本： python scripts/ga4_report.py --property <id> --report referrals --json

来源模式（--sources）：

• ai（默认）——精心整理的 AI 助手主机名列表
• all——Referral 渠道组中的所有来源
• chatgpt.com,perplexity.ai,...——以逗号分隔的明确来源列表

结合 --page 可回答“这篇特定文章获得了多少 AI 流量？”： --report referrals --page /blog/best-ai-seo-tools/。

ga4-channel-mix [property-id]

按 sessionDefaultChannelGroup 拆分会话（Direct / Organic Search / Referral / Paid Search / Organic Social / …）。不筛选渠道——这是用于诊断“这个页面的流量实际上来自哪里？”的视图。每行都包含 share_of_sessions 百分比，可一目了然地查看流量构成。

脚本： python scripts/ga4_report.py --property <id> --report channel-mix --json

此报告可回答诸如 “这篇文章的表现主要来自自然流量，还是流量来自其他渠道？” 之类的问题。AI 助手流量通常会被计入 Direct（未归因），而非 Referral，因此，近期内容丰富的页面若 Direct 占比较高，本身就是 AI 可见度信号——可结合 ga4-referrals 获取更全面的情况。

按页面诊断：--report channel-mix --page /blog/best-ai-seo-tools/ --days 90。

ga4-properties

列出服务账号有权读取的所有 GA4 账号和属性。当客户端有多个 GA4 属性（通常是营销网站和应用分别使用不同属性，或按地区划分属性），且你需要确认要查询哪个 property_id 时，请先运行此命令，再运行 ga4 / ga4-pages / ga4-referrals / ga4-channel-mix。输出会按上级账号对属性分组；property_id 字段是要传入 --property 的数字值。

脚本： python scripts/ga4_admin.py properties --json

需要在 Cloud 项目中启用 Google Analytics Admin API（与 Data API 相互独立），并确保服务账号至少拥有一个属性的 Viewer 访问权限。

---

YouTube（视频 SEO）

YouTube 提及与 AI 可见度的相关性最强（0.737）。免费，仅需 API key。

youtube <query>

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

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

youtube-video <video_id>

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

脚本： python scripts/youtube_search.py video <video_id> --json 配额： 2 个单位（视频详情 + 评论）。

---

NLP 内容分析

Google 自有的实体／情感分析。可提升 E-E-A-T 评分。

nlp <url-or-text>

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

脚本： python scripts/nlp_analyze.py --url <url> --json 或 --text "..." 参考： references/nlp-api.md 免费层级： 每月 5,000 个单位。需要在 GCP 项目中启用结算。

entities <url-or-text>

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

脚本： python scripts/nlp_analyze.py --url <url> --features entities --json

---

关键词研究（Google Ads）

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

keywords <seed>

根据种子词生成关键词建议。

脚本： python scripts/keyword_planner.py ideas "<seed>" --json 参考： references/keyword-planner-api.md 需要： 在配置中设置 Ads 开发者令牌 + 客户 ID（Tier 3）。

volume <keywords>

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

脚本： python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json

---

补充功能

entity <query>

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

参考： references/supplementary-apis.md 使用带 API 密钥的 Knowledge Graph Search API。

safety <url>

使用 Web Risk API 检查恶意软件／社会工程攻击标记。

参考： references/supplementary-apis.md

quotas

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

---

报告

运行任何分析命令后，均可选择生成 PDF/HTML/XLSX 报告。

report <type>

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

脚本： python scripts/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 输出保存到文件：python scripts/pagespeed_check.py <url> --json > data.json
3. 生成报告：python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>

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

---

速率限制

API	每分钟	每天	身份验证
PSI v5	240 QPM	25,000 QPD	API Key
CrUX + History	150 QPM（共享）	不限	API Key
GSC Search Analytics	1,200 QPM/站点	30M QPD	Service Account
GSC URL Inspection	600 QPM	2,000 QPD/站点	Service Account
Indexing API	380 RPM	每天发布 200 次	Service Account
GA4 Data API	10 个并发请求	每天约 25K 个令牌	Service Account

跨技能集成

• seo-technical-audit — 使用 pagespeed_check.py 获取真实的 CWV 实地数据；使用 inspect 确认 SE Ranking 审计标记的索引状态。
• seo-page — 通过 gsc 使用真实的 GSC query,page 数据替代预估流量；通过 inspect 确认索引状态。
• seo-drift — 将 crux-history（25 周趋势）和 GSC 变化跟踪添加到基线/比较快照中。
• seo-sitemap — sitemaps 命令会显示 Google 实际抓取了哪些站点地图，以及其中的错误/警告数量（而 SE Ranking 审计只会抓取站点）。
• seo-content-audit — nlp 可增强对受审计页面的 E-E-A-T 实体/情感评分；gsc 可确认该页面是否为目标关键词带来展示。
• seo-geo — gsc --ai-overview --page <url> 使用 Google 自身的数据回答“此 URL 是否出现在 AI Overview 中，以及获得了什么效果？”，与 SE Ranking 的 AIO 引用提取相辅相成。将 gsc --ai-overview --dimensions query,page 与 GEO 建议搭配使用，逐个 URL 确认成效。
• seo-ai-search-share-of-voice — 将 ga4-referrals（来自 chatgpt.com/perplexity.ai/gemini.google.com 等平台的后续流量）与 SoV 提取结果（上游引用/品牌提及情况）结合起来，全面了解 AI 可见性：SoV 衡量 LLM 是否引用你，GA4 引荐流量衡量其用户是否实际点击进入你的网站。
• seo-keyword-cluster / seo-keyword-niche — 有可用数据时，volume（Tier 3）会使用 Google Ads 黄金标准搜索量替代 SE Ranking 搜索量。
• seo-plan — 配置 GSC + GA4 后，“当前状况”基线将使用真实展示次数/点击次数/转化次数，而非 SE Ranking 估算值。

输出格式

• CWV 指标：红绿灯评级（良好 / 需要改进 / 较差）
• 性能报告：包含可排序列的表格
• 始终注明数据时效性
• 将报告保存为 GOOGLE-API-REPORT-{domain}.md
• 使用 assets/templates/ 中的模板生成结构化输出

技术说明

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

错误处理

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