AI 画图这事大家应该都体验过让大模型画个流程图看着挺像那么回事真要拿去用不是字体大小忽大忽小就是连线跟蜘蛛网似的想改一个框的位置整个布局直接崩掉。说到底AI 生成的图大多只是“好看”压根儿没想过你要拿它去编辑、去交付、去进团队协作流程。这个项目 diagram-design 要解决的就是这个问题——给 AI 的画图能力套上一套“编辑级”的规范让它输出的东西不是一张静态图片而是一份能真正进入编辑器的工程文件。这篇文章我会把整套规范的设计思路、落地步骤、关键细节和踩坑经验完整拆开讲一遍。适合正在做 AI 应用开发、AI Agent 工具链或者被 AI 图表质量折磨过的产品经理、前端工程师和提示词工程师参考。1. 整体设计思路为什么 AI 画图需要一套“编辑级”规范1.1 AI 绘图输出的真实痛点不是不美是没法改先说一个很现实的问题。我们平时让 AI 画图最常见的输出形式是 Mermaid 语法、PlantUML 语法或者直接生成 SVG。Mermaid 这类文本描述型方案好处是生成成本低AI 很擅长写这种结构化的文本。但问题恰恰出在“文本”二字上——它只描述了图的结构和样式没有描述图的“编辑状态”。你在 Mermaid 渲染出来的图里拖拽一个节点位置改完想再倒回 Mermaid 代码基本不可能。这就是只读图和可编辑图之间最大的鸿沟。SVG 的情况稍微好一点因为它本身就是给编辑器用的格式坐标、路径、变换矩阵都是显式存在的。但 AI 直接生成 SVG 又会引入另一个麻烦坐标计算全靠模型“瞎猜”AI 对空间布局的感知能力很弱生成的节点经常重叠、连线穿模视觉上惨不忍睹。更关键的是AI 生成的 SVG 里到处都是内联样式和绝对定位没有分层、没有命名、没有组件化思维交给前端同事维护的时候人家只想骂人。所以核心矛盾就出来了AI 擅长处理“语义结构”不擅长处理“精确空间坐标”。如果直接让 AI 去画像素级精确的图等于让一个文科生去做工程制图必然翻车。diagram-design 的出发点就是把这个矛盾拆开——让 AI 负责它擅长的语义组织把精确布局和样式交给一套规范化的模板和规则来处理。1.2 编辑级图表的判断标准能拖、能改、能交接什么样的图才配叫“编辑级”我自己在项目里定了三条硬指标拿这三条去卡任何 AI 生成结果立刻就能分辨能不能用。第一元素必须可选中、可拖拽。不管用什么格式输出最终进到编辑器里每个节点、连线、标签都应该是一个独立的对象有自己独立的边界框和命理坐标而不是把整张图拍扁成一张背景图。第二样式必须可批量控制。编辑级图表一定有样式令牌的概念比如颜色、线宽、字体大小、圆角弧度都应该能在全局改一处就全部生效。这就意味着图里不能出现一千个写死的颜色值而应该引用统一的令牌。第三文件格式必须可逆。也就是说图不仅能打开还能导出回源文件格式再重新编辑。如果导出后再导入格式就乱了那编辑级就是空话。第四必须携带业务语义。纯装饰的图不是规范的目标图里的节点应该关联到真实业务对象比如系统模块、数据实体、流程步骤带着 ID、类型、描述这些元信息让下游工具能解析、能联动。这里我用的格式方案是 XML 文件格式类似 draw.io 这种老牌绘图工具内嵌的格式。为什么选它因为它本身就是一种“半文本化、半结构化”的存储格式坐标、样式、连线关系都显式写在 XML 节点里AI 生成这种格式比直接生成像素 SVG 要稳定得多。同时 XML 有天然的树形结构节点之间的关系可以通过父级和子级表达非常适合描述图和图之间的嵌套关系比如泳道图里的分组、容器图里的子节点。选 XML 还有一个隐蔽但很重要的原因主流绘图工具已经有成熟的 XML 解析引擎。团队里如果有人用 draw.io把 XML 拖进去就能秒开不需要我们从头造一个渲染器。这样规范落地的时候工具链的迁移成本几乎为零。1.3 分层架构语义层、规范层、渲染层各管一段基于上面的痛点分析我把 diagram-design 拆成分层的三段架构每一层只干一件事这样 AI 的压力会小很多规范的维护也会清晰很多。语义层是一个纯业务概念的东西它规定一张图里可以有哪些“东西”。比如流程图的语义层包含开始事件、结束事件、任务节点、判断节点、泳道架构图的语义层包含服务、数据库、消息队列、负载均衡。不同场景的图有各自的语义类型。这一层其实就是“领域模型”AI 要做的是把用户的需求映射到这些语义类型上而不是直接去算坐标。这是 AI 唯一需要动脑子的地方。规范层管的是“长什么样”。它会规定每种语义类型对应的默认尺寸、默认颜色、默认图标、默认文本格式。比如“数据库”节点在架构图里必须用圆柱体的形状颜色取自品牌色板里的蓝色圆角 4px线宽 1.5px。所有节点不允许自定义颜色值必须引用调色板里的令牌。这一层用一套配置化的 JSON 来描述AI 生成图的时候只需要按配置填参数。渲染层管的是“画在哪”。它负责把语义层和规范层的信息组合起来计算坐标、布局、连线路由最后输出可编辑的 XML 文件。这一层其实不应该让 AI 来做因为布局计算是确定性的算法活交给代码库去完成更靠谱。所以我在设计里引入了“后处理器”的概念AI 只输出一个结构化的 JSON描述节点和连线的语义一个本地脚本把这套 JSON 翻译成 XML 并做自动布局。这样 AI 不需要具备任何空间想象力也不会再犯坐标重叠的错误。这套分层的设计也直接决定了后面所有提示词怎么写。提示词里不会出现“把节点放在左上角”“两个框保持 50px 间距”这种话而是要求模型输出“节点 A 是类型 load_balancer节点 B 是类型 service_aA 指向 B”。剩下的交给后处理器。2. 核心规范细节给节点、连线、样式建立“行为准则”2.1 元素类型总览把图的零件标准化没有一套标准零件库图纸就画不出统一的风格。diagram-design 里我定义了四类基础元素所有图都从这四类元素里组合出来。第一类是节点这是图的“主体”表示一个实体或一个操作步骤。每种节点必须有唯一的 type 标识、显示名称、所属分组、业务标签。比如在系统架构图里节点类型有 service、database、queue、gateway在流程图中节点类型有 start、end、task、decision、delay。类型决定形状、颜色、图标。第二类是连线它描述节点之间的逻辑关系。连线必须有 source 和 target指向两个节点的 ID同时还要有 direction单向、双向、label关系描述、lineStyle实线、虚线、点线。比如“服务 A 调用了数据库”就是一条 directionone_way、labelread/write、lineStylesolid 的连线。第三类是容器它是节点的节点用来表达分组、边界和泳道。容器可以嵌套容器容器内的节点会继承容器的色调和边框风格。用在架构图里表现“服务网格”用在流程图里表现“责任人分区”都非常合适。容器是让图看起来结构化的重要工具但它也是 AI 最容易乱用的一类元素AI 经常把普通分组和容器搞混导致嵌套层级混乱。第四类是文本标注用来补充图上画不出来的信息比如节点描述、版本号、备注、链路说明等。文本标注不是独立的节点它必须挂载到某个节点或连线上否则会出现悬空的文字框这个在编辑过程中特别讨厌。这套元素体系的好处在于它把无限的画图可能性压缩成了一组有限且明确的选项。AI 不需要自己发明画法只需要在这个体系内选择、组合。相当于给了模型一套约束条件它的输出空间变小了出错概率自然就降下来了。2.2 样式令牌颜色、字体、线宽全部走统一配置编辑级图表里最忌讳的就是“每个节点长得都不一样”。高频出现的样式必须抽成令牌放到集中的配置文件里图里不允许出现裸的颜色值或像素值。我维护的规范里这套令牌大概分四组。色彩令牌的核心是主色、辅助色、语义色。主色通常就是团队或产品的品牌色用在标题、主要节点和容器边框上辅助色是灰色系用来做背景、网格线和次要内容语义色则和业务含义绑定比如成功绿、警告黄、错误红用在流程状态和告警链路上。每个节点只允许从这三个色系中取值不允许自创颜色。然后是字体令牌包括标题字体、正文字体、等宽字体字号也要分大、中、小三个档位。AI 很容易犯的毛病是给每个节点单独定义 font-size结果一个图里出现五六种字号。规范里明确标题节点用大字号普通节点用中字号备注和技术说明用小字号就这么简单。线条令牌管的是线宽和线型主连接线用 2px 实线次要关系用 1.5px 虚线弱关联用 1px 点线。圆角和间距令牌管理视觉节奏普通圆角 4px容器圆角 8px节点间距最低 20px容器内边距最低 32px。这些参数在配置里集中定义渲染层读取这些令牌再生成 XML这样任何一张图拿到手样式都是同一套衣服不会出现东拼西凑的感觉。2.3 可编辑属性坐标、端口、锚点是编辑体验的命根子规范里我特别强调了三个容易被忽视的“可编辑属性”。第一是中心坐标每个节点都必须要有一个明确的中心点坐标。XML 里通常直接存坐标位置后处理器在做自动布局时会给每个节点赋予一个合理的坐标之后用户在编辑器里拖拽任意节点也只改这个坐标值其他元素不受影响。第二是连接端口。节点和节点之间连线严谨的做法不是直接连到节点边界上而是连到节点预设的端口上比如顶部端口、底部端口、左右端口。连线连到端口拖动节点时连线才会跟着断开点优雅地移动而不是线头钉死在图上。AI 生成的图如果端口信息是缺失的进了编辑器一拖节点线就变成飞线体验直接崩。所以规范里对支持连接关系的节点必须带 out 和 in 两个方向的端口定义。第三是锚点。连线的拐弯路径需要锚点来定义也就是线从哪里进、从哪里出、中间经过哪些折点。规范要求生成连线时至少要给出 sourceAnchor 和 targetAnchor 两个锚点引用中间路由路径可以让编辑器自动计算也可以预先给出一条默认路径。这一点直接决定了用户对“这张图能不能编辑”的直观感受锚点信息完整的图拖起来非常跟手缺失的图一动就乱。这些属性在 XML 中都是显式的字段但 AI 直接输出它们很容易出错所以我的方案里AI 根本不直接碰这些字段它们全由后处理脚本在渲染阶段自动填充。规范本身只要求 AI 在语义 JSON 里提供节点和连线的逻辑关系坐标、端口、锚点这些全是程序生成的。这也是我最想分享的一条经验可编辑性不是靠提示词“描述”出来的而是靠代码“生成”出来的。提示词能约束的是逻辑结构物理编辑属性必须由确定性代码来保证。3. 实操落地结合提示词工程和后处理器跑通全流程3.1 领域描述文件AI 理解的“词汇表”要落地这套规范第一步是做一本“词汇表”专业点说就是领域描述文件。它跟 AI 提示词是两个层面提示词是教 AI 如何输出的“操作手册”领域描述文件是告诉 AI 它要画的东西“由哪些零件组成”的“零部件目录”。举个例子如果团队做的是系统架构图领域描述文件里就应该包含这些内容节点类型有哪些每种类型的中文名、英文标识、语义说明、允许连接的节点类型容器类型有哪些嵌套规则是什么关系类型有哪些比如依赖、调用、数据流向每种关系用什么线型和颜色。我的做法是用 JSON 定义一份 schema包含nodeTypes、edgeTypes、containerTypes三个数组每个数组里的每一项包含type、label、description、connectableTo这些字段。然后把这套 schema 作为提示词的一部分喂给 AI要求它严格按照 schema 中的类型来组织输出。实测下来AI 的“幻觉”发生频率能下降不少因为它不再需要猜测一个节点应该叫什么名、属于什么类型直接照抄词汇表就行。这份领域描述文件必须人工维护而且维护频率很高。每画一种新图或者业务新增一种节点都要回这里来补充。但它的定力很好代码可以做完自动校验AI 生成的 JSON 里如果出现了 schema 之外的 type直接判为非法不进入渲染流程。3.2 提示词模板让模型输出标准 JSON 而不是画图这里分享一套我调试过的提示词模板核心思路是“剥离物理层保留语义层”。给 AI 的原话大致是你是架构制图助手只能输出符合特定 schema 的 JSON 数据。你的任务是根据用户自然语言描述抽取节点、容器、连线关系。禁止输出任何 XML、SVG、HTML 或自然语言解释只输出 JSON。节点必须引用【节点类型清单】中的类型不得自行发明。连线必须引用连线的 source 和 target 节点的 ID且 ID 必须唯一、可读比如node_gateway_01。如果用户描述中提到的对象不在类型清单里必须标记为unknown_type由后续人工确认不能擅自归类。这套提示词里没有任何一句要求模型去计算坐标或者调整布局它只需要做“翻译”把用户需求翻译成语义 JSON。模型的压力小了输出质量就会稳定。输出示例大概是这样的{ diagramName: 订单服务架构, nodes: [ { id: node_gateway_01, type: gateway, name: 统一入口网关, description: 处理所有客户端请求的流量入口 }, { id: node_service_order, type: service, name: 订单服务, description: 核心业务逻辑负责订单状态流转 }, { id: node_db_order, type: database, name: 订单库, description: MySQL 8.0存储订单主数据和状态 } ], edges: [ { id: edge_01, source: node_gateway_01, target: node_service_order, label: HTTP, relation: 调用 }, { id: edge_02, source: node_service_order, target: node_db_order, label: SQL, relation: 读写 } ] }你会发现模型只输出了纯业务语义没有任何像素和坐标。这一步是我整个规范里最关键的平衡点给了规范足够的约束力又没让 AI 去做它不擅长的事。3.3 后处理器用代码把 JSON 变成可编辑 XMLAI 输出的 JSON 只是中间态要让图真正“可编辑”必须交给后处理器转成 XML 文件。这个后处理器承担三个任务自动布局、样式注入、产物生成。自动布局我用的是分层布局算法。算法先按连线关系把节点排成分层比如入口网关在第一层服务在第二层数据库在第三层。每层节点按数量均分宽度再给每个节点算出一个确定性的中心坐标。这个布局结果不会完美到让人惊艳但胜在稳定、不重叠、可预期而且每次跑出来的结果是一致的不会出现同一次输出两种布局的情况。对于更复杂的图可以换成力导向布局或正交布局但别让 AI 参与布局决策。样式注入就是从令牌配置里读取每个节点类型对应的颜色、尺寸、形状参数生成 XML 里每个 cell 的 style 属性。这里要注意XML 里的 style 属性是一串分号分隔的 keyvalue 列表每种图形形状还要加对应的几何参数。比如 draw.io 格式里矩形节点要写rounded1;arcSize8;fillColor#E8F0FE;strokeColor#4285F4;数据库节点要写shapecylinder3;分组容器要写container1;。产物生成环节把布局坐标、端口信息、锚点信息、样式信息、业务元数据合并按 XML 结构拼接成完整文件。每个业务节点除了视觉样式还要带上额外的元数据字段比如data.nodeType、data.businessId、data.description这样这张图流转到需求文档、技术设计文档里下游系统可以直接解析这些字段做自动化处理图不再是一张“死图”而是带语义的活数据。后处理器的脚本量不大核心逻辑几百行就能搞定但它承担了整个规范体系里最“硬”的部分。AI 负责软后处理负责硬两者结合才有一份能真正编辑的图。3.4 渲染与迭代从“能看”到“能用”的反复打磨后处理器输出 XML 之后直接拖进 draw.io 验证一下。我测试的流程是先看节点是否重叠、连线路由是否合理、能否正常拖动节点不影响其他元素、改样式是否全图联动。如果发现问题回后处理器改布局参数或样式映射而不是去改提示词。因为这类物理层面的问题改提示词是隔靴搔痒治不了本。我跑第一个完整案例的时候生成的图能看但拖动节点时连线拐点不跟手检查发现是连线锚点信息缺失导致。后来我在后处理器里给每种连线类型增加了默认的 sourceAnchor 和 targetAnchor 定义连线才变“听话”。这个迭代过程需要循环几次但每一次都在往前推最终效果是稳定产出可以直接交付编辑的图表文件整体流程跑通后后续生成的新图基本都能直接复用不用再频繁调整。4. 常见问题与排查技巧AI 生成图表项目的“避坑手册”4.1 常见问题速查表症状根本原因解决办法节点大面积重叠AI 或早期版本直接输出坐标布局缺乏确定性算法启用后处理器自动布局禁止 AI 参与坐标计算拖动节点时连线乱飞连线缺少端口和锚点信息在后处理器中为所有连线补充默认锚点节点预置注入端口颜色五花八门、风格不统一节点样式值直接写在提示词里模型自由发挥引入样式令牌配置AI 只输出类型样式由后处理映射XML 打开报错或渲染异常关键属性缺失shape 类型不存在编写校验脚本对每个节点类型强制校验必填属性和合法值图太复杂时布局路线交叉严重单一布局算法无法应对高复杂度图分层布局失败时自动切换力导向布局并开放手动调整入口业务语义丢失节点无法关联真实系统元数据字段未写入产物在 XML 层增加 data 字段强制携带业务 ID、节点类型、描述信息这张表基本覆盖了我实际项目中遇到的所有高频问题。如果你也一样在构建 AI 图表功能可以对照检查。4.2 排查实录一次连线乱飞的问题定位说一个实际排过的坑帮大家理解编辑级图表对锚点的依赖到底有多大。当时我在测试一个支付链路架构图图里有 15 个节点、20 条连线自动布局看着很好节点整整齐齐。结果把 XML 拖进编辑器里拖动任意一个节点连接到它的线不是甩到图外就是拐成一个极其诡异的直角效果惨不忍睹。第一反应以为是布局问题调了半天布局参数一点用没有。后来打开 XML 源码逐条检查 edge 单元格才发现所有连线只有source和target两个节点 ID根本没有端口概念。编辑器不知道线从节点的哪一侧出发、哪一侧进入只能随手选择一个坐标拖动节点时这个坐标不会跟着更新线就“飞”了。修复办法是在后端处理时给每一条连线补充端口和锚点定义。比如一个订单服务节点的右侧出线sourceAnchor 固定指向节点右侧的点targetAnchor 指向对端节点左侧。改完之后再拖动节点连线就稳稳地跟着走。这次排查让我彻底意识到可编辑性的根基不在布局算法而在这些不起眼的端口和锚点属性上它们才是编辑体验的底层基础设施。4.3 团队和流程层面规范落地最大的阻力往往不在技术最后说说技术和代码之外的东西。给 AI 装规范技术上的难点其实都有解真正难的是团队里每个成员是否愿意遵守规范。我踩过最深的坑是规范文件建好了提示词模板也写好了但组里的同事用的时候不按套路出牌有人让 AI 直接输出 SVG有人从旧流程里复制粘贴旧格式的代码结果整个工作流又回到混乱状态。后来我做了两件事情况才好转。第一件事是把规范做成“代码库”而不是“文档”。一切规范内容都收进一个 Git 仓库包含 schema 文件、令牌配置、后处理器脚本、示例模板。任何人要接入新图型不是去读文档而是改这个仓库里的代码。规范本身就是软件有版本、有测试、有 CI 校验这样它就不是一堆“建议”而是一套“约束”。第二件事是给流程加了强制网关。所有 AI 生成的图表产物必须先经过后处理器和校验器不合格直接打回。用的时候根本不需要讨论“这张图合不合规范”因为不合规范的产物根本走不到交付那一步。这个设计省掉了大量无意义的沟通成本也逼着团队所有人只能从规范入口进入。我个人的体会是编辑级图表设计规范这件事本质是把“AI 的创造力”和“工程的确定性”做一次分工。AI 负责从模糊需求里抽取出清晰的语义结构代码负责把语义结构翻译成像素级精准、可编辑、可交接的工程产物。这套思路放之四海都能用换任何图型、换任何编辑器格式原理都一样。最后再分享一个小技巧如果你也在做类似的事先把“AI 输出什么中间格式”定死比先定“编辑器输出什么成品格式”更重要中间格式一稳整个链路就稳了一大半。