一、这套 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 导入，可以跳过这步。
安装时按你用的宿主选一条，命令逐字照抄。下面这张表是全文最实用的部分，建议收藏。
| 宿主 | 安装命令（逐字照抄） | 更新命令 | 更新是否自动 |
|---|---|---|---|
| Claude Code | /plugin marketplace add cathrynlavery/diagram-design 然后 /plugin install diagram-design@diagram-design | 手动到 /plugin 的 Marketplaces 开 Enable auto-update；提示时 /reload-plugins | 默认关闭，需手动开 |
| Codex | codex plugin marketplace add cathrynlavery/diagram-design 然后 codex plugin add diagram-design@diagram-design | codex plugin marketplace upgrade diagram-design，开新会话 | 启动时刷新，可手动拉 |
| GitHub Copilot | copilot plugin marketplace add cathrynlavery/diagram-design 然后 copilot plugin install diagram-design@diagram-design | copilot plugin marketplace update diagram-design 再 copilot plugin update 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 | droid plugin marketplace update diagram-design 再 droid plugin update diagram-design@diagram-design --scope user，开新会话 | 按 commit 跟踪，手动 |
| Pi | pi install https://github.com/cathrynlavery/diagram-design，当前会话 /reload | pi update --extensions | 完全无自动刷新 |
| Kiro | 以子目录 URL 导入：https://github.com/cathrynlavery/diagram-design/tree/main/skills/diagram-design | 重新导入一次该 URL | 复制式，手动重导 |
| OpenCode | 复制或软链 skills/diagram-design/ 到 .opencode/skills/diagram-design 或 ~/.config/opencode/skills/diagram-design | 手动替换目录 | 无 marketplace，手动 |
确认 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：
- 一个常规请求（比如"给我画个流程图"）只加载
SKILL.md加恰好一个类型参考文件，不加载别的； - 画之前，agent 会先说明它选的类型、模式、尺寸和打算做的删减，然后才渲染；
- 产物是一个
.html文件，双击就能离线打开，除了 Google Fonts 之外没有任何网络请求； - 屏幕阅读器能朗读出图的标题与描述；
prefers-reduced-motion下显示完整静态帧； self_check.py在上面那个文件上打印OK；- 品牌 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 --registryPi 里把命令前缀换成 /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 条逐条写清现象与原因，谁照着排查都能省下几小时。
| 序号 | 踩坑 | 现象与原因 | 解法 |
|---|---|---|---|
| 1 | Claude Code 第三方 marketplace 默认关自动更新 | 装完不手动去 /plugin 的 Marketplaces 里开 Enable auto-update，版本会一直停在旧版 | 装完立刻去开 Enable auto-update，提示时 /reload-plugins |
| 2 | Factory Droid 按 commit 跟踪，不认 manifest 显示版本 | 光看版本号没用，必须 marketplace update 再加 plugin update 并开新会话 | droid plugin marketplace update diagram-design 再 droid plugin update diagram-design@diagram-design --scope user，开新会话 |
| 3 | Pi 完全没有自动刷新机制 | 装完不动就永远旧版 | 手动 pi update --extensions |
| 4 | Kiro 是复制不是链接 | 导入后文件被拷进 .kiro/skills/，想拿新版得重新导入 URL | 重新导入该子目录 URL；自定义 agent 声明资源应包含 skill://diagram-design/**/SKILL.md |
| 5 | OpenCode 复制式安装不会自动更新 | 没有 marketplace 包，只有自己替换目录时才更新 | 手动复制或软链新目录到 .opencode/skills/diagram-design |
| 6 | 旧版 npx skills add 装的独立副本不跟随 Codex marketplace | 两路并存，版本错乱 | 先删掉独立副本，再用 Codex marketplace 两条命令重装 |
| 7 | 自定义 style-guide.md 会被包更新覆盖 | 托管式安装一更新就还原 | 用可编辑安装（clone 后装本地路径），或 profile 加 .diagram-design 标记隔离 |
| 8 | PNG 导出第一次会失败 | 缺 Playwright 与 Chromium | 先跑 pip install playwright && playwright install chromium；SVG 不需要 |
| 9 | 以为导出包含全版式 | SVG 和 PNG 都只导出图本身，编辑级卡片与页眉不含在内 | 要整页用浏览器打印成 PDF 或整页截图 |
| 10 | 动效 HTML 直接截图截到中间帧 | 截的时候动画正播 | 开 ?motion=static，等 document.fonts.ready，确认 data-frame="static" 再截 |
结尾判断：什么样团队值得花这一小时接进来？如果你的图要进对外品牌物料、要给客户看、要可访问性达标、要反复导出 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 逐项指名。