如果你常让 AI 帮忙画架构图，大概见过这种画面：让它画个流程图，回给你的是一堆圆角矩形加箭头，配色像 2012 年的 PPT，圆角大小还不统一。你只能要么花半小时在 Figma 里重画，要么干脆放弃配图。

Diagram Design 就是冲这个问题去的。它是一个给 AI 编程助手用的技能包（Agent Skill），用一句话描述你要的图，它吐出一个自包含的 HTML 文件 —— 内联 SVG、无构建步骤、双击就能在浏览器里打开。作者给它的定位很直白："Editorial diagrams your designer won't hate."（设计师不会嫌弃的编辑级图表。）

本文讲清它是什么、怎么装、到底支持多少种图，并顺带纠正几个网上流传的错误数字。

一、先纠正一个数字：是 42 种，不是 39 种

你在不少地方（包括很多转载文章）会看到"39 种图表"的说法。这个数字不算错，但已经过期了。

我实际去仓库里数了一遍：skills/diagram-design/references/ 目录下有 42 个 type-*.md 文件，每个文件对应一种图表类型的独立排版规范。这与仓库当前简介里写的"42 diagram types"、以及 SKILL.md 正文里的"Forty-two visual types"三方一致。

39 是 2.5.10 版本时期的口径（那一次一口气加了 Sankey、鱼骨图、Wardley 图、看板、用户旅程、部署图、依赖图、UML 类图、故事地图、数据库结构这 10 种）。之后又陆续补齐，现在是 42 种。二手文章的滞后是常态，看这类项目建议直接查一手。

这 42 种大致可以分成几类：

• 工程架构类：架构图、架构变更对比（Before · Changes · After）、IT 现状图、部署图、依赖图、UML 类图、数据库结构图、数据流、Medallion 分层、DP 集成图、DP 权限矩阵
• 流程与状态类：流程图、时序图、状态机、泳道图、多角色流程、生命周期图
• 数据可视化类：柱状图、折线图（含斜率图、山脊图、流图、凹凸图）、散点图（含气泡图、蜂群图）、雷达图、极坐标图、矩形树图、马赛克图、热力图、桑基图、瀑布图、甘特图
• 结构关系类：树形图、嵌套图、组织架构图、层级堆叠图、维恩图、金字塔/漏斗图、循环/飞轮图、象限图
• 管理与分析类：看板、用户旅程图、故事地图、时间轴、鱼骨图、Wardley 战略图

二、它凭什么好看：一套很克制的设计系统

作者的设计哲学写在 README 里，一句话就能记住：

"The highest-quality move is usually deletion. Every node earns its place. The accent color is reserved for the 1–2 things the reader should look at first. Target density: 4/10."

翻译过来：最高质量的动作通常是删除。每个节点都得挣得自己的位置，强调色只留给读者应该最先注意的那 1–2 样东西，目标信息密度是 4/10（十分制）。

落到具体规则上，是这几条硬约束：

• 一种强调色，每张图只允许 1–2 个视觉焦点
• 三套字体：Instrument Serif 做标题和斜体旁注，Geist 做节点名，Geist Mono 做技术性副标签（端口、URL、字段类型）
• 1px 发丝边框，不用阴影，圆角最大 10px
• 所有坐标、宽度、间距必须能被 4 整除 —— 作者说这是"不可协商"的，正是这一条让图看起来不像 AI 生成的

它有个说法叫"不用 Mermaid slop"。"slop"在这里指那种廉价、批量、机械感十足的输出。作者的判断是：问题不在语法，而在默认视觉质量 —— 与其忍受 Mermaid 的自动布局，不如直接生成一份你能完全掌控的 SVG。

三、三种变体，开箱即用

每种图表类型都自带三个静态变体：

• minimal light（极简浅色）—— 写博客、放文档里用这个
• minimal dark（极简深色）—— 暗色主题的 README 或站点
• full-editorial（完整编辑版）—— 带摘要卡片的版本，适合做幻灯片封面

输出是纯静态 HTML + 内联 SVG：没有构建步骤、没有 JavaScript、不依赖任何外部图片。双击就能在浏览器里打开。

另外还有一个可选的动效层，但它设计得很克制：动效不是一个独立的图表类型，默认关闭（none），可选 reveal / step / loop 三种模式。开启时使用一份固定的、经过审阅的控制器脚本 —— 任意自定义内联脚本、远程资源、CSS 导入和可执行属性都会被拒绝。同时它会遵守系统的"减少动态效果"（prefers-reduced-motion）设置，那种情况下直接显示完整的静态首帧。

顺带一提，仓库里还带了一套 87 个单色 IT / 云图标（笔记本、手机、服务器、数据库、Docker、Kubernetes、AWS、Azure、GitHub、Postgres 等）。这个数字我也核对过 —— 图标画廊文件 assets/icons.html 里正好有 87 个 <svg> 标签，对得上。图标用的是 currentColor，会自动继承你的品牌色。

四、怎么装：支持的主机比想象中多

它的安装方式是按 AI 助手分渠道的。以下是官方 README 里给出的命令：

Claude Code：

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

Codex：

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

GitHub Copilot：

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

Factory Droid：

droid plugin marketplace add https://github.com/cathrynlavery/diagram-design
droid plugin install diagram-design@diagram-design --scope user

Pi：

pi install https://github.com/cathrynlavery/diagram-design

另外还支持 Kiro（从仓库子目录 URL 导入）、OpenCode（把目录拷贝或软链到 skills 路径），以及 Claude Cowork 组织级市场（需要先把公开仓库镜像到组织内的私有仓库）。

官方的说明是：共享的技能本体就在 skills/diagram-design/ 这一个目录里，Claude Code、GitHub Copilot、Codex、Factory Droid 以及其他任何兼容 Agent Skills 的工具读的都是同一批文件。所以严格来说，它不绑定某一家 —— 只要你的 AI 助手支持 Agent Skills 规范，就可以用这个技能目录，只是各家的"安装/更新"方式不同。

一个容易踩的坑：Claude Code 对第三方插件市场默认关闭自动更新，装完要手动去 /plugin → Marketplaces → diagram-design → 打开 Enable auto-update，否则你拿不到后续更新。Codex 是启动时刷新市场，Droid 按提交（commit）跟踪而不是按版本号，Pi 没有自动刷新、需要手动跑 pi update --extensions。

想先看看效果再装，可以直接打开线上画廊：cathrynlavery.github.io/diagram-design，能切换浅色 / 深色 / 编辑版三种变体。

五、三件核心用法

1. 从零画一张：说出你要什么就行

直接用自然语言提需求：

• "画一下我应用的架构图：前端、后端、数据库、Redis 缓存。"
• "我要一个象限图，把 Q2 的项目按影响力和工作量排一下。"
• "给我一个时序图，展示 Bearer 调用在 401 时刷新令牌的流程。"

值得注意的是它的交互习惯：动手之前，它会先报出选定的图表类型、尺寸预设和打算裁掉哪些内容，你确认之后才开始生成文件。这个"先说再做"的设计，比直接甩一份结果给你要靠谱得多。

2. 把旧图重绘：吃 draw.io / Mermaid / Excalidraw

这是我认为最实用的一块。很多团队仓库里躺着一堆手拖的 .drawio 文件，内容全但难看。直接喂给它可以重绘：

/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid README.md --diagram=all
/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9

它支持 .drawio / .drawio.xml / .drawio.png（内嵌图）/ .drawio.svg，包括那种在编辑器里看着像 base64 乱码的压缩载荷；Mermaid 支持 .mmd、.mermaid 以及 Markdown 里一个或多个 mermaid 围栏代码块；Excalidraw 支持 .excalidraw 和 .excalidraw.json 场景文件。

关键在于它有四个调节旋钮，同一个源文件能出三种完全不同的图：

• Format（格式）：html / svg / png / html+png —— SVG 给 Figma，PNG 给幻灯片，HTML 给网页
• Size（尺寸）：doc-inline、doc-wide、slide-16x9、slide-4x3、social-og、social-square、print-a4-landscape 等十种预设。它不只改 viewBox，还改字号梯度 —— 投屏幻灯片用 16px 节点名，不是文档里的 12px
• Detail（细节度）：faithful（≤24 节点）/ balanced（≤12）/ simplified（≤7），按固定降级阶梯依次丢弃装饰、重复项、叶子簇、基础设施
• Audience（受众）：engineer / mixed / executive —— 改的是措辞不是数量。同一个东西可以是 Auth Service / JWT · RS256 · :8443，也可以是 Auth Service / token check，还可以只是 Sign-in

每次导入结束会附一份保真账本，告诉你什么被合并、什么被折叠、什么被丢掉了 —— 比如"Token 是否有效？"这个判断框变成了边上的一条标签，"1 条便签（未连接的遗留路径说明）"被丢弃。这个设计很实在：源文件是你写的，你不看账本也会发现，与其让你事后质疑，不如主动交代。

什么不会被带过去：源文件或渲染器的坐标、原配色、原字体、draw.io 的斜线连线、Mermaid 的自动布局、Excalidraw 的手绘几何。什么一定保留：组件、关系、分组、方向。

3. 导出成 PNG / SVG：给 Figma 和幻灯片用

/diagram-design:export-diagram path/to/diagram.html --png-only --scale=3

SVG 导出会抽出 <svg> 节点并注入 Google Fonts，让它在浏览器、Figma、Illustrator 里都能独立渲染。PNG 走 Playwright 无头浏览器栅格化，默认 2 倍。两个格式都只导出图本身，不含编辑版的外框卡片。

六、最聪明的一步：读你的网站，自动配你的品牌

默认调色板是"墨黑 + 原子橘"（白烟纸底、墨黑字、原子橘强调、蓝板岩弱化色、银色发丝线）。开箱截图就能用。但真正的杀手锏是这句话：

You: "onboard diagram-design to https://yoursite.com"

它会去抓你的首页，提取主色调和字体栈，映射到五个语义角色（paper / ink / muted / accent / link），先给你看一份改动前后的对比，你确认后才写入配置。之后就每张图都用你的品牌色了 —— 你网站的纸张色变成图的背景色，你 CTA 的颜色变成焦点强调色，你正文字体变成节点标签字体。

它还会生成一份"保真回执"，列出采样了哪些 URL、每个颜色角色取到什么值、字体族和字重、字体来源、以及有没有降级。公开站点的字体是直接用并渲染后验证的，不会悄悄替换成系统字体。

两个附加设计值得单独说：

• 对比度自动检查：写配置之前，它会验证 ink 在 paper 上的 WCAG AA 对比度。如果你的配色在图表字号（9–12px）下不达标，它会提出一个调整值并解释原因。
• 首次使用会拦一下：在一个新项目里第一次用它，如果风格指南还是默认值，它会停下来问你 —— "这是本项目第一张图，风格指南还是默认的，要不要走品牌适配、手动贴 token，还是就用默认？"它不会默默把默认皮肤的图塞进一个有品牌的项目里。

做多个客户的话，可以把一个品牌存成命名档案，再在客户项目里放一个 .diagram-design 标记文件写上 profile: 名字，这样并行工作区可以各用各的品牌，不会互相覆盖。

七、42 种图为什么不会撑爆上下文

这是这个项目在工程上最值得学的一点。有 42 种图表类型，每种都有独立的排版规范，如果一次全塞进模型上下文，既贵又容易乱。它的做法叫渐进披露：

• 启动时，模型只看到技能名和一句描述
• 请求命中后，加载 SKILL.md（哲学、选型指南、检查清单）
• 具体某一种图表的排版规范，只在选定该类型时才加载

所以你要一张流程图，模型读的是 SKILL.md + references/type-flowchart.md，就这两个。官方 README 里有一张"你要什么 → 模型加载什么"的对照表，把这条讲得很清楚。

它还加了一层语义模式：当"行为"比"形状"更重要时（比如队列和瓶颈、重复的阶段槽位、非结构化输入的转换、成对的政策轨迹、安全铺装路径、治理目录、可追溯的块分解、生命周期阶段图这九种），先选语义模式，再选视觉类型。语义模式不增加图表类型的数量，而是复用最接近的现有类型 —— 这是它能在控制类型总数的同时覆盖更多场景的关键。

八、工程严谨度：一个"个人项目"的 CI 有多重

这一点出乎我意料。这个仓库虽然主要是一个人做的，但 CI 门禁相当密集：

• lint-skin.py 读源码查设计规范，lint-render.py 用无头 Chromium 渲染后查实际画出来的结果（内容被 SVG 视口裁掉、SVG 塌陷、页面横向溢出、缺资源、JS 报错）
• 几何门禁 verify-geometry.py：当某个标签的遮罩与文档中后声明的节点重叠时会失败 —— 因为渲染时节点填充会裁掉文字
• 矩形树图有专门门禁 verify-treemap.py：格子面积占比与格子里印的数值不符就失败（因为它的全部主张就是"面积即编码"），而且用的是相对误差而非绝对误差 —— 绝对误差恰好会放过最容易出错的小格子
• 瀑布图有 verify-waterfall.py：起止值和增减量对不上账、桥接条没画在两个流动水位上、缺少进位连接线、增减量没带正负号，都会失败
• 每个门禁脚本都配了 test-verify-*.py 对抗测试，"让检查器本身也保持诚实" —— 而且测的用例里超过一半是不该被报错的情况

截至 2026-10-01，仓库共约 217 次提交，最后一次是 chore(release): bump plugin manifests to 2.6.51；插件版本号 2.6.51，许可证 MIT。仓库里还有 12 份 ADR（架构决策记录），记录"为什么只保留一个固定的动效控制器""为什么语义模式不增加类型数""为什么标签位置要用几何方式验证"这类已经定下来的决策 —— 并明确写了"重新讨论之前先读它们"。

九、隐私：没有服务器，没有遥测

这一点做得很干净，值得单独说。它的隐私声明写得很明确：没有服务器、没有账号、没有分析、没有遥测，作者收不到你的任何使用数据。

需要留意的两处外部请求：

• Google Fonts：生成的图和模板在浏览器打开时，会从 fonts.googleapis.com 和 fonts.gstatic.com 加载字体。Google 会收到查看者的 IP 和浏览器信息。该请求只声明字体名，不含你的图表内容。想完全避免的话，把生成文件里的 Google Fonts 链接删掉或离线打开，就会回落到系统字体（所有字体都有系统回退）。
• 品牌适配时抓取的网站：只有你主动要求做品牌适配时才会去抓那个站点的少量页面。跳过适配、或者给它一个本地目录，就不会发起任何抓取。

十、它自己说了什么时候不该用

这点挺难得 —— 很多项目只会讲自己多好，它专门写了一节"什么时候不要用这个技能"：

• 想在推文或终端输出里搞快速 Unicode 图 → 用别的工具
• 要列一堆条目 → 用表格或列表
• 要前后对比 → 用表格
• 只有一个框加一个标签的"图" → 直接写那句话

它的自检问题是："读者从这张图里学到的，会比从一段写得好的文字里学到的更多吗？" 如果答案是否，就别画。这个克制，恰恰是它输出的图好看的原因。

十一、几个需要留意的边界

1. 默认没有交互。 悬停态、提示框、下钻这些都要你自己做。动效是可选的，且面向无障碍而非装饰。它不是一个 Figma 替代品，不用于协同设计和评审。
2. 质量取决于你怎么描述系统。 提示词含糊，图就含糊。它是个渲染器，不是需求分析师。
3. 个人项目，巴士系数是真实存在的。 作者 Cathryn Lavery 是 BestSelf.co 的创始人（自己从零做到 5500 万美元营收，2022 年卖给 PE，2024 年又买回来），这个仓库是她的"AI 原生转型"练手项目之一。好在 MIT 许可 + 纯静态输出，即使项目停更，你已经生成的文件也不会失效，最坏情况是换个人继续维护。
4. 它不替代你的架构文档。 它替代的是"把文档做得能看"所花的那一小时。对于要持续产出技术内容（RFC、入职指南、事故复盘、销售材料）的团队来说，这一小时会持续累积。

十二、顺手提醒：别信二手数字

写这篇的时候我把几个转载源的数据对比了一下，漂移得有点夸张：

• 某篇文章说 32,000 star、"39 种图表"
• 某技能目录站说 26,907 star、"38 editorial diagram types"，还说它"主要用 HTML 编写"
• 而 2026-10-02 的 GitHub 官方接口返回的是 43,057 star、2,771 fork

也就是说，二手来源之间差了 1.6 万 star，且全都低于实际值。这个项目 2026-04-16 建仓，半年左右涨到 4.3 万，速度快到所有转载都来不及跟上。品类数字同理（38 / 39 / 42 三个版本并存）。看活跃项目，二手数据基本不可用，直接查一手。

十三、一句话总结

Diagram Design 的核心价值不在"能画 42 种图"，而在两个更朴素的地方：一是把"图好不好看"变成了可执行的规则（一种强调色、坐标被 4 整除、密度 4/10、标签位置用几何验证），而不是靠模型自由发挥；二是把 42 种类型的知识拆成了按需加载的文件，让它在不撑爆上下文的前提下真的能覆盖这么多场景。如果你经常需要把技术内容做成能看的图，它省下的就是那反复发生的一小时。

参考来源

• cathrynlavery/diagram-design 官方仓库 README、SKILL.md、PRIVACY.md、SECURITY.md、.claude-plugin/plugin.json、docs/adr/
• 仓库结构实测：GitHub Trees API（git/trees/main?recursive=1，619 个文件），2026-10-02 查询 —— 42 个 type-*.md、170 个 example-*.html、5 个模板、87 个图标
• 仓库元数据：GitHub REST API（star、fork、许可证、建仓与推送时间、提交数），查询时间 2026-10-02
• 作者信息：GitHub 用户接口（cathrynlavery）
• 线上画廊：cathrynlavery.github.io/diagram-design

本文为项目解读与生态综述，信息取自上述官方仓库与官方接口在 2026 年 10 月 2 日的公开内容，未在本地安装该技能实测。star 数、版本号与图表类型数会持续变化，请以官方页面为准。文中引用的第三方数据漂移对比，取自同期可检索到的转载页面。