处理 Terraform/.tf/HCL…

适用于需要对 Terraform/HCL 配置做格式化、lint、语法验证、安全审计、provider 文档查询和 dry-run 检查的场景。

适用场景

解决思路

1. 按关键要求清单顺序执行：1 运行 `bash scripts/extract_tf_info_wrapper.sh <path>`；2 对显式和隐式所有 provider 做 Context7 查询，找不到则 WebSearch 回退；3 读 `references/security_checklist.md`；4 读 `references/best_practices.md`；5 运行 `terraform fmt`；6 运行 `tflint`，不可用则标记跳过；7 运行 `terraform init`（若未初始化）；8 运行 `terraform validate`；9 运行 `bash scripts/run_checkov.sh <path>`；10 将发现与 `security_checklist.md` 小节交叉引用；11 生成引用参考文件的报告；12 运行 `bash tests/test_regression.sh`；13 运行轻量 CI 检查 `bash -n`、`py_compile`、smoke。
2. 识别作用范围：判断目标是单个 Terraform 文件、目录还是多环境配置。
3. 运行 `bash scripts/extract_tf_info_wrapper.sh <path>` 提取 provider/module 信息；该脚本会自动处理 python-hcl2 依赖，若系统 Python 缺少 python-hcl2，默认在 `~/.cache/terraform-validator/` 下创建或复用缓存虚拟环境。
4. 解析 `extract_tf_info_wrapper.sh` 输出中的 providers 和 modules，用于后续 Context7 文档查询。
5. 对每个检测到的 provider（显式与隐式）执行 Context7 查询：调用 `mcp__context7__resolve-library-id` 查询 `terraform-provider-{name}`，再调用 `mcp__context7__query-docs` 获取版本特定指导。
6. 若 Context7 找不到 provider，使用 WebSearch 回退：查询 `"terraform-provider-{name} hashicorp documentation"`；特定版本查询 `"terraform-provider-{name} {version} documentation site:registry.terraform.io"`。
7. 对常见不在 Context7 中的 HashiCorp 工具 provider（random、null、local、time、tls、archive、external、http）直接使用 WebSearch，并在报告中记录 `Provider docs via WebSearch (not in Context7)`。
8. 检测隐式 provider：从资源类型前缀推断，例如 `random_*`→`random`、`null_*`→`null`、`local_*`→`local`、`tls_*`→`tls`、`time_*`→`time`、`archive_*`→`archive`、`http` 数据源→`http`、`external` 数据源→`external`。
9. 完整 provider 检测流程：解析 extract 输出；从 `providers` 数组获取显式 provider；从 `resources` 数组获取资源；对每个资源类型提取前缀；若前缀不在 providers 列表则添加为隐式 provider；对显式+隐式全部 provider 做 Context7 查询。
10. 安全扫描前必须阅读 `references/security_checklist.md`，理解安全检查和修复模式；验证期间阅读 `references/best_practices.md` 校验项目结构、命名和模式；出错时阅读 `references/common_errors.md` 查找解决方案；Terraform 1.10+ 阅读 `references/advanced_features.md` 了解 ephemeral values、actions、list resources。
11. 运行 `terraform fmt -recursive` 自动修复格式化，再运行 `terraform fmt -check -recursive` 验证无格式漂移，并报告格式化问题。
12. 运行 `tflint`（若不可用则标记为 skipped），可选先运行 `tflint --init` 安装插件，使用 `tflint --recursive` 和 `tflint --format compact` 进行递归与紧凑输出。
13. 若尚未初始化，运行 `terraform init` 下载 provider 和 module。
14. 运行 `terraform validate` 验证语法；也可运行 `terraform validate -json` 获取 JSON 输出；出错时查阅 `references/common_errors.md`。
15. 运行 `bash scripts/run_checkov.sh <path>` 执行安全扫描；必须使用包装脚本，而不是直接调用工具；可带选项如 `bash scripts/run_checkov.sh -f json ./terraform` 或 `bash scripts/run_checkov.sh --compact ./terraform`。
16. 对照 `references/security_checklist.md` 分析 Checkov 策略违规，并从参考文件中提供修复建议。
17. 如果凭据可用，运行 `terraform plan` 做干跑测试；分析计划变更并报告潜在问题；可选命令：`terraform plan -out=tfplan`、`terraform plan -var-file="production.tfvars"`、`terraform plan -target=aws_instance.example`。
18. 解释 `terraform plan` 输出符号：`+` 创建、`-` 销毁、`~` 修改、`-/+` 替换。
19. 将安全发现与 `security_checklist.md` 小节交叉引用，例如 `CKV_AWS_24`/`CKV_AWS_260`→"Overly Permissive Security Groups"，`CKV_AWS_16`→"Encryption at Rest"，`CKV_AWS_17`→"RDS Databases"，`CKV_AWS_130`→"Network Security"，`CKV_AWS_53-56`→"Public S3 Buckets"，`CKV_AWS_*` IAM→"IAM Security"，`CKV_AWS_79`→"ECS/EKS"，Hardcoded passwords→"Hardcoded Credentials"，Sensitive outputs→"Sensitive Output Exposure"。
20. 按报告模板输出安全发现：`Security Issue: [Check ID]`、`Finding`、`Resource`、`Severity`、`Reference`、`Remediation Pattern`、`Recommended Fix`；修复模式从 `security_checklist.md` 复制相关代码示例。
21. 运行回归测试 `bash tests/test_regression.sh`，确认解析器错误处理返回非零、隐式 provider 检测用于文档查询、包装器参数处理确定、checkov 包装器保留扫描器退出码。
22. 运行轻量 CI 检查：`bash -n scripts/*.sh`、`python3 -m py_compile scripts/*.py`、对示例 fixture 执行 extract wrapper 的 smoke check；记录命令输出和退出码。
23. 生成综合报告：包含所有发现及严重性，引用 `references/best_practices.md` 的建议，并在合适时提出自动修复。
24. 若工具缺失，按恢复工作流操作：检测缺失工具→告知用户缺少什么及为何需要→提供安装命令→询问 `Would you like me to install [tool] and continue?`→若同意则安装并重跑验证步骤→若不同意则在报告中标记为 skipped 并继续用可用工具。
25. 针对缺失工具的具体恢复：checkov 缺失时告知需要安全扫描，询问后用 `bash scripts/install_checkov.sh install` 安装并重跑；tflint 缺失时告知其提供高级 lint，询问安装并提供 `brew install tflint`（macOS）或 Linux 安装脚本；python-hcl2 缺失无需用户操作，包装器自动处理。
26. 记录必需工具：`terraform fmt`、`terraform init`、`terraform validate` 必需；`checkov` 是完整安全验证必需；`tflint` 可选但推荐。
27. 按脚本用途使用：`extract_tf_info_wrapper.sh` 解析 providers/modules 并自动处理依赖；`extract_tf_info.py` 是核心解析器但需 python-hcl2，应改用包装器；`run_checkov.sh` 是带增强输出的 Checkov 扫描包装器；`install_checkov.sh` 在隔离 venv 中安装 Checkov。
28. 脚本运行上下文：默认工作目录为 `devops-skills-plugin/skills/terraform-validator`；若从其他位置运行，使用绝对路径：`bash /absolute/path/to/terraform-validator/scripts/extract_tf_info_wrapper.sh <path>`、`bash /absolute/path/to/terraform-validator/scripts/run_checkov.sh <path>`、`bash /absolute/path/to/terraform-validator/scripts/install_checkov.sh install`。
29. 按参考文档阅读时机执行：安全扫描前读 `references/security_checklist.md`（安全验证、Checkov/Trivy 用法、常见策略、修复模式）；验证期间读 `references/best_practices.md`（项目结构、命名约定、模块设计、状态管理）；出错时读 `references/common_errors.md`（错误数据库）；Terraform >= 1.10 读 `references/advanced_features.md`（ephemeral values、Actions、List Resources）。
30. 单文件验证示例流程：`bash scripts/extract_tf_info_wrapper.sh main.tf`→对每个 provider 做 Context7 查询→读 `references/security_checklist.md` 和 `references/best_practices.md`→`terraform fmt -check main.tf`→`terraform init`（如需）和 `terraform validate`→`bash scripts/run_checkov.sh -f json main.tf`→报告并引用修复；自定义 provider 用 WebSearch。
31. 完整模块验证示例流程：识别目录中所有 `.tf` 文件→`bash scripts/extract_tf_info_wrapper.sh ./modules/vpc/`→对所有 provider 做 Context7 查询→读 `references/security_checklist.md` 和 `references/best_practices.md`→`terraform fmt -recursive`→`tflint --recursive` 或标记 skipped→`terraform init && terraform validate`→`bash scripts/run_checkov.sh ./modules/vpc/`→对照 `security_checklist.md` 分析→对照 `best_practices.md` 校验结构→提供带引用的综合报告。
32. 生产干跑示例流程：确认 terraform 已初始化→读 `references/security_checklist.md`（生产重点）→`terraform plan -var-file="production.tfvars"`→分析意外变更→突出创建/修改/销毁操作→标记安全问题并与 `security_checklist.md` 对比→建议是否可安全 apply。
33. 高级功能处理：Terraform 1.10+ 引入 ephemeral values 用于秘密管理；1.14+ 添加 Actions 和 List Resources；检测到 Terraform >=1.10、配置使用 `ephemeral` 块、`action` 块或 `.tfquery.hcl` 文件时，必须阅读 `references/advanced_features.md`。
34. 与其他技能集成：Terraform Kubernetes provider 验证用 k8s-yaml-validator；Terraform 管理 Helm releases 时用 helm-validator；调试 Terraform 配置的基础设施时用 k8s-debug。
35. 遵守执行顺序：提取信息→查询文档→读参考文件→格式化→lint→validate→安全扫描→plan。
36. 始终使用包装脚本执行 extract_tf_info 和 checkov。
37. 脚本变更后运行 `bash tests/test_regression.sh`。
38. 运行轻量 CI 检查：`bash -n scripts/*.sh` 和 `python3 -m py_compile scripts/*.py`。
39. 在相关验证步骤前阅读参考文件。
40. 通过 Context7 查询所有 provider 文档；找不到则 WebSearch。
41. 工具缺失时提供恢复/重跑选项。
42. 提交前必须运行 `terraform fmt`。
43. apply 前始终审查 plan 输出。
44. 为所有 provider 和 module 使用版本约束。
45. 团队协作使用远程 state。
46. 启用 state locking 防止并发修改。
47. 达到完成标准：验证指令可端到端执行并具有一条确定性命令路径；包装脚本在成功和失败路径行为可预测，包括传播非零退出；回归测试覆盖解析器错误处理、隐式 provider 检测、包装器参数处理、checkov 退出码行为；最终报告前轻量 CI 检查（`bash -n`、`py_compile`、smoke checks）通过。

适用边界 · 注意事项

• 没有 Terraform/HCL 文件，或不需要验证/审计 Terraform 配置时。
• 环境无法安装或运行 Terraform、Checkov、TFLint，且不能使用 Context7/WebSearch 查询 provider 文档时。
• 没有云凭据且必须执行 `terraform plan` 或 apply 验证时；此时只能做不依赖凭据的静态检查。