pp-google-search-console

Google Search Console — Printing Press CLI

前置条件：安装 CLI

此技能使用 google-search-console-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install google-search-console --cli-only
   

2. 验证：google-search-console-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/marketing/google-search-console/cmd/google-search-console-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿执行技能命令。

何时使用此 CLI

当 Agent 需要针对 Google Search Console 资源回答 SEO 问题，且无需往返网页界面时，可使用此 CLI。适用场景包括：获取任意时间范围内的热门查询和页面；比较不同时段；发现索引或站点地图问题；找出第 2 页上的快速见效机会、流量下滑的页面或关键词蚕食；以及在已有同步历史记录时，回答有关 API 16 个月数据窗口之外的数据的问题。如果尚未运行同步，则不适合用于一次性的临时查询——请先运行 sync。

独特功能

这些功能在其他用于此 API 的工具中均不可用。

基于本地语料的 SEO 机会

• quick-wins — 找出展示次数高、点击率低的第 2 页查询——根据已同步的语料离线计算并按潜在收益排序，筛选有望从第 2 页升至第 1 页的候选项。

  当 Agent 需要为某个资源推荐最值得把握的 SEO 机会，且无需重新从 API 获取数据时，可使用此功能。

  google-search-console-pp-cli quick-wins sc-domain:example.com --position 8-20 --min-imps 100 --json
  

• cannibalization — 找出多个页面相互竞争的查询，并按总展示次数排序——可用于关键词蚕食审计，而 GSC 网页界面不提供此功能。

  当 Agent 调查某个查询的排名为何低于预期时，可使用此功能——它会直接列出各自 URL 上相互竞争的页面。

  google-search-console-pp-cli cannibalization sc-domain:example.com --min-imps 50 --top 25 --json
  

• outliers — 找出点击率偏离自有语料中“点击率与排名位置”曲线的查询或页面。

  这些是 Agent 可直接处理的标题标签和摘要改写候选项——其展示次数高，但对于所在排名位置而言点击率偏低。

  google-search-console-pp-cli outliers sc-domain:example.com --metric ctr --sigma 2 --top 50 --json
  

时间序列分析

• compare — 比较任意维度在不同时段之间的点击次数、展示次数、点击率和排名位置变化——支持周环比、月环比或自定义时间范围。

  当某个资源的流量发生变化时，可将此功能作为首选调查手段——Agent 无需深入检查两组原始查询，就能获取变化数据。

  google-search-console-pp-cli compare sc-domain:example.com --period 28d --vs prev-period --dim query --top 50 --agent --select rows.keys,rows.delta_clicks,rows.delta_position
  

• cliff — 找出点击次数或展示次数骤降的日期，并提供可能与同日站点地图问题或索引下降相关的特征提示。

  当用户表示“流量下降”时，Agent 应首先运行此命令——它会指出问题发生的日期和可能原因。

  google-search-console-pp-cli cliff sc-domain:example.com --metric clicks --threshold -25% --window 7d
  

• historical — 查询超出 API 滚动 16 个月窗口的日期范围内的搜索分析数据——根据缓存历史回答“2024 年 3 月的情况是否正常？”。

  适用于预测和季节性问题；Agent 无需打开备份文件，即可一次性回答“与两年前相比如何”。

  google-search-console-pp-cli historical sc-domain:example.com --start 2023-01-01 --end 2023-12-31 --dim query --top 100
  

跨资源分析

• roll-up — 通过一条命令汇总每个已验证资源中的热门查询或页面——而 API 需要进行 N 次往返请求。

  适用于代理机构的工作流：Agent 无需编写针对每个站点的循环，即可找出整个资源组合中的表现最佳者。

  google-search-console-pp-cli roll-up --metric clicks --group-by query --top 50 --last 28d --json
  

索引诊断

• coverage-drift — 在某个时间窗口内，检查状态发生变化（已编入索引 → 未编入索引、robots 已更改、规范链接已更改）的 URL。

  捕捉索引回归问题，否则由于状态恢复后 API 会将其隐藏，Agent 可能会错过这些问题。

  google-search-console-pp-cli coverage-drift sc-domain:example.com --field indexingState --days 30 --json
  

• sitemap-watch — 对比不同快照中的站点地图状态——找出新增错误、新增警告、内容数量下降以及 lastDownloaded 时间过久的问题。

  周五自动化任务，可在下周一流量下滑前捕捉站点地图回归问题——使用本地数据运行，不会产生额外的 API 费用。

  google-search-console-pp-cli sitemap-watch sc-domain:example.com --since 7d --json
  

内容工作流

• decaying — 在滚动时间窗口内点击量持续下降的页面，按总展示次数 × 负斜率排序——构成内容更新队列。

  内容营销人员周四的更新队列——Agent 会根据具体的数据，挑选待更新内容。

  google-search-console-pp-cli decaying sc-domain:example.com --window 90d --min-imps 500 --top 50 --json
  

• new-queries — 在过去 N 天内开始获得展示次数、但之前不存在于数据集中的查询——代表新兴需求。

  为营销人员提供内容创意；Agent 获取的是针对该网站的新兴搜索趋势，而不是通用的 Trends 数据。

  google-search-console-pp-cli new-queries sc-domain:example.com --since 28d --min-imps 50 --top 100 --json
  

命令参考

url-inspection — 检查 URL 在 Google 搜索中的索引状态

• google-search-console-pp-cli url-inspection — 返回 Google 对单个 URL 的看法：索引状态、上次抓取时间、规范 URL（Google 选择的 URL 与……）

webmasters — 管理网站管理员

• google-search-console-pp-cli webmasters add-site — 将网站添加到用户在 Search Console 中的网站集合中。网站仍需单独验证（通过 DNS，……）
• google-search-console-pp-cli webmasters delete-site — 从用户的 Search Console 网站集合中移除网站。不会删除 Google 已收集的数据。
• google-search-console-pp-cli webmasters delete-sitemap — 从站点地图报告中删除站点地图。如果站点地图仍然……，不会阻止 Google 抓取它。
• google-search-console-pp-cli webmasters get-site — 获取特定已验证网站的信息，包括用户的权限级别。
• google-search-console-pp-cli webmasters get-sitemap — 获取特定站点地图的信息，包括警告、错误、上次提交／下载时间以及……
• google-search-console-pp-cli webmasters list-sitemaps — 列出为此网站提交的站点地图，或站点地图索引文件中包含的站点地图（如果在……中提供了 sitemapIndex）
• google-search-console-pp-cli webmasters list-sites — 返回经过身份验证的用户在 Search Console 中可访问的所有网站（网域资源或网址前缀资源），……
• google-search-console-pp-cli webmasters query-search-analytics — 返回点击次数、展示次数、点击率和平均排名，并按指定维度分组（查询、网页、国家/地区，……）
• google-search-console-pp-cli webmasters submit-sitemap — 为网站提交站点地图。站点地图 URL 必须是与 siteUrl 属于同一网站的绝对 URL。提交操作……

查找合适的命令

知道要做什么，但不确定该用哪个命令时，可以直接询问 CLI：

google-search-console-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help 或缩小查询范围。

使用示例

点击率较低的热门查询——标题标签改写候选项

google-search-console-pp-cli outliers sc-domain:example.com --metric ctr --sigma 2 --top 50 --agent --select rows.keys,rows.position,rows.ctr,rows.expected_ctr

将 --agent（紧凑 NDJSON）与 --select 配合使用，以缩小响应范围，免得 Agent 必须逐一查看完整的 ApiDataRow 对象。输出仅包含维度以及相对于该排名区间平均值的点击率差值。

昨天的流量为什么下降了？

google-search-console-pp-cli cliff sc-domain:example.com --metric clicks --threshold -20% --window 14d --json

返回点击量较前一天下降超过 20% 的日期，以及来自站点地图（新增错误）和 url_inspections（索引状态变化）的当天信号。一个命令即可回答最常见的 SEO 复盘问题。

跨资源每周摘要

google-search-console-pp-cli roll-up --metric clicks --group-by query --last 7d --top 25 --csv > weekly.csv

汇总过去 7 天内所有已验证资源中按点击量排名前 25 的查询。CSV 可直接导入电子表格或数据工具。

从文件批量检查 URL

google-search-console-pp-cli url-inspection inspect-batch --file urls.txt --site sc-domain:example.com --max-per-day 2000 --json

以每行一条检查结果的方式输出 NDJSON。遵守每个资源的每日配额。通过管道传递给 jq 'select(.indexStatusResult.coverageState != "Submitted and indexed")'，仅筛出问题。

发布新页面前进行蚕食审计

google-search-console-pp-cli cannibalization sc-domain:example.com --min-imps 50 --top 20 --json

找出网站上已有多个页面竞争的查询。在同一主题发布新内容前运行——选择表现最强的现有页面，或合并页面。

身份验证设置

有两种方式。

推荐：auth login——一次性通过浏览器登录，之后自动刷新。

google-search-console-pp-cli auth set-client <client_id> <client_secret>   # 5-min Google Cloud Console setup, then run once
google-search-console-pp-cli auth login                                    # browser flow, persists refresh token
google-search-console-pp-cli auth login --no-browser                       # WSL2/SSH/headless variant
google-search-console-pp-cli auth login --scope write                      # opt into sitemap submit / site add+delete

运行 auth login 后，每条命令都会使用已保存的刷新令牌，静默刷新有效期为 1 小时的访问令牌。用户之后无需再接触令牌。完整的 Google Cloud Console 操作指南请参阅 README.md。

适用于 CI / 一次性脚本：GSC_ACCESS_TOKEN——从 OAuth Playground 获取令牌，导出后运行。令牌有效期为 1 小时，且不会自动刷新。

export GSC_ACCESS_TOKEN="ya29..."   # https://developers.google.com/oauthplayground/

两种方式可以并存。如果两者都存在，环境变量优先于文件中存储的令牌。

运行 google-search-console-pp-cli doctor 验证设置。auth status 会显示刷新令牌是否存在以及距离过期的倒计时。

Agent 模式

为任意命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 支持管道传递——JSON 输出到 stdout，错误输出到 stderr

• 支持筛选——--select 可保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这对控制上下文大小至关重要：

  google-search-console-pp-cli url-inspection --inspection-url https://example.com/resource --agent --select id,name,status
  

• 支持预览——--dry-run 显示请求，但不发送

• 非交互式——绝不提示输入，所有输入都通过标志传递

• 显式重试——仅当已存在的创建结果应视为成功时才使用 --idempotent；仅当缺失的删除目标应视为成功时才使用 --ignore-missing

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

google-search-console-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
google-search-console-pp-cli feedback --stdin < notes.txt
google-search-console-pp-cli feedback list --json --limit 10

条目会保存在本地 ~/.google-search-console-pp-cli/feedback.jsonl。除非设置了 GOOGLE_SEARCH_CONSOLE_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 GOOGLE_SEARCH_CONSOLE_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅保存在本地。

记录让你感到意外的事情，而不是提交错误报告。简短、具体、写成一行：这才是能不断累积价值的部分。

输出交付

每条命令都接受 --deliver <sink>。除 stdout 之外（或取代 stdout），输出还会发送到指定的接收端，因此 Agent 无需手动通过管道传递即可路由命令结果。支持三种接收端：

接收端	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

对于未知方案，会拒绝执行并返回结构化错误，其中列出受支持的方案。Webhook 请求失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置文件是保存的一组标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一命令，可使用配置文件——这就是 HeyGen 的“Beacon”模式。

google-search-console-pp-cli profile save briefing --json
google-search-console-pp-cli --profile briefing url-inspection --inspection-url https://example.com/resource
google-search-console-pp-cli profile list --json
google-search-console-pp-cli profile show briefing
google-search-console-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件中的值；配置文件中的值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置文件，让进行自省的 Agent 能在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 google-search-console-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上方的前置条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并带上 --agent）

安装 MCP 服务

从此 CLI 发布的公共库条目或预构建版本安装 MCP 二进制文件，然后注册：

claude mcp add google-search-console-pp-mcp -- google-search-console-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which google-search-console-pp-cli 如果未找到，则提供安装选项（请参阅本技能顶部的前置条件）。
2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   google-search-console-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，则进一步查看子命令帮助：google-search-console-pp-cli <command> --help。