实时搜索控制台数据

要解决的具体问题

在让编码代理（coding agent）读取 Google Search Console 与 Google Analytics 4 数据时，传统路径往往需要先配置 GCP 项目、创建服务账号、下载 JSON 密钥，并手动维护权限和缓存策略。只要项目变更或人员轮岗，密钥权限、有效范围和过期问题就会拖慢开发节奏。

工作原理与核心能力

该技能通过 RefreshAgent 作为安全代理，让代理直接访问 Google 官方 GSC / GA4 API，而无需经历 GCP OAuth 或服务账号配置。内置的 Python REST 助手会在首次使用时打开浏览器登录，获取 API Key 后保存至 ~/.config/refreshagent/.env，后续请求自动携带凭据。所有调用都经过 Google 官方 API，并在每个响应中报告缓存年龄，便于判断数据新鲜度。

• 认证流程：浏览器登录 → 获取 Key → 写入本地配置文件 → 自动续用
• 统一 API 层：代理无需关心 GSC 与 GA4 的差异，技能负责参数转换与端点路由
• GSC 能力：站点列表、流量摘要与周期对比、按点击/展示排序的热门查询与页面、精确关键词位置追踪与历史比较、关键词冲突（cannibalization）检测、Sitemap 提交状态与索引量
• GA4 能力：自然流量会话、落地页、热门事件，并支持跨站点映射与客户提案构建

适用边界与注意点

• 数据延迟：响应中的 cache age 字段会告诉你当前数据的更新时间，不要假设所有指标都是实时。
• 权限范围：登录账号需对目标 GSC 站点或 GA4 媒体资源有查看权限，否则列表或指标可能为空。
• 客户端站点映射：用于客户项目时，建议先完成站点关联与权限确认，再导出提案数据，避免跨账号混淆。
• 不要将缓存年龄误当作真实延迟：某些维度可能受 Google 侧处理队列影响，需要结合缓存年龄判断是否适合立即用于决策。