sparklabx/drawio-ai-kit

drawio‑ai‑kit – AI 기반, 검증된 draw.io 다이어그램 생성

정의

• 자체 포함된 CLI(drawio‑ai)와 LLM 에이전트(Claude, Gemini 등)가 수동으로 좌표를 조정하지 않고 draw.io에서 클라우드 아키텍처 다이어그램을 구축할 수 있게 해주는 스킬.
• 이 키트는 다이어그램에 사용된 모든 스텐실 ID가 draw.io의 AWS/Azure/GCP 라이브러리에 실제로 존재하고 레이아웃이 일련의 코드화된 설계 원칙을 따르도록 보장합니다.

주요 구성 요소

구성 요소	역할
선언적 카탈로그	모든 draw.io 스텐실 ID(mxgraph.aws4.*, Azure, GCP 등)를 분류, 표준 색상 팔레트, 연결 지점에 매핑하는 단일 JSON 기반 소스.
설계 원칙	아키텍처 및 시각적 규칙(예: 노드 겹침 금지, 고정 종횡비, 색상 일관성)을 인코딩하는 마크다운 파일(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 3계층 웹 앱을 그려줘”).
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 레이크하우스, MLOps 파이프라인, BPMN 프로세스 흐름.
  모든 예제는 examples/에 있으며 drawio‑ai scaffold로 스캐폴드할 수 있습니다.

중요성

• 환각 감소: AI 에이전트는 종종 스텐실 ID를 발명합니다. 검증기가 다이어그램이 저장되기 전에 이를 잡아냅니다.
• 일관된 시각적 스타일: 공식 아이콘 카탈로그와 색상/크기 팔레트를 적용하여 다이어그램이 전문적으로 보이고 즉시 인식할 수 있습니다.
• 모델 친화적: 스킬의 단계는 작고 결정적이어서 저렴한 LLM(Claude Haiku)도 전체 파이프라인을 구동할 수 있습니다.

결론 drawio‑ai-kit는 대규모 언어 모델과 정확하고 표준을 준수하는 draw.io 다이어그램 사이의 실용적인 다리 역할을 하며, 개발자용 CLI와 LLM 에이전트가 자동으로 호출할 수 있는 스킬을 모두 제공합니다.