architecture-diagrams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture Diagrams

架构图生成工具

Portable Claude Agent Skill

Professional architecture diagram generator using the Diagrams Python library. Produces publication-quality diagrams with real cloud provider icons (AWS, Azure, GCP, K8s, OnPrem, Generic).

Portability: This entire

architecture-diagrams/

folder is self-contained. Copy it to

~/.claude/skills/

or any project's

.claude/skills/

directory. Run

./scripts/setup.sh

once per location.

可移植的Claude Agent技能

基于Diagrams Python库的专业架构图生成工具。可生成带有真实云服务商图标（AWS、Azure、GCP、K8s、OnPrem、通用类）的出版级架构图。

可移植性：整个

architecture-diagrams/

文件夹是自包含的。你可以将其复制到

~/.claude/skills/

或任何项目的

.claude/skills/

目录下。每个安装位置只需运行一次

./scripts/setup.sh

。

Installation & Setup

安装与设置

System Prerequisite

系统前置要求

Graphviz must be installed system-wide (provides the

dot

binary):

bash

undefined

必须在系统全局安装Graphviz（提供

dot

二进制文件）：

bash

undefined

Ubuntu/Debian

sudo apt install graphviz

macOS

brew install graphviz

RHEL/Fedora

sudo dnf install graphviz

undefined

sudo dnf install graphviz

undefined

One-Time Setup (Per Installation Location)

一次性设置（每个安装位置仅需执行一次）

bash

cd <path-to>/architecture-diagrams/
chmod +x scripts/setup.sh
./scripts/setup.sh

This creates

.venv/

, installs Python dependencies, and verifies graphviz.

bash

cd <path-to>/architecture-diagrams/
chmod +x scripts/setup.sh
./scripts/setup.sh

该脚本会创建

.venv/

虚拟环境、安装Python依赖并验证Graphviz是否正常运行。

Automated Setup Check

自动化设置检查

bash

cd <path-to>/architecture-diagrams/
if [ ! -d ".venv" ]; then
  ./scripts/setup.sh
fi
echo "Skill ready"

bash

cd <path-to>/architecture-diagrams/
if [ ! -d ".venv" ]; then
  ./scripts/setup.sh
fi
echo "Skill ready"

Quick Start

快速开始

bash

undefined

bash

undefined

1. Navigate to your project directory

1. 导航到你的项目目录

cd ~/projects/my-project/

2. Set skill path for convenience

2. 为方便使用，设置技能路径

SKILL_DIR=~/.claude-wa/.claude/skills/architecture-diagrams

3. Verify setup

3. 验证设置是否完成

if [ ! -d "$SKILL_DIR/.venv" ]; then cd "$SKILL_DIR" && ./scripts/setup.sh && cd -; fi

4. Activate venv

4. 激活虚拟环境

source "$SKILL_DIR/.venv/bin/activate"

5. Create a diagram script in your project

5. 在项目中创建一个架构图脚本

cat > my-diagram.py << 'EOF' from diagrams import Diagram, Cluster from diagrams.aws.compute import EC2 from diagrams.aws.network import ELB

with Diagram("My Architecture", show=False): lb = ELB("Load Balancer") with Cluster("Web Tier"): web = [EC2("Web 1"), EC2("Web 2")] lb >> web EOF

cat > my-diagram.py << 'EOF' from diagrams import Diagram, Cluster from diagrams.aws.compute import EC2 from diagrams.aws.network import ELB

with Diagram("My Architecture", show=False): lb = ELB("Load Balancer") with Cluster("Web Tier"): web = [EC2("Web 1"), EC2("Web 2")] lb >> web EOF

6. Generate PNG (output goes to ./output/png/ in current directory)

6. 生成PNG格式图（输出文件会保存在当前目录的./output/png/下）

python "$SKILL_DIR/scripts/generate.py" my-diagram.py

Output: ~/projects/my-project/output/png/my-diagram.png

输出路径示例: ~/projects/my-project/output/png/my-diagram.png

undefined

undefined

File Structure

文件结构

architecture-diagrams/        <-- Skill root (portable)
  SKILL.md                    # This file
  requirements.txt            # Python deps (diagrams, graphviz)
  .venv/                      # Python virtual environment (created by setup.sh)
  scripts/
    setup.sh                  # Creates .venv and installs deps
    generate.py               # Runs diagram script, outputs to cwd/output/png/
  src/
    templates/                # Starter templates — copy these
      basic-template.py       # Minimal template with TODOs
    examples/                 # Working example diagrams
      cisco-network.py        # Network topology with routers, switches, firewall
      aws-architecture.py     # AWS cloud architecture with VPC, ALB, RDS
      kubernetes-cluster.py   # K8s cluster with namespaces, services, monitoring
  docs/
    icon-reference.md         # Index with top icons + navigation (load this first)
    icons/                    # Provider-specific icon catalogs (load on demand, all ≤450 lines)
      generic.md              # Generic infrastructure (26 icons)
      aws.md                  # Amazon Web Services (562 icons)
      azure-compute-network.md # Azure: Compute, Network, Database, Storage (~400 icons)
      azure-app-devops.md     # Azure: App Services, DevOps, Identity, Integration, IoT (~240 icons)
      azure-web-security.md   # Azure: Management, Security, Web Services (~170 icons)
      gcp.md                  # Google Cloud Platform (144 icons)
      kubernetes.md           # Kubernetes (69 icons)
      onprem.md               # On-Premise tools (211 icons)
      saas.md                 # SaaS providers (42 icons)
      programming.md          # Languages & frameworks (81 icons)
      elastic-firebase.md     # Elastic Stack, Firebase (~109 icons)
      digitalocean-ibm.md     # DigitalOcean, IBM Cloud (~309 icons)
      oracle-openstack.md     # Oracle OCI, OpenStack (~415 icons)
      outscale-alibaba-misc.md # Outscale, Alibaba, GIS, Custom, C4 (~220 icons)

architecture-diagrams/        <-- 技能根目录（可移植）
  SKILL.md                    # 本说明文件
  requirements.txt            # Python依赖（diagrams、graphviz）
  .venv/                      # Python虚拟环境（由setup.sh创建）
  scripts/
    setup.sh                  # 创建虚拟环境并安装依赖
    generate.py               # 运行架构图脚本，输出到当前目录的output/png/
  src/
    templates/                # 入门模板 — 可直接复制使用
      basic-template.py       # 带TODO提示的极简模板
    examples/                 # 可用的示例架构图
      cisco-network.py        # 包含路由器、交换机、防火墙的网络拓扑图
      aws-architecture.py     # 包含VPC、ALB、RDS的AWS云架构图
      kubernetes-cluster.py   # 包含命名空间、服务、监控的K8s集群图
  docs/
    icon-reference.md         # 图标索引（包含常用图标和导航，建议先查看）
    icons/                    # 各服务商专属图标目录（按需加载，每个文件≤450行）
      generic.md              # 通用基础设施图标（26个）
      aws.md                  # 亚马逊云服务图标（562个）
      azure-compute-network.md # Azure：计算、网络、数据库、存储类图标（约400个）
      azure-app-devops.md     # Azure：应用服务、DevOps、身份认证、集成、IoT类图标（约240个）
      azure-web-security.md   # Azure：管理、安全、Web服务类图标（约170个）
      gcp.md                  # 谷歌云平台图标（144个）
      kubernetes.md           # Kubernetes图标（69个）
      onprem.md               # 本地部署工具图标（211个）
      saas.md                 # SaaS服务商图标（42个）
      programming.md          # 编程语言与框架图标（81个）
      elastic-firebase.md     # Elastic Stack、Firebase类图标（约109个）
      digitalocean-ibm.md     # DigitalOcean、IBM云图标（约309个）
      oracle-openstack.md     # Oracle OCI、OpenStack类图标（约415个）
      outscale-alibaba-misc.md # Outscale、阿里云、GIS、自定义、C4类图标（约220个）

Output Path Behavior

输出路径规则

Diagrams are generated in

./output/png/

relative to your current working directory (not the skill directory). This means output appears in your project folder:

bash

undefined

架构图会生成在相对于你当前工作目录的

./output/png/

目录下（而非技能目录）。这意味着输出文件会保存在你的项目文件夹中：

bash

undefined

From your project directory

从你的项目目录执行

cd ~/projects/my-project/ python <skill>/scripts/generate.py diagram.py

Output: ~/projects/my-project/output/png/diagram.png

输出路径: ~/projects/my-project/output/png/diagram.png

Custom output directory

自定义输出目录

python <skill>/scripts/generate.py diagram.py --output-dir ./diagrams/

Output: ~/projects/my-project/diagrams/diagram.png

输出路径: ~/projects/my-project/diagrams/diagram.png

Absolute path

绝对路径输出

python <skill>/scripts/generate.py diagram.py --output-dir /tmp/diagrams/

Output: /tmp/diagrams/diagram.png

输出路径: /tmp/diagrams/diagram.png

undefined

undefined

Icon Reference (Progressive Disclosure)

图标参考（渐进式加载）

2634 icons across 17 providers, organized for efficient context loading:

Start with
docs/icon-reference.md
— Main index (~130 lines) with navigation table, top 30 most-used icons, and quick-start imports
Load provider files on demand from
```
docs/icons/
```
— Only load the specific provider file you need (e.g.,
```
docs/icons/aws.md
```
for AWS icons)

Provider File	Icons	When to Load
`icons/generic.md`	26	Network devices, OS, compute, storage
`icons/aws.md`	562	AWS cloud architecture
Azure (split):	810	Microsoft Azure - load as needed
`icons/azure-compute-network.md`	~400	Azure compute, network, database, storage
`icons/azure-app-devops.md`	~240	Azure app services, DevOps, identity, IoT
`icons/azure-web-security.md`	~170	Azure management, security, web
`icons/gcp.md`	144	GCP architecture
`icons/kubernetes.md`	69	K8s clusters, pods, services
`icons/onprem.md`	211	Self-hosted infra, databases, CI/CD
`icons/saas.md`	42	SaaS providers
`icons/programming.md`	81	Languages, frameworks
Other Clouds (split):	689	Other cloud providers - load as needed
`icons/elastic-firebase.md`	~109	Elastic Stack, Firebase
`icons/digitalocean-ibm.md`	~309	DigitalOcean, IBM Cloud
`icons/oracle-openstack.md`	~415	Oracle OCI, OpenStack
`icons/outscale-alibaba-misc.md`	~220	Outscale, Alibaba, GIS, Custom, C4

总计2634个图标，覆盖17个服务商，按类别组织以提升加载效率：

先查看
docs/icon-reference.md
— 主索引（约130行），包含导航表、30个最常用图标和快速导入示例
按需加载服务商文件 — 仅加载你需要的服务商图标文件（例如，使用AWS图标时加载
```
docs/icons/aws.md
```
）

服务商文件	图标数量	使用场景
`icons/generic.md`	26	网络设备、操作系统、计算、存储类
`icons/aws.md`	562	AWS云架构设计
Azure（拆分文件）：	810	微软Azure相关场景 - 按需加载
`icons/azure-compute-network.md`	~400	Azure计算、网络、数据库、存储类
`icons/azure-app-devops.md`	~240	Azure应用服务、DevOps、身份认证、IoT类
`icons/azure-web-security.md`	~170	Azure管理、安全、Web服务类
`icons/gcp.md`	144	GCP架构设计
`icons/kubernetes.md`	69	K8s集群、Pod、服务类
`icons/onprem.md`	211	自托管基础设施、数据库、CI/CD类
`icons/saas.md`	42	SaaS服务商类
`icons/programming.md`	81	编程语言、框架类
其他云服务商（拆分文件）：	689	其他云服务商场景 - 按需加载
`icons/elastic-firebase.md`	~109	Elastic Stack、Firebase类
`icons/digitalocean-ibm.md`	~309	DigitalOcean、IBM云类
`icons/oracle-openstack.md`	~415	Oracle OCI、OpenStack类
`icons/outscale-alibaba-misc.md`	~220	Outscale、阿里云、GIS、自定义、C4类

Core Concepts

核心概念

Diagram Context Manager

图形容器上下文

Every diagram uses the

Diagram

context manager:

python

from diagrams import Diagram, Cluster, Edge

with Diagram(
    "Diagram Title",          # Title shown on diagram
    filename="output-name",   # Output filename (no extension)
    outformat="png",          # png, jpg, svg, pdf, dot
    show=False,               # Don't auto-open
    direction="TB",           # TB, BT, LR, RL
    graph_attr={...},         # Graphviz attributes
):
    # nodes and connections here

每个架构图都需要使用

Diagram

上下文管理器：

python

from diagrams import Diagram, Cluster, Edge

with Diagram(
    "Diagram Title",          # 架构图标题
    filename="output-name",   # 输出文件名（无扩展名）
    outformat="png",          # 输出格式：png、jpg、svg、pdf、dot
    show=False,               # 生成后不自动打开
    direction="TB",           # 布局方向：TB、BT、LR、RL
    graph_attr={...},         # Graphviz属性
):
    # 在此处定义节点和连接关系

Direction

布局方向

Value	Meaning	Best For
`TB`	Top to bottom	Hierarchical architectures, network topologies
`BT`	Bottom to top	Data flow upward
`LR`	Left to right	Pipelines, data flow, timelines
`RL`	Right to left	Reverse flows

参数值	含义	适用场景
`TB`	从上到下	分层架构、网络拓扑图
`BT`	从下到上	数据向上流动的场景
`LR`	从左到右	流水线、数据流、时间线
`RL`	从右到左	反向数据流场景

Graph Attributes

图属性配置

python

graph_attr = {
    "fontsize": "14",       # Title font size
    "bgcolor": "#ffffff",   # Background color
    "pad": "0.5",           # Padding around diagram
    "nodesep": "0.6",       # Horizontal spacing
    "ranksep": "0.8",       # Vertical spacing between ranks
    "splines": "spline",    # Edge routing: spline, ortho, curved, polyline
    "concentrate": "true",  # Merge parallel edges
}

python

graph_attr = {
    "fontsize": "14",       # 标题字体大小
    "bgcolor": "#ffffff",   # 背景颜色
    "pad": "0.5",           # 图周围的内边距
    "nodesep": "0.6",       # 节点间水平间距
    "ranksep": "0.8",       # 不同层级间的垂直间距
    "splines": "spline",    # 连接线样式：spline、ortho、curved、polyline
    "concentrate": "true",  # 合并平行连接线
}

Node Providers Quick Reference

节点服务商快速参考

Generic (Network Infrastructure)

通用类（网络基础设施）

python

from diagrams.generic.network import Firewall, Router, Switch, Subnet, VPN
from diagrams.generic.compute import Rack
from diagrams.generic.database import SQL
from diagrams.generic.storage import Storage
from diagrams.generic.device import Mobile, Tablet
from diagrams.generic.place import Datacenter
from diagrams.generic.os import Ubuntu, Windows, LinuxGeneral, Debian, RedHat, CentOS
from diagrams.generic.virtualization import Vmware, Virtualbox, Qemu
from diagrams.generic.blank import Blank  # Invisible node for layout control

python

from diagrams.generic.network import Firewall, Router, Switch, Subnet, VPN
from diagrams.generic.compute import Rack
from diagrams.generic.database import SQL
from diagrams.generic.storage import Storage
from diagrams.generic.device import Mobile, Tablet
from diagrams.generic.place import Datacenter
from diagrams.generic.os import Ubuntu, Windows, LinuxGeneral, Debian, RedHat, CentOS
from diagrams.generic.virtualization import Vmware, Virtualbox, Qemu
from diagrams.generic.blank import Blank  # 用于布局控制的不可见节点

AWS

python

undefined

python

undefined

Compute

计算类

from diagrams.aws.compute import EC2, ECS, Lambda, Fargate, ElasticBeanstalk, Batch

Database

数据库类

from diagrams.aws.database import RDS, Aurora, Dynamodb, ElastiCache, Neptune, Redshift

Network

网络类

from diagrams.aws.network import ELB, Route53, CloudFront, VPC, APIGateway, DirectConnect

Storage

存储类

from diagrams.aws.storage import S3, EFS, FSx

Security

安全类

from diagrams.aws.security import Cognito, WAF, IAM, KMS, CertificateManager

Integration

集成类

from diagrams.aws.integration import SQS, SNS, Eventbridge, StepFunctions

Management

管理类

from diagrams.aws.management import Cloudwatch, Cloudformation, Cloudtrail, AutoScaling

Analytics

分析类

from diagrams.aws.analytics import Kinesis, Athena, Glue, EMR

General

通用类

from diagrams.aws.general import Users, Client

undefined

from diagrams.aws.general import Users, Client

undefined

Azure

python

from diagrams.azure.compute import VM, FunctionApps, ContainerInstances, KubernetesServices
from diagrams.azure.database import CosmosDb, SQLDatabases, CacheForRedis
from diagrams.azure.network import LoadBalancers, ApplicationGateway, DNS, VirtualNetworks
from diagrams.azure.storage import BlobStorage, StorageAccounts
from diagrams.azure.security import KeyVaults, ActiveDirectory
from diagrams.azure.integration import ServiceBus, EventGrid
from diagrams.azure.web import AppServices

python

from diagrams.azure.compute import VM, FunctionApps, ContainerInstances, KubernetesServices
from diagrams.azure.database import CosmosDb, SQLDatabases, CacheForRedis
from diagrams.azure.network import LoadBalancers, ApplicationGateway, DNS, VirtualNetworks
from diagrams.azure.storage import BlobStorage, StorageAccounts
from diagrams.azure.security import KeyVaults, ActiveDirectory
from diagrams.azure.integration import ServiceBus, EventGrid
from diagrams.azure.web import AppServices

GCP

python

from diagrams.gcp.compute import GCE, GKE, Functions, Run, AppEngine
from diagrams.gcp.database import SQL as GcpSQL, Spanner, Firestore, BigTable, Memorystore
from diagrams.gcp.network import LoadBalancing, CDN, DNS as GcpDNS, VPC as GcpVPC
from diagrams.gcp.storage import GCS
from diagrams.gcp.analytics import BigQuery, PubSub, Dataflow
from diagrams.gcp.security import IAP, KMS as GcpKMS

python

from diagrams.gcp.compute import GCE, GKE, Functions, Run, AppEngine
from diagrams.gcp.database import SQL as GcpSQL, Spanner, Firestore, BigTable, Memorystore
from diagrams.gcp.network import LoadBalancing, CDN, DNS as GcpDNS, VPC as GcpVPC
from diagrams.gcp.storage import GCS
from diagrams.gcp.analytics import BigQuery, PubSub, Dataflow
from diagrams.gcp.security import IAP, KMS as GcpKMS

Kubernetes

python

from diagrams.k8s.compute import Pod, Deployment, StatefulSet, ReplicaSet, Job, CronJob, DaemonSet
from diagrams.k8s.network import Ingress, Service, NetworkPolicy
from diagrams.k8s.storage import PV, PVC, StorageClass
from diagrams.k8s.rbac import ServiceAccount, Role, ClusterRole
from diagrams.k8s.infra import Node as K8sNode, Master
from diagrams.k8s.clusterconfig import HPA, ConfigMap, Secret
from diagrams.k8s.podconfig import Container

python

from diagrams.k8s.compute import Pod, Deployment, StatefulSet, ReplicaSet, Job, CronJob, DaemonSet
from diagrams.k8s.network import Ingress, Service, NetworkPolicy
from diagrams.k8s.storage import PV, PVC, StorageClass
from diagrams.k8s.rbac import ServiceAccount, Role, ClusterRole
from diagrams.k8s.infra import Node as K8sNode, Master
from diagrams.k8s.clusterconfig import HPA, ConfigMap, Secret
from diagrams.k8s.podconfig import Container

On-Premise

本地部署类

python

undefined

python

undefined

Network

网络类

from diagrams.onprem.network import Nginx, HAProxy, Traefik, Istio, Envoy, Consul, Kong, Apache

Database

数据库类

from diagrams.onprem.database import PostgreSQL, MySQL, MongoDB, Cassandra, Redis as OnPremRedis from diagrams.onprem.database import Neo4J, CockroachDB, InfluxDB, Clickhouse

Queue

消息队列类

from diagrams.onprem.queue import Kafka, RabbitMQ, ActiveMQ, Celery, Nats

Container

容器类

from diagrams.onprem.container import Docker

CI/CD

CI类

from diagrams.onprem.ci import Jenkins, GithubActions, GitlabCI, CircleCI from diagrams.onprem.cd import Spinnaker, Tekton from diagrams.onprem.gitops import ArgoCD, Flux

Monitoring

监控类

from diagrams.onprem.monitoring import Prometheus, Grafana, Datadog, Splunk, Nagios from diagrams.onprem.logging import Loki, Fluentbit from diagrams.onprem.tracing import Jaeger, Tempo

IAC

基础设施即代码类

from diagrams.onprem.iac import Terraform, Ansible

VCS

版本控制类

from diagrams.onprem.vcs import Git, Github, Gitlab

Analytics

分析类

from diagrams.onprem.analytics import Spark, Hadoop, Flink

Auth/Security

认证/安全类

from diagrams.onprem.security import Vault, Trivy

Workflow

工作流类

from diagrams.onprem.workflow import Airflow, Kubeflow, Nifi

In-Memory

内存存储类

from diagrams.onprem.inmemory import Redis, Memcached

Compute

计算类

from diagrams.onprem.compute import Server, Nomad

undefined

from diagrams.onprem.compute import Server, Nomad

undefined

Custom Icons

自定义图标

python

from diagrams.custom import Custom

python

from diagrams.custom import Custom

Use any local PNG/JPG image as a node icon

使用本地PNG/JPG图片作为节点图标

my_service = Custom("My Service", "./path/to/icon.png")

undefined

my_service = Custom("My Service", "./path/to/icon.png")

undefined

Clusters (Grouping)

集群（节点分组）

python

with Cluster("VPC"):
    with Cluster("Public Subnet"):
        web = EC2("Web")
    with Cluster("Private Subnet"):
        api = EC2("API")
        db = RDS("Database")

Cluster attributes:

python

with Cluster("Styled Group", graph_attr={
    "bgcolor": "#e8f4fd",     # Background color
    "style": "dashed",        # solid, dashed, dotted, rounded
    "color": "#2196F3",       # Border color
    "penwidth": "2.0",        # Border width
    "fontsize": "12",         # Label font size
    "fontcolor": "#333333",   # Label color
    "labeljust": "l",         # Label alignment: l, r, c
}):
    pass

python

with Cluster("VPC"):
    with Cluster("Public Subnet"):
        web = EC2("Web")
    with Cluster("Private Subnet"):
        api = EC2("API")
        db = RDS("Database")

集群属性配置：

python

with Cluster("Styled Group", graph_attr={
    "bgcolor": "#e8f4fd",     # 背景颜色
    "style": "dashed",        # 边框样式：solid、dashed、dotted、rounded
    "color": "#2196F3",       # 边框颜色
    "penwidth": "2.0",        # 边框宽度
    "fontsize": "12",         # 标签字体大小
    "fontcolor": "#333333",   # 标签颜色
    "labeljust": "l",         # 标签对齐方式：l、r、c
}):
    pass

Edges (Connections)

连接线（节点关系）

Basic Connections

基础连接

python

undefined

python

undefined

Forward direction

正向连接

node_a >> node_b

Backward direction

反向连接

node_a << node_b

Bidirectional (no arrows)

双向连接（无箭头）

node_a - node_b

One-to-many

一对多连接

node_a >> [node_b, node_c, node_d]

Chain

链式连接

node_a >> node_b >> node_c

undefined

node_a >> node_b >> node_c

undefined

Styled Edges

样式化连接线

python

from diagrams import Edge

node_a >> Edge(
    label="HTTPS",        # Text label on the edge
    color="blue",         # Edge color (name or hex)
    style="dashed",       # solid, dashed, dotted, bold
    minlen="2",           # Minimum edge length (ranks)
) >> node_b

python

from diagrams import Edge

node_a >> Edge(
    label="HTTPS",        # 连接线标签
    color="blue",         # 连接线颜色（名称或十六进制值）
    style="dashed",       # 连接线样式：solid、dashed、dotted、bold
    minlen="2",           # 最小连接线长度（层级间）
) >> node_b

Edge Style Patterns

连接线样式规范

Connection Type	Color	Style	Example
Synchronous API	`blue` or `navy`	`solid`	REST/gRPC calls
Async messaging	`orange` or `green`	`dashed`	Kafka, SQS, events
Database access	`purple` or `red`	`solid`	SQL queries
Replication	`gray`	`dashed`	DB replication
Monitoring	`gray`	`dotted`	Metrics/logs
External API	`brown` or `gold`	`solid`	Third-party
Cache	`red`	`solid`	Redis/Memcached
Storage	`brown`	`dotted`	S3, NFS, iSCSI

连接类型	颜色	样式	示例场景
同步API调用	`blue` 或 `navy`	`solid`	REST/gRPC调用
异步消息传递	`orange` 或 `green`	`dashed`	Kafka、SQS、事件通知
数据库访问	`purple` 或 `red`	`solid`	SQL查询
数据复制	`gray`	`dashed`	数据库同步
监控数据	`gray`	`dotted`	指标/日志采集
外部API调用	`brown` 或 `gold`	`solid`	第三方服务调用
缓存访问	`red`	`solid`	Redis/Memcached访问
存储访问	`brown`	`dotted`	S3、NFS、iSCSI访问

Output Formats

输出格式

Format	Flag	Use Case
PNG	`png` (default)	Documentation, presentations
SVG	`svg`	Scalable web embedding
PDF	`pdf`	Print-quality documents
JPG	`jpg`	Compressed images
DOT	`dot`	Graphviz source for manual editing

python

undefined

格式	参数值	适用场景
PNG	`png` （默认）	文档、演示文稿
SVG	`svg`	可缩放的网页嵌入
PDF	`pdf`	印刷级文档
JPG	`jpg`	压缩图片
DOT	`dot`	Graphviz源文件（用于手动编辑）

python

undefined

Single format

单一输出格式

with Diagram("Title", outformat="svg"): ...

Multiple formats at once

同时输出多种格式

with Diagram("Title", outformat=["png", "svg", "pdf"]): ...

undefined

with Diagram("Title", outformat=["png", "svg", "pdf"]): ...

undefined

Generate Script Usage

生成脚本使用说明

bash

undefined

bash

undefined

Set skill path

设置技能路径

SKILL=~/.claude-wa/.claude/skills/architecture-diagrams

Activate venv first

先激活虚拟环境

source "$SKILL/.venv/bin/activate"

Generate from example (output in ./output/png/)

生成示例图（输出到./output/png/）

python "$SKILL/scripts/generate.py" "$SKILL/src/examples/cisco-network.py"

Custom output name

自定义输出文件名

python "$SKILL/scripts/generate.py" "$SKILL/src/examples/cisco-network.py" --name my-network

SVG format

生成SVG格式

python "$SKILL/scripts/generate.py" "$SKILL/src/examples/aws-architecture.py" --outformat svg

Custom output directory

自定义输出目录

python "$SKILL/scripts/generate.py" "$SKILL/src/examples/aws-architecture.py" --output-dir ./my-diagrams/

Generate in a project directory

在项目目录中生成

cd ~/projects/my-project/ python "$SKILL/scripts/generate.py" my-diagram.py

Output: ~/projects/my-project/output/png/my-diagram.png

输出路径: ~/projects/my-project/output/png/my-diagram.png

undefined

undefined

Common Diagram Patterns

常见架构图模式

Network Topology

网络拓扑图

Layout:

TB

. Use

diagrams.generic.network

for Router, Switch, Firewall, VPN, Subnet. Cluster for DMZ, Internal, Management zones. See

src/examples/cisco-network.py

布局方向：

TB

。使用

diagrams.generic.network

中的Router、Switch、Firewall、VPN、Subnet节点。用Cluster分组DMZ区、内部区、管理区。参考示例

src/examples/cisco-network.py

。

Cloud Architecture

云架构图

Layout:

TB

. Use AWS/Azure/GCP provider icons. Cluster for VPC, subnets, AZs. Edge labels for protocols. See

src/examples/aws-architecture.py

布局方向：

TB

。使用AWS/Azure/GCP服务商图标。用Cluster分组VPC、子网、可用区。为连接线添加协议标签。参考示例

src/examples/aws-architecture.py

。

Kubernetes Cluster

Kubernetes集群图

Layout:

TB

. Use

diagrams.k8s

for Pod, Deployment, Service, Ingress. Cluster for namespaces. OnPrem for monitoring stack (Prometheus, Grafana). See

src/examples/kubernetes-cluster.py

布局方向：

TB

。使用

diagrams.k8s

中的Pod、Deployment、Service、Ingress节点。用Cluster分组命名空间。使用OnPrem类图标表示监控栈（Prometheus、Grafana）。参考示例

src/examples/kubernetes-cluster.py

。

Microservices

微服务架构图

Layout:

TB

LR

. Mix providers: OnPrem for services, AWS for infra. Cluster for service groups. Edge styles differentiate sync/async/data flows.

布局方向：

TB

或

LR

。混合使用不同服务商图标：用OnPrem类表示服务，用AWS类表示基础设施。用Cluster分组服务集群。通过连接线样式区分同步/异步/数据流。

CI/CD Pipeline

CI/CD流水线图

Layout:

LR

. Use

diagrams.onprem.ci

and

diagrams.onprem.cd

. Linear flow with branching for environments.

布局方向：

LR

。使用

diagrams.onprem.ci

和

diagrams.onprem.cd

类图标。采用线性流布局，为不同环境添加分支。

Common Mistakes

常见错误

Mistake	Fix
`ModuleNotFoundError: diagrams`	Activate venv first: `source .venv/bin/activate`
`ExecutableNotFound: dot`	Install graphviz: `sudo apt install graphviz`
Diagram opens in viewer	Set `show=False` in Diagram()
File saved in wrong directory	Output goes to `cwd/output/png/` — run from your project directory, or use `--output-dir`
Import error for provider class	Check exact class name at diagrams.mingrammer.com/docs/nodes/
Cluttered edges overlapping	Use `"splines": "ortho"` or `"concentrate": "true"` in graph_attr
Nodes too close together	Increase `nodesep` and `ranksep` in graph_attr
Diagram too large/small	Adjust `pad` , `fontsize` , and node count per cluster
Custom icon not found	Path must be relative to the script's working directory
Multiple outputs not working	Pass list to outformat: `outformat=["png", "svg"]`

错误	解决方法
`ModuleNotFoundError: diagrams`	先激活虚拟环境： `source .venv/bin/activate`
`ExecutableNotFound: dot`	安装Graphviz： `sudo apt install graphviz`
生成后自动打开查看器	在Diagram()中设置 `show=False`
文件保存到错误目录	输出文件默认保存在 `当前工作目录/output/png/` — 请从项目目录执行命令，或使用 `--output-dir` 指定路径
服务商类导入错误	访问diagrams.mingrammer.com/docs/nodes/检查类名是否正确
连接线重叠混乱	在graph_attr中设置 `"splines": "ortho"` 或 `"concentrate": "true"`
节点间距过近	在graph_attr中增大 `nodesep` 和 `ranksep` 的值
图过大/过小	调整 `pad` 、 `fontsize` 和每个Cluster中的节点数量
自定义图标无法显示	图标路径必须是相对于脚本工作目录的路径
无法同时输出多种格式	为outformat传入列表： `outformat=["png", "svg"]`

Troubleshooting

故障排除

Issue	Solution
`setup.sh` fails	Ensure Python 3.7+ and graphviz binary are installed
`.venv` creation fails	Try `python3 -m venv .venv --clear` to recreate
Blank/empty output	Verify nodes are defined inside the `with Diagram()` block
Permission denied on output	Check write permissions for `output/png/` directory
Slow generation	Large diagrams with many nodes are normal — reduce clusters or nodes
`dot` segfault	Update graphviz: `sudo apt install --only-upgrade graphviz`

问题	解决方法
`setup.sh` 执行失败	确保安装了Python 3.7+和Graphviz二进制文件
`.venv` 创建失败	尝试使用 `python3 -m venv .venv --clear` 重新创建
输出空白图	确保节点定义在 `with Diagram()` 上下文管理器内部
输出目录权限不足	检查 `output/png/` 目录的写入权限
生成速度慢	包含大量节点的大型图生成速度慢是正常现象 — 可减少Cluster或节点数量
`dot` 命令段错误	更新Graphviz： `sudo apt install --only-upgrade graphviz`