cathrynlavery/diagram-design — 编辑级 AI 图解生成

让 AI 生成可编辑的 HTML 和 SVG 图解。
本周新增 Star 6,638 ｜ 仓库 Star 总数 60,276 ｜ Forks 3,893

▲ 图 0：Diagram Design 官方 Logo（官方图）

▲ 图 1：diagram-design 官方演示（官方截图）

官方架构图示例

▲ 图 2：Architecture 图解示例（官方截图）

官方时序图示例

▲ 图 3：Sequence 图解示例（官方截图）

官方树状图示例

▲ 图 4：Tree 图解示例（官方截图）

一、核心理念

不是"把 Mermaid 渲染得好看点"，而是重新定义图解的视觉语言。

典型提示词：

• "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
• "I need a quadrant showing Q2 projects by impact vs effort."
• "Give me a sequence of a bearer call with token refresh on 401."
• "Onboard diagram-design to https://yoursite.com"（抓取你站点的调色板与字体，让之后每张图都一致）

智能体会选定类型、说明计划，然后写出 一个 .html 文件 —— 双击就能打开。

45 种图解类型

架构、流程图、时序图、UML 类图、ER 图、状态机、泳道、旅程图、故事地图、看板、甘特图、瀑布图、四象限、雷达图、树状图、桑基图、层级树、热力图、散点图、极坐标、维恩图、金字塔、堆栈、爆炸图、axonometric 平面图、鱼骨图、方差矩阵、安全矩阵、服务蓝图、依赖图、部署图、数据流、DP 集成、层次分解、极简架构、高级架构、圆环流程、循环图、迁移图、决策树、组织架构、封面/标题图、行业 IT 状态图、旅程/漏斗、路线图、时间线等。

二、部署方式

方式 A：通用 skills CLI（覆盖绝大多数客户端）

适用于任何读取 Agent Skills 的主机：Cursor、Claude Code、Codex、Qoder、GitHub Copilot、Gemini CLI、Cline、Windsurf、Amp 等。

npx skills add cathrynlavery/diagram-design

跨智能体的 skills CLI 会解析本仓库，检测到 skills/diagram-design/SKILL.md，并把整个 skill（references/、assets/、scripts/）安装到你选择的每个主机根目录。

• 当选中的根目录解析为 多个 skills 目录时，CLI 会询问安装方式并推荐 Symlink —— 一份规范副本，链到每个根目录，之后一次更新同时到达所有地方
• 传 --copy 可为每个主机做独立副本
• 选中项只解析为单个目录时会直接复制（此处区分无意义）
• Windows 未开启开发者模式、符号链接不可用时，CLI 回退为复制并报告哪些根目录被复制

这是 独立安装，与下面的 marketplace 分离：它 不自动跟随 marketplace 更新。用 npx skills update diagram-design 拉取合并后的更新。

独立安装 只装 Agent Skill，/export-diagram、/import-mermaid、/profile、/doctor 这些命令界面仍属原生包。若你的主机支持下面某个 marketplace，优先用 marketplace。

方式 B：Claude Code —— 插件市场（带更新与斜杠命令）

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

开启自动更新： 运行 /plugin → 打开 Marketplaces → 选择 diagram-design → 选择 Enable auto-update。Claude Code 对第三方 marketplace 默认关闭自动更新；开启后会在启动后后台刷新市场与已安装插件。提示时运行 /reload-plugins，或让下次会话加载更新。

方式 C：Codex

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

Codex 在启动时刷新已配置的 Git marketplace。要立即拉取，运行 codex plugin marketplace upgrade diagram-design 并开启新会话。

方式 D：Qoder

git clone https://github.com/cathrynlavery/diagram-design.git
qoder plugins validate ./diagram-design
qoder plugins install ./diagram-design
qoder plugins list

Qoder 直接加载规范的 skills/diagram-design/ 树与共享命令定义，不维护 Qoder 专属副本。

Qoder IDE： 从受版本控制的插件面构建有界 ZIP，再通过 Extensions → Plugins → Add Plugins → Upload Plugin 导入：

git -C diagram-design archive --format=zip \
  --output=../diagram-design-qoder.zip HEAD \
  .qoder-plugin commands skills LICENSE

安装或更新插件后需开启新任务。

方式 E：GitHub Copilot

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

用 copilot skill list（或交互会话中的 /skills）确认发现，然后用自然语言要一张图。拉取合并更新：

copilot plugin marketplace update diagram-design
copilot plugin update diagram-design@diagram-design

方式 F：Factory Droid

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

Droid 按 commit 而非清单的显示版本跟踪 Git 插件。更新：

droid plugin marketplace update diagram-design
droid plugin update diagram-design@diagram-design --scope user

然后开启新会话。

方式 G：Claude Cowork（组织市场）

组织 GitHub marketplace 目前要求私有或内部仓库，因此需 先把本公开仓库镜像到你自己组织拥有的仓库。在 Organization settings → Plugins → Add plugin → GitHub，连接该镜像，并从 marketplace 菜单启用 Sync automatically。

自动同步在含插件版本提升的 PR 合并到镜像默认分支时触发（直接 push 不触发 webhook）。然后从组织 marketplace 安装。

方式 H：Pi

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

在打开的 Pi 会话中运行 /reload。Pi 会为匹配的图解请求提供该 skill；用 /skill:diagram-design 显式调用。Pi 还会加载 /export-diagram、/import-mermaid、/import-excalidraw、/profile、/doctor 提示模板。

未固定版本的 Git 安装是 有意为之 —— Pi 没有自动包刷新机制，需运行 pi update --extensions 拉取合并后的更新。

方式 I：Kiro

从仓库子目录 URL 导入 Agent Skill：

https://github.com/cathrynlavery/diagram-design/tree/main/skills/diagram-design

Kiro 把导入的 skill 复制到工作区的 .kiro/skills/ 或全局的 ~/.kiro/skills/。要更新需 重新导入该 URL。自定义智能体若声明资源，应包含 skill://diagram-design/**/SKILL.md。

方式 J：OpenCode

把 skills/diagram-design/ 复制或符号链接到项目的 .opencode/skills/diagram-design 或全局的 ~/.config/opencode/skills/diagram-design。OpenCode 没有 Diagram Design 的 marketplace 包；复制安装仅在用更新的 checkout 替换目录时才会更新。

方式 K：可编辑安装（想自定义风格指南时）

托管安装方便，但修改 references/style-guide.md 可能在包更新时被覆盖。已保存的 profile 在 ~/.diagram-design/profiles/ 中 能存活更新，带 .diagram-design 标记的项目也不受影响。要直接改工作风格指南，请克隆仓库并安装本地路径：

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design

# Pi：把 checkout 注册为本地包
pi install ~/code/diagram-design

# Claude Code：符号链接内层 skill
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

# 其它 Agent Skills 主机：只创建你实际用的根目录
mkdir -p ~/.agents/skills ~/.cursor/skills ~/.cline/skills ~/.kiro/skills ~/.config/opencode/skills ~/.copilot/skills
ln -s ~/code/diagram-design/skills/diagram-design ~/.agents/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.cursor/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.cline/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.kiro/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.config/opencode/skills/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.copilot/skills/diagram-design

三、使用方法

3.1 快速上手

在克隆的 checkout 中打开画廊看全部图解：

open skills/diagram-design/assets/index.html       # macOS
xdg-open skills/diagram-design/assets/index.html  # Linux

Windows：

start skills\diagram-design\assets\index.html

直接从模板起步：

cp skills/diagram-design/assets/template.html my-diagram.html        # 极简浅色
cp skills/diagram-design/assets/template-full.html my-diagram.html   # 含摘要卡片的编辑级版式
cp skills/diagram-design/assets/template-motion.html my-diagram.html # 可选的无障碍动效

然后直接向你的智能体要一张图。

3.2 语义模式与可选动效

当行为比形状更重要时，skill 先选语义模式，再选视觉类型。九个可路由的模式覆盖：

扇入队列与瓶颈、重复阶段槽位、无结构输入转换、成对策略追踪、安全铺路、治理目录、补偿性安全层、可追溯的块分解、生命周期阶段图。

每个模式定义了触发条件、原语、预算、反模式、静态回退与最近的视觉类型（见 references/semantic-patterns.md）。

动效是可选的，不会创造新的视觉类型。 animation.md 定义了 none、reveal、step、loop 四种模式，要求有完整的静态首帧、确定性时序，以及交互可用时的控件。

• 减弱动效输出 显示完整静态帧并隐藏/禁用播放控件
• 动效 HTML 必须使用 template-motion.html 中 经过审查的 控制器；任意的或被修改过的内联脚本、远程资源、CSS import 与可执行 HTML 属性都会被 拒绝
• 默认是 none —— 普通输出保持静态且无脚本

3.3 从 draw.io / Mermaid / Excalidraw 导入

已有 draw.io（diagrams.net）、Mermaid 或 Excalidraw 图？指向源文件，skill 会 重绘 它们：同样的内容，这套设计系统，按目标所需尺寸。

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

或者直接说："redraw this drawio file for my deck"、"make this Mermaid block editorial"、"この Mermaid をスライド用にきれいにして"。

支持的容器格式：

• draw.io：.drawio、.drawio.xml、内嵌图的 .drawio.png、.drawio.svg（含看起来像 base64 乱码的压缩载荷）
• Mermaid：.mmd、.mermaid，或 Markdown 中一个或多个 ```mermaid 围栏块。UTF-8 文件可能带 BOM
• Excalidraw：.excalidraw、.excalidraw.json 场景文件（不支持 .excalidraw.png / .excalidraw.svg 导出）
• 只解析文本：无渲染、无 JavaScript、无浏览器、无网络、不跟随点击目标

3.4 四个旋钮

重点不是转换，而是 把输出适配到它要去的地方。同一源文件，三种不同结果：

每次导入都以一份 保真度账本（fidelity ledger） 结束，列出什么被合并、折叠或丢弃：

Detail: balanced · 12 source nodes → 8 drawn
Collapsed: "Token valid?" decision → edge label on Gateway → Auth
Dropped:   1 sticky note ("legacy path, to be retired"), unconnected in source
Kept in full: the request path (Web/Mobile → Gateway → Orders → Postgres)

永不承接的： 源或渲染器的坐标、源调色板、源字体、draw.io 的斜向连接线乱麻、Mermaid 的自动布局、Excalidraw 的手绘几何。
永远承接的： 组件、关系、分组、方向。

3.5 导出 PNG / SVG

图解以自包含 HTML 交付，但你可以把图解本体导出给 Figma、幻灯片或社交卡片。

Pi：

/export-diagram path/to/diagram.html
/export-diagram path/to/diagram.html --svg-only
/export-diagram path/to/diagram.html --png-only --scale=3
/export-diagram path/to/diagram.html --registry

Claude Code：

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

或直接说："Export this diagram as SVG and PNG."

• SVG 抽取 ` 节点并注入 Google Fonts，使其能在浏览器、Figma、Illustrator 中独立渲染。动画绑定遵循带命名空间的 keyframes，即使属性名使用 CSS 转义。传--system-fonts` 可跳过字体导入以离线使用。
• PNG 通过 Playwright 以 2× 默认倍率光栅化。一次性准备： pip install playwright && playwright install chromium
• 两种格式都 只含图解本体 —— -full 变体中的编辑卡片与页眉不包含在内。要截取完整编辑版式，用浏览器的打印为 PDF 或整页截图。
• --registry：对使用可追溯块分解模式的图解，额外输出 .registry.json，把每个块的 data-block-* 元数据结构化投影出来。

动效 HTML 导出： 打开 ?motion=static，等待 document.fonts.ready，确认动效根节点有 data-frame="static" 后再捕获。仅在明确要求某个中间帧时才用 ?motion=step&step=N。

3.6 品牌化引导

Onboard diagram-design to https://yoursite.com

skill 会抓取你的 调色板与字体，让之后每张图都匹配你的站点。

流程：

1. 检测 —— 抓取站点，识别调色板、字体与设计 token
2. 提取 —— 抽取主色、强调色、中性色与字体栈
3. 对比度检查自动进行 —— 无障碍对比度在生成时就校验
4. 默认无障碍 —— 生成的颜色组合满足 WCAG 对比度要求
5. 离线字体 —— 可用时使用本地字体，避免依赖外部 CDN
6. 手动覆盖 —— 需要时可手动指定
7. 首次运行闸门 —— 未完成品牌配置前会先询问

已保存的 profile 在 ~/.diagram-design/profiles/ 中，能存活包更新；带 .diagram-design 标记的项目不受影响。

3.7 多客户端协作

同一 skill 可在多个客户端间共享。保存的 profile 全局通用，项目级标记让项目自带样式上下文。

3.8 架构：渐进式披露

SKILL.md 先路由行为（需要时），再路由版式。语义、类型、动画参考 只在相关时才加载。

diagram-design/
├── SKILL.md
├── references/       # 版式、类型、语义模式、动画、导入、输出规范
├── assets/           # 模板、示例、画廊 index.html
└── scripts/          # 导出、校验工具

渐进式披露的意义： 不把 45 种类型的全部细节一次性塞进上下文 —— 只在需要时加载相关的那几份。

四、什么时候 不该 用这个 skill

官方文档明确列出了反模式。在以下场景请用普通图表工具：

• 需要严格遵循企业既有图表规范（Visio、draw.io 模板）的场景
• 需要实时数据流或动态交互式仪表盘（不是静态图解）
• 只需要一张快速草图，不需要可编辑、可导出的成品
• 团队已有成熟的 Mermaid + 主题化工作流

参考链接

• 仓库：https://github.com/cathrynlavery/diagram-design
• 官网：https://diagramdesign.dev
• 烹饪手册：https://github.com/cathrynlavery/diagram-design/blob/main/docs/cookbook.md
• 隐私说明：https://github.com/cathrynlavery/diagram-design/blob/main/PRIVACY.md
• 贡献指南：https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md