diagram-design Skill 怎么装？图表导出踩坑与用法

diagram-design 是一个跑在 Claude Code、Codex 和 Pi 上的图表生成 Skill：你说一句「帮我画个架构图」，它产出一张可以直接放进文章、幻灯片和官网的编辑级图表，格式是自包含的 HTML + SVG，没有构建步骤、没有 JS 依赖，浏览器直接打开就能看。

这个项目 2026 年 4 月开源，官方 GitHub 仓库 当前约 4 万 star、2.6k fork，作者是 BestSelf.co 创始人 Cathryn Lavery。它解决的是一个人人都烦的问题：让 AI 画图，出来永远是「圆角方块 + 紫色阴影」的 AI 味图表。中文圈目前几乎没有像样的教程，这篇一次讲清安装、品牌配色、版式清单，以及社区里真实出现过的那几个坑。

它能做出什么

• 仓库描述当前口径是 38 种编辑级图表版式：架构图、流程图、时序图、状态机、ER 图、时间线、泳道图、四象限等
• 每种版式自带三套皮肤：极简浅色、极简深色、完整编辑风
• 默认 jet-black + atomic-tangerine 配色，开箱截图就能用
• 60 秒品牌适配：读你的网站，自动提取配色和字体，之后每张图都用你的品牌
• 能把 draw.io / Mermaid 旧图按目标场景重绘：导 PNG 进幻灯片、导 SVG 进 Figma
• 可选动效（reveal / step / loop），默认纯静态、无脚本

这里要提醒一句：版式数量这个数字一直在变。维护者自己的 issue #211 里指出过 README 的计数滞后（README 写 39、实际已发布 40），也记录过画廊序号错乱的问题。所以别记数字，装好之后以 Skill 实际列出的清单为准。

一句话：适合做技术文章配图、汇报幻灯片、官网架构示意，不适合画促销海报。

安装：Claude Code（两行命令）

在 Claude Code 会话里执行：

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

装完建议开一次自动更新：运行 /plugin，打开 Marketplaces，选中 diagram-design，点 Enable auto-update（Claude Code 对第三方市场默认关闭自动更新）。按提示执行 /reload-plugins。

安装：Codex

在终端执行：

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

Codex 启动时会自动刷新市场；想立刻拉取就执行 codex plugin marketplace upgrade diagram-design，然后开新会话。

安装：Pi

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

在已打开的 Pi 会话里执行 /reload。之后用 /skill:diagram-design 显式调用，/import-mermaid、/profile 等提示词模板也会一并加载。

装完没反应？先按顺序排查这三步

1. 会话没重载：Claude Code 执行 /reload-plugins，Pi 执行 /reload，Codex 直接开新会话，三者都需要让 Skill 清单重新加载。
2. 市场没刷新：Claude Code 看 /plugin 里 Marketplaces 是否已包含 diagram-design；Codex 执行一次 codex plugin marketplace upgrade diagram-design。
3. 调用方式不对：装好后直接用自然语言提需求即可触发，不需要你手动指定版式；Pi 上想显式调用才用 /skill:diagram-design。

快速上手：直接说话就行

装好后不用记命令，直接提需求，Skill 会自己挑版式并保存 HTML 文件：

• 「给我的应用画个架构图：前端、后端、数据库、Redis 缓存。」
• 「画一个四象限，把 Q2 的项目按影响力 × 投入放进去。」
• 「画一张时序图：带 token 刷新的 bearer 调用，401 时走 ALT 分支。」

60 秒品牌适配（最值得做的一步）

对它说「onboard diagram-design to https://你的网站」，它会：

1. 抓取首页，提取主色和字体栈
2. 把检测到的值映射到语义角色：paper（背景）、ink（主文字）、muted（次级文字）、accent（强调色）
3. 给你一份确认 diff，你回复确认后写入 style-guide.md

之后每张图自动用你的品牌色：网站的背景色变成图表底色，CTA 色变成焦点强调色，正文和标题字体也会跟着走。它还会自动做 WCAG AA 对比度检查，图表小字号下不达标的颜色会主动给出调整建议。

首次在新项目里使用时它会停下来问：运行 onboarding、手动贴色值，还是先用默认皮肤，不会悄悄把默认样式混进你的品牌项目。

不过要注意：默认皮肤本身也不是对比度满分。社区 issue 里明确记录过，默认配色的 accent 在 paper 背景上对比度只有 2.86:1，低于 AA 要求，所以默认皮肤更适合当草稿，正式稿建议走一次品牌适配。

把 draw.io / Mermaid 旧图重绘

已有旧图不用重画，直接让它按新设计系统重绘：

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

四个可调旋钮：

• Format：html / svg / png / html+png，按交付场景选
• Size：doc-inline、doc-wide、slide-16x9、social-og、print-a4-landscape 等，尺寸会同时改变字号阶梯
• Detail：faithful（≤24 节点）/ balanced（≤12）/ simplified（≤7），按固定降级阶梯删减
• Audience：engineer / mixed / executive，改的是措辞不是节点数

每次导入结束会给一份「保真清单」：哪些节点被合并、哪些被丢弃，一目了然。支持 .drawio、.drawio.xml、.drawio.png（内嵌图）和 Mermaid 的 .mmd、Markdown 代码块。

社区里真实踩过的五个坑

这部分全部来自该仓库公开的 issue 列表，不是推测：

多品牌 / 多客户怎么管理

~/.diagram-design/profiles/ 可以存多套品牌 profile，Claude Code、Codex、Pi 三端共享。在客户项目根目录放一个 .diagram-design 标记文件，写上 profile: <slug>，不同项目自动切品牌，不会互相覆盖。

版本与更新节奏

这个项目迭代非常密：仓库已经积累 300 多次提交、上百个 tag，最新版本在 2026 年 9 月仍在持续发版；同时保持约 20 个 open issue、近 30 个 open PR 的活跃维护状态。

对你意味着两件事：一是值得开自动更新，跟上新版式和新修复；二是遇到问题先去 issue 列表搜一遍，大概率已经有人报过并且有绕行方案。

什么时候不该用它

作者自己列了反面清单：推特和终端里用的 unicode 小图、任何形式的列表、前后对比，这些用表格或文字更好；只有一个框一个标签的「图」，不如直接写一句话。画之前先问自己：读者从这张图得到的信息，比一段写得好的文字更多吗？

相关阅读

• Dashi PPT Skill 完全教程：用 AI 做汇报演示文稿
• gc-minimal-zine-poster 中文教程：海报生成 Skill 安装与使用
• 去AI味 Skill 实测全指南：7 个开源项目怎么选
• ffmpeg-skill 怎么用：一条命令装上视频剪辑
• 项目主页与 issue 列表：https://github.com/cathrynlavery/diagram-design