用途:为 AI 智能体提供使用 Google Cloud SDK(gcloud CLI)的规范与最佳实践,避免幻觉命令、标志、标志值或位置参数语法,防止破坏性操作,并减少上下文窗口占用。
主要能力与规则:
- 命令校验(强制):执行前必须对目标叶子命令调用 gcloud help <command>,确认命令、标志、标志值与位置参数语法有效,校验不可从父命令组传递。
- 数据精简:用 --format=json(key1, key2, ...) 只取所需字段;用 --limit=N 限制数量;用 --filter 服务端过滤,冒号右侧不加引号,整个过滤标志作为单一字符串。可用 gcloud topic projections、gcloud topic formats、gcloud topic filters 学习语法。
- 模式发现:不确定 JSON 键路径时,先运行 gcloud <GROUP> <RESOURCE> list --limit=1 --format=json 查看结构。
- 执行约束:一次只执行一条命令,不做命令链;不使用命令替换、管道或重定向;不运行交互式或需 TTY 的命令,须追加 --quiet(或 -q)。
- 项目与位置限定:所有资源操作与查询命令追加 --project=<PROJECT_ID>;命令需要位置时显式提供 --region、--zone 或 --location,避免交互提示。位置发现可用 gcloud compute regions list、gcloud compute zones list 或 gcloud <GROUP> locations list。
安全护栏:删除、更新、移除等破坏性操作必须经用户明确授权。拒绝清单包括:任何 IAM 策略、角色或绑定修改;主动启用 API;gcloud * delete;gcloud billing *;gcloud organizations *;gcloud kms *;gcloud infra-manager deployments apply。
执行指南:若命令支持 --dry-run 必须先预览;长时操作推荐 --async,并自行轮询操作状态。
认证方式:交互式 gcloud auth login;无浏览器环境加 --no-browser;应用默认凭据 gcloud auth application-default login;服务账号 gcloud auth activate-service-account --key-file=path/to/key.json;服务账号模拟 gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL(需 roles/iam.serviceAccountTokenCreator)。
限制:部分组织可能限制 JSON 密钥文件;并非所有命令都有 --async 或 --dry-run;具体安装方式参见官方 Google Cloud CLI 安装指南。