Mermaid Architect - Hierarchische Diagramm- und Dokumentationsfertigkeit

Mermaid-Diagramm- und Dokumentationssystem mit spezialisierten Anleitungen und Code-zu-Diagramm-Funktionen.

Inhaltsverzeichnis

Entscheidungsbaum
GitHub Wiki, WikiTicket und Confluence
Verfügbare Anleitungen und Ressourcen
Nutzungsmuster
Resilienter Workflow
Unicode-Semantiksymbole
Python-Dienstprogramme
Entscheidungsbaum-Beispiele
Hochkontrast-Stil
Dateiorganisation
Workflow-Zusammenfassung
Wann verwende ich was?
Bewährte Praktiken
Lernpfad

Entscheidungsbaum

So funktioniert diese Fertigkeit:

Benutzer stellt eine Anfrage → Fertigkeit analysiert die Absicht
Fertigkeit bestimmt Diagramm-/Dokumenttyp → Lädt die entsprechende Anleitung(en)
KI liest die spezialisierte Anleitung → Erstellt Diagramm/Dokument mit Vorlagen
Ergebnis wird geliefert — Mit Validierungs- und Exportoptionen

Analyse der Benutzerabsicht:

flowchart TD
    Start([Benutzeranfrage]) --> Analyze{Absicht analysieren}

    Analyze -->|"Workflow, Prozess, Geschäftslogik"| Activity[Aktivitätsdiagramm-Anleitung laden<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"Infrastruktur, Bereitstellung, Cloud"| Deploy[Bereitstellungsdiagramm-Anleitung laden<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"Systemarchitektur, Komponenten"| Arch[Architektur-Anleitung laden<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"API-Fluss, Interaktionen"| Sequence[Sequenzdiagramm-Anleitung laden<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"Klasse, ER, Zustand, Wiki, Walkthrough"| WikiGuide[WikiTicket GitHub-Anleitung laden<br/>references/guides/wiki-ticket-and-github.md]
    Analyze -->|"Code zu Diagramm"| CodeToDiag[Code-zu-Diagramm-Anleitung laden<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"Design-Dokument, vollständige Dokumentation"| DesignDoc[Design-Dokumentvorlage laden<br/>assets/*-design-template.md]
    Analyze -->|"Unicode-Symbole, Icons"| Unicode[Unicode-Symbole-Anleitung laden<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"extrahieren, validieren, konvertieren"| Scripts[Python-Skripte verwenden<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> Generate[Diagramm erstellen]
    Deploy --> Generate
    Arch --> Generate
    Sequence --> Generate
    WikiGuide --> Generate
    CodeToDiag --> Generate
    DesignDoc --> Generate
    Unicode --> Generate
    Scripts --> Execute[Skript ausführen]

    Generate --> Validate{Validieren?}
    Validate -->|Ja| RunValidation[mmdc-Validierung ausführen]
    Validate -->|Nein| Output
    RunValidation --> Output[Ergebnis ausgeben]
    Execute --> Output

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analyze,Validate decision
    class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide
    class Generate,Execute,RunValidation,Output action

Verfügbare Anleitungen und Ressourcen

Diagrammtyp-Anleitungen (`references/guides/diagrams/`)

Anleitung	Vollständiger Pfad	Laden, wenn Benutzer möchte	Beispiele
Aktivitätsdiagramme	`references/guides/diagrams/activity-diagrams.md`	Workflows, Prozesse, Geschäftslogik, Benutzerabläufe, Entscheidungsbäume	"Checkout-Ablauf zeigen", "ETL-Pipeline dokumentieren", "Genehmigungsworkflow erstellen"
Bereitstellungsdiagramme	`references/guides/diagrams/deployment-diagrams.md`	Infrastruktur, Cloud-Architektur, K8s, serverlos, Netzwerktopologie	"AWS-Architektur zeigen", "GCP-Bereitstellung dokumentieren", "K8s-Diagramm erstellen"
Architekturdiagramme	`references/guides/diagrams/architecture-diagrams.md`	Systemarchitektur, Komponentendesign, High-Level-Struktur	"Systemkomponenten zeigen", "Microservices dokumentieren", "Architekturübersicht"
Sequenzdiagramme	`references/guides/diagrams/sequence-diagrams.md`	API-Interaktionen, Dienstkommunikation, Anfrage/Antwort-Abläufe	"API-Aufrufsequenz zeigen", "Auth-Ablauf dokumentieren", "Dienstinteraktionen"
WikiTicket / GitHub / Confluence	`references/guides/wiki-ticket-and-github.md`	Design-Dokumente, Walkthroughs, Anforderungen, Wiki-Veröffentlichung, Confluence-Bilder	"Architektur-Dokument", "Code Walkthrough", "Wiki", "Confluence"

Standard für WikiTicket und GitHub Wiki ist diese Fertigkeit, einschließlich classDiagram, erDiagram und stateDiagram-v2. Senden Sie diese nicht an PlantUML. Wenn GitHub C4 / architecture-beta / block-beta nicht rendern kann, verwenden Sie als Fallback flowchart TD.

Code-zu-Diagramm-Anleitung & Beispiele

Ressource	Vollständiger Pfad	Was wird bereitgestellt
Master-Anleitung	`references/guides/code-to-diagram/README.md`	Vollständiger Workflow zur Analyse jeder Codebasis und zum Extrahieren von Diagrammen
Spring Boot	`examples/spring-boot/README.md`	Controller→Service→Repository-Architektur, Bereitstellungskonfiguration, Sequenz aus Methoden, Aktivität aus Geschäftslogik
FastAPI	`examples/fastapi/README.md`	Python-Async-Muster, Pydantic-Modelle, Dependency Injection, Cloud-Bereitstellung
React	`examples/react/README.md`	Komponentenhierarchie, Zustandsverwaltung, Datenfluss, Build-Pipeline
Python ETL	`examples/python-etl/README.md`	Datenpipeline, Transformationsschritte, Fehlerbehandlung, Planung
Node/Express	`examples/node-webapp/README.md`	Middleware-Kette, Route-Handler, Async-Muster, Bereitstellung
Java Web App	`examples/java-webapp/README.md`	Traditionelles MVC, Servlet-Container, WAR-Bereitstellung

Design-Dokumentvorlagen

Vorlage	Vollständiger Pfad	Verwendung für	Laden, wenn
Architektur-Design	`assets/architecture-design-template.md`	Systemweite Architektur	"Architektur-Dokument erstellen", "Systemdesign dokumentieren"
API-Design	`assets/api-design-template.md`	API-Spezifikationen	"API-Design-Dokument", "REST-API dokumentieren"
Feature-Design	`assets/feature-design-template.md`	Feature-Planung	"Feature-Design", "Neues Feature planen"
Datenbank-Design	`assets/database-design-template.md`	Datenbankschema	"Datenbank-Design", "Schema dokumentieren"
System-Design	`assets/system-design-template.md`	Komplettes System	"System-Design-Dokument", "Volle Systemdokumentation"

Unicode-Symbole-Anleitung

Vollständiger Pfad: references/guides/unicode-symbols/guide.md

Laden, wenn Benutzer erwähnt: "Unicode-Symbole", "Emojis in Diagrammen", "semantische Icons", "Symbole hinzufügen"

Schnellreferenz:

📦 Infrastruktur: ☁️ 🌐 🔌 📡 🗄️
⚙️ Berechnung: ⚙️ ⚡ 🔄 ♻️ 🚀 💨
💾 Daten: 💾 📦 📊 📈 🗃️ 🧊
📨 Nachrichten: 📨 📬 📤 📥 🐰 📢
🔐 Sicherheit: 🔐 🔑 🛡️ 🚪 👤 🎫
📝 Überwachung: 📝 📊 🚨 ⚠️ ✅ ❌

Python-Skripte (`scripts/`)

Skript	Verwendung für	Laden, wenn
`extract_mermaid.py`	Diagramme aus Markdown extrahieren, Syntax validieren, durch Bilder ersetzen	"Diagramme extrahieren", "Mermaid validieren", "alle Diagramme finden"
`mermaid_to_image.py`	.mmd in PNG/SVG konvertieren, Batch-Konvertierung, benutzerdefinierte Designs	"in Bild konvertieren", "Diagramm rendern", "PNG erstellen"
`resilient_diagram.py`	Vollständiger Workflow: .mmd speichern, Bild generieren, validieren, Fehlerbehebung	"Diagramm generieren", "Diagramm mit Validierung erstellen", "resilientes Diagramm"

GitHub Wiki, WikiTicket und Confluence

Laden Sie references/guides/wiki-ticket-and-github.md für WikiTicket-Design-Dokumente, Code-Walkthroughs, Anforderungen, GitHub-Wiki oder Confluence.

Ziel	Was liefern
GitHub Wiki / GFM	Begrenzter `mermaid`-Block. GitHub rendert class, ER, state, sequence, flowchart, C4.
Confluence / Notion / Word / PDF	Auch PNG oder SVG rendern (`scripts/resilient_diagram.py` oder `mmdc`) und das Bild hochladen. Verlassen Sie sich nicht darauf, dass Confluence Mermaid rendert.

PlantUML ist opt-in für Salt-Drahtmodelle, Use Case, Timing, ArchiMate, nwdiag und WBS. Diese werden immer als PNG oder SVG geliefert.

Nutzungsmuster

Häufige Anfragemuster und Anleitungsauswahl. Siehe Wann verwende ich was? für die vollständige Zuordnung.

Muster	Beispielanfrage	Zu ladende Anleitungen
Einzelnes Diagramm	"Aktivitätsdiagramm für Login-Ablauf erstellen"	Diagrammtyp-Anleitung + Unicode-Symbole
Code-zu-Diagramm	"Bereitstellung aus application.yml generieren"	Framework-Beispiel + Bereitstellungsanleitung
Design-Dokument	"API-Design-Dokument erstellen"	Vorlage aus assets/ + relevante Diagrammanleitungen
Extrahieren/Validieren	"Diagramme aus design.md extrahieren"	`scripts/extract_mermaid.py` verwenden
Batch-Konvertierung	"Alle .mmd in PNG konvertieren"	`scripts/mermaid_to_image.py` verwenden

Resilienter Workflow

KRITISCH: Dies ist der empfohlene Ansatz für ALLE Diagrammgenerierungen. Er stellt Validierung, Fehlerbehebung und konsistente Dateiorganisation sicher.

Vollständige Anleitung: references/guides/resilient-workflow.md

Workflow-Übersicht

flowchart LR
    A[1. Typ identifizieren] --> B[2. .mmd + Bild speichern]
    B --> C{3. Gültig?}
    C -->|Ja| D[4. Zu Markdown hinzufügen]
    C -->|Nein| E[5. Fehlerbehebung]
    E --> F{Fix gefunden?}
    F -->|Ja| A
    F -->|Nein| G[Extern suchen]
    G --> A

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G step
    class C,F decision

Schlüsselprinzip

Fügen Sie NIEMALS ein Diagramm zu Markdown hinzu, bevor es die Validierung besteht. Dadurch werden defekte Diagramme in der Dokumentation vermieden.

Verwendung des Skripts (Empfohlen)

# Mit vollständiger Fehlerbehebung generieren
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

Ausgabe: Sowohl .mmd- als auch .png-Dateien im Verzeichnis ./diagrams/.

Dateibenennungskonvention

./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

Beispiel: ./diagrams/api_design_01_sequence_auth_flow.png

Priorität der Fehlerbehebung

Wenn die Validierung fehlschlägt, führt der Workflow automatisch Folgendes durch:

Fehlerbehebungsanleitung prüfen - references/guides/troubleshooting.md (28 dokumentierte Fehler)
Mit perplexity suchen - perplexity_ask MCP für Syntaxfragen
Mit brave suchen - brave_web_search MCP für aktuelle Lösungen
Gemini fragen - gemini-Fertigkeit für alternative Perspektive
Allgemeine Suche - WebSearch-Werkzeug als Fallback

Manuelle Fallback-Schritte

Wenn das Skript nicht verfügbar ist:

Diagrammtyp identifizieren aus der ersten Zeile (flowchart, sequence, etc.)
Referenzanleitung laden aus references/guides/diagrams/
Speichern in ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
Validieren: mmdc -i file.mmd -o file.png -b transparent
Bei Fehler: Suche in references/guides/troubleshooting.md nach passendem Fehler
Wenn nicht gefunden: Suchwerkzeuge in der obigen Prioritätsreihenfolge verwenden
Referenz hinzufügen: ![Beschreibung](./diagrams/dateiname.png)

Muster 6: Resiliente Diagrammgenerierung

Benutzer: "Erstelle ein Sequenzdiagramm und füge es dem Design-Dokument hinzu"

Fertigkeit-Aktionen:

Absicht identifizieren: Diagrammgenerierung + Markdown-Integration
Workflow-Anleitung laden: references/guides/resilient-workflow.md
Diagrammtyp identifizieren: Sequenz
Diagrammanleitung laden: references/guides/diagrams/sequence-diagrams.md
Mermaid-Code mit Vorlagen generieren

Resilienten Workflow ausführen:

python scripts/resilient_diagram.py \
    --code "[generierter Code]" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "api_sequence" \
    --json

Wenn Validierung fehlschlägt → Fehlerbehebungsfix anwenden → Wiederholen
Bei Erfolg → ![API-Sequenz](./diagrams/design_doc_01_sequence_api_sequence.png) zu Markdown hinzufügen

Unicode-Semantiksymbole

Verwenden Sie immer Unicode-Symbole, um die Diagrammklarheit zu verbessern. Häufige Muster:

Infrastruktur & Bereitstellung

graph TB
    Client[👤 Benutzer] --> LB[🌐 Load Balancer]
    LB --> App1[⚙️ App-Server 1]
    LB --> App2[⚙️ App-Server 2]
    App1 --> DB[(💾 Datenbank)]
    App1 --> Cache[(⚡ Redis)]

Aktivitätsablauf mit Zuständen

flowchart TD
    Start([🚀 Start]) --> Process[⚙️ Daten verarbeiten]
    Process --> Check{✓ Gültig?}
    Check -->|Ja| Save[💾 Speichern]
    Check -->|Nein| Error[❌ Fehler]
    Save --> Complete([✅ Abgeschlossen])

Microservices-Architektur

graph TB
    API[🌐 API-Gateway] --> Auth[🔐 Authentifizierungsdienst]
    API --> Orders[📋 Bestelldienst]
    Orders --> Queue[📬 Nachrichtenwarteschlange]
    Queue --> Worker[⚙️ Hintergrundarbeiter]
    Worker --> Storage[📦 Objektspeicher]

Für die vollständige Symbolreferenz laden Sie: references/guides/unicode-symbols/guide.md

Python-Dienstprogramme

Mermaid-Diagramme extrahieren

# Alle Diagramme auflisten
python scripts/extract_mermaid.py dokument.md --list-only

# In separate Dateien extrahieren
python scripts/extract_mermaid.py dokument.md --output-dir diagrams/

# Alle Diagramme validieren
python scripts/extract_mermaid.py dokument.md --validate

# Mit Bildreferenzen ersetzen (für Confluence-Upload)
python scripts/extract_mermaid.py dokument.md --replace-with-images \
  --image-format png --output-markdown ausgabe.md

In Bilder konvertieren

# Einzelne Konvertierung
python scripts/mermaid_to_image.py diagramm.mmd ausgabe.png

# Mit benutzerdefinierten Einstellungen
python scripts/mermaid_to_image.py diagramm.mmd ausgabe.svg \
  --theme dunkel --background weiß --width 1200

# Verzeichnis stapelweise konvertieren
python scripts/mermaid_to_image.py diagrams/ ausgabe/ --format png --recursive

# Von stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_

…

[gekürzt für die Übersetzung]

Mermaid Architect - Hierarchische Diagramm- und Dokumentationsf…

Was ist Mermaid Architect - Hierarchische Diagramm- und Dokumentationsf…?

In Ihrer bevorzugten KI fragen

Vorschau

Dokumentation