用于快速产出**架构图 / 流程图 / 时序图 / 部署图**等可视化交付物，常见输出为 `.svg`（可离线打开）或 `.html`（浏览器直接预览）

面向架构与流程的专业制图技能。支持两种产出方式：(1) 直接生成高质量 SVG 分层架构图，提供 11+ 种风格（blue/cyber/dark/gray/green/handdrawn/mono/morandi/ocean/orange/purple/tailwind），支持精确布局与中文；(2) 使用 Mermaid / PlantUML / Graphviz 描述结构，并通过 Kroki 渲染为 SVG 或 HTML。适用于系统架构设计、方案评审与技术沟通中的可视化输出。

架构制图技能（Architecture Diagrammer）

本技能帮助在产品/前端/后端/系统等多视角下，快速产出高质量的架构图、流程图、时序图与部署图，并导出为 SVG 与 HTML。

产出模式

模式一：纯 SVG 分层架构图（推荐用于分层展示）

直接生成纯 SVG 代码，无需外部渲染，支持精确控制布局、配色、字体。

支持 11+ 种风格（详见 references/svg-layered-spec.md）：

风格	特点	适用场景
blue	深蓝商务渐变	企业正式
cyber	黑底霓虹色	科技演示
dark	GitHub Dark 主题	开发者
gray	简约灰阶	文档嵌入
green	森林绿渐变	自然环保
handdrawn	手绘风格	草稿创意
mono	极简黑白直角	打印极简
morandi	低饱和度复古	设计感
ocean	海洋蓝绿	清新科技
orange	暖橙渐变	活力营销
purple	紫色渐变	创意高端
tailwind	多色层级区分	层级复杂

• 适用：系统分层架构、方案架构、技术全景图
• 参考：references/svg-layered-spec.md（风格规范、配色表、代码片段）
• 模板：assets/svg-templates/ 目录下各风格模板

说明（重要）：

• 当用户说“生成一个 分层架构图 / “我要的是 svg 的分层架构图”，默认指 纯分层 SVG（模式一），而不是 “Mermaid 渲染出的 SVG”。
• 目标交付物：一个可离线打开的 .svg 文件（不依赖 Kroki / Mermaid CDN）。

模式二：Mermaid/PlantUML/Graphviz + Kroki 渲染

使用图形 DSL 描述结构，通过 Kroki 渲染为 SVG/HTML/PNG/PDF。

• 适用：流程图、时序图、C4 架构图、依赖关系图
• 参考：references/diagram-quickstart.md（语法速查）

工作流

画图前：先让用户选择

在开始画图前，向用户提供若干建议供选择，确认后再动手：

• 产出模式：纯 SVG 分层图 vs Mermaid/PlantUML/Graphviz + Kroki
• 图类型：分层架构 / 流程图 / 时序图 / C4 / 部署图 等
• 层级或复杂度：层数按需（常见 2–5 层，不固定）、每层模块数量、是否要图例
• 风格偏好：11+ 种风格可选（blue/cyber/dark/gray/green/handdrawn/mono/morandi/ocean/orange/purple/tailwind，见 references/svg-layered-spec.md）、是否图例、输出格式（.svg / .html） 用户选定或默认后，再按对应模式执行下方步骤。

不确定时询问

以下任一情况不确定时，先向用户列出选项或给出建议，待确认后再动手，不要自行假设：

• 产出模式、图类型不明确
• 层数、层级名称、每层包含哪些模块
• 配色/风格偏好、是否要图例
• 输出文件名、格式（.svg / .html）

纯 SVG 分层架构图

1. 按需求确定层级划分（层数不固定，常见 2–5 层，可少于 2 或多于 5）
2. 选定配色风格（11+ 种可选：blue/cyber/dark/gray/green/handdrawn/mono/morandi/ocean/orange/purple/tailwind，见 references/svg-layered-spec.md）
3. 基于模板绘制层级容器与子模块（画布高度、层高按层数动态调整）
4. 结构与连线（按需取舍）：
   • 只表达对沟通有价值的“直接关系/关键路径”，不必把所有区块都强行连起来
   • 允许出现不连线的独立模块/模块组（例如同层的独立域、横切能力、外部依赖清单）
   • 允许同一行放多个互不相连的大模块（并排布局），按视觉平衡与阅读顺序灵活排布
5. 添加箭头连线与标注（只画必要的流向与依赖，并用最少文字说明）
6. 添加图例
7. 对照 references/architecture-checklist.md 自检
8. 版式检查（避免重叠）：
   • 层级标题与子模块之间至少预留 8-12px
   • 子模块与层级容器底部至少预留 10-16px
   • 同层/同一行可并排多个独立模块组：组间留足间距，避免交叉线，必要时用小标题/分组框增强可读性
   • 图例不要贴底，必要时增加画布高度（<svg height="...">）并下移图例
9. 编码检查（避免中文乱码）：
   • 输出文件声明 UTF-8：<?xml version="1.0" encoding="UTF-8"?>
   • 推荐：中文一律使用 XML 数字字符引用（&#xXXXX;），不依赖文件编码，任何 SVG 查看器都能正确显示。规则：每个汉字对应 &#x + 其 Unicode 码点（4 位十六进制）+ ;，例如「权限」→ 权限。详见 references/svg-layered-spec.md 的「中文编码与乱码修正」。
   • 若已用裸中文且出现乱码，可整体重写为数字字符引用，或用脚本按 UTF-8 重写文件（避免局部编辑混入非 UTF-8 字节）。

Mermaid/PlantUML/Graphviz

1. 明确目标与范围：业务目标、上下文、关键约束
2. 选择图类型：C4（Context/Container/Component）、流程图、时序图、部署图
3. 起稿与迭代：从粗到细，命名统一、边界清晰
4. 渲染与导出：使用 scripts/render_kroki.py 生成 SVG 或 HTML
5. 质量检查：对照 references/architecture-checklist.md 自检

快速开始

• 语法速查与范例：见 references/diagram-quickstart.md
• 质量检查清单：见 references/architecture-checklist.md
• 以下命令默认假定本 skill 安装在 ~/.cursor/skills/arch-diagrammer/

渲染为 SVG（Kroki）

bash

python3 "$HOME/.cursor/skills/arch-diagrammer/scripts/render_kroki.py" \
  --type mermaid --format svg \
  --in your_diagram.mmd --out out.svg

渲染为 HTML（可直接在浏览器打开）

bash

python3 "$HOME/.cursor/skills/arch-diagrammer/scripts/render_kroki.py" \
  --type plantuml --format html \
  --in your_diagram.puml --out out.html

C4 架构图（使用 Kroki 内置 C4 支持）

bash

python3 "$HOME/.cursor/skills/arch-diagrammer/scripts/render_kroki.py" \
  --type c4plantuml --format svg \
  --in your_c4.puml --out out.svg

Kroki 内置 C4-PlantUML 宏，源文件不需要 !includeurl 引用 C4 库。

JSON API 模式

当纯文本 POST 遇到特殊字符问题时，加 --json 切换为 JSON POST（POST / + JSON body）：

bash

python3 "$HOME/.cursor/skills/arch-diagrammer/scripts/render_kroki.py" \
  --type graphviz --format svg --json \
  --in your_diagram.dot --out out.svg

说明：

• --type 支持 Kroki 全部 28 种图类型：actdiag | blockdiag | bpmn | bytefield | c4plantuml | d2 | dbml | ditaa | erd | excalidraw | graphviz | mermaid | nomnoml | nwdiag | packetdiag | pikchr | plantuml | rackdiag | seqdiag | structurizr | svgbob | symbolator | tikz | umlet | vega | vegalite | wavedrom | wireviz
• 别名：dot→graphviz、c4→c4plantuml、vega-lite→vegalite
• --format 支持：svg | png | pdf | jpeg | html（可由 --out 后缀自动推断）
• --json：使用 JSON POST API（POST / + {"diagram_source":...}），适用于包含特殊字符的复杂图
• --kroki-url：指定私有 Kroki 实例；或用环境变量 KROKI_URL（默认 https://kroki.io）
• --list-types：列出全部支持的图类型
• 输入来源：--in 文件或标准输入（省略 --in 时从 stdin 读取）

渲染为 SVG（本地 Mermaid CLI，避免 Kroki 失败）

当 Kroki 返回 403/限流（常见于公共服务）时，可改用本地渲染：

bash

npx -y @mermaid-js/mermaid-cli -i your_diagram.mmd -o out.svg

产出建议

• 命名清晰、一致：系统、服务、模块、接口、数据流命名统一
• 图例与边界：提供清晰图例；明确系统边界、外部依赖与信任区
• 分层与分视图：按 C4 层次逐步细化，避免一图承载过多信息
• 可复用：将公共元素抽为模板/片段，便于复用与演进

参考

• 纯 SVG 风格规范：references/svg-layered-spec.md（11+ 种风格配色、布局、代码片段）
• 分层架构模板：assets/svg-templates/ 目录下各风格模板
• Mermaid/PlantUML/Graphviz 语法：references/diagram-quickstart.md
• 质量检查清单：references/architecture-checklist.md
• HTML 预览模板：assets/html/mermaid-standalone.html