Architecture diagram

Architecture Diagram

生成可维护的 Draw.io 原生文件。核心交付物是 .drawio，预览工具和浏览器都只是增强。

1. 确认图的语义

从用户材料提取：

• 图表类型和阅读目的；
• 节点、分组、层级与边界；
• 连线方向、协议、条件或时序；
• 标题、语言、视觉风格和输出位置。

简单图（不超过 10 个节点且不超过 3 层）可直接生成。复杂图、需求矛盾或缺少关键关系时，先展示文本骨架并请求确认，不要用视觉细节掩盖结构不确定性。

2. 选择布局

图表	默认布局
分层架构、数据流	左到右
组织、概念层级	上到下
流程图	主路径左到右，分支上下展开
时序图	参与者横向排列，时间向下
思维导图	中心向左右或四周展开

视觉规则：

• 同类节点使用同一颜色和尺寸；整图主色不超过 5 种。
• 主流程使用较深连线，辅助关系使用灰色或虚线。
• 节点间距至少约 40px，标签过长时换行。
• 标题、节点、注释只使用三档字号。
• 连线使用正交路由和明确连接点，避免穿过节点或无意义交叉。

3. 生成 Draw.io XML

输出标准 XML，至少包含：

<mxfile host="app.diagrams.net">
  <diagram name="Page-1">
    <mxGraphModel>
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <!-- vertices and edges -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

要求：

• 每个 mxCell 使用唯一稳定 ID。
• 图形节点包含 vertex="1"、parent="1" 和完整 mxGeometry。
• 连线包含 edge="1"、有效的 source/target 和 relative="1" geometry。
• 标签中的 & < > " ' 必须正确 XML 转义。
• 不生成 XML 声明，避免部分编辑器把它当作普通 XML 文本。
• 修改既有图时保留未要求改变的页面、ID 和样式。

4. 先保存，再打开

这是不可调整的顺序：

1. 将完整 XML 写入用户指定路径；未指定时保存为当前工作目录下的 {slug}.drawio。
2. 使用当前环境可用的标准 XML 解析器做真实的 XML 解析，不得只搜索标签文本。解析后逐项验证：
   • 文档包含 mxfile、至少一个 diagram、mxGraphModel、root 以及 ID 为 0、1 的根 cell；
   • 所有 cell 的 ID 非空且唯一，明确检查重复 ID；
   • 根 cell 的关系是 1 → 0；每个非根 cell 都有 parent，且该 parent 存在并引用已有 cell；
   • 每个 vertex="1" 的 cell 都有 mxGeometry，且 x、y、width、height 是有效数字；
   • 每个 edge="1" 的 source 和 target 都存在并引用已有 cell，且 mxGeometry relative="1"；
   • XML 实体能够正常解码，解析器没有报告截断或格式错误。
3. 再打开 https://app.diagrams.net/?lang=zh&mode=device。

若环境没有可用的标准 XML 解析器，文件可以作为草稿返回，但必须标记“未完成 XML 验证”，且不得打开编辑器或声称已验证。

优先使用当前平台已有的浏览器打开能力；否则可调用操作系统的默认 URL 打开方式。用户明确要求离线时跳过打开步骤。

在线编辑器不会自动获得本地文件。告诉用户选择“从设备打开”，或把 .drawio 文件拖放到空白画布。只有环境已经提供安全的浏览器自动化能力时，才可在不上传到临时服务器的前提下辅助选择本地文件。

Draw.io MCP、桌面应用或编辑器扩展都属于可选增强：存在时可以额外预览，但不得成为生成、保存或成功交付的前置依赖。

5. 失败降级

• 浏览器、MCP 或桌面应用打开失败不影响图表交付；不要因此删除或重写已验证的文件。
• 打开失败时返回文件路径、失败原因和“从设备打开/拖放”的手动步骤。
• 文件写入或 XML 验证失败才算生成失败；此时报告具体错误，不得只打开空白编辑器后声称完成。

交付检查

• 主结构或主流程无需逐字阅读即可识别。
• 没有彩虹配色、文字溢出、节点重叠和穿越节点的连线。
• .drawio 已在外部打开动作前写入并验证。
• 返回真实文件路径，并准确区分“文件已生成”和“编辑器是否已打开”。