UMLet LLM Chat – VSCode Extension

Entwicklung eines UMLet Plugins zur automatischen, LLM-unterstützten Generierung von UML-Diagrammen

Übersicht

Dieses VSCode-Plugin integriert Large Language Models (LLMs) direkt in den UMLet-Workflow. Über die Chat Participant API von VS Code kann der Benutzer im GitHub Copilot Chat mit @uml Anforderungen eingeben und automatisch UML-Diagramme generieren lassen.

Die Extension verwendet eine Multi-Agenten-Pipeline auf Basis von LangGraph, die Requirements analysiert, UML-Beziehungen ableitet, UXF-XML generiert und syntaktisch validiert — mit Human-in-the-Loop (HITL) Feedback nach jedem Schritt.

Features

Multi-Agenten-Pipeline: Spezialisierte Agenten (Requirements-Analyst → UML-Architekt → UXF-Generator → Syntax-Validator) mit iterativer Verfeinerung
Graphviz Layout-Engine: Industriestandard-Layouts für professionelle Diagramme (Dot für Klassen-Hierarchien, Neato für Use-Cases). Sequenzdiagramme verwenden einen eigenen deterministischen Gitter-Placer (Zeit-Achse + feste Lifeline-Spalten).
Human-in-the-Loop: Nach jedem Pipeline-Schritt kann der Benutzer Feedback geben oder mit „ok" fortfahren
Chat-basierte Interaktion: Verwende @uml im Copilot Chat
Klassendiagramme: /classdiagram – Generiere Klassendiagramme aus Beschreibungen
Use-Case-Diagramme: /usecase – Generiere Use-Case-Diagramme
Sequenzdiagramme: /sequence – Generiere Sequenzdiagramme mit Lifelines, Nachrichten (sync/async/return), Aktivierungsbalken und opt/alt/loop-Frames
Auto-Modus: /requirements – Erkenne den passenden UML-Diagrammtyp aus Requirements und generiere das Diagramm
Modell-Auswahl: /model – Zeige verfügbare Modelle und aktuelle Konfiguration
Klassendiagramm-Anpassung: Aktiviere/deaktiviere spezifische Features (Methoden, Sichtbarkeiten, Rückgabetypen, etc.) — ideal für Business vs. Technical Views
Automatische UXF-Persistierung: Generierte Diagramme werden automatisch im Workspace gespeichert und mit UMLet geöffnet
Markdown-Protokolle: Optionale Dokumentation jedes Pipeline-Schritts als Markdown-Datei (in .uml-docs/)
Flexible Modellwahl: Verwendet automatisch das in der Copilot Chat-Oberfläche gewählte Modell; alternative Provider (OpenAI, Anthropic) werden ebenfalls unterstützt

Voraussetzungen

Visual Studio Code >= 1.109.0
GitHub Copilot Chat Extension
UMLet Extension (empfohlen für UXF-Darstellung)
Node.js >= 18.x
Optional für PDF-Unterstützung: poppler-utils (siehe PDF-Unterstützung)

Development Setup

1. Dependencies installieren

cd umlet-llm-chat
npm install

2. Kompilieren

npm run compile

3. Extension testen

Öffne das Projekt in VSCode
Drücke F5 um die Extension Development Host zu starten
Öffne im Extension Development Host den GitHub Copilot Chat
Tippe @uml /classdiagram gefolgt von deiner Anfrage

4. Watch-Mode für Entwicklung

npm run watch

Verwendung

Chat Commands

Command	Beschreibung
`@uml`	Allgemeine UML-Fragen und Hilfe
`@uml /classdiagram`	Klassendiagramm aus Beschreibung generieren
`@uml /usecase`	Use-Case-Diagramm generieren
`@uml /sequence`	Sequenzdiagramm generieren (Lifelines + zeitlich geordnete Nachrichten)
`@uml /requirements`	Auto-Modus: passenden UML-Diagrammtyp erkennen und Diagramm generieren
`@uml /model`	Verfügbare Modelle anzeigen und Konfiguration prüfen

Beispiele

@uml /classdiagram Erstelle ein Klassendiagramm für ein Bibliothekssystem mit Büchern, Mitgliedern und Ausleihen.

@uml /usecase Ein Online-Shop soll folgende Funktionen haben: Produkte suchen, in den Warenkorb legen, bestellen und bezahlen.

@uml /sequence Ein Benutzer loggt sich beim AuthService ein: (1) login(user, pw), (2) AuthService validiert und gibt Token zurück.

@uml /requirements Die Software soll eine Benutzerverwaltung mit Login, Registrierung und Passwort-Reset unterstützen. Wähle den passenden UML-Diagrammtyp automatisch.

@uml /model

Kontext-Dateien

Du kannst Dateien und Verzeichnisse direkt in den Chat-Kontext hinzufügen, die dann bei der UML-Generierung berücksichtigt werden. Das ist nützlich, wenn Requirements in externen Dokumenten vorliegen.

Unterstützte Formate:

Text-Dateien: .txt, .md, .json, .xml, .yaml, .ts, .js, .py, .java, etc.
PDF-Dateien: Text wird automatisch extrahiert
Verzeichnisse: Alle Text-Dateien werden rekursiv gelesen (max. 20 Dateien)

Limits:

Maximale Gesamtgröße: 200 KB
Maximale Dateigröße: 100 KB pro Datei
Maximale Dateien aus Verzeichnis: 20

Beispiel:

Füge eine Anforderungsdatei zum Chat hinzu (z.B. requirements.pdf oder spec.md)
Schreibe: @uml /classdiagram Erstelle ein Klassendiagramm basierend auf diesen Requirements
Die Extension extrahiert den Text und verwendet ihn für die UML-Generierung

Hinweis: Bilder werden derzeit übersprungen. Bei zu großen Dateien oder zu vielen Dateien wird ein Fehler angezeigt.

PDF-Unterstützung

Für PDF-Dateien wird pdftotext (Teil von poppler-utils) verwendet. Das Paket muss auf deinem System installiert sein:

Installation:

Linux (Debian/Ubuntu): sudo apt install poppler-utils
Linux (Arch): pacman -S poppler
macOS: brew install poppler
Windows: choco install poppler (via Chocolatey) oder Poppler herunterladen

Wenn pdftotext nicht verfügbar ist, wird eine hilfreiche Fehlermeldung mit Installationsanweisungen angezeigt.

Klassendiagramm-Anpassung

Für Klassendiagramme (/classdiagram) kannst du spezifische UML-Features aktivieren oder deaktivieren — ideal, um zwischen Fachlichen (vereinfacht) und Technischen (detailliert) Diagrammen zu wechseln.

Beim Aufrufen von /classdiagram wirst du aufgefordert, ein Preset auszuwählen:

Preset	Features	Anwendungsfall
All Features	Methoden, Sichtbarkeiten (+, -, #, ~), Rückgabetypen, Parameter	Technische/vollständige Diagramme
Business	Methoden, keine Sichtbarkeiten/Rückgabetypen, keine Parameter-Details	Geschäftliche/vereinfachte Diagramme
Technical	Methoden, Sichtbarkeiten, Rückgabetypen, alle Parameter	Technische Details
Use Workspace Default	Nutze die Workspace-Einstellung (siehe unten)	Standardeinstellung verwenden

Workspace-Einstellungen (dauerhaft):

Du kannst die Standardwerte auch in den Workspace Settings konfigurieren (Command Palette → UMLet LLM: Configure Class Diagram Features):

Setting	Typ	Standard	Beschreibung
`umlet-llm-chat.classdiagram.preset`	`all` \| `business` \| `technical`	`all`	Voreingestelltes Preset
`umlet-llm-chat.classdiagram.showMethods`	`boolean`	`true`	Zeige Methoden
`umlet-llm-chat.classdiagram.showVisibility`	`boolean`	`true`	Zeige Sichtbarkeitssymbole (+, -, #, ~)
`umlet-llm-chat.classdiagram.showReturnTypes`	`boolean`	`true`	Zeige Rückgabetypen von Methoden
`umlet-llm-chat.classdiagram.showParameterDetails`	`boolean`	`true`	Zeige Parameterdetails (Namen und Typen)
`umlet-llm-chat.classdiagram.showAbstract`	`boolean`	`true`	Zeige Abstract-Markierungen
`umlet-llm-chat.colorize.enabled`	`boolean`	`true`	Aktiviere LLM-vorgeschlagene Farben für Klassen, Akteure und Use Cases

Sprache der Diagramme

Die Extension bleibt standardmäßig deutsch. Wenn Diagramminhalte auf Englisch erzeugt werden sollen, setze die Workspace-Setting:

{
  "umlet-llm-chat.diagramLanguage": "en"
}

Mögliche Werte:

Wert	Verhalten
`de`	LLM-generierte Diagramminhalte werden auf Deutsch erzeugt
`en`	LLM-generierte Diagramminhalte werden auf Englisch erzeugt

Die Agent-Prompts bleiben intern deutsch, werden aber bei jeder Generierung um eine zentrale Sprach-Anweisung ergänzt. Das betrifft z.B. Klassen-/Akteursnamen, Use Cases, Beschreibungen, Relations-Labels und Sequenznachrichten. Feste UML-/Schemawerte wie classdiagram, association oder sync bleiben unverändert.

Pipeline-Ablauf

Requirements-Analyst: Extrahiert Klassen, Akteure, Use Cases, Attribute und Methoden aus der Beschreibung
HITL: Benutzer prüft die Analyse und gibt Feedback oder bestätigt mit „ok"
UML-Architekt: Leitet Beziehungen ab (Assoziationen, Vererbung, Komposition etc.) mit Multiplizitäten und Labels
HITL: Benutzer prüft die Beziehungen
UXF-Generator: Erzeugt UMLet-kompatibles UXF-XML mit Graphviz-basiertem Layout
Syntax-Validator: Validiert die XML-Struktur (bis zu 3 Iterationen bei Fehlern)
HITL: Benutzer prüft das finale Ergebnis
Persistierung: UXF-Datei wird im Workspace gespeichert und automatisch mit UMLet geöffnet

Command Palette

Öffne die Command Palette (Ctrl+Shift+P / Cmd+Shift+P) und suche nach einem dieser Befehle:

Befehl	Beschreibung
UMLet LLM: Open Chat	Öffnet den Copilot Chat mit `@uml` Prefix für schnellen Zugriff
UMLet LLM: Select Model	Wählt ein bestimmtes LLM-Modell aus (Copilot, OpenAI oder Anthropic)
UMLet LLM: Configure Class Diagram Features	Konfiguriert die Klassendiagramm-Features (Methoden, Sichtbarkeiten, etc.)
UMLet LLM: Edit Agent Prompt	Öffnet den System-Prompt eines Agenten zur Bearbeitung
UMLet LLM: Reset Agent Prompt	Setzt einen benutzerdefinierten Agent-Prompt auf den Standard zurück
UMLet LLM: Export Prompts to Workspace	Kopiert alle Agent-Prompts nach `.uml-prompts/` zur Anpassung
UMLet LLM: Show Logs	Öffnet das Output Panel mit dem "UMLet LLM Chat" Kanal
UMLet LLM: Accept HIL Step	Genehmigt den aktuellen Human-in-the-Loop Schritt (sendet "ok")
UMLet LLM: Refine HIL Step	Öffnet einen Dialog zur Eingabe von Feedback für den aktuellen Schritt

Modell-Konfiguration

Copilot (Standard, empfohlen)

Bei Provider copilot wird automatisch das in der Copilot Chat-Oberfläche gewählte Modell verwendet (über /models oder den Dropdown). Das bedeutet:

Kostenloser Copilot-Tier: Nur die dort verfügbaren Modelle stehen zur Auswahl
Copilot Pro/Business: Alle freigeschalteten Modelle (GPT-4o, Claude, etc.)
Die Extension zeigt bei jeder Generierung an, welches Modell verwendet wird (z.B. 🔧 Modell: Claude Opus 4.6 (copilot, Chat-UI))

Optional kann über die Setting umlet-llm-chat.modelName ein bestimmtes Modell erzwungen werden (z.B. gpt-4o). Das überschreibt die Chat-UI-Auswahl.

⚠️ Wichtig: Beim Verwenden der Copilot Chat-Oberfläche, wähle "Local" aus dem Modell-Dropdown statt "CLI". Die CLI-Variante kann dazu führen, dass die Extension während der Diagramm-Generierung hängen bleibt. Das "Local"-Modell funktioniert zuverlässig mit allen LLM-Providern.

Alternative Provider (OpenAI, Anthropic)

Für direkte API-Nutzung ohne Copilot:

Setting umlet-llm-chat.llmProvider auf openai oder anthropic setzen
Entsprechenden API-Key in den Settings hinterlegen
Optional: umlet-llm-chat.modelName setzen (sonst wird das Standardmodell des Providers verwendet)

Hinweis: Bei nicht-Copilot Providern wird der Modellselektor in der Copilot Chat-Oberfläche ignoriert. Die Extension zeigt einen entsprechenden Hinweis an.

Settings

Setting	Typ	Standard	Beschreibung
`umlet-llm-chat.llmProvider`	`copilot` \| `openai` \| `anthropic`	`copilot`	LLM-Provider
`umlet-llm-chat.modelName`	`string`	(leer)	Modell-Override (leer = Standardmodell/Chat-UI-Auswahl)
`umlet-llm-chat.openaiApiKey`	`string`	(leer)	OpenAI API Key
`umlet-llm-chat.anthropicApiKey`	`string`	(leer)	Anthropic API Key
`umlet-llm-chat.debugLogs`	`boolean`	`true`	Detaillierte Debug-Logs im Extension Host Output
`umlet-llm-chat.generateProtocol`	`boolean`	`true`	Markdown-Protokolldateien pro Pipeline-Schritt generieren
`umlet-llm-chat.diagramLanguage`	`de` \| `en`	`de`	Ausgabesprache für LLM-generierte Diagramminhalte

Agent-Prompts anpassen

Die Extension erlaubt die Anpassung der System-Prompts für die verschiedenen Agenten. Dies ist nützlich um das Verhalten der Diagramm-Generierung an spezifische Bedürfnisse anzupassen.

Prompts bearbeiten

Über Command Palette: UMLet LLM: Edit Agent Prompt
Agent auswählen (z.B. requirementsAnalyst oder umlArchitect)
Die Prompt-Datei wird im Editor geöffnet und kann bearbeitet werden

Die Prompts werden im Workspace unter .uml-prompts/ gespeichert und bei jeder Diagramm-Generierung automatisch neu geladen (kein Extension-Neustart nötig).

Prompts zurücksetzen

Command: UMLet LLM: Reset Agent Prompt
Löscht die benutzerdefinierte Prompt-Datei, sodass wieder der Standard verwendet wird

Prompts exportieren

Command: UMLet LLM: Export Prompts to Workspace
Kopiert alle Standard-Prompts nach .uml-prompts/ zur einfachen Anpassung

Verfügbare Agenten

Agent	Datei	Beschreibung
`requirementsAnalyst`	`.uml-prompts/requirementsAnalyst.md`	Extrahiert Klassen, Akteure, Use Cases aus dem Input-Text
`umlArchitect`	`.uml-prompts/umlArchitect.md`	Deduziert Beziehungen (Vererbung, Assoziationen, etc.)
`uxfRefiner`	`.uml-prompts/uxfRefiner.md`	Wendet Post-Open-Feedback als Quick-Edit direkt auf das UXF-XML an

Debugging & Logs

Die Extension bietet detaillierte Protokollierung für Troubleshooting und Überwachung des Agent-Verhaltens.

Logs anzeigen

Option 1: Output Panel (Empfohlen)

Öffne das Output Panel: Ctrl+Shift+U (Windows/Linux) oder Cmd+Shift+U (Mac)
Wähle "UMLet LLM Chat" aus der Dropdown-Liste oben rechts
Logs werden hier angezeigt, während Diagramme generiert werden

Option 2: Show Logs Befehl

Führe den Befehl aus: UMLet LLM: Show Logs
Öffnet automatisch das Output Panel mit dem "UMLet LLM Chat" Kanal

Option 3: Developer Tools (Fortgeschritten)

Öffne Developer Tools: Help → Toggle Developer Tools
Navigiere zur Console Registerkarte
Alle Extension-Logs erscheinen hier, einschließlich Extension Host Output
Nützlich für erweitertes Debugging in produktiven VSIX-Installationen

Beispiel-Log-Ausgabe

[14:05:23] UMLet LLM Chat extension is now active.
[14:05:24] [PromptLoader] Created prompts folder: /path/to/workspace/.uml-prompts
[14:05:25] [PromptLoader] Loaded bundled prompt for: requirementsAnalyst
[14:05:26] [RequirementsAnalyst] withStructuredOutput failed: {...}
[14:05:27] [PromptLoader] Loaded user prompt from workspace: umlArchitect

Graphviz Layout-Engine

Die Extension verwendet Graphviz (via WASM) für professionelle Diagramm-Layouts:

Klassendiagramme: dot Engine für hierarchische Layouts (optimiert für Vererbungshierarchien)
Use-Case-Diagramme: neato Engine für spring-based Layouts (flexibles Positioning von Akteuren und Use Cases)
Sequenzdiagramme: Eigener deterministischer Gitter-Placer (siehe src/layout/sequence-layout.ts) — Graphviz ist für Sequenzdiagramme ungeeignet, da deren Geometrie auf einem Zeit-Achsen-Gitter basiert, nicht auf Graph-Layout

Vorteile:

Industriestandard für Graphen-Layouts
Deterministisch: gleiche Eingabe = gleiche Ausgabe
Keine externen Dependencies (WASM-basiert)
Automatische Konfliktvermeidung (keine Überlappungen)

Das Projekt kann als installierbare VSIX-Datei verpackt werden, damit andere Nutzer die Extension direkt installieren können.

Lokale VSIX-Erstellung

cd umlet-llm-chat
npm run vsix:package:dated

Ergebnis:

VSIX-Datei unter .artifacts/vsix/
Dateiname mit Zeitstempel: umlet-llm-chat-<version>-YYYY-MM-DD_HHmm.vsix

Automatische Erstellung in GitLab CI

Die Pipeline (/.gitlab-ci.yml) erstellt automatisch eine VSIX-Datei bei Pushes/Merges auf:

main
develop

Die VSIX-Datei wird als GitLab Job-Artifact bereitgestellt (kein Commit der Binärdatei ins Repository).

Installation einer VSIX in VS Code

VSIX aus den GitLab Pipeline-Artifacts herunterladen
In VS Code: Extensions: Install from VSIX...
Die heruntergeladene .vsix-Datei auswählen

Projektstruktur

umlet-llm-chat/
├── src/
│   ├── extension.ts                # Extension Entry Point & Command Registration
│   ├── chatParticipant.ts          # Chat Participant API, HITL, Session Management
│   ├── types.ts                    # TypeScript Type Definitions (Entities, Relations, etc.)
│   ├── umletXmlGenerator.ts        # UMLet UXF XML Generator (Legacy)
│   ├── agents/
│   │   ├── graph.ts                # LangGraph StateGraph Definition
│   │   ├── graphState.ts           # Graph State Schema (Zod-basiert)
│   │   ├── requirementsAnalyst.ts  # Agent 1: Entity-Extraktion aus Requirements
│   │   ├── umlArchitect.ts         # Agent 2: Beziehungsanalyse & Heuristiken
│   │   ├── uxfGenerator.ts         # Agent 3: Deterministischer UXF-XML-Generator
│   │   └── syntaxValidator.ts      # Agent 4: XML-Syntax-Validierung
│   ├── llm/
│   │   ├── llmProvider.ts          # LLM-Provider-Fabrik (Copilot/OpenAI/Anthropic)
│   │   └── copilotChatModel.ts     # LangChain-Bridge für VS Code Copilot LM API
│   └── workspace/
│       ├── uxfFileManager.ts       # UXF-Dateiverwaltung & UMLet-Integration
│       └── markdownProtocolGenerator.ts  # Markdown-Protokoll-Generierung
├── package.json                    # Extension Manifest & Settings
├── tsconfig.json                   # TypeScript Configuration
├── esbuild.js                      # esbuild Bundler Configuration
├── eslint.config.mjs               # ESLint Configuration
└── .gitlab-ci.yml                  # CI/CD Pipeline (Verify & Package)

Technologie-Stack

Extension API: VS Code Chat Participant API (TypeScript)
Agent Framework: LangGraph.js (StateGraph mit HITL-Interrupts)
LLM-Integration: LangChain.js (@langchain/core, @langchain/openai, @langchain/anthropic)
Copilot-Bridge: Custom CopilotChatModel (LangChain BaseChatModel ↔ vscode.lm API)
Schema-Validierung: Zod
XML-Parsing: fast-xml-parser
Bundler: esbuild
CI/CD: GitLab CI mit automatischer VSIX-Erstellung

UMLet LLM Chat

UMLet LLM