内容
# aws-excalidraw-template
用于绘制AWS架构图的Excalidraw模板仓库，包含官方AWS资产包图标、即用Excalidraw模板和两种创建图表的方式。
## 功能特点
| 功能 | 描述 |
|---------|-------------|
| **基于脚本的生成** | 任何代理都可以通过编写Python脚本并运行它来生成`.excalidraw`文件 — 无需Docker，无需VS Code |
| **`aet`命令行工具** | Go二进制文件：复制框架模板、列出服务图标、将图标添加到图表中 |
| **纸张大小框架** | Excalidraw模板，尺寸标准纸张（A1–A5，Letter，Legal，Tabloid ×纵向/横向） |
| **AWS架构框架** | 180+个变体，预建嵌套组框架（云→账户→区域→VPC→可用区→子网） |
| **服务目录** | `.excalidraw`文件，列出所有AWS图标（架构/资源/组/类别） |
| **MCP实时画布** | 可选：通过MCP工具从GitHub Copilot控制实时Excalidraw画布 |
## 前置条件
### 基于脚本的图表生成 *(无需额外设置)*
- **Python 3.10+** — 标准库，仅需，无需第三方包
### `aet`命令行工具 *(可选)*
- **Go 1.21+** — `go build -o .bin/aet ./cmd`
### MCP实时画布 *(可选)*
- Docker / Docker Compose
- VS Code + GitHub Copilot扩展
## 目录结构
```
.
├── docker-compose.yml # MCP画布服务器（端口3000）
├── doc/
│ └── COMMAND_SPEC.md # 完整的CLI命令参考
├── Asset-Package/ # 官方AWS图标SVG
│ ├── Architecture-Service-Icons/ # 服务图标（16/32/48/64像素每类别）
│ ├── Resource-Icons/ # 资源图标（48像素每类别）
│ ├── Architecture-Group-Icons/ # 组图标 （32像素）
│ └── Category-Icons/ # 类别图标（64像素）
├── etc/
│ ├── generate_aws_frames.py # 生成templates/aws-frames/**/*.excalidraw
│ ├── generate_catalog_scene.py # 生成templates/service-catalog.excalidraw
│ ├── excalidraw_helpers.py # 共享Python帮助程序（make_rect, make_text, …）
│ └── resources/
│ └── service-catalog.csv # AWS服务列表（名称，类别，SVG路径，base64）
├── pkg/ # Go源代码（控制器/存储库/实体）
├── cmd/ # Go CLI入口点
├── output/ # 生成的图表输出（git-ignored）
├── templates/
│ ├── service-catalog.excalidraw # 预生成的服务目录
│ ├── paper-frames/ # 纸张大小框架模板（16个文件）
│ │ ├── A4-portrait.excalidraw
│ │ └── ... (A1–A5, Letter, Legal, Tabloid × 纵向/横向)
│ └── aws-frames/ # AWS架构框架模板
│ ├── 1cloud-1account-1region-2az-3subnet/ # 默认变体
│ │ ├── A4-portrait.excalidraw
│ │ └── ... (16个纸张大小)
│ ├── 1cloud-1account-1region-2az-3subnet-staggered/
│ └── ... (180+个变体)
└── README.md
```
---
## `aet`命令行工具快速参考
> 完整规范：[doc/COMMAND_SPEC.md](doc/COMMAND_SPEC.md)
> 代理手册：[AGENTS.md](AGENTS.md)
```bash
# 构建
go build -o .bin/aet ./cmd
# 复制框架模板（默认：3个子网，2个可用区）
aet generate frames --size A4 --output output/my-diagram/
# 列出所有布局变体
aet generate frames --list-variants
# 复制服务目录
aet generate catalog
# 列出可用服务图标
aet list services --category Compute
aet list services --query "load balancing"
# 将图标添加到图表（单个）
aet add service --name "Amazon EC2" --file output/my-diagram/A4-portrait.excalidraw
# 从CSV列表中添加图标（批量）
aet add service --list services.csv --file output/my-diagram/A4-portrait.excalidraw
```
### 变体命名
```
<N>cloud-<N>account-<N>region-<N>az-<N>subnet[-staggered]
```
| 后缀 | 子网层 |
|--------|---------------|
| `2subnet` | 公共 + 私有 |
| `3subnet` | 公共 + 私有1 + 私有2 *(默认)* |
| `4subnet` | 公共 + 私有1 + 私有2 + 私有3 |
可用区布局：`grid`（默认平面布局）或`staggered`（重叠深度效果，可用区≥2）。
## 基于脚本的图表生成
任何代理（GitHub Copilot，Claude，Cursor，CI等）都可以通过编写Python脚本并运行它来生成架构图表。无需Docker或VS Code。
### 工作流程
```bash
# 1. 编写生成脚本 → etc/my_diagram.py
# 2. 运行它
python3 etc/my_diagram.py
# 3. 在Excalidraw中打开输出（https://excalidraw.com 或 VS Code扩展）
```
### 脚本模板
```python
#!/usr/bin/env python3
import json, os, base64, hashlib
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
GROUP_ICONS = os.path.join(BASE_DIR, "..", "Asset-Package", "Architecture-Group-Icons")
SVC_ICONS = os.path.join(BASE_DIR, "..", "Asset-Package", "Architecture-Service-Icons")
OUT_DIR = os.path.join(BASE_DIR, "..", "output")
W, H = 794, 1122 # A4 纸张，纵向 @ 96 dpi（见下表）
SEED = 1000
# --- 帮助程序（从generate_aws_frames.py复制或内联实现）---
# make_rect / make_text / make_image / make_frame / make_arrow / ensure_icon
elements, files = [], {}
# ... 构建元素 ...
os.makedirs(OUT_DIR, exist_ok=True)
scene = dict(type="excalidraw", version=2,
source="https://excalidraw.com",
elements=elements,
appState={"gridSize": None, "viewBackgroundColor": "#ffffff"},
files=files)
with open(os.path.join(OUT_DIR, "my-diagram-a4-portrait.excalidraw"), "w") as f:
json.dump(scene, f, ensure_ascii=False, indent=2)
```
### 元素生成器参考
| 函数签名 | 描述 |
|-------------------|-------------|
| `make_rect(id, x, y, w, h, stroke, stroke_style, fill, stroke_width)` | 矩形/组边框。`roundness=None`（锐角） |
| `make_text(id, x, y, w, h, text, font_size=12, color, bold)` | 文本标签 — Helvetica，12像素 |
| `make_image(id, x, y, w, h, file_id)` | SVG图标（先使用`ensure_icon`注册） |
| `make_arrow(id, x1, y1, x2, y2)` | 有向箭头 |
| `make_frame(id, x, y, w, h, name)` | 命名Excalidraw框架 |
| `ensure_icon(svg_path, files_dict)` | Base64编码SVG，在文件字典中注册，返回`file_id` |
关键约定：
- `roundness=None` — 所有矩形均为锐角
- 组图标：**32 × 32 像素**（来自`Architecture-Group-Icons/*.svg`）
- 服务图标：显示为**48 × 48 像素**，使用64像素SVG文件
- 字体大小：**12 像素**，所有标签
### 图标路径
```
# 服务图标
Asset-Package/Architecture-Service-Icons/{Category}/64/{Name}_64.svg
# 组图标
Asset-Package/Architecture-Group-Icons/{Name}_32.svg
```
常用服务图标类别：`Arch_Compute`，`Arch_Database`，`Arch_Storage`，
`Arch_Containers`，`Arch_Networking-Content-Delivery`，`Arch_Management-Governance`，
`Arch_Security-Identity-Compliance`，`Arch_App-Integration`
### 纸张尺寸 @ 96 dpi
| 尺寸 | 纵向（像素） | 横向（像素） |
|------|--------------|----------------|
| A5 | 559 × 794 | 794 × 559 |
| A4 | 794 × 1122 | 1122 × 794 |
| A3 | 1122 × 1587 | 1587 × 1122 |
| A2 | 1587 × 2245 | 2245 × 1587 |
| A1 | 2245 × 3179 | 3179 × 2245 |
| Letter | 816 × 1056 | 1056 × 816 |
| Legal | 816 × 1344 | 1344 × 816 |
| Tabloid | 1056 × 1632 | 1632 × 1056 |
---
## 模板
### 纸张框架（`templates/paper-frames/`）
16个文件 — 8种纸张尺寸 × 纵向/横向。
每个文件包含一个精确到纸张尺寸的Excalidraw `frame`元素。
### AWS架构框架（`templates/aws-frames/`）
180+个变体，每个包含16种纸张尺寸。
颜色遵循官方 [AWS Architecture Icons Deck for Light BG](https://aws.amazon.com/architecture/icons/)。
```
AWS 云 #242F3E 实线 2像素
└─ AWS 账户 #E7157B 实线 2像素
└─ 区域 #00A4A6 虚线 2像素
└─ VPC #8C4FFF 实线 2像素
└─ 可用区 [×N] #00A4A6 虚线 1像素
├─ 公共子网 #7AA116 实线 1像素
│ └─ 安全组 #9B0000 虚线 1像素
├─ 私有子网 1 #00A4A6 实线 1像素
│ └─ 安全组 #9B0000 虚线 1像素
└─ 私有子网 2 (3subnet / 4subnet)
└─ 安全组 #9B0000 虚线 1像素
```
重新生成：
```bash
python3 etc/generate_aws_frames.py
# → templates/aws-frames/<变体>/*.excalidraw
# → 180个变体 × 16个纸张尺寸 = 2,880个文件
```
## 服务目录
```bash
python3 etc/generate_catalog_scene.py
# → templates/service-catalog.excalidraw
```
| 目录 | 尺寸 | 前缀 |
|-----------|------|--------|
| `Architecture-Service-Icons/*/64/` | 64像素 | `[服务]` |
| `Resource-Icons/*/` | 48像素 | `[资源]` |
| `Architecture-Group-Icons/` | 32像素 | `[组]` |
| `Category-Icons/Arch-Category_64/` | 64像素 | `[类别]` |
---
## MCP实时画布设置
> 仅需交互式编辑通过GitHub Copilot时需要。如果使用基于脚本的生成，请跳过此部分。
### 1. 启动画布服务器
```bash
docker compose up -d
```
- 容器：`mcp-excalidraw-canvas` · 端口：`3000`
- 浏览器：http://localhost:3000
### 2. VS Code MCP配置
`.vscode/mcp.json`已经提交 — VS Code自动识别`excalidraw` MCP服务器。
```json
{
"servers": {
"excalidraw": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"--network", "mcp-net",
"-e", "EXPRESS_SERVER_URL=http://mcp-excalidraw-canvas:3000",
"-e", "ENABLE_CANVAS_SYNC=true",
"ghcr.io/yctimlin/mcp_excalidraw:latest"
]
}
}
}
```
> VS Code自动管理`mcp_excalidraw`客户端容器。您只需手动启动`mcp-excalidraw-canvas`（步骤1）。
### 网络架构
```
[您]
docker compose up -d
└─ mcp-excalidraw-canvas (ghcr.io/yctimlin/mcp_excalidraw-canvas)
端口 3000:3000 | 网络：mcp-net
浏览器：http://localhost:3000
[VS Code自动管理]
GitHub Copilot（MCP客户端）
│ stdio
▼
ghcr.io/yctimlin/mcp_excalidraw [--network mcp-net, --rm]
│ HTTP
▼
mcp-excalidraw-canvas [mcp-net]
```
