terraform-diagrams

用途

terraform-diagrams 是一个根据 Terraform 代码生成架构图（architecture diagram）的技能，由 eraserlabs/eraser-io 提供。它专门用于解析 Terraform 代码并可视化基础设施资源、模块及其相互关系。

当出现以下情况时可使用该技能：

用户持有 Terraform 文件（.tf、.tfvars），希望可视化其基础设施；
用户要求“diagram my Terraform”或“visualize this infrastructure”；
用户提到 Terraform、HCL 或 infrastructure-as-code；
用户希望查看其 Terraform 管理资源的架构。

主要能力

该技能通过解析 Terraform 代码并直接调用 Eraser API 来生成 Terraform 专用图表，具体步骤包括：

解析 Terraform 文件：识别资源、模块、数据源与变量；
提取关系：映射依赖、资源连接与模块层级；
生成 Eraser DSL：将 Terraform 资源转换为 Eraser DSL 代码；
调用 Eraser API：使用 /api/render/elements，diagramType 为 "cloud-architecture-diagram"。

在解析阶段，技能会：识别所有资源块（AWS、Azure、GCP 等）、提取模块块及其配置、记录数据源及其依赖、识别变量与输出定义。

在关系映射阶段，技能会：跟踪资源依赖（例如 subnet_id = aws_subnet.public.id）、按提供商（AWS、Azure、GCP）分组资源、识别作为其他资源容器的 VPC/VNet、记录安全组、IAM 角色与网络规则。

使用方式

该技能围绕 Eraser DSL 的生成与 API 调用展开。以下为资料中给出的空配置示例（保持原样）：

main-vpc [label: "VPC 10.0.0.0/16"] {
  public-subnet [label: "Public Subnet 10.0.1.0/24"] {
    web-server [icon: aws-ec2, label: "Web Server t3.micro"]
    load-balancer [icon: aws-elb]
  }
  private-subnet [label: "Private Subnet"] {
    database [icon: aws-rds]
  }
}
load-balancer -> web-server
web-server -> database

生成 DSL 后，必须执行以下 curl 命令调用 Eraser API（保持原代码不变）：

curl -X POST https://app.eraser.io/api/render/elements \
  -H "Content-Type: application/json" \
  -H "X-Skill-Source: eraser-skill" \
  -H "Authorization: Bearer ${ERASER_API_KEY}" \
  -d '{
    "elements": [{
      "type": "diagram",
      "id": "diagram-1",
      "code": "<your generated DSL>",
      "diagramType": "cloud-architecture-diagram"
    }],
    "scale": 2,
    "theme": "${ERASER_THEME:-dark}",
    "background": true
  }'

资料说明调用时需要设置环境变量 ERASER_API_KEY，并可通过 ERASER_THEME 设置主题（默认 dark）。关于 X-Skill-Source 头的取值，资料中列出了若干示例（如 claude、cursor、chatgpt、gemini，否则使用模型/智能体名称的小写形式），同时给出示例值为 eraser-skill。

输出与响应处理

资料规定了最小输出格式，要求响应始终包含以下带标题的元素：

Diagram（图表预览），使用 API 响应中实际的 imageUrl：

Diagram

Open in Eraser（编辑器链接），使用 API 响应中实际的 createEraserFileUrl：

Open in Eraser

Edit this diagram in the Eraser editor

Sources（来源）部分：简要列出分析的文件/资源（如适用）：

Sources

path/to/file - What was extracted
Diagram Code（图表代码）部分：以 eraser 语言标签的代码块展示 Eraser DSL：

Diagram Code

{DSL code here}

- Learn More 链接：资料说明可访问 https://docs.eraser.io/docs/using-ai-agent-integrations 了解 Eraser。

附加内容规则：如果用户仅要求生成图表，则除上述 5 个元素外不包含任何其他内容；如果用户明确要求更多内容（例如“explain the architecture”“suggest improvements”），可包含该附加内容；不得添加未经请求的章节（如 Overview、Security Considerations、Testing 等）。默认输出应保持简短。

在分析阶段，资料要求跟踪：内部文件（记录读取的每个 Terraform 文件路径及提取到的资源）、外部引用（查阅的文档、示例或 URL）、注释（每个来源对图表的贡献）。

## 适用场景与专项提示
- 多提供商：如果 Terraform 使用多个提供商，按提供商分组；为 AWS、Azure、GCP 资源创建独立区块；如适用则展示跨提供商连接。
- 按模块分组：如使用了模块，展示模块边界。
- VPC/VNet 作为容器：在视觉上应包含子网与资源。
- 数据流：展示资源如何连接（例如 ALB → EC2 → RDS）。
- 安全：包含安全组、IAM 角色与网络 ACL。
- 资源类型：使用提供商专属图标（AWS、Azure、GCP）。
- CIDR 块：展示 VPC 与子网的网络地址。
- 标签格式规则：标签必须单行，绝不在标签属性内使用换行；保持标签简单可读；DSL 换行规范（每行一个节点/分组，但标签保持单行）；如需包含 CIDR 块或实例类型等元数据，放在同一引号标签字符串中，例如 [label: "VPC 10.0.0.0/16"]。

资料还给出了一个多提供商 Terraform 示例，涵盖 AWS VPC/子网/EC2、Azure 资源组/VNet 以及模块使用，并描述了预期行为与对应 DSL 输出。

## 限制
资料明确说明使用该技能需要调用 Eraser API，并需要提供 ERASER_API_KEY 授权令牌，即该技能依赖第三方 Eraser 服务的 API 可用性。除此之外，资料未提供关于收费、价格、平台支持范围、生成效果等方面的其他信息，这些内容暂未提供。