用途
本技能用于指导通过 treg 连接查询 Google Search Console API 的实践，重点关注那些“不报错、但返回看似合理却是错误答案”的情形。资料声明这些陷阱在 2026-07-22 针对 sc-domain:example.com 进行了实测，每个陷阱均由三个独立智能体确认。
站点标识与资源选择
站点 ID 可通过 treg connections ls 查看，对应 resource_ref。若为空，表示没有固定站点，可用 treg connections resources <id> 列出全部资源，并说明选择了哪一个以及原因。不要将推断出的站点描述成已配置的站点，也不要把空值当成故障上报——它并不是故障。当未固定站点且问题未指定站点时，应选择域名与问题匹配的站点，并明确说明这是推断。需要注意子域是独立资源，sc-domain:example.com 与 sc-domain:app.example.com 是不同的答案，必须说明使用的是哪一个。
陷阱一：近期数据不完整，不可当作趋势
实测中三个智能体中有三个都得出“自然流量下降约 47%”的结论，但这个结论是错的。GSC 数据滞后约 2–3 天，并会直接省略缺失日期——请求 14 天只返回 11–12 行，且没有任何警告。更麻烦的是，最新出现的几天读数偏低。示例数据尾部为：07-15: 640、07-16: 610、07-17: 500、07-18: 520、07-19: 430，其中最后三天不完整。与同期 GA4 自然会话交叉核对后，并不存在下降，GA4 还显示 07-20 和 07-21 回升至 746 和 849，而这两天 GSC 完全没有报告。由此有两条规则：时间范围的结束日期应距今天至少 3 天，且不要以本地高峰作为窗口起点；在将任何 GSC 趋势判定为真实之前，必须用同期 GA4 自然会话交叉核对。两个独立来源不一致，说明 GSC 尾部是伪影。
陷阱二：维度求和不等于站点总量
示例说明（重点在于维度求和会偏离真实总量，而非绝对数值）：按 query 分组返回 4,219 行，展示量仅约为真实总量的 31%，少算约 69%；按 page 分组返回 1,161 行，展示量约为真实总量的 151%，多算约 51%；按 date 分组返回 28 行，等于真实总量，100%；不分组返回 1 行，等于真实总量，100%。query 少算是因为 Google 会丢弃匿名化的罕见查询；page 多算是因为一次 SERP 展示中出现你的多个页面时会按页面各计一次。（数值为实测；机制属于标准解释，并未实测。）因此永远不要用维度求和来上报总量，尤其是在回答“我的头部查询带来多少流量”时，这样求和会以十足的信心少报约 69% 的自然流量。
陷阱三：searchAppearance 不能与其他维度组合
与其他维度组合会明确失败并返回 400：“Cannot group by search appearance dimension together with another dimension.” 应单独查询该维度。另外，该维度结果稀疏是正确结果，不是缺陷。
陷阱四：同一主机上存在两套 API 面
webmasters/v3/... 用于搜索分析和 sitemaps；v1/urlInspection/index:inspect 用于 URL Inspection。猜测 webmasters/v3/urlInspection/... 会返回 Google 的 HTML 404，而不是 JSON 错误。三个智能体中有两个踩过这个坑。HTML 与 JSON 的区别普遍值得注意：返回 HTML 意味着该路径从未被路由。
其他事实
其余为标准 API 行为。ctr 是小数（0.0882 即 8.82%）；position 是平均值，因此不要跨行再求平均。rowLimit 可接受 25000（默认值报为 1000，未经验证）。sitemap 的 contents[].indexed 对一个完全收录、含 1,079 个 URL 的站点返回了 “0”，因此应使用 URL Inspection 获取真实收录状态。子域是独立资源。sc-domain:example.com 与 sc-domain%3Aexample.com 在路径中均可使用，已经由审计日志验证；编码是可选的，不要为了排查 403 而去添加编码。
未验证事项
URL-prefix 属性（https://example.com/，带结尾斜杠）没有可测试的对象，尚未验证。据报告，403 通常意味着属性形式不对，而不是缺少权限。
写操作
对 sitemaps 的 PUT/DELETE 会改变 Google 的抓取行为。资料声明出于设计原因未做测试；应先取得明确目标并获得人工许可。
参考链接
搜索分析查询：https://developers.google.com/webmaster-tools/v1/searchanalytics/query URL Inspection：https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect 数据新鲜度与匿名化：https://support.google.com/webmasters/answer/7576553