name: yaml-authoring description: 创建和验证YAML图表文件。在编写新图表或排查YAML语法问题时使用。

YAML图表编写

基本结构

version: 1
docId: 唯一文档标识符
title: "我的架构图"  # 可选

nodes:
  - id: 唯一标识符
    provider: aws  # 提供商名称（例如：aws、gcp、azure）
    kind: compute.lambda  # 服务类别.类型
    label: "显示名称"  # 可选
    parent: 容器标识符  # 可选，用于嵌套在VPC/子网中
    layout:  # 子节点可选（自动定位）
      x: 100  # 子节点可选
      y: 200  # 子节点可选
      w: 200  # 容器（VPC/子网）必需
      h: 150  # 容器必需

edges:
  - id: 边-1
    from: 源节点标识符
    to: 目标节点标识符
    label: "可选标签"  # 可选

自动布局

子节点（带parent）可以完全省略layout以实现自动定位：

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    layout: { x: 0, y: 0, w: 800, h: 600 }  # 容器：显式布局

  - id: ec2_1
    provider: aws
    kind: compute.ec2
    parent: vpc
    # 无布局 - 自动定位在(40, 40)

  - id: ec2_2
    provider: aws
    kind: compute.ec2
    parent: vpc
    # 无布局 - 自动定位在(200, 40)

自动布局规则：

每行3列
60px内边距，160px水平间距，140px垂直间距
显式x/y会覆盖自动定位
不能仅指定x或仅指定y（要么两者都指定，要么都不指定）

节点类型类别

kind字段使用分层格式：类别.类型或类别.子类别.类型

容器类型（布局中需要w/h）

类型	描述
`network.vpc`	虚拟私有云
`network.subnet`	VPC内的子网

资源类型

类别	类型示例
`compute`	`compute.lambda`、`compute.ec2`、`compute.ecs`、`compute.eks`
`compute.lb`	`compute.lb.alb`、`compute.lb.nlb`、`compute.lb.elb`
`database`	`database.dynamodb`、`database.rds`、`database.aurora`
`storage`	`storage.s3`、`storage.efs`、`storage.ebs`
`integration`	`integration.apiGateway`、`integration.sns`、`integration.sqs`、`integration.eventBridge`
`security`	`security.iam`、`security.cognito`、`security.waf`
`analytics`	`analytics.kinesis`、`analytics.athena`、`analytics.glue`

示例

简单Lambda + S3

version: 1
docId: lambda-s3-example
title: "Lambda S3集成"

nodes:
  - id: fn
    provider: aws
    kind: compute.lambda
    label: "处理上传"
    layout:
      x: 100
      y: 100
  - id: bucket
    provider: aws
    kind: storage.s3
    label: "上传桶"
    layout:
      x: 300
      y: 100

edges:
  - id: fn-to-bucket
    from: fn
    to: bucket

API与数据库

version: 1
docId: api-db-example
title: "REST API架构"

nodes:
  - id: api
    provider: aws
    kind: integration.apiGateway
    label: "REST API"
    layout:
      x: 100
      y: 200
  - id: handler
    provider: aws
    kind: compute.lambda
    label: "处理器"
    layout:
      x: 300
      y: 200
  - id: db
    provider: aws
    kind: database.dynamodb
    label: "用户表"
    layout:
      x: 500
      y: 200

edges:
  - id: api-to-handler
    from: api
    to: handler
    label: "调用"
  - id: handler-to-db
    from: handler
    to: db
    label: "读/写"

带嵌套资源的VPC

version: 1
docId: vpc-example
title: "VPC架构"

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "生产VPC"
    layout:
      x: 50
      y: 50
      w: 600
      h: 400
  - id: public-subnet
    provider: aws
    kind: network.subnet
    label: "公共子网"
    parent: vpc
    layout:
      x: 70
      y: 100
      w: 250
      h: 300
  - id: alb
    provider: aws
    kind: compute.lb.alb
    label: "应用负载均衡器"
    parent: public-subnet
    layout:
      x: 100
      y: 150
  - id: lambda
    provider: aws
    kind: compute.lambda
    label: "API处理器"
    parent: public-subnet
    layout:
      x: 100
      y: 280

edges:
  - id: alb-to-lambda
    from: alb
    to: lambda

验证

# 验证并构建为JSON
bun run packages/cli/src/index.ts build diagram.yaml

# 带实时重载的服务（默认端口：3456）
bun run packages/cli/src/index.ts serve diagram.yaml

常见错误

缺少必填字段

错误：缺少必填字段 "version"
错误：缺少必填字段 "docId"

确保version和docId位于文档根目录。

重复ID

错误：重复的节点ID："my-node"

每个节点和边必须具有唯一的id。

缺少边ID

错误：边必须具有id

所有边都需要id字段。

缺少布局

错误：顶级节点需要layout
错误：顶级节点需要layout.x

顶级节点（无parent）必须具有包含x和y的layout。子节点可以省略布局以进行自动定位。

部分坐标

错误：layout.x和layout.y必须同时指定或同时省略

不能仅指定x或仅指定y。要么同时提供两者，要么两者都省略以进行自动布局。

无效的父引用

错误：节点 "child" 引用了未知的父节点："missing-vpc"

确保parent引用现有的容器节点。

缺少边目标

错误：边引用了未知节点："missing-id"

确保from和to引用现有的节点ID。

YAML语法错误

错误：第5行YAML解析错误

检查缩进（2个空格）和正确的引号使用。

提示

使用描述性ID：user-api而非n1
标签可以包含空格和特殊字符（使用引号）
使用parent将资源嵌套在VPC/子网容器内
容器节点（VPC、子网）需要在布局中指定w和h
子节点可以完全省略layout以实现自动网格定位
使用#进行注释以记录文档
kind字段灵活 - 使用对您的架构有意义的任何字符串