一个绘图 Skill 的进化史：diagram-builder 从草稿到生产可用

最近我折腾了一个专门画图的 skill——diagram-builder。起因很简单：日常工作中频频需要向团队展示架构、流程、状态机这些东西，每次都手工写 SVG 或者打开 draw.io 拖拽，效率太低，而手头能快速搜到的skill效果都不够好。正好 WorkBuddy 提供了 skill 机制，可以把它写成可复用的能力模块，以后说一句"画个微服务架构图"就能出图。

关于 skill ，你可以理解为一个封装了特定能力的 Prompt + 参考文档 + 脚本的组合包，这样AI工具 加载skill后就知道怎么处理某一类任务。关于skill的介绍本篇不再赘述，我想聊的是：从动手建这个 skill，到它真正能稳定出图，中间踩了多少坑，又是怎么一步步进行问题分析和修正的。

一、建设思路

动手之前先想清楚几件事：

1. 输出形式是用 WorkBuddy 内置的 show_widget 渲染内联 SVG，还是输出 Mermaid 代码让用户自己渲染？答案是两者都要。内联 SVG 精美可控，适合对话中即刻查看；Mermaid 语法简单，方便嵌入飞书文档、GitHub README。
2. 图表类型覆盖系统架构图、微服务拓扑、业务流程图（含泳道）、时序图、状态机、ER 图、数据流图、网络拓扑图——这 8 种是最常用的，都应该有 SVG 模板。
3. 规范先行没有规范的 skill 就是靠运气出图。箭头大小、颜色体系、分层框样式、间距约束，这些必须写成文档而不是每次靠 AI"看着办"。
4. 校验闭环人工检查一定会有遗漏。所以必须有一个自动化脚本，每次出图后跑一遍，把箭头裁切、颜色越界、viewBox 不够这些问题揪出来。

想清楚这些之后，我们开始动手建目录结构。

二、结构分析

最终落地后的目录长这样：

diagram-builder/ ├── SKILL.md← 主入口，skill 加载时最先读取 ├── references/ │ ├── diagram-types.md← 8种图表的 SVG 骨架模板 │ ├── svg-marker-guide.md← 箭头 marker 完整规范 │ ├── architecture-layout-guide.md← 分层架构图坐标计算 │ ├── color-tokens.md← 统一色彩体系 │ ├── svg-components.md← CSS 类 + defs 组件库 │ └── mermaid-cheatsheet.md← Mermaid 语法速查 └── scripts/ └── validate-svg.py ← 自动校验脚本

参考skill的最佳实践，几个关键设计决策如下：

• SKILL.md 只放流程和原则skill.md不会放具体的模板，模板统一放 references/ 下，并按照主题拆分，单一文件不超过 200 行，这样既好找又好修改。
• 颜色抽成独立文件 color-tokens.md而不是散落在各模板里。后面做颜色统一修复时这个决策帮了大忙——只改一个文件，所有模板就能自动对齐。
• 校验脚本独立于 skill 内容不依赖于任何外部库，一个 Python 文件搞定，随时可以跑。

这个结构的核心思路是：SKILL.md 是宪法，references/ 是法典，scripts/ 是警察——三层分工明确，各司其职。

skill.md的核心描述：

三、优化过程：从"能画"到"画对"

第一版 skill 建好后我立刻试了一手：画一个微服务架构图。结果出来了，怎么说呢？能看，但问题也很多。后面的几轮优化基本就是"发现问题→定位根因→修复→沉淀到 skill 里"的循环。以下，我将会按时间线进行复盘。

3.1 第一轮：能用就行

第一张微服务架构图出来的时候，直观感觉是"还行"。但仔细一看：

• 通知服务模块和右下角的"同步 RPC"图例重叠了，信息被挡住
• 四个业务层的服务没有分组框，看不出它们属于同一层
• 向下的箭头只能看到半边——箭尖被裁了

当时的态度是"坐标算错了，调一下就行"。于是手工把通知服务的 y 坐标往下挪了 30px，把图例挪到左下角，箭头间距拉大了一点。修完觉得差不多了，就没往 skill 里沉淀——这是个错误，后面果然又踩了一次。

3.2 第二轮：箭头方向这个坑

当我要求"把处于同一层的块用虚线圆角框包起来"时，重新画了一张。分层框加上了，但箭头方向全乱了：我想要的是向下箭头，画出来的却是向左的箭头。

我盯着 SVG 源码看了好一会儿才搞明白问题出在哪。先看原来的 marker 定义：

<marker id="arrow" viewBox="0 0 10 10" refX="5" refY="5"
        markerWidth="6" markerHeight="6" orient="auto">
  <path d="M1 2L5 8L9 2" .../>
</marker>

这里的 path M1 2L5 8L9 2 画出来的三角形尖端指向 y=8——也就是朝下。问题在于 orient="auto" 的工作方式：它把 marker 的 x 轴 旋转到线的方向上。对于竖线，x 轴旋转后变成竖线方向，原本朝下的路径就变成了朝左。

正确的做法是：路径尖端必须指向 +x 方向（右侧），剩下的交给 orient="auto" 自动旋转。修正后的marker如下：

<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5"
        markerWidth="10" markerHeight="10" orient="auto">
  <path d="M1 2L8 5L1 8" .../>
</marker>

同时，我还注意到另一个问题：markerWidth="6" 比 viewBox 宽高 10 要小，这意味着 marker 的视口被压缩了，路径超出视口的部分被裁切——这就是第一轮遇到的"箭头只显示半边"的根因。于是修改成 markerWidth="10" markerHeight="10"，再进行绘图验证，箭头终于完整了。

这个坑踩完之后我意识到，SVG marker 不是一个"随便写写就对了"的东西，它有自己的坐标系旋转逻辑和视口裁切规则。我把这些总结成了 svg-marker-guide.md，以后每次画图都强制引用。

3.3 第三轮：分层架构图的结构化

箭头修好后，分层框的问题还在。每次画分层架构图，层与层之间的间距、分组框的位置、图例的位置，全靠"感觉"——感觉准的时候还好，不准的时候就会发生重叠。

那么解决思路也就明确了：我需要把它变成可计算的，只有这样才能严谨，保证位置准确。

于是我定义了严格的坐标公式，写进 architecture-layout-guide.md：

层 N 框顶 = (N-1) × (层框高度 + 层间箭头区) + 起始 y
层间箭头 zone = 40px（上层框底 + 8 + 箭头 24 + 下层框顶 - 8）
viewBox 高度 = 最下层框底 + 图例高度 + 16px 余量（向上取整）

举个例子，5 层架构图的标准坐标：

有了这套公式后，viewBox 高度直接是 910（864 + 16 + 30，取整）。每次画分层图，坐标都是算出来的，而不再是简单地拍脑袋。后来实际验证：4 层电商架构图用这套公式画出来，自动校验 0 错误 0 警告，一稿过。

3.4 第四轮：颜色体系统一

做完前面几轮后，我停下来做了一次全面自检，列出了 10 个问题，按严重程度分 为P0/P1/P2。

P1 级别里最让我难受的是颜色混乱。回顾之前画的几张图：微服务架构图用了浅蓝 + 深蓝 + 灰，skill 系统架构图用了蓝 + 紫 + 绿 + 橙 + 粉，电商架构图用的又是另一套——每张图都是独立选色，没有固定规则，十分随意。

我的解决方案是建一个 color-tokens.md，定义 7 种标准色板，每种色板包含 填充色 + 描边色 + 文字色 三件套：

分层架构图固定按"蓝→紫→绿→橙→粉"顺序配色，不是按"感觉这层该用什么颜色"——这样所有分层图看起来是一套体系。

同时在 svg-components.md 里把这些颜色封装成 CSS 类：

.node-blue  { fill: #E6F1FB; stroke: #378ADD; }
.node-purple { fill: #EEEDFE; stroke: #7F77DD; }
.node-green  { fill: #E1F5EE; stroke: #1D9E75; }
.node-orange { fill: #FAECE7; stroke: #D85A30; }
.node-pink   { fill: #FBEAF0; stroke: #D4537E; }
.node-yellow { fill: #FAEEDA; stroke: #BA7517; }
.node-gray   { fill: #F1EFE8; stroke: #888780; }

画图时直接用 class="node-blue"，不用每次都手写 fill/stroke了。

3.5 第五轮：文本溢出和校验脚本

另一个 P1 问题是文本溢出。节点标签超长时，文字会溢出边框。我定了 4 级处理策略：

1. 动态扩宽节点（首选）：中文超 8 字 → 宽度从 140px 扩到 180~220px
2. 自动换行（次选）：用 <tspan> 分行，同时增加节点高度
3. 截断 + 省略号（最后手段）：保留前 6 个字 + "..."
4. 悬停提示（仅 HTML 交互式图表）：title 属性显示完整文字

但光有规范还不够——每次画完图都要逐项检查 20 多个点，人会累会漏。所以写了 validate-svg.py，一个 270 行的 Python 脚本，自动检查：

• 箭头 marker 的 markerWidth/Height 是否 ≥ viewBox
• 箭头路径方向是否朝右（+x）
• 分层框是否使用了 layer-box 类
• viewBox 高度是否足够容纳所有元素
• 颜色是否来自规范色板
• 中文标签是否超过 8 个字

输出分三级：错误（必须修）、警告（建议修）、建议（可选）。几分钟的时间，画完图顺手跑一下，这样才足够严谨，心里也有底。

四、优化结果

用修复后的 skill 重新画了一张电商微服务 4 层架构图，然后跑校验脚本：

============================================================
SVG 规范性检查报告
文件: 电商微服务架构图.svg
============================================================

✅ 检查通过！未发现规范性问题。

============================================================
总计: 0 个错误, 0 个警告, 0 条建议
============================================================

对比修复前后的关键指标：

当前最新版本绘制效果如下，以OpenAI Codex技术架构图为例：

五、几点反思

回顾skill创建和调试优化的整个过程，总结有以下几个心得：

1. SVG marker 的 orient="auto" 是反直觉的我第一次也写错了，把路径尖端指向下方，心想"向下箭头尖端朝下，很合理啊"——但 orient="auto" 旋转的是 x 轴，不是路径本身，这个坑值得单独写一篇。
2. "先用后修"比"一步到位"更实际第一版能画出来就行，后面看着效果改。如果一上来就追求完美，会卡在"要不要建 color-tokens"、"要不要写校验脚本"这类决策上，反而迟迟出不了第一张图。
3. 规范要写成文件，不能靠记忆箭头规范、颜色令牌、布局坐标公式，这些都是"以为自己记住了但过两天就忘"的东西。写进 SKILL.md 和 references/ 里，每次加载 skill 时自动带进来，不用靠记忆。
4. 自动化校验是兜底线人可以漏，脚本不会漏。270 行 Python 换来的确定性，比"我觉得应该没问题"靠谱得多。
5. 文档即 skill 的质量基石diagram-builder 最终完整的文件清单——1 个 SKILL.md、6 个 reference 文件、1 个校验脚本——看起来不多，但每一样都是被实际踩过的坑逼出来的。没有坑就没有文档，没有文档就没有质量。

目前这个 skill 已经发布到腾讯 SkillHub，也已公开到https://gitcode.com/liuhuoxingkong/ai-skills，感兴趣的话可以自行获取。实际画了微服务架构图、Skill 系统架构图、OpenAI Codex 架构图、电商订单状态机等多张图，都校验通过。支持 8 种图表类型（架构图、流程图、泳道图、时序图、状态机、ER 图、数据流图、网络拓扑图），SVG 和 Mermaid 两种输出方式。