google-search-console

Google Search Console 技能

由 Return Zero Inc. 创建

为 Claude Code 提供全面的 Google Search Console API 技能，支持搜索分析、URL 检查、站点地图管理和网站验证。

使用时机

• 用户提到“Google Search Console”“GSC”或“search console”
• 用户询问搜索效果、点击次数、展示次数或 CTR
• 用户需要查询 URL 编入索引的状态或进行检查
• 用户想要管理站点地图
• 用户询问搜索排名或索引状态
• 用户需要 Google 搜索 SEO 分析数据

功能

1. 搜索分析 ⭐

• 查询搜索效果数据（点击次数、展示次数、CTR、排名）
• 按日期范围、页面、查询、国家/地区和设备筛选
• 按维度分组（查询、页面、国家/地区、设备、日期）
• 比较不同时间段
• 导出为 CSV/JSON

2. URL 检查

• 检查特定 URL 的编入索引状态
• 查看抓取信息
• 检查移动设备易用性
• 识别索引问题
• 请求将 URL 编入索引

3. 站点地图管理

• 列出网站的所有站点地图
• 提交新站点地图
• 删除站点地图
• 检查站点地图状态和错误

4. 网站管理

• 列出所有已验证的网站
• 添加新网站
• 移除网站
• 检查验证状态

环境变量

此技能使用由 jelly-dotenv 管理的环境变量。配置详情请参阅 skills/jelly-dotenv/SKILL.md。

选项 1：服务账号（推荐）

# Service account JSON key file path
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account.json

# Or inline JSON (for CI/CD environments)
GOOGLE_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'

选项 2：OAuth 2.0 客户端凭据

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token

常用设置

# Default site URL (optional, can be specified per request)
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://your-site.com

# Alternative naming patterns (auto-detected)
GSC_SITE_URL=https://your-site.com
SEARCH_CONSOLE_SITE=sc-domain:your-site.com

变量可配置在以下任一位置：

• skills/jelly-dotenv/.env（技能通用，优先级最高）
• 项目根目录 /.env（项目专用，作为回退选项）

配置

设置服务账号

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用“Google Search Console API”
4. 创建服务账号：
   • 前往“IAM 与管理”→“服务账号”
   • 创建服务账号
   • 下载 JSON 密钥文件
5. 将服务账号邮箱添加到 Search Console：
   • 前往 Search Console
   • 选择“设置”→“用户和权限”
   • 使用服务账号邮箱添加用户
   • 授予“完全”或“受限”访问权限

设置 OAuth 2.0

1. 前往 Google Cloud Console
2. 创建 OAuth 2.0 凭据（Web 应用）
3. 设置已获授权的重定向 URI
4. 使用 OAuth playground 或你的应用获取刷新令牌
5. 所需范围：https://www.googleapis.com/auth/webmasters.readonly

使用场景

场景 1：搜索效果概览

用户请求：“显示过去 7 天的搜索效果”

技能操作：

1. 从环境变量加载凭据
2. 使用日期范围查询 Search Analytics API
3. 汇总点击次数、展示次数、CTR 和排名
4. 格式化为带趋势的 Markdown 表格

输出：

## Search Performance (Last 7 Days)

| Metric | Value | Change |
|--------|-------|--------|
| Clicks | 1,234 | +12% |
| Impressions | 45,678 | +8% |
| CTR | 2.7% | +0.3% |
| Avg Position | 15.2 | -2.1 |

### Top Queries
| Query | Clicks | Impressions | CTR | Position |
|-------|--------|-------------|-----|----------|
| keyword 1 | 234 | 5,678 | 4.1% | 8.5 |
| keyword 2 | 189 | 4,321 | 4.4% | 12.3 |

场景 2：URL 检查

用户请求：“检查 https://example.com/page 的编入索引状态”

技能操作：

1. 调用 URL Inspection API
2. 解析索引结果
3. 检查覆盖率状态
4. 显示移动设备易用性

输出：

## URL Inspection: https://example.com/page

| Property | Status |
|----------|--------|
| Index Status | ✅ Indexed |
| Crawled | 2024-01-15 |
| Canonical | https://example.com/page |
| Mobile Usability | ✅ Mobile friendly |
| Rich Results | ⚠️ 2 warnings |

场景 3：站点地图管理

用户请求：“显示所有站点地图并提交一个新的”

技能操作：

1. 列出现有站点地图
2. 显示状态和上次提交日期
3. 提交新的站点地图 URL
4. 确认提交

场景 4：热门页面分析

用户请求：“我的哪些页面效果最好？”

技能操作：

1. 按页面分组查询 Search Analytics
2. 按点击次数排序
3. 包含展示次数、CTR 和排名
4. 突出展示次数高但 CTR 低的页面

API 参考

搜索分析查询

interface SearchAnalyticsRequest {
  startDate: string;      // YYYY-MM-DD
  endDate: string;        // YYYY-MM-DD
  dimensions?: ('query' | 'page' | 'country' | 'device' | 'date')[];
  searchType?: 'web' | 'image' | 'video' | 'news';
  dimensionFilterGroups?: FilterGroup[];
  aggregationType?: 'auto' | 'byPage' | 'byProperty';
  rowLimit?: number;      // Max 25000
  startRow?: number;
}

URL 检查

interface UrlInspectionRequest {
  inspectionUrl: string;
  siteUrl: string;
  languageCode?: string;
}

Sitemap 操作

操作	方法	Endpoint
列出	GET	/webmasters/v3/sites/{siteUrl}/sitemaps
获取	GET	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
提交	PUT	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
删除	DELETE	/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}

输出格式

Markdown（默认）

• 包含指标的格式化表格
• 趋势指示符（↑↓）
• 状态图标（✅⚠️❌）
• 摘要洞察

JSON

• 原始 API 响应
• 完整数据结构
• 程序化访问

CSV

• 兼容电子表格的导出
• 所有数据行
• 供进一步分析

错误处理

身份验证错误

错误	原因	解决方案
401 未授权	凭据无效	检查服务账号密钥或 OAuth 令牌
403 禁止访问	无权访问网站	将服务账号添加到 Search Console
范围无效	OAuth 范围错误	使用 webmasters.readonly 范围

API 错误

错误	原因	解决方案
404 未找到	Search Console 中没有该网站	先将网站添加到 Search Console
400 错误请求	参数无效	检查日期格式（YYYY-MM-DD）
429 请求次数超限	请求过多	等待后使用退避策略重试

常见问题

“配置错误：未找到 Google 凭据”

# Solution: Add credentials to .env
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json

“未找到网站或无权访问”

# Solution: Add service account email to Search Console
# Go to: Search Console → Settings → Users and permissions

“日期范围无效”

# Solution: Use YYYY-MM-DD format, max 16 months historical data

安全策略

身份验证

• 服务账号：建议用于服务器端使用
• OAuth 2.0：用于经过用户身份验证的请求
• 凭据：仅从环境变量加载
• 日志记录：自动隐藏私钥和令牌

数据访问

• 默认只读：使用 webmasters.readonly 范围
• 写入操作：提交/删除 Sitemap 需要完整范围
• 限定网站：仅限访问已获授权的网站

速率限制

• 自动处理：遵守 Google API 配额
• 重试：遇到 429 错误时采用指数退避
• 每日配额：每天 1,200 次查询（默认）

限制

• 历史数据：最多包含 16 个月的搜索数据
• 数据时效性：搜索分析数据延迟 2-3 天
• URL 检查：每个网站每天 2,000 次请求
• 行数限制：每次查询最多 25,000 行
• 维度：每次查询最多 3 个维度

与 Claude Code 集成

当用户提及以下内容时，此技能会自动激活：

• “google search console”、“gsc”、“search console”
• “search performance”、“search analytics”
• “url inspection”、“index status”
• “sitemap”、“sitemap management”
• “seo analytics”、“seo data”

此技能将：

1. 从 .env 加载 Google 凭据
2. 执行请求的查询/操作
3. 将结果格式化为 Markdown 表格
4. 提供可执行的洞察和建议

参考资料

• Google Search Console API 文档
• Search Analytics API 参考
• URL Inspection API 参考
• OAuth 2.0 设置
• API 配额和限制