1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | bigquery-troubleshooting-google-skills |
| 作者/维护者 | Google(官方) |
| 来源链接 | https://github.com/google/skills/tree/main/skills/cloud/bigquery-troubleshooting |
| 许可证 | Apache-2.0 |
| GitHub Stars / Forks | 21,805 / 1,861(所属仓库整体数字,不代表本技能自身热度;GitHub API,2026-11-06 读取) |
| 最新版本 | 技能内标注 1.1.1;仓库主分支最近一次提交 2026-11-02 |
| 安装方式 | 把技能目录复制进 agent 的 skills 目录;另需 Google Cloud SDK 与有权限的项目 |
数据来源:上述数字取自 GitHub API;功能与评分依据来自技能正文与官方文档。
2. 功能介绍与亮点
一句话:作业失败、变慢或账单突然变高时,按症状—瓶颈—根因的顺序做诊断,而不是直接改 SQL。
- 从症状出发:先解释现象(失败、变慢、变贵),再隔离到具体阶段。
- 看执行图:把查询分解到 stage 与 substep,指出哪一步在拖时间或烧 slot。
- 成本专项:区分按需查询花费、容量预留的伸缩、存储增长三类原因。
- 给根因也给处置:每条结论对应一个可执行的修复动作,而不是「再查查」。
- 边界清楚:写 SQL 与主动优化交给 optimization 技能,取遥测数据交给 observability 技能。
- 调用可归因:执行命令带使用标记,企业侧能核对。
3. 适用场景
所属分类:数据分析与可视化。
- 早上发现某个定时作业失败,需要快速定位到具体 stage 的工程师;
- 查询突然变慢、怀疑是执行计划变了的数据团队;
- 账单异常上涨,想分清是查询、预留还是存储导致的 FinOps;
- 接手别人的 BigQuery 项目,需要一套稳定的排障顺序。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 技能目录安装,按描述触发 |
| Codex | 需适配 | 技能正文通用,认证与项目配置需按平台调整 |
| OpenClaw | 需适配 | 需要平台支持技能目录并允许执行本地命令 |
| Hermes Agent | 未验证 | 未找到该平台的接入示例 |
5. 推荐理由
BigQuery 贵和慢的原因常常不在 SQL 本身,而在执行图、预留与存储策略。多数「优化」技能直接从改查询开始;这个技能先要求把症状定位到具体 stage 或成本项,再谈改法——顺序对了,才不会被表象带偏。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Google 官方出品;所属仓库 21,805 stars 是整个合集热度,不代表本技能自身热度 |
| 可用性 | 8 | 诊断步骤与命令对照完整、边界明确;前置是 gcloud 与项目权限 |
| 安全性 | 9 | 见下方清单;官方开源,命令范围限于用户自己的项目 |
安全性检查清单:
| 项 | 结果 |
|---|---|
| ① 执行 shell 与权限 | 通过 gcloud/API 读取作业与执行图,作用域限于所给项目 |
| ② 联网外发 | 只与 Google Cloud 端点通信,使用归因标记,目标透明 |
| ③ 凭据 | 使用 gcloud 既有凭据,不要求把密钥写进对话 |
| ④ 可疑指令 | 未见注入或夹带推广 |
| ⑤ 作者信誉 | Google 官方仓库,Apache-2.0 |
| ⑥ License | Apache-2.0,全文可查 |
| ⑦ 维护时间 | 2026-11-02 仍在更新 |
扣分点:需要真实项目与权限;诊断依赖遥测数据是否开全。
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| bigquery-optimization-google-skills | 慢查询改写与容量规划 | 管「怎么改好」;本技能管「为什么坏了」 |
| bigquery-basics-google-skills | BigQuery 入门与基本操作 | 管「怎么用」;本技能管「出问题怎么查」 |
| cloud-logging-finops | 日志成本治理 | 面向日志开销;本技能覆盖查询、预留与存储三类 |
核心差异:同类多给优化建议或基础操作,它给的是排障顺序与执行图读法。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价(2026-11-06)。
9. 其他补充
- 技能内标注 1.1.1,随官方仓库更新。
- 属于
google/skills合集(180 个技能),可按需只装这一条。
10. 安装使用方式
git clone https://github.com/google/skills
mkdir -p ~/.claude/skills
cp -r skills/skills/cloud/bigquery-troubleshooting ~/.claude/skills/
gcloud auth login && gcloud config set project <你的项目>
装好后说「这个作业昨天开始变慢,帮我看是哪一步的问题」,它会先读执行图再给根因。
11. 注意事项
- 需要 gcloud 与项目权限,纯本地无法验证。
- 遥测数据不全时结论会打折,报告里会说明缺什么。
- 属于诊断技能,不替你重写查询。
- 调用带使用归因标记,企业合规上需先确认。