1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | gke-ai-troubleshooting-tpu-metrics-monitoring-google-skills |
| 作者/维护者 | Google（google/skills 官方仓库） |
| 来源链接 | https://github.com/google/skills/tree/main/skills/cloud/gke-ai-troubleshooting-tpu-metrics-monitoring |
| 许可证 | Apache-2.0（GitHub API 获取，适用于整个仓库） |
| GitHub Stars | 19,678（GitHub API 获取；该数字属整个 google/skills 合集仓库，不代表本技能自身热度） |
| Forks | 1,584（GitHub API 获取，同为合集整体数据） |
| 最新版本 | 无独立版本号；该技能目录最近一次改动为 2026-08-21（重命名为 gke-ai-troubleshooting- 前缀），GitHub API 获取 |
| 安装方式 | npx skills add google/skills 后勾选对应技能，或手动复制 skills/cloud/gke-ai-troubleshooting-tpu-metrics-monitoring 目录 |
2. 功能介绍与亮点
这是一个把“GKE 上 TPU 工作负载是不是被底层基础设施拖累”这个问题，从翻日志排查变成按脚本跑查询的诊断技能。核心能力：
- 前置配置核验：先检查容器是否暴露
containerPort: 8431、JAX 版本是否 ≥0.4.14、GKE 版本是否满足 TPU 运行时指标的最低要求——避免在指标压根没被采集的情况下瞎排查。 - 八步诊断流程：从 TensorCore 占用率、加速器显存用量，到节点 Ready 状态、多主机 TPU 节点池可用性、维护/抢占中断次数分类统计，每一步都配好可直接套用的 PromQL 查询语句。
- 量化恢复指标：内置 MTTR（平均恢复时间）与 MTBI（平均中断间隔）两条 PromQL 计算公式，把“这个集群最近是不是老出问题”变成一个可比较的数字，而不是凭印象判断。
- 全程只读：所有步骤标注
[Low Risk] [Auto]，全部是对 Cloud Monitoring 的查询请求，不触碰集群配置、不下发任何变更命令。 - 产品命名对齐：2026-08-21 由旧的独立命名统一重命名为
gke-ai-troubleshooting-前缀系列，与同仓库处理 TPU OOM、动态分片监控、抢占中断等技能构成一套针对 GKE AI 基础设施故障排查的家族。
3. 适用场景
所属分类：DevOps 与基础设施
适用于在 GKE 上运行 TPU 训练或推理工作负载的机器学习基础设施工程师与 SRE：训练任务突然变慢、多主机 TPU 节点池报告不可用、或需要向团队汇报“这个季度 TPU 集群的平均故障恢复时间是多少”时，可以让 agent 按本技能的步骤逐条跑 PromQL 查询，定位问题出在配置缺失、节点异常、还是宿主维护/抢占事件，而不必现翻 Cloud Monitoring 文档现拼查询语句。
分类判定说明：用 python3 scripts/update_index.py --neighbors "TPU 监控 GKE PromQL 指标" 核查，命中 85 条中 DevOps 与基础设施以 54 条明显居首（数据分析与可视化 13 条），与本技能“排查基础设施层面故障”的定位一致，判定与邻居分布一致，也与同库中 gke-cost-optimization、gke-workload-security 等同前缀技能所属分类一致。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 ✅ | SKILL.md 遵循 Agent Skills 规范（YAML frontmatter + 纯 Markdown 正文），全部步骤是只读查询语句，agent 可直接输出或经已配置的 GCP 工具执行，无需额外权限申请 |
| Codex | 需适配 ⚠️ | Codex CLI 默认沙箱在 workspace-write 模式下网络访问关闭，而查询 Cloud Monitoring 需要联网调用 GCP API；技能本身不含任何写操作，兼容性瓶颈完全在沙箱网络开关而非技能设计 |
| OpenClaw | 未验证 ❓ | 遵循同一 SKILL.md 开放标准，理论上可直接复制安装，但该平台默认沙箱的网络出站策略未逐一核实 |
| Hermes Agent | 未验证 ❓ | 未找到该平台默认沙箱网络策略与 GCP Monitoring API 调用兼容性的公开可靠资料 |
5. 推荐理由
TPU 工作负载出问题时，很难第一时间分清是代码本身的锅还是底层节点/宿主的锅——尤其是多主机 TPU 节点池，一个节点掉线就可能拖垮整批训练任务，而 Cloud Monitoring 里能查的指标和 PromQL 语法本身就有门槛。这个技能把“该查哪些指标、用什么语句查、异常值该怎么解读”提前想清楚并固化成一套可复制的诊断步骤，还搭配了 MTTR/MTBI 这种能直接写进事故复盘报告的量化结论。对已经在用 GKE + TPU、但还没有一套系统化排障流程的团队，这是一个能立刻拿来跑的现成工具，不需要额外部署或申请新权限。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 发布方 Google 是 GKE/TPU 产品的所有者，属第一方出品；google/skills 属合集仓库，19,678 星属整个仓库不代表本技能自身热度；GitHub 上未检索到针对本子技能自身的独立第三方讨论 |
| 可用性 | 8 | 单个 SKILL.md 即可触发，8 个诊断步骤均附可直接复制的 PromQL 语句，前置条件（端口、JAX/GKE 版本）说明清晰；最近一次改动为 2026-08-21（约 19 天前，在 3 个月维护窗口内）；无付费依赖，但需要用户已有一个真实的 GKE+TPU 集群才能验证效果 |
| 安全性 | 9 | 全部步骤为只读 Cloud Monitoring 查询，无 Shell 命令执行、无写操作、无第三方外发；见下方检查清单 |
综合评分：8.00
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行范围 | 无——技能全部内容是 PromQL 查询语句与判断逻辑，不涉及任何命令执行 |
| ② 运行时联网外发 | 网络行为限于向用户已认证的 GCP 项目发起 Cloud Monitoring 查询请求，不向第三方外发数据 |
| ③ API Key/凭据 | 不要求本技能自身存储任何密钥，依赖用户已配置的 GCP/GKE 认证 |
| ④ 可疑指令 | 通读全文未发现夹带推广、隐蔽外发或索取额外权限的指令 |
| ⑤ 作者信誉 | Google 官方仓库，无造假迹象 |
| ⑥ License | Apache-2.0，明确开源 |
| ⑦ 最近维护 | 最近一次改动 2026-08-21，所属仓库当日（2026-09-09）仍有持续提交，处于活跃开发状态 |
7. 跟同类 Skills 相比的优势
| 技能/工具 | 覆盖范围 | 特点 |
|---|---|---|
| gke-ai-troubleshooting-tpu-metrics-monitoring-google-skills（本技能） | 用 PromQL 监控与诊断 GKE TPU 工作负载/节点/节点池的性能与可用性 | 覆盖面最广的“体检式”排障入口，含前置配置核验 + 8 步查询 + MTTR/MTBI 量化指标，不针对某个具体故障场景 |
| gke-ai-troubleshooting-tpu-vbar-oom-google-skills | 诊断 TPU v6e vbar_control_agent 内存溢出这一具体故障 |
是本仓库同前缀家族里的单一事故 runbook，只解决一种已知问题，不做通用性能巡检 |
| gke-workload-security-google-skills | GKE 工作负载安全配置检查（如 Pod 安全策略、网络策略） | 关注的是安全合规配置是否到位，不涉及性能指标或中断归因，与本技能的“故障排查”定位不同 |
| victoriametrics-skills | 通用 PromQL/VictoriaMetrics 时序数据库查询与运维 | 是面向任意 Prometheus 兼容后端的通用查询工具，不预置任何 TPU/GKE 专属指标名称或诊断步骤，需要用户自己知道该查什么 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价；GitHub 上以此技能名称检索 issue 与 pull request 均无匹配结果，尚未见针对本技能自身的独立使用反馈。
9. 安装使用方式
- 通用安装：
npx skills add google/skills，交互式勾选 “gke-ai-troubleshooting-tpu-metrics-monitoring” 后自动写入当前 agent 的技能目录。 - 手动安装：复制仓库中
skills/cloud/gke-ai-troubleshooting-tpu-metrics-monitoring/SKILL.md到所用 agent 的技能目录下即可，本技能不依赖额外脚本或参考文件。 - 使用前提：目标 GKE 集群需已启用 GKE 系统指标采集，容器需暴露
containerPort: 8431，若使用 JAX 需 ≥0.4.14 版本，GKE 版本需满足各步骤标注的最低版本要求（部分查询需 1.32.1-gke.1357001 及以上）。 - 触发方式：向 agent 描述排障需求（如“帮我看看这个 GKE 集群的 TPU 节点池是不是有中断”）并提供项目 ID、集群名称等上下文，agent 会按步骤跑相应 PromQL 查询并解读结果；全程只读，无需重启 agent、无需额外确认门槛。
10. 注意事项
- 仅适用于已在 GKE 上部署 TPU 工作负载的场景，非 TPU 的通用 GKE 工作负载监控、或不依赖指标的其他 TPU 调试方式不在覆盖范围内。
- 多数查询依赖特定的最低 GKE 版本（如节点池状态查询需 1.27.4-gke.900+，节点 Ready 状态查询需 1.32.1-gke.1357001+），版本过旧的集群可能查不到对应指标。
- 跨 Agent 兼容性仅确认 Claude Code 原生支持；Codex 需手动开启网络访问权限以完成 Cloud Monitoring API 调用，OpenClaw、Hermes Agent 的沙箱网络策略均未逐一核实。
- 该技能只做诊断和数据呈现，不包含任何自动修复动作，具体的扩容、重启节点等处置仍需人工或其他工具完成。