Diagrams (Diagrammes)
Concevez, créez, révisez et convertissez des diagrammes tout en gardant l'argument visuel et la source native indépendamment corrects.
Le contrat d'intégration lisible par machine répertorie les prérequis externes.
Résoudre deux décisions
Choisissez d'abord la vue qui exprime la relation : organigramme, séquence, état, architecture, modèle de données, hiérarchie, chronologie, comparaison ou une autre vue prise en charge. Choisissez ensuite le format de livraison. Ne laissez pas un format de fichier familier décider du type de diagramme.
Un format explicite l'emporte lorsqu'il peut exprimer la structure requise. S'il crée une limitation matérielle, expliquez la limitation et proposez une alternative sans modifier silencieusement le livrable.
Utilisez cette matrice lorsque le format est ouvert :
| Contrainte | Excalidraw | Mermaid | draw.io |
|---|---|---|---|
| Contrôle manuel des coordonnées | Fort | Faible ; la disposition est automatique | Fort |
| Édition visuelle collaborative | Fort dans Excalidraw | Dépend de l'hôte | Fort dans diagrams.net |
| Diff textuel et revue de code | Faible | Fort | Modéré avec XML non compressé |
| Disposition automatique | Manuel d'abord | Fort | Disponible, mais la géométrie manuelle reste explicite |
| Composition spatiale libre | Fort | Limité | Fort |
| Pages, calques, conteneurs, bibliothèques de formes | Limité | Limité et dépendant du moteur de rendu | Fort |
| Rendu direct dans Markdown/chat | Rare | Fort lorsque pris en charge | Rare |
| Éditabilité native après transfert | .excalidraw | Source Mermaid dans un éditeur compatible | .drawio XML |
| Validation et rendu fiables | Nécessite vérificateur plus rendu fidèle | Nécessite analyseur cible plus rendu | Nécessite vérifications XML plus éditeur/exportateur compatible |
Préférez le format dont l'éditeur natif, le validateur et le moteur de rendu sont disponibles dans l'environnement de livraison. Si aucun ne peut fournir une preuve visuelle, produisez la source native demandée uniquement si elle est encore utile et étiquetez le résultat DEGRADED.
Posséder l'argument visuel
Réglez une question, un public, une fenêtre de livraison, un point d'entrée et une direction de lecture dominante. Préservez les faits et identifiants exacts tout en raccourcissant les étiquettes explicatives. Modélisez les nœuds sémantiques, les limites et les relations avant la syntaxe ou les coordonnées.
Lisez la méthode de conception partagée avant de créer ou de réviser substantiellement un diagramme. Elle possède la topologie, la hiérarchie, la densité, le regroupement, les limites, le routage, l'utilisation sémantique des formes/couleurs/lignes, les critères de scission et l'acceptation visuelle.
Utiliser un adaptateur de format
- Pour le JSON natif
.excalidraw, lisez l'adaptateur Excalidraw. Exécutez son vérificateur intégré et inspectez un rendu fidèle. - Pour la source Mermaid ou un bloc Mermaid dans le chat, lisez l'adaptateur Mermaid. Analysez et rendez avec la cible réelle ou un outil compatible existant.
- Pour le XML natif
.drawio, lisez l'adaptateur draw.io. Validez la structure XML, ouvrez-la ou exportez-la avec un outil diagrams.net compatible et inspectez le résultat.
Les adaptateurs de format possèdent la sérialisation, l'échappement, les identifiants, les liaisons, la géométrie, les thèmes, les pages, les calques et les limitations spécifiques au moteur de rendu. Ne copiez pas leur mécanique volatile dans ce noyau.
Préserver la source native
Pour un nouveau livrable nommé, le chemin demandé devient canonique lors de la première écriture. Pour une révision, la source existante reste canonique pendant que les changements vivent dans un candidat. Les éditeurs et moteurs de rendu consomment ces artefacts ; une exportation ailleurs ne remplace jamais implicitement la source canonique.
Un candidat de révision remplace la source existante uniquement lorsqu'il satisfait au portail de complétion. Sinon, signalez DEGRADED, laissez la source existante inchangée et identifiez le candidat comme inachevé.
Convertir et réviser
Dans les conversions, préservez l'identité sémantique : signification des nœuds, direction des relations, séquence, containment, limites, cardinalité et jetons techniques exacts. Préservez l'identité des pages, calques et conteneurs lorsque la source et la cible les prennent en charge. Signalez les pertes telles que les modifications de disposition automatique, les bibliothèques de formes non prises en charge ou le style aplati ; ne promettez jamais une parité pixel par pixel.
Pour un travail de révision uniquement, inspectez et signalez sans réécrire. Vérifiez la structure native séparément de la composition rendue : un succès d'analyse ne prouve pas la lisibilité, et une image plausible ne prouve pas l'éditabilité.
Limite de déclenchement
Cette compétence possède les appels explicites x9-diagrams, la sélection de format, la conversion inter-format, la méthode visuelle partagée et la vérification structurelle et visuelle combinée. Une demande limitée à une syntaxe Mermaid ordinaire peut rester avec une compétence spécialisée mermaid-diagrams installée. Cette compétence reste autonome pour les utilisateurs qui ne possèdent pas cette compétence tierce.
Lorsque la propriété du déclenchement est ambiguë, utilisez x9-diagrams uniquement si la tâche nécessite son contrat de décision ou de vérification plus large. N'invoquez pas les deux compétences simplement parce que Mermaid apparaît dans la requête.
Portail de complétion
Faites correspondre les preuves de complétion à l'action demandée :
- Sélection de format : nommez la vue et le format de livraison, reliez le choix aux contraintes de l'utilisateur, indiquez les limitations matérielles et identifiez si un validateur, un moteur de rendu ou un éditeur compatible est disponible.
- Création ou révision matérielle : la vue choisie répond à la question posée ; la source native s'analyse ou s'ouvre et reste éditable ; l'agent n'a pas déclenché un sélecteur de fichier ou de répertoire natif qu'il ne pouvait pas terminer lui-même ; la disposition post-chargement spécifique au format est stable le cas échéant ; un moteur de rendu ou un éditeur compatible a produit la vue réelle à partir de la source canonique finale après sa dernière mutation matérielle ; et cette vue a été inspectée dans son mode de livraison déclaré pour la lisibilité, la hiérarchie, les croisements, le rognage et la structure trompeuse.
- Conversion : satisfaites aux preuves de création et confirmez que les sémantiques importantes ont survécu ; signalez toute perte de disposition, de style, de pages, de calques, de conteneurs ou de notation.
- Révision uniquement : distinguez les résultats de la structure native des résultats de la composition rendue et citez les preuves inspectées sans réécrire l'artefact.
Si une preuve requise pour l'action active ne peut être obtenue, signalez DEGRADED avec le vérificateur, le validateur, le moteur de rendu, l'éditeur ou l'artefact source exact manquant. Les tests de régression du vérificateur Excalidraw se trouvent dans scripts/test_check_scene.py.