AI Agent 结合 SVG 手放坐标：实现可控图表生成与自动化流水线

前阵子 Hacker News 上有个项目叫SVG-diagram一句话概括就是一个 Agent Skill让 AI Agent 用“手工摆坐标”的方式直接输出 SVG 图表。它不是又一个 Mermaid 封装也不是让模型乱写 HTML 再截屏而是把图表生成收敛到 SVG 这一种确定性很强的矢量格式上让 Agent 像设计师一样“手放”每个元素。对做 Agent 工作流、自动化出图、文档插图生成的人来说这个方向挺值得跟一下。先说它最核心的几个特点输出即 SVGAgent 生成的是标准 SVG 文本能直接嵌入网页、Markdown、文档和报告。手工坐标布局通过限定“手放”的方式让模型显式写出x/y/width/height布局可预期不会像 HTML 渲染那样飘。Agent Skill 形态以技能包形式分发跑在 Agent 应用层不需要单独训练模型。几乎不吃显卡它不是图像生成模型本质是“规则 提示 工具脚本”硬件门槛很低。适合接入流水线批量出图、自动插图、程序化生成 XML 素材都可以做。这篇文章会拆开讲Agent Skill 到底是个什么东西、为什么选 SVG 而不是 Mermaid、怎么部署这类技能、怎么验证它生成的图、以及实际接入批量任务时要避开哪些坑。1. SVG-diagram 核心能力速览能力项说明项目类型Agent Skill 技能包非独立大模型主要功能让 Agent 生成结构完整、坐标明确的 SVG 图表输出格式标准 SVG 文本/文件布局方式手放坐标模型显式计算元素位置运行环境支持 Agent 的客户端、API 服务或本地推理框架显存需求理论上可以接近 0取决于你用的是 API 还是本地模型启动方式安装技能 → 在 Agent 会话中触发 → 保存返回的 SVGAPI 能力依赖宿主 Agent 是否暴露 API通常可通过脚本接口封装批量任务支持用输入清单逐个生成即可适合场景文档配图、流程说明、架构图、数据图表自动生成这里有个很容易误判的地方它不负责“画图算颜色”它负责“把图画出来”。真正决定图好不好看的还是底层模型的空间想象力和坐标计算能力。技能的价值是给模型一套稳定的约束和可复用模板避免每次生成都在“自由发挥”。用一句话说SVG-diagram 是减少 Agent 画图随机性的工程化手段。2. Agent Skill 与 Agent、Tool 的边界这段时间 “Agent Skill” 这个词出现频率很高很多人把它和 Tool、Agent 混在一起。尤其“skill和agent的区别”“ai agent skill”这类问题被反复问这里先把概念拉清楚。2.1 Skill 是什么Skill 可以理解为一套预置的“情境操作手册”。它包含任务定义、拆解步骤、代码脚本、示例模板、质量检查项。Agent 在某个任务里把这个 Skill 挂载上相当于临时获得了一组“领域专业知识 动手套路”。和 Tool 的区别是Tool 是“一个可调用的外部函数”比如search_web()、run_sql()Skill 是“一组可复用的工作流”它内部可能调用多个 Tool也可能只是一套规范化输出指令。SVG-diagram 就是典型的后者它不一定调外部工具但它改变了 Agent 的思考方式和输出格式。2.2 Agent 是什么Agent 是能感知环境、做决策、调用工具并执行多步任务的智能体。Skill 是给 Agent 用的“软件包”。Agent 是运行的“人手”Skill 是给这个人的“SOP”。同一个 Agent装上不同 Skill就能处理完全不同的任务。2.3 SVG-diagram 在这条链上的位置从项目命名看SVG-diagram 被设计成标准化 Agent Skill也就是说它应该被复制到 Agent 的 skills 目录里然后 Agent 在绘图任务开始时自动加载。这种分发方式的好处是能力边界清晰更新成本低复用到多项目不需要改模型。缺点也明显它受限于宿主 Agent 对技能包规范的兼容程度。换一个不支持该约定的 Agent 框架技能文件就可能不被加载。实际落地时你最好先确认宿主框架的技能目录规范。主流的做法是把技能放在类似.claude/skills/、skills/或配置文件指定的目录中。每个技能一般是一个文件夹里面是SKILL.md和辅助脚本、模板资源。下面是通用目录结构示例svg-diagram/ ├── SKILL.md ├── scripts/ │ ├── svg_to_png.py │ └── validate_svg.py ├── assets/ │ ├── icon_library.svg │ └── template_flowchart.svg └── examples/ └── demo_request.txt复制到技能目录后先做一次加载测试确认 Agent 能读取到技能描述再进入正式使用。3. 为什么是 SVG而不是 Mermaid、HTML、Canvas生成图表的老路子很多SVG 的优势不是“唯一”而是“均衡”。方案优点缺点Mermaid语法简单模型好生成渲染依赖引擎样式受限复杂图不好控制HTML/CSS页面表现强截图依赖浏览器换环境样式崩Canvas适合动画/复杂绘制不可编辑不可搜索文本难提取SVG矢量、可编辑、可嵌入、可缩放坐标计算容易出错长代码费 tokenPNG/JPEGAgent 可调用画图模型不可编辑缩放模糊文件大SVG 最核心的价值是**“一次生成处处使用”**网页直接img引用Markdown 里用图片标签嵌入文档工具可以导入设计软件能继续编辑。这个链路极其适合自动化流程。“Hand-placed” 手放坐标是 SVG-diagram 的关键限定词。它要求 Agent 在生成图形元素时别指望任何“自适应布局引擎”必须自己把每个矩形的x、y每条路径的d每个文本的text-anchor写清楚。这种做法牺牲了一部分生成速度换来的是布局可预期性。对自动出图来说确定性比炫技重要得多。模型一旦写得含糊渲染出来就是乱成一团的线条。4. 适用场景与使用边界4.1 适合谁做 Agent 工作流需要稳定输出架构图、流程图、时序图的人。写文档不想手动配图希望模型按模板出 SVG 插图的人。做批量素材生成需要导出矢量图给设计/前端复用的人。搞研究验证 AGI 绘图能力想用结构化输出做评估的人。4.2 不适合谁追求“艺术感海报”的用户这个方向不对口SVG-diagram 擅长结构图不擅长光影质感。需要像素级输出照片风格图的人SVG 不是位图格式。对坐标细节零容忍的生产环境Agent 生成的 SVG 偶尔会出现元素重叠需要后置校验。4.3 安全与合规边界用 Agent 生成 SVG 时要注意几点版权素材授权如果能从模板库复制图标要确认图标库的许可证是否是 MIT、CC0 或允许商用。SVG 脚本注入SVG 可以内嵌 JavaScript。如果 Agent 生成的 SVG 要放到公开网站强烈建议经过净化处理然后用img方式加载避免直接内联到页面。数据隐私涉及内部架构图的生成不要传给不可信的第三方 API。审核义务批量生成内容用于商用发布前要做人工复核。5. 环境准备与前置条件SVG-diagram 这种 Agent Skill 的部署门槛比部署一个大模型低很多。它的运行载体是 Agent 本身所以你的核心环境是“能跑 Agent 的运行时”。5.1 你需要准备的环境清单项目要求操作系统Windows / macOS / Linux 均可Python建议 3.10主要跑辅助脚本Node.js非必须取决于技能脚本用什么语言GPU不强制本地小模型也主要看内存磁盘空间很小技能文件通常在几 MB 内Agent 客户端支持 Skill 机制的 Agent CLI 或 API 服务浏览器用于预览 SVG 渲染效果如果走本地推理还需要准备量化的 LLM并给足上下文窗口。SVG 生成属于“长结构化输出”模型上下文太短经常会产出被截断的 SVG。5.2 端口与运行方式这类技能通常不自己开端口它是被 Agent 宿主调用的。如果你把技能包装成一个 HTTP 服务那么要预留一个本地端口比如127.0.0.1:7860。这个不属于项目默认行为是工程集成时自己加的。5.3 前置依赖检查在跑技能前建议先检查下面几项Agent 是否能联网调用模型 API或本地模型服务是否已启动。技能目录是否被宿主正确读取。是否安装了lxml或svgpathtools这类 SVG 解析库如果脚本需要。输出目录是否存在并有写入权限。6. 安装部署与启动方式因为输入材料里没有给出一键包或官方安装脚本下面给一套通用的 Agent Skill 安装流程。实际路径要以项目的 README 为准但结构基本是通用的6.1 下载技能包首先确认技能包的来源。如果是 GitHub 仓库用git clone拉下来或者直接下载 ZIP 解压。git clone https://github.com/your-target/svg-diagram.git cd svg-diagram注意上面是一个通用仓库模板实际地址需要按项目主页替换。不要把不存在的地址当默认值写进脚本。6.2 安装到 Agent 技能目录不同 Agent 框架的技能目录不同。常见的有# Claude Code / Claude 系技能目录 mkdir -p ~/.claude/skills/svg-diagram cp -r svg-diagram/* ~/.claude/skills/svg-diagram/# 项目级技能目录 mkdir -p .claude/skills/svg-diagram cp -r svg-diagram/* .claude/skills/svg-diagram/装完之后重启 Agent 会话或者在 Agent 输入框中查看技能列表确认svg-diagram已被识别。不同客户端的加载方式不同有的需要配置文件声明路径。6.3 处理辅助脚本依赖如果技能包里有 Python 脚本安装依赖pip install lxml defusedxml建议用虚拟环境python -m venv .venv source .venv/bin/activate # Windows 下用 .venv\Scripts\activate pip install -r requirements.txt没有requirements.txt的话就只装实际用到的库。6.4 验证加载给 Agent 发一条非常简单的指令使用 svg-diagram 技能画一个包含 3 个步骤的简单流程图。如果 Agent 返回的是完整svg代码并且你能用浏览器打开预览说明技能已生效。如果 Agent 说“没有找到该技能”优先检查目录层级是不是多套了一层。6.5 服务化启动如果你希望把 Agent 技能封装为 HTTP 服务可以写一个轻量的 FastAPI 入口# app.py from fastapi import FastAPI from pydantic import BaseModel import subprocess app FastAPI() class Request(BaseModel): prompt: str output: str output.svg app.post(/generate) def generate(req: Request): # 这里只是演示真实调用需要按技能脚本来改 result subprocess.run( [your-agent-cli, generate, --prompt, req.prompt], capture_outputTrue, textTrue ) return {status: ok, output: result.stdout}不要把这个当成项目自带接口它只是演示了“如何把一个 Agent 技能包进接口服务”。正式项目若有官方 API以官方接口文档为准。7. 功能测试与效果验证部署好之后不要立刻上复杂需求。按功能粒度逐项测试。7.1 基础生成测试测试目的确认技能能稳定输出合法 SVG。输入示例画一个水平流程图包含 4 个节点数据采集、数据清洗、特征工程、模型训练。每个节点用一个矩形表示矩形之间用箭头连接。检查点返回文本是否以svg开始以/svg结束。SVG 中是否有rect、line或path元素。坐标是否都在viewBox范围内。在浏览器中打开后是否完整显示。判断标准能打开、能看到图形、节点文字可读。7.2 元素重叠测试测试目的验证“手放坐标”是否真的可控。输入示例画一个组织架构图一个上级节点下面 5 个子节点节点之间不能重叠子节点要在同一水平线上均匀分布。检查点5 个矩形是否水平排列。节点间距是否大致一致。上级节点是否位于正上方。如果出现重叠就是模型坐标规划出错需要你手动指正或修改模板。这类问题出现频率不低所以技能包里最好带一个校验脚本# validate_svg.py import re import sys from lxml import etree def validate_svg(path): tree etree.parse(path) root tree.getroot() ns {s: http://www.w3.org/2000/svg} rects root.findall(.//s:rect, ns) overlaps [] for i in range(len(rects)): for j in range(i 1, len(rects)): r1 rects[i] r2 rects[j] x1, y1 float(r1.get(x, 0)), float(r1.get(y, 0)) w1, h1 float(r1.get(width, 0)), float(r1.get(height, 0)) x2, y2 float(r2.get(x, 0)), float(r2.get(y, 0)) w2, h2 float(r2.get(width, 0)), float(r2.get(height, 0)) if x1 x2 w2 and x2 x1 w1 and y1 y2 h2 and y2 y1 h1: overlaps.append((i, j)) return overlaps if __name__ __main__: overlaps validate_svg(sys.argv[1]) if overlaps: print(f发现重叠: {overlaps}) sys.exit(1) print(未发现重叠)这个脚本是通用示例需要按实际情况调整命名空间和元素类型。7.3 样式与主题测试测试目的验证技能能否把颜色、字体、边框统一下来。输入示例画一个暗色主题的系统架构图背景深灰节点边框蓝色文字白色字体大小为 14px。检查点根节点是否带style或fill、stroke属性。文字是否带font-size和fill。颜色是否按指令执行。暗色背景下文字是否可读。SVG-diagram 这类技能通常会内置样式模板如果模型乱改主题大概率是技能描述里没有约束“所有节点必须使用统一样式类”。7.4 文本与可读性测试测试目的验证中文/英文文本是否错位、截断。输入示例画一个数据库关系图包含用户表、订单表、商品表。每张表和它的 3 个字段列在矩形内。字段名id、name、created_at。检查点字段名是否在矩形内部。中文文本是否正常显示。超长字段名是否溢出。SVG 文字溢出是常见问题。如果多次出现最好的办法是让技能在输出前计算文本长度按字符数估算矩形宽度。7.5 导出与兼容性测试测试目的验证 SVG 能否转为 PNG 或嵌入文档。方式用 Inkscape、Chrome 打开或命令行转换为 PNG# 用 rsvg-convert 转换未安装时需要先安装 rsvg-convert -w 1200 -h 800 output.svg -o output.png如果 SVG 中包含外部字体或外部图片导出时可能出现缺失测试时要用自包含字体或系统字体。8. 接口 API 与批量任务如果要把 SVG-diagram 接入自动化流水线最稳妥的做法是“脚本调用 Agent → Agent 返回 SVG → 校验 → 存盘”。下面给的是通用批处理结构具体参数需要按技能脚本调整。8.1 批量任务目录设计batch/ ├── requests/ │ ├── 01_flow.txt │ ├── 02_arch.txt │ └── 03_sequence.txt ├── svg_output/ ├── png_output/ └── logs/每个请求文件里写好一句绘图描述。程序批量读取请求逐个发送给 Agent拿到 SVG 后写入输出目录。8.2 批量调用示例import requests import os API_URL http://127.0.0.1:7860/generate REQUESTS_DIR batch/requests OUTPUT_DIR batch/svg_output os.makedirs(OUTPUT_DIR, exist_okTrue) for filename in sorted(os.listdir(REQUESTS_DIR)): if not filename.endswith(.txt): continue with open(os.path.join(REQUESTS_DIR, filename), r, encodingutf-8) as f: prompt f.read().strip() try: resp requests.post(API_URL, json{prompt: prompt}, timeout180) data resp.json() out_name filename.replace(.txt, .svg) with open(os.path.join(OUTPUT_DIR, out_name), w, encodingutf-8) as f: f.write(data[svg]) print(f[OK] {filename} - {out_name}) except Exception as e: print(f[FAIL] {filename}: {e})如果宿主的 Agent 没有 HTTP 服务可以把上面API_URL部分替换为调用本地 CLI 命令的subprocess.run()。8.3 失败重试策略批量生成最容易遇到三类失败模型超时。返回内容不是合法 SVG。返回内容被截断。建议做法对输出做字符串校验不以/svg结尾就判定失败。失败自动重试 2 到 3 次间隔递增。重试仍失败时写入logs/failed.txt记录请求文件名和错误信息。全部跑完后用批量脚本统一校验 SVG 合法性。def is_valid_svg(text): return text.strip().startswith(svg) and text.strip().endswith(/svg)9. 资源占用与性能观察这类 Agent Skill 的资源占用要分成两个维度看宿主 Agent 的资源消耗、SVG 生成过程中的资源消耗。9.1 显存占用先明确一点Agent Skill 本身不是权重模型不占显存。如果你接的是云端 API本地只跑一个客户端脚本显存占用约等于 0。如果你接的是本地语言模型那么显存占用由那个 LLM 决定与 SVG 技能无关。上下文长度越长KV Cache 占用越高长 SVG 输出会明显增加显存压力。因此能跑大模型的机器更适合接这类技能瓶颈在上下文窗口不在 SVG 渲染。9.2 CPU 与内存渲染 SVG 的 CPU 开销很小但模型生成阶段如果有本地脚本做 SVG 树解析内存取决于 SVG 文件节点数量。几百个元素的 SVG 文件解析起来通常是瞬时的。数千个节点时会慢一些可以用defusedxml做安全解析顺便避免恶意实体扩展问题。9.3 性能瓶颈Token 与上下文真正要盯的是 Token 消耗。SVG 是冗长格式一个复杂架构图的 SVG 代码可能有 3000 到 8000 token。批量生成时API 费用和响应时间都会显著上升。优化建议让技能优先复用模板不要每次从零画。公共图标抽成defs用use引用代码量可以降一半。限制viewBox尺寸避免模型生成大画布但没内容。大批量任务设置队列不要一次性并发太多避免触发模型限流。9.4 如何观察性能服务端日志里记录每个请求的耗时。本地用nvidia-smi观察显存变化。生成结束后用time命令测量耗时。对输出 SVG 做行数统计行数异常说明模型可能陷入了冗余循环。wc -l output.svg10. 常见问题与排查方法问题现象可能原因排查方式解决方案Agent 无法识别技能技能目录层级错误检查目录是否多套了一层技能名是否匹配调整为skills/svg-diagram/SKILL.md返回的不是 SVG模型没有遵循技能约束查看提示中是否包含“必须输出标准 SVG”要求强化技能描述增加负例SVG 打开后空白viewBox或坐标异常用浏览器开发者工具检查元素限制画布范围增加默认背景元素重叠严重模型空间计算能力不足跑校验脚本定位重叠预先定义网格模板禁止随机坐标中文乱码/方块字体缺失或编码问题检查 SVG 中点击文本使用系统字体显式指定font-family避免特殊字符导出 PNG 失败缺少转换工具或外部资源检查是否安装rsvg-convert或 Inkscape替换为 Chrome headless 截图API 超时模型生成太慢或上下文太长看日志中的耗时缩短提示增加 timeout分批重试批量任务生成一半卡住部分请求触发了模型限流查看返回状态码增加退避重试降低并发Windows 资源管理器不显示 SVG 缩略图系统本身对 SVG 缩略图支持较弱用浏览器或专业看图工具打开转出 PNG 作为预览图SVG 文件内嵌了不信任脚本模型在输出中加了大地址的代码用defusedxml解析并移除script生产环境强制净化后再上线11. 最佳实践与使用建议11.1 先固化模板再放开自由度在正式用之前先在技能包 assets 目录里放 5 到 10 个标准 SVG 模板流程图、架构图、时序图、状态机、数据库关系图。让 Agent 优先套模板而不是每次从空白画布开始。模板的自由度低了质量稳定度会明显提高。11.2 给技能加“输出校验”步骤不要信 Agent 一次性生成的 SVG 一定合法。在技能流程里加一个强制步骤“生成完 SVG 后必须检查是否以/svg结尾检查所有rect的width、height是否大于 0。”这种人类看起来平平无奇的检查能拦住大量低级错误。11.3 做好输出目录规约一个标准输出目录结构可以长这样output/ ├── svg/ ├── png/ ├── templates/ └── logs/Agent 只允许写output/svg下的文件其他目录由宿主程序控制避免文件路径混乱。11.4 接入 CI 或文档流程如果你在写技术文档可以把 SVG-diagram 接进构建脚本从diagrams/requests/*.txt生成 SVG再用脚本转成 PNG最后在文档中引用。这样文档配图就是可追踪、可版本管理的。11.5 合规与安全生成架构图时绘制前先脱敏内部 IP、域名、真实服务名。如果 SVG 用于公开网站务必过滤script和外部实体。不要用包含他人版权图标库的技能包做商业用途除非许可证允许。对批量生成内容保留人审环节。12. 总结与下一步SVG-diagram 这个方向真正值得尝试的不是某个惊艳的绘图效果而是它把 Agent 画图的“不确定性”往“工程化”推了一步。用手放坐标 Agent Skill 的组合让图表生成变得更可控、可校验、可复用。建议的第一步验证动作安装技能后只做一个小测试——让它画一个包含 5 个节点的流程图然后检查 SVG 是否合法、节点是否不重叠。这一步能跑通再考虑接入批量任务。最容易踩的坑是模型生成 SVG 后没有校验就当成成品使用。这不是项目的问题而是所有结构化输出类 Agent 任务共通的工程问题。一定要在技能流程里嵌入校验和重试逻辑。后续可以扩展的方向包括接入 MCP 让 Agent 直接写文件到工作流目录、把常见图形抽成更细粒度的组件库、或者增加 PNG/WEBP 导出管线。那样的话这个技能从“Agent 会画图”就变成了“Agent 可以直接给交付物配图”离真正可落地的自动化更近一步。