文章目录一、为什么技术图一直是工程团队的隐形债务二、项目概览一个能同时跑在 Codex 和 Claude Code 上的 Agent Skill三、设计支柱之一可执行的风格系统四、设计支柱之二语义化的形状与箭头词汇表五、设计支柱之三Diagram IR 与结构化校验六、设计支柱之四几何安全的路由与组合质量契约七、设计支柱之五Loop Engineering——有界的验证反馈闭环八、语义动效从静态 SVG 到经过验证的 GIF九、上手安装、依赖与 CLI推荐安装方式可编辑的 Git 检出一份检出两端共享渲染器依赖统一 CLI十、实战按场景写提示词AI / Agent 系统基础设施与云工程评审场景的提示词指纹风格选择速查产品图标覆盖十一、与 Mermaid、draw.io 的定位差异十二、排错手册十三、可迁移的方法论十四、边界与适用范围十五、结语一句话概括它不是又一个画图工具而是把「图好不好看」这件主观的事改写成了一组可执行、可校验、可回归的工程契约。一、为什么技术图一直是工程团队的隐形债务写过设计文档的人都清楚一件事文字部分往往一两个小时就能交付卡住进度的经常是那张架构图。真实的困境大致分三类。第一类是工具与表达之间的落差。Mermaid 的语法足够轻写在 Markdown 里随手可渲染但它的布局引擎是自动的你几乎无法精确控制一条边绕开哪个节点一旦节点数超过十几个连线就开始打结。draw.io 反过来控制力极强但每一个像素都要手工拖拽改一次命名要点开七八个框评审会上临时加一个服务就意味着重新排版半小时。第二类是一致性问题。同一个系统架构师画出来是蓝底白线后端同学画出来是彩色圆角矩形SRE 画出来又是另一套记号。数据库有时是圆柱体有时是方框异步调用有时用虚线有时用不同颜色的实线。读者每看一张新图都要重新学习一次视觉约定。图越多认知负担越重。第三类也是最容易被忽略的一类图没有验收标准。代码有单元测试、有 lint、有 CI图只有「我看着还行」。箭头穿过了组件内部、标签压在连线上、图例盖住了内容、导出 PNG 底部被裁掉一截——这些问题往往到了 PPT 投屏那一刻才被发现。fireworks-tech-graph值得拆开来看的原因正在于它对第三类问题给出了一个相当彻底的回答把图当作构建产物配一条带校验门禁的流水线。二、项目概览一个能同时跑在 Codex 和 Claude Code 上的 Agent Skill这个项目由「一支烟花 AI 社区」维护MIT 协议目前 GitHub 上约 9.6k star、800 fork主体由 Python、JavaScript、HTML 和 Shell 构成。它的形态是Agent Skill——不是 CLI 工具也不是 SaaS而是一份可以被编码智能体加载的能力包。同一份代码在 Codex 与 Claude Code 中原样运行SKILL.md是共享入口捆绑资源全部使用相对路径agents/openai.yaml提供 Codex 专用的 UI 元数据Claude Code 会直接忽略这个文件。它的核心能力可以概括成一条链路自然语言描述 → 几何校验通过的 SVG → 1920px 高分辨率 PNG → 经过验证的 SVG-to-GIF 语义动效 → 可离线打开的交互式 HTML一个最小示例长这样用户生成一张 Mem0 记忆架构图暗色风格 → 技能分类Memory Architecture DiagramStyle 2 → 生成带泳道、圆柱体、语义箭头的 SVG → 导出 1920px PNG → 返回mem0-architecture.svg / mem0-architecture.png当前版本提供12 种视觉风格11 种由生成器驱动 1 种 AI 自主排版、14 种图类型覆盖完整 UML 体系以及一批 AI/Agent 领域的内建图式。三、设计支柱之一可执行的风格系统多数「多主题」画图工具的做法是写一份风格指南然后指望使用者遵守。这种约定在人类手里就已经容易走样交给大模型更是必然漂移。这里的处理方式不同——风格被编码进生成器而不是只写在 Markdown 里。每个风格在references/下有独立的参考文件规定精确的色值 token 与 SVG 图案生成阶段直接消费这些定义。12 种风格及其定位#名称背景字体适用场景1Flat Icon默认#ffffffHelvetica博客、幻灯片、文档2Dark Terminal#0f0f1aSF Mono / Fira CodeGitHub README、开发者文章3Blueprint#0a1628Courier New架构文档、工程蓝图4Notion Clean#ffffffsystem-uiNotion、Confluence、Wiki5Glassmorphism#0d1117渐变Inter产品站、主题演讲6Claude Official#f8f6f3system-uiAnthropic 风格、暖色调7OpenAI Official#ffffffsystem-uiOpenAI 风格、干净现代8Dark LuxuryAI 排版#0a0a0aGeorgia system-ui高端文档、README 头图、大会 slide9C4 Review Canvas#f7f2e8Avenir / system-uiC4 评审、ADR、职责界定10Cloud Fabric#edf5fbInter / system-ui多区域部署、VPC/网络归属11Event Transit#fbf7eeAvenir / system-uiKafka 事件流、消费组、DLQ12Ops Pulse#07111fSF Mono / Fira CodeSRE 复盘、黄金信号、关键链路真正有意思的是9 到 12 这四种「工程优先」风格。它们不只提供配色还附带领域语义契约Style 9C4 评审必须声明单一抽象层级标注职责、技术选型、评审状态与关系协议。混层会被判失败。Style 10云部署必须表达全局入口、Region/VPC 归属、部署模式与跨边界机制。Style 11事件流主题是细轨道处理器是编号站点还需声明汇合点、消费组、死信队列与状态投影。Style 12可靠性必须给出一个观测窗口、每个服务的四项黄金信号、编号的关键跳数、遥测导出路径以及一条被关联的 trace。这些字段在布局之前就会被fireworks.py validate检查缺失或自相矛盾的工程事实直接 fail closed。换句话说你没法用它画出一张「看起来像 C4 但实际上把容器和组件混在一层」的图——契约不允许。这一步的价值超出了美观范畴。它把「画图」从表达行为变成了建模行为你被迫先把系统事实说清楚才能拿到图。四、设计支柱之二语义化的形状与箭头词汇表一致性靠的不是自觉而是词汇表。形状与线条被赋予固定含义跨风格保持稳定。形状部分概念形状用户 / 人圆形 身体LLM / 模型双边框圆角矩形带 ⚡Agent / 编排器六边形短期记忆虚线边框圆角矩形长期记忆实心圆柱向量库带内环的圆柱图数据库三圆簇工具 / 函数带 ⚙ 的矩形API / 网关单边框六边形队列 / 流横向管道文档 / 文件折角矩形浏览器 / UI带三点标题栏的矩形判定菱形外部服务虚线边框矩形这里的记号选择是有讲究的短暂用虚线、持久用实体是一条几乎不需要图例就能被读者内化的规则向量库在圆柱里加内环与普通数据库形成最小差异但足够可辨的区分。箭头部分把「颜色 线型」组合成语义编码流类型颜色线宽虚线含义主数据流蓝#2563eb2px 实线无主请求/响应路径控制 / 触发橙#ea580c1.5px 实线无A 触发 B记忆读绿#0596691.5px 实线无从存储检索记忆写绿#0596691.5px5,3写入/落库异步 / 事件灰#6b72801.5px4,2非阻塞嵌入 / 变换紫#7c3aed1px 实线无数据变换反馈 / 循环紫#7c3aed1.5px 曲线无迭代推理注意「记忆读」和「记忆写」共用绿色只靠虚线区分——这是刻意的设计同一语义家族共享色相家族内部用线型细分。这样读者的第一层判断这是不是记忆操作成本极低第二层判断读还是写再看线型。还有一条硬规则只要用到两种以上箭头类型必须出图例。五、设计支柱之三Diagram IR 与结构化校验从自然语言直接生成 SVG 字符串是最容易出问题的路径——模型可能写出未闭合标签、引用不存在的 marker、给出非有限的坐标。这个项目在中间插了一层版本化的图中间表示Diagram IR。scripts/diagram_ir.py负责把输入规范化到 schema v1历史遗留的 JSON 也会被归一。在这一层以下问题会在渲染之前被拦下重复 ID悬空引用边指向不存在的节点畸形的路径 waypoint非有限的几何数值NaN、Infinity通过 IR 之后还有一道结构化 SVG 校验validate_svg.py检查项包括 XML 结构、marker 完整性、语义节点、保留区域、标签、画布边界、边重叠与边交叉。生成器消费的结构字段是显式的containers容器分组、nodes[].kind节点语义类型、arrows[].flow流语义以及明确的端口锚点。还有几个高杠杆字段能在不 fork 整套风格的前提下做局部微调style_overrides微调标题对齐或调色板 tokencontainers[].header_prefix/header_text蓝图风格的编号段头例如01 // EDGEcontainers[].side_labelClaude 风格的左侧层级标签window_controls、meta_left、meta_center、meta_right终端/文档外框装饰blueprint_title_blockStyle 3 的工程标题栏把这层 IR 加进来的收益是结构性的模型的自由度被限制在「填字段」而不是「写 XML」可校验面积因此大幅增加。这是所有 LLM 生成结构化产物的通用经验——不要让模型直接产出最终格式让它产出可校验的中间表示。六、设计支柱之四几何安全的路由与组合质量契约图之所以难看八成不是配色问题而是连线问题。路由这块采用确定性正交布线精确 waypoint、独立端口、图例自动避让、标签强制留在画布内对无法避免的交叉使用经过验证的跨线桥bridge jump。更值得关注的是那份共享组合质量契约references/composition-quality-contract.md它给出的是可量化的预算零交叉、零桥跳 每条边最多 2 个折点 整图最多 8 个折点 节点间距 ≥ 40px 容器内边距 ≥ 20px 避免过短的正交线段 标签必须远离节点、路线与段头布局规则同样具体同层节点水平间距 80px层间垂直间距 120px画布外边距至少 40px节点边缘之间 60px坐标吸附到 8px 网格。序列图的画布高度直接给公式80 消息数 × 50。心智图的中心节点固定在cx480, cy280一级分支按360/N度均分。箭头标签有一条被标记为 CRITICAL 的规则很值得单独说偏移优先水平箭头的标签放在线上方 6–8px垂直箭头放在左右 8px绝不压线背景兜底只有当偏移后仍与其他元素冲突时才加背景矩形标签放在箭头中段不超过 3 个词多条箭头汇聚时错开 15–20px为什么是「偏移优先」而不是「一律加白底」因为白底色块会在深色风格里割裂背景在密集区域会遮挡相邻连线。先用空间解决问题实在不行才用遮挡解决——这个优先级顺序本身就是排版经验的沉淀。七、设计支柱之五Loop Engineering——有界的验证反馈闭环这是整个项目最具方法论价值的部分。首次渲染的结果被当作候选而不是自动定稿。完整链路如下Prompt → Diagram Contract → Semantic IR → Style Spec → Route Planner → SVG Build → Structural Validation → PNG Visual Readback → Targeted Revision → Verified SVG PNG背后是五条设计原则求证而非断言Evaluate, don’t assert——完成状态由校验器和渲染证据支撑而不是模型自己说「看起来没问题」。确定性检查优先——XML 结构、marker 完整性、路径几何、箭头与组件的碰撞、可渲染性全部先于视觉判断执行。感知校验其次——把导出的 PNG 读回来检查裁切、标签碰撞、层级关系、留白与走线质量。这些是语法检查看不见的东西。定向修正——每一轮只改被诊断出的标签、坐标、走线通道或间距然后重跑校验与渲染。有界收敛——视觉复核默认最多两轮定向修正杜绝无限自我编辑。最终状态是可观测的validation: passed visual_review: passed如果运行时没有读图能力它会明确报告visual_review: skipped (image reader unavailable)而不是含糊带过。不谎报视觉验证——这一条在 AI 工具里比听上去更稀有。视觉复核阶段的常见修正手法也被固化成了清单让箭头走盒子之间的空隙不穿过组件内部标签先偏移 6–8px不够再加背景矩形加宽行/列间距给同层箭头留出走线通道把重复的跨层箭头收敛成一条位于内容区外侧的「delegates down」总线把图例/注释移出箭头与标签的落点区域优先增大 viewBox而不是把元素压得更紧带滤镜阴影、模糊的元素若缺了一侧边框把它移离该侧画布边缘 ≥30px或者干脆去掉滤镜用颜色对比来区隔这套「有界闭环」的思路可以直接迁移到任何 AI 生成任务先做确定性校验再做感知校验每轮只改被诊断的部分并且给循环设上限。它同时解决了两个方向的失败——模型过早宣布成功以及模型陷入无休止的自我修改。八、语义动效从静态 SVG 到经过验证的 GIF动效在这里不是装饰而是受契约约束的语义表达。触发方式很直接说「生成 GIF」「制作 GIF」「让这张图动起来」「把刚才的 SVG 转成 GIF」或英文的 Generate a GIF / Animate this diagram。输入必须是已生成的语义 SVG且需满足 12 条已批准的动效契约之一。它不锁定源文件字节因此同一拓扑的标题与内容变体可以通过但角色/阶段/顺序覆盖、路线方向、必需颜色、几何形状一旦缺失或改变直接 fail closed。GIF 是唯一的动效媒介格式默认命令还会同时输出.motion.json作为验证报告。默认时间线参数是经过审批的固定值960px 宽、5.75 秒、20fps、115 个帧中心采样所有场景以「无连接线」开场第 1–36 帧路线按语义顺序依次绘入第 36–38 帧实时流淡入第 38–109 帧保持完整的稳态流动第 110–114 帧复位帧唯一性规则相当严格75 帧及以下的时间线要求全部唯一更长的时间线允许在全不透明区间内出现非相邻的重复栅格第 110 帧是唯一的边界例外——它的复位不透明度恰好等于 1.00这类证据被归类为intentional_reset_boundary_repeat第 111–114 帧必须全局互异。长时间线至少要有 75 个唯一栅格且禁止相邻重复。75 帧与 115 帧的兼容门禁分两级计数先比对二进制精确帧再比对解码后 RGBA 精确帧仅当合成器差异满足 AE ≤ 128、归一化 RMSE ≤ 0.001、每个差异分量不超过 2px 宽高、且差异全部落在边或节点边框上时才接受抗锯齿等价回退。DOM 与签名几何保持严格精确。除默认时间线外3.75s/75 帧与 2.75s/55 帧仍受支持。每种风格有各自的「活体签名」风格预设动效签名5agent-orchestration玻璃任务胶囊 协调器光晕6governed-runtime治理线程 策略印章7token-streamAPI 轨道 三格 token 列车8golden-circuit奢华电路轨 宝石游标9review-trace评审轨道 移动评审光标10cloud-flow区域人字纹 复制胶囊11event-transit事件列车 异常/投影车厢12ops-pulse心电/导出头 trace 揭示 瀑布扫描把动画参数精确到帧号和 RMSE 阈值看上去有些偏执。但换个角度看这正是「让动效可回归」的必要条件没有确定的帧时间线就没有办法在 CI 里判断一次改动有没有破坏视觉输出。九、上手安装、依赖与 CLI推荐安装方式必须使用嵌套的技能路径末尾的/skills/fireworks-tech-graph不能省略——当前版本的skillsCLI 在仓库根路径安装时只会选中根目录的SKILL.md。npx-yskills1.5.17add\yizhiyanhua-ai/fireworks-tech-graph/skills/fireworks-tech-graph\--agentcodex claude-code-g-y--copy这会在~/.agents/skills/fireworks-tech-graphCodex与~/.claude/skills/fireworks-tech-graphClaude Code各创建一份完整副本含脚本、schema、fixture、模板、测试、参考文件与元数据。可编辑的 Git 检出# Codexmkdir-p~/.agents/skillsgitclone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.agents/skills/fireworks-tech-graph# Claude Codemkdir-p~/.claude/skillsgitclone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.claude/skills/fireworks-tech-graph一份检出两端共享Claude Code 2.1.203 及以上版本可以用软链接共用同一份检出先把已存在的目标目录挪开mkdir-p~/.local/share/agent-skills ~/.agents/skills ~/.claude/skillsgitclone https://github.com/yizhiyanhua-ai/fireworks-tech-graph.git ~/.local/share/agent-skills/fireworks-tech-graphln-s~/.local/share/agent-skills/fireworks-tech-graph ~/.agents/skills/fireworks-tech-graphln-s~/.local/share/agent-skills/fireworks-tech-graph ~/.claude/skills/fireworks-tech-graph这样SKILL.md、references、scripts、templates 与后续更新在两个 agent 中始终一致。需要注意npm 是独立的分发渠道版本可能落后于 GitHub Release追新请用上面的 GitHub 嵌套路径。首次安装后重启 Codex 与 Claude Code 以完成发现之后SKILL.md的改动会被自动检测但改动捆绑脚本或参考文件后如果没生效需要再重启一次运行时。以上命令针对 macOS、Linux、WSL 与 Git Bash原生 Windows 请换成%USERPROFILE%\\.agents\\skills与%USERPROFILE%\\.claude\\skills。运行环境要求 Python 3.9可选的 Puppeteer 路径需要 Node.js 18。渲染器依赖# 推荐cairosvgCSS 支持最好python3-mpipinstallcairosvg# 备选rsvg-convert系统包可能丢失 CSS / foreignObjectbrewinstalllibrsvg# macOSsudoaptinstalllibrsvg2-bin# Ubuntu/Debian# 可选语义动效导出brewinstallffmpegforSKILL_ROOTin\$HOME/.agents/skills/fireworks-tech-graph\$HOME/.claude/skills/fireworks-tech-graphdo[-d$SKILL_ROOT]||continuenpminstall--prefix$SKILL_ROOT--ignore-scripts --no-save --package-lockfalse puppeteer-core25.3.0 python3$SKILL_ROOT/scripts/fireworks.pydoctordone三种渲染器的取舍渲染器质量安装成本何时使用cairosvg好一条 pip 命令默认选择平衡最佳rsvg-convert一般系统包无 Python 环境、简单扁平图puppeteer最佳Node ChromiumD3、Mermaid 或像素级精确输出注意npm install要装在每一份技能副本旁边——渲染器有意不从调用方目录加载模块。统一 CLISKILL_ROOT${CLAUDE_SKILL_DIR:-$HOME/.agents/skills/fireworks-tech-graph}python3$SKILL_ROOT/scripts/fireworks.pydoctor python3$SKILL_ROOT/scripts/fireworks.pyvalidate architecture$SKILL_ROOT/fixtures/api-flow-style7.jsonpython3$SKILL_ROOT/scripts/fireworks.pyrender architecture$SKILL_ROOT/fixtures/api-flow-style7.jsondiagram.svg--reportlayout.json python3$SKILL_ROOT/scripts/fireworks.pycheck diagram.svg python3$SKILL_ROOT/scripts/fireworks.pyexport-html diagram.svg diagram.html--titleAgent Runtime Architecturepython3$SKILL_ROOT/scripts/fireworks.pyanimate diagram.svg diagram.gifexport-html产出的是单个离线文件内部会对 SVG 做净化处理附带平移/缩放/复位、明暗主题、SVG 源码复制以及 1×–4× 的 SVG/PNG/JPEG/WebP 下载。评审场景里这个格式相当好用——发一个文件出去对方双击就能放大看细节不需要装任何东西。十、实战按场景写提示词触发词很宽松中英文都能识别generate diagram / draw diagram / create chart / visualize architecture diagram / flowchart / sequence diagram / data flow 生成 GIF / 制作 GIF / 让这张图动起来 / 把刚才的 SVG 转成 GIF指定风格与输出路径也很自然画一张微服务架构图style 2暗色终端 画一张多智能体协作图 --style glassmorphism 生成 Mem0 架构图输出到 ~/Desktop/AI / Agent 系统内建的领域图式让这类图几乎不用解释细节RAG Pipeline → Query → Embed → VectorSearch → Retrieve → LLM → Response Agentic RAG → 增加 Agent 循环 工具使用 Agentic Search → Query → Planner → [Search/Calc/Code] → Synthesizer Mem0 Memory Layer → Input → Memory Manager → [VectorDB GraphDB] → Context Agent Memory Types → Sensory → Working → Episodic → Semantic → Procedural Multi-Agent → Orchestrator → [SubAgent×N] → Aggregator → Output Tool Call Flow → LLM → Tool Selector → Execution → Parser → LLM循环几个可直接复制的提示词用 Notion clean 风格做一张 Agentic RAG 与标准 RAG 的能力对比矩阵 覆盖检索策略、Agent 循环、工具使用生成 Mem0 记忆架构图包含向量库、图数据库、KV 存储和记忆管理器→ 带泳道的记忆架构Input → Memory Manager → 存储分层 → Retrieval画一张多智能体图Orchestrator 派发 3 个 SubAgent搜索/计算/代码执行结果聚合→ 六边形节点 工具层 结果聚合绘制 Agent 架构图时它会固定考虑五个概念层输入层用户、查询、触发、Agent 核心LLM、推理循环、规划器、记忆层短期上下文窗口、长期向量/图库、情景记忆、工具层工具调用、API、搜索、代码执行、输出层响应、动作、副作用。迭代推理用环形弧线表示不同记忆类型在视觉上强制区分。记忆架构图还有额外约束读路径与写路径必须用不同颜色分开画存储分层按 Working → Short-term → Long-term → External Store 排列记忆操作要标注成store()、retrieve()、forget()、consolidate()。基础设施与云画微服务架构Client → API Gateway → [User Service / Order Service / Payment Service] → PostgreSQL Redis生成数据管道图Kafka → Spark 处理 → 写入 S3 → Athena 查询画 Kubernetes 部署Ingress → Service → [Pod × 3] → ConfigMap PersistentVolume工程评审场景的提示词指纹对 9–12 这四种风格用下面的措辞能让路由器同时选中领域契约与视觉主题Style 9 · C4 评审板展示单一 C4 层级、职责、技术栈、评审状态与关系协议 Style 10 · 多区域部署图展示全局入口、Region/VPC 归属、中性云图标、部署模式与命名边界机制 Style 11 · 事件地铁图展示细主题轨道、编号处理器站点、声明的汇合点、消费组、DLQ 与状态投影 Style 12 · 可靠性脉搏展示单一观测窗口、每服务四项黄金信号、编号关键跳、遥测导出与一条关联 trace风格选择速查UML 类图/组件图/包图Style 1 或 4结构清晰易读序列图/时序图Style 2等宽字体有助于对齐状态机/活动图Style 3工程美学契合流程表达RAG / Agentic SearchStyle 2 或 5记忆架构Style 3强调分层存储多智能体Style 5磨砂卡片天然区隔 agent 边界内部文档Style 4博客Style 1GitHub READMEStyle 2演讲Style 5 或 6Anthropic 项目Style 6OpenAI 项目Style 7高端编辑向图Style 8产品图标覆盖内建 40 品牌色图标省去手动找 logo 的功夫AI/MLOpenAI、Anthropic/Claude、Google Gemini、Meta LLaMA、Mistral、Cohere、Groq、Hugging FaceAI 框架Mem0、LangChain、LlamaIndex、LangGraph、CrewAI、AutoGen、DSPy、Haystack向量库Pinecone、Weaviate、Qdrant、Chroma、Milvus、pgvector、Faiss数据库PostgreSQL、MySQL、MongoDB、Redis、Elasticsearch、Neo4j、Cassandra消息Kafka、RabbitMQ、NATS、Pulsar云AWS、GCP、Azure、Cloudflare、Vercel、Docker、Kubernetes可观测性Grafana、Prometheus、Datadog、LangSmith、Langfuse、Arize十一、与 Mermaid、draw.io 的定位差异Mermaiddraw.iofireworks-tech-graph自然语言输入✗✗✅AI/Agent 领域图式✗✗✅多视觉风格✗手动✅ 内建 12 种高分辨率 PNG 导出✗手动✅ 自动 1920px语义化箭头配色✗手动✅ 自动无需在线工具✅✗✅这张表容易被误读成「谁更强」实际上三者服务的是不同环节。Mermaid 的优势在于源码内联它和代码住在同一个仓库、同一份 Markdown 里改代码顺手改图diff 可读。做 README 里的小流程图它依然是最省事的选择。draw.io 的优势在于最终控制权需要逐像素调整的正式交付物人手拖拽仍然不可替代。fireworks-tech-graph瞄准的是中间那段最痛的距离——你脑子里有一个系统需要马上得到一张能直接放进文档、README 或幻灯片的成品图既不想学 DSL也不想在 GUI 里点半小时。它的输出是 SVG所以后续仍可以扔进 draw.io 或 Figma 做最后微调这条退路是通的。十二、排错手册常见问题基本集中在渲染环节症状原因处理PNG 全空白或全黑SVG 里有import url()cairosvg 和 rsvg-convert 都无法抓取外部字体去掉import改用系统字体栈PNG 没生成没装渲染器python3 -m pip install cairosvg或brew install librsvg/apt install librsvg2-binPNG 里边框或文字缺失用 rsvg-convert 渲染含 CSS 的 SVG换 cairosvgCSS 支持强得多图底部被裁掉viewBox 高度不够调大viewBox0 0 960 …的高度值文字溢出方框标签太长加text-anchormiddle或缩短标签第一条尤其值得记住在需要脚本化渲染的 SVG 里永远不要写import。浏览器能拿到字体无头渲染器拿不到结果就是一片空白。项目本身遵守了这条约束——所有输出使用纯内联 SVG不做外部字体请求因此在 cairosvg、rsvg-convert 和无头 Chrome 下都能干净渲染。十三、可迁移的方法论抛开画图这个具体场景这个项目沉淀了四条对任何 AI 工程都成立的经验。第一把风格与规范写进代码而不是写进文档。只写在 Markdown 里的规范人和模型都会漂移编码进生成器的规范才有约束力。这也是为什么「executable style system」这个说法比「style guide」更准确。第二让模型产出中间表示而不是最终格式。直接生成 SVG/HTML/SQL 这类最终产物校验面积极小出错难以定位。加一层带 schema 的 IR重复 ID、悬空引用、非有限数值这些问题就能在渲染前拦下来。第三验收必须分两级确定性检查在前感知检查在后。语法正确不等于视觉正确——箭头可以合法地穿过组件内部标签可以合法地压在生命线上。只有把导出的位图读回来检查才能捕获这一类缺陷。同样重要的是读不了图就诚实地报skipped而不是假装通过。第四反馈循环必须有界。默认最多两轮定向修正既避免过早收工也避免模型陷入无休止的自我编辑。每轮只改被诊断出的部分而不是整体重写——这一点同时保证了收敛速度与可解释性。第四条尤其容易被低估。很多 agent 工具的失败模式不是「做不好」而是「不知道什么时候算做完」。给出可观测的终态validation: passed/visual_review: passed加上明确的迭代上限这个问题就变成了工程问题而非玄学问题。十四、边界与适用范围讲清楚它不做什么同样重要。技能定义里明确排除了三类内容照片、栅格美术作品、以及定量数据图表。也就是说柱状图、折线图、散点图这类需要精确映射数值的可视化不在服务范围内——那是 matplotlib、ECharts 或 D3 的领域。它处理的是结构与关系的可视化不是数量的可视化。动效方面同样有硬边界只接受生成的语义 SVG 作为输入拒绝栅格动画输入与非 GIF 的动效输出同一风格的任意拓扑并不都被支持只有满足已批准契约的才通过。其他需要注意的现实约束依赖 Codex 或 Claude Code 这类支持 Agent Skill 的运行时不是独立可用的 CLI 工具链视觉复核依赖运行时的读图能力缺失时会降级对比矩阵最多 5 列超过就得拆成两张图流程图节点标签建议不超过 3 个词细节放子标签Style 8 是 AI 自主排版 静态回归 fixture与其余 11 种生成器驱动的风格机制不同十五、结语把这个项目仅仅看作「AI 画图工具」会错过它真正的价值。它真正做的事情是给一个长期被当作主观审美问题的领域装上了软件工程的那一整套基础设施schema、validator、契约、回归 fixture、CI 门禁、有界迭代、可观测终态。图不再是「画完了」而是「通过了」。这套思路的适用面远不止画图。任何 AI 生成结构化产物的场景——生成配置、生成 SQL、生成前端组件、生成测试用例——都面临同一个核心问题如何在没有人类逐项检查的前提下判断一次生成是否可交付。答案不是把模型换得更大而是把「可交付」拆解成一组机器能判定的条件然后让模型在这些条件的约束下迭代收敛。下一次你在设计文档前卡住半小时排版一张架构图时可以换个角度想想真正该被自动化的不是画线这个动作而是「这张图对不对」这个判断。项目地址github.com/yizhiyanhua-ai/fireworks-tech-graph · MIT 协议
)
