blog-google

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

以下捆绑路径使用宿主的 Markdown 替换功能解析 ${CLAUDE_SKILL_DIR}； 它不是导出的 shell 变量。执行前解析这些路径，加上引号，并拒绝非绝对路径的覆盖值。将从 ${CLAUDE_SKILL_DIR}/../blog/references 解析出的 blog_reference_root、从 ${CLAUDE_SKILL_DIR}/../blog/templates 解析出的 blog_template_root，以及所需的同级根目录传递给 Agent。 加载项目上下文前，先阅读主参考文档 orchestration-details.md；只将其由辅助代码围栏包围的输出传递给下游 Agent。

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

大多数集成在其文档规定的配额内不收取使用费。Cloud Natural Language 需要启用结算，超出每月免费额度后可能产生费用。Google Ads 需要符合条件的账号和开发者令牌。未经用户明确批准，切勿启用结算或发出付费请求。

费用与授权关卡（必须先阅读）

此技能会使用用户的 Google 凭据、配额，有时还会涉及结算。

• 消耗内容： 使用用户 Google Cloud 项目的 API 配额（小额配额池：YouTube search.list 每天有独立的 100 次调用配额，URL Inspection 每个站点每天允许 2,000 次调用，Indexing API 每天允许 200 次发布请求）；Cloud Natural Language 每月免费额度为 5,000 个单位，超出后会收费；Keyword Planner 需要 Google Ads 账号。
• 对外写入内容： index 会向 Google 发送通知，setup 会在 ~/.config/claude-seo/ 下写入凭据配置。其他操作均为只读。
• 授权： 每个会话中，在首次调用读取账号数据（gsc、inspect、ga4、keywords）、消耗小额配额池（youtube、批量 inspect）、可能产生费用（nlp）或写入数据（index、setup）的命令前，先说明命令、资源或 URL、预期调用次数，以及配额或费用依据，然后等待用户明确同意。对于仅需调用命令的免费无密钥读取操作（例如针对公开 URL 的 pagespeed 和 crux），只需说明调用命令。
• 禁止无上限循环： 批处理文件不得超出用户批准的范围；遇到第一个配额错误时即停止，不要继续重试。
• 跳过项： 在提供给编排器的“回退与跳过项”摘要中，用一行说明每个跳过或不可用的命令，例如“Google：没有凭据，已跳过 CrUX”。

持久运行时目录

CLAUDE_BLOG_RUNTIME_DIR 可用于指定一个可信的绝对持久根目录。此集成使用 <root>/blog-google/.venv；NotebookLM 也会将 <root>/blog-notebooklm/data 用于其知识库、身份验证和浏览器状态。未设置此覆盖项时，仍使用现有的技能本地默认路径。Google 的共享凭据配置/令牌路径保持不变。不会自动复制或迁移状态，常规运行也绝不会执行设置操作。

保留现有且已验证的运维人员覆盖值。对于没有此覆盖值的插件，在设置操作和之后的每次运行器调用中，都显式传入宿主替换后的 ${CLAUDE_PLUGIN_DATA}/claude-blog-runtime 路径。这是 Markdown 替换，不是导出的 shell 变量。只有在路径解析为绝对路径后才能执行。单引号会将未解析的占位符保留为字面值，这样验证会拒绝该路径，而不会将其展开成不同的 shell 路径：

CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/setup_environment.py" --check --json
CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/run.py" google_auth --check --json

只有在不带 --check 的显式设置操作中才会安装依赖。独立用户继续使用默认值，除非他们明确选择了绝对运行时根目录。相对路径、未解析路径或已链接的受管子目录都会被安全拒绝。更改根目录会选择单独的状态；这绝不代表允许迁移或清理旧根目录。插件持久数据遵循宿主的卸载保留规则；如果卸载时仍需要这些数据，请明确予以保留。

前置条件

运行任何命令前，始终检查凭据：

BLOG_SKILLS_DIR="${CLAUDE_BLOG_SKILLS_DIR:-${CLAUDE_SKILL_DIR}/..}"
case "$BLOG_SKILLS_DIR" in /*) ;; *) echo "ERROR: skills dir must be absolute" >&2; exit 1 ;; esac
python3 "$BLOG_SKILLS_DIR/blog-google/scripts/run.py" google_auth --check --json

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

{
  "api_key": "YOUR_GOOGLE_API_KEY",
  "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",
  "ads_login_customer_id": "123-456-7890"
}

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

凭据级别

级别	检测条件	可用命令
0（API Key）	存在 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

运行命令前，始终告知用户检测到的级别。

机器可读错误

某些旧版辅助工具在 --json 模式下会输出 error JSON 对象，但进程退出码为 0。集成现有调用方时，请保留这些退出约定，但要检查解析后的结果：任何 error 都表示操作失败。批处理结果也需要逐项检查错误；不能仅凭退出状态为 0 就认定 API 操作成功。未来迁移退出状态时，需要单独审查兼容性变更。

快速参考

命令	功能	级别
/blog google setup	检查/配置 API 凭据	:
/blog google pagespeed <url>	PSI Lighthouse + CrUX 现场数据	0
/blog google crux <url>	仅 CrUX 现场数据（p75 指标）	0
/blog google crux-history <url>	CWV 趋势，默认 25 周，最多 40 周	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（仅限职位或直播页面；博客文章不符合条件）	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 "$BLOG_SKILLS_DIR/blog-google/scripts/run.py" pagespeed_check <url> --json 参考： ${CLAUDE_SKILL_DIR}/references/api-reference.md

输出会合并实验室评分（Lighthouse 单次检测数据）与现场数据（28 天 Chrome 用户指标）。CrUX 会先尝试 URL 级数据，失败时回退到来源级数据。

/blog google crux <url>

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

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

/blog google crux-history <url>

CrUX History 趋势默认使用 25 个每周周期，也可通过 --periods 指定最多 40 个周期。它们显示 CWV 指标是在改善、保持稳定还是恶化。

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

---

Search Console

/blog google gsc <property>

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

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

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

Search Console 专用的生成式 AI 报告正在 Search Console 界面中逐步向部分用户推出。它们分别提供搜索和 Discover 视图；搜索视图涵盖 AI Overviews 和 AI Mode。不要承诺能从这些专用视图中获取点击次数、查询或 API 数据。在 Google 发布 API 文档之前，请将此功能报告为 SKIPPED 或不可用，并引导用户前往界面查看。

Google 在 7 月 29 日发布的 Search Central 公告称，适用于 Instagram、TikTok、X 和 YouTube 的 Search Console 平台属性已在全球推出。目前的帮助中心仍称该功能正在逐步推出。请将此情况报告为 Google 来源之间的信息冲突，核实用户账号中的可用性，并且不要声称 /blog google gsc 可通过当前 API 获取这些平台报告。

/blog google inspect <url>

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

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

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

修复规范网址问题后，Google 可能会在重复网址集群中保留该网址长达两周。如果当前实现已正确，且修复时间仍在此期限内，请报告为 PENDING_REEVALUATION，而不是立即判定失败。Search Console 的请求编入索引功能有配额限制；请留给重要网址使用。

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

---

索引 API

/blog google index <url>

通过索引 API 通知 Google 网址已更新。

适用范围： Google 的索引 API 文档指出，该 API“只能用于抓取嵌入了 JobPosting 或 VideoObject 中嵌入了 BroadcastEvent 的页面”（https://developers.google.com/search/apis/indexing-api/v3/quickstart， 读取日期：2026-10-12）。普通博客文章不符合适用条件。不要对博客文章运行此命令，也不要将其作为加快文章编入索引的方法。对于博客文章，请使用 /blog google inspect <url>；如有需要，可在界面中使用 Search Console 的请求编入索引功能（有配额限制）。

如果用户仍然指定了网址，请先询问它是否为 JobPosting 页面或直播（VideoObject 中的 BroadcastEvent）页面。只有在用户明确确认后，才说明将发送的内容并再次取得明确同意，然后运行：

脚本： python3 "$BLOG_SKILLS_DIR/blog-google/scripts/run.py" indexing_notify <url> --confirm-eligible --json 参考： ${CLAUDE_SKILL_DIR}/references/api-reference.md

如果没有 --confirm-eligible，脚本会拒绝提交；切勿自行添加此标志。每日配额：200 次发布请求。不要将此功能说成 URL 检查中“请求编入索引”功能的替代方案。

批量处理（同样需要确认适用条件，且适用于文件中的每个网址）： python3 "$BLOG_SKILLS_DIR/blog-google/scripts/run.py" indexing_notify --batch <file> --confirm-eligible --json

---

GA4 流量

/blog google ga4 [property-id]

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

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

查看热门落地页：python3 "$BLOG_SKILLS_DIR/blog-google/scripts/run.py" ga4_report --property <id> --report top-pages --json

---

YouTube（视频发现）

YouTube 研究可以为博客补充有用且相关的媒体和分发背景信息。任何第三方可见度相关性都只是观察结果，并非 Google 排名或引用要求。免费，仅需 API 密钥。blog-write 和 blog-rewrite 会使用此功能嵌入视频。

/blog google youtube <query>

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

脚本： python3 "$BLOG_SKILLS_DIR/blog-google/scripts/run.py" youtube_search search "<query>" --json 配额： search.list 有独立的配额池：默认每天 100 次调用，每次 1 个单位（Google 配额成本页面，2026-10-12 阅读）。其他 YouTube 端点共用另一个每天 10,000 个单位的配额池。针对每个不同需求只进行一次搜索，遇到首次配额错误时即停止。

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

获取视频详情和评论：python3 "$BLOG_SKILLS_DIR/blog-google/scripts/run.py" youtube_search video <video_id> --json

---

NLP 内容分析

Google 的实体和情感分析可用于支持主题和编辑审查。 它不会提供排名系统评分，E-E-A-T 也不是 Google 的数值排名因素。

/blog google nlp <url-or-text>

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

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

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

---

关键词研究（Google Ads）

关键词搜索量数据的黄金标准。需要 Google Ads 账户（Tier 3）。

/blog google keywords <seed>

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

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

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

---

报告

/blog google report <type>

生成带图表和表格的 PDF/HTML 报告。

脚本： python3 "$BLOG_SKILLS_DIR/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 需要 WeasyPrint 及其系统库（Pango 和 Cairo）。显式设置脚本只安装 Python 包，且没有任何 运行会安装系统包。如果缺少这些库，报告将回退为 HTML；请告知用户，由他们决定是否安装这些库。

---

速率限制

API	每分钟	每天	身份验证
PSI v5	240 QPM	25,000 QPD	API Key
CrUX + History	150 QPM（共享）	无限	API Key
GSC Search Analytics	每个站点和每个用户 1,200 QPM；每个项目 40,000 QPM	每个项目 30M QPD	Service Account
GSC URL Inspection	每个站点 600 QPM	每个站点 2,000 QPD（每个项目 10M）	Service Account
Indexing API	380 RPM	每天发布 200 次	Service Account
GA4 Data API	10 个并发（360 版为 50 个）	每天 200K 个 Core Token（360 版为 2M）	Service Account
YouTube Data	：	search.list：每天 100 次调用（独立配额池）；其他端点每天 10,000 个单位	API Key
NLP API	：	每月 5,000 个单位	API Key（结算）

阅读 ${CLAUDE_SKILL_DIR}/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 视频以便嵌入

未配置凭据时会平稳回退。

报告模板

工作流需要生成可长期保存、便于阅读的报告时，请使用附带的模板。账户数据不可用时，应标记为 SKIPPED；切勿用估算指标填充空白章节。

• assets/templates/cwv-audit-report.md 用于 PageSpeed 和 CrUX 证据。
• assets/templates/gsc-performance-report.md 用于 Search Analytics 导出数据。
• assets/templates/indexation-status-report.md 用于 URL Inspection 证据。

技术说明

• INP 于 2024 年 3 月 12 日取代了 FID。切勿提及 FID。
• CrUX 中的 CLS 值以字符串编码（例如 "0.05"）。脚本会负责解析。
• CrUX 返回 404 表示 Chrome 流量不足，并非身份验证错误。
• Search Analytics 数据有 2-3 天延迟。
• Indexing API 官方仅适用于 JobPosting 和 BroadcastEvent-in-VideoObject 页面；博客文章不符合条件。
• 大多数集成在配额范围内不收取使用费。Cloud Natural Language 需要启用结算，可能会产生费用；Google Ads 需要账户和开发者令牌访问权限。
• 在诊断具名更新、规范网址变更、Discover 可见性、Google 生成式 AI 报告、平台属性、Preferred Sources、AMP 或爬虫字节限制问题之前，请先阅读 ${CLAUDE_SKILL_DIR}/references/search-currentness.md。
• 具名更新的日期无法证明其导致了某个网站的变动。更新推出后等待一整周再比较数据，并分别分析 Web、Image、Video 和 News 的表现。
• Googlebot 仅会处理受支持文件的前 2MB，以及 PDF 的前 64MB。请将关键元数据和主要内容放在截断位置之前。

错误处理

情况	操作
未配置凭据	运行 /blog google setup。列出 Tier 0 命令（仅需 API 密钥）。
服务账号没有 GSC 访问权限	在 GSC > Settings > Users and permissions > Add user 中添加 client_email，并授予满足需求的最低权限级别（Performance 数据选择 Restricted，URL Inspection 选择 Full）；不要授予 Owner 权限。参阅 references/auth-setup.md。
CrUX 数据不可用（404）	Chrome 流量不足。使用 PSI 实验室数据作为备用。
找不到 GA4 媒体资源	在 GA4 Admin > Property Details 中查找媒体资源 ID。
Indexing API 配额超限	每日上限为 200。停止操作；只有符合条件的职位或直播 URL 才适用于此 API。
速率限制（429）	等待后使用指数退避重试。