架构制图技能（Architecture Diagrammer）#

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

产出模式#

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

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

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

风格特点适用场景blue深蓝商务渐变企业正式cyber黑底霓虹色科技演示darkGitHub 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