想在文档里配张图，手写 SVG 太费时间，画图工具导出来的东西进不了 git ，Mermaid 又是把排版交给引擎，你说不上话。svg-diagram 走的是第三条路：你用一句话说要什么图，agent 手写一份 SVG 给你，直接放进 README 或文档站就能用。
下面每张图都是这么来的，附上当时说的那句话。图里全是中文标签，不用额外配字体。
装上
npx skills add bybit-exchange/svg-diagram -g
嫌记不住命令，把这句话丢给你的 agent 也一样：
帮我装一下 svg-diagram skill： https://github.com/bybit-exchange/svg-diagram
运行 npx skills add bybit-exchange/svg-diagram -g
它会认出你本机装了哪些 agent ，按各家的约定写好路径。Claude Code 在 ~/.claude/skills/，Codex 、Cursor 、Gemini CLI 、Copilot 、opencode 、Antigravity 共用 ~/.agents/skills/，其它四十多个 agent 各按自己的目录。去掉 -g 就只装进当前项目。
装完开一个新会话，说「画一张 XX 架构图」。agent 应该主动说它在用 svg-diagram。没说就是没触发，重开一次会话再试。
开口的时候说清五件事
图画歪，多半是信息没给够。这五项给齐，第一版基本就能直接用：
- 要哪种图。架构图、流程图、泳道图、时序图，说法不同，骨架就不同
- 有哪些框，谁跟谁并列、谁在谁下游、哪几个要圈成一组
- 方向。自上而下，还是从左到右
- 颜色想区分什么。按层、按角色、按成功失败，你不说它就自己挑，挑的未必是你想强调的那条线
- 最终多宽。要进 README 就说 700–800 ，窄栏文档说 500–600
一个能直接改着用的模板：
画一张中文<图种类>：<一句话主题>。
<第一组> = A / B / C ；<第二组> = D / E ；<第三组> = F 。
方向<自上而下 / 从左到右>，<某几个> 圈成一个虚线分组框。
颜色按<层 / 角色 / 状态>区分：<X 蓝、Y 橙、Z 绿>。
宽度 <700-800>。
架构图：讲清楚数据从哪进、从哪出
画一张中文架构图：混合检索记忆系统的分层架构。
检索层 = 用户提问 → 检索引擎 → 向量搜索与 BM25 两路并行 → 合并重排 → 上下文注入 → LLM 回答；
存储层 = Markdown 文件（唯一事实来源）、向量索引、倒排索引、元数据；
索引层 = 文件监听 → 分块嵌入 → 增量更新。
三层各圈一个虚线分组框，层之间用箭头串起来。宽度 700-800 。
这种图最适合放在 README 开头，或者技术方案的第一节。有个细节值得注意：两路并行搜索是画成左右分叉再汇合，而不是排成一列。让 agent 说「两路并行」它就会这么处理，你不用去描述分叉的形状。
分层漏斗：一眼看出量级怎么收窄
画一张中文漏斗式分层图：推荐系统四层漏斗。
自上而下 = 候选池（约 1000 万）→ 召回（约 1 万）→ 粗排（约 1000 ）
→ 精排（约 100 ）→ 重排（约 10 ）→ Top N 。
用逐级收窄的框宽表现漏斗形状，量级数字用小字放在框右侧。
漏斗形状不用你算宽度，说「逐级收窄」就够了。量级注释放右侧而不是框里，是因为框里塞两行会把图撑高，右侧留白反正是空着的。
泳道图：谁在什么时候做什么
画一张中文泳道图：一个需求从提出到上线的跨职能流程。
四条横向泳道自上而下 = 产品 / 研发 / 测试 / 运维。
产品道：需求评审、验收确认；研发道：方案设计、编码实现、修复缺陷；
测试道：用例执行、回归验证；运维道：灰度发布、全量上线。
主流程从左到右推进。再加一条紫色虚线回退箭头：用例执行失败回到修复缺陷。
泳道图的价值在于责任边界，所以泳道名要用职能而不是人名。回退线记得单独提一句，不然它只会画顺流程；提了它就会用虚线画，跟主流程区分开。
时序图：一次调用里谁先谁后
画一张中文时序图：一次带工具调用的 agent 会话。
参与者 = 开发者 / 编码 Agent / MCP 数据工具 / LiteLLM 网关。
消息自上而下：提出问题 → 匹配并加载 Skill （ Agent 自调用）→ 查询指标
→ 返回数据行 → 带上下文请求模型 → 流式返回 → 给出答案。
用一个虚线框圈住「命中缓存 / 未命中转发上游」这段。
「自调用」这个词要说出来，它才会画成离开生命线再弯回去的那条弧线。分支、循环这类框也一样，说「圈一个虚线框」比说「加一个 alt 」更稳。
生命周期：带回环的闭环流程
画一张中文生命周期图：一个 skill 从想法到发布的八个阶段，
按准备 / 测试 / 评估迭代 / 发布四个大阶段分组。
从「改进内容」回到「运行测试」画一条虚线回环，标注「重复迭代」。
回环线是这类图最容易画丢的东西。SVG 里画在后面的元素盖住前面的，跨越好几个框的回环线如果按顺序画，会被后画的框吃掉半截。跟 agent 说清「有一条从 X 回到 Y 的回环」就行，它知道要最后画。
左右对照：两种方案摆在一起比
画一张中文对照图：Loop Engineering 与 Graph Engineering 的差别，
左右两栏对照。左栏控制权在模型，右栏控制权在代码，
每栏下面列三条对比说明：控制权归属、状态怎么存、改行为的成本。
技术选型文档里最实用的一种。左右分栏要说明「对照」，不然它容易画成上下两块，读者就得来回扫。
不满意怎么让它改
改动一次收齐再说。你说一条它改一条，每改一次它都要把整张 SVG 重新输出一遍，来回几轮很磨人。它收到单条改动时通常会反问一句「还有别的要调的吗」，这时候把想改的都列出来。
这些说法它都能直接执行：
- 「整体紧凑一点，空白太多」
- 「把 B 框挪到 C 后面」
- 「颜色按成功和失败区分，失败那条走粉色」
- 「加一条从 E 回到 B 的虚线，标注重试」
- 「标题改成 XXX ，宽度收到 600 」
挪框这种改动不用你操心连带影响。说「把 A 往右挪 20px 」，进出 A 的箭头、A 那一排的对齐、A 的文字、包着 A 的分组框、整张图的尺寸，它会一起跟上。这些依赖关系写在规范里，漏一个图就歪了，所以直接说结果，别自己拆成五条指令。
图放哪、怎么引
放在文档旁边的 assets/ 里：docs/foo.md 的图放 docs/assets/foo-arch.svg，正文用相对路径引 。不要把 SVG 内容内联进 Markdown ，那样 diff 会很难看。
出来的是纯 SVG ，没有运行时也不带 JavaScript ，README 、文档站、PDF 、终端预览里都能渲染。每个坐标都是文件里写死的数字，改一张图在 git 里就是一条正常的 diff 。
最后一件事：文档里的数据改了，图得跟着改。这条规范里是硬要求，理由是一张跟旁边正文对不上的图比没有图更糟。
还能画什么
同一套画法也能画平台分层这种偏静态的结构图：
数据流、状态机、对比矩阵、事件时序都在射程内。
觉得有用的话
给个 star 就是最好的反馈：https://github.com/bybit-exchange/svg-diagram
Select Language