sparklabx/drawio-ai-kit

# drawio-ai-kit 一个编排和验证框架，使 AI agent 能够生成**结构精确且美观标准化**的 draw.io 图表，专为 AWS、Azure 和 GCP 架构优化。  它通过三个核心组件来缓解常见的 AI agent 幻觉（例如生成不存在的 stencil ID 导致出现空白形状）： 1. **声明式目录** — 将 draw.io stencil ID（`mxgraph.aws4.*`）映射到其各自分类和标准调色板的唯一事实来源。 2. **设计原则** — 已编纂的架构和布局规则（`rules/principles.md`）。 3. **结构验证器** — 一个静态分析引擎，用于审计图表 XML，以确保在序列化之前 stencil 引用有效且满足设计原则。 通过**零依赖的 `drawio-ai` CLI** 暴露给 AI 使用。 ## 展示 每个平台一张图表——全部由该套件端到端生成：无需手动放置坐标，使用真实 stencil，经过验证和视觉检查。完整集合请见 [`examples/`](examples/)。

## 快速开始 完整安装 —— CLI 外加所有 5 个 Domain Skills（AWS、Azure、GCP、Databricks、BPMN）—— 只需一行命令： ``` npm i -g github:sparklabx/drawio-ai-kit && npx skills add sparklabx/drawio-ai-kit ``` 重启你的 agent，然后尝试：*"draw an AWS 3-tier web app"（画一个 AWS 三层 Web 应用）*。 第一条命令将 `drawio-ai` 可执行文件添加到 PATH 中（直接从 GitHub 安装——尚未发布到 npm 注册表；请参阅 [INSTALL.md](INSTALL.md) 以固定版本 或从克隆中安装）。第二条命令将 Domain Skills 注册到你的 agent （`skills` CLI 会自动检测 Claude Code、Codex、Gemini CLI 等……）——如果没有它， agent 永远不会自己发现该套件。 - 如果只需一个领域：`npx skills add sparklabx/drawio-ai-kit --skill drawio-aws`（使用 `--list` 预览全部 5 个） - 可选，为了获得完整体验：**draw.io 桌面应用程序**启用 `drawio-ai render`（视觉自检）；**Graphviz** 启用 `vendor/autolayout.py` 用于处理大型图。详情见 [INSTALL.md](INSTALL.md)。 ## 安装安全吗？ 简短回答：是的——而且你不必只听我的一面之词。 - **没有隐藏代码。** 没有 `postinstall`（或任何生命周期）钩子——在 `npm install` 时不会运行任何东西。零运行时依赖。**没有 `sudo`，没有 `curl | bash`，没有远程代码。** - **零运行时依赖。** 单个依赖项（`@modelcontextprotocol/sdk`）在 1.0.0 版本中已被移除。该包现在是完全自包含的。 - **本地运行，无遥测。** CLI 仅读取/写入本地文件。唯一的可选出站调用是从公共 CDN (lobe-icons) 获取图标 logo，且需手动开启。 - **易于撤销：** ``` npm uninstall -g drawio-ai-kit # remove the CLI npx skills remove drawio-aws # remove a domain skill (repeat for each) ``` 如需报告安全问题，请参阅 [`SECURITY.md`](SECURITY.md)。 ## 构建图表 —— 声明式，无需硬编码坐标 定义图表的**拓扑结构**（`pipeline`/`hierarchy`/`network`/`hubspoke`/`hybrid`/`mesh`/`sequence`），声明**嵌套结构**，布局引擎将以编程方式计算空间坐标（x/y/w/h）——框架会自动调整大小以适应其子元素，而行和列会自动调整间距。你定义的是逻辑拓扑，而不是原始像素。 ``` import { Diagram } from "./src/builder.mjs"; import { group, icon, box, renderTree } from "./src/layout-engine.mjs"; const d = new Diagram("network"); const tree = group("region", "group_region", "Region", { dir: "row" }, [ group("vpc", "group_vpc", "VPC", { dir: "col" }, [ icon("alb", "elastic_load_balancing", "ALB"), icon("ec2", "ec2", "EC2"), ]), ]); renderTree(d, tree); // engine lays everything out + sizes the page d.title("My VPC"); d.link("alb", "ec2"); // edges by id; router picks straight/corridor const res = d.validate(); // names real? colors/nesting/labels clean? // d.mxfile("My VPC") → write to .drawio, export PNG, then vision self-check ``` 图标名称通过 `drawio-ai search` 获取，以防止捏造名称；边缘路由、容器大小调整、对齐和上下文角样式是动态计算的。AI agent 定义逻辑布局，并通过渲染-分析-纠正循环（基于视觉的自我纠正）进行迭代。示例：`examples/aws/build_mesh.mjs`（零手动坐标）。 ## 迁移（从 <1.0） 在 **1.0.0** 版本中，移除了 MCP server 和专用安装程序。迁移方法： - **安装：** 从 `claude mcp add ... mcp-server.mjs` 切换到 `npm i -g github:sparklabx/drawio-ai-kit`。 - **Skills：** 用 5 个轻量级 Domain Skills 替换旧的 `drawio-cloud-architect` skill——通过 `npx skills add sparklabx/drawio-ai-kit` 一次性全部安装，或按领域使用 `--skill drawio-aws` 等命令安装。 - **视觉自检：** 内联图像被 `drawio-ai render` → PNG → `Read` 取代。 - **卸载：** `npm uninstall -g drawio-ai-kit` + 通过 skills 工具移除每个 skill。 ## 模板库 (`examples/`) 每个文件都通过布局引擎构建一个通用架构（零硬编码坐标）——复制其中一个作为起点。示例**按领域子文件夹组织**——完整索引请参阅 [`examples/README.md`](examples/README.md)。使用 `node examples//` 运行任意示例 → 写入 `out/*.drawio`。 **`examples/aws/`** | 示例 | 类型 | 架构 | | --- | --- | --- | | `build_pipeline.mjs` | pipeline | 分层数据分析流水线（摄取 → 处理 → 存储 → 服务）+ 跨领域带 | | `build_landingzone.mjs` | hierarchy | AWS Landing Zone / Control Tower 组织和 OU | | `build_vpc.mjs` | network | VPC 多可用区三层架构（ALB 跨可用区） | | `build_vpc_routing.mjs` | network | 子网 + 路由表 + VPC Endpoint (Gateway) → S3 | | `build_vpc_eks.mjs` | network | 包含 Bastion、NAT、EKS、Auto Scaling 工作节点的 VPC | | `build_vpc_efs.mjs` | network | 包含 Amazon EFS 的 VPC（每个可用区一个挂载目标） | | `build_web3tier.mjs` | network | 三层 Web 应用（边缘 → Web → 应用 → 数据） | | `build_eventdriven.mjs` | hubspoke | Serverless 事件总线（EventBridge 中心 → 消费者） | | `build_serverless.mjs` | sequence | Serverless Web 应用，编号请求演练 | | `build_hybrid.mjs` | hybrid | 通过 Direct Connect + VPN 实现的本地 ↔ AWS 混合架构，镜像 DR | | `build_mesh.mjs` | mesh | 多账户连接/服务网格 | | `build_iam_accounts.mjs` | hierarchy | 多账户 IAM + 跨账户 assume-role | **`examples/azure/` · `gcp/` · `databricks/` · `multicloud/` · `bpmn/`** | 示例 | 类型 | 架构 | | --- | --- | --- | | `azure/build_azure_vnet.mjs` | network | Azure N 层：Subscription → Resource Group → VNet → Subnet 层 | | `azure/build_azure_hub_spoke_lz.mjs` | network | CAF 轮辐式 Landing Zone（管理组，中心 + 辐射 VNet，预留子网，peering，私有 endpoints） | | `gcp/build_gcp_vpc.mjs` | network | 跨两个区域的 GCP 全局 VPC（Project → 全局 VPC → 区域 Subnets） | | `gcp/build_gcp_shared_vpc_landing_zone.mjs` | network | 共享 VPC Landing Zone（主机/服务项目，区域 Cloud Router/NAT，Interconnect，PSC，VPC-SC） | | `databricks/build_lakehouse.mjs` | pipeline | Databricks Lakehouse 奖牌架构（铜/银/金）+ Unity Catalog | | `databricks/build_platform.mjs` | hybrid | Databricks 控制平面与数据平面部署拓扑 | | `databricks/build_data_intelligence_platform.mjs` | pipeline | Databricks 数据智能平台参考（标志性条带，奖牌架构，基础层） | | `databricks/build_mlops.mjs` | pipeline | Databricks MLOps — Git provider + Dev/Staging/Prod 工作区 + Unity Catalog + Lakehouse | | `multicloud/build_multicloud.mjs` | hybrid | 通过中立的互连组成的本地 + AWS + Azure 混合云 | | `bpmn/build_bpmn.mjs` | bpmn | BPMN 泳道流程（池 → 泳道 × 阶段） | ## 运行时架构 - **Node 18+**（`.nvmrc` 固定了当前的 LTS 版本）—— 编排和验证层：CLI 和验证器（`src/`）。支持的运行时包括 Node 20、22 (LTS) 或 24。 - **Python 3.11**（`.python-version`）—— 数据摄取和编译流水线：目录生成器 + 图标包构建器（`scripts/build_pack.py`，仅使用标准库）。 安装依赖项： ``` nvm install --lts && nvm use --lts # or: brew install node brew install python@3.11 # then: python3.11 --version ``` ## CLI 命令 | 命令 | 用途 | | --- | --- | | `search` | 按关键字/类别查找 stencil → 返回确切名称 + 可直接粘贴的 draw.io `style`（引自索引原文：真实名称、官方颜色、连接点）。 | | `style` | 通过确切名称获取单个 stencil 的完整 style。 | | `validate` | 校验 XML：未知的 stencil、悬空边缘、缺失 `aspect=fixed`、**重新着色的 AWS 图标**、**损坏的 AWS 组嵌套**、**几何形状（重叠 / 子元素溢出其框架 / 堆叠箭头）**，以及美学 `audit`（字体/调色板/展开/图标大小）。 | | `audit` | 仅进行美学审计（字体/调色板/展开/图标大小）。 | | `render` | 将 XML 渲染为 PNG（`drawio-ai render -o out.png`）。需要 draw.io 桌面 CLI；设置 `DRAWIO_CLI` 以覆盖路径。 | | `logo` | 通过 `vendor/aiicons.py` (lobe-icons) 将非 AWS 品牌（AI/LLM 及部分品牌）的 logo 作为 `image` 样式获取。需要 python3。 | | `categories` | 列出所有目录类别。 | | `types` | 列出支持的图表拓扑。 | | `principles` | 设计规则 + 架构预设 + 目录类别。传递 `--mode aws|azure|gcp|databricks|bpmn` 用于特定领域。 | | `root` | 打印已安装套件的绝对路径（用于按路径 `import`）。 | | `workflow` | 打印共享的 build → validate → render → write 工作流。 | 5 个 Domain Skills（`drawio-aws`、`drawio-azure`、`drawio-gcp`、`drawio-databricks`、`drawio-bpmn`）中的每一个都将这些命令封装成一个完整的带引擎构建 → 验证 → **渲染 + 视觉自检** → 最终导出工作流。`vendor/` 中的内置辅助工具：`autolayout.py`（针对 >15 个节点的图进行 Graphviz 布局）、`aiicons.py`、`repair_png.py`、`encode_drawio_url.py`（浏览器回退）。 ## Domain Skills 该套件附带了 5 个轻量级的 Domain Skills——每个云/领域一个——通过标准的 npm skills 工具进行分发： | Skill | 领域 | | --- | --- | | `drawio-aws` | AWS | | `drawio-azure` | Azure | | `drawio-gcp` | GCP | | `drawio-databricks` | Databricks | | `drawio-bpmn` | BPMN | 使用 `skills` CLI 添加一个或多个，例如 `npx skills add sparklabx/drawio-ai-kit --skill drawio-aws`（或省略 `--skill` 以安装所有 5 个；使用 `--list` 预览）。每个 skill 都是一个轻量级前端；确定性引擎、验证器和规则位于 `drawio-ai-kit` 包中，通过 `drawio-ai` CLI 访问。 ## 其他宿主（Coworker AI、Agent SDK 等） 该套件不绑定于特定应用程序——“大脑”位于 **CLI + repo + 规则** 中，因此 任何可以运行 **shell 命令** 的 Claude 宿主都可以使用它。将 agent 指向 CLI：`drawio-ai principles`、`drawio-ai search`、`drawio-ai validate`，以及 `rules/diagram-types` 中的模板索引和再现循环。（`draw.io` CLI 仅 在 PNG 渲染/视觉检查时需要。） ## CLI 用法 ``` drawio-ai search s3 drawio-ai search kubernetes --category Containers drawio-ai search "aws cloud" --kind group drawio-ai style s3 drawio-ai validate ../4_oncloud.drawio drawio-ai categories drawio-ai principles --mode aws drawio-ai render out.drawio -o out.png ``` ## 目录（2106 个图标 —— 983 个 AWS + 626 个 Azure + 216 个 GCP + 分布于 8 个开源包中的 281 个） `loadCatalog` 会合并所有 `catalog/*.json`，因此所有图标都可以通过 `drawio-ai search` 一起搜索。 `catalog/aws.json` 是根据 `data/shape-index.json.gz`（来自 jgraph/drawio-mcp 的 10,446 个形状的索引，Apache-2.0 许可证）生成的——真实的 stencil 名称（`s3`、`eks`、`identity_and_access_management` 等）、官方的单图标颜色、连接点以及 `aspect=fixed`，全部**原样保留**。无需人工猜测。 刷新索引后重新生成： ``` python3.11 scripts/ingest_index.py # data/shape-index.json.gz → catalog/aws.json (983 icons, 19 groups) ``` ### 图标包（非 AWS） 人们在与 AWS 一起绘制图时所用工具的品牌/技术图标——可按名称搜索（`spark`、`kafka`、`postgres`、`kubernetes`、`argocd`、`prometheus`、`pytorch` 等），并以相同的统一风格呈现为方形图块： | 包 | 图标 | 示例 | |---|---:|---| | `database` | 66 | postgres, mysql, mongodb, redis, clickhouse, snowflake | | `bigdata` | 48 | spark, kafka, airflow, flink, trino, dbt, minio | | `cicd` | 42 | jenkins, argocd, terraform, ansible, sonarqube | | `aiml` | 26 | pytorch, tensorflow, huggingface, ollama, langchain | | `containers` | 26 | kubernetes, docker, helm, istio, linkerd | | `observability` | 26 | datadog, prometheus, grafana, opentelemetry | | `databricks` | 24 | unity catalog, delta sharing, mosaic ai | | `network` | 15 | nginx, kong, traefik, haproxy, cloudflare | 预先构建的 `catalog/*.json` 已提交——**使用**该套件无需重新构建。要添加或刷新包，请编辑 `packs//manifest.json` 然后： ``` python3 scripts/build_pack.py # devicon → vectorlogo.zone → gilbarbara → simple-icons → text (needs macOS qlmanage) ``` 有关署名，请参阅 `THIRD_PARTY_NOTICES.md`。 ## 测试 ``` npm test # node --test ``` ## 注意事项和许可 - **代码**使用 MIT 许可证（见 [`LICENSE`](LICENSE)）。捆绑的**图标/logo**（AWS 架构图标 + 第三方项目 logo）是其所有者的商标，**不**受 MIT 许可——请参阅 [`NOTICE`](NOTICE)。 - 推荐使用**原生 stencil**（此目录）而非 base64——文件更小，矢量清晰，许可更干净。 - 仅对于 draw.io 缺失的图标（Confluent、Starburst、OpenMetadata、MinIO、Dagster、内部/品牌 logo）或在 draw.io 之外渲染时，才使用 **base64**（`custom-icons.json`）。 - 官方的 AWS 架构图标有其自己的使用条款——在公开分发 base64 捆绑包之前请进行审查。 - 种子中的类别颜色是近似的；生成器可以对其进行刷新。 ## Star 历史

标签：AI辅助设计, draw.io, MITM代理, 云安全监控, 云架构, 暗色界面, 架构图生成, 自定义脚本, 逆向工具, 静态分析