别再让 AI 画“方框套方框”了!这个开源 Skill,让架构图有了设计感

第一章：它不是新的画图网站，而是 AI 的一套设计规范

你可能遇到过这种情况：把系统说明交给 AI，让它画一张架构图，结果得到十几个同样大小的圆角矩形，配上五颜六色的箭头。

信息似乎都有，但读者不知道先看哪里。

Diagram Design 解决的，正是这类问题。

它不是需要注册的新网站，也不是一个独立的文生图模型，而是一套给 AI 编程助手使用的 Skill：把图表类型、布局规则、品牌样式、导入流程和检查清单组织起来，指导助手生成图表。[1][2]

它的典型产物是包含内联 SVG 和 CSS 的 HTML 文件。需要交付图片时，再从 HTML 导出 SVG 或 PNG。[2][6]

可以这样理解：

你的系统说明 / 已有图表
           ↓
AI 助手读取 Diagram Design
           ↓
选择图表类型和布局规则
           ↓
应用品牌颜色、字体和信息层级
           ↓
生成 HTML + SVG
           ↓
检查、修改，按需导出图片

这与“让图像模型画一张架构图”不同：它主要让助手编写 HTML/SVG，而不是把所有文字和线条直接生成到一张位图里。

因此，后续修改可以针对节点、文字和连接关系进行；但这不代表生成结果永远正确，仍需要检查内容和排版。

项目提供架构图、流程图、时序图、泳道图、数据模型、时间线等数十种类型，也包含浅色、深色和完整编辑式版面示例。[1][2]

版本说明：本文核对时，插件清单标注版本为 2.6.22。README 与 SKILL 对图表总数的描述存在不同步，因此这里使用“数十种”，不把某个数量当作长期保证。本文依据项目文档整理操作流程，不声称已经对所有宿主完成端到端实测。[1][2][7]

第二章：从零安装，先分清“终端”和“AI 对话框”

本文以 Mac + Claude Code 为主线。已经使用 Codex 的读者，可以选择本章后面的替代安装方式，不需要两个助手都装。

最容易犯的错误，是把所有内容都粘贴到终端。

请先记住：

2.1 安装并登录 Claude Code

还没有安装 Claude Code，可以按其官方快速入门文档，在 macOS 终端执行原生安装命令：[8]

curl -fsSL https://claude.ai/install.sh | bash

这是下载并执行安装脚本的命令，应确认来源为官方域名。已经安装的读者跳过此步。

检查安装：

claude --version

创建一个专门用于练习的目录：

mkdir -p ~/diagram-lab/docs/diagrams
cd ~/diagram-lab
claude

首次启动按提示完成登录。Claude Code 的账号、订阅或 API 使用条件与这个开源 Skill 是两回事；安装开源 Skill，不等于获得免费的模型调用额度。[8]

2.2 安装 Diagram Design 插件

进入 Claude Code 后，逐条输入：

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

这些是项目 README 给出的安装命令，也符合 Claude Code 的插件市场安装方式。[1][9]

安装后查看：

/plugin

确认插件已经安装并启用。按照客户端提示重载插件，或退出后重新进入会话。

然后直接问：

请确认 diagram-design 技能是否可用，并运行它的 doctor 检查。
先不要生成图，也不要自动安装依赖。

Doctor 用于检查环境。项目的操作指南明确要求它不要自动安装软件。[3]

2.3 已经使用 Codex 的替代路线

在系统终端执行：

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design
codex plugin list

之后启动新会话，用自然语言要求使用 diagram-design。这些终端命令不要与 Claude Code 内部的 /plugin 命令混用。[1][10]

如果旧客户端不认识 plugin 子命令，先检查宿主版本和官方安装说明，不要猜测一个 pip install diagram-design 来替代。

第三章：生成第一张图，把“帮我画一下”改成明确需求

先不读取整个代码库，也不追求复杂架构。

我们用一个虚构的任务处理平台练习，包含六个组件：Web 页面、FastAPI、Redis 队列、Worker、MySQL、对象存储。

在 Claude Code 会话中输入以下内容。这是教程设计的示例需求，不是项目自带案例。

请使用 diagram-design，为下面这个任务处理平台生成架构图。

主题：一个异步任务如何从提交走到结果展示。
读者：了解基本开发概念的工程师。
图表类型：Architecture。
尺寸：doc-inline。
输出：静态 HTML，保存到 docs/diagrams/task-platform.html。
品牌：本次明确使用默认样式。



要求：
- 保持六个组件，不添加需求里没有的服务。
- 重点突出任务队列与 Worker。
- 所有可见说明使用简体中文，产品名保留英文。
- 使用支持简体中文的字体回退。
- 先说明布局方案，再生成文件。
- 如果合并了重复关系，请说明合并方式。
- 生成后检查文字溢出、线条穿框、箭头方向和信息遗漏。
- 此次只生成 HTML，不导出 PNG 或 SVG。

这个提示词明确了主题、读者、组件、关系、尺寸和输出位置，避免让模型同时猜业务和猜设计。

“本次明确使用默认样式”也有实际作用：项目第一次在新项目中使用时，会检查品牌样式是否配置；没有配置时，它应询问用户是定制还是使用默认样式。[2][3]

生成完成后，在另一个终端窗口打开文件：

open ~/diagram-lab/docs/diagrams/task-platform.html

检查时，先看关系是否正确，再看是否好看。

尤其注意 Worker 与队列的关系：箭头表达的是任务流向，还是组件发起调用的方向？不要在同一张图里不加说明地混用。

需要调整时，给出具体修改：

请修改 task-platform.html：
将 Worker 从队列取任务的动作标为“领取任务”，
并在图例中说明箭头表示业务流程方向。
保留现有组件，不新增节点。
调整后重新检查箭头与标签是否重叠。

第四章：先选对图，再谈配色和美化

架构图不适合解释所有问题。

“系统有哪些组件”和“用户登录时发生了什么”，虽然涉及同一个系统，却是不同的表达任务。

项目会根据内容选择视觉类型；当队列、信任边界或策略执行等行为是重点时，还可以先选择语义模式，再选择布局。[2]

入门先掌握下面几种：

例如，解释“请求失败后刷新令牌再重试”，时序图通常比一组静态组件更直接；解释“任务在多个部门间流转”，则应关注泳道和交接。

4.1 图表为什么看起来更克制？

项目的设计规则不是“多加装饰”，而是限制无效信息：默认只突出一两个焦点，使用统一网格，减少没有信息价值的连接，并避免阴影、过度圆角和线条压住标签。[2]

普通示意图的默认复杂度预算约为 9 个节点、12 条箭头。导入模式另有不同档位，不能把这个数字套到所有场景。[3][5]

我的建议是：当一张图必须靠不断缩小字体才能放下时，先考虑拆成总览和局部详图。

4.2 先看官方示例，再决定风格

可以打开项目在线图库：

https://cathrynlavery.github.io/diagram-design/

也可以在终端获取本地参考副本：

mkdir -p ~/code
git clone https://github.com/cathrynlavery/diagram-design.git ~/code/diagram-design
open ~/code/diagram-design/skills/diagram-design/assets/index.html

已经存在这个目录时不要重复克隆。

这个参考副本用于浏览模板和后面的源码检查，不需要再次安装成同名 Skill。[3]

第五章：让每张图都像同一个品牌做出来的

单张图好看，不等于一套图风格一致。

技术文章、产品介绍和公司方案，往往需要复用同一套背景、文字颜色、强调色和字体。

Diagram Design 用语义化样式角色管理这些内容，而不是在每次提示词里重新描述所有细节。[2][4]

常见角色包括：

paper      页面背景
paper-2    容器背景
ink        主要文字和线条
muted      次要说明
accent     少量重点元素
link       部分连接或外部调用

5.1 从网站提取品牌

在 AI 会话中输入，先把示例地址替换为你的真实网站：

请从 https://example.com 提取 diagram-design 所需的品牌样式。

先列出建议采用的背景色、文字色、强调色和字体，
说明它们分别来自哪里，以及是否存在字体回退。
先展示方案，不要直接覆盖现有配置。

我确认后，将完整配置保存为名为 my-brand 的 profile，
并让当前项目使用这个 profile。

项目支持从网站进行品牌初始化，也支持手动提供样式或从本地设计系统中提取。[1][3]

没有网站，直接提供品牌规范即可，不必为了这一步先搭网站。

5.2 品牌配置不要只写在插件目录里

插件更新可能替换安装目录。项目提供了独立的 profile 存储位置：[4]

~/.diagram-design/profiles/my-brand.md

项目根目录用 .diagram-design 文件选择配置，内容应当只有：

profile: my-brand

这个标记文件不是配色文件，也不是随意添加字段的 YAML 配置。

对应的 profile 必须真实存在。只有标记、没有 profile，并不能完成品牌设置。[4]

在多项目场景下，这种方式比反复修改同一个已安装的 style-guide.md 更合适：每个项目选择自己的品牌，避免互相覆盖。

5.3 简体中文要单独确认字体

项目的输出规范明确要求为非拉丁文字配置字体回退。简体中文可采用这样的字体栈：[5]

font-family: 'Geist', 'PingFang SC', 'Noto Sans SC', 'Microsoft YaHei', sans-serif;

但写出字体名称，并不意味着目标电脑已经安装该字体。

因此，请在实际生成 PNG 的机器上检查中文显示和文字宽度，而不是只看英文示例正常就认为中文也正常。

第六章：把已有 Mermaid、draw.io、Excalidraw 重新排版

很多团队的问题不是没有图，而是已经有图，但不适合公开讲解。

Diagram Design 的导入流程重在读取内容后重新设计：保留或明确归并组件、关系和方向，再按照目标用途重画。它不是保证坐标、字体和颜色不变的格式转换器。[1][3][5]

6.1 先准备一个 Mermaid 示例

在练习目录创建 workflow.mmd，写入：

flowchart LR
    A[Web 页面] -->|提交任务| B[FastAPI]
    B -->|保存元数据| E[(MySQL)]
    B -->|入队| C[Redis 队列]
    C -->|任务流| D[Worker]
    D -->|写入结果| E
    D -->|保存文件| F[对象存储]

然后在 Claude Code 会话内输入以下命令。每条按一行输入：

/diagram-design:import-mermaid workflow.mmd --size=doc-inline --detail=balanced --audience=engineer

需要从 Markdown 文件提取所有 Mermaid 图，可以使用：

/diagram-design:import-mermaid README.md --diagram=all

以上导入形式由项目 README 提供。[1]

6.2 draw.io 与 Excalidraw

将实际文件放到当前项目中，然后使用：

/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive

/diagram-design:import-excalidraw whiteboard.excalidraw --size=doc-inline --detail=balanced

其中，Excalidraw 导入支持场景 JSON 文件，例如 .excalidraw、.excalidraw.json；不要把一张普通 PNG 当作等价的场景源文件。[1]

其他宿主不一定提供相同斜杠命令。也可以直接说：

请使用 diagram-design 重绘当前目录的 platform.drawio。
目标为 16:9 演示文稿，面向管理者，采用 simplified 细节级别。
先输出 HTML；如有合并或省略，逐项说明。

6.3 四个参数，决定它怎么重画

导入规范中，faithful、balanced、simplified 的节点上限分别为 24、12、7；高密度模式还需要分区，超过预算时应拆图，而不是无限缩字。[5]

其中，audience=executive 调整的是表达方式，不能理解成“让 AI 替我编一个商业结论”。

6.4 一定要求“变更说明”

项目称之为 fidelity ledger，即重绘前后内容变化的清单。[5]

例如，应当说明：

合并：三个相同 Worker 合并为“Worker ×3”。
折叠：监控组件组折叠为一个节点。
省略：不影响本图主线的部署细节。
完整保留：任务提交、入队、执行与结果写入路径。

图更简洁可以接受；关键关系被静默删除，不可以接受。

第七章：导出 SVG 和 PNG，先弄清楚交付范围

生成 HTML 后，还需要决定它最终用在哪里。

HTML 适合作为继续修改的源文件；SVG 适合矢量交付；PNG 适合需要稳定显示的文章或演示配图。[5][6]

7.1 导出 SVG

在 Claude Code 会话内输入：

/diagram-design:export-diagram docs/diagrams/task-platform.html --svg-only

按默认命名规则，会在源文件旁边生成：

docs/diagrams/task-platform.svg

也可以用自然语言要求导出到指定位置。[6]

SVG 的一个限制是字体可移植性。 项目导出流程可能引用在线字体，某些离线软件或导入路径会发生字体替换。因此，不能把“SVG 是矢量”理解成“在任何电脑上都像素级一致”。[6]

7.2 PNG 导出需要 Python、Playwright 和 Chromium

只浏览生成的 HTML，不需要为了这个项目运行后端服务。

但项目的 PNG 导出流程需要浏览器截图工具。[3][6]

在另一个系统终端中，先检查 Python：

python3 --version

确认 Python 可用后，在练习目录创建独立环境：

cd ~/diagram-lab
python3 -m venv .venv
source .venv/bin/activate
python -m pip install playwright
python -m playwright install chromium

这两项安装不同：前者安装 Python 包，后者安装 Playwright 使用的 Chromium 浏览器。

如果机器没有 python3，先通过 Python 官方安装方式准备环境，不要把系统中其他项目的环境随意改掉。

回到 AI 会话，告诉它明确的解释器路径：

PNG 导出依赖安装在 ~/diagram-lab/.venv 中。
请用 ~/diagram-lab/.venv/bin/python 检查 Playwright，
不要使用其他项目的 Python 环境。

然后执行：

/diagram-design:export-diagram docs/diagrams/task-platform.html --png-only --scale=2

也可以一次请求两种格式：

请将 docs/diagrams/task-platform.html 导出为 SVG 和 PNG，
PNG 使用 2 倍缩放，并报告实际图片尺寸。

默认导出倍率为 2，输出文件通常位于 HTML 旁边。[6]

7.3 最大的误会：导出的不一定是整页

默认 SVG/PNG 导出针对的是图形本身，不包含完整编辑式版面里的页眉、说明卡片和页脚。[6]

所以，“网页里看得到，导出图片里没有”，不一定是导出失败。

需要完整页面时，请明确要求：

我要整页截图，包含标题、主图和说明卡片。
不要使用仅截取 SVG 的导出方式。
请另存为 task-platform-full.png，保留原有图形导出文件。

这应当按单独的整页截图任务处理，而不是期待 --png-only 自动改变导出范围。

第八章：完整应用，把技术架构图改成公众号配图

技术文档里的图，和手机屏幕上的文章配图，不应该只是同一张图片等比例缩放。

这里给出一套建议工作流：先确认技术关系，再为文章调整信息密度，最后检查最终展示尺寸。

8.1 先确定这张图要回答什么

延续前面的例子，文章主题可以是：

为什么任务提交后，页面可以先返回“已接收”，而不必等待全部处理完成？

配图就应该围绕“提交”和“执行”分离展开，而不是把系统部署细节全部塞进去。

在 AI 会话中输入：

请基于 docs/diagrams/task-platform.html，
另做一张用于技术公众号正文的解释图。

读者：了解基本编程，但不熟悉异步任务系统的人。
主线：提交请求 → 任务排队 → 后台执行 → 结果可查询。

要求：
- 简体中文。
- 使用当前品牌 profile；未配置时使用我已确认的默认样式。
- 保留必要组件，但减少端口、部署位置等细节。
- 清楚区分“任务已接收”与“任务已完成”。
- 不添加原图未说明的系统保证，例如 exactly-once。
- 优先采用 doc-inline，检查缩小后是否可读。
- 若中文标签过长，缩短表达或拆图，不要无限缩小字号。
- 保存为 docs/diagrams/task-platform-article.html。
- 报告相对原图合并或省略了什么。
- 我检查后，再单独导出 PNG。

这段提示词是应用建议，不是新增的命令行参数。

8.2 配图不是“越全越专业”

建议让一张图只回答一个主要问题。

如果正文需要同时解释完整架构和单个任务的生命周期，就做两张图：一张总览，一张流程或时序详解。

检查时，把图片缩到接近手机正文的展示宽度。文字看不清，就减少内容或调整版式；单纯提高导出倍率不能挽救过密的布局。

8.3 保留源文件和说明

建议按用途保存，而不是只留下最后一张 PNG：

docs/diagrams/
├── task-platform.html
├── task-platform.svg
├── task-platform.png
├── task-platform-article.html
└── task-platform-article.png

这里是完成相应导出后的建议目录，不代表生成 HTML 时会自动产生所有格式。

保存源文件的好处很直接：下次增加一个组件时，可以修改已有图，而不是重新解释整个系统。

第九章：拆开项目，看懂 Skill 为什么不只是一段提示词

Diagram Design 值得学习的地方，是它把“设计规范”拆成了可以按需读取的文件。

核心入口在内层目录，而不是仓库根目录：[2][3]

diagram-design/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── doctor.md
│   ├── export-diagram.md
│   └── import-mermaid.md
├── docs/
│   └── cookbook.md
├── scripts/
│   ├── lint-skin.py
│   └── verify-geometry.py
└── skills/
    └── diagram-design/
        ├── SKILL.md
        ├── references/
        │   ├── style-guide.md
        │   ├── profiles.md
        │   ├── output-spec.md
        │   ├── export.md
        │   └── type-architecture.md
        ├── assets/
        │   ├── index.html
        │   ├── template.html
        │   └── template-full.html
        └── scripts/
            └── self_check.py

这是部分目录结构，不是全部文件清单。

9.1 四层分工

SKILL.md 决定工作流程：何时使用、如何选图、需要遵守哪些约束。

references/ 提供具体知识：品牌、图表类型、导入导出、复杂度预算。

assets/ 提供模板和示例，帮助助手看到目标结构。

检查脚本则提供额外验证入口。项目 cookbook 给出了自检、样式检查和几何检查的调用方式。[2][3]

这可以概括为：

入口指令 → 按需参考 → 模板生成 → 检查与修正

9.2 不要只看浏览器截图

如果第 4 章已经把仓库克隆到 ~/code/diagram-design，可以在系统终端运行自检：

python3 ~/code/diagram-design/skills/diagram-design/scripts/self_check.py \
  ~/diagram-lab/docs/diagrams/task-platform.html

进一步的仓库级检查包括：

cd ~/code/diagram-design

python3 scripts/lint-skin.py \
  ~/diagram-lab/docs/diagrams/task-platform.html

python3 scripts/verify-geometry.py \
  ~/diagram-lab/docs/diagrams/task-platform.html

这些调用来自项目操作指南。若检查提示缺少依赖，按具体脚本的说明补齐；若自定义品牌触发样式规则，先区分“允许的品牌差异”和“真实错误”，不要为了消除告警盲目改色。[3]

检查通过，也不代表业务关系正确。 它不能替你证明某个服务真的部署了，或者某条调用链与生产环境一致。

9.3 手动安装时，链接内层目录

只有准备采用独立 Skill 安装、并且没有同时启用同名插件时，才考虑：

mkdir -p ~/.claude/skills
ln -s ~/code/diagram-design/skills/diagram-design \
  ~/.claude/skills/diagram-design

关键是链接到包含 SKILL.md 的内层目录。

目标路径已经存在时，先检查它是什么，不要直接覆盖。独立 Skill 安装也不等于完整插件命令都已注册，缺少斜杠命令时使用自然语言调用相应流程。[3][9]

第十章：常见问题、边界，以及真正值得复用的做法

10.1 安装了，但助手没有使用它

先检查插件是否启用，是否已重载或启动新会话，再明确要求“使用 diagram-design”。

采用手动安装时，检查目录层级和符号链接是否有效，避免同时发现多个同名安装。[3][9]

10.2 终端提示找不到 /diagram-design:...

这是因为它是 Claude Code 会话内的命令，不是系统可执行程序。

先进入 claude 会话，再输入斜杠命令；其他宿主可以用自然语言调用，不要假设命令前缀完全一致。[1][3]

10.3 HTML 能看，PNG 导不出来

分别检查 Python 包和浏览器运行时：

~/diagram-lab/.venv/bin/python -c "import playwright; print('Playwright OK')"
~/diagram-lab/.venv/bin/python -m playwright install chromium

第一条成功，只能说明 Python 包可导入，不代表浏览器运行时已经齐全。

如果助手还在报缺依赖，确认它实际调用的解释器是不是这个虚拟环境。[3][6]

10.4 中文溢出，或者换电脑后字体变了

检查实际可用的中文字体、回退字体与渲染后的文字宽度。中文不能直接套用英文标签的字符宽度估算。[5]

项目的“单文件 HTML”也不应被理解为“所有字体均已嵌入、完全不联网”。导出说明明确涉及在线字体及离线替换风险。[6]

需要固定视觉结果时，在目标环境确认字体后导出 PNG。

10.5 为什么它合并了我的节点？

先看 detail 档位。simplified 本来就用于压缩信息，不适合逐项保留所有基础设施。

要求更高保真时，选择 faithful，并允许分区或拆成多张图；同时查看变更清单，确认关键关系没有被省略。[5]

10.6 它能替代 Figma、Mermaid 或人工设计吗？

更准确的定位是：给 AI 辅助绘图增加一套可复用的表达和设计流程，而不是宣称其他工具没有价值。

需要精细手工设计，可以继续使用熟悉的设计工具；需要长期维护文本关系，可以保留 Mermaid 等源文件，再按发布用途重绘。

对最终交付，应当保留三个边界：

第一，生成代码不等于内容正确。 架构、数字、权限边界和调用方向，仍要由了解业务的人复核。

第二，本地文件不等于内容只在本地处理。 是否向云端发送内容，取决于所使用的 AI 宿主与配置。敏感架构先做脱敏，并按组织批准的方式使用工具。

第三，静态图不等于实时系统。 图中的状态不会因为线上服务变化就自动更新；它仍然需要维护。

10.7 最值得带走的，不是某个提示词

我认为这个项目最值得借鉴的是：

与其每次让 AI “自由发挥”，不如把可复用的设计规范、示例和检查流程交给它。

从实际使用看，可以把流程固定为：

明确读者和问题
    ↓
给出真实组件与关系
    ↓
选择一种主要图表类型
    ↓
应用项目品牌
    ↓
生成并检查 HTML
    ↓
按用途导出
    ↓
人工复核内容与阅读效果

好的技术配图，不是展示系统里有多少东西，而是让读者更容易理解它们为什么这样连接。