svg-diagram：用 AI 画一张真正能用的架构图

"Diagrams go in SVG, never ASCII art." — SKILL.md 开篇第一句

---

一、痛点：从「AI 画图」到「AI 画对图」

你让 Claude Code 画一张微服务架构图，它吐出了一张 SVG——看起来还不错，但仔细一看：文字超出了方框、箭头弯成了奇怪的直角、箭头指向了错误的方向、CJK 字符变成了方块（tofu）。你让它修复，它修了这边坏了那边，改了三轮依然一塌糊涂。

这不是 AI 不努力，是 AI 根本不知道你期望什么样的图。

svg-diagram 解决的就是这个问题：它不是给 AI 一个模糊的指令「画个架构图」，而是把「什么叫一张合规的 SVG 图」的完整规范编码成一份 SKILL.md，让 AI 在生成每一条线、每一个框、每一个箭头时都有据可查。

这个项目来自 Bybit（加密货币交易所）的工程团队，目前在 GitHub 拥有约 600 颗星，收录于 Vercel 维护的 Agent Skills 生态。

---

二、项目是什么

svg-diagram 是一个 AI 编码 Agent 的技能包（Skill），核心交付物是两份文件：

1. SKILL.md：告诉 AI 如何手写 SVG — 布局公式、颜色系统、字体规范、连接线规则
2. tools/svg-lint/：一个零依赖的 Node.js linter，验证生成的 SVG 是否符合规范

它支持的图类型包括：架构图（Architecture）、流程图（Flowchart）、时序图（Sequence）、数据流图（Data Flow）和生命周期图（Lifecycle），覆盖了技术文档中最常见的需求。

项目用 JavaScript/Node.js 编写，测试覆盖 984 个用例，全部通过 node --test 运行，无需安装依赖（零 node_modules）。

---

三、核心机制：把「画图规范」变成 AI 可执行的指令

svg-diagram 的设计哲学是「placed, not auto-laid-out」——每个元素的坐标都是经过计算放置的，而不是交给布局引擎自动生成。这与 Mermaid、PlantUML 等自动布局工具走了完全相反的路。

3.1 布局公式：AI 也能做「数学题」

SKILL.md 把所有关键的尺寸关系编码成公式，AI 在生成时直接代入计算：

• 方框高度 = 字体大小 × 3（单行文字），每多一行加 × 1.5
• 文字基线 = 方框 y 坐标 + 方框高度/2 + 字体大小 × 0.35
• 箭头余量：起点侧留 5px，终端侧留 11px
• viewBox 边距：固定 20-25px

这些数字不是魔法，而是经过实践检验的经验值。AI 直接使用这些公式，每次生成的图都有稳定的质量下限。

3.2 CJK 字体安全：专门解决中文乱码

这是 svg-diagram 区别于其他 SVG 图规范的一个显著特点：它内置了 CJK 字符宽度表，并要求使用完整的字体回退栈：

font-family: 'PingFang SC', 'Microsoft YaHei', 'Noto Sans CJK SC', system-ui, sans-serif

非拉丁文字符的宽度计算也做了单独处理：每个 CJK 字符按一个完整字体大小（12px）计算，而非西文字符的 0.5 倍。这直接解决了 AI 画图时中文字符溢出的顽疾。

3.3 十二项检查的 linter

svg-lint 是项目的工程核心，目前实现了 12 项检查：

检查项	验证内容
xml-escaping	&、<、>、"、' 正确转义
viewbox-clipping	viewBox 边距在 20-25px 范围
font-stack/missing-font-stack	必须声明完整字体栈
box/height	方框高度符合字体倍数公式
box/baseline	文字基线位置正确
block/spacing	元素间距合规
arrow/marker	箭头标记尺寸与线宽匹配
text/overflow	文字不超出方框
text/overlap	元素无重叠
canvas/background	有白色底板保证深色主题可读性
colour/palette	颜色符合语义色板（5 套三元组）
connector/geometry	连接线无右角折线，使用贝塞尔曲线

每个失败都附带「当前值 → 正确值」的修复建议，例如：

font-stack/missing-font-stack
  repair: font-family: absent → 'PingFang SC', 'Microsoft YaHei', ...

linter 本身零依赖，仅用 Node.js 内置 API 实现，是工程质量的体现。

---

四、AI Agent 加载流程

svg-diagram 支持覆盖所有主流 AI 编码工具的技能目录：

平台	安装路径
Claude Code	~/.claude/skills/svg-diagram/
Codex, Cursor, Copilot, opencode 等	~/.agents/skills/svg-diagram/
Windsurf, Continue, Roo, Trae 等	~/.<agent>/skills/svg-diagram/

安装命令一行搞定：

npx skills add bybit-exchange/svg-diagram -g

Agent 加载 SKILL.md 后，会在对话中自动识别「这是画图任务」，并按规范输出 SVG 文件。

---

五、Gallery：十个示范图，每个对应一条规则

项目自带十个经过 linter 验证的示例图，每个图对应 SKILL.md 中的一条具体规则，是最直观的使用指南：

• 01-架构技能加载图：展示 Agent 如何从磁盘加载 SKILL.md 并在会话中激活技能
• 02-SVG 创作循环：六步创作流程，含失败修复分支
• 03-lint gate 时序图：展示 Agent → svg-lint → 文件系统的闭环
• 04-数据 API 到文档图：演示 CJK 标签宽度计算的实际应用
• 05-技能生命周期图：从 draft 到 deprecated 的五态转换
• 06-仓库结构图：用图本身表示图自身的目录结构
• 07-一键安装扇出图：一个命令如何分发到多个平台
• 08-CJK 字体对比图：正确渲染 vs tofu 渲染的视觉对比
• 09-分层路由数据流图：展示请求如何经过分类进入不同能力层
• 10-A/B 基准测试图：用模型评判两条输出质量的实验设计

---

六、使用门槛与局限

适用人群

• 有 AI 编码 Agent（Claude Code、Codex 等）的开发者：安装即用，质量立即提升
• 需要生成技术文档配图的团队：统一视觉风格，减少人工 review 成本
• 关注文档可维护性的开发者：SVG 是纯文本，diff 可追溯

局限

1. 不适用非编码 Agent：纯 Chat 界面的 AI（如 ChatGPT 网页版）无法加载 SKILL.md
2. 需要 AI 主动使用：Agent 需要在对话中识别图任务并加载技能，非强制
3. lint gate 是手动的：svg-lint 需要人工运行，Agent 不会自动触发
4. 需要基础 SVG 知识：调试不符合预期的输出时，需要了解 SVG 基本语法

---

七、项目质量评价

维度	评分	说明
代码质量	★★★★★	984 个测试，零依赖，代码即文档
文档质量	★★★★★	SKILL.md 本身即是最完整的使用手册
实用性	★★★★☆	直接提升 AI 生成技术图表的质量
CJK 支持	★★★★★	解决了 AI 画图中文乱码的痛点
生态覆盖	★★★★★	覆盖 40+ AI 编码工具平台

---

八、行业意义

随着 AI 编程工具的普及，「让 AI 写代码」已经成熟，但「让 AI 写好文档」仍是痛点。svg-diagram 填补了一个具体缺口：AI 生成的技术图表。

传统方案（Mermaid、PlantUML）的局限在于：需要用户写 DSL，AI 很难直接生成符合预期的输出。svg-diagram 则把规范直接灌入 AI 的行为，让 AI 在「画图」这个具体任务上真正做到「第一次就画对」。

这种「把规范编码成 Agent Skill」的思路，可以复制到任何需要一致性的 AI 任务上：代码风格检查、文档格式规范、API 设计模式——svg-diagram 是这个方向的先行者。

---

项目地址：https://github.com/bybit-exchange/svg-diagram · MIT License · 约 600 ⭐