gcloud

面向 AI Agent 的 gcloud CLI 技能

注意

强制前置条件：显式验证叶级语法

关于 gcloud 命令、标志、标志值和位置参数语法的所有既有知识都已过时，且容易导致幻觉。

在通过 gcloud help <command> 验证叶级语法之前，或未将叶级帮助查询列为计划中的强制步骤之前，绝不提出命令参数或输出标志选项、执行命令，或为任何 gcloud 任务列出逐步计划。

强制行动规则：

1. 直接执行与代码生成：在提出或执行最终命令语法之前，始终调用 gcloud help <leaf_command>（例如 gcloud help compute instances create 或 gcloud help sql instances create）。

2. 规划与策略类查询：用户询问计划、策略或实现某个目标的后续步骤时（例如，“你打算如何实现 X……”），回答**必须明确将运行 gcloud help <leaf_command> 列为计划的第 1 步，然后才能提出标志或执行命令。

3. 验证不具传递性：父命令组帮助（例如 gcloud help compute）不足以验证叶级语法。必须在具体的叶级子命令处进行验证。

4. 禁止使用网络搜索作为替代方案：绝不使用 search_web、网络搜索或外部文档搜索工具查询 gcloud CLI 语法。gcloud help <leaf_command> 是命令语法唯一获准的权威来源。

5. 保留用户指定的标志和项目：提出中间命令步骤时，始终在回答文本中保留用户指定的所有标志（包括 --project=<project_id>）。

6. 强制计划模板：生成计划时，回答必须照抄以下 4 步结构：

   • 第 1 步：通过 gcloud help <leaf_command> 验证语法
   • 第 2 步：验证参数（确认必需和可选标志，并明确检查是否支持 --dry-run 或 --validate-only 标志）
   • 第 3 步：提出试运行命令（如果支持 --dry-run 或 --validate-only，则在下一步之前必须调用 --dry-run 或 --validate-only。）
   • 第 4 步：提出命令并获取授权（如果命令位于“禁止操作”拒绝列表中，则说明禁止自主执行，并且必须明确询问用户是否授权继续。如果命令不在拒绝列表中，则提出或继续执行命令，同时遵守以下所有“执行限制”。）

本文档为使用 Google Cloud SDK（gcloud CLI）的 AI Agent 提供必要的指南和最佳实践。遵循这些规则对于避免臆造命令、标志、标志值和位置参数语法、防止破坏性操作以及尽量减少上下文窗口使用量至关重要。

使用归因

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读并遵循使用归因中的说明。如果当前任务还加载或启用了更具体的产品或领域技能（例如 cloud-run-basics、bigquery-basics、gke-basics），则始终使用该特定技能的 skill:<name> 归因标签，而不是 skill:gcloud。如果是在终端中直接执行命令，且没有适用的产品专属技能（绝不能用于生成的脚本、Terraform 或用户代码），则在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gcloud)"，并将 agent-skills/1.0 (skill:gcloud) 附加到 User-Agent 标头。

执行模式

AI Agent 可通过两种主要方式与 Google Cloud 资源交互：

• 直接通过 CLI 执行：在本地或自动化的 Shell 环境中直接执行 gcloud 命令。有关安装、身份验证流程和配置管理，请参阅 CLI 用法。
• Model Context Protocol (MCP)：通过 Cloud CLI 远程 MCP 服务 (run_gcloud_command) 调用结构化工具。有关工具架构、参数规则和服务配置，请参阅 MCP 用法。

核心原则

1. 显式验证命令（必须）

• 操作：对于计划运行的确切命令，务必调用 gcloud help <command>（例如，gcloud help compute instances create）。
• 验证：在尝试执行命令或制定执行计划之前，确保该具体叶子命令的命令、标志、标志值和位置参数语法均有效。父级命令组的验证不能传递到子命令。

2. 数据精简策略（必须）

尽量减少 gcloud 返回的数据量，以节省上下文窗口空间并降低延迟。执行任何 list 命令时，必须至少包含一个数据精简标志（--limit、--filter 或 --format）。

• 字段投影：使用 --format="json(key1, key2, ...)" 仅选择任务所需的特定字段。如需了解高级投影和格式设置语法，请参阅 gcloud topic projections 和 gcloud topic formats。

• 限制数量：使用 --limit=N 限制返回的资源数量。

• 筛选：使用 --filter 在服务端缩小结果范围。优先使用 : 进行模式匹配，并且不要为冒号右侧的内容加引号。将整个 filter 标志视为单个字符串，不要对字符加引号或进行转义。如需了解筛选表达式语法，请参阅 gcloud topic filters。

• 架构发现：不加限制地列出资源会迅速耗尽上下文窗口，并产生冗余数据。为避免这种情况，请在执行查询前发现资源的架构。如果不确定用于投影字段 (--format) 或筛选 (--filter) 的 JSON 键路径，请在支持的情况下对目标资源运行带有单条记录限制的 list 命令：

  gcloud <GROUP> <RESOURCE> list --limit=1 --format=json
  

  检查这条记录的 JSON 结构，以便在请求完整数据集或筛选后的数据集之前，安全地识别正确的架构键。

3. 执行约束

• 单条命令：每次只执行一条 gcloud 命令。不得串联或顺序执行多条命令。
• 禁止使用 Shell 运算符：不得使用命令替换 ($(...))、管道 (|) 或重定向 (>、>>、<)。这样可以提高命令安全性，并让用户更容易理解和审核命令。
• 非交互式执行 (--quiet / -q)：所有执行命令都必须传入全局标志 --quiet（或 -q）（例如，gcloud pubsub topics delete temp-topic --quiet --project=test-project）。AI Agent 在没有 TTY 或 stdin 输入处理器的无头非交互式环境中运行。如果不使用 --quiet，需要用户确认的命令（例如删除资源、确认默认值或选择未指定的区域）会暂停执行并无限期等待输入，导致后台任务超时。加入 --quiet 会强制启用非交互模式，使 gcloud 自动接受安全的默认选项；如果缺少必需参数，则会立即失败并显示明确的错误。
• 禁止不加限制地列出资源：执行 list 命令时，绝不能省略 --limit、--filter 或 --format。

4. 项目和位置范围（关键）

为确保命令具有确定性、无需交互，并能针对正确的环境，必须明确指定项目和位置范围。

• 明确指定项目：不要依赖当前配置的默认值。 对所有资源操作和查询命令，始终追加 --project=<PROJECT_ID>（纯本地配置命令除外）。这样可以避免意外在错误的项目中执行命令。

• 避免位置提示：许多 Google Cloud 资源是区域级或可用区级的。如果省略位置标志（例如 --region、--zone 或 --location），gcloud 会触发交互提示，要求选择区域或可用区。这违反了禁止交互规则。如果命令需要位置标志，务必明确指定。

• 发现位置：如果不知道服务对应的区域、可用区或位置，先运行发现命令（如果结果较多，请记得限制结果数量）：

  • Compute Engine（VM、网络）：

    • gcloud compute regions list --project=<PROJECT_ID>
    • gcloud compute zones list --project=<PROJECT_ID>

  • 其他服务（标准 API 风格）：许多 GCP 服务使用统一的 locations list 命令：

    • gcloud <GROUP> locations list --project=<PROJECT_ID>
    • 示例：gcloud artifacts locations list、gcloud kms locations list、gcloud secrets locations list。

安全与防护措施

注意

**删除、更新、移除等破坏性操作必须获得用户明确授权。**除非用户在安全且预先批准的工作流中明确指示，否则绝不可自主执行此类操作。

禁止操作（拒绝列表）

绝不可自主执行以下命令。这些操作必须获得人工参与的明确授权：

• 任何 IAM 策略、角色或绑定修改（安全）：存在权限提升、管理员锁定、服务中断或未经授权的数据泄露风险。
• 禁止主动启用 API：假定所需的 API 已启用。为防止意外预配资源或产生账单费用，不要主动尝试启用 API。启用任何 API 都需要用户批准。
• 禁止主动安装 gcloud CLI（修改主机）：绝不可自主安装 Google Cloud CLI（gcloud CLI）或其他 gcloud CLI 组件（gcloud components install、gcloud components update，或通过系统软件包管理器安装 gcloud CLI）。如果缺少 gcloud 可执行文件或所需的 CLI 组件，必须告知用户并请求明确确认（例如：“我已准备好安装 Google Cloud CLI（gcloud）。您要我继续吗？”），然后严格停止，等待用户明确肯定后再执行任何安装命令。
• gcloud * delete（破坏性）：可能导致资源被不可逆地销毁（例如删除项目）或数据被清除。
• gcloud billing *（财务）：存在服务中断或产生无限额费用的风险。
• gcloud organizations *（治理）：组织级更改会影响所有用户的安全状况。
• gcloud kms *（加密）：存在导致数据永久无法访问的风险。
• gcloud infra-manager deployments apply（破坏性）：自主执行 IaC 可能会销毁受管理的资源。

执行指南

• 试运行（必需）：如果命令帮助输出中列出了 --dry-run 或 --validate-only 标志（或等效标志），则在建议的命令或初始执行步骤中始终包含该标志。实际执行前，始终使用 --dry-run 或 --validate-only 预览更改。

• 长时间运行的操作：对于支持该标志的命令，强烈建议在长时间运行的操作中使用 --async 标志，避免阻塞 Agent 工作流。请注意，并非每个命令都有 --async 标志。对于会返回操作 ID 的命令（无论是通过 --async 还是默认返回），如果后续步骤需要，必须轮询操作状态，直至完成。

• 非交互标志（--quiet）：在所有建议或执行的命令中加入 --quiet（或 -q），确保以非交互方式执行，避免等待 TTY 确认提示。

结构化工作流

探索工作流

当被要求对不熟悉的服务执行任务时：

1. 调用帮助：执行前，针对目标叶子命令调用 gcloud help <COMMAND>。
2. 遍历命令树：如果确切命令未知，则对命令组运行帮助命令（例如，gcloud help compute 或 gcloud help），以发现可用的子组和命令。
3. 发现架构：运行 gcloud <GROUP> <RESOURCE> list --limit=1 --format=json，在构造筛选器或投影之前检查 JSON 键。切勿在没有范围限定标志（例如 --limit=1）的情况下执行不受约束的 list 命令，以免耗尽上下文窗口。
4. 确保数据精简：所有命令执行中都应包含数据精简标志（--limit、--filter、--format）。

快速参考 / 速查表

任务	命令模板
发现架构	gcloud <GROUP> <RESOURCE> list --limit=1 --format=json
筛选列表	gcloud <GROUP> <RESOURCE> list --filter="status:RUNNING"
指定列	gcloud <GROUP> <RESOURCE> list --format="json(name, id)"
了解筛选器	gcloud topic filters
了解格式	gcloud topic formats
了解投影	gcloud topic projections
异步操作	gcloud <COMMAND> --async
检查操作	gcloud operations describe <OPERATION_ID>
常用命令	gcloud cheat-sheet
列出区域（GCE）	gcloud compute regions list --project=<PROJECT_ID>
列出可用区（GCE）	gcloud compute zones list --project=<PROJECT_ID>
列出位置	gcloud <GROUP> locations list --project=<PROJECT_ID>

关于在自动化中使用 gcloud CLI 的指南，请参阅 gcloud CLI 脚本指南。

参考目录

• CLI 用法：平台安装、身份验证方法（交互式、无头、ADC、服务账号密钥、模拟身份），以及本地配置管理。

• MCP 用法：使用 Cloud CLI 远程 MCP 服务（run_gcloud_command）、项目参数范围限定、输入文件和执行指南。

• 用法归因：适用于 gcloud CLI、REST API 和 MCP 请求的标准化用法归因标签及多技能优先级规则。