一语成美图的 SKILL

想在文档里配张图，手写 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，正文用相对路径引 ![标题](assets/foo-arch.svg)。不要把 SVG 内容内联进 Markdown ，那样 diff 会很难看。

出来的是纯 SVG ，没有运行时也不带 JavaScript ，README 、文档站、PDF 、终端预览里都能渲染。每个坐标都是文件里写死的数字，改一张图在 git 里就是一条正常的 diff 。

最后一件事：文档里的数据改了，图得跟着改。这条规范里是硬要求，理由是一张跟旁边正文对不上的图比没有图更糟。

还能画什么

同一套画法也能画平台分层这种偏静态的结构图：

数据流、状态机、对比矩阵、事件时序都在射程内。

觉得有用的话

给个 star 就是最好的反馈：https://github.com/bybit-exchange/svg-diagram