architecture-diagram

架构图生成器

生成独立、完全可编辑的 .svg 文件：使用真实内嵌矢量图标（AWS/Azure/GCP 官方架构图标，或用于其他所有内容的手绘通用图标集）、确定性的区域感知布局、正交连接路由，以及真实的 <text> 标签。deliver --emit drawio 还会额外生成一个自包含、可编辑的 .drawio mxGraph 配套文件。SVG 输出不含栅格图像和 <use> 克隆；draw.io 输出使用可独立编辑的单元格，包含本地矢量图标数据，且不依赖远程图像、外部 URL 或提供商图形库。

适用场景

场景	使用此技能？
“绘制我们的 AWS/Azure/GCP 架构”	是
“用于文档的系统拓扑图”	是
“我需要之后在 Figma 中编辑此图”	是 — 这是它相较于所有栅格输出替代方案的差异化优势
多云或混合云（云端 + 本地）图	是 — 可为各节点自由混用 provider:
交互式、可点击跳转或带动画的图	否 — 使用 static-web-artifacts-builder
手绘 / 白板风格草图	否 — 使用 tldraw
数据图表、绘图或仪表盘	否 — 使用 chart-clarity
审查或评议现有架构	否 — 使用 architecture-reviewer
不含组件或连接的单帧概念插图	否 — 使用 concept-to-image

前置条件

在此技能目录（检出目录中的 skills/architecture-diagram）中运行以下命令。

• 已安装 pyyaml 的 python3（如果尚不可用，请使用 uv run --with pyyaml python3 -m engine ...）。

• 云服务提供商图标需要在每台机器上联网获取一次。 此技能不会捆绑图标；图标提供商会发布图表使用条款，因此 architecture-diagram 会在本地缓存中记录各提供商的来源和条款，而不是重新分发图标资源。图表首次需要某个提供商的图标时，请运行：

  python3 -m engine.fetch_icons --provider aws    # ~5s, 1037 icons
  python3 -m engine.fetch_icons --provider gcp    # ~5s, 297 icons
  python3 -m engine.fetch_icons --provider azure  # ~60s, 704 icons
  # or: --provider all
  

  此命令会构建本地缓存（默认路径为 ~/.cache/armory/cloud-icons，可通过 --cache-dir 或 $XDG_CACHE_HOME 覆盖），并固定到特定的 jgraph/drawio 提交，以确保输出可复现。每个渲染出的云图标都会根据其清单中的 SHA-256 摘要进行验证；icon/digest-mismatch 会失败并中止，且需要使用 python3 -m engine.fetch_icons --provider <provider> --force 重建提供商缓存。后续渲染会复用经过验证的缓存——每个提供商首次获取后，无需联网。provider: generic 完全无需获取；它使用 references/icons-generic.md 中捆绑的手绘图标集。

工作流

1. 解析用户的请求：组件（及其描述）、包含层级（区域 — VPC/Region/Resource Group/Subnet）、连接（如有指定，则包括语义类型）以及云提供商。
2. 将服务对应到图标。 对于每个云组件，读取 references/services-aws.yaml、references/services-azure.yaml 或 references/services-gcp.yaml（根据其提供商选择），非云组件则读取 references/icons-generic.md，并记下要用作该节点 service 字段的精确 slug。如果某项服务在该提供商的图标集中确实没有图标（各表中按提供商列有说明），则选择最接近的同类图标，或不设置 service — 渲染器会回退到带标签的占位符，而不是错误图标。
3. 确保每个所用提供商的图标缓存已预热（见先决条件）。对于 provider: generic，跳过此步骤。
4. 编写规范文件 — 按照 references/spec-format.md 编写一个小型 YAML 文件，包含：title、direction（LR/TB）、zones（嵌套时带有 parent）、nodes（id、label、service、zone、color）、edges（id、from、to、label、type）。
5. 验证，但不写入产物：

   python3 -m engine validate spec.yaml --quality showcase --json
   

   回执包含精确的规范文件和候选产物 SHA-256 摘要、验证计数、质量配置、组成状态以及编码诊断信息。validate 不会触碰输出路径。 对于已声明的 sources，添加 --verify-sources；该选项会依据规范文件检出目录中的本地 Git 提交、blob 和含首尾行的行范围进行失败即关闭验证。它要求存在 origin 远程，并且不会复制源内容或联系远程服务。 如果 Agent 需要精确查看已输出的节点框、区域成员关系及区域框、路由后的边路径点和边标签矩形以供审查，请使用 --layout-json 代替 --json。它也不会写入 SVG 输出。
6. 仅交付干净的候选产物：

   python3 -m engine deliver spec.yaml -o diagram.svg --quality showcase --emit drawio --json
   

   deliver 会将精确的规范文件和候选 SVG 暂存到目标文件旁，并且仅在所有检查通过后，才原子替换所有指定的输出。--emit drawio 也会交付 diagram.drawio；JSON 回执顶层的 artifacts 列表会记录每个已提交文件的路径、SHA-256 和字节数。使用 --verify-sources 时，它会原子交付 diagram.svg、diagram.drawio 和 diagram.sources.json；SVG 和 draw.io 输出带有本地 VERIFIED SRC n 徽标，而旁置文件会将已验证的引用绑定到已交付 SVG 的摘要。若捕获到写入或替换失败，则会恢复先前的文件组；进程在替换期间终止，不在此回滚保障范围内。
7. 交接前检查 draw.io 配套文件：
   1. 在 draw.io 中打开 diagram.drawio。
   2. 确认区域、节点容器、图标、节点标签、边和边标签均可单独选中。
   3. 移动节点标签并保存。输出会保留编写时的结构和初始计算位置；但不保证往返转换后 SVG 字节不变，也不保证保留手动路由。
8. 按需比较编写版本：

   python3 -m engine compare base.yaml head.yaml
   

   compare 会输出仅以编写的节点和边 ID 为键的 JSON 回执。它会报告新增、移除、变更、移动和重新路由的实体，并提供精确的字段路径。其强制限制是：仅比较编写的规范；不推断运行时影响、因果关系、风险或合并安全性。
9. 将最终 .svg 和请求的 .drawio 配套文件输出到工作目录或用户指定的路径。仅当这是某个提供商的首次渲染时，才提及图标缓存先决条件。

规范字段一览

完整架构和示例：references/spec-format.md。摘要：

title: string
direction: LR | TB        # default LR
provider: aws | azure | gcp | generic   # default provider for nodes that omit it
profile: deployment-ownership             # opt-in blocking deployment checks
sources:
  - id: string               # unique authored reference id
    revision: 40-char hex    # declared Git object id
    path: relative POSIX path
    lines: [start, end]      # positive inclusive range
zones:
  - id: string
    label: string
    parent: string | null # nesting — omit for a top-level zone
    kind: generic | region | security # default generic
nodes:
  - id: string             # unique
    label: string
    sublabel: string       # optional secondary line
    service: string        # icon cache slug — see services-aws.yaml / services-azure.yaml / services-gcp.yaml
    provider: string       # overrides the top-level provider for this node
    zone: string | null    # zone id this node belongs to
    color: "#RRGGBB"       # icon fill color
    owner: string          # required for non-external nodes under deployment-ownership
    external: boolean      # default false
    storage: boolean       # true requires a security zone under deployment-ownership
    sources: [source-id]     # optional declared source ids
edges:
  - id: string              # required and stable when using compare
    from: string            # node id
    to: string              # node id
    label: string           # required for security-boundary crossings under deployment-ownership
    type: realtime | batch | event | control | default
    sources: [source-id]     # optional declared source ids

部署所有权验证

仅当规范是部署所有权记录，而非纯视觉图表时，才设置 profile: deployment-ownership。此配置采用默认拒绝策略：每个节点都必须且只能归属到一个 kind: region，每个非外部节点都必须有非空的 owner，每个 storage: true 节点都必须位于 kind: security 内，跨安全区的边必须有非空标签，说明其机制。它绝不会根据标签、图标、服务标识或布局推断这些信息。省略 profile 可保留现有行为。

连接类型语义

类型	颜色	样式	用途
realtime	蓝色	实线	REST、gRPC、同步请求
batch	红色	虚线	SFTP、文件传输、计划任务
event	绿色	实线	发布-订阅、Webhook、事件驱动触发器
control	橙色	实线	管理平面、监控、配置推送
default	灰色	实线	未指定语义，或仅存在一种流类型时

只要图表中使用了多种连接类型，就会自动渲染图例；当所有边都为 default 时，则完全省略图例。

暂不支持／支持不完整

• Kubernetes 和本地部署提供商目前还没有专用图标集——可先使用 provider: generic 建模（references/icons-generic.md 中有 server、container、database、queue 等 31 种手绘字形，共 35 种），等待后续里程碑添加原生 K8s／本地部署图标支持。
• GCP 和 Azure 的图标覆盖范围小于 AWS（分别为 297 个和约 700 个图标，而 AWS 为 1037 个）。references/services-aws.yaml、references/services-azure.yaml 和 references/services-gcp.yaml 分别说明了各提供商的具体缺失项（例如，GCP 没有专用的 Vertex AI 或 Artifact Registry 图标；Azure 没有专用的 Pipelines／Boards／Artifacts 图标），而不会悄悄用容易造成误解的图标代替。
• 交互元素（点击跳转、动画、模式切换）不在支持范围内——此技能只生成单个静态 SVG。如需这些功能，请使用 static-web-artifacts-builder。
• PNG／PDF 导出不是内置功能。如需栅格格式，请在之后将 SVG 通过转换器处理：rsvg-convert diagram.svg -o diagram.png 或 cairosvg diagram.svg -o diagram.pdf。

常见模式

AWS 无服务器 API

title: Serverless API — us-east-1
provider: aws
direction: LR
zones:
  - id: vpc
    label: VPC 10.0.0.0/16
nodes:
  - id: cf
    label: CloudFront
    service: cloudfront
    color: "#8C4FFF"
  - id: apigw
    label: API Gateway
    service: api-gateway
    zone: vpc
    color: "#E7157B"
  - id: fn
    label: Lambda
    service: lambda
    zone: vpc
    color: "#ED7100"
  - id: ddb
    label: DynamoDB
    zone: vpc
    service: dynamodb
    color: "#C925D1"
edges:
  - {from: cf, to: apigw, label: HTTPS, type: realtime}
  - {from: apigw, to: fn, label: invoke, type: realtime}
  - {from: fn, to: ddb, label: query, type: realtime}

Azure Web 应用（从上到下）

title: Azure Web App
provider: azure
direction: TB
nodes:
  - {id: user, label: User, color: "#6B7280"}
  - {id: gw, label: App Gateway, service: application-gateways, color: "#0078D4"}
  - {id: app, label: App Service, service: app-services, color: "#0078D4"}
  - {id: db, label: SQL Database, service: sql-database, color: "#0078D4"}
edges:
  - {from: user, to: gw, label: HTTPS}
  - {from: gw, to: app}
  - {from: app, to: db, label: TDS}

多云流水线

可自由混用提供商——为每个节点设置 provider，而非在顶层设置：

title: Multi-Cloud Data Pipeline
direction: LR
nodes:
  - {id: ingest, label: Kinesis, provider: aws, service: kinesis, color: "#8C4FFF"}
  - {id: transform, label: Dataflow, provider: gcp, service: cloud-dataflow, color: "#4285F4"}
  - {id: notify, label: Logic Apps, provider: azure, service: logic-apps, color: "#0078D4"}
edges:
  - {from: ingest, to: transform, label: stream, type: event}
  - {from: transform, to: notify, label: alert, type: event}

与厂商无关／本地部署

对于没有云图标的节点，可省略 service（或设置 provider: generic）——它们会显示为带颜色的占位符，并使用标签的首字母：

title: On-Prem 3-Tier
provider: generic
direction: LR
nodes:
  - {id: lb, label: Nginx, color: "#3A3A3A"}
  - {id: app, label: App Servers, color: "#3A3A3A"}
  - {id: db, label: PostgreSQL, color: "#3A3A3A"}
edges:
  - {from: lb, to: app}
  - {from: app, to: db}

处理模糊情况

• 根据命名惯例推断区域嵌套关系（Region > VPC > Subnet、Resource Group > VNet > Subnet）。
• 用户未指定流语义时，默认使用 default 连接类型且不显示图例。
• 请求／数据流图默认使用 LR 方向，分层或层级图默认使用 TB 方向。
• 未指定云提供商或架构与厂商无关时，使用 provider: generic 和手绘图标集。
• 仅当组件列表或拓扑结构根本不清晰时才请求澄清——单个图标缺失时绝不请求澄清（按上文“暂不支持”中的说明回退处理）。

退出代码和诊断信息

每条发现都是带有 code、severity、message、subject（所涉及的对象）、evidence（用于定位的数字）、supported_fixes（规范层面的修改建议）以及有时还带有 suppresses 的编码诊断信息。退出代码就是判定结果：

退出代码	含义	操作
0	validate 已完成，且没有错误级别的发现；或 deliver 已原子性地提交通过验证的 SVG 套件	交付回执和请求的产物；任何警告都是有意为之且可解释的权衡
1	存在阻断性发现或交付操作失败	应用诊断中的 supported_fixes，或修正输出路径或文件系统权限
2	用法错误——缺少子命令、规范路径不可读、标志或配置文件值未知	修正命令

--json 会仅在 stdout 上输出回执，不包含其他内容。回执包含 input 和主 SVG 的 artifact SHA-256/字节数记录、output.written、validation.checks_passed/checks_total、质量、构图状态、严重级别计数和诊断信息。启用 --emit drawio 时，artifacts 会列出每个已提交输出的路径、SHA-256 和字节数。--quality showcase 会将 composition/* 路由几何问题提升为错误；默认的 standard 会将其保留为警告。

代码	含义	修复方法
spec/*	规范无法处理：没有节点、id 重复或缺失、未知区域/父级/边端点、区域循环、区域为空	每条诊断的 supported_fixes 会指出需要修改的字段
icon/not-found	该提供方的缓存中没有此 service slug，或者从未获取过缓存	使用该提供方参考服务映射中的准确 slug，或运行 fetch_icons.py --provider <name>；移除 service，以有意使用带标签的占位符
layout/node-overlap	两个节点框相互碰撞	将节点分隔到不同层级，或移除重复项
layout/zone-overlap	两个互不相关的区域框因其成员节点交错而相互碰撞	在 nodes 中连续列出每个区域的成员，或修正 zone 分配
layout/label-overflow	label 或 sublabel 在节点框内无法以最低 6px 字号完整显示（阻断性问题）	缩短文本，或将详细内容移入 sublabel
editability/*	输出包含栅格图像、<use> 或外部引用	渲染器错误——规范不会导致此问题；请报告
usage/spec-unreadable	规范路径不存在或无法读取	传入现有且可读取的 YAML 路径

获取失败（could not fetch <provider> icons）属于网络问题，而非规范问题：重新运行该提供方的 fetch_icons.py，该命令会跳过已缓存的图标。

输出

报告 SVG 路径、所请求的 draw.io 配套文件路径，以及任何尚未解决的警告级别发现及其原因。对于特定提供方，仅在首次渲染时说明图标缓存获取成本。

参考表

文件	内容	阅读时机
references/spec-format.md	完整的 YAML 规范架构，逐字段说明并列出边界情况	始终在编写规范前阅读
references/services-aws.yaml	AWS 服务名称 → 图标 slug + 颜色，约 70 项，并记录已知缺项	绘制 AWS 组件图时
references/services-azure.yaml	Azure 服务名称 → 图标 slug + 颜色，约 45 项，并记录已知缺项	绘制 Azure 组件图时
references/services-gcp.yaml	GCP 服务名称 → 图标 slug + 颜色，约 35 项，并记录已知缺项	绘制 GCP 组件图时
references/icons-generic.md	35 个手绘通用图标（服务器、数据库、队列、用户等），适用于非云图表	使用 provider: generic，或节点没有对应的云服务时
references/editability.md	说明为何输出绝不使用 <use>/栅格图像/转曲文本，以及“可编辑”实际验证的内容	了解或修改渲染器的输出约定时

引擎

文件	用途
engine/__main__.py	用于 validate、deliver 和 compare 的 python3 -m engine 入口点。
engine/pipeline.py	确定性地将规格组合并渲染为 SVG 结果。
engine/commands.py	验证、交付、比较回执、暂存和 CLI 分发。
engine/fetch_icons.py	本地图标缓存构建器；使用 python3 -m engine.fetch_icons 调用。
engine/stencil2svg.py	AWS/GCP 模板转 SVG 转换器 — 内部使用。
engine/svg_inline.py	Azure 原生 SVG 内联器/命名空间处理器 — 内部使用。
engine/data.py	用于捆绑资产和参考数据的统一解析器。

资产

文件	内容
assets/example-serverless.yaml	完整的真实规格（AWS、区域和混合连接类型）— 可复制并以此为起点
assets/example-serverless.svg	该规格实际渲染的输出，已提交以供参考
assets/generic-icons.json	BundledGenericIconLookup 读取的数据；references/icons-generic.md 是这份内容的 Agent 可读形式