RFC-0031: 基于 Cloud Support API 的开 Case Skill

概述

在本仓库中新增一个 Claude Code Skill，当 TPU 生产任务发生故障时，引导 Claude 协助使用者收集关键信息、定位受影响产品（聚焦 Cloud TPU、GKE、GCS 三个产品）的分类，并通过 Google Cloud Support API 提交（或预演）一个 support case。部分字段（时区、语言、抄送人）固化为团队默认值，优先级等需人工判断的字段则在开 case 时向用户提问；标题与描述统一采用双语（英文在前、中文在后）。

背景与动机

我们的 TPU 训练任务跑在 GCP 上，生产故障（节点池创建/删除卡住、JobSet hang、TPU 主机 XID/维护事件等）需要尽快开 Google Cloud support case。当前开 case 存在几个痛点：

没有原生 gcloud 子命令：gcloud support cases create 并不存在，开 case 必须直接调用 Cloud Support API v2（cloudsupport.googleapis.com），gcloud 仅用于产出 access token。这对不熟悉 API 的同学有门槛。
环境配置易踩坑：用户 ADC 凭证调用时会因为缺少 quota project 报 403，需要先 gcloud services enable cloudsupport.googleapis.com 并在请求中带上 x-goog-user-project 头。
classification.id 无法手填：分类是一个长字符串 ID，必须先通过 caseClassifications:search 查询，不能凭空构造。
信息收集不规范：description 缺少结构化的排查信息（环境、复现步骤、日志等）会拖慢支持响应。

把这些步骤固化成一个 Skill，可以让 Claude 在故障发生时按既定流程引导使用者，减少重复劳动和低级错误。

收益：降低开 case 门槛、统一信息收集模板、避免 quota project / 分类 ID 等常见错误、提交前必须经用户明确确认。

目标

在仓库中新增一个 Skill（位于 .claude/skills/ 或对应约定目录），描述清晰、触发条件明确（TPU 生产故障 + 需要开 case）。
Skill 能引导 Claude 完成完整链路：环境预检 → 信息收集 → 查询 classification.id → 组装请求 → 复述请求体 → 用户确认（真实/测试/取消）→ 提交。
需要人工判断的细节（问题描述、优先级、受影响产品、目标项目）由 Skill 显式向使用者提问获取，不臆造；时区、语言、抄送人等团队固定值则内置为默认，无需每次询问。
提交前复述完整请求体，通过对话框让用户在「真实 case（testCase: false，默认）/ 测试 case（testCase: true）/ 取消」中三选一，明确确认后再提交。
提供查询/列出已有 case 的辅助流程，避免重复开 case。

成功判据：使用者在一次会话内，凭 Skill 引导即可正确提交一个 case（或完成可正式提交的预演），无需查阅 API 文档。

非目标

不实现独立的 CLI 工具或服务，仅提供 Skill（Markdown 指令 + 嵌入的命令模板）。
不自动判断故障根因、不替代人工排障；Skill 只负责"信息收集 + 开 case"。
不托管或存储任何凭证；认证完全依赖使用者本地的 gcloud auth。
不覆盖非 TPU/非 GCP 的工单系统。
不自动决定优先级（P1–P4，团队约定不开 P0）或代替用户点击"正式提交"——这些必须由人确认。

方案

新增一个 Skill，核心是一份结构化的操作手册（SKILL.md），让 Claude 在 TPU 生产故障场景下按步骤驱动开 case。Skill 内容包含：

触发与适用边界：何时该用（TPU 生产任务故障且需要 Google 支持介入）、何时不该用。
环境预检清单：确认 gcloud config（account/project）、启用 cloudsupport.googleapis.com、请求必须带 x-goog-user-project 头。
必填/可选字段说明：displayName / description / classification.id / priority 必填；timeZone / languageCode / subscriberEmailAddresses / contactEmail / testCase 可选。
向使用者提问的清单：把所有需人工提供的细节列成问题，一次问清。
命令模板：查询 classification、列出已有 case、创建 case（先 testCase）、查看评论、关闭 case。
安全护栏：正式提交前必须复述完整请求体，通过对话框让用户明确选择「真实 case / 测试 case / 取消」后再提交。

用户故事（可选）

作为一名 oncall 工程师，当 GKE TPU 节点池删除卡住时，我对 Claude 说"帮我开个 case"，Claude 会先问我项目/现象/优先级等信息，查好对应的 classification.id，用 testCase: true 跑一遍校验请求无误，复述给我确认后再正式提交，并返回 case 编号。
作为团队成员，我想先看有没有人已经开过同类 case，Claude 能列出当前项目未关闭的 case 供我判断是否重复。

备选方案

写成 Shell 脚本 / CLI 工具：能固化命令，但缺少"按场景提问、动态查分类、人工确认"的交互能力，且需要单独维护和分发。Skill 天然贴合 Claude 的交互式工作流。
只写一篇文档（best-practices）：信息齐全但不会主动触发，使用者仍需自己照着敲命令。Skill 可被 Claude 在合适场景自动援引并代为执行。
封装成 MCP server：能力更强、可结构化调用 API，但实现/部署成本高，且凭证管理更复杂；当前需求用 Skill + gcloud auth 足够。

约束与注意事项（可选）

需要项目具备 Standard / Enhanced / Premium 支持等级，否则 Support API 不可用。
priority 取值为 P1–P4（团队约定不开 P0，API 也不支持设置 P0）；classification 是对象，需填 id 而非自由文本。
ADC 用户凭证必须设置 quota project（请求头 x-goog-user-project 或 gcloud auth application-default set-quota-project），否则 403。
parent 可以是 projects/<id> 或 organizations/<id>。

设计细节

Skill 目录结构（遵循本仓库 Skill 约定，最终路径以仓库现状为准）：

text

.claude/skills/gcloud-support-case/
  └── SKILL.md          # 触发说明 + 操作手册 + 命令模板 + 提问清单

SKILL.md frontmatter（示意）：

yaml

---
name: gcloud-support-case
description: Use when a TPU production job has an incident and the user needs to open
  (or check) a Google Cloud support case for Cloud TPU, GKE, or GCS. Guides info
  gathering, classification selection, a testCase dry-run, then submission via Cloud
  Support API v2. Asks the user for priority; fixes timeZone/languageCode/subscribers.
---

关键命令模板（嵌入 Skill）：

① 环境预检：

bash

gcloud config list            # 确认 account / project
gcloud services enable cloudsupport.googleapis.com --project=<PROJECT_ID>

② 查询 classification.id（本 Skill 聚焦 Cloud TPU / GKE / GCS 三个产品）：

常用分类 ID 已在下方「产品分类 ID 快速参考」中固化，可直接选用、省去查询。若需其它子类或怀疑 ID 失效，再实时查询（display_name 按产品替换）：

bash

curl -s \
  --header "Authorization: Bearer $TOKEN" \
  --header "x-goog-user-project: <PROJECT_ID>" \
  "https://cloudsupport.googleapis.com/v2/caseClassifications:search?query=display_name:\"*Cloud TPU*\""
# 其它产品：display_name:"*Kubernetes Engine*" / display_name:"*Cloud Storage*"

③ 列出已有 case（避免重复；可加 ?filter=state=OPEN）：

bash

curl -s \
  --header "Authorization: Bearer $TOKEN" \
  --header "x-goog-user-project: <PROJECT_ID>" \
  "https://cloudsupport.googleapis.com/v2/projects/<PROJECT_ID>/cases"

④ 创建 case（提交前通过对话框让用户选择真实/测试）：

bash

PARENT="projects/<PROJECT_ID>"
curl -s --request POST \
  --header "Authorization: Bearer $TOKEN" \
  --header "x-goog-user-project: <PROJECT_ID>" \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "<English title only>",
    "description": "<[EN] ... [CN] ...，向用户提问，英文段在前中文段在后>",
    "classification": { "id": "<从下方快速参考中选择 TPU/GKE/GCS>" },
    "priority": "<P1–P4，向用户提问>",
    "timeZone": "Asia/Shanghai",
    "languageCode": "zh-CN",
    "subscriberEmailAddresses": ["wangyunpeng@google.com", "peishiuanwu@google.com"],
    "testCase": false
  }' \
  "https://cloudsupport.googleapis.com/v2/$PARENT/cases"

字段取值约定（本 Skill 的固定默认 vs 需提问项）：

字段	取值方式	值
`timeZone`	固定	`Asia/Shanghai`
`languageCode`	固定	`zh-CN`
`subscriberEmailAddresses`	固定	`wangyunpeng@google.com`、`peishiuanwu@google.com`
`priority`	每次向用户提问	`P1`–`P4`（团队约定不开 P0）
`displayName`	每次向用户提问，只写英文	—
`description`	每次向用户提问，双语：英文在前、中文在后	—
`classification.id`	据受影响产品从快速参考选择	见下表
`testCase`	提交前通过对话框让用户在「真实 case（默认，`false`）/ 测试 case（`true`）/ 取消」中选择	—

产品分类 ID 快速参考（查询时间 2026-06-18，如失效用 ② 重新查询）：

Cloud TPU（Other Google Cloud Products > Cloud TPU > …）：

子类	classification.id
Manage TPUs	`584L8PB3D1N6IOR1DGP10GRCDTQM8NQKA1ALUCPO70RJ0C9Q296M2RJ1CTILUL2GALPLUDPJ6SQ38DI2204024GC8TNMUPRCCKG46R3FELI0`
Monitoring and Troubleshooting	`584L8PB3D1N6IOR1DGP10GRCDTQM8NQKA1ALUCPO70RJ0C9Q5H374OBDCLRMUSJBEDFIGL35DPPMUSJ6DHNNEB2VA1SN8RRICDK2ONQA85C2INPL60R38D1H8880G08I1H3MURR7DHII0GRCDTQM8`
Training and Inference	`584L8PB3D1N6IOR1DGP10GRCDTQM8NQKA1ALUCPO70RJ0C9Q256NAR3KD5PMOQB3CLFJIDPI6GO3CGGG100H4327DTNMER35411MORRLCG`
Deploy TPU workloads	`584L8PB3D1N6IOR1DGP10GRCDTQM8NQKA1ALUCPO70RJ0C9Q4926AS3CDTSLUL2GALFNERRIDDM6UOB4EDFMURIV8T5KANPJ60R32CPJ8880G08I1H3MURR7DHII0GRCDTQM8`

Google Kubernetes Engine（Google Kubernetes Engine > …）：

子类	classification.id
Deploy and Manage Workloads	`584L8PB3D1N6IOR1DGP1GIRLC9IN4RJ5EHIN6NQ5DPJMIRJ5BSR30C1J74SJK8I4CLO6ORRPBTGMSP2V9LGMSOB7CLFLERRIDDM6UOB4EDFJACHM6SSJ6GGG100H4327DTNMER35411MORRLCG`
Set up GKE clusters	`584L8PB3D1N6IOR1DGP1GIRLC9IN4RJ5EHIN6NQ5DPJMIRJ5BSR30C1J74SJK6IJCLQ5UTBGBT3KMHAVCDM7ASRKCLP76NPH6OQJ0CPL8880G08I1H3MURR7DHII0GRCDTQM8`
Manage and Optimize Clusters	`584L8PB3D1N6IOR1DGP1GIRLC9IN4RJ5EHIN6NQ5DPJMIRJ5BSR30C1J74SJK8QDC5N62PR5BTGMSP2V9TO78QBDD5T6ANQ3DHQN6T35E9PLUCHN74SJGE22204024GC8TNMUPRCCKG46R3FELI0`
GKE AI/ML	`584L8PB3D1N6IOR1DGP1GIRLC9IN4RJ5EHIN6NQ5DPJMIRJ5BSR30C1J74SJK7A4CLO6ORRPBT0KIBQD9HFLERRIDDM6UOB4EDFJAC9L60PJEGGG100H4327DTNMER35411MORRLCG`
Monitor	`584L8PB3D1N6IOR1DGP1GIRLC9IN4RJ5EHIN6NQ5DPJMIRJ5BSR30C1J74SJK3IDDTN6IT3FE9FJCD1J6CRJGGGG100H4327DTNMER35411MORRLCG`

Cloud Storage（Other Google Cloud Products > Cloud Storage > …）：

子类	classification.id
Making requests :: Request retry strategy	`584L8PB3D1N6IOR1DGP18GRCDTQM8NQJEHNN4OB7CLFJ4C9O6CO32EHG9LGMMQBECTFN4PBHELIN6T3JBST3KNQICLONAPBJEHFN4PBKE9SLUSRKE9GN8PB7F5FJ6D9M64PJEGGG100H4327DTNMER35411MORRLCG`
Manage objects :: Upload objects	`584L8PB3D1N6IOR1DGP18GRCDTQM8NQJEHNN4OB7CLFJ4C9O6CO32EHE8PN48EIVADIN4TJ9DPJJKNQ5E9P6USJJBSK6SRRE5LGNAT38BTP6AR31EHIM8AAV70OJGC1J6D1102012864ERRFCTM6A823DHNNAP0`
Manage objects :: Download objects	`584L8PB3D1N6IOR1DGP18GRCDTQM8NQJEHNN4OB7CLFJ4C9O6CO32EHF9TH6KPB3EHFKQOBEC5JMARB5DPQ5UEHQBT26UTREDHNM2P39DPJLUJR2D9IM6T3JBSSJ8C1N6SR444080490OHRFDTJMOP908DM6UTB4`
Manage storage buckets :: Bucket metadata and configuration	`584L8PB3D1N6IOR1DGP18GRCDTQM8NQJEHNN4OB7CLFJ4C9O6CO32EI29LGMSOB7CLFN6T3FE9GMEPAVC9QM6QR5EHPLUEHQBT17AORBCLQ5URB5EHGM8OBKC5FM2RJ4BTHMURJ6D5JNASJ1EHKMURIV6KS32E9K651102012864ERRFCTM6A823DHNNAP0`
Monitoring :: Bucket monitoring	`584L8PB3D1N6IOR1DGP18GRCDTQM8NQJEHNN4OB7CLFJ4C9O6CO32EH59LIN8PBID5N6EEIV9LNMSQBKDTP6IRJ7BSJ5UJ3FCTJMIRJ7BSPJEE9I70P444080490OHRFDTJMOP908DM6UTB4`

Skill 向使用者收集的细节（必须由人提供）：

受影响产品：Cloud TPU / GKE / GCS（据此从快速参考选 classification.id，必要时再细分子类）
问题标题（displayName）—— 只写英文
结构化描述（description）—— 双语，英文段在前、中文段在后；内容覆盖：目标 / 业务影响 / 错误现象（命令、日志、报错、截图）/ 实际 vs 预期 / 环境（编排、框架、TPU 型号、复现步骤）
优先级 P1–P4（团队约定不开 P0，每次必问，不设默认）
目标项目（PROJECT_ID），以及 parent 用 projects/ 还是 organizations/

以下字段为本 Skill 固定值，无需向用户提问：timeZone=Asia/Shanghai、languageCode=zh-CN、subscriberEmailAddresses=[wangyunpeng@google.com, peishiuanwu@google.com]。

description 推荐结构（沿用 Google 标准排查模板）：目标、业务影响、错误/失败详情、观察到的行为、预期行为、编排方案、存储方案、Guest OS、ML 框架与模型、其他细节。

双语格式约定：displayName 只写英文（单行简洁标题）；description 双语，英文在前、中文在后。例如：

text

displayName:
  TPU node pool delete stuck

description:
  [EN] Objective: ...; Business impact: ...; Error details: ...
  [CN] 目标：……；业务影响：……；错误详情：……

测试计划

预演验证：用 testCase: true 提交，确认 API 返回 2xx 且回显的字段正确（classification displayName 与预期一致），不会真正路由给工程师——这是 Skill 的内建"测试用例"。
干跑校验：对命令模板做参数替换检查（project、parent、分类 ID 是否已填、是否误留 testCase: true）。
流程演练：在测试项目上走一遍"预检 → 查分类 → 列已有 → 预演 → 确认 → 提交 → 查看评论 → 关闭"，验证每步命令可用。
难点：分类 ID 随产品目录变化，需依赖实时 caseClassifications:search 而非硬编码；不同支持等级/项目权限差异需在预检阶段尽早暴露。

影响范围

仅新增一个 Skill 文件，不改动站点构建或现有文档结构；对 VitePress nav/sidebar 无影响（Skill 不是站点页面）。
使用者需具备：本地已登录的 gcloud、对目标 project 的支持 API 权限、相应支持等级。
不引入新的依赖或服务，不存储凭证。
注意：.claude/skills/ 是否纳入站点构建/lint 需按仓库现状确认（参照 superpowers/ 被 srcExclude 排除的做法），避免影响 npm run docs:build 与 npm run lint。

实施计划

阶段一：确认仓库 Skill 的存放约定与命名（参考现有 superpowers/.claude/commands 结构），确定目录与是否需要在构建/lint 中排除。
阶段二：编写 SKILL.md（触发说明、预检、提问清单、命令模板、安全护栏）。
阶段三：在测试项目上端到端演练，校正命令与字段。
阶段四：提 PR，指定架构组 Review；合入后将本 RFC status 推进至 accepted/implemented。

风险与缓解

误提交正式 case：提交前 Skill 必须复述完整请求体，通过对话框让用户明确选择「真实 case / 测试 case / 取消」后才提交，默认为真实 case（testCase: false）。
凭证/权限问题：预检阶段先验证 gcloud auth、quota project 与支持等级，尽早给出可读的错误指引（如 403 → 提示设置 x-goog-user-project）。
分类 ID 失效或选错：始终通过实时 caseClassifications:search 获取，并让用户从候选 displayName 中确认，不硬编码。
信息泄露：description 可能包含项目/日志等敏感信息，Skill 应提醒使用者注意脱敏，且不把凭证写入文件。
API 变更：Cloud Support API 若调整字段/端点，需更新 Skill；通过测试演练定期校验。

RFC-0031: 基于 Cloud Support API 的开 Case Skill ​

概述 ​

背景与动机 ​

目标 ​

非目标 ​

方案 ​

用户故事（可选） ​

备选方案 ​

约束与注意事项（可选） ​

设计细节 ​

测试计划 ​

影响范围 ​

实施计划 ​

风险与缓解 ​

RFC-0031: 基于 Cloud Support API 的开 Case Skill

概述

背景与动机

目标

非目标

方案

用户故事（可选）

备选方案

约束与注意事项（可选）

设计细节

测试计划

影响范围

实施计划

风险与缓解