1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | gke-ai-troubleshooting-tpu-vbar-oom-google-skills |
| 作者/维护者 | Google（google/skills 官方仓库） |
| 来源链接 | https://github.com/google/skills/tree/main/skills/cloud/gke-ai-troubleshooting-tpu-vbar-oom |
| 许可证 | Apache-2.0（GitHub API 获取，适用于整个仓库） |
| GitHub Stars | 19,697（GitHub API 获取；该数字属整个 google/skills 合集仓库，不代表本技能自身热度） |
| Forks | 1,584（GitHub API 获取，同为合集整体数据） |
| 最新版本 | 无独立版本号；该技能目录自 2026-08-04 创建以来仅一次提交，GitHub API 获取 |
| 安装方式 | npx skills add google/skills 后勾选对应技能，或手动复制 skills/cloud/gke-ai-troubleshooting-tpu-vbar-oom 目录 |
2. 功能介绍与亮点
这是一个针对 GKE 上 TPU v6e 节点一种具体已知故障——vbar_control_agent 段错误与内存溢出（OOM）——的专项诊断 runbook。核心能力：
- 时间窗口自动换算：只需提供故障发生时间戳，技能自动推算前后 30 分钟的日志查询窗口，省去手工拼时间范围的步骤。
- 三步诊断链：从串行控制台日志中的
Memory cgroup out of memory崩溃特征，到tpu-device-plugin的指标校验和错误，再到检查是否存在自定义高频指标采集脚本触发了竞态条件——层层收窄根因范围，每一步都配好可直接执行的 Cloud Logging 查询语句。 - 可复制的处置建议：定位到自定义指标采集是诱因时，给出“临时禁用采集脚本”的处置建议；同时说明该问题的根本修复依赖未来 GKE 版本对
vbar_control_agent的健壮性更新。 - 全程只读：所有诊断步骤均为 Cloud Logging 查询或
kubectl get只读检查，不下发任何集群变更命令；仓库自带的校验脚本validate_queries.sh同样只做gcloud logging read --limit=1的只读试跑。 - 产品命名对齐：与同仓库的
gke-ai-troubleshooting-tpu-metrics-monitoring、gke-ai-troubleshooting-tpu-dynamic-slices-monitoring等技能同属gke-ai-troubleshooting-前缀家族，共同覆盖 GKE AI 基础设施的不同故障场景。
3. 适用场景
所属分类：DevOps 与基础设施
适用于在 GKE 上运行 TPU v6e 训练或推理工作负载、且已遇到（或希望提前排查）vbar_control_agent 崩溃或 OOM 问题的机器学习基础设施工程师与 SRE：串行控制台日志出现莫名的内存溢出终止、或 TPU 设备插件报告指标校验和错误时，可以让 agent 按本技能的三步流程定位是否为已知的竞态条件问题，而不必现翻内核日志现猜根因。
分类判定说明：用 python3 scripts/update_index.py --neighbors "TPU vbar OOM 诊断 段错误" 核查，命中 61 条中 DevOps 与基础设施以 28 条明显居首（工程效率与代码质量 11 条），与本技能“诊断基础设施层面具体故障”的定位一致，也与同库 gke-ai-troubleshooting-tpu-metrics-monitoring、gke-workload-security 等同前缀/同领域技能所属分类一致，判定与邻居分布一致。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 ✅ | SKILL.md 遵循 Agent Skills 规范（YAML frontmatter + 纯 Markdown 正文），全部步骤是只读查询语句，agent 可直接输出或经已配置的 GCP 工具执行，无需额外权限申请 |
| Codex | 需适配 ⚠️ | Codex CLI 默认沙箱在 workspace-write 模式下网络访问关闭，而查询 Cloud Logging 需要联网调用 GCP API；技能本身不含任何写操作，兼容性瓶颈完全在沙箱网络开关而非技能设计 |
| OpenClaw | 未验证 ❓ | 遵循同一 SKILL.md 开放标准，理论上可直接复制安装，但该平台默认沙箱的网络出站策略未逐一核实 |
| Hermes Agent | 未验证 ❓ | 未找到该平台默认沙箱网络策略与 GCP Logging API 调用兼容性的公开可靠资料 |
5. 推荐理由
TPU v6e 节点上的 vbar_control_agent 崩溃是一种隐蔽的竞态条件问题——现象是内存溢出终止或指标校验和错误，很容易被误判为普通的容器 OOM 或网络抖动，靠人工翻日志定位耗时且容易走弯路。这个技能把“该查哪条日志特征、怎么排除是不是自定义指标采集脚本引起的竞态”这套排查经验固化成三步可直接执行的诊断链，还内置了官方给出的临时处置建议。对已经在 GKE 上跑 TPU v6e 工作负载、担心遇到这类底层故障的团队，这是一个能直接拿来对照排查的现成工具，不需要额外部署。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | 发布方 Google 是 GKE/TPU 产品的所有者，属第一方出品；google/skills 属合集仓库，19,697 星属整个仓库不代表本技能自身热度；GitHub 上未检索到针对本子技能自身的独立第三方讨论 |
| 可用性 | 7 | 单个 SKILL.md 即可触发，三步诊断均附可直接复制的日志查询语句，时间窗口自动换算省去人工计算；最近一次改动为 2026-08-04（约 5 周前，在 3 个月维护窗口内）；但仅针对 TPU v6e 这一具体硬件型号的单一已知故障，受众场景较窄 |
| 安全性 | 9 | 全部诊断步骤为只读日志查询与 kubectl get 只读检查，处置建议为人工执行的推荐而非自动下发命令，随附校验脚本同样只做只读试跑；见下方检查清单 |
综合评分：7.67
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行范围 | 仅随附的 validate_queries.sh 校验脚本执行 gcloud logging read --limit=1，为只读试跑，不涉及任何写操作 |
| ② 运行时联网外发 | 网络行为限于向用户已认证的 GCP 项目发起 Cloud Logging 查询请求，不向第三方外发数据 |
| ③ API Key/凭据 | 不要求本技能自身存储任何密钥，依赖用户已配置的 GCP/GKE 认证 |
| ④ 可疑指令 | 通读全文未发现夹带推广、隐蔽外发或索取额外权限的指令 |
| ⑤ 作者信誉 | Google 官方仓库，无造假迹象 |
| ⑥ License | Apache-2.0，明确开源 |
| ⑦ 最近维护 | 技能目录最近一次改动 2026-08-04，所属仓库当日（2026-09-10）仍有持续提交，处于活跃开发状态 |
7. 跟同类 Skills 相比的优势
| 技能/工具 | 覆盖范围 | 特点 |
|---|---|---|
| gke-ai-troubleshooting-tpu-vbar-oom-google-skills（本技能） | 诊断 TPU v6e vbar_control_agent 段错误与 OOM 这一具体已知故障 |
单一事故 runbook，聚焦一种明确的竞态条件问题，诊断链短、结论明确 |
| gke-ai-troubleshooting-tpu-metrics-monitoring-google-skills | 用 PromQL 监控 GKE TPU 工作负载/节点/节点池整体性能与可用性 | 覆盖面更广的“体检式”排障入口，含前置配置核验 + 八步查询 + MTTR/MTBI 量化指标，不针对某个具体故障场景 |
| gke-workload-security-google-skills | GKE 工作负载安全配置检查（如 Pod 安全策略、网络策略） | 关注的是安全合规配置是否到位，不涉及硬件层面的崩溃或性能问题，与本技能的“具体故障诊断”定位不同 |
| victoriametrics-skills | 通用 PromQL/VictoriaMetrics 时序数据库查询与运维 | 面向任意 Prometheus 兼容后端的通用查询工具，不预置任何 TPU 专属故障特征或诊断步骤，需要用户自己知道该查什么 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价；GitHub 上以此技能名称检索 issue 与 pull request 均无匹配结果，尚未见针对本技能自身的独立使用反馈。
9. 安装使用方式
- 通用安装：
npx skills add google/skills，交互式勾选 “gke-ai-troubleshooting-tpu-vbar-oom” 后自动写入当前 agent 的技能目录。 - 手动安装：复制仓库中
skills/cloud/gke-ai-troubleshooting-tpu-vbar-oom/SKILL.md（含references/与scripts/子目录）到所用 agent 的技能目录下即可。 - 使用前提：目标 GKE 集群需已启用 Cloud Logging，且拥有可访问对应 GCP 项目与集群的
gcloud权限；需已在 TPU v6e 节点上运行工作负载。 - 触发方式：向 agent 描述故障现象（如“某节点串行控制台出现 vbar_control_agent OOM”）并提供项目 ID、节点名称、故障时间等上下文，agent 会按三步流程跑相应日志查询并给出根因判断；全程只读，无需重启 agent、无需额外确认门槛。
10. 注意事项
- 仅适用于 TPU v6e 型号节点上的
vbar_control_agent崩溃/OOM 场景，其他 TPU 型号或非 TPU 相关的容器 OOM 问题不在覆盖范围内。 - 技能本身只做诊断和处置建议，不包含自动修复能力；根本性修复依赖未来 GKE 版本更新，当前只能通过临时禁用自定义指标采集脚本规避。
- 跨 Agent 兼容性仅确认 Claude Code 原生支持；Codex 需手动开启网络访问权限以完成 Cloud Logging API 调用，OpenClaw、Hermes Agent 的沙箱网络策略均未逐一核实。