设计品味能写进Skill文件，但检查才是难题

让编程智能体画架构图，你基本能预判结果：圆角方块、柔和阴影、五种毫无意义的柔和填充色，外加一条斜穿中线的箭头。模型知道系统长什么样，却对「好图长什么样」毫无概念。

GitHub 上的 diagram-design 项目试图填补这道鸿沟。作者 Cathryn Lavery 把它做成一个 agent skill，周日登上 GitHub Trending 第 4 名，单日 1083 星，累计 50933 星，MIT 协议。它能绘制 44 种图表类型，输出单个内联 SVG 的 HTML 文件，支持重绘 Mermaid、draw.io 和 Excalidraw 源文件，还带有从你自己网站提取配色和字体的引导步骤。

有开发者没有直接安装（安装 skill 会写入 agent 配置），而是克隆到临时目录，读规则、看输出、跑脚本。真正有意思的地方，是规则与脚本之间的落差。

它主要是一份散文式风格指南

skill 文件夹的内容分配很说明问题：

• SKILL.md：30.5 KB。CI 把它卡在 40000 字节以内，因为每次调用都会加载（理由见仓库 ADR 0004）。
• references/：62 个 Markdown 文件，合计约 710 KB。每种图表类型一份，外加风格指南、导入流程，以及节点、箭头、标签的精确 SVG 标记。
• assets/：204 个示例图和模板。
• scripts/：五个小型 Python 文件，仅用标准库。

所以这是一个附带几个工具的编辑风格指南。规则读起来像编辑手记：超过九个节点就拆分；强调色只用在一两个元素上；禁止阴影；所有连接线都是直角折线，不用斜线；结构几何对齐 4px 网格；不要照搬 Mermaid 的自动布局。定调的是哲学部分的第一句话——「最高质量的操作通常是删除」。

README 的起源故事很简短：Claude 总是内容对、视觉错，于是作者把自己的设计偏好变成了规则。有用户提交 issue #242，说自己只复制了规则、没复制代码到自己的图表 skill 里。Lavery 回复：「用规则而非代码，正是它们该有的传播方式。」

agent skill 是 2024 年底随 Anthropic Claude Agent SDK 等框架流行起来的一种约定：把一段可复用的能力打包成一个包含 SKILL.md 主文档、references/ 参考资料和 scripts/ 辅助脚本的文件夹，agent 在需要时按需加载。它与「工具函数」或「插件」的关键区别在于，skill 的主体通常是一大段自然语言指令，而非可执行代码——模型读取后靠理解来行动，因此同一 skill 在不同模型、不同上下文下的行为会有波动。SKILL.md 被刻意限制体积，是因为它每次调用都会被完整载入上下文窗口，太大就会挤占推理预算。

输出是有意为之的「无聊」HTML

打开仓库自带的流程图示例，标题是「Should you write this as a skill？」，大小 9395 字节，没有 script 标签，只有一个外部请求（Google Fonts 样式表）。SVG 带有 role="img" 和真实的 <title>、<desc>，屏幕阅读器能读到一句话而不是空白。

用一个短 Node 脚本扫描全部 204 个示例后发现：唯一的外部主机是 fonts.googleapis.com；十个文件含 script，全是动画变体；文件大小中位数 12.6 KB，最大的是一个 208 KB 的动画爆炸键盘图。内置的 export_svg.py 能把它转成 8703 字节的独立 SVG，id 加了前缀，便于与其他图表共处一页。

内联 SVG 指把 <svg> 元素直接嵌在 HTML 文档里，而不是用 <img src> 引用外部文件。这样做的优点是：SVG 可以继承和复用页面 CSS、可被屏幕阅读器直接朗读、不需要额外网络请求，同时整个页面能作为一个文件分享。代价是文件体积随图形复杂度线性增长，且无法被浏览器单独缓存。配合 role="img" 加 <title>、<desc> 的写法，是 WAI-ARIA 为纯装饰图形和有意义图形做区分时的标准可访问性做法。

导入端的实测与边界

导入脚本只解析文本，从不渲染或抓取。用 python3 -I 从克隆目录外跑 Mermaid 脚本处理仓库自带样例，输出摘要包含节点数、边数、预算检查和「焦点候选」。

这份摘要就是模型重绘时的输入。它已经应用了规则：检查预算、提名强调色的焦点候选、标记出无人连接的孤立节点。仓库的对抗性样例把 IGNORE ALL PREVIOUS INSTRUCTIONS 藏在节点标签里，提取器将其保留为转义文本，并丢弃了四条样式指令和点击处理器。

边界也很快暴露。三行 Mermaid 饼图直接以退出码 2 失败——导入器只读流程图、序列图、状态图和 ER 图。其源码列出的拒绝类型还包括甘特图、时间线、旅程图、桑基图和象限图，尽管 skill 本身能从零绘制这五种。

提示词注入（prompt injection） 在这里指的是把 IGNORE ALL PREVIOUS INSTRUCTIONS 之类的指令伪装成数据混入模型输入，诱使它放弃原有规则。图表导入天然是注入面：Mermaid、draw.io 的节点标签是用户可写的自由文本，模型很可能把它们当成新的指令。这类对抗性样例的防御思路与「文字转换」任务一致——把外来内容当作纯数据转义、剥离任何可执行语义（如点击处理器、样式指令），并且不要在解析阶段就让模型接触原文。要注意，导入器只解析文本而不渲染，本身就是收缩攻击面的设计选择。

亲手「弄脏」输出的测试

skill 自带一个检查器 self_check.py，要求 agent 对自己的输出运行。测试者复制流程图示例，故意破坏三条头部规则：七个节点全上强调色、六个加投影、一条斜向箭头。

结果：自带的检查器直接放行。仓库的几何验证器抓到了斜线，但它位于 npx skills add 安装的 skill 文件夹之外，SKILL.md 只在仓库检出时指向它。调色板 lint 也没说话，因为所有颜色都在调色板上。没有任何脚本检查阴影。几个图表验证器（热力图、瀑布图、气泡图等）确实把强调色限制在一个标记上，说明规则可检查，但通用流程图没有对应检查，而且那些验证器也在 skill 文件夹之外。

公平地说，self_check.py 做到了它文档字符串承诺的事。加一张远程图片并删掉 <title> 后，它报出五个问题。它是一个安全与无障碍门禁，不是品味门禁。

连示例本身都会漂移。issue #276 中，有用户发现同一个流程图示例违反了自己的类型参考：椭圆半径是 24 而非 20，YES 标签压在连接线上而非放在旁边。几何验证器当时放行了它。现在已修复，但作者的参考文件都会漂移，模型的新输出更不用说。

两类规则：可脚本检查 vs 只能靠判断

这是最值得带走的部分，哪怕你从不画图。

有些规则脚本能检查：调色板、字体、无外部资源、无障碍名称、无斜向连接线、网格对齐。另一些只能靠判断：删掉哪个节点、哪一两个元素配得上强调色、一段文字是否比一张图更好。第二类规则决定了这个 skill 的输出为什么好看，也正是没有任何东西能验证的那类。

README 对此很坦诚：输出质量取决于模型，同一提示词两次可能排版不同。Skill 是指令，它提升下限的程度，完全取决于模型读了多少、跟了多少。

所以如果你在为团队写 skill（幻灯片风格、邮件语气、图表规则），把每条规则分进这两堆。脚本能检查的每条规则都应该变成脚本，而且应该随 skill 一起发布，让 agent 能运行它。测试者自己用 27 行 Node 写的检查脚本就能数出强调笔画和阴影滤镜——单是阴影计数就足以让那个「脏」文件失败。

lint（静态检查） 原是代码领域的术语，指不运行程序就扫描源文本、按规则集报告问题的工具。迁移到设计资产上时，lint 只能识别「形式化、可枚举」的约束：颜色是否在调色板内、是否存在 <filter> 阴影、连接线端点坐标差是否为零。它无法判断「这张图是否需要少画两个节点」或「这个强调色用在这里是否合适」——那属于设计判断，需要人或其他模型评估。这也是为什么测试者自己写的 27 行 Node 脚本比官方 self_check.py 更有效：他针对自己想守住的规则现造了 lint，而官方检查器只覆盖安全与可访问性。

没测到的部分与已知边界

有一个诚实的空白：测试者从未真正让模型用它画图。可以告诉你规则写了什么、检查器抓了什么，但无法告诉你 agent 到底多久遵守一次。

从 issue 和文档里还能看到一些边缘情况：

• 首次运行会暂停。 默认风格指南下，skill 会停下来询问你的品牌信息。issue #262 描述了一次无人值守运行，任务中途弹出这个问题却没人回答。
• 字体默认来自 Google。 检查器的 --offline 标志会拒绝任何加载它们的文件，风格指南提供系统字体选项。
• PNG 导出需要 Playwright 和 Chromium。 SVG 导出是纯 Python。

想先看再装，可以访问在线画廊，那里展示了每种类型的浅色、深色和编辑风格变体。

真正的问题留给你：你团队品味规则里，哪些今天就能变成检查脚本，哪些注定只能活在散文里？