让 coding agent 画图，现在已经很方便：描述系统，要求输出 Mermaid、PlantUML 或 SVG，再让它修改几轮，就能得到一张图。
那么，cathrynlavery 的开源项目 diagram-design，究竟多提供了什么？如果只是让 Agent 输出 SVG，再加一句“画得好看一点”，值得专门装一个 skill 吗？
我的判断是：它的价值主要在于把选图、排版、风格和检查整理成可复用流程。对已经拥有这些规则的人，新增价值会小很多。
本文根据项目文档与实现结构分析，没有进行同模型、同提示词的生成效果评测。文中的示意图用于解释取舍，不代表不同工具的实测输出。
先分清：这几个选项处在不同层次
Mermaid 和 PlantUML 都可以通过文本描述图中的关系。Agent 写下参与者、消息、节点与连线，再由渲染器安排图形。它们分别有自己的语法、图种与生态，不能简单视为完全相同的工具。
SVG 则是矢量图形格式。它能描述坐标、路径、形状与文字，却不会仅凭几个矩形和箭头，就知道你要表达的是“调用”“继承”还是“失败重试”。这些含义需要生成者表达并核对。
diagram-design 是给 Agent 使用的 skill。它提供设计规范、类型参考、模板和辅助脚本，主要生成包含内联 SVG 的 HTML，也提供 SVG、PNG 导出流程。
因此，“diagram-design 比 SVG 强在哪里”这个问题，需要换成：同样生成 SVG，增加这套工作流程后，Agent 会少遗漏哪些设计任务？
看下面的分叉：左侧把关系描述交给渲染器，右侧由 Agent 依据规则安排图形。两条路径都能接受自然语言需求，差别主要发生在后续的布局与检查。
两条路径都由 Agent 接收需求，区别在于谁负责布局，以及检查哪些问题。
项目 README 把“写文本”和“向 Agent 描述”放在对照表两侧，但对已经使用 coding agent 的人，这个区分并不充分。让 Agent 写 Mermaid，同样不需要自己手写全部语法。
它补上的，是几类容易被省略的工作
先决定这张图要解释什么
一句“画架构图”，没有说明读者应该看到什么：部署边界？请求路径？故障如何扩散？还是改造前后发生了什么变化？
这些问题需要不同的表现方式。把每个组件都画成方框，再把已知关系全部连上，可能只得到一张需要作者现场讲解的接线图。
diagram-design 把选图纳入流程，提供多类布局参考，并要求考虑内容的行为含义。对复杂输入，它也要求控制信息量、必要时拆成概览与细节。
这类约束能提醒 Agent 先做信息取舍。收益来自选择是否合适；图种更多本身并不能证明图更清楚。
把“好看一点”拆成具体约束
直接要求 Agent 写 SVG，它必须同时决定字号、配色、间距、转折点和视觉重点。若提示词没有约束，这些决定容易随生成结果变化。
该项目把这些选择集中到设计规范与模板中。例如，样式使用具有明确用途的颜色角色；连接线有路由规则；强调色用于少数焦点；不同图形类型有各自的排版参考。
这让“整套文章的配图风格一致”更容易成为可重复的要求。团队也可以复用品牌配置，减少每次重新说明颜色和字体的工作。
但这套风格带有作者偏好。无阴影、克制的强调色、特定字体组合，并非任何场景都更优。Mermaid 支持主题配置，PlantUML 也支持样式设置；不能把它们的默认外观当作能力上限。
把交付检查变成流程的一部分
“SVG 可以打开”只说明文件能渲染，不说明文字没被裁掉、连线没遮住标签，更不说明系统关系正确。
项目既有检查清单，也有脚本。安装包内的 self_check.py 检查可访问性标记、单文件约束及部分边界问题等；仓库中还有几何与浏览器渲染检查工具。
这里要区分三件事：提供了检查工具、Agent 实际运行了检查、检查覆盖了当前问题。三者不能画等号。仓库 CI 检查示例，也不意味着每张新生成的图都自动经过同样检查。
这些检查有助于发现格式和布局问题。至于“超时后是否可以重试”“箭头是不是指反了”，仍然需要对照业务事实。
用一次缓存读取，看清差别
假设我要解释一个简单的 cache-aside（旁路缓存）读取过程：应用先查缓存；命中就返回；未命中时，由应用读取数据库、把结果写回缓存，再返回数据。为突出读取分支，这个例子暂不讨论并发更新与一致性。
直接让 Agent 生成 Mermaid，完全可以表达正确的节点、分支和调用关系。PlantUML 的时序图也适合呈现这些调用先后。
如果目标是一篇讲解“命中为什么省掉数据库读取”的文章，我会进一步提出几个要求：让命中路径首先进入视线；把未命中后的数据库读取放到侧面；保留回填方向；在线边就近写条件。
下面的示意图把蓝色命中路径放在左侧。顺着右侧的“未命中”箭头，才能进入读库步骤；底部回路表示应用把结果写回缓存。图中展示数据路径，省略了完整调用时序；数据库不会自行回填缓存。这些布局选择服务于同一个解释目标。
蓝色命中路径直接返回，右侧未命中路径访问数据库，并把结果回填缓存。
diagram-design 的潜在收益，在于更稳定地提醒 Agent 做这些决定。它没有让 Mermaid 无法表达的缓存关系突然变得可表达。上图也不是调用该 skill 的效果样本，不能据此声称它胜过另外两种工具。
想检验实际收益，可以固定模型、业务输入和输出尺寸，分别比较“直接生成”“直接生成并附完整设计规范”“使用 skill”三组。检查事实错误、阅读顺序、窄屏可读性和修改成本，并记录生成及修订开销。只挑一张漂亮样例，回答不了这个问题。
与三条直接画图路径分别比较
对比 Agent + Mermaid：如果图主要放在支持 Mermaid 的 Markdown 文档中，内容经常修改，紧凑的关系描述很有价值。渲染器负责布局，开发者能直接审查文本变化。需要精确安排重点、留白和注释位置时，定制 SVG 的自由度更大，但也承担更多布局维护。
对比 Agent + PlantUML：对于协议交互、分支循环、类关系等技术文档，PlantUML 提供相应语法和图形约定。diagram-design 的展示自由度有价值，却不能替代对这些语义的核对。若目标是维护一份经常变化的协议说明，我会优先保留可审查的文本模型。
对比 Agent + 原生 SVG：两者在图形表达能力上没有天然鸿沟。你完全可以给 Agent 提供同等水平的设计规则、模板、渲染检查和导出脚本。此时，diagram-design 的主要优势是复用已有整理成果，减少自己建立与维护流程的工作。
对已经在项目里约定“保留可编辑 SVG、导出 PNG、检查手机字号和箭头”的使用者，它补充的可能是类型参考、品牌配置与导入工具，而非一套此前完全缺失的能力。
便利背后的几项成本
首先，检查图形代码的变化，比检查关系描述更费力。修改一条 Mermaid 消息，通常能直接看到语义变化；修改 SVG 可能同时改变坐标、路径和文字。SVG 当然也是文本，也能进入 Git，但文本可 diff 不等于语义容易 review。
其次，重新生成的布局不保证一致。模型、上下文与修改指令都可能影响结果。若一张图每周都要加服务、改调用链，需要同时考虑局部修改是否稳定，而不只看第一次交付。
再者，单文件不必然等于完全离线。项目的字体方案可以涉及 Google Fonts，也提供系统字体路径。对离线阅读或中文标签，应明确字体要求，检查实际渲染，避免把 fallback 当成预期字体。
还有一个容易忽视的边界：浏览器里可读，不等于公众号里可读。项目输出规范使用局部横向滚动来保留 SVG 的显示尺寸。导出 PNG 嵌入文章后，图片通常会整体缩到屏幕宽度，原有滚动方式不会随图片保留。
例如，宽 1200px 的图片中，24px 的文字缩到 360px 显示时只有 7.2px。提高导出分辨率能改善清晰度，却不能改变显示字号。公众号配图仍然需要减少内容、放大文字，并在实际显示宽度下预览。
已有 Mermaid，可以保留模型再制作展示版本
项目提供 Mermaid 导入流程，这是两条路线能够结合的地方。
它先提取结构信息，再让 Agent 重新布局。已说明支持的语法包括 flowchart/graph、sequenceDiagram、stateDiagram-v2 和 erDiagram，不能理解为覆盖所有 Mermaid 图种。
重新布局会舍弃原主题与样式，也可能根据目标读者和细节级别合并内容。流程要求报告合并、折叠或删除情况。因此，这更适合制作展示版本，不能直接当作可无损往返的格式转换。
我的建议是保留两个角色：文本模型作为关系事实的维护入口，SVG/PNG 作为某次文章或演示的展示产物。模型更新后，重新检查展示版本，并记录源文件版本。不要让两份内容各自修改，却没有同步规则。
什么情况下值得用
如果只是给 README 补一张小流程图，我会先让 Agent 写 Mermaid。若团队已经围绕 PlantUML 维护技术模型，也没有必要为了外观统一迁走全部图。
如果要持续制作技术文章、方案讲解或品牌统一的演示配图，diagram-design 值得试用。它把多项设计工作放进同一套流程，尤其适合尚未建立制图规范的人。
对于已经熟练让 Agent 生成 SVG 的人，可以先拿一张真实需求验证：它是否减少了排版返工？改一个节点是否影响全图？导出后中文和手机字号是否仍然合适？检查脚本究竟执行了哪些？
无论是否采用这个项目，都可以把下面这段要求交给 Agent：
先说明这张图要让读者理解什么，再选择图形类型。保留关键分支、方向和边界；合并或删除内容时列出清单。输出可编辑源文件及 PNG，实际渲染并检查文字、连线和裁切。文章配图按 320px、360px 显示宽度验收，并说明运行过哪些检查。
对我而言，是否安装这个 skill，最终取决于一件具体的事：它能否把我尚未稳定执行的设计与检查工作，变成每次都会完成的步骤。