uulab-official/drawio-skills

Ingeniero de Diagramas Draw.io

Construye diagramas a través de una representación intermedia (IR) pequeña y determinista. Trata la IR como la fuente de verdad y el .drawio como el artefacto compilado.

Flujo de trabajo

1. En el primer uso o después de un fallo del entorno, ejecuta doctor. Lee user-workflows.md para conocer los estados de capacidad, la selección de plantillas iniciales, el contenido del paquete y el comportamiento seguro de sobrescritura. Lee cli.md al componer comandos poco comunes o interpretar códigos de salida. Para IR de diagrama heredado o versionado, lee compatibility.md y ejecuta migrate --check antes de editar.

2. Inspecciona la solicitud y el material fuente relevante. Infiere un tipo de diagrama, alcance, dirección y tema sensatos cuando el usuario no los especifique. Para un paquete de diagramas de arquitectura coordinados, lee blueprint.md, escribe contra blueprint.schema.json y usa blueprint. Para un ERD, lee erd.md, escribe contra erd.schema.json y usa erd. Acepta directamente el DDL de SQL cuando sea la fuente de verdad. Para alta disponibilidad, lee ha.md, escribe contra ha.schema.json y usa ha.

3. Escribe o adapta la fuente estructurada más pequeña. Usa init architecture, init blueprint, init erd o init ha cuando no exista ninguna fuente. Lee ir-format.md para la IR del Diagrama y authoring.md para elecciones específicas del diagrama. Al comenzar desde un árbol de Python/TypeScript, OpenAPI, SQL, Compose, Terraform, Kubernetes, GitHub Actions o GitLab CI, lee importers.md y genera la IR con import. Cuando los conectores automáticos sigan siendo visualmente ambiguos o una interfaz fija sea importante, lee routing.md antes de asignar puertos explícitos. Cuando se requiera un estilo organizativo o una revisión visual más profunda, lee style-system.md y utiliza un paquete de temas validado. Al importar contenido no confiable o preparar un paquete de lanzamiento, lee security.md. Nunca coloques credenciales en etiquetas, descripciones, enlaces, metadatos o valores predeterminados de entidades.

4. Prefiere el flujo de trabajo de paquete con un solo comando:

   python3 <dir-skill>/scripts/drawio_tool.py build source.json \
     -o build/diagram --name diagram --strict
   

   Esto crea IR normalizada, .drawio editable, todas las vistas previas SVG, audit.json, security.json y bundle.json. Usa los comandos de nivel inferior compile, validate, preview, security y audit solo cuando el usuario necesite artefactos individuales o un flujo de trabajo incremental.

5. Si draw.io Desktop está disponible y se solicita una exportación, lee desktop-export.md, renderiza desde el .drawio del paquete y conserva su informe de verificación:

   python3 <dir-skill>/scripts/drawio_tool.py render build/diagram/diagram.drawio \
     -o diagram.png --report diagram.export.json
   

6. Inspecciona cada vista previa empaquetada visualmente. Corrige jerarquía, texto recortado, colisiones, bordes no claros, contraste débil y detalles excesivos. Reconstruye como máximo dos veces antes de presentar el mejor resultado.

7. Entrega el .drawio editable del paquete, la fuente IR, el informe de auditoría, las vistas previas y las exportaciones solicitadas. Indica claramente cuándo se omitió la exportación de Desktop.

Al comparar una arquitectura aprobada con un modelo recién generado, lee drift.md, ejecuta diff y entrega tanto el informe legible por máquina como la vista de desviación editable.

Edición de diagramas existentes

Preserva el artefacto del usuario. Comienza inspeccionándolo y validándolo:

python3 <dir-skill>/scripts/drawio_tool.py inspect existente.drawio
python3 <dir-skill>/scripts/drawio_tool.py validate existente.drawio

Recupera la IR del diagrama revisable antes de las ediciones semánticas:

python3 <dir-skill>/scripts/drawio_tool.py extract existente.drawio \
  -o existente.diagram.json --report existente.extraction.json --strict

Lee round-trip.md antes de confiar en un modelo recuperado. lossless: true significa que todas las celdas semánticas utilizaron metadatos de compilador compatibles. Aún se puede escribir un modelo válido de mejor esfuerzo cuando --strict sale con 3; revisa cada celda inferida antes de reemplazar la original.

Para un diagrama respaldado por IR, escribe operaciones semánticas y aplícalas atómicamente:

python3 <dir-skill>/scripts/drawio_tool.py patch diagrama.json cambios.json -o diagrama.actualizado.json

Lee patching.md antes de ediciones destructivas o de varias páginas. Si la extracción informa contenido no compatible solo en XML, modifica solo los valores, estilos o geometría de mxCell coincidentes y preserva el original hasta que la revisión visual sea exitosa. Nunca renumeres IDs estables por el mero orden.

Contrato de calidad

Requerir todo lo siguiente antes de la entrega:

• Sin extremos de borde colgantes, IDs duplicados, referencias a padres inválidas o superposiciones de nodos.
• Las etiquetas encajan en sus nodos y siguen siendo legibles con zoom normal.
• La dirección y la agrupación comunican la jerarquía prevista.
• Las etiquetas de borde describen relaciones, no detalles de implementación.
• El color tiene un significado consistente y no se convierte en el único diferenciador.
• El detalle decorativo no abruma la ruta de lectura principal.

Usa --strict como compuerta de lanzamiento. Lee quality-gates.md cuando una verificación falla o un diagrama necesita revisión visual manual.

Reglas de autoría

• Usa IDs semánticas y estables como api-gateway, no IDs ordinales como node-7.
• Mantén las etiquetas cortas. Pon el contexto más largo en description.
• Usa valores explícitos de group para niveles, zonas de confianza, contextos limitados o propiedad.
• Prefiere izquierda a derecha para tuberías de solicitud/datos y arriba a abajo para procesos o jerarquías.
• Mantén una idea principal por diagrama. Divide sistemas grandes en varias páginas o niveles en lugar de encoger todo.
• Usa position solo cuando el usuario necesite una colocación intencional; de lo contrario, deja que el compilador organice los nodos de forma determinista.
• No adivines nombres de plantillas stencil específicas de draw.io. Usa un tipo semántico neutral hasta que exista un mapeo de formas verificado.

Comportamiento de la herramienta

scripts/drawio_tool.py usa solo la biblioteca estándar para entrada JSON. La entrada YAML es compatible si PyYAML está instalado. Proporciona:

• doctor: verifica los archivos principales y el soporte de Python/XML, luego informa las capacidades opcionales de YAML y Desktop.
• init: copia una plantilla inicial segura para arquitectura, Blueprint, ERD, HA, enrutamiento, infraestructura o CI.
• build: detecta automáticamente un modelo o fuente y crea un paquete drawio-diagram-bundle/v1 completo y auditado.
• migrate: actualiza de forma determinista la IR de diagrama heredada/sin versión y emite un informe de cambios legible por máquina.
• compile: valida la IR, calcula el diseño determinista y emite XML draw.io editable sin comprimir.
• extract: recupera la IR de un draw.io comprimido o sin comprimir, preservando la semántica respaldada por el compilador e informando cada celda heredada inferida.
• blueprint: proyecta un modelo de arquitectura en páginas de contexto, lógica, datos, despliegue, seguridad y decisiones.
• erd: valida entidades, campos, claves, tipos y cardinalidades, luego genera un ERD editable de Pata de Cuervo a partir de un modelo o DDL de SQL.
• ha: valida dominios de fallo, réplicas, replicación, verificaciones de salud y conmutaciones por error, luego genera páginas de topología y conmutación por error.
• import: convierte árboles de módulos Python/TypeScript, OpenAPI, DDL de SQL, Docker Compose, Terraform, Kubernetes, GitHub Actions o GitLab CI en IR de Diagrama.
• diff: compara la IR de Diagrama semánticamente, emite un informe de desviación estructurado y, opcionalmente, genera una vista de desviación editable codificada por color y forma.
• patch: aplica atómicamente cambios semánticos de nodo, borde, grupo, posición y diagrama.
• preview: crea un SVG revisable sin draw.io Desktop.
• audit: inspecciona la fuente estructurada y la geometría generada, luego agrupa los hallazgos con sugerencias de reparación y rutas de vista previa.
• security: escanea un modelo, .drawio o paquete completo en busca de credenciales, enlaces inseguros, construcciones XML prohibidas y riesgos de descompresión.
• validate: analiza IR o .drawio, imprime una puntuación de calidad de 0 a 100 y falla bajo --strict.
• inspect: resume páginas, nodos, bordes, grupos y límites del lienzo.
• render: descubre la CLI de draw.io Desktop en macOS, Windows y Linux, respeta DRAWIO_DESKTOP_BINARY o --binary, y exporta PNG, SVG, PDF o JPG.
• verify-export: valida la firma de formato, el terminador estructural, las dimensiones y el contenido SVG seguro de una exportación nativa sin iniciar Desktop.

Antes del primer uso, verifica python3 -c "import xml.etree.ElementTree". Si un Python de macOS Homebrew reporta un error de símbolo pyexpat/libexpat, usa /usr/bin/python3 o repara esa instalación de Python; no atribuyas el fallo ABI a la entrada del diagrama.

Usa example.architecture.json, example.blueprint.json, example.erd.json, example.ha.json, example.routing.json, example.terraform.tf o example.kubernetes.json como punto de partida compacto, no como plantilla fija. Aplica corporate.json cuando sea útil un ejemplo de tema personalizado reutilizable.