Communitygithub.com

BESSER-PEARL/diagrama-uml

Dibuja un diagrama de clases UML correcto mediante BESSER B-UML y lo renderiza a SVG/PNG incrustable en una sola llamada, sin necesidad de navegador. Ideal para READMEs, documentos de diseño, wikis y diapositivas.

¿Qué es diagrama-uml?

Esta habilidad permite a un agente de IA generar y entregar diagramas de clases UML correctos tanto en código B-UML como en imágenes SVG/PNG incrustables, sin depender de un navegador. Está construida sobre BESSER B-UML, lo que garantiza que cada diagrama derive de un modelo semánticamente válido (con multiplicidades, asociaciones y herencias correctas), evitando errores comunes de modelado manual. Soporta dos modos de entrega: incrustar el código Python del modelo para documentos ejecutables, o generar una imagen renderizada automáticamente mediante una única solicitud HTTP a un endpoint headless. Los agentes pueden construir el modelo a partir de una descripción textual, código existente o formatos como PlantUML y Draw.io. Está diseñada para plataformas como Claude Code, Cursor, Codex y equivalentes, y se integra con otros skills de BESSER para generación de código y resolución de problemas. El resultado es un diagrama fiel al modelo, sin desviaciones, y fácilmente actualizable.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Vista previa

Del README del skill

Modelo de datos

Documentación

Incrusta un diagrama UML correcto en tus documentos

A los agentes se les pide constantemente "añadir un diagrama" a la documentación — y suelen obtener el modelado sutilmente incorrecto (multiplicidades inválidas, flechas invertidas, herencia al revés) o devuelven un bloque de código que nunca se renderiza como imagen. Esta habilidad produce un diagrama de clases correcto y una imagen incrustable real.

Alcance

  • Solo diagramas de clases, por ahora — clases, atributos, asociaciones, multiplicidades, herencia. Otros tipos de diagramas UML (máquinas de estado, objetos, secuencia, actividad, …) quedan fuera del alcance de esta habilidad.
  • Siempre a través de BESSER B-UML. Cada diagrama se construye primero como un DomainModel de B-UML y luego se entrega. Pasar por el modelo es lo que hace que el diagrama sea correcto y reutilizable como código.

Dónde puede comenzar

  • Una descripción — el usuario explica el dominio; el agente escribe el modelo.
  • Código existente — el agente lee el código fuente y construye el modelo B-UML a partir de su estructura. (No hay un escáner de código automático; el agente realiza el modelado a partir de lo que lee — no es un importador de un solo clic).
  • Una ruta compatible hacia B-UML — PlantUML, Draw.io o un mockup de interfaz.

Dos formas de entregar

Modela una vez, luego entrega como código B-UML incrustado (Entrega A) o una imagen renderizada (Entrega B) — ambos a partir del mismo modelo, por lo que nunca entran en conflicto. Elige según el contexto (un documento de diseño que debe seguir siendo ejecutable → código; un README que debe mostrar una imagen → imagen), o proporciona ambos. Los detalles están en las secciones de Entrega a continuación.

Dónde colocar el resultado. Si el usuario nombra un documento destino (un README, un documento de diseño), incrusta en ese archivo. Si no nombra ninguno — o pide un diagrama independiente de un repositorio/sistema — por defecto entrega un nuevo .md autocontenido (p. ej. docs/<modelo>.md): la imagen renderizada (Entrega B) y/o el código B-UML (Entrega A), más una línea o dos explicando lo que muestra el diagrama. Así convierte una simple solicitud "diagrama mi repositorio" en un documento consolidable en lugar de un SVG suelto. Cuando crees un nuevo archivo, indica dónde lo colocaste (y ofrece la alternativa — incrustarlo en un documento existente — si puede ser lo que el usuario quería).

Flujo de trabajo

1. Construye el modelo B-UML — a partir de una descripción, código existente que el agente
   lea, o mediante una ruta compatible hacia B-UML (PlantUML / Draw.io / mockup)
2. model.validate()  → confirma que es estructuralmente correcto

Luego entrega uno (o ambos):

  A) Incrusta el código:  coloca el DomainModel Python en un bloque delimitado en el .md
  B) Incrusta una imagen:  envía el modelo al endpoint headless SVG de BESSER (una
     llamada HTTP — sin navegador), guarda el SVG devuelto (p. ej. docs/img/data-model.svg),
     incrusta  ![Modelo de datos](docs/img/data-model.svg)

3. Cuando el modelo cambie, actualiza el modelo y vuelve a entregar — una única fuente de verdad

1. Construye el modelo

Un diagrama correcto comienza con un modelo correcto. La forma mínima:

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)})
author = Class(name="Author", attributes={Property(name="name", type=StringType)})

book_is_a = Generalization(general=publication, specific=book)   # Book es una Publication

# Un Book está escrito por 1..* Authors; un Author escribe 0..* Books
written_by = Property(name="writtenBy", type=author, multiplicity=Multiplicity(1, "*"))
writes     = Property(name="writes",    type=book,   multiplicity=Multiplicity(0, "*"))
book_author = BinaryAssociation(name="book_author", ends={written_by, writes})

model = DomainModel(
    name="Library",
    types={publication, book, author},
    associations={book_author},
    generalizations={book_is_a},
)
assert model.validate()["success"]

Nombres: sin espacios, sin guiones. Para todo lo más allá de esta forma mínima — enumeraciones, todos los patrones de multiplicidad/composición, clases de asociación, conjuntos de generalización, métodos, detalles de validación — consulta references/class-diagram.md (incluido con esta habilidad). Para tipos de modelo que no son de clases (objeto, característica, despliegue, OCL, …), consulta la habilidad besser-user de la plataforma BESSER.

Forma importable — requerida para ambas rutas de entrega. Escribe cada Class(...), BinaryAssociation(...) y Generalization(...) como una asignación explícita de nivel superior, exactamente como se muestra arriba. El importador de BESSER (usado por el endpoint SVG y por el editor en Importar) lee la estructura del archivo — no lo ejecuta — por lo que las relaciones construidas dentro de una función auxiliar o un bucle son invisibles: las clases se importan pero las asociaciones desaparecen silenciosamente. Una sentencia literal por relación.

Debido a que el importador nunca ejecuta el archivo, model.validate() no se ejecuta en la ruta de renderizado — no necesitas BESSER instalado para renderizar mediante el endpoint. Mantén la llamada validate() para cuando sí tengas BESSER localmente (y antes de generar código); es un no-op para el endpoint, no un requisito.

De dónde viene el modelo:

  • Desde una descripción — escríbelo como arriba.
  • Desde código existente — lee el código fuente y traduce su estructura (clases, campos, relaciones, herencia) al modelo B-UML. El agente realiza el modelado; no hay un escáner de código automático.
  • Desde PlantUML / Draw.io / un mockup de interfaz — usa la conversión correspondiente hacia B-UML (disponible a través de la plataforma BESSER), luego continúa.

Ahora entrégalo de una de las dos maneras.

Entrega A — incrusta el código B-UML en el documento

Coloca el modelo directamente dentro de un bloque delimitado ```python en el .md. Es correcto, validado con validate(), re-ejecutable e importable en el editor. Ideal cuando el documento debe contener el modelo en sí (un documento de diseño, una especificación):

## Modelo de datos

```python
# (el DomainModel de arriba)
```

Este modelo B-UML es la fuente de verdad para el dominio — validado con `validate()`,
y la entrada para cualquier generador de BESSER.

Entrega B — incrusta una imagen renderizada

El modelo se convierte en una imagen real a través del renderizador de BESSER, por lo que la imagen siempre coincide con el modelo. Dos formas — elige según quieras un proceso automatizado o ajustado manualmente.

B1. Renderízalo automáticamente (por defecto) — una llamada HTTP, sin navegador

BESSER expone un endpoint headless B-UML → SVG. El agente envía el archivo .py del modelo mediante POST y obtiene un SVG de vuelta — sin editor, sin pasos manuales, sin nada que el usuario deba hacer clic:

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

El endpoint analiza el B-UML, lo maqueta automáticamente y devuelve image/svg+xml. Guárdalo en el repositorio e incrústalo:

![Modelo de datos](docs/img/data-model.svg)
  • El archivo del modelo debe estar en forma importable (ver el aviso en §1) — la misma forma que importa el editor. Solo diagramas de clases.
  • La maquetación es automática. Cuando la colocación importe, ajústalo manualmente con B2.
  • Guarda el .py como UTF-8 sin BOM — una marca de orden de bytes inicial hace que el endpoint rechace el archivo (HTTP 400).
  • Omite default_value=... de literales de enumeración en un modelo que renderices aquí — el endpoint actualmente falla con ello (HTTP 500). Es correcto para generación de código; un enumerado simple usado como tipo de atributo se renderiza bien.
  • Una respuesta no-200 es un pequeño JSON de error, no un SVG ({ "detail": ... }) — verifica el estado antes de guardar.

B2. Exportación ajustada manualmente desde el editor (cuando la maquetación importa)

Abre https://editor.besser-pearl.org, Importa el .py (elige el formato B-UML), arrastra cajas y líneas de ruta a tu gusto, luego Exporta y elige un formato:

  • SVG — nítido a cualquier tamaño; ideal para documentos y la web.
  • PNG — fondo transparente.
  • PNG (fondo blanco) — para superficies que necesiten una imagen opaca.

Guárdalo en el repositorio e incrústalo de la misma manera. (El editor también puede exportar el modelo como B-UML o JSON — esos son el modelo, no una imagen.)

De cualquier manera, SVG y PNG se renderizan en todos los lugares donde las imágenes Markdown lo hacen — GitHub, GitLab, sitios de documentación, wikis, diapositivas — sin necesidad de complementos.

Evita que se desvíe

Sea cual sea el modo que elijas, el modelo es la fuente de verdad. Cuando los requisitos cambien, actualiza el modelo y vuelve a entregar (vuelve a pegar el código, o vuelve a exportar la imagen) — nunca edites manualmente un SVG/PNG exportado; es generado.

El beneficio más allá de una imagen

Debido a que el diagrama es un modelo B-UML real, el mismo artefacto puede generar código funcional — clases Python, SQL, un backend FastAPI, Django, React y más. Un diagrama que dibujaste para explicar el sistema puede convertirse en el sistema. Para generar código a partir de él, consulta la habilidad besser-generators.

Cuándo recurrir a habilidades relacionadas

  • Construcción de modelos en profundidad (enumeraciones, herencia, métodos, OCL, modelos de objeto / característica / despliegue / NN / cuánticos) → la habilidad besser-user.
  • Generación de código a partir del modelo → la habilidad besser-generators.
  • Errores (problemas de importación/validación/editor) → la habilidad besser-troubleshooting.

Skills relacionados