UMLet LLM Chat

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

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

4. Watch-Mode für Entwicklung

npm run watch

Verwendung

Chat Commands

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:

1. Füge eine Anforderungsdatei zum Chat hinzu (z.B. requirements.pdf oder spec.md)
2. Schreibe: @uml /classdiagram Erstelle ein Klassendiagramm basierend auf diesen Requirements
3. 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:

Workspace-Einstellungen (dauerhaft):

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

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:

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

1. Requirements-Analyst: Extrahiert Klassen, Akteure, Use Cases, Attribute und Methoden aus der Beschreibung
2. HITL: Benutzer prüft die Analyse und gibt Feedback oder bestätigt mit „ok"
3. UML-Architekt: Leitet Beziehungen ab (Assoziationen, Vererbung, Komposition etc.) mit Multiplizitäten und Labels
4. HITL: Benutzer prüft die Beziehungen
5. UXF-Generator: Erzeugt UMLet-kompatibles UXF-XML mit Graphviz-basiertem Layout
6. Syntax-Validator: Validiert die XML-Struktur (bis zu 3 Iterationen bei Fehlern)
7. HITL: Benutzer prüft das finale Ergebnis
8. 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:

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:

1. Setting umlet-llm-chat.llmProvider auf openai oder anthropic setzen
2. Entsprechenden API-Key in den Settings hinterlegen
3. 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

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

1. Über Command Palette: UMLet LLM: Edit Agent Prompt
2. Agent auswählen (z.B. requirementsAnalyst oder umlArchitect)
3. 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

Debugging & Logs

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

Logs anzeigen

Option 1: Output Panel (Empfohlen)

1. Öffne das Output Panel: Ctrl+Shift+U (Windows/Linux) oder Cmd+Shift+U (Mac)
2. Wähle "UMLet LLM Chat" aus der Dropdown-Liste oben rechts
3. 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)

1. Öffne Developer Tools: Help → Toggle Developer Tools
2. Navigiere zur Console Registerkarte
3. Alle Extension-Logs erscheinen hier, einschließlich Extension Host Output
4. 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)

VSIX Packaging und Sharing

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

1. VSIX aus den GitLab Pipeline-Artifacts herunterladen
2. In VS Code: Extensions: Install from VSIX...
3. 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