阿里云 Terraform 代码生成

将自然语言形式的阿里云基础设施需求转换为经过验证的 Terraform，以用于当前的 aliyun/alicloud 提供程序。资源架构和 验证通过 MCP 调用 IaCService 来完成；Terraform 提供程序文档和 本地参考文件用于确定 HCL 参数结构、示例、弃用项 以及特定产品的约束规则。

强制规则（绝不得违反）

1. 凭据——禁止泄露，也不得要求提供

禁止在任何位置读取、打印、索取或写入 AK/SK 值，包括 HCL、注释、环境变量 声明、命令行输出和日志。alicloud 提供程序解析凭据时 采用七种机制（环境变量 AK/SK、共享的 config.json、ECS 实例的 RAM 角色、Assume Role、OIDC/RRSA、边车 URI、静态 HCL）——完整链路见 references/auth-and-network.md。这些凭据均由 提供程序自身读取，禁止由此 skill 读取。不得推荐已弃用的 ALICLOUD_* / ALIBABACLOUD_*（无下划线）环境变量名称——当前名称为 ALIBABA_CLOUD_ACCESS_KEY_ID / _ACCESS_KEY_SECRET / _SECURITY_TOKEN。

2. 如实报告——不得声称执行过实际未执行的步骤

除非对应 命令确实已执行并且返回相应状态，否则禁止报告 fmt: ok / validate: ok / plan: ok。当某个步骤被跳过 （工具缺失或用户选择不执行）时，应注明 "SKIPPED"（或 "FAILED"）并 说明原因。可以转述真实输出，但不得捏造。

3. 禁止在本地执行 terraform

此 skill 禁止在本地运行 terraform，包括 fmt、init、validate、 plan 或 apply。验证通过 MCP 进行（第 6 步，通过 AlibabaCloud___CallCLI 调用 aliyun iacservice validate-module）。plan 和 apply 应在用户的部署工作流或 alibabacloud-spec-ops 执行 skill 中完成，而不属于此独立的代码生成 skill。

环境（建议性要求）

• MCP — 必须能够访问 alibabacloud-core MCP 服务器；所有

IaCService API 调用均通过 AlibabaCloud___CallCLI 进行。不得在本地调用 aliyun 或辅助脚本来访问 IaCService。

• IaCService 端点 — 使用 --endpoint iac.cn-zhangjiakou.aliyuncs.com

执行所有 IaCService 命令。不得根据 region 推导端点。

• 无需本地 Terraform 依赖 — 验证使用远程 IaCService

validate-module；无需本地 terraform 二进制文件。

工作流

第 1 步：解析需求

Extract:

• region — 默认值为 cn-hangzhou。
• resources[] — { alicloud_type, quantity, attributes }.
• 非功能需求：多 AZ、加密、备份、HA、IOPS。

如果含义不明确（例如 "搭个数据库"），最多提出 一个 澄清问题。

第 2 步：确定目标目录

从用户请求中提取 <target-dir>（例如显式路径 myshop-infra/；如果未指定，则使用当前工作目录）。后续所有 文件写入和静态 HCL 检查均在此目录中进行。远程验证 通过 MCP/IaCService 提交此目录中的文件。

在写入任何 .tf 文件之前，必须创建该目录：

mkdir -p <target-dir>

所有文件写入路径都必须以 <target-dir>/ 为前缀——禁止直接写入 当前工作目录，也禁止写入通用的 outputs/ 父目录。生成完成后，验证目录结构：

ls -R <target-dir>

第 3 步：勾勒架构

在编写任何 HCL 之前，先绘制依赖关系表，每项资源一行：

| 资源 | 依赖项 | AZ / 部署位置 | | --- | --- | --- |

• 扩展 resources[]，补充隐含的基础设施（VPC → VSwitch → SecurityGroup

→ 工作负载）；用户需求解析通常会漏掉这些内容。

• 扩展后的列表是第 4 步准入检查的输入。

第 4 步：HCL 编写前准入检查（强制要求）

对于第 3 步中的每种不同 alicloud_* 类型（资源和数据 源），依次执行 4.1 → 4.2 → 4.3。运行任何查询前，先构建 任务本地查询缓存：

• types[] — 第 3 步中去重后的最终资源/数据源名称。
• catalog[type] — 本地目录条目和提供程序文档 URL。
• product[type] — IaCService 产品；可根据

IaCService 元数据或资源命名确定。

• resource_type[type] — IaCService 架构响应或失败信息。
• example[type] — 选定的 IaCService 示例代码，仅在有用时保存。
• provider_doc[type] — GetProviderDocument 结果或备用文档，仅在需要时保存。

对于同一个键，禁止重复执行相同的 IaCService 调用、目录检索、模式查询或提供程序 文档获取。并行运行相互独立的查询：list-products、 目录检索和模式检索；然后按类型并行执行 get-resource-type。

4.1 文档前查询（并行执行 MCP 元数据、目录和模式查询）

写入 HCL 前，执行实时 MCP 元数据查询和本地定向查询。 优化为每个唯一键仅查询一次：

(a) 通过 MCP 获取 IaCService 元数据 — 当当前会话中提供了 AlibabaCloud___CallCLI 时，必须尝试实时查询元数据。不得静默跳过此 步骤。不得在本地 shell 中运行这些命令。

使用以下去重后的调用计划：

1. 每个生成任务调用一次 list-products。
2. 根据元数据、资源命名或任务缓存确定每种类型所属的产品。
3. 针对最终确定的每种不同 alicloud_* 类型，各调用一次 get-resource-type；调用应在

完成弃用路由之后进行；当 CallCLI 可用时，这是强制要求。

4. 仅当无法推断产品/资源类型时，才调用 list-resource-types。
5. 仅在以下情况下调用示例 APIs：复杂/嵌套资源、元数据不完整，或

存在无法通过元数据和本地参考资料修复的步骤 6 诊断问题。

aliyun iacservice list-products --endpoint iac.cn-zhangjiakou.aliyuncs.com
aliyun iacservice get-resource-type --resource-type alicloud_<name> --endpoint iac.cn-zhangjiakou.aliyuncs.com

# Conditional only:
aliyun iacservice list-resource-types --product <Product> --endpoint iac.cn-zhangjiakou.aliyuncs.com
aliyun iacservice list-resource-type-examples --resource-type alicloud_<name> --endpoint iac.cn-zhangjiakou.aliyuncs.com
aliyun iacservice get-resource-type-example --example-id <exampleId> --endpoint iac.cn-zhangjiakou.aliyuncs.com

在有相应信息时，使用元数据确定产品/资源可用性、必需属性、枚举 值、默认值、敏感性、ForceNew 和 Computed 约束。 对于每种不同类型，为步骤 4.3 和 步骤 7 记录以下元数据状态之一：

• ok — 包含产品/资源类型和架构来源；返回方为

IaCService.

• failed — 包含尝试执行的命令/API 及简要失败原因；

继续使用提供商文档和本地目录。

• skipped — 仅当 AlibabaCloud___CallCLI 工具未在

当前会话中提供时才允许；请原样注明该原因。

如果 CallCLI 可用，但你 未尝试执行 IaCService 命令，严禁报告 metadata constraints: SKIPPED。这是工作流失败；请返回并执行 元数据查询。如果 CallCLI 调用失败，请将该失败记录为 证据，并继续使用提供商文档和本地目录；不得 模拟 API 结果。

执行两项本地查询；与实时元数据查询并发运行：

(b) 目录查询 — 确认资源存在并检查是否弃用。 目录（references/alicloud-providers.md）约有 2600 行；不得 使用 Read 完整读取该文件。针对每个请求的类型使用精确表格行 grep；避免使用 alicloud_(vpc|instance) 这类子字符串 模式，因为它们会过度匹配：

for type in alicloud_vpc alicloud_vswitch alicloud_instance; do
  grep -E '^\| (resource|data source) \| `'"$type"'` \|' references/alicloud-providers.md
done

如果单个类型或路由后的替代项需要后续查询：

grep -E '^\| (resource|data source) \| `alicloud_<name>` \|' references/alicloud-providers.md

有三种结果：

• 找到行且状态列为空 → 记下该行中的 [doc](<url>)；

继续执行 4.2。

• 找到行且状态为 DEPRECATED -> <new_name> → 将方案切换为

<new_name>，然后重新查询。禁止输出已弃用的名称。常见疏漏： alicloud_fc_function → alicloud_fcv3_function。

• 找到行、状态为 DEPRECATED 且无替代项 → 停止并要求提供

受支持的替代方案；不得输出已弃用的资源/数据源。

• 未找到行 → 停止。询问用户该名称是否存在拼写错误；

不得臆造 alicloud_<guess>。

(c) 模式查询（条件性）— 如果用户需求与 references/resource-patterns.md 中列出的产品特定惯用模式匹配（例如 RDS 跨 AZ HA、OSS 生命周期非当前版本、VPC 对等连接），请阅读 相关章节。这些惯用模式不在提供商文档的*必需* 列表中，但它们才是用户实际需要的内容（例如，用于 RDS HA 的 zone_id_slave_a 在文档中是可选的，但要实现真正的跨 AZ 部署则是必需的）。 缺少这些内容会生成“验证通过但悄然出错”的输出。

找到匹配的模式章节后，该章节“必需属性”表中列出的所有 属性都必须出现在生成的 HCL 中 — 即使提供商文档将其标为可选，也要将其视为必需项。

# Quick check whether a relevant pattern exists, then Read only the section:
grep -inE "<keyword1>|<keyword2>" references/resource-patterns.md

针对用户的产品关键词运行一次模式 grep，而不是针对每个 资源各运行一次，然后缓存所有匹配的章节。

4.2 提供商文档回退（元数据优先）

当 IaCService 元数据和 4.1 中选定的官方 示例已包含生成 HCL 所需的足够架构信息和用法形式时，不得获取提供商文档。 获取提供商文档不是默认阶段；在快速路径中运行 WebFetch 属于工作流失败。

仅当元数据无法满足用户 需求或不完整、示例缺失或不足、步骤 6 的诊断问题无法 通过元数据和本地参考资料修复，或用户明确要求提供文档时，才获取提供商文档。

需要文档时，先通过 MCP 调用 IaCService get-provider-document。 使用 --endpoint iac.cn-zhangjiakou.aliyuncs.com，针对每种不同类型调用一次， 并缓存 provider_doc[type]。

如果 get-provider-document 失败，则回退到目录中的 GitHub URL/原始 URL。 如果所有文档渠道都失败，请使用本地目录以及 IaCService 在 4.1 中提供的元数据，并在复述前添加 doc unreachable: used metadata/local catalog。

4.3 复述（已读证明）

编写 HCL 前，针对每个资源输出一份简要说明：

• 仅列出必需参数名称，来源为 IaCService 元数据/文档/本地回退来源
• 与用户需求相关的 2–5 个关键可选/嵌套参数
• 来自 resource-patterns.md 的非显而易见模式属性（如有）
• 元数据约束，来源为 IaCService，或使用 `metadata constraints: SKIPPED

(<reason>) / metadata constraints: FAILED (<reason>)`

• 元数据证据 — 针对该类型尝试执行的 IaCService 命令/API 及

其状态（ok、failed 或 skipped）。如果缺少此行，则步骤 4 尚未完成，不得开始生成 HCL。

• 文档证据 — 快速路径使用 not fetched (metadata sufficient)，或

当 4.2 获取了文档时，提供提供商文档/原始 URL。

如果缺少必需或可选参数，请返回 4.2。跳过复述或使用 不完整的复述均属于硬性失败；元数据/文档获取失败时应使用本地目录 作为回退，而不是依赖记忆。

步骤 5. 生成

5.1 根据复述内容而非记忆编写 HCL

仅使用在 4.3 中确定的参数。如果所需参数未包含在 已复述的简报中，请重新获取 4.2 并深入阅读；不要猜测。 使用宿主客户端允许的最快批量写入方法（单次批量 编辑、脚本或 heredoc）；除非必要，否则避免逐文件串行写入。

写入字段前，请在 references/deprecated-fields.md 中查找该资源（请参阅 §5.5 的处理规则）：

grep '`alicloud_<resource>`' references/deprecated-fields.md

如果用户需求涉及具有特定用法模式的产品 （例如 RDS 跨 AZ HA、VPC 对等连接、OSS 生命周期），还应查阅 references/resource-patterns.md，了解不明显的属性。

5.2 数据源强制要求（强制要求 — 禁止硬编码 ID）

通过 data 块解析，禁止使用字面量。这些也能通过步骤 4 的门禁：

• zone_id → data "alicloud_zones"（按 available_resource_creation 筛选）。
• image_id → data "alicloud_images"（按 name_regex、owners = "system"、most_recent = true 筛选）。
• instance_type → data "alicloud_instance_types"（按 cpu_core_count、memory_size、AZ 筛选）。

为所有 variable 块生成 variables.tf；生成的每个 var.* 都必须具有类型和说明。生成 outputs.tf，用于输出有用的非敏感 资源 ID、端点和名称。Terraform 会以相同方式合并所有 *.tf。

5.3 提供程序块（内容契约）

项目的 *.tf 文件中必须在某处出现两个 Terraform 块。Terraform 会合并目录中的所有 *.tf，因此*文件组织 只是一种风格选择，而非契约*——请参阅下文“文件组织”。

Block 1 — terraform { required_providers {} }:

terraform {
  required_version = ">= 1.5"
  required_providers {
    alicloud = {
      source  = "aliyun/alicloud"
      version = "~> 1.274"
    }
  }
}

• 提供程序版本：最新发布的稳定版 aliyun/alicloud 1.x

版本应在 IaCService 元数据可用时通过该元数据解析，然后写入悲观式 次版本约束（1.278.0 -> ~> 1.278）。 查找源的使用顺序如下：

1. MCP AlibabaCloud___CallCLI with aliyun iacservice list-terraform-provider-versions

如果已安装的 MCP/代理版本支持。

2. MCP AlibabaCloud___CallCLI 元数据响应，其中包含提供程序

版本信息。

3. 提供程序注册表/GitHub 发布元数据，仅当宿主客户端具有

明确的安全文档获取机制时使用。

• 如果查找失败，则回退到 ~> 1.274。可接受的格式为 ~> 1.<minor>，

其基于已确认或保守选择的稳定 1.x 版本。不得写入开放式 约束（>= 1.x、>= 1.239.0）或裸版本字符串。

块 2 — provider "alicloud" {}，同时包含 region = var.region 和 configuration_source：

provider "alicloud" {
  region               = var.region
  configuration_source = "AlibabaCloud-Agent-Toolkit/alibabacloud-core"
}

• configuration_source 是归属标识签名——必须提供。
• region 必须引用 var.region，不得使用硬编码字面量。

文件组织（建议但非必需）：常规拆分方式为 terraform.tf（块 1）+ providers.tf（块 2）。也可以 使用一个同时包含两个块的 versions.tf，或将任一块放在 main.tf 顶部。请选择适合项目的方式——Terraform 会以相同方式合并所有 *.tf。不得添加文件名检查；应改为运行 下方的内容检查。

生成后验证：阅读 references/static-checks.md 并运行 提供程序块检查。三项检查都必须返回 OK。如果有任何一项失败，请修复 相应内容并重新运行——存在失败时不得继续执行步骤 6。

5.4 风格基线

• 使用 2 个空格缩进；块内的 = 对齐；使用具有语义的 snake_case 资源标签

(alicloud_vswitch.app_a, not vsw1).

• 每个支持标签的资源都应包含非空的 tags 块，以保障运维

规范——根据场景选择合理的键（常见选择： ManagedBy、Project、Environment、CreatedBy）。Skill 不会 规定具体的标签键或值。

5.5 已弃用字段审计——静态 grep 检查（强制要求）

在需要 terraform 之前运行——这是对刚刚写入的 HCL 执行的纯 grep 检查。对于本次生成中的每个资源，请使用 references/deprecated-fields.md 对项目执行 grep，并处理每种行类型：

• rename 行 → 如果旧字段名出现在刚刚写入的 HCL 中，

请将其替换为新字段名。最常出现的示例如下：

• alicloud_ram_role: name → role_name,

document → assume_role_policy_document

• alicloud_security_group: name → security_group_name
• alicloud_db_database: name → data_base_name
• split / soft-split 行 → 不得在父资源上写入内联字段。

仅当用户的需求 需要该能力，或 references/resource-patterns.md 表明 子资源具有明确的安全默认值时，才声明替代子资源。例如，对于 OSS 存储桶， alicloud_oss_bucket_acl 默认为 private，但除非用户要求这些功能，否则会省略日志/CORS/网站 子资源。

• deprecated-no-replacement 行 → 停止使用该字段，不提供替代项。

仅适用于本次生成中写入的文件——不得重构 用户原有且未要求修改的文件。

硬性门禁：必须在步骤 6 之前通过——阅读 references/static-checks.md 并运行已弃用字段审计。如果产生 任何 DEPRECATED: 行，请按照 references/deprecated-fields.md 中的操作列进行修复，然后重新运行，直到每一行都返回 OK:。 在仍有任何 DEPRECATED: 输出时，不得继续执行步骤 6。不得声称 “已验证”，除非脚本生成的所有结果均为 OK:。

步骤 6. 通过 IaCService 验证（远程，MCP）

严禁在本地运行 terraform fmt、terraform init 或 terraform validate 。验证在服务端运行，通过可用的 MCP 工具执行，该工具名称以 AlibabaCloud___CallCLI 结尾，并使用 aliyun iacservice validate-module。IaCService 后端会执行 Terraform 语法和模式验证，无需本地 Terraform 二进制文件、对 registry.terraform.io 的网络访问或后端初始化。 始终使用固定的张家口端点： --endpoint iac.cn-zhangjiakou.aliyuncs.com。不得将 Terraform 资源地域（例如 cn-hangzhou）用作 IaCService 端点地域。

阅读 references/iacservice-cli.md 以了解确切语法。优先使用快速路径： 在内存中拼接生成的 .tf 文件，并提交一个 --code 载荷。 --code-map 仅在以下情况下使用：需要特定于文件名的诊断，或 --code 意外失败。每次调用都生成一个新的 UUID --client-token。

循环直至验证通过（总计最多尝试修复 3 次）：

1. 解析 IaCService 响应。如果存在**错误 / 严重级别为

严重级别为 error** → 修复 <target-dir>/ 中出错的文件， 重新生成 --code 或 --code-map 载荷，然后转到步骤 3。

2. 扫描响应中的诊断信息，查找 [DEPRECATED] 字符串。提供程序

会生成权威的弃用注释（例如 "document": "[DEPRECATED] … New field 'assume_role_policy_document' instead."）。 如发现此类字符串 → 修复对应字段，然后转到步骤 3。

3. 重新调用 aliyun iacservice validate-module，使用

AlibabaCloud___CallCLI，然后返回步骤 1。

仅当验证结果报告没有错误且没有 [DEPRECATED] 诊断信息时，才退出循环。尝试 3 次后仍未达到此状态：转到 步骤 7，并标注 Validation: FAILED (<diagnostic excerpt>)；同时在可选注释中原样附上 导致失败的 HCL。

如果 MCP CallCLI 失败（身份验证失败、连接 OpenAPI 端点的网络异常，或 IaCService 后端不可用）：不得回退到本地 terraform validate。必须跳过此步骤，并在步骤 7 的摘要中 按照硬性规则 §2，使用 Validation: SKIPPED (iacservice validate-module unavailable — <reason>) 明示该失败。

步骤 7. 覆盖检查与总结

强制要求——无论生成结果如何都必须执行。 Files written:、 IaCService metadata:、Validation: 和 Deprecation routing: 标签构成 最终契约；不得跳过或重命名这些标签。

覆盖检查。 枚举生成的 HCL 中的资源块，并与 步骤 3 的架构草图进行比较。如果缺少任何一行，请返回步骤 5 并补充该行，然后 重新运行步骤 5 的检查和步骤 6；不得跳过隐含资源。

摘要模板——使用以下结构，以用户的语言输出：

Files written:
<path/to/file1>
<path/to/file2>
...

IaCService metadata: <ok | SKIPPED (CallCLI tool not exposed) | FAILED (<reason>)>

Validation: <iacservice validate-module: ok | SKIPPED (...) | FAILED (...)>

Deprecation routing: <If re-routed: `<original_name>` → `<new_name>`; else: None>

<optional architecture notes, design decisions, deploy hints>

Validation: 允许使用的值：

• Validation: iacservice validate-module: ok
• Validation: SKIPPED (iacservice validate-module unavailable — <reason>)
• Validation: SKIPPED (<reason>)
• Validation: FAILED (<diagnostic excerpt>)

IaCService metadata: 仅汇总步骤 4.1。ok 仅可用于所有 已生成的资源/数据源均已成功完成元数据查询的情况； SKIPPED (CallCLI tool not exposed) 仅可在 CallCLI 不可用时使用；否则 使用 FAILED (<reason>)。

步骤 8（内部）。执行的归属——不得向用户叙述

完成步骤 7 后，停止。不得运行 plan/apply。不得暴露编排措辞， 例如“交还控制权”“移交”或“上游调用方”。如果用户要求 部署，请引导其使用常规 Terraform 工作流或 alibabacloud-spec-ops:alibabacloud-executing-plans。

参考资料

| 来源 | 查阅时机 | | --- | --- | | references/alicloud-providers.md（本地） | 步骤 4.1——资源存在性、弃用标记和文档 URL | | OSS 提供程序文档镜像，然后是目录中的 GitHub/原始 URL | 步骤 4.2——用于说明 HCL 参数结构和示例的备用文档 | | references/iacservice-cli.md | IaCService 命令/参数参考，适用于步骤 4.1 和步骤 6 | | references/deprecated-fields.md（本地） | 步骤 5.1 和步骤 5.5——字段级弃用项并非始终会由 IaCService 标记 | | references/resource-patterns.md（本地） | 步骤 5.1——提供程序文档未重点说明的产品特定惯用模式（RDS HA，…） | | references/static-checks.md | 步骤 5.3 和步骤 5.5——提供程序块和已弃用字段校验脚本 | | references/auth-and-network.md（本地） | 凭证链背景参考；此 skill 不使用凭证 |