Draw.io 图表工程师
通过一个小型、确定性的中间表示（IR）来构建图表。将IR视为真相来源，.drawio 文件视为编译后的产物。
工作流程
-
首次使用或环境失败后，运行
doctor。阅读 user-workflows.md 了解功能状态、启动器选择、包内容及安全覆盖行为。在组合不常见命令或解读退出码时，阅读 cli.md。 对于遗留或版本化的图表IR，请阅读 compatibility.md，并在编辑前运行migrate --check。 -
检查请求和相关源材料。当用户未指定时，推断出合理的图表类型、范围、方向和主题。 对于协调的架构图包，阅读 blueprint.md，根据 blueprint.schema.json 编写内容，并使用
blueprint。 对于ERD，阅读 erd.md，根据 erd.schema.json 编写内容，并使用erd。当SQL DDL是真相来源时，直接接受它。 对于高可用性，阅读 ha.md，根据 ha.schema.json 编写内容，并使用ha。 -
编写或适配最小的结构化源。当没有源存在时，使用
init architecture、init blueprint、init erd或init ha。阅读 ir-format.md 了解图表IR，阅读 authoring.md 了解图表特定的选择。 当从Python/TypeScript树、OpenAPI、SQL、Compose、Terraform、Kubernetes、GitHub Actions或GitLab CI开始时，阅读 importers.md，并使用import生成IR。 当自动连接器在视觉上仍然模糊或固定接口很重要时，在分配显式端口前阅读 routing.md。 当需要组织样式或更深层次的视觉质量检查时，阅读 style-system.md 并使用经过验证的主题包。 当导入不受信任的内容或准备发布包时，阅读 security.md。切勿将凭证放在标签、描述、链接、元数据或实体默认值中。 -
优先使用单命令包工作流：
python3 <skill-dir>/scripts/drawio_tool.py build source.json \ -o build/diagram --name diagram --strict这会创建规范化的IR、可编辑的
.drawio、所有SVG预览、audit.json、security.json和bundle.json。仅当用户需要单个工件或增量工作流时，才使用较低级别的compile、validate、preview、security和audit命令。 -
如果安装了 draw.io Desktop 并且请求了Desktop导出，请阅读 desktop-export.md，从包的
.drawio渲染，并保留其验证报告：python3 <skill-dir>/scripts/drawio_tool.py render build/diagram/diagram.drawio \ -o diagram.png --report diagram.export.json -
检查每个打包的预览。修复层次结构、剪切的文本、碰撞、不清晰的边缘、对比度弱以及过多的细节。在呈现最佳结果之前，最多重建两次。
-
交付包的可编辑
.drawio、IR源、审计报告、预览以及请求的导出。当跳过Desktop导出时，需明确说明。
在比较已批准的架构与新生成的模型时，阅读 drift.md，运行 diff，并交付机器可读的报告和可编辑的漂移视图。
编辑现有图表
保留用户的工件。首先检查并验证它：
python3 <skill-dir>/scripts/drawio_tool.py inspect existing.drawio
python3 <skill-dir>/scripts/drawio_tool.py validate existing.drawio
在进行语义编辑前，恢复可审查的图表IR：
python3 <skill-dir>/scripts/drawio_tool.py extract existing.drawio \
-o existing.diagram.json --report existing.extraction.json --strict
在依赖恢复的模型之前，阅读 round-trip.md。lossless: true 表示所有语义单元格使用了支持的编译器元数据。当 --strict 以退出码 3 退出时，仍然可以写入一个有效的尽力而为模型；在替换原始模型之前，审查每个推断出的单元格。
对于一个由IR支持的图表，编写语义操作并原子化应用：
python3 <skill-dir>/scripts/drawio_tool.py patch diagram.json changes.json -o diagram.updated.json
在进行破坏性或多页编辑前，阅读 patching.md。如果提取报告了不受支持的仅XML内容，则仅修改匹配的 mxCell 值、样式或几何结构，并保留原始内容直到视觉审查通过。切勿仅仅为了整洁而重命名稳定的ID。
质量合约
在交付前需要满足以下所有条件：
- 没有悬空的边缘端点、重复的ID、无效的父引用或节点重叠。
- 标签适合其节点，并且在正常缩放时保持可读。
- 方向和分组传达了预期的层次结构。
- 边缘标签描述关系，而不是实现细节。
- 颜色具有一致的含义，并且不会成为唯一的区分因素。
- 装饰细节不会压倒主要的阅读路径。
使用 --strict 作为发布门控。当检查失败或图表需要手动视觉审查时，阅读 quality-gates.md。
编写规则
- 使用稳定、语义化的ID，例如
api-gateway，而不是序数ID，例如node-7。 - 保持标签简短。将更长的上下文放在
description中。 - 对层次、信任区域、限界上下文或所有权使用显式的
group值。 - 请求/数据管道优先采用从左到右布局，流程或层次结构优先采用从上到下布局。
- 每个图表只保留一个主要概念。将大型系统拆分到多个页面或层级，而不是缩小所有内容。
- 仅在用户需要有意放置时使用
position；否则让编译器确定性地布局节点。 - 不要猜测特定供应商的 draw.io 模具名称。在存在经过验证的形状映射之前，使用中性的语义种类。
工具行为
scripts/drawio_tool.py 对于JSON输入仅使用标准库。当安装了 PyYAML 时，支持YAML输入。它提供：
doctor：验证核心文件和Python/XML支持，然后报告可选的YAML和Desktop功能。init：为架构、蓝图、ERD、HA、路由、基础设施或CI复制一个安全的启动器。build：自动检测模型或源，并创建一个完整的、经过审计的drawio-diagram-bundle/v1。migrate：确定性地升级遗留/未版本化的图表IR，并发出机器可读的更改报告。compile：验证IR，计算确定性布局，并发出未压缩的可编辑 draw.io XML。extract：从压缩或未压缩的 draw.io 中恢复图表IR，保留编译器支持的语义，并报告每个推断出的遗留单元格。blueprint：将一个架构模型投射到上下文、逻辑、数据、部署、安全和决策页面。erd：验证实体、字段、键、类型和基数，然后从模型或SQL DDL生成可编辑的鸦脚记法ERD。ha：验证故障域、副本、复制、健康检查和故障转移，然后生成拓扑和故障转移页面。import：将Python/TypeScript模块树、OpenAPI、SQL DDL、Docker Compose、Terraform、Kubernetes、GitHub Actions或GitLab CI转换为图表IR。diff：语义化比较图表IR，发出结构化的漂移报告，并可选择生成一个带有颜色和形状编码的可编辑漂移视图。patch：原子化应用语义上的节点、边缘、组、位置和图表更改。preview：创建一个可审查的SVG，无需 draw.io Desktop。audit：检查结构化源和生成的几何图形，然后将发现结果分组，附上修复建议和预览路径。security：扫描模型、.drawio或完整包，查找凭证、不安全的链接、禁止的XML构造和解压缩风险。validate：检查IR或.drawio，打印0–100质量分数，并在--strict下失败。inspect：汇总页面、节点、边缘、组和画布边界。verify-export：在不启动Desktop的情况下，验证原生导出的格式签名、结构终止符、尺寸和安全SVG内容。
首次使用前，请验证 python3 -c "import xml.etree.ElementTree"。如果macOS Homebrew Python报告 pyexpat/libexpat 符号错误，请使用 /usr/bin/python3 或修复该Python安装；不要将ABI故障归因于图表输入。
使用 example.architecture.json、example.blueprint.json、example.erd.json、example.ha.json、example.routing.json、example.terraform.tf 或 example.kubernetes.json 作为紧凑的起点，而不是固定的模板。当需要可重用的自定义主题示例时，应用 corporate.json。