1. 这波“画图Skill”热起来恰好戳中了Agent最尴尬的死角先说个我自己的故事。前阵子有朋友找我帮忙搭一套“自动生成技术方案配图”的流水线我当时第一反应是让大模型写Python画图还不简单结果真跑起来才发现十个图里能有一个能直接放进文档都算烧高香。要么是matplotlib中文全变方块要么是流程图节点挤成一团要么是图表风格丑到不敢发给同事。那段时间我几乎快把画图相关的开源库翻了个底朝天直到看到GitHub上这个狂揽2.5万 Star的画图Skill项目才意识到问题根本不在“绘图代码”而在“怎么让Agent把画图当成一件有章法的事来做”。这个开源项目本身不复杂核心就一个词Skill。如果你接触过Anthropic提出的 Claude Skills 体系或者玩过Codex的skills目录应该知道它本质上是一套“给AI代理预置能力”的规范包。以前我们让Agent画图是在瞎碰运气模型今天心情好可能给出一个能跑的matplotlib脚本明天换个模型可能连图表类型都选错。而有了这套Skill之后Agent会按照固定的工作流去处理画图需求先判断你要什么类型的图再选择合适的渲染引擎然后生成文件、执行预检、最后把结果反馈给你。整个过程不再是自由发挥而是走一条被验证过无数次的流水线。它解决的是什么问题说白了过去AI画图是个“玄学”现在被做成了“工程”。我举个例子以前让Agent画“系统架构图”它大概率会直接输出一段mermaid代码但你把它复制到文档里可能连布局都歪了。这套Skill会先问自己这个架构图是给谁看的是给开发看详细的模块依赖还是给领导看顶层划分然后它会主动选择用mermaid的flowchart、还是用SVG模板、甚至是用Python的Graphviz来画。这个“主动选型”的能力就是它能拿下2.5万Star的根本原因。所以这篇内容我打算站在一个“深度用户二开贡献者”的角度给你完整拆一遍它内部到底设计成了什么样为什么能让Agent稳定画出能用的图怎么把它接到你自己的Agent工作流里我实测跑了几千次之后踩过的坑哪些是文档里绝对没写的最后再说说怎么往这套Skill里加自己的私有模板。不管你是正在折腾Agent技能包、想给团队搭一个画图服务还是单纯被“2.5万Star”吸引进来想看看它凭什么火这篇文章应该都能给你一些可落地的参考。2. 架构拆解一个画图Skill的肚子里装的不只是“会画图”2.1 三层管线设计先想清楚再动手是它和普通脚本的本质区别这套Skill给我的第一印象是它的目录结构特别像一个正经的软件工程而不是一堆随手写的脚本。核心检索下来它内部大致分了三层第一层是需求理解。Agent接收到用户一句话之后不是直接调画图函数而是先完成一次“翻译”。比如用户说“帮我看看最近30天请求量趋势”Skill会先提取意图时间序列数据、需要折线图、横轴是日期、纵轴是请求量还要考虑数据点的个数和显示密度。这一步看起来简单但大多数画图翻车都是在这里埋下了隐患——模型根本没搞懂你要对比关系、分布关系、还是流程关系就急着生成代码。第二层是方案选择。根据第一步的判断结果Skill内部会走一个“路由表”。同样是数据可视化如果数据量小、偏展示型可以走Python的matplotlib或Plotly如果目标是快速生成一张流程图、时序图走Mermaid最省事如果是复杂的架构图、拓扑图SVG模板的稳定性反而比让模型现写代码高得多。这一层是这套Skill设计里最值钱的部分因为它把“选型经验”固化成了规则。第三层是渲染执行。选定方案之后Skill会调用预设的模板、脚本把数据填充进去生成代码、执行渲染、输出文件并主动跑一遍预检脚本。比如检查生成的文件是否为空、尺寸是否合理、字体是否存在然后把结果反馈给用户。这一步是它和“裸奔式Agent画图”拉开差距的关键。这里有一个特别值得学习的设计理念它没有奢求大模型“一锤子生成一张完美图片”而是把任务拆成“理解-选型-渲染-校验”四个环节让模型在每个环节只做自己擅长的事。这就像你让一个实习生画图不是丢给他一个需求就撒手不管而是先让他说清楚打算怎么画、用什么工具画完还要自己检查一遍再交上来。2.2 渲染引擎的选型逻辑为什么Mermaid、Python、SVG一个都不能少我仔细看了它的renderers目录里面挂了四类渲染方案。说实话一开始我觉得有点多余后来用多了才明白每个工具都有自己不可替代的边界渲染方案适用场景常见用途举例为什么选它Mermaid结构化图表流程图、时序图、甘特图、状态图语法接近自然语言模型生成的正确率高文本可diff方便版本管理Pythonmatplotlib/Plotly数据图表折线图、柱状图、散点图、热力图生态最成熟定制能力强适合科学计算和数据分析SVG模板示意图/架构图系统架构图、网络拓扑、容器关系图用占位符参数填充布局稳定不会出现乱跑的重叠HTML/CSS大屏看板、汇报页仪表盘、卡片式统计图展示效果最好适合直接嵌入Web页面Mermaid被放在默认首选位置不是没有道理的。对于大模型来说Mermaid语法容错率很高而且生成结果是纯文本后续修改只需要让模型改几行代码就行。但Mermaid的硬伤也很明显一旦节点太多、连线太复杂布局就会乱得没法看。所以这套Skill做了一个“复杂度判断”如果识别到流程超过12个节点它会自动提醒用户“建议拆图”或者切换到SVG模板方案由预置的布局系统来保证整齐度。Python引擎更多是“数据类”兜底。比如用户给了一份CSV说要分析各渠道的转化率这时候Mermaid就使不上劲了得靠matplotlib或Plotly出图。Skill内部预置了多个图表模板包括横坐标自动旋转、标签密度控制、中文字体配置这些其实都是在解决那些年我们被“python画图横坐标太密集”“plt画图显示中文问题”支配的恐惧。SVG模板是我个人最喜欢的一部分。它里面存了很多带占位符的SVG文件比如一个三层的微服务架构图模板你只需要往{{service1}}、{{service2}}这些位置填服务名字就能生成一张排版工整的图。这比让模型直接写SVG路径要可靠得多——模型手写SVG经常出现坐标重叠、文字溢出但填模板基本不会出大问题。2.3 SKILL.md里的门道为什么一份说明书就能管住Agent如果你打开这个项目的根目录会看到一个SKILL.md文件。别小看这份Markdown它才是整套Skill的灵魂。我读这份文件时最大的感受是它把“画图领域的隐性经验”全部转化成了模型能读懂的操作指令。举个具体的例子文件里会写这类规则当用户请求绘制图表时第一步识别图表类型按“流程类/数据类/结构类/展示类”四类归档第二步估算数据规模和节点数量超过阈值必须提示拆图或换用模板第三步选择渲染引擎按“默认Mermaid、数据用Python、架构用SVG模板”的优先级执行渲染完成后必须用validators目录下的脚本检查输出文件出现0字节文件或明显尺寸异常时要自动重试。这些规则表面上看是在教模型“怎么画图”实际上是在限制模型的自由发挥空间。大模型天生爱自由给它一个空白的画布它可能画出花来但大多数情况下画出来的是灾难。SKILL.md的作用就是把过去踩过的坑、验证过的做法全部变成一条条“如果看到X就做Y”的约束条件让模型在既定轨道里行动。另外它还特意写明了一个细节在生成图片文件之后要把生成的关键代码片段一并输出给用户方便用户二次修改。这个设计很聪明。因为无论Skill做得再完善AI出的图总是需要微调的把代码暴露出来等于给了用户一条“手动接管”的通道而不是让用户面对一个黑盒。3. 从Clone到跑通如何把这个画图Skill装进你的Agent工作流3.1 环境准备只靠clone是跑不起来的先说打击人的结论这项目不是git clone下来就能用的。虽然仓库本身是一个Skill包但它依赖的外部工具不少。要让Agent走完完整渲染流程你至少需要准备这么几样东西Python 3.10以及matplotlib、plotly这些核心绘图库Node.js环境因为Mermaid CLI靠它跑一个能执行HTML渲染的无头浏览器项目默认用Playwright主要用于SVG和HTML方案的截图导出如果你想把它接到云端Agent还需要配置对应的模型API和本地沙箱执行目录。我自己踩过一个比较蠢的坑第一次clone完想直接跑demo结果发现渲染流程图时一直报“mmdc command not found”折腾了半天才想起来没全局安装mermaid-js/mermaid-cli。这类环境问题文档里有写但很容易被跳过毕竟大家都习惯“先跑起来再说”。环境配好之后建议先把仓库里的demo目录跑一遍。里面有几个写死的测试用例包括画一个系统架构图、画一份月度销售趋势图、画一张简单的部署流程图。如果这三个用例都能正常输出文件说明基础环境基本没问题。3.2 接入Claude Code把Skill塞进它的技能目录如果你用的是Claude Code或者桌面版接入方式比较直接。Claude Skills的规范是在项目下建一个.claude/skills目录把Skill包放进去模型会自动扫描并识别。具体操作就是在项目根目录创建.claude/skills/目录把chart-skill整个目录复制进去确保SKILL.md在chart-skill根目录下重新启动Claude Code然后在对话里输入“你会画图吗”如果模型回答里提到了流程图的处理方式说明它已经加载到Skill了。这里有个容易被忽略的点SKILL.md里的文件名不能随意改。Claude Code是靠扫描固定文件名来识别Skill的如果你改成README.md或者instructions.md它大概率就找不到了。目录名可以改但文件名最好保持原样。3.3 接入Codex CLI和自建Agent框架Codex CLI的接入思路类似但它更依赖“自定义指令文件”。你可以把SKILL.md的核心内容抽成一段系统提示词加到Codex的AGENTS.md里然后把renderers目录作为可引用的外部资源。这样做的好处是接入快缺点是失去了Skill目录的动态加载能力。自建Agent框架的情况更灵活一些。比如你用LangChain或者CrewAI的话可以把这套Skill封装成一个Tool。核心思路是把“选型渲染校验”封装成一个函数函数输入是用户需求文本输出是生成图片的路径和相关说明。我封装的时候保留了一个入口函数generate_chart(request: str, output_dir: str)内部会先调用一个小的意图分类Prompt再根据分类结果走不同渲染管线。无论哪种接入方式有一个原则是通用的你需要让Agent能够“看得到”渲染结果而不是只知道“文件已经生成”。我在自建工具链时会在渲染完成后把图片转成base64回传给模型让模型自己看一眼生成效果再决定要不要重试。这一步看起来多余但对成图率的提升非常明显。3.4 最小可用验证一条Prompt跑通全流程接入完成后拿这条Prompt做“冒烟测试”最合适“画一个用户登录模块的时序图包含客户端、服务端、数据库三个角色以及登录请求、校验、返回Token三个步骤。”正常情况下Skill会识别出这是“流程类时序图”然后走Mermaid渲染生成一个SVG或PNG文件。然后你打开文件看一眼如果角色没有重叠、消息线清晰、整体可读说明管线已经通了。这时候恭喜你你已经拥有了一个基本靠谱的AI画图助理。不过还要提醒一句第一次跑通不代表所有场景都OK我后面一整章讲的都是你以为OK了、结果被现实打脸的情况。4. 实测数千次后的翻车现场汇总5类最隐蔽的画图坑4.1 中文乱码与字体问题它比你想的更阴魂不散这大概是所有画图场景里出现频率最高的坑特别是Python引擎。明明同一个matplotlib脚本在本地跑没问题但放进Agent沙箱里跑中文全变方格。根因不是代码问题而是沙箱镜像里根本没有中文字体。这套Skill虽然有字体预检逻辑但防不住用户新增的服务器环境里没装字体。我实测下来的解决办法是两步走第一步在环境初始化脚本里主动安装一组字体比如fonts-noto-cjk并把matplotlib的字体缓存路径指过去第二步在SKILL.md的规则里强约束“启动任何绘图任务前必须先执行字体检查脚本”。项目自带的validators里有一个check_fonts.py它会扫描系统已安装的中文字体并把可用的字体名写到一个缓存文件里画图脚本再从这个文件里动态读取字体名。如果这两步都做了还是乱码那就要检查是不是模型生成代码时硬编码了英文字体名比如设置了font.family为Arial。我在二次开发时直接改了系统默认模板把所有字体设置统一改成config.py里的FONT_NAME变量避免模型写死。4.2 横坐标过密与时间轴错位数据一多阅读性直接归零第二个高频翻车点就是输入数据几百条时模型生成的折线图横坐标标签全部堆在一起。这个场景在Keyword里被反复提及说明是普遍的痛。Skill里有两个应对机制自动降采样当数据点超过50个模板会自动改成每隔N个点取一个标签旋转标签设置rotation45并且开启tight_layout。但这两个机制也有限制。我曾经拿一份包含300天数据的CSV去测试降采样之后横轴还是密密麻麻因为模型生成代码时偷懒直接把所有日期都当成了刻度。后来我在模板里加强了一个规则当时间跨度超过60天自动切换为“月度”刻度格式而不是逐日显示。这需要调用matplotlib.dates的MonthLocator模板里提前写好模型只需要在对应分支里填入数据。如果你自己维护这类Skill我的建议是别指望模型自己判断“应该显示多少标签”百分之百会在边界条件上翻车。把刻度策略写死在模板里比在Prompt里反复强调“别太密”要可靠得多。4.3 长流程时序图的布局爆炸Mermaid不是万能的Mermaid虽然好写但它的布局算法很脆弱。一旦时序图里参与交互的角色超过4个、步骤超过10步生成出来的图基本没法看消息线交叉得跟蜘蛛网一样。最让我崩溃的一次是让Agent画一个“订单从创建到完成”的全链路时序图涉及用户、前端、后端、订单服务、支付服务、库存服务、消息队列七个角色模型很勤快地生成了完整代码但渲染出来的图完全不可读。这个Skill的解法是“强制分图”当检测到参与者超过5个就提示用户是否拆分成多张子图。比如“第一张画订单创建阶段第二张画支付阶段第三张画库存扣减阶段”。这么做虽然增加了输出数量但每张图都清晰可读反而比一张巨图更有实用价值。我后来在自己的分支里把“分图提示”改成了“自动拆分”。如果模型检测到角色数超限它会直接输出一个包含多张子图的Markdown结构而不是停下来问用户。生成完之后再统一渲染节省了不少交互轮次。如果你打算长期使用这个Skill强烈建议把这个自动拆分逻辑加上。4.4 SVG模板里暗藏的绝对定位陷阱SVG模板方案最稳但也最容易出现“字面意义上的离奇问题”。项目预置的模板里很多图形元素的坐标是px写死的。填进去的服务名一旦超过一定长度文字就会溢出边界或者和旁边的模块重叠。举例来说一个预置的“四模块架构图”模板每个模块的位置写死在SVG里占位符只替换了模块名称文本。当我把一个叫user-profile-service-with-cache的长名字填进去整个模块就被撑破了。后来我在模板里引入了“文本长度自适应”机制在渲染前先用脚本估算文本占位宽度如果超出预设阈值就自动缩短显示名或者在SVG里插入tspan做换行。这个坑也是文档里完全没写的属于典型的“只有被真实业务毒打之后才会想到”的细节。如果你打算基于这个Skill二次开发建议把模板里的固定尺寸全部改成可计算变量哪怕牺牲一点模板复杂度也要换来自适应性。4.5 多轮迭代后风格漂移越改越不像同一张图最后这个坑比较进阶但影响很大。当你让Agent“重新画一版颜色柔和一点”或者“把标题改成另一个”它大概率只会改你指定的部分。但如果连续改四到五次你会发现最终图和最初版本已经完全不像同一套风格了——标题字体大小变了、配色歪了、图例位置也挪了。根因是模型只看到当前对话的局部上下文缺少一份“全局风格基线”。我在踩过几次坑之后给Skill增加了一个style_profile.md文件里面固定记录了一套风格规范包括主色、辅色、字体族、标题字号、图例位置、圆角大小。每一轮迭代开始前SKILL.md都会强制模型先读这个文件再基于它执行改动。效果立竿见影。加了这个风格基线之后连续迭代个五六轮图的风格依然能保持统一。这个思路其实可以推广到其他类型的Agent技能包里任何涉及“多轮修改”的生成任务都应该在外部保存一份“不可随意更改的基线配置”而不是靠模型自带的记忆能力。5. 进阶扩展把通用画图Skill改造成你的团队私有资产5.1 Skill目录里的扩展点在哪里加东西才是对的用熟之后你大概率会想往里面加自己的模板或者规则。这套Skill的设计留了几个明确的扩展点我先说结论再解释为什么templates/目录放自定义的SVG模板、HTML模板命名规则要遵循类型_用途.svgrenderers/目录加新的渲染器比如接入Graphviz、接入R的ggplot2或者接公司内部的图表服务validators/目录加自定义校验脚本比如检查图片分辨率是否低于某阈值、检查输出文件是否是空文件SKILL.md在对应章节追加你的新规则但注意不要和原有指令冲突。其中SKILL.md的修改风险最高因为它影响的是全局行为。我建议每次改动只加一条规则并且跑一遍demo用例做回归。不要一次性加五六条你会发现某个渲染链路莫名挂了排查起来非常痛苦。举个例子我给团队加过一个“品牌规范”规则所有对外图表必须在右下角加上公司logo。这个需求看似简单但在SVG模板、matplotlib脚本、Mermaid渲染三种方案里的实现方式完全不同。SVG可以直接插入水印标签matplotlib需要额外绘制一个imageMermaid只能靠后期用ImageMagick合成。如果不分别处理就会出现“有的图有水印有的图没有”的诡异现象。5.2 让Skill从“画得出”变成“画得对”压缩先行的设计思路用了一段时间之后我意识到一个更深层的问题很多画图任务的失败根源不在画图本身而在数据预处理。Agent拿到的原始数据可能是几万行的CSV、一堆混乱的JSON或者一段口语化的描述。如果不做“压缩”就直接画必然产出没法看的图。所以我把自己的分支改成了“压缩先行”模式任何数据图表任务先经历三个子步骤——数据清洗去空值、去重复、统一字段格式数据聚合把高基数数据按天/按周/按类别聚合成可读的粒度结构摘要让模型用不超过100字说明“这张图要表达的核心信息”确认之后再动手。这一步看起来多花了几秒钟但对出图质量提升巨大。而且它有个额外的好处当模型先写出核心结论、再去画图时它更清楚图表的标题和图例应该怎么写不会再出现“图对了但标题让人摸不着头脑”的问题。5.3 不要把Skill当咒语它只是把“靠运气”变成了“拼流程”最后说点可能不太中听、但真心实意的体会。很多开发者看到“2.5万Star”就觉得这玩意儿是灵丹妙药装上之后Agent画图从此一劳永逸。真不是这样。我实测下来这套Skill能把“随机成功率”从可能20%提升到85%左右但剩下的15%依然需要人来兜底。它本质上做的是“让Agent用一套验证过的流程去画图”而不是“让Agent拥有艺术家的才华”。所以我会建议把它定位成一个标准化生产工具而不是一个智能设计师。适合批量产出那种“质量稳定、风格统一、可交付”的基础图表。如果你需要一张真正有创意、有冲击力的视觉图目前这个开源项目还做不到可能需要结合Stable Diffusion那类生成式绘图模型属于另一个赛道了。想清楚这一点之后这套Skill就会成为你工具箱里一个非常可靠的部件。我的日常工作流里凡是涉及方案流程图、数据趋势图、架构示意图的基本都交给它处理每次至少省半小时。这个效率提升我觉得才是它那2.5万Star背后真正沉淀下来的价值。