Diagram Design 新手教程

1这是什么

Diagram Design（作者 Cathryn Lavery，BestSelf.co 创始人）是一个 Agent Skill：它本身不是软件，而是一套写给 AI Agent 看的「图表设计规范 + 39 种版式模板」。装好之后，你在 Cursor 的 Agent 对话里说一句「给我画一张架构图」，Agent 就会按它的规范产出图表。

它解决的问题非常具体：AI 生成的图表太丑。作者的原话是「每次让 Claude 画图，得到的都是千篇一律的通用圆角框，和我的网站风格毫无关系」。这套 skill 的对策是一套近乎苛刻的设计系统：单一强调色、三字体、1px 发丝边、零阴影、圆角不超过 10px、坐标全部落在 4px 网格上。

它不做什么

• 不是绘图库或 SDK——你不会写 import diagram 这样的代码，一切通过自然语言驱动。
• 不是 Mermaid 替代渲染器——它明确反对 Mermaid 式的自动布局产物，还提供「把已有 Mermaid 重绘成编辑级图表」的导入功能。
• 不是所有信息的正确载体——skill 自己规定：一张列表能说清的事用表格，前后对比用表格，单个方框能说清的直接写句子。图表只用在「读者从图里比从文字学到更多」的场合。

2为什么需要

在它出现之前，给文档配一张体面的架构图，通常要走下面三条弯路之一：

Diagram Design 的核心洞察只有一句话，来自作者写在 README 里的设计哲学：

这套哲学不是口号，而是写进 SKILL.md 的硬约束：Agent 画图前必须声明「画什么类型、砍掉什么」，节点超过 9 个就强制分区或拆图，输出前还要过一道 21 项的「品味检查清单」。你得到的不只是一张图，而是一套被反复执行的设计纪律。

3核心流程

整条链路只有三步：装进 Cursor 的 skill 目录 → 在 Agent 会话里说话 → 拿到自包含 HTML。中间的两次「交互确认」（风格确认、画前确认）是 skill 主动设计的，不是 bug。

第二步里 Agent 会做两件「多问一句」的事：首次使用时先和你确认配色风格（见第 6 节），动笔前再复述一遍「我准备画什么类型、多大尺寸、砍掉哪些细节」。这两次确认就是它的品味来源——你随时可以打断改方向。

4在 Cursor CLI 里安装

先说最容易踩的坑：Cursor 没有 marketplace 插件入口。README 里那些 /plugin install、codex plugin add 命令是 Claude Code / Codex / Droid 专属的。Cursor 的唯一正确姿势是：clone 仓库，把内层 skill 目录软链到 Cursor 的发现路径。

四条命令装好（macOS / Linux）

# 1. clone 仓库到任意固定位置（建议 ~/code/）
git clone https://github.com/cathrynlavery/diagram-design.git ~/code/diagram-design

# 2. 确保 Cursor 的用户级 skill 目录存在
mkdir -p ~/.cursor/skills

# 3. 软链内层 skill 目录（注意：是 skills/diagram-design，不是仓库根！）
ln -s ~/code/diagram-design/skills/diagram-design ~/.cursor/skills/diagram-design

# 4. 验证
ls -l ~/.cursor/skills/

软链，不要复制

用 ln -s 而不是 cp -r：以后 git pull 一下，skill 就更新了；复制安装则永远停在旧版本。这与你自己维护的 Cursor skill 体系是同一个思路——单一事实源，多处引用。

只装一处，防止「双重发现」

Cursor 会扫描四个位置：用户级 ~/.cursor/skills/、~/.agents/skills/，项目级 .cursor/skills/、.agents/skills/。如果你在两个根里都放了它，会被发现两次。官方建议：挑一个根，只装一处。想全局可用就装 ~/.cursor/skills/；只想某个项目用就装那个项目的 .cursor/skills/。

Windows

Windows 不支持文件软链目录，要用目录 junction（cmd 的 mklink /J）。PowerShell 写法：

$src = "C:\code\diagram-design\skills\diagram-design"
$dst = "$env:USERPROFILE\.cursor\skills\diagram-design"
New-Item -ItemType Directory -Path (Split-Path $dst) -Force | Out-Null
cmd /c mklink /J "$dst" "$src"

其他宿主一览

同一份 clone 可以同时软链给多个宿主——这正是软链安装的好处：一处更新，处处生效。

5环境自检

装完别急着画图，先花一分钟确认三件事：skill 被发现、Python 可用、（如果以后要导出 PNG）Playwright 就绪。

另外可以在 Cursor 会话里直接说 run diagram-design doctor——这是内置的体检流程，会逐项报告环境状态（它只检查、不自动装包）。

6第一次实战（Cursor CLI）

在你自己的项目里画第一张图（不要在 skill 目录里画）。全程 5 分钟，跟着下面的对话走一遍，你就掌握了它的全部交互模式。

第 1 步：进入项目目录，启动 Cursor Agent

cd ~/你的项目
mkdir -p docs/diagrams
cursor

第 2 步：发第一句话

把这段模板里的方括号内容换成你的真实情况（节点数控制在 9 个以内）：

Use the diagram-design skill.
Draw an architecture diagram of [我的 App 后端].
Nodes: [Web 前端, API 网关, 订单服务, 用户服务, Postgres, Redis 缓存].
Focal: [API 网关].
Size doc-inline, format HTML. Confirm type and cuts before drawing.
Save to docs/diagrams/backend.html.

翻译成人话：画什么（架构图）、有哪些节点、谁是视觉焦点、尺寸多大（文档内嵌规格 960×600）、先确认再画、存到哪。

第 3 步：回应「风格确认门」

第一次使用时，Agent 必定暂停问你风格问题——因为它检测到你还在用出厂默认配色（paper #f5f5f5、ink #2d3142、accent 珊瑚橙 #eb6c36）。它会给你几个选项：

• 「Onboard diagram-design to https://我的网站.com」——它去抓你网站的配色和字体，映射成 paper / ink / muted / accent 语义角色，给你看一份 diff，你说 yes 才写入。
• 「Proceed with the default skin」——就用默认皮，Agent 会在项目根写一个 .diagram-design 标记文件（内容一行：profile: default），以后不再问。
• 手动给 token——直接把十六进制色值报给它。

新手建议先选 default 跑通全流程，回头再做品牌定制（第 9 节）。

第 4 步：回应「画前确认」

接着 Agent 会复述它的计划：「架构图、doc-inline 尺寸、6 节点 5 箭头、预算内不裁剪」。没问题就回复确认；想改方向（比如 Redis 其实是可选组件）现在说，成本最低。

第 5 步：验收

# 浏览器打开产物（自包含 HTML，离线可看）
open docs/diagrams/backend.html

# 跑一次官方自检
python3 ~/code/diagram-design/skills/diagram-design/scripts/self_check.py docs/diagrams/backend.html

self_check.py 打印 OK 说明可访问性契约（role="img"、<title>/<desc>）、单文件安全性都达标。之后每次让它画图，都可以顺手让它自己跑一遍这个检查。

7产物结构

每一次生成的都是一个可以单独提交进 git 的 HTML 文件。它的内部结构和设计原则如下：

四种模板变体

8会话里怎么说

Cursor 里没有 /diagram-design:xxx 斜杠命令（那是 Claude Code 的语法）。在 Cursor 里，一切靠自然语言触发，SKILL.md 里的描述负责让 Agent 识别意图。三种最常用的说法：

# 新画一张
"Make me an architecture diagram of my app: frontend, backend, database, Redis cache."

# 带四旋钮的重绘指令（导入旧图时最常用）
"Redraw platform.drawio for a 16:9 slide, detail simplified, audience executive, format PNG."

# 导出
"Export docs/diagrams/backend.html as SVG and PNG."

✅ 一定会发生的

• 首次风格确认门——只要还在默认皮肤，它必先问配色。
• 画前声明——类型、语义模式、尺寸、要砍什么，先说后画。
• 复杂度预算执法——节点超 9 个会主动建议分区或拆成总览 + 细节两张图，而不是硬塞。
• 保真度账单（fidelity ledger）——导入重绘后，它会报告「合并了什么、折叠了什么、丢弃了什么」，因为图的读者看不到被删掉的内容。

❌ 不会发生的

• 不会未经要求就导出 PNG/SVG——导出是显式动作。
• 不会保留源文件的自动布局——Mermaid / draw.io 的坐标、调色板、字体一概不带过来，这是「重绘」而非「转换」。
• 不会悄悄覆盖画廊示例——产物默认写到你的项目路径。
• 不会在图表里堆强调色——珊瑚橙永远只出现在 1–2 个焦点元素上，超过就违规。

9进阶玩法

品牌接入（onboard）

说一句 Onboard diagram-design to https://你的站点.com，它会抓取首页并按下表提取 token，给你看 diff、你批准后才写入。对比度会自动过 WCAG AA 校验：

做多个客户项目时，用命名 profile（存 ~/.diagram-design/profiles/）+ 项目根的 .diagram-design 标记文件切换，互不污染。

四个旋钮（导入重绘的精髓）

重绘旧图前先定四个拨盘，它们决定版式、节点数和措辞，事后改等于重画：

导入三种旧格式

draw.io / Mermaid / Excalidraw 都能吃。在 Cursor 里直接说「Import every Mermaid block in README.md, size doc-wide, detail balanced」，Agent 会调内置提取脚本解析源文件，再按新设计系统重画，最后附上保真度账单。

导出 PNG / SVG

# 前提（仅需一次）：Playwright 就绪
pip install playwright && playwright install chromium

# 然后在 Cursor 里自然语言导出，或让它执行：
# SVG：只取第一个 <svg>，注入转义后的 Google Fonts
# PNG：默认 2 倍分辨率截图，透明背景；要更高清就说 --scale=3
"Export docs/diagrams/backend.html --png-only --scale=3"

导出 PNG 会顺带生成一个 .registry.json 块元数据文件，记录这张图的 token、类型、尺寸，方便批量管理。

更新与卸载

cd ~/code/diagram-design && git pull   # 软链安装的更新方式
rm ~/.cursor/skills/diagram-design     # 卸载（只删软链，不动仓库）

10不止画架构图

名字里带 diagram，容易以为它只能画技术架构。39 种类型覆盖的场景其实宽得多：

• 周报 / 技术文档——Architecture、Data flow、Deployment：把系统讲给新同事和老板听。
• 产品与运营——User journey、Kanban、Story map、Gantt：流程、优先级、排期一图说清。
• 复盘与决策——Fishbone（根因）、Quadrant（影响 × 成本）、Wardley map（价值链演化）。
• 内容创作——Timeline、Loop（飞轮）、Pyramid / funnel：公众号配图、OG 分享卡（social-og 规格）。
• 数据叙事——Bar、Line、Waterfall、Sankey、Treemap：不接 Excel，直接把数据报给 Agent 画。
• 旧资产翻新——仓库里沉睡的 .drawio / .mmd 文件批量重绘成和站点同风格的新图。

选型拿不准时不用背类型表——直接描述行为（「我想表达一个越滚越快的增长循环」「这是一个有瓶颈的汇入队列」），skill 内置了「行为 → 语义模式 → 图表类型」的路由表，Agent 会自己选型并告诉你选了什么。

11设计系统与预算

这一节是理解「它为什么好看」的钥匙。所有约束都写在 SKILL.md 里，Agent 每次画图都在执行：

核心预算（默认上限）

视觉纪律

• 零阴影——阴影是明令禁止项，层次靠 1px 发丝边和填充深浅表达。
• 单强调色——默认珊瑚橙，品牌接入后换成你的主色，但「只给 1–2 个焦点」的规则不变。
• 4px 网格——坐标、间距、字号全部落在 4 的倍数上，这是版式稳的物理基础。
• 反 AI 味清单——同款圆角框全家桶、深底青紫辉光、JetBrains Mono 当默认字体、图内悬浮图例……全部是自动 fail 项。

成本与性能

skill 采用「按需加载」：常规的静态图请求只加载 SKILL.md + 对应类型的一份参考文档（如 type-architecture.md），不会把 39 个类型的文档全塞进上下文。产出本身是静态 HTML，无运行时开销。比较花 token 的是 faithful 级重绘和多轮品牌调试，日常画图很轻。

12FAQ / 踩坑

13合规与版权

• 仓库许可证：MIT——可以自由商用、修改、内部分发，保留版权声明即可。
• 内置图标：87 个单色图标来自 Tabler Icons（MIT）与 Simple Icons（CC0），再分发无额外义务。
• 字体：Instrument Serif / Geist / Geist Mono 均为开源字体（SIL OFL 系），通过 Google Fonts 加载；产物离线打开时会回退到系统字体。
• 内容责任：图表内容来自你喂给 Agent 的信息，涉及公司内部架构、数据时自行注意脱敏；重绘第三方图表时确认你有权使用其内容。

14参考链接