uulab-official/drawio-skills

Ingénieur Diagramme draw.io

Construisez des diagrammes via une petite représentation intermédiaire (IR) déterministe. Traitez l'IR comme la source de vérité et le .drawio comme l'artefact compilé.

Workflow

1. Lors de la première utilisation ou après un échec d'environnement, exécutez doctor. Lisez user-workflows.md pour les états des capacités, la sélection du starter, le contenu du bundle et le comportement de remplacement sécurisé. Lisez cli.md lorsque vous composez des commandes moins courantes ou interprétez des codes de sortie. Pour un IR de diagramme hérité ou versionné, lisez compatibility.md et exécutez migrate --check avant d'éditer.

2. Inspectez la demande et le matériel source pertinent. Inférez un type de diagramme, une portée, une direction et un thème sensés lorsque l'utilisateur ne les spécifie pas. Pour un ensemble coordonné de diagrammes d'architecture, lisez blueprint.md, écrivez selon blueprint.schema.json, et utilisez blueprint. Pour un ERD, lisez erd.md, écrivez selon erd.schema.json, et utilisez erd. Acceptez directement le DDL SQL lorsqu'il est la source de vérité. Pour une haute disponibilité, lisez ha.md, écrivez selon ha.schema.json, et utilisez ha.

3. Écrivez ou adaptez la plus petite source structurée. Utilisez init architecture, init blueprint, init erd ou init ha lorsqu'aucune source n'existe. Lisez ir-format.md pour l'IR de diagramme et authoring.md pour les choix spécifiques au diagramme. Lorsque vous partez d'un arbre Python/TypeScript, OpenAPI, SQL, Compose, Terraform, Kubernetes, GitHub Actions ou GitLab CI, lisez importers.md et générez l'IR avec import. Lorsque les connecteurs automatiques restent visuellement ambigus ou qu'une interface fixe est importante, lisez routing.md avant d'assigner des ports explicites. Lorsque le style d'organisation ou une révision visuelle plus approfondie est nécessaire, lisez style-system.md et utilisez un pack de thèmes validé. Lors de l'import de contenu non fiable ou de la préparation d'un bundle de publication, lisez security.md. Ne placez jamais d'identifiants dans les étiquettes, descriptions, liens, métadonnées ou valeurs par défaut d'entité.

4. Privilégiez le workflow bundle en une commande :

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

   Cela crée un IR normalisé, un .drawio éditable, toutes les préviews SVG, audit.json, security.json et bundle.json. N'utilisez les commandes de plus bas niveau compile, validate, preview, security et audit que lorsque l'utilisateur a besoin d'artefacts individuels ou d'un workflow incrémental.

5. Si draw.io Desktop est disponible et qu'une exportation Desktop est demandée, lisez desktop-export.md, générez à partir du .drawio du bundle et conservez son rapport de vérification :

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

6. Inspectez visuellement chaque préview du bundle. Corrigez la hiérarchie, le texte tronqué, les collisions, les arêtes peu claires, le faible contraste et les détails excessifs. Reconstruisez au maximum deux fois avant de présenter le meilleur résultat.

7. Livrez le .drawio éditable du bundle, la source IR, le rapport d'audit, les préviews et les exportations demandées. Indiquez clairement lorsque l'exportation Desktop a été ignorée.

Lorsque vous comparez une architecture approuvée avec un modèle nouvellement généré, lisez drift.md, exécutez diff et livrez à la fois le rapport lisible par machine et la vue de dérive éditable.

Édition de diagrammes existants

Préservez l'artefact de l'utilisateur. Commencez par l'inspecter et le valider :

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

Récupérez un IR de diagramme révisable avant les modifications sémantiques :

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

Lisez round-trip.md avant de vous fier à un modèle récupéré. lossless: true signifie que toutes les cellules sémantiques ont utilisé les métadonnées du compilateur prises en charge. Un modèle valide de meilleur effort peut toujours être écrit lorsque --strict se termine avec le code 3 ; examinez chaque cellule inférée avant de remplacer l'originale.

Pour un diagramme basé sur IR, écrivez des opérations sémantiques et appliquez-les de manière atomique :

python3 <skill-dir>/scripts/drawio_tool.py patch diagram.json changes.json -o diagram.updated.json

Lisez patching.md avant les modifications destructrices ou multi-pages. Si l'extraction signale un contenu non pris en charge uniquement XML, modifiez uniquement les valeurs mxCell, styles ou géométrie correspondants et préservez l'original jusqu'à ce que la révision visuelle soit réussie. Ne renumérotez jamais les IDs stables par souci de propreté.

Contrat de qualité

Exigez tout ce qui suit avant la livraison :

• Pas de points d'extrémité d'arête pendants, d'ID en double, de références parent invalides ou de chevauchements de nœuds.
• Les étiquettes tiennent dans leurs nœuds et restent lisibles à un zoom normal.
• La direction et le regroupement communiquent la hiérarchie prévue.
• Les étiquettes d'arête décrivent les relations, pas des détails d'implémentation.
• La couleur a une signification cohérente et ne devient pas le seul différenciateur.
• Les détails décoratifs ne submergent pas le chemin de lecture principal.

Utilisez --strict comme passerelle de publication. Lisez quality-gates.md lorsqu'une vérification échoue ou qu'un diagramme nécessite une révision visuelle manuelle.

Règles de création

• Utilisez des IDs sémantiques stables tels que api-gateway, pas des IDs ordinaux tels que node-7.
• Gardez les étiquettes courtes. Mettez le contexte plus long dans description.
• Utilisez des valeurs group explicites pour les couches, les zones de confiance, les contextes délimités ou la propriété.
• Préférez le sens gauche-droite pour les pipelines de requêtes/données et le sens haut-bas pour les processus ou hiérarchies.
• Gardez une idée principale par diagramme. Divisez les grands systèmes en plusieurs pages ou niveaux plutôt que de tout réduire.
• Utilisez position uniquement lorsque l'utilisateur a besoin d'un placement intentionnel ; sinon, laissez le compilateur disposer les nœuds de manière déterministe.
• Ne devinez pas les noms de pochoirs draw.io spécifiques au fournisseur. Utilisez un type sémantique neutre jusqu'à ce qu'un mappage de forme vérifié existe.

Comportement de l'outil

scripts/drawio_tool.py utilise uniquement la bibliothèque standard pour l'entrée JSON. L'entrée YAML est prise en charge lorsque PyYAML est installé. Il fournit :

• doctor : vérifie les fichiers principaux et le support Python/XML, puis rapporte les capacités YAML et Desktop optionnelles.
• init : copie un starter sûr pour l'architecture, Blueprint, ERD, HA, routage, infrastructure ou CI.
• build : détecte automatiquement un modèle ou une source et crée un drawio-diagram-bundle/v1 complet et audité.
• migrate : met à niveau de manière déterministe un IR de diagramme hérité/non versionné et émet un rapport de changement lisible par machine.
• compile : valide l'IR, calcule une disposition déterministe et émet du XML draw.io éditable non compressé.
• extract : récupère l'IR de diagramme à partir de draw.io compressé ou non compressé, en préservant la sémantique soutenue par le compilateur et en rapportant chaque cellule héritée inférée.
• blueprint : projette un modèle d'architecture en pages de contexte, logique, données, déploiement, sécurité et décision.
• erd : valide les entités, champs, clés, types et cardinalités, puis génère un ERD de patte d'oie éditable à partir d'un modèle ou d'un DDL SQL.
• ha : valide les domaines de défaillance, réplicas, réplication, contrôles de santé et basculements, puis génère des pages de topologie et de basculement.
• import : convertit les arbres de modules Python/TypeScript, OpenAPI, DDL SQL, Docker Compose, Terraform, Kubernetes, GitHub Actions ou GitLab CI en IR de diagramme.
• diff : compare l'IR de diagramme sémantiquement, émet un rapport de dérive structuré et génère optionnellement une vue de dérive éditable codée par couleur et forme.
• patch : applique atomiquement des modifications sémantiques de nœud, arête, groupe, position et diagramme.
• preview : crée un SVG révisable sans draw.io Desktop.
• audit : inspecte la source structurée et la géométrie générée, puis regroupe les résultats avec des suggestions de réparation et des chemins de prévisualisation.
• security : analyse un modèle, un .drawio ou un bundle complet pour les identifiants, les liens non sécurisés, les constructions XML interdites et les risques de décompression.
• validate : vérifie la syntaxe de l'IR ou du .drawio, affiche un score de qualité de 0 à 100 et échoue sous --strict.
• inspect : résume les pages, nœuds, arêtes, groupes et limites du canevas.
• render : découvre le CLI draw.io Desktop sur macOS, Windows et Linux, honore DRAWIO_DESKTOP_BINARY ou --binary, et exporte en PNG, SVG, PDF ou JPG.
• verify-export : valide la signature de format, le terminateur structurel, les dimensions et le contenu SVG sûr d'une exportation native sans lancer Desktop.

Avant la première utilisation, vérifiez `python3 -c