SAGE 如何通过提示词编辑 Draw.io 和 Mermaid 软件工程图？

SAGE 是一个浏览器端研究原型，用自然语言提示编辑 Draw.io 和 Mermaid 风格的软件工程图。它不会把模型输出直接当作最终图，而是先把图表规范化为可编辑图模型，再把提示解析为结构化编辑意图，绑定具体节点与边，执行确定性图操作，最后校验、修复并保存为可恢复版本。用户仍可在画布上手工移动、改名、增删和重连元素。

SAGE 解决什么问题

软件架构图会随系统变化，但传统维护方式要么依赖大量拖拽，要么直接修改 Draw.io XML 或 Mermaid 文本。纯 AI 图片编辑虽然操作自然，却可能破坏连接、样式和可编辑结构。

SAGE 的核心取舍是：让语言模型负责理解请求和消除歧义，让结构化应用逻辑负责修改图、序列化、校验、修复和版本恢复。

两种工作模式有什么区别

• Diagram 模式：导入或生成结构化图，使用提示词和画布编辑，保留节点、边、标签与几何。
• Image 模式：上传或生成位图，通过蒙版做局部图片修改，不具备显式图模型和连接校验。

需要长期维护、重新加载和版本控制的软件工程图，应优先使用 Diagram 模式。Image 模式更灵活，但重复修改容易产生布局漂移、字体变化和视觉退化。

提示词编辑的完整链路

1. 导入 Draw.io XML 或建立可编辑图表。
2. 系统规范化为 DiagramModel。
3. 用户输入自然语言修改要求。
4. 模型把请求转换为 ParsedEditIntent。
5. 分析阶段将抽象目标绑定到具体节点和边。
6. 生成图导向的操作步骤。
7. 执行改名、插入、重连、分组或布局操作。
8. 序列化并验证 Draw.io 兼容 XML。
9. 修复常见结构问题。
10. 验证成功后保存版本化工件。

这条链路把“模型觉得应该怎么改”和“系统实际接受什么改动”分开，降低自由文本直接重写整个 XML 的风险。

DiagramModel 包含哪些内容

SAGE 的内部图模型包含节点、边、标签、分组、几何、样式属性，以及边的源和目标引用。导入 Draw.io XML 时，解析器会：

• 提取图表单元。
• 区分顶点和连接器。
• 分配稳定标识。
• 统一几何坐标。
• 根据连接元数据重建图关系。
• 尽可能保留不影响编辑的展示细节。

画布不是最终事实来源，DiagramModel 才是可序列化、验证、恢复和导出的状态。

怎样写可执行的编辑提示

提示应包含操作、目标、位置、关系和限制。例如：

将“API Gateway”重命名为“Edge Router”，不要修改其他节点和连接。

在“Frontend”和“Backend”之间插入“Cache”。
把原连接改为 Frontend → Cache → Backend，保留原有样式。

在每个 Worker Node 分组中新增“Monitoring Agent”，
并分别连接到同一分组内的 kubelet。

“优化架构图”没有明确目标，系统难以判断应改标签、拓扑、布局还是样式。

ParsedEditIntent 如何约束模型

结构化编辑意图会记录操作类型、目标选择器、替换内容、插入约束和可选布局约束。例如“把 API Gateway 改成 Edge Router”会变成带标签选择器的 rename 操作；“在前端和后端之间增加缓存”会变成 insert-between 操作。

语言模型负责把自然语言解释成这些字段，但图的修改不会直接使用任意自由文本输出。

如何避免目标歧义

• 使用图中完整且唯一的标签。
• 同名节点要补充分组或邻接节点。
• 明确是节点、边还是分组。
• 插入时写清两个端点。
• 批量修改时说明范围和例外。

例如“修改数据库”可能匹配多个节点，应写成“将 Payment 分组内连接 API 的 PostgreSQL 节点改名为 Orders DB”。

执行计划包含哪些图操作

编辑分析会记录匹配目标、操作步骤、验证说明和执行路线。常见操作包括：

• 更新标签。
• 插入节点。
• 创建边。
• 重连边。
• 调整样式。
• 建立或修改分组。
• 调整布局。

执行前置条件会拒绝不存在的节点或无效边端点。这样的失败比生成一张看似正确但结构损坏的图更容易恢复。

Draw.io XML 如何校验和修复

转换后，系统检查 Draw.io 兼容 XML 的基本结构、必需根节点和图层单元，并检查带源目标的连接器引用。修复逻辑可处理：

• 空输出。
• 缺失 Draw.io 包装。
• 缺少根单元。
• 缺少图层单元。

校验失败时，不把结果记录为成功的结构化工件。

当前校验没有覆盖什么

论文明确说明，当前原型只部分覆盖更深层检查，包括：

• 穷尽的重复标识检测。
• 标签质量。
• 所有元素的有限几何值。
• 完整的分组成员关系。
• 领域特定架构语义。

因此“XML 能重新加载”只证明基本结构有效，不证明图的架构含义或视觉布局正确。

如何编辑 Mermaid 风格图

SAGE 面向 Draw.io 与 Mermaid 风格工程图，但论文最详细的结构化管线和校验描述集中在 Draw.io XML。处理 Mermaid 时仍应把文本图表视为节点和边构成的图，使用目标明确的操作，并在最终 Mermaid 渲染器中验证。

flowchart LR
    client[Client] --> gateway[API Gateway]
    gateway --> service[Backend]
    service --> db[(Database)]

若要插入缓存，可要求：

在 API Gateway 与 Backend 之间插入 Cache，
替换原连接，不要改变 Client 和 Database。

再检查最终文本是否变为 Gateway → Cache → Backend，而不是额外保留旧直连。

画布手工编辑能做什么

Diagram 模式支持选择节点和边、移动元素、编辑标签、增删组件、重连边、检查 XML 并导出。手工编辑适合：

• 修正局部布局。
• 调整一个标签。
• 重连模型匹配错误的边。
• 处理提示难以表达的精确位置。

提示词和画布修改都应生成新的会话步骤，便于审查和恢复。

版本化恢复如何工作

每次成功转换会创建版本化 session step，保存原提示、解析意图、编辑分析、规范化图模型、序列化 XML、渲染预览和可用的执行跟踪。

回退通过移动当前版本指针完成，不重写历史或删除旧工件。这使用户能查看系统理解了什么、执行了什么以及结果是否通过验证。

当前实现会在验证前创建版本步骤，更强的活动版本指针事务保护仍是未来工作。发生故障时仍要检查当前指针是否指向有效版本。

提示词编辑的推荐节奏

1. 导入并验证基线图。
2. 执行一次单目标修改。
3. 检查 ParsedEditIntent 和匹配目标。
4. 比较修改前后拓扑。
5. 重新加载导出 XML。
6. 确认无关元素未变化。
7. 再执行下一项修改。

不要在上一次操作尚未确认时连续提交多个提示。

Kubernetes 案例做了哪些修改

论文使用 Kubernetes 集群架构图作为案例，先根据参考图重建包含控制平面、两个工作节点、组件、Pod 区域和连接的结构化图，再执行三次提示编辑：

• 把 kube-api-server 重命名为 Kubernetes API Server。
• 在每个工作节点增加 Monitoring Agent，并连接到对应 kubelet。
• 在云提供商 API 与 cloud-controller-manager 之间插入 Authentication Layer，并重路由连接。

三个编辑都正确命中目标，保留无关结构并维持高层拓扑。

案例结果不能证明什么

重建结果只被评为部分正确，因为布局与参考图不同。评测主要是一个 Kubernetes 案例加单元测试，不是覆盖大量不同架构图的基准。

复杂提示可能产生拥挤、标签重叠、区域重叠，并且浏览器画布与 Draw.io 渲染略有差异。论文称这些通常可手工修正，但也说明布局校验仍需加强。

怎样验证一次编辑成功

• 结构有效：输出能序列化并重新加载。
• 编辑正确：目标变化已发生。
• 无关保留：其他节点、标签和区域未变化。
• 拓扑保持：关键连接仍存在。

只有结构有效且目标修改正确、无关结构不被破坏，才算成功。外观合理不足以证明可编辑工件有效。

Image 模式的蒙版编辑怎么用

Image 模式允许上传或生成旧位图，在局部区域绘制蒙版后执行语义编辑。它适合只改图片一小块，但没有 DiagramModel、连接模型或确定性验证。

1. 上传原图。
2. 精确绘制要修改的蒙版。
3. 描述局部变化。
4. 生成并检查边界区域。
5. 保存原图和每次结果。

重复编辑会累积视觉不一致、布局漂移和字体变化。需要结构正确性时应返回 Diagram 模式。

为什么结构化编辑比图片编辑更可靠

结构化模式有显式节点、边、分组和验证规则，可以确定性地重连、序列化和回退。图片模式只对像素工作，语义正确、连接保持和布局稳定依赖图像模型。

软件工程图应优先保留可编辑结构，位图只作为展示或无法获得源文件时的补充。

如何保护敏感架构信息

SAGE 会调用 OpenAI 和可选 Gemini 等模型服务，上传图片、提示和模型输出还会保存为本地工件。使用前应确认部署位置和提供商策略。

• 替换真实域名、IP 和集群名。
• 删除密钥、证书和连接字符串。
• 只上传需要修改的最小图。
• 检查会话工件与 SQLite 元数据的存储权限。
• 完成后清理不再需要的蒙版和上传图片。

常见问题如何排查

提示匹配到错误节点

使用完整标签、所属分组和相邻节点限定目标。检查解析意图后再执行。

插入节点后旧连接仍存在

明确要求“替换原连接”，并检查旧边是否删除、新边端点是否正确。

XML 可以加载但布局拥挤

结构校验不覆盖完整布局质量。手工移动节点、扩大分组或拆分图表。

Draw.io 中显示与浏览器不同

比较几何和样式属性，检查外部图标库、字体和渲染差异。以目标编辑器中的最终结果验收。

验证失败但出现了版本步骤

当前原型在验证前创建步骤。检查成功标记和当前版本指针，不要只看步骤是否存在。

重复图片编辑后字体变形

回到原图或较早版本，减少串行蒙版编辑；能结构化表达时改用 Diagram 模式。

Mermaid 结果无法渲染

在目标 Mermaid 渲染器检查声明、节点标识、括号、箭头和特殊字符，再确认结构化编辑没有保留冲突旧边。

最终验收清单

1. 导入基线可以重新加载。
2. 提示只包含一个明确修改目标。
3. ParsedEditIntent 目标和操作正确。
4. 新节点、边与分组符合预期。
5. 无关元素保持不变。
6. XML 或 Mermaid 在目标工具中可打开。
7. 布局没有重叠或严重漂移。
8. 成功版本和当前指针一致。
9. 敏感架构已脱敏。
10. 领域负责人完成语义审核。

总结

SAGE 的关键不是让模型直接重绘软件工程图，而是把提示转换成结构化意图，再由图操作、XML 校验、修复和版本管理约束结果。它适合改名、插入组件、重连依赖和批量修改分组内节点。Draw.io 结构化路径比蒙版图片编辑提供更强的恢复和验证能力，但深层语义、布局、重复 ID 和分组检查仍不完整。每次只做一个目标修改，检查无关元素与拓扑，并在目标编辑器重新加载，才能可靠使用提示驱动编辑。