一份 SKILL.md + 渲染脚本，教 AI 按手绘风格画 SVG 流程图。
1. svg-flow-diagram 是什么？
svg-flow-diagram 是一个 AI 代理技能（Skill），安装后 AI 会学会一套从零生成 SVG 流程图的方法。
它不是一个 npm 包，不是一个 CLI 工具——而是一份"操作手册"，让 Copilot / Claude Code / Codex 按照这套方法，
根据你的描述自动生成图表。
生成的图表采用 Excalidraw 手绘风格：暖色纸质背景、圆润边框、虚线动画流线， 看起来像手画的草图，但其实是精确的 SVG 矢量图。
关键区别：这不是 Mermaid 那样的文本转图表工具。AI 会直接输出原始 SVG 代码，
节点位置、连线路径、动画参数全部由 AI 根据上下文计算——灵活度远高于模板方案。
2. 支持哪些平台？
目前三个主流 AI 编码代理都支持这个 Skill，安装目录略有不同：
⬡
GitHub Copilot
VS Code 中的 Copilot Chat，通过 .copilot/skills/ 或 .vscode/ 目录发现。
~/.copilot/skills/svg-flow-diagram/
◈
Claude Code
终端中的 Claude Code，通过 ~/.claude/skills/ 目录加载。
~/.claude/skills/svg-flow-diagram/
◉
OpenAI Codex
Codex CLI，通过 ~/.codex/skills/ 目录加载。
~/.codex/skills/svg-flow-diagram/
3. 安装步骤
以 GitHub Copilot（VS Code）为例，其他平台只需替换目标路径。
方式一：Git Clone（推荐）
bash
# 进入 Copilot skills 目录（不存在会自动创建）
mkdir -p ~/.copilot/skills
cd ~/.copilot/skills
# 克隆仓库
git clone https://github.com/helson-lin/svg-flow-diagram.git方式二：软链接（适合本地开发）
如果你已经把仓库 clone 到别的位置，可以建一个软链接：
bash
mkdir -p ~/.copilot/skills
ln -s /your/local/path/svg-flow-diagram ~/.copilot/skills/svg-flow-diagram针对 Claude Code
bash
mkdir -p ~/.claude/skills
git clone https://github.com/helson-lin/svg-flow-diagram.git ~/.claude/skills/svg-flow-diagram针对 Codex
bash
mkdir -p ~/.codex/skills
git clone https://github.com/helson-lin/svg-flow-diagram.git ~/.codex/skills/svg-flow-diagram4. 验证安装
安装完成后，确认目录结构正确：
bash
# 以 Copilot 为例，检查关键文件是否存在
ls ~/.copilot/skills/svg-flow-diagram/
# 你应该看到这些文件：
# SKILL.md ← AI 读取的技能定义
# scripts/ ← 渲染脚本
# references/ ← 风格和格式参考
# assets/ ← 模板和示例
重要：安装后请重启 VS Code（或重启 Claude Code / Codex 会话），
让代理重新扫描 skills 目录，才能发现新安装的技能。
5. 仓库结构一览
| 文件 / 目录 | 作用 |
|---|---|
SKILL.md |
技能定义文件，AI 代理读取后学会生成流程图的完整方法论 |
scripts/render_flow_svg.py |
主渲染脚本，从 JSON spec 生成 SVG 文件 |
scripts/flatten_svg_colors.py |
颜色扁平化辅助脚本，用于导出兼容性更好的 flat SVG |
references/style-guide.md |
视觉规则：配色、字体、节点形状、动画参数 |
references/svg-recipes.md |
JSON spec 格式说明和可复用的 SVG 代码片段 |
assets/example-spec.json |
示例 JSON 规范文件，可直接作为脚本输入 |
assets/base-template.svg |
基础 SVG 模板，适合快速手动编辑 |
6. 怎么用？
安装完成后，在对话中描述你需要的图表，AI 会自动调用这个 Skill。
Copilot（VS Code）
直接在 Copilot Chat 里说：
prompt
帮我画一个用户注册流程的 SVG 流程图：
填写表单 → 提交 → 后端校验 → 发送验证邮件 → 用户确认 → 注册成功Claude Code
建议在提示词中显式引用技能路径，避免发现差异：
prompt
使用 $svg-flow-diagram（路径 ~/.claude/skills/svg-flow-diagram）
帮我画一个微服务架构图，包含：
API Gateway、用户服务、订单服务、消息队列、数据库
保留 svg，同时导出 png。Codex
prompt
$svg-flow-diagram 帮我画一个 CI/CD 部署流水线：
代码提交 → 构建 → 单元测试 → 部署 Staging → 人工审批 → 部署生产
导出 svg 和 png，告诉我文件路径。7. 不通过 AI，直接命令行使用
如果你只想用渲染脚本本身，也可以直接跑命令行：
bash
# 基本用法：从 JSON spec 生成 SVG
python3 ~/.copilot/skills/svg-flow-diagram/scripts/render_flow_svg.py \
spec.json \
output.svg
# 完整用法：同时导出 flat SVG 和 PNG
python3 ~/.copilot/skills/svg-flow-diagram/scripts/render_flow_svg.py \
spec.json \
output.svg \
--flat-svg-out output.flat.svg \
--png-out output.png
其中 spec.json 是图表的结构描述，格式参考仓库中的 assets/example-spec.json。
支持的字段包括 width、height、title、nodes、edges、groups 等。
8. 出图是什么风格？
生成的 SVG 遵循一套统一的手绘视觉系统：
暖色纸质背景
不是纯白，而是带微黄的纸张质感（#FCFBF7），配合点状纹理。
圆润双线边框
节点用双层描边模拟手绘效果，支持方形、药丸形、菱形。
虚线动画流线
连接线用 stroke-dashoffset 动画表示流向，比静态箭头更直观。
克制的柔和配色
6 种预设色调：sand、mint、sky、coral、amber、graphite，都是低饱和柔和色。
9. JSON Spec 格式速查
如果你想自己写 spec 文件传给脚本，这是核心字段：
| 层级 | 字段 | 说明 |
|---|---|---|
| 顶层 | width, height |
画布尺寸（px） |
| 顶层 | title, subtitle |
图表标题和副标题 |
| nodes[] | id, label, caption |
节点标识、显示名和小标注 |
| nodes[] | x, y, w, h |
节点位置和尺寸 |
| nodes[] | tone |
填充色调：sand / mint / sky / coral / amber / graphite |
| nodes[] | shape |
节点形状：rect / pill / diamond |
| edges[] | from, to |
连线的起始和结束节点 id |
| edges[] | label, tone, duration |
连线标注、颜色和动画时长 |
10. 使用技巧
- 节点数量：请求描述模糊时，AI 默认会画 4-8 个节点、一条主线加最多两条支线。如果图更复杂，请明确列出。
- 迭代调整：生成后可以对 AI 说"把节点 A 的颜色改成 coral""把连线方向从左到右改成从上到下"，AI 会直接修改 SVG。
- PNG 变黑：如果导出的 PNG 背景变黑，多半是转换器没处理好 CSS 变量——让 AI 先导出
flat.svg，再从 flat 版转 PNG。 - 不要混合太多：不要把"系统架构"和"执行时序"强塞进一张图。拆开画，可读性更好。
11. 注意事项
- 这个 Skill 只输出 SVG。不会切换到 Mermaid、HTML Canvas 或 Figma，除非你明确要求。
- 不会引入远程字体、外部库或 JavaScript——输出是完全自包含的 SVG 文件。
- 不使用 3D 渐变、毛玻璃或浓重阴影——保持手绘风格的克制美感。
- 动画只用于辅助表达方向，暂停动画后图表依然完整可读。