blog-google

Blog Google：用于博客表现分析的 Google API 数据

直接访问 Google 的 SEO API，分析博客表现。提供真实的 Chrome 用户指标、收录状态、搜索表现、实体分析、YouTube 视频发现、关键词搜索量，以及 PDF/HTML 表现报告。

正常使用量范围内，所有 API 均免费。设置需要拥有 API 密钥和/或 服务账号的 Google Cloud 项目。

先决条件

运行任何命令前，请务必检查凭据：

python3 skills/blog-google/scripts/run.py google_auth --check --json

配置文件： ~/.config/claude-seo/google-api.json（与 claude-seo 共用）

{
  "api_key": "AIzaSy...",
  "oauth_client_path": "/path/to/client_secret.json",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789",
  "ads_developer_token": "...",
  "ads_customer_id": "123-456-7890"
}

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

凭据等级

等级	检测方式	可用命令
0（API 密钥）	存在 api_key	pagespeed、crux、crux-history、youtube、nlp
1（OAuth/SA）	+ OAuth 令牌或服务账号	等级 0 + gsc、inspect、index
2（完整）	+ 已配置 ga4_property_id	等级 1 + ga4
3（Ads）	+ ads_developer_token + ads_customer_id	等级 2 + keywords

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

快速参考

命令	功能	等级
/blog google setup	检查/配置 API 凭据	:
/blog google pagespeed <url>	PSI Lighthouse + CrUX 实测数据	0
/blog google crux <url>	仅 CrUX 实测数据（p75 指标）	0
/blog google crux-history <url>	25 周 CWV 趋势分析	0
/blog google youtube <query>	YouTube 视频搜索（观看次数、点赞数、时长）	0
/blog google nlp <url-or-text>	NLP 实体提取 + 情感分析	0
/blog google gsc <property>	Search Console：点击次数、展示次数、CTR、排名	1
/blog google inspect <url>	URL 检查：收录状态、规范网址	1
/blog google index <url>	通过 Indexing API 提交 URL	1
/blog google ga4 [property-id]	GA4 自然流量报告	2
/blog google keywords <seed>	来自 Google Ads Keyword Planner 的关键词创意	3
/blog google report <type>	PDF/HTML 表现报告	:
/blog google quotas	显示所有 API 的速率限制	:

---

PageSpeed + CrUX

/blog google pagespeed <url>

合并 Lighthouse 实验室数据与 CrUX 实测数据，分析已发布的博客文章。

脚本： python3 skills/blog-google/scripts/run.py pagespeed_check <url> --json 参考： references/api-reference.md

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

/blog google crux <url>

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

脚本： python3 skills/blog-google/scripts/run.py pagespeed_check <url> --crux-only --json

/blog google crux-history <url>

25 周 CrUX History 趋势。显示 CWV 指标是在改善、稳定还是恶化。

脚本： python3 skills/blog-google/scripts/run.py crux_history <url> --json

---

Search Console

/blog google gsc <property>

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

脚本： python3 skills/blog-google/scripts/run.py gsc_query --property <property> --json 默认值： 28 天，维度为 query、page，类型为 web，限制为 1000。

包含快速获益机会检测：排名在 4–10 位且展示次数较高的查询。

/blog google inspect <url>

URL 检查：Google 返回的真实收录状态。

脚本： python3 skills/blog-google/scripts/run.py gsc_inspect <url> --json

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

批量检查：python3 skills/blog-google/scripts/run.py gsc_inspect --batch <file> --json

---

Indexing API

/blog google index <url>

通知 Google 某个 URL 已更新。提交新的博客文章，以便更快地编入索引。

脚本： python3 skills/blog-google/scripts/run.py indexing_notify <url> --json 参考： references/api-reference.md

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

批量处理：python3 skills/blog-google/scripts/run.py indexing_notify --batch <file> --json

---

GA4 流量

/blog google ga4 [property-id]

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

脚本： python3 skills/blog-google/scripts/run.py ga4_report --property <id> --json 默认值： 28 天，筛选自然搜索渠道组。

查看热门着陆页：python3 skills/blog-google/scripts/run.py ga4_report --property <id> --report top-pages --json

---

YouTube（视频发现）

YouTube 提及与 AI 曝光度的相关性最高（0.737，基于 Ahrefs 对 75K 个品牌的分析）。 免费，仅需 API 密钥。blog-write 和 blog-rewrite 会使用此功能嵌入视频。

/blog google youtube <query>

在 YouTube 上搜索与博客主题相关的视频。

脚本： python3 skills/blog-google/scripts/run.py youtube_search search "<query>" --json 配额： 每次搜索 100 个单位（免费每日 10,000 个单位）。

返回：标题、频道、观看次数、点赞数、时长、描述、标签。

查看视频详情和评论：python3 skills/blog-google/scripts/run.py youtube_search video <video_id> --json

---

NLP 内容分析

使用 Google 自有的实体和情感分析功能。可提升博客内容的 E-E-A-T 评分。

/blog google nlp <url-or-text>

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

脚本： python3 skills/blog-google/scripts/run.py nlp_analyze --url <url> --json 免费额度： 每月 5,000 个单位。需要在 GCP 项目中启用结算。

仅提取实体：python3 skills/blog-google/scripts/run.py nlp_analyze --url <url> --features entities --json

---

关键词研究（Google Ads）

行业标准的关键词搜索量数据。需要 Google Ads 账号（Tier 3）。

/blog google keywords <seed>

根据种子词生成关键词创意，用于博客主题研究。

脚本： python3 skills/blog-google/scripts/run.py keyword_planner ideas "<seed>" --json

查询搜索量：python3 skills/blog-google/scripts/run.py keyword_planner volume "<kw1>,<kw2>" --json

---

报告

/blog google report <type>

生成包含图表的专业 PDF/HTML 报告。

脚本： python3 skills/blog-google/scripts/run.py google_report --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 报告

注意： 生成 PDF 需要系统库：sudo apt install libpango1.0-dev libcairo2-dev。 如果 weasyprint 不可用，则会回退为 HTML。

---

速率限制

API	每分钟	每日	认证方式
PSI v5	240 QPM	25,000 QPD	API 密钥
CrUX + History	150 QPM（共享）	无限制	API 密钥
GSC Search Analytics	1,200 QPM/site	30M QPD	服务账号
GSC URL Inspection	600 QPM	2,000 QPD/site	服务账号
Indexing API	380 RPM	200 次发布/日	服务账号
GA4 Data API	10 个并发请求（360 为 50 个）	每日 200K Core Tokens（360 为 2M）	服务账号
YouTube Data	:	每日 10,000 个单位	API 密钥
NLP API	:	每月 5,000 个单位	API 密钥（结算）

阅读 references/rate-limits-quotas.md，了解详细的配额管理信息。

博客工作流集成

此技能既可由用户调用（/blog google pagespeed），也可由其他博客子技能在内部调用：

• blog-seo-check：对已发布文章的 URL 运行 PSI + CrUX，获取实时 CWV 数据
• blog-rewrite：通过 NLP 实体分析识别 E-E-A-T 实体缺口
• blog-geo：利用 GSC 性能数据了解真实的搜索展示情况
• blog-audit：批量检查所有已发布博客 URL 的 CWV 和索引状态
• blog-write / blog-rewrite：搜索 YouTube 视频以便嵌入

未配置凭据时会平稳降级。

技术说明

• INP 于 2024 年 3 月 12 日取代 FID。切勿引用 FID。
• CrUX 中的 CLS 值以字符串编码（例如 "0.05"）。脚本会处理解析。
• CrUX 返回 404 表示 Chrome 流量不足，而非身份验证错误。
• Search Analytics 数据有 2–3 天的延迟。
• Indexing API 官方仅适用于 JobPosting/BroadcastEvent 页面。
• 所有使用的 Google API 在正常用量范围内均免费。

错误处理

场景	操作
未配置凭据	运行 /blog google setup。列出 Tier 0 命令（仅需 API 密钥）。
服务账号缺少 GSC 访问权限	将 client_email 添加到 GSC > Settings > Users > Add。
CrUX 数据不可用（404）	Chrome 流量不足。使用 PSI 实验室数据作为回退。
未找到 GA4 媒体资源	在 GA4 Admin > Property Details 中查找媒体资源 ID。
超出 Indexing API 配额	每日限额为 200 次。优先处理最重要的 URL。
速率限制（429）	等待后使用指数退避策略重试。