规划、生成或执行 gcloud CLI 命令时，用叶级…

适用于所有 gcloud CLI 命令的规划、生成、语法查询与执行；不适用于编写 Google Cloud 客户端库代码或原始 REST/gRPC 请求。

适用场景

解决思路

1. 1. 在任何 gcloud 任务中，不要信任已有知识；在提出参数、输出标志、执行命令或列出步骤计划前，先验证叶级语法。
2. 2. 直接执行或生成代码时，始终在最终命令前调用 `gcloud help <leaf_command>`，例如 `gcloud help compute instances create` 或 `gcloud help sql instances create`。
3. 3. 对计划、策略或下一步查询，响应必须明确把运行 `gcloud help <leaf_command>` 作为计划 Step 1，再提出 flags 或执行命令。
4. 4. 叶级验证不可传递：父命令组 help（如 `gcloud help compute`）不够，必须在具体叶级子命令验证。
5. 5. 禁止用 `search_web`、网页搜索或外部文档搜索工具查 gcloud CLI 语法；`gcloud help <leaf_command>` 是唯一授权权威。
6. 6. 提出中间命令步骤时，始终保留用户指定的所有 flags（包括 `--project=<project_id>`）在响应文本中。
7. 7. 生成计划时必须复制 4 步模板：Step 1 Syntax Validation via `gcloud help <leaf_command>`；Step 2 Parameter Verification（确认必需和可选 flags，并明确检查是否支持 `--dry-run` 或 `--validate-only`）；Step 3 Dry-Run Command Proposal（若支持 `--dry-run` 或 `--validate-only`，下一步前必须有该调用）；Step 4 Command Proposal & Authorization（若命令在禁止操作 denylist，说明禁止自主执行，必须显式请求用户授权；否则按执行约束提议或执行）。
8. 8. 直接 CLI 执行：在本地或自动化 shell 中执行 gcloud 命令；安装、认证流程、配置管理参考 references/cli-usage.md。
9. 9. MCP：通过 Cloud CLI remote MCP server 的 `run_gcloud_command` 调用结构化工具；工具 schema、参数规则、服务器配置参考 references/mcp-usage.md。
10. 10. 显式命令验证：始终对打算运行的精确命令调用 `gcloud help <command>`，例如 `gcloud help compute instances create`。
11. 11. 在执行或展示计划前，确认命令、flags、flag values、位置参数语法对该具体叶命令有效；验证不能从父组传递。
12. 12. 数据缩减：尽量减少 gcloud 返回数据量；不对任何 `list` 命令执行除非至少包含一个数据缩减 flag（`--limit`、`--filter` 或 `--format`）。
13. 13. Projection：用 `--format="json(key1, key2, ...)"` 只选择任务需要的字段；高级 projection/formatting 语法参考 `gcloud topic projections` 和 `gcloud topic formats`。
14. 14. Limiting：用 `--limit=N` 限制返回资源数量。
15. 15. Filtering：用 `--filter` 在服务端缩小结果；模式匹配优先用 `:`，且不要给冒号右侧加引号；整个 filter flag 作为单个字符串，不要加引号或转义字符；filter 表达式语法参考 `gcloud topic filters`。
16. 16. Schema Discovery：执行查询前发现资源 schema；如果不确定投影字段（`--format`）或过滤（`--filter`）的 JSON key path，运行目标资源的 list 命令（若支持）并只取单项：`gcloud <GROUP> <RESOURCE> list --limit=1 --format=json`。
17. 17. 检查单项 JSON 结构，在请求完整或过滤数据集前安全识别正确 schema keys。
18. 18. 单命令执行：一次只执行一个 gcloud 命令，不串联或排序命令。
19. 19. 禁用 shell 操作符：不要用命令替换 `$(...)`、管道 `|`、重定向 `>`、`>>`、`<`。
20. 20. 非交互执行：所有执行命令都传全局 flag `--quiet`（或 `-q`），例如 `gcloud pubsub topics delete temp-topic --quiet --project=test-project`；避免 headless 环境等待 TTY 确认而卡住；使其自动接受安全默认或缺失必需参数时立即失败。
21. 21. 禁止盲目 list：绝不在没有 `--limit`、`--filter` 或 `--format` 时执行 `list` 命令。
22. 22. 显式项目目标：不要依赖 active configuration 默认值；对所有资源操作和查询命令始终追加 `--project=<PROJECT_ID>`（纯本地配置命令除外），避免错误项目执行。
23. 23. 防止位置提示：许多资源是 regional/zonal；若省略位置 flag（`--region`、`--zone` 或 `--location`），gcloud 会触发交互提示，违反非交互规则；命令需要时始终提供显式位置 flag。
24. 24. 位置发现：若不知道服务的正确 region、zone 或 location，先运行发现命令（结果多时限制数量）：Compute Engine（VMs、Networks）用 `gcloud compute regions list --project=<PROJECT_ID>`、`gcloud compute zones list --project=<PROJECT_ID>`；其他服务（标准 API 风格）用 `gcloud <GROUP> locations list --project=<PROJECT_ID>`，例如 `gcloud artifacts locations list`、`gcloud kms locations list`、`gcloud secrets locations list`。
25. 25. 破坏性动作（delete、update、remove）必须得到用户明确授权；除非在安全、预先批准的工作流中明确指示，否则绝不自主调用。
26. 26. 禁止操作 denylist：绝不自主执行以下命令，需要人类显式授权：任何 IAM policy、role 或 binding 修改（安全）；不要主动启用 API（假设必要 API 已启用，启用任何 API 需用户批准）；`gcloud * delete`（破坏性）；`gcloud billing *`（财务）；`gcloud organizations *`（治理）；`gcloud kms *`（加密）；`gcloud infra-manager deployments apply`（破坏性 IaC）。
27. 27. Dry Run 强制：如果命令 help 输出列出 `--dry-run` 或 `--validate-only` flag（或等效项），提议命令或初始执行步骤中始终包含它；实际执行前始终用 `--dry-run` 或 `--validate-only` 预览变更。
28. 28. 长时间运行操作：对支持的命令，强烈推荐用 `--async` 避免阻塞 agentic flow；注意不是所有命令都有 `--async`；对返回 operation ID 的命令（无论通过 `--async` 还是默认），如下一步需要，必须轮询 operation 状态直到完成。
29. 29. 所有提议或执行的命令都包含非交互 flag `--quiet`（或 `-q`）。
30. 30. Discovery Workflow：对不熟悉服务执行任务时，1) 执行前对目标叶命令调用 `gcloud help <COMMAND>`；2) 若不知道确切命令，对命令组运行 help（`gcloud help compute` 或 `gcloud help`）遍历命令树发现可用子组和命令；3) 运行 `gcloud <GROUP> <RESOURCE> list --limit=1 --format=json` 检查 JSON keys 再构造 filters/projections；不要执行未加范围限制（如 `--limit=1`）的 list 命令以免耗尽上下文；4) 所有命令执行都包含数据缩减 flags（`--limit`、`--filter`、`--format`）。
31. 31. Quick reference 模板：Discover Schema 用 `gcloud <GROUP> <RESOURCE> list --limit=1 --format=json`；Filtered List 用 `gcloud <GROUP> <RESOURCE> list --filter="status:RUNNING"`；Specific Columns 用 `gcloud <GROUP> <RESOURCE> list --format="json(name, id)"`；Learn Filters 用 `gcloud topic filters`；Learn Formats 用 `gcloud topic formats`；Learn Projections 用 `gcloud topic projections`；Asynchronous Op 用 `gcloud <COMMAND> --async`；Check Operation 用 `gcloud operations describe <OPERATION_ID>`；Common commands 用 `gcloud cheat-sheet`；List Regions (GCE) 用 `gcloud compute regions list --project=<PROJECT_ID>`；List Zones (GCE) 用 `gcloud compute zones list --project=<PROJECT_ID>`；List Locations 用 `gcloud <GROUP> locations list --project=<PROJECT_ID>`。
32. 32. 参考 gcloud CLI Scripting Guide 获取在自动化中使用 gcloud CLI 的指导。
33. 33. 需要 CLI 安装、认证（interactive、headless、ADC、service account keys、impersonation）和本地配置管理时参考 references/cli-usage.md。
34. 34. 使用 Cloud CLI remote MCP server（`run_gcloud_command`）、项目参数范围、输入文件和执行指南时参考 references/mcp-usage.md。

适用边界 · 注意事项

• 不适用于编写 Google Cloud 客户端库代码或原始 REST/gRPC API 请求。
• 不适用于没有 gcloud CLI 或 Cloud CLI MCP 工具/环境且无法执行 `gcloud help` 的场景。