阿里云 Terraform 代码生成

将自然语言描述的阿里云基础设施需求转换为经过验证的 Terraform 代码，适用于当前 aliyun/alicloud 提供商。资源知识在生成时从提供商官方文档中实时获取——不维护本地的示例库。

硬性规则（严禁违反）

1. 凭证安全 —— 绝不泄露、绝不索取

绝不能在任何地方读取、打印、询问或写入 AK/SK 值——包括 HCL 文件、注释、环境变量声明、Shell 输出或日志。alicloud 提供商通过七种机制解析凭证（环境变量中的 AK/SK、共享的 config.json、ECS 实例 RAM 角色、Assume Role、OIDC/RRSA、Sidecar URI、静态 HCL）——详见 references/auth-and-network.md 中的完整链路。所有凭证读取均由提供商标记完成，本技能绝不介入。**禁止推荐已弃用的 ALICLOUD_* / ALIBABACLOUD_*（无下划线）环境变量名**——当前正确名称为 ALIBABA_CLOUD_ACCESS_KEY_ID / _ACCESS_KEY_SECRET / _SECURITY_TOKEN。

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

仅当对应命令实际执行且返回成功状态时，方可报告 fmt: ok / validate: ok / plan: ok。若某步骤被跳过（如工具缺失、用户选择跳过），必须明确标注 "SKIPPED"（或 "FAILED"），并附上原因。对真实输出进行合理转述可以接受；但不得虚构结果。

3. terraform apply 严格禁止

本技能绝不运行 terraform apply。plan 操作为可选（第 8 步）；apply 必须由用户自行执行。

环境建议（软性推荐）

• 推荐使用 Terraform ≥ 1.5。不要自动安装或下载 Terraform；第 6 步会检查 terraform 是否在 PATH 中，并报告实际验证状态。
• 网络连接为必需项——第 4.2 步需通过 WebFetch 获取每个资源的提供商标准文档。

工作流程

第一步：解析需求

提取以下信息：

• region —— 默认值为 cn-hangzhou。
• resources[] —— 包含 { alicloud_type, quantity, attributes }。
• 非功能性要求：多可用区、加密、备份、高可用性（HA）、IOPS。

若存在歧义（如“搭个数据库”），最多提出一次澄清问题。

第二步：确定目标目录

从用户请求中提取 <target-dir>（如显式路径 myshop-infra/，或未指定时使用当前工作目录）。后续所有 fmt / init / validate 命令均在此目录下运行。

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

mkdir -p <target-dir>

所有文件写入操作必须以 <target-dir>/ 为前缀——不得直接写入当前目录，也不得写入通用的 outputs/ 上级目录。生成完成后，验证目录结构：

ls -R <target-dir>

第三步：绘制架构草图

在编写任何 HCL 代码前，先绘制依赖关系表——每行一个资源：

• 将 resources[] 扩展为隐含基础设施（如 VPC → VSwitch → SecurityGroup → 工作负载）；用户通常会忽略这些。
• 扩展后的列表作为第 4 步的准入依据。

第四步：HCL 生成前检查（强制执行）

针对第 3 步中列出的每个独立 alicloud_* 类型（包括资源与数据源），依次执行 4.1 → 4.2 → 4.3。不同类型的调用可并行处理。

4.1 文档前查（目录 + 模式，可并行）

执行两个本地查找；在发起 WebFetch 前并行执行：

(a) 目录查询 —— 确认资源是否存在，并检查是否已弃用。目录文件 references/alicloud-providers.md 约 2600 行；不要一次性读取整份文件——使用 grep 只返回所需行：

grep "alicloud_<name>" references/alicloud-providers.md

三种结果：

• 找到匹配行，状态列为空 → 记录该行中的 [doc](<url>)；进入 4.2。
• **找到匹配行，状态为 ⚠️ 弃用 → <new_name>** → 将计划切换至 <new_name> 并重新查询。绝对不可输出已弃用名称。常见情况：alicloud_fc_function → alicloud_fcv3_function。
• 未找到匹配行 → 停止。询问用户是否拼写错误；**不得自行猜测生成 alicloud_<guess>**。

(b) 模式查询（条件性）—— 若用户需求符合 references/resource-patterns.md 中列出的产品特定模式（如 RDS 多可用区高可用、OSS 生命周期非当前版本、VPC 对等连接），则阅读相关章节。这些模式虽不在提供商标准的“必填”列表中，却是用户真正需要的功能（例如，RDS 跨可用区部署所需的 zone_id_slave_a 在文档中标记为可选，但实际部署必需）。忽略这些模式会导致“验证通过但结果错误”的输出。

当发现匹配的模式章节时，该章节“必填属性”表格中列出的所有属性都必须出现在生成的 HCL 中——即使提供商标记为可选，也应视为强制要求。

# 快速检查是否存在相关模式，然后仅读取该章节：
grep -in "<keyword>" references/resource-patterns.md

4.2 获取提供商标准文档（WebFetch）

从 4.1 中获取的文档 URL 执行 WebFetch。若失败或返回无效内容，直接根据目录行中的 doc URL 构造原始地址。保留目录中的类型标识：资源使用 website/docs/r/，数据源使用 website/docs/d/。

https://raw.githubusercontent.com/aliyun/terraform-provider-alicloud/master/website/docs/{r|d}/<doc_name>.html.markdown

若两者均失败，回退至本地目录行中的 references/alicloud-providers.md 内容。在复述部分前添加前缀 doc unreachable: used local catalog。不得访问其他任何 URL——仅允许上述两个 URL 或本地目录作为可信来源。

4.3 复述（证明已读）

在编写任何 HCL 之前，必须输出并确认每个资源的完整简要说明：

• 必填参数（直接引用文档原文，或在 4.2 回退时使用本地目录）
• 2–5 个与用户需求相关的关键可选参数
• 来自文档“示例用法”部分的最小 HCL 片段（仅当回退时才可注明 no example available）

如果必需或可选参数缺失，返回步骤 4.2。跳过或部分复述会导致硬失败；WebFetch 失败时使用 4.2 的回退机制，而非依赖记忆。

步骤 5. 生成

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

仅使用步骤 4.3 中确定的参数。若需要复述中未包含的参数，应通过更深入的阅读重新获取步骤 4.2 的内容；不得猜测。

在编写字段前，请查阅 references/deprecated-fields.md（详见 §5.6 中四种行类型及其处理规则）：

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

若用户需求涉及特定使用模式的产品（如 RDS 跨可用区高可用、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、可用区过滤）。

5.4 Provider 块（内容契约）

项目中 *.tf 文件任意位置必须包含两个 Terraform 块。Terraform 会合并同一目录下的所有 *.tf 文件，因此文件组织属于风格选择，而非契约——详见下方“文件组织”。

**块 1 — terraform { required_providers {} }**：

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

• Provider 版本：查找最新发布的稳定版 aliyun/alicloud 1.x 版本，然后写出悲观的次要版本约束（如 1.278.0 → ~> 1.278）。查找顺序如下：

1. https://registry.terraform.io/v1/providers/aliyun/alicloud/versions

2. https://registry.terraform.io/providers/aliyun/alicloud/latest

3. https://github.com/aliyun/terraform-provider-alicloud/releases 或 https://github.com/aliyun/terraform-provider-alicloud/tags

• 若查找失败，回退至 ~> 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-Skills/alibabacloud-terraform-code-generation"
}

• configuration_source 为归属标识，必须存在。
• region 必须引用 var.region，不可使用硬编码字面量。

文件组织（推荐，非强制）：常规拆分方式为 terraform.tf（块 1）+ providers.tf（块 2）。也可接受将两个块合并至单一 versions.tf，或任一区块置于 main.tf 文件顶部。根据项目实际情况选择即可——Terraform 会等效合并所有 *.tf 文件。禁止添加文件名检查，改用以下内容检查。

生成后验证（跨文件内容 grep 检查）：

# 1. required_providers 是否包含 aliyun/alicloud 且版本为 ~> 1.<minor>
awk '
  /required_providers[[:space:]]*{/ { in_req=1 }
  in_req && /alicloud[[:space:]]*=[[:space:]]*{/ { in_ali=1 }
  in_ali && /source[[:space:]]*=[[:space:]]*"aliyun\/alicloud"/ { source=1 }
  in_ali && /version[[:space:]]*=[[:space:]]*"~>[[:space:]]*1\.[0-9]+"/ { version=1 }
  in_ali && /^[[:space:]]*}/ { in_ali=0 }
  END { exit(source && version ? 0 : 1) }
' <target-dir>/*.tf \
  && echo OK_VERSION || echo BAD_OR_MISSING_VERSION

# 2. configuration_source 归属标识是否存在
grep -Rq 'configuration_source = "AlibabaCloud-Agent-Skills/alibabacloud-terraform-code-generation"' \
  <target-dir>/*.tf \
  && echo OK_CFG_SOURCE || echo MISSING_CFG_SOURCE

# 3. region 是否使用变量，而非硬编码
grep -Rq 'region\s*=\s*var\.region' <target-dir>/*.tf \
  && echo OK_REGION_VAR || echo HARDCODED_REGION

以上三项检查均需返回 OK。若任一项失败，需修正问题并重新运行——不得在存在失败的情况下进入步骤 6。

5.5 风格基准

• 使用 2 空格缩进；= 在块内对齐；资源标签采用 snake_case 语义命名（如 alicloud_vswitch.app_a，而非 vsw1）。
• 所有支持标签的资源都应包含非空的 tags 块，以保障运维规范性——根据场景选择合理键名（常见选项：ManagedBy、Project、Environment、CreatedBy）。本技能不指定具体标签键或值。

5.6 已废弃字段审计 —— 静态 grep 检查（必须通过）

在调用 terraform 之前执行——此为纯 grep 检查，针对你刚刚编写的 HCL 内容。对本次生成中的每个资源，使用 references/deprecated-fields.md 进行匹配，并按行类型处理：

• 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 行 → 停止使用该字段，无替代方案。

仅适用于本次生成的文件——不得修改用户原有未被要求改动的文件。

审计后验证（bash grep — 必须全部返回 OK）：

# 遍历 deprecated-fields.md 的每一行，检查生成的资源中是否仍使用了已弃用的字段。
# 使用 awk 提取单个资源块后再进行字段匹配，
# 以避免短字段名（如 name、document）错误地匹配复合字段名中的子串（如 role_name、policy_document）。
grep '| `alicloud_' references/deprecated-fields.md | while IFS='|' read _ resource field kind _; do
  resource=$(echo "$resource" | tr -d ' `')
  field=$(echo "$field" | tr -d ' ')
  kind=$(echo "$kind" | tr -d ' ')
  # 仅当该资源存在于生成的 HCL 中时才进行检查
  if grep -Rq "resource \"$resource\"" <target-dir>/*.tf; then
    case "$kind" in
      rename|deprecated-no-replacement)
        awk -v res="$resource" -v fld="$field" '
          $0 ~ "resource \"" res "\"" { in_block=1; next }
          in_block && /^}/ { in_block=0 }
          in_block && $0 ~ "(^|[^_[:alnum:]])" fld "([^_[:alnum:]]|$)" { found=1; exit }
          END { exit found ? 0 : 1 }
        ' <target-dir>/*.tf \
          && echo "DEPRECATED: $resource.$field" || echo "OK: $resource.$field"
        ;;
      split|soft-split)
        grep -q "\b$field\b\s*=" <target-dir>/*.tf \
          && echo "DEPRECATED: $resource.$field (inline — use standalone sub-resource)" \
          || echo "OK: $resource.$field (not inline)"
        ;;
    esac
  fi
done

硬性检查：必须在 Step 6 之前通过 —— 如果上述脚本输出任何 DEPRECATED: 行：

1. 逐行阅读每个 DEPRECATED: 输出 —— 它指明了资源名称和字段。
2. 在 references/deprecated-fields.md 中查找该资源+字段，获取 Action 列（如重命名目标、拆分为子资源等）。
3. 在 HCL 文件中应用对应的修复。
4. 重新运行验证脚本。
5. 重复此过程，直到所有输出均为 OK:。这是强制性关卡 —— 若存在任何 DEPRECATED: 输出，不得进入 Step 6。不得声称“已验证”，除非脚本返回全部 OK:。

Step 6. 验证 + provider 弃用检测

如果 terraform 命令在 PATH 中可用：

(cd <target-dir> \
  && terraform fmt -recursive \
  && terraform init -backend=false \
  && terraform validate -json)

循环执行，直到满足以下两个条件（最多尝试 3 次）：

1. 解析 validate -json 输出。若存在 错误 → 修复对应文件，然后返回 Step 3。
2. 检查 validate -json 中 diagnostics[].summary 是否包含 [DEPRECATED] 字符串。Provider 会发出权威的弃用标注（例如 "document": "[DEPRECATED] … New field 'assume_role_policy_document' instead."）。若发现 → 修复对应字段，然后返回 Step 3。
3. 重新运行 cd <target-dir> && terraform validate -json，并返回步骤 1。

仅当 validate 报告 **无错误且无 [DEPRECATED] 诊断信息** 时，退出循环。若经过 3 次尝试仍未达到此状态：进入 Step 7 时使用 Validation: FAILED (<diagnostic excerpt>)，并在可选备注中附上失败的 HCL 内容原文。

**若 init 因网络错误失败**（无法访问 registry.terraform.io）：

并非配置错误。请引导用户参考 references/auth-and-network.md 中的镜像源配置，然后进入 Step 7 —— Summary 必须使用 Validation: SKIPPED (init failed — network/unreachable)。不要盲目重试，也不要自行编写 ~/.terraformrc。

**若 terraform 不存在**：跳过此步骤，并在 Step 7 的 Summary 中明确说明（硬规则 §2），使用 Validation: SKIPPED (terraform binary not on PATH)。

Step 7. 覆盖率检查 + 总结

强制执行 —— 无论生成结果如何均需运行。即使前面步骤中断（如 init 网络失败、validate 循环耗尽、terraform 不在 PATH 中），此步骤也必须执行。Files written: 和 Validation: 行是与下游评估者之间的最终承诺 —— 跳过它们属于硬性失败。

覆盖率检查：枚举生成的 HCL 中的资源块，并与 Step 3 的草图进行对比。若草图中任何一行缺失，返回 Step 5 并补充 —— 不得因“用户未显式命名”而跳过某行。

总结模板 —— 使用用户语言打印，严格遵循以下结构（填充 <bracketed> 占位符，保留 Files written: 和 Validation: 两行标签原样）：

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

Validation: <one-of-four-exact-strings-below>

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

<optional: architecture notes, design decisions, deploy hints — free-form
here is fine, but NOT inside the lines above>

Validation: 行必须为以下精确字符串之一，根据 Step 6 实际情况选择。不得改写或合并进段落：

• Validation: terraform fmt+validate: ok
• Validation: SKIPPED (terraform binary not on PATH)
• Validation: SKIPPED (<reason>)
• Validation: FAILED (<diagnostic excerpt>) — 经过 3 次重试后达到上限

边缘情况：

• Init 超时 → Validation: FAILED (init timed out — provider installation exceeded time limit)
• Init 网络不可达 → Validation: SKIPPED (init failed — network/unreachable)
• init 在 fmt 成功后失败 → 使用根本原因字符串，而非混合状态。

(
  [[ -n "${ALIBABA_CLOUD_ACCESS_KEY_ID:-}" ]] && [[ -n "${ALIBABA_CLOUD_ACCESS_KEY_SECRET:-}" ]] && echo "ready:env-ak-sk"
  [[ -f "$HOME/.aliyun/config.json" ]]                                                           && echo "ready:shared-config"
  { [[ -n "${ALIBABA_CLOUD_CREDENTIALS_FILE:-}" ]] && [[ -f "${ALIBABA_CLOUD_CREDENTIALS_FILE}" ]]; } && echo "ready:custom-credentials-file"
  [[ -n "${ALIBABA_CLOUD_ECS_METADATA:-}" ]]                                                      && echo "ready:ecs-ram-role"
  [[ -n "${ALIBABA_CLOUD_ROLE_ARN:-}" ]]                                                          && echo "ready:assume-role"
  [[ -n "${ALIBABA_CLOUD_CREDENTIALS_URI:-}" ]]                                                   && echo "ready:sidecar"
) | head -1

• 任意输出行 → 表示存在可用的凭证路径：

(cd <target-dir> && terraform init && terraform plan -out=tfplan)；

输出该命令结果。

• 无输出 → 返回 NO_CREDENTIALS。向用户说明所有可能的凭证路径（环境变量 AK/SK、共享配置文件 ~/.aliyun/config.json 及 ALIBABA_CLOUD_PROFILE，ECS 实例 RAM 角色，角色假设链，OIDC/RRSA，Sidecar URI），不要仅提示环境变量 AK/SK。引导用户查阅 references/auth-and-network.md 完整配置说明。禁止读取或打印任何密钥值。

参考资料

本地目录为每个 alicloud_* 资源和数据源生成一行 Markdown 表格，包含 [doc](<url>) 列，弃用条目额外标注 ⚠️ 弃用 → <new_name>`。该表格由上游 Provider 仓库通过 scripts/build_alicloud_providers.py 脚本生成；当新版本 aliyun/alicloud` 发布并引入或调整弃用项时，请重新运行该脚本。