sparklabx/drawio-ai-kit

drawio‑ai‑kit – AI 驱动的、经过验证的 draw.io 图表生成

它是什么

• 一个自包含的 CLI（drawio‑ai）加上一个 技能，让 LLM 代理（Claude、Gemini 等）无需手动调整坐标即可在 draw.io 中构建云架构图。
• 该工具包保证图表中使用的每个模板 ID 在 draw.io 的 AWS/Azure/GCP 库中确实存在，并且布局遵循一组编码的设计原则。

关键组件

组件	作用
声明式目录	一个基于 JSON 的单一来源，将每个 draw.io 模板 ID（mxgraph.aws4.*、Azure、GCP 等）映射到其分类、规范调色板和连接点。
设计原则	一个 markdown 文件（principles.md），编码了架构和视觉规则（例如，节点不重叠、固定宽高比、颜色一致性）。
结构验证器	一个静态分析引擎，解析生成的 draw.io XML，检查模板有效性，强制执行原则，并在文件保存前报告任何违规。
CLI（drawio‑ai）	打包为单个 Bun 压缩文件（dist/cli.mjs）。它提供命令用于搜索图标、渲染 PNG、验证 XML、审计美学和安装技能。
技能（skills/drawio/）	一个 LLM 可以调用的小型指令集：它询问用户要绘制什么，加载适当的领域参考（AWS、Azure、GCP、Databricks、BPMN），运行构建‑验证‑渲染循环，并返回完成的 .drawio 文件。

它如何为 AI 代理工作

1. 代理发出自然语言请求（例如，“绘制一个 AWS 三层 Web 应用”）。
2. drawio‑ai skill 提示代理提供缺失的细节（云提供商、拓扑类型）。
3. 代理使用工具包的 TypeScript API（Diagram、group、icon、renderTree 等）编写一个简短脚本。
4. drawio‑ai run <script> 执行脚本，布局引擎自动计算坐标，并生成图表 XML。
5. drawio‑ai validate 检查 XML；任何幻觉模板 ID 都会被捕获。
6. 可选地，drawio‑ai render 将 XML 转换为 PNG，用于基于视觉的自我检查。
7. 最终的 .drawio 文件交还给用户。

安装与使用

• 零运行时依赖 – 仅需 Node ≥ 20.6 或 Bun 1.4+。安装程序（install.sh）将单个二进制文件（drawio‑ai）放入 ~/.local/bin 并注册技能。
• 一行命令：curl …/install.sh | sh（或手动 npm i -g drawio‑ai-kit && drawio‑ai skill install）。
• 编程使用：import { Diagram, group, icon, renderTree } from "drawio‑ai-kit"; – 该库附带完整的 TypeScript 类型定义。
• 安全性：无安装后脚本，无隐藏遥测，捆绑的 dist/ 是可读源代码的可重现构建。

你可以构建什么

• 云着陆区（AWS Control Tower、Azure CAF、GCP Shared VPC）。
• 网络拓扑（VPC、子网、路由表、EKS 集群等）。
• 多云或混合图（本地 ↔ AWS ↔ Azure）。
• Databricks lakehouse、MLOps 管道、BPMN 流程。
  所有示例位于 examples/ 下，可以使用 drawio‑ai scaffold 搭建。

为什么重要

• 减少幻觉：AI 代理经常发明模板 ID；验证器在图表保存前捕获这些错误。
• 一致的视觉风格：通过强制使用官方图标目录和颜色/大小调色板，图表看起来专业且易于识别。
• 模型友好：技能的步骤小而确定，即使便宜的 LLM（Claude Haiku）也能驱动整个管道。

结论 drawio‑ai-kit 是大型语言模型与精确、符合标准的 draw.io 图表之间的实用桥梁，既为开发者提供 CLI，也为 LLM 代理提供可自动调用的技能。