diagram-design 接入 Claude Code 的实操 SOP

一、这套 SOP 解决什么问题

diagram-design 是 cathrynlavery 维护的一套开源图表技能包，采用 MIT 许可，在 2026 年 9 月 14 日的 GitHub 周榜上排到第 2 名，截至 9 月 15 日实核星标数为 39,807。它不是某个厂商的私有工具，而是一套可以装进多个 AI 编码宿主、照着你的品牌风格出图的技能。

它最值得说的点是：出图产物是一个独立的 HTML 文件，双击就能离线打开，除了 Google Fonts 之外没有任何网络请求；整张图可以被品牌化，变成你站点的纸色、墨色、强调色和字体；它还自带可访问性（屏幕阅读器能朗读标题与描述）和自带的输出校验脚本。

但它能干什么、不能干什么，边界非常清楚。它能画的是结构化的、可编辑的图：架构图、流程图、象限图、时序图、状态图等共 39 种。它不画插画，也不做数据可视化，你别指望用它画折线图、柱状图、热力图那种以数值映射为主的图。它的定位是"把架构与流程讲清楚"，不是"把数据画漂亮"。

它同时以两种形态发布：一种叫 Agent Skills（技能），另一种叫插件包（plugin）。这带来一个现实好处：Claude Code、Codex、Factory Droid、Pi、GitHub Copilot、Kiro、OpenCode 等宿主都能接。但正因为每种宿主的更新机制都不一样，这套技能包真正的门槛不在"安装"这一步，而在"版本更新路径"和"产出物边界"这两处。下面每一节都会把这两件事讲透。

如果想先了解它和同类工具的差别，可以看 AI 图表方案横评；想看它作为技能框架的定位，可以看 AI 编码技能框架横评。另一篇 diagram-design 项目介绍 也值得一读。

二、各宿主安装与更新命令对照表

先说环境准备。常规使用不需要任何额外依赖。只有当你要导出 PNG 时，才需要一次性装一个依赖：

pip install playwright && playwright install chromium

导出 SVG 不需要这个依赖，所以如果你暂时只做网页内嵌或 Figma 导入，可以跳过这步。

安装时按你用的宿主选一条，命令逐字照抄。下面这张表是全文最实用的部分，建议收藏。

确认 Copilot 是否发现技能，用 copilot skill list（交互会话里是 /skills）确认。Pi 装完还会加载 /export-diagram、/import-mermaid、/import-excalidraw、/profile、/doctor 这几个 prompt 模板，显式调用用 /skill:diagram-design。

下面几节以 Claude Code 为主线讲实操，因为它对第三方 marketplace 的更新默认关闭，最容易踩坑。如果你装的是 Codex，可以直接看 Codex harness 接入实操。

三、首次运行 gate 与品牌 onboarding

装好之后，在一个没定制过样式指南的新项目里首次出图，技能不会闷头用默认皮肤，而是暂停并问你："这是本项目的第一张图，样式指南还是默认值。要跑 onboarding、手动粘贴 token，还是就用默认？"这个 gate 是设计上故意的，目的是逼你想清楚要不要品牌化。

如果你想要图长得像你自己的品牌，直接说：

onboard diagram-design to https://你的站点

它会做这几件事：抓取你的首页，抽取主色调与字体栈，把颜色映射到语义角色（paper、ink、muted、accent、link、paper-2），给你看一串 proposed diff，确认后才写入 references/style-guide.md。

映射规则要记牢：<body> 背景对应 paper；主文本色对应 ink；次级或图注文字对应 muted；卡片或容器对应 paper-2；最常用的品牌色（CTA、链接、标题）对应 accent；<h1> 字体对应 title；<body> 字体对应 node-name；<code> 或 <pre> 字体对应 sublabel。

写入前它会自动做 WCAG AA 对比度检查：如果你的品牌色在图内 9 到 12px 的字号下不达标，它会给出调整值并解释原因。它还会输出一份 fidelity receipt：列出采样的 URL、确切的颜色角色、字体族与字重、字体来源 URL，以及任何回退。公共站点字体会被直接使用并在渲染后校验，而不是被悄悄换成通用系统字体。

不想自动跑也可以手动改 skills/diagram-design/references/style-guide.md 里的表，下游全部从那里继承语义角色名，写 accent，不是写 #eb6c36。这点是它设计上的关键：所有下游引用颜色都用语义角色名，改品牌只改一处。

四、出图与自检

出图直接用自然语言，官方给的示例可以直接抄：

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.

也可以直接从模板起步，有三种可选：

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 # 可选的无障碍动效

仓库自带一个可翻看全部 39 种图的图库：本地开 skills/diagram-design/assets/index.html，或在线上看 cathrynlavery.github.io/diagram-design。

动效是可选的，支持 none、reveal、step、loop 四种模式，默认 none，即默认输出静态且无脚本。动效 HTML 只允许使用仓库里那个固定的、经过审查的控制器；任意或改过的内联脚本、远程资源、CSS @import、可执行属性（如 onclick、srcdoc）都会被拒绝。

画完之后，自检这一步最容易被跳过，但官方把"算跑通"的标准放在这里。运行技能自带的输出检查器：

python3 skills/diagram-design/scripts/self_check.py <你的文件.html>

打印 OK 才算过。官方给了 6 条"算跑通了"的判据，任何一条不成立都算值得提 issue 的 bug：

1. 一个常规请求（比如"给我画个流程图"）只加载 SKILL.md 加恰好一个类型参考文件，不加载别的；
2. 画之前，agent 会先说明它选的类型、模式、尺寸和打算做的删减，然后才渲染；
3. 产物是一个 .html 文件，双击就能离线打开，除了 Google Fonts 之外没有任何网络请求；
4. 屏幕阅读器能朗读出图的标题与描述；prefers-reduced-motion 下显示完整静态帧；
5. self_check.py 在上面那个文件上打印 OK；
6. 品牌 onboarding 之后，新图用的是你站点的 paper、ink、accent 和字体，并且有一份 fidelity receipt 逐项指名。

五、导出与导入

出好的图可以导出给 Figma、幻灯片或社交卡。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

Pi 里把命令前缀换成 /export-diagram，参数相同。SVG 的做法是抽出 <svg> 节点并注入 Google Fonts，使其能在浏览器、Figma、Illustrator 里独立渲染；PNG 是用 Playwright 栅格化，默认 2 倍。

这里有一个重要的边界：两种格式都只含图本身，-full 变体里的编辑级卡片和页眉不包含在内。要整页编辑级版式的截图，得用浏览器的打印成 PDF 或整页截图。--registry 只对使用"可溯源块分解"模式画出来的图有效，会额外产出 <basename>.registry.json，把每个块的 data-block-* 元数据结构化导出。动效 HTML 要导出时，必须导出明确的最终静态帧：开 ?motion=static，等 document.fonts.ready，确认动效根节点带 data-frame="static" 再截。

如果你已有存量资产，这套技能支持把 draw.io、Mermaid、Excalidraw 的源文件重绘成这套设计系统，保留内容，换掉样式。命令示例：

/diagram-design:import-drawio platform.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-mermaid architecture.mmd --size=slide-16x9 --detail=simplified
/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9 --detail=simplified

支持的输入格式：draw.io 支持 .drawio、.drawio.xml、.drawio.png（内嵌图）、.drawio.svg，包括看起来像 base64 乱码的压缩 payload；Mermaid 支持 .mmd、.mermaid 以及 Markdown 里的一个或多个 mermaid 代码块；Excalidraw 支持 .excalidraw 与 .excalidraw.json 场景文件，不支持 .excalidraw.png 与 .excalidraw.svg 导出件。Excalidraw 路径只解析文本：不渲染、不执行 JavaScript、不开浏览器、不联网、不跟随点击目标。

导入有四个旋钮。Format（html、svg、png、html+png）；Size（doc-inline、doc-wide、slide-16x9、slide-4x3、social-og、social-square、print-a4-landscape、print-letter-landscape、fit）；Detail（faithful 最多 24 节点且有分区、balanced 最多 12、simplified 最多 7，按固定降级阶梯删减：先装饰、再重复、再叶簇、最后基础设施）；Audience（engineer、mixed、executive，改的是措辞不是数量）。

每次 import 结束都会给一份 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 的手绘几何。明确会继承：组件、关系、分组、方向。

六、多客户品牌隔离

做外包或多站点的人会用到多品牌隔离。做法是：一个品牌 onboard 一次，存成命名 profile，然后在每个客户项目里放一个 .diagram-design 标记文件，内容写 profile: <slug>。

标记项目会直接读 ~/.diagram-design/profiles/<slug>.md，因此并行工作区可以用不同品牌，而不互相覆盖已安装的共享 style-guide.md。profile 库在 Claude Code、Codex、Factory Droid、Pi 之间共享。Claude Code 里用 /diagram-design:profile，Factory Droid 或 Pi 里用 /profile，其他宿主用自然语言即可。

注意 references/style-guide.md 的改动可能被包更新覆盖；已保存的 profile（~/.diagram-design/profiles/）不受更新影响，带 .diagram-design 标记文件的项目也不受影响。想稳定改样式，用可编辑安装（下一节）或 profile 加标记来隔离。

项目的 docs/cookbook.md 里给了可编辑安装、首图、品牌设置、导入、导出、校验以及 Windows junction 的操作配方，需要更细的本地化玩法可以直接翻。可编辑安装本身也很简单：

git clone [email protected]:cathrynlavery/diagram-design.git ~/code/diagram-design

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

# Claude Code：软链内部技能目录
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

其他 Agent Skills 宿主按需创建目录再软链即可，注意托管式安装很方便，但 references/style-guide.md 的改动可能被包更新覆盖。

七、踩坑速查表

这一节是全文的核心价值。下面 10 条逐条写清现象与原因，谁照着排查都能省下几小时。

结尾判断：什么样团队值得花这一小时接进来？如果你的图要进对外品牌物料、要给客户看、要可访问性达标、要反复导出 Figma 或幻灯片，那么 diagram-design 的品牌化与自检流水线值回票价。如果你的图只是内部随手画架构、README 里贴一下、协作者都用 Mermaid 协作，那继续用 Mermaid 更划算，它零依赖、纯文本、diff 友好。这个决策的关键不在"哪个更强"，而在"你的图要不要带品牌、要不要被机器校验"。关于它的来龙去脉，可以看 diagram-design 项目介绍。

常见问题

Q1：装在 Claude Code 还是 Codex 上，我该怎么选？ A1：看你的主力宿主。Claude Code 用户多、文档最全，但第三方 marketplace 默认关自动更新，装完必须手动开。Codex 启动时自动刷新已配置的 Git marketplace，更新更省心，用 codex plugin marketplace upgrade diagram-design 即可立刻拉取。两个都能接，差别主要在更新路径。

Q2：我已有大量 Mermaid 资产，能接进来吗？ A2：能。用 /diagram-design:import-mermaid 把 .mmd、.mermaid 或 Markdown 里的 mermaid 代码块重绘成这套设计系统，支持 --size、--detail、--audience 等旋钮，并会产出一份 fidelity ledger 说明哪些节点被合并或丢弃。注意它不继承源配色与自动布局，只继承组件、关系、分组、方向。

Q3：这套技能能在 Windows 上用吗？ A3：能。Claude Code、Codex、Factory Droid、Pi 等宿主在 Windows 上均可运行，常规使用无额外依赖。PNG 导出需要 pip install playwright && playwright install chromium 这一步。项目的 cookbook 还专门给了 Windows junction 的操作配方，用于可编辑安装时的目录链接。

Q4：导出 PNG 时为什么报缺依赖？ A4：因为导出 PNG 需要 Playwright 加 Chromium，这不是常规依赖，只有导出 PNG 时才用。第一次导出 PNG 前先跑 pip install playwright && playwright install chromium 即可。导出 SVG 不需要这个依赖，可临时绕开。

Q5：首图就要用它，会不会被默认皮肤带偏？ A5：不会。在新项目里首次出图时，技能会暂停并询问你：跑 onboarding、手动粘贴 token，还是就用默认。它不会闷头用默认皮肤直接渲染。只要你选 onboarding 并指向你的站点，新图就会用你站点的 paper、ink、accent 和字体，并附一份 fidelity receipt 逐项指名。

参考来源

• https://github.com/cathrynlavery/diagram-design
• https://cathrynlavery.github.io/diagram-design
• https://github.com/cathrynlavery/diagram-design/tree/main/docs