简介

diagram-design是一个给AI编程助手用的Agent Skill：把一套编辑级设计系统、选型判断和校验闸门装进Agent，让AI画出的图风格统一、可机检、离线可看。

Agent Skill是把指令、参考文件和脚本打包给AI助手按需加载的机制，原理见《Skill原理》，本文不展开。

这个skill解决一个很具体的痛点：让AI画架构图，收回来的总是千篇一律的圆角盒加青色发光，配色字体和整站不搭；想调整就得打开Figma耗半小时，或者干脆放弃配图。diagram-design的解法是把一套编辑级设计系统连同选型判断、校验闸门一起交给Agent，产出一律是自包含的HTML加内联SVG，不依赖外部服务。

几个基本事实（截至2026年10月，来源为GitHub API实测）：MIT协议；2026年4月创建；约4.6万star；当前版本v2.6；支持Claude Code、Codex、GitHub Copilot、Factory Droid、Pi以及一切兼容Agent Skills的宿主；内置44种图表类型。仓库简介里写的”42 types”是滞后信息，以SKILL.md和44个type-*.md参考文件为准。

整套插件包含一个主skill加六个slash command，共七项能力：

能力	触发方式	干什么
主skill `:diagram-design`	`/diagram-design:diagram-design [自然语言]` 或自然语言（自动匹配）	从一句话需求生成新图：选型、排版、按设计系统出单个自包含HTML
`:import-drawio`	`/diagram-design:import-drawio 文件.drawio`	把draw.io存量图重绘成编辑级图
`:import-mermaid`	`/diagram-design:import-mermaid README.md --diagram=all`	把Mermaid源码或Markdown围栏块重绘成编辑级图
`:import-excalidraw`	`/diagram-design:import-excalidraw 白板.excalidraw`	把Excalidraw白板场景重绘成编辑级图
`:export-diagram`	`/diagram-design:export-diagram 图.html`	把HTML成果导出为SVG/PNG（或块元数据registry）
`:profile`	`/diagram-design:profile save acme`	多客户品牌档案：保存、切换、查看、更新、重置、删除命名皮肤
`:doctor`	`/diagram-design:doctor`	环境体检：一条命令查Python、Playwright等依赖是否就绪，只读不装东西

三个import、export、profile也都能用自然语言触发，比如说”redraw this drawio file for my deck”。下文从安装开始，按使用顺序逐个展开。

安装与启用

文档与地址

GIT地址：https://github.com/cathrynlavery/diagram-design

安装

Claude Code用户两步安装：

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

一个常见的坑：第三方marketplace的自动更新默认关闭。装完进/plugin→Marketplaces→选中diagram-design→Enable auto-update，手动开一次，之后每次启动会在后台刷新。

两种安装途径的差异：

途径	命令	差异
宿主原生marketplace（推荐）	上例；`Codex`、`Copilot`、`Factory Droid`各有对应的`plugin marketplace add`子命令	完整能力：主skill加全部slash command，随marketplace更新
通用`npx skills` CLI（Cursor、Windsurf、Zed等）	`npx skills add cathrynlavery/diagram-design`	独立安装：只含skill本体，无slash command，不随marketplace更新，需`npx skills update diagram-design`手动拉

另外两点注意：Kiro按URL导入，更新要重新导入；Pi没有自动刷新，用pi update --extensions。如果打算直接改style-guide.md做深度定制，受管安装可能被包更新覆盖，建议clone仓库后把skills/diagram-design软链到宿主的skills目录（~/.diagram-design/profiles/和项目级.diagram-design标记不受更新影响）。

首次使用流程

装完之后的最小使用回路分三步：

（可选）先换肤：对它说一句onboard diagram-design to https://你的站点，它抓取首页提取品牌色和字体，展示diff，确认后写入style-guide.md。不定制也能用，默认是一套white-smoke纸面、墨黑文字、珊瑚橙点缀的编辑风。
要图直接说：比如”Make me an architecture diagram of my app: frontend, backend, database, Redis cache”，或者”画一张Q3项目四象限”。
对产出不满意就导出发表：/diagram-design:export-diagram my-diagram.html，拿到SVG和PNG。

跳过第一步也有保护：新工程里画第一张图时，如果皮肤还是出厂默认值，skill会停下来询问要不要定制（first-run gate），不会无提示地把默认皮肤塞进品牌工程。

主skill：生成新图

主skill通过对话使用，说清”画什么、给谁看、放哪里”即可。它内部按四步选型法工作，使用者要了解的是它会问什么、自己拍板什么。

四步选型法

要不要画：列清单用表格，一个框说得清就写句子。判据是”读者看图是否比读一段文字学到更多”。这一步排最前有现实原因：AI的默认倾向是能画就画。
有行为就先选语义模式：当行为、状态、强制、风险是图的主体时，先从9个语义模式里选一个，再套最近的布局类型。对应关系见下表。
没有行为就直接选类型：44种类型按场景分五堆，见下一节。
预算内才画：超过预算就拆成”总览加明细”两张，而不是缩小字号硬塞。渲染前它会先报一句”选了什么类型、什么尺寸、哪些内容会被预算砍掉”，这是改主意的窗口，不要跳过。

语义模式与图表类型的对应：

要表达的事	语义模式→落到的类型
多来源挤有限容量的服务	扇入队列/瓶颈→Data flow
各阶段重复同样的问题、输入、管控、输出	阶段框架带语义槽→Process
对话、随笔变成结构化制品	非结构化→结构化→Data flow
两个相似请求为何结果不同	成对策略求值轨迹→Flowchart
哪些路径能穿信任边界、哪些被拦	安全铺路石→Architecture
控制项按强制执行界面归类	治理控制目录→Layer stack
每层防线补上层漏下的风险	补偿安全层→Layer stack
系统拆成可溯源到代码的块	可追溯块分解→Tree
一个对象经历阶段、等待、重试、终态	生命周期阶段图→State machine

44种类型按场景分五堆

没有行为要表达时直接选类型，44种类型分五堆：

系统与数据平台结构（11种）：Architecture、Architecture delta、IT current-state、High-Level、Deployment、Dependency graph、Layer stack、Medallion、DP integration、DP security matrix、Data flow。
流程时间交付（13种）：Flowchart、Sequence、State、Swimlane、Process、Timeline、Gantt、Loop、Kanban、Story map、User journey、Wardley、Fishbone。
结构与建模（6种）：ER、DB schema、UML class、Tree、Nested、Org chart。
定量与定位（12种）：Bar、Line、Scatter、Radar、Polar、Heatmap、Treemap、Sankey、Waterfall、Pyramid、Venn、Quadrant。
空间（2种）：Exploded axonometric、Axonometric plan。

两条口诀：树表达不了的扇入和环，选Dependency graph；包含表层级选Nested，连线表父子选Tree；两种都像就选主轴。

尺寸与预算

说”放博客里””做进PPT””发推的OG图”，它会据此推断size预设。共10档：doc-inline（960×600，默认）、doc-wide、slide-16x9、slide-4x3、social-og、social-square、三种print、fit。预设同时决定viewBox和字号档，例如投屏slide档的节点名自动放大到16px。

预算线：不超过9个节点、12条连线，强调色不超过2处，注释不超过2条。超了就拆”总览加明细”两张——拆分优于缩字（splitting beats shrinking），不允许缩小字号硬塞。

三种静态变体

每张图有三种静态版本：minimal light（默认，截图即用）、minimal dark（暗色站和幻灯片）、full editorial（长文hero图，带总结卡）。说”要暗色版”或”要完整版卡片”即可切换。

另有两个特殊变体：手绘sketchy滤镜（随笔散文用，技术文档禁用）和terminal窗口皮肤（写CLI工具文章用，不参与换肤）。想手工起步，复制assets/template.html，替换标题和SVG体即可。

中文标签

中文节点名可以直接用。正确姿势是给含中文的<text>元素单独扩字体族，而不是换整张皮肤：

1	'Geist', 'Noto Sans SC', 'PingFang SC', 'Microsoft YaHei', sans-serif

要点三条：

CJK名字下限12px，放不下砍名字，不缩字号；子标签（端口、协议、字段类型）保持拉丁字符不翻译。
宽度预算按每个全角字符1em计，全角标点（（）「」，。：）最容易漏算。
一个隐性坑：默认字体link里带了繁中TC和韩文KR的Noto，没有简中SC。查看者本机没装中文字体时，简体标签会落到系统回退字体，重要图要自己先渲染验证。

import命令：重绘存量图

三个import命令共用同一套流程，差别只在接受哪些源文件：

1
2
3

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

原则：重绘不是转换

源文件只提供内容（组件、关系、分组、方向），坐标、配色、字体、主题一律丢弃，从空白画布重新排版。它不会复刻Mermaid的自动布局——那正是要被替换掉的东西。

画前必设的四个参数

事后改参数等于重画，所以三个import命令的参数一致：

参数	取值	默认	说明
`--format`	`html`/`svg`/`png`/`html+png`	`html`	非HTML格式都从HTML导出，不手搓SVG
`--size`	上述10档尺寸预设	`doc-inline`	同时决定viewBox和字号档
`--detail`	`faithful`≤24节点/`balanced`≤12/`simplified`≤7	`balanced`	faithful是唯一可超9节点预算的档：超过9必须分区加标签，超过24强制拆图，连线规则不放松
`--audience`	`engineer`/`mixed`/`executive`	`mixed`	只管措辞不管数量：同一节点`Auth Service / JWT · RS256 · :8443`会随档位缩成`Auth Service / token check`，再到`Sign-in`

另有--variant=light|dark|full选变体、--type=architecture强制指定类型（默认从抽取结构推断）。Mermaid多块文件用--diagram=N|all指定块号，all时每块独立选型、独立出文件，不合并画布。

各源支持范围

命令	接受	不支持/注意
`import-drawio`	`.drawio`、`.drawio.xml`、`.xml`、`.drawio.png`（图嵌在PNG里）、`.drawio.svg`，含压缩payload	多页文件会列出页码询问要哪页，`–page=N
`import-mermaid`	`.mmd`、`.mermaid`、Markdown围栏块；语法限`flowchart/graph`、`sequenceDiagram`、`stateDiagram-v2`、`erDiagram`	pie、mindmap、gitGraph、C4、sankey等直接报错，不能用别的类型近似凑
`import-excalidraw`	`.excalidraw`、`.excalidraw.json`场景文件	拒收导出的PNG/SVG，要用保存的场景文件

删减必须如实报告

节点超过detail预算时，按固定的降级阶梯砍：装饰件→完全重复项（6个worker合并成Worker ×6）→叶簇→不影响故事的汇聚点→横切基础设施→还超就拆图。交付时附一份fidelity ledger：

Detail: balanced · 18 source nodes → 9 drawn
Merged:    worker-01..06 → "Ingest Worker ×6"
Collapsed: "Observability" group (Grafana, Loki, Tempo) → one node
Dropped:   2 sticky notes, CI pipeline (cross-cutting)
Kept in full: the request path (Client → Gateway → Orders → Postgres)

这份清单存在的理由：图的读者看不见缺了什么，要图的人必须知道。另有两条措辞铁规：源里只有编号（如svc-04）没有解释时，保留编号并提问，不许编造业务名；把Kafka写成”消息总线”是概括，写成”Event Grid”是事实错误。

export命令：导出SVG/PNG

/diagram-design:export-diagram my-diagram.html                  # 默认SVG+PNG都出
/diagram-design:export-diagram my-diagram.html --svg-only       # 只SVG，不碰Playwright
/diagram-design:export-diagram my-diagram.html --png-only --scale=3
/diagram-design:export-diagram my-diagram.html --registry       # 只出块元数据JSON

默认行为：不带格式参数时，SVG和PNG都生成在源文件旁；--scale控制PNG倍率（默认2×）；--output=<path>改输出路径。
SVG：抽出<svg>节点并注入Google Fonts，可在浏览器、Figma、Illustrator中独立渲染；官方脚本会把class CSS带进片段、给defs的id加命名空间，保证多张图内联到同一页面不撞名。
PNG：Playwright光栅化，一次性setup：pip install playwright && playwright install chromium。
--registry是独立旁路：给”可追溯块分解”模式的图导出每个块的data-block-*元数据JSON，单独使用只出JSON，不需要Playwright。
两种格式都只导图形本体，full editorial的卡片页眉按设计丢弃；要整页排版效果用浏览器打印。导出永远手动触发，不会未经要求生成文件。

profile：多客户品牌档案

品牌换肤结果可以存成命名profile，供多项目、多客户复用。管理命令六个动词：

/diagram-design:profile              # 不带参数=list，当前生效的会标出
/diagram-design:profile save acme    # 把当前工作皮肤存为命名档
/diagram-design:profile load globex  # 加载（裸名字=load，switch同义）
/diagram-design:profile show / update globex / reset / delete acme

存储位置：~/.diagram-design/profiles/<slug>.md（带frontmatter的token文件），跨Claude Code、Codex、Droid、Pi共享；内置一个default档。
项目绑定：在项目目录放一个.diagram-design标记文件，内容profile: <slug>，此后该工程生成图时直接读对应profile，不碰共享的style-guide.md——多个并行项目各用各的品牌，互不覆盖。
覆盖已有档、改标记、删档前都会要求确认，脚本调用也不例外。
onboarding流程再展开一次：它抓取首页后按固定映射提取token——body背景→paper、主文字色→ink、次级文字→muted、卡片底→paper-2、最常用的品牌色→accent、h1/body/code字体→标题/节点名/子标签。写入前自动校验WCAG AA对比度，不合格给出调整值；完成后出一份fidelity receipt（来源URL、每个角色的精确色值、字体族/字重/来源、回退声明），公开站上字体渲染后会验证，绝不悄悄替换成系统字体。

doctor：环境体检

1	/diagram-design:doctor [--strict] [--json]

一条命令回答”这台机器能不能完整跑diagram-design”。检查项包括：python3解释器（要求≥3.10，Windows商店那个假的python3它也能识破并回退）、PNG导出所需的Playwright加Chromium（缺失只标warn，绝不自动装依赖）、常见路径误用；在仓库checkout里会追加维护者级检查（校验脚本、插件清单齐全性）。输出为逐项pass/warn/fail摘要加Next actions：--strict把warn按fail算，--json给机器可读报告。全程只读。

设计约束与原理

前述能力为什么长这样，可以从四层看。

输出形态决定一切。 交付物是单文件自包含HTML加内联SVG加内嵌CSS，除Google Fonts外零依赖、零构建、默认零JS——浏览器就是渲染器，离线双击可开，截图即可发表。无障碍是默认契约：<svg>带role="img"和aria-labelledby，首个子元素是<title>，配一句话<desc>，id按文件前缀命名防止同页多图撞名。动画是可选表现层（none默认/reveal/step/loop），静态首帧必须完整表意，prefers-reduced-motion下隐藏播放控件。

“不像AI画的”是硬约束堆出来的。 所有规则收敛在一个style-guide.md（换肤只改这一个文件）：颜色按语义角色引用（paper/ink/muted/soft/rule/accent/link），不写裸hex；accent全图不超过2处，涂4处等于没决定重点是谁；三套字体各司其职——Instrument Serif管标题斜体，Geist 600管人类可读的名字，Geist Mono只放技术值（端口、命令、URL），点名禁用JetBrains Mono当氛围字体；一切坐标、宽高、间隙被4整除；描边0.8/1/1.2三档，圆角不超过10px，任何元素无阴影。连线有六条违例即fail的铁律：只许正交折线；标签垫不透明mask并留6到10px间隙；禁止线线重叠；锚点均匀扇形分配、间距不小于12px；禁止穿过非端点节点；mask不得压住后画的节点。出图前跑一遍Taste Gate清单（含”删除测试”三连问：能删节点吗、能合并吗、能删线吗），安装版还能用python3 scripts/self_check.py机检。它点名的”AI slop”反模式清单本身就值得读：暗色底加cyan紫发光（”看起来技术，但没有设计决策”）、全等方框抹掉层级、三张等宽卡片、复刻Mermaid自动布局。设计哲学一句话：The highest-quality move is usually deletion——图不是加满算完，是删到无可再删；目标密度4/10。

重绘靠抽取而非渲染。 三个import各自配一个纯文本Python抽取器，把源文件解析成统一IR（节点、边、容器、环、可折叠组、预算标记），不求值渲染执行、不联网、不打开链接；源文本一律按不受信数据处理——标签里嵌的”指令”只是内容，绝不服从（防提示注入）。抽取失败就原样报错停下，不许”拿去在线渲染一下”当退路。不可丢弃的内容有明确清单：时序图的alt/loop片段、ER基数与字段、状态guard、容器归属、有意义的边标签和环。

架构是Agent Skill渐进披露的活标本。 SKILL.md约390行，只做哲学、选型路由、闸门清单；62个reference按需加载——画flowchart只读type-flowchart.md，行为图加读semantic-patterns.md，做动画才碰animation.md，新增类型不碰任何旧文件。类型层与语义层解耦（44种布局×9种行为模式），新语义不必新增类型。系统机制见《Skill原理》，Mermaid侧的语法速查见《Mermaid语法速查》：Mermaid管快速写，这套管发表，import-mermaid正是两者的接头。

总结

能力	一句话
主skill	四步选型（要不要画→语义模式→类型→预算），超预算拆而不缩；中文标签12px下限、全角按1em预算
import×3	重绘不是转换；四参数画前定（format/size/detail/audience）；降级阶梯固定序；删了什么必进fidelity ledger
export	HTML是唯一事实源，SVG/PNG从它导出；只导图形本体；registry是元数据旁路
profile	一次onboarding存成命名档，项目放`.diagram-design`标记绑定；profile库跨宿主共享
doctor	Python≥3.10加Playwright就绪度，只读体检
设计底座	语义token单文件换肤；accent≤2；mono只放技术值；坐标÷4；无阴影；连线六律；删除哲学

使用要点三条：提需求时说清放哪、给谁看（会触发size和audience推断）；它画前的选型报告值得认真看一眼再放行；收到重绘结果，先看fidelity ledger再信图。

下一步实践：拿本系列一张现成的Mermaid图跑一次/diagram-design:import-mermaid --detail=balanced，实测中文标签的简中SC字体回退效果和self_check.py的手感；顺手跑一次doctor把体检基线记下来。

成果展示

下面是我负责的一个项目所绘制的架构图，暂时可能样式、完整性还有待补充（这不属于diagram-design的工作范畴了）

图表设计Skill——diagram-design

简介