Communitygithub.com

BESSER-PEARL/uml-drawing

Compétence Agent : dessiner un diagramme de classes UML correct via BESSER B-UML et le rendre en SVG/PNG intégrable en un appel — sans navigateur. Pour README, documents de conception, wikis et présentations.

Qu'est-ce que uml-drawing ?

Cette compétence permet à un agent IA de produire un diagramme de classes UML **correct** et une **image réellement intégrable** (SVG/PNG) sans intervention manuelle ni navigateur. Le flux de travail est le suivant : 1) construire un modèle B-UML à partir d'une description, d'un code existant ou d'une conversion PlantUML/Draw.io ; 2) valider le modèle avec `model.validate()` ; 3) livrer le code Python du modèle (pour des documents réexécutables) ou le rendu via une requête HTTP unique vers le endpoint SVG sans tête de BESSER. La compétence garantit que le diagramme est syntaxiquement correct (multiplicités, flèches, héritage) et reste synchronisé avec le code généré. Elle prend en charge les agents Claude Code, Cursor, Codex, Copilot et tout outil compatible avec la spécification Pearl. Le modèle B-UML est maintenu comme source unique de vérité, ce qui permet de régénérer l'image à tout moment sans dérive.

Compatible avec✓Claude Code~Codex CLI✓Cursor✓Windsurf
npx skills add BESSER-PEARL/uml-drawing

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Aperçu

Depuis le README du skill

Modèle de données

Documentation

Intégrer un diagramme UML correct dans votre documentation

Les agents sont constamment invités à « ajouter un diagramme » à la documentation — mais ils font souvent des erreurs de modélisation (multiplicités invalides, flèches inversées, héritage dans le mauvais sens) ou renvoient un bloc de code qui ne devient jamais une image. Cette compétence produit un diagramme de classes correct et une image réellement intégrable.

Périmètre

  • Diagrammes de classes uniquement, pour l'instant — classes, attributs, associations, multiplicités, héritage. Les autres types de diagrammes UML (machines à états, objets, séquences, activités, …) sortent du périmètre de cette compétence.
  • Toujours par BESSER B-UML. Chaque diagramme est d'abord construit comme un DomainModel B-UML, puis livré. Passer par le modèle garantit que le diagramme est correct et réutilisable comme code.

Par où commencer

  • Une description — l'utilisateur explique le domaine ; l'agent écrit le modèle.
  • Du code existant — l'agent lit la source et construit le modèle B-UML à partir de sa structure. (Il n'y a pas de scanner de code automatique ; c'est l'agent qui fait la modélisation à partir de ce qu'il lit — ce n'est pas un importateur en un clic.)
  • Un chemin pris en charge vers B-UML — PlantUML, Draw.io, ou une maquette d'interface.

Deux façons de livrer

Modélisez une fois, puis livrez sous forme de code B-UML intégré (Livraison A) ou d'image rendue (Livraison B) — tous deux issus du même modèle, donc ils ne sont jamais en désaccord. Choisissez selon le contexte (un document de conception qui doit rester exécutable → code ; un README qui doit montrer une image → image), ou fournissez les deux. Détails dans les sections Livraison ci-dessous.

Où le placer. Si l'utilisateur nomme un document cible (un README, un document de conception), intégrez-le dans ce fichier. S'il n'en nomme aucun — ou s'il demande un diagramme autonome d'un dépôt/système — livrez par défaut un nouveau .md autonome (par exemple docs/<modèle>.md) : l'image rendue (Livraison B) et/ou le code B-UML (Livraison A), plus une ligne ou deux expliquant ce que montre le diagramme. Cela transforme un simple « diagramme mon dépôt » en un document engageable plutôt qu'en un SVG isolé. Lorsque vous créez un nouveau fichier, dites où vous l'avez placé (et proposez l'alternative — l'intégrer dans un document existant — si cela peut correspondre à ce que l'utilisateur souhaitait).

Flux de travail

1. Construire le modèle B-UML — à partir d'une description, de code existant lu par l'agent, ou via un chemin pris en charge vers B-UML (PlantUML / Draw.io / maquette)
2. model.validate()  → confirmer qu'il est structurellement correct

Puis livrer l'un (ou les deux) :

  A) Intégrer le code :  placer le DomainModel Python dans un bloc délimité dans le .md
  B) Intégrer une image :  POSTer le modèle vers le endpoint SVG sans tête de BESSER (un
     appel HTTP — pas de navigateur), sauvegarder le SVG retourné (par exemple docs/img/data-model.svg),
     intégrer  ![Modèle de données](docs/img/data-model.svg)

3. Quand le modèle change, mettre à jour le modèle et relivrer — une source unique de vérité

1. Construire le modèle

Un diagramme correct commence par un modèle correct. La forme minimale :

from besser.BUML.metamodel.structural import (
    DomainModel, Class, Property, Multiplicity,
    BinaryAssociation, Generalization, StringType, IntegerType,
)

publication = Class(name="Publication", attributes={Property(name="title", type=StringType)})
book   = Class(name="Book",   attributes={Property(name="pages", type=IntegerType)})
auteur = Class(name="Auteur", attributes={Property(name="nom", type=StringType)})

book_is_a = Generalization(general=publication, specific=book)   # Book est une Publication

# Un Book est écrit par 1..* Auteurs ; un Auteur écrit 0..* Books
ecrite_par = Property(name="ecritePar", type=auteur, multiplicity=Multiplicity(1, "*"))
ecrit     = Property(name="ecrit",    type=book,   multiplicity=Multiplicity(0, "*"))
book_auteur = BinaryAssociation(name="book_auteur", ends={ecrite_par, ecrit})

modele = DomainModel(
    name="Bibliotheque",
    types={publication, book, auteur},
    associations={book_auteur},
    generalizations={book_is_a},
)
assert modele.validate()["success"]

Nommage : pas d'espaces, pas de traits d'union. Pour tout ce qui dépasse cette forme minimale — énumérations, tous les motifs de multiplicité/composition, classes d'association, ensembles de généralisation, méthodes, détails de validation — lisez references/class-diagram.md (fourni avec cette compétence). Pour les types de modèles non-classe (objet, feature, déploiement, OCL, …), voir la compétence besser-user de la plateforme BESSER.

Forme importable — requise pour les deux chemins de livraison. Écrivez chaque Class(...), BinaryAssociation(...) et Generalization(...) comme une affectation explicite de premier niveau, exactement comme ci-dessus. L'importateur de BESSER (utilisé par le endpoint SVG et par l'Import de l'éditeur) lit la structure du fichier — il ne l'exécute pas — donc les relations construites à l'intérieur d'une fonction d'aide ou d'une boucle sont invisibles : les classes s'importent mais les associations disparaissent silencieusement. Une instruction littérale par relation.

Parce que l'importateur n'exécute jamais le fichier, model.validate() n'est pas exécuté sur le chemin de rendu — vous n'avez pas besoin d'installer BESSER pour faire un rendu via le endpoint. Conservez l'appel validate() pour quand vous avez BESSER localement (et avant de générer du code) ; il est sans effet pour le endpoint, pas une exigence.

D'où vient le modèle :

  • D'une description — écrivez-le comme ci-dessus.
  • De code existant — lisez la source et traduisez sa structure (classes, champs, relations, héritage) en modèle B-UML. L'agent fait la modélisation ; il n'y a pas de scanner de code automatique.
  • De PlantUML / Draw.io / d'une maquette d'interface — utilisez la conversion appropriée (disponible via la plateforme BESSER), puis continuez.

Maintenant, livrez-le d'une des deux manières.

Livraison A — intégrer le code B-UML dans le document

Placez le modèle directement dans un bloc délimité ```python dans le .md. Il est correct, validé par validate(), réexécutable et importable dans l'éditeur. Idéal quand le document doit porter le modèle lui-même (un document de conception, une spécification) :

## Modèle de données

```python
# (le DomainModel ci-dessus)
```

Ce modèle B-UML est la source unique de vérité pour le domaine — validé par `validate()`,
et l'entrée de tout générateur BESSER.

Livraison B — intégrer une image rendue

Le modèle devient une image réelle via le moteur de rendu de BESSER, donc l'image correspond toujours au modèle. Deux façons — choisissez selon que vous voulez une approche entièrement automatique ou un réglage manuel.

B1. Rendu automatique (par défaut) — un appel HTTP, pas de navigateur

BESSER expose un endpoint B-UML → SVG sans tête. L'agent POSTe le fichier modèle .py et reçoit un SVG en retour — pas d'éditeur, pas de manipulations manuelles, rien à faire pour l'utilisateur :

curl -X POST https://editor.besser-pearl.org/besser_api/get-svg \
  -F "[email protected];type=text/x-python" \
  -o docs/img/data-model.svg

Le endpoint parse le B-UML, le dispose automatiquement et retourne image/svg+xml. Sauvegardez-le dans le dépôt et intégrez-le :

![Modèle de données](docs/img/data-model.svg)
  • Le fichier modèle doit être en forme importable (voir l'encart dans §1) — la même forme que celle importée par l'éditeur. Diagrammes de classes uniquement.
  • La disposition est automatique. Quand le placement est important, ajustez-le manuellement avec B2.
  • Sauvegardez le .py en UTF-8 sans BOM — une marque d'ordre d'octets en tête fait rejeter le fichier par le endpoint (HTTP 400).
  • Omettez default_value=... d'un littéral d'énumération dans un modèle que vous rendez ici — le endpoint échoue actuellement dessus (HTTP 500). Il est correct pour la génération de code ; une énumération simple utilisée comme type d'attribut se rend correctement.
  • Une réponse non-200 est une petite erreur JSON, pas un SVG ({ "detail": ... }) — vérifiez le statut avant de sauvegarder.

B2. Export réglé manuellement depuis l'éditeur (quand la disposition compte)

Ouvrez https://editor.besser-pearl.org, Importez le .py (choisissez le format B-UML), déplacez les boîtes et les lignes de routage à votre guise, puis Exportez et choisissez un format :

  • SVG — net à toute taille ; idéal pour la documentation et le web.
  • PNG — fond transparent.
  • PNG (fond blanc) — pour les surfaces qui nécessitent une image opaque.

Sauvegardez dans le dépôt et intégrez-le de la même manière. (L'éditeur peut aussi exporter le modèle en B-UML ou JSON — ce sont le modèle, pas une image.)

Dans les deux cas, SVG et PNG s'affichent partout où les images Markdown sont supportées — GitHub, GitLab, sites de documentation, wikis, présentations — sans plugin.

Empêcher la dérive

Quel que soit le mode choisi, le modèle est la source unique de vérité. Quand les exigences changent, mettez à jour le modèle et relivrez (recollez le code, ou réexportez l'image) — ne modifiez jamais manuellement un SVG/PNG exporté, il est généré.

L'avantage au-delà d'une image

Parce que le diagramme est un vrai modèle B-UML, le même artefact peut générer un code fonctionnel — classes Python, SQL, un backend FastAPI, Django, React, et plus encore. Un diagramme que vous avez dessiné pour expliquer le système peut devenir le système. Pour générer le code à partir de celui-ci, référez-vous à la compétence besser-generators.

Quand utiliser les compétences connexes

  • Construction de modèles en profondeur (énumérations, héritage, méthodes, OCL, modèles objet / feature / déploiement / NN / quantique) → la compétence besser-user.
  • Génération de code à partir du modèle → la compétence besser-generators.
  • Erreurs (problèmes d'import/validation/éditeur) → la compétence besser-troubleshooting.

Skills associés