google-search-console

Google Search Console

架构

gsc 是一个封装了两个 Google API 的 Python CLI：

• Search Console API（webmasters v3 + searchconsole v1）——搜索分析、网站管理、站点地图、URL 检查
• PageSpeed Insights API（v5）——用于性能、无障碍性、SEO 和最佳做法的 Lighthouse 实验室测试

所有命令都将 JSON 输出到 stdout。错误输出到 stderr。专为 Claude 调用并以编程方式解析而设计。

首次使用前

1. uv：运行 which uv。如果未安装，请询问用户想如何安装（brew install uv，或参阅 https://docs.astral.sh/uv/getting-started/installation/）。
2. 项目同步：uv sync --project <skill-dir>
3. 身份验证：见下文。
4. PageSpeed API 密钥：见下文。

Search Console 身份验证（OAuth）

将 OAuth client_secret.json（从 GCP 下载）保存到已知路径，然后进行身份验证：

gsc auth login --client-secret /path/to/client_secret.json

系统会打开浏览器以进行 OAuth 授权。在无头计算机上，先建立 SSH 隧道：ssh -L 8085:localhost:8085 <this-host>，然后在有浏览器的计算机上打开打印出的 URL。凭据存储在 ~/.config/skills/gsc/credentials.json 中，并会自动刷新。

如果需要创建新的 OAuth 客户端，请参阅 references/setup.md，了解完整的 GCP 点击操作步骤。

PageSpeed Insights API 密钥

设置一次密钥后，gsc 会记住它：

gsc config set pagespeed-api-key <your-key>

如果没有密钥，请在 GCP 项目的 Credentials 页面创建一个，将其限制为“PageSpeed Insights API”，然后传递给上面的 gsc config set。

调用

uv run --project /path/to/skills/google-search-console gsc <command> [args]

为简洁起见，以下示例直接使用 gsc。

命令

auth —— 管理身份验证

# Authenticate with OAuth
gsc auth login --client-secret ./client_secret.json --port 8085

# Check auth status
gsc auth status

# Remove stored credentials
gsc auth logout

config —— 管理设置

# Set PageSpeed API key
gsc config set pagespeed-api-key AIza...

# Get a config value
gsc config get pagespeed-api-key

# Show all config (secrets masked)
gsc config show

query —— 搜索分析

# Basic query: clicks, impressions, CTR, position for last 7 days
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07

# Group by query keyword
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d query

# Group by page and query
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d page -d query

# Daily breakdown
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d date

# Filter by query containing "pricing"
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d query --query-filter pricing

# Exact match filter
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --query-filter "=best coffee shop"

# Mobile only
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --device-filter "=MOBILE"

# Image search
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --search-type image

# Paginate results
gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 --row-limit 5000 --start-row 0

筛选前缀运算符：= 表示精确匹配，! 表示不包含，不加前缀或使用 ~ 表示包含。

inspect —— URL 检查

gsc inspect sc-domain:example.com https://example.com/page
gsc inspect https://example.com/ https://example.com/page --language en-US

返回：索引状态、抓取信息、规范 URL、移动设备易用性、富媒体搜索结果状态。

sites —— 管理属性

gsc sites list
gsc sites get sc-domain:example.com
gsc sites add https://example.com/

sitemaps —— 管理站点地图

gsc sitemaps list sc-domain:example.com
gsc sitemaps get sc-domain:example.com https://example.com/sitemap.xml
gsc sitemaps submit sc-domain:example.com https://example.com/sitemap.xml
gsc sitemaps delete sc-domain:example.com https://example.com/sitemap.xml

pagespeed —— PageSpeed Insights

# Mobile performance (default)
gsc pagespeed https://example.com

# Desktop, all categories
gsc pagespeed https://example.com --strategy desktop \
  --category performance --category accessibility --category seo --category best-practices

# Specific locale
gsc pagespeed https://example.com --locale fr

需要 API 密钥：gsc config set pagespeed-api-key <key>。实验室测试需要 30–60 秒。

网站 URL 格式

Google Search Console 支持两种属性类型：

类型	格式	示例	范围
域名属性	sc-domain:example.com	sc-domain:example.com	所有子域名、协议和路径
URL 前缀属性	https://example.com/	https://example.com/	仅匹配完全相同的前缀

尽可能使用域名属性——它们涵盖所有变体。

常见工作流

每周性能检查

# This week vs last week, grouped by date
gsc query sc-domain:example.com -s 2026-03-05 -e 2026-03-11 -d date
gsc query sc-domain:example.com -s 2026-02-26 -e 2026-03-04 -d date

# Top queries by clicks
gsc query sc-domain:example.com -s 2026-03-05 -e 2026-03-11 -d query --row-limit 25

索引状态检查

# Check if key pages are indexed
gsc inspect sc-domain:example.com https://example.com/important-page
gsc inspect sc-domain:example.com https://example.com/new-blog-post

# Verify sitemap coverage
gsc sitemaps list sc-domain:example.com
gsc sitemaps get sc-domain:example.com https://example.com/sitemap.xml

点击率优化

# Find high-impression, low-CTR queries (position 3-10)
gsc query sc-domain:example.com -s 2026-02-10 -e 2026-03-11 -d query -d page --row-limit 5000

# Filter results to find optimization opportunities:
# Look for rows where impressions > 100 and position between 3-10 but CTR < 3%

设备对比

gsc query sc-domain:example.com -s 2026-03-01 -e 2026-03-07 -d device

Core Web Vitals 检查

gsc pagespeed https://example.com --strategy mobile
gsc pagespeed https://example.com --strategy desktop

解读输出

详细的解读指南请参阅 references/seo-playbook.md，其中包括：

• 不同 SERP 排名位置的点击率基准
• Core Web Vitals 阈值
• URL 检查结果
• 标题/描述优化
• 每月监控方法

配置文件

• OAuth 凭据：~/.config/skills/gsc/credentials.json
• 配置（API 密钥）：~/.config/skills/gsc/config.json
• 使用 GSC_CONFIG_DIR=/path/to/dir 覆盖配置目录

从早期版本迁移

如果从将配置存储在 ~/.config/gsc/ 的构建版本升级，请运行 gsc config migrate --apply，将凭据和配置迁移到新位置。迁移完成前，gsc auth status 会输出 deprecation_warning。

故障排除

“未通过身份验证” -- 运行 gsc auth login --client-secret /path/to/client_secret.json。凭据可能已过期，或在新设备上缺失。

“权限被拒绝” -- 已通过身份验证的账号必须是 Search Console 资源的已验证所有者或用户。请在 https://search.google.com/search-console 检查资源访问权限。

“超出速率限制” -- Search Console API 有每分钟和每天的配额。请等待 60 秒后重试。配额详情请参阅 references/setup.md。

URL 检查没有返回数据 -- 该 URL 可能不在 Google 的索引中。请检查 verdict 字段。只能检查已验证资源中的 URL。

PageSpeed 超时 -- Lighthouse 实验室测试可能需要 30-60 秒。该命令使用 120 秒超时。若失败，请重试。

设置配置时出现“未知键” -- 只有 pagespeed-api-key 是有效的配置键。