CommunityBildgithub.com

Unicode-Diagramme

Zeichne Architektur-, Systemdesign- und Ablaufdiagramme als Unicode-Box-Zeichenkunst (┌─┐ │ └─┘ ░ Schatten), nicht als einfaches ASCII. Verwende dies, wenn nach einem Textdiagramm, ASCII- oder Box-Zeichendiagramm oder einem Diagramm in einem Designdokument oder einer README gefragt wird.

Was ist Unicode-Diagramme?

Diese Fähigkeit ermöglicht es einem KI-Agenten, professionelle Systemdesign-Diagramme mithilfe von Unicode-Box-Zeichen zu erstellen, die direkt in Textdokumente, README-Dateien oder Code-Kommentare eingefügt werden können. Der Agent generiert präzise, ausgerichtete Diagramme mit Komponentenboxen (mit Schatten), Titelboxen (mit doppelten Linien), Rahmenboxen sowie horizontalen, vertikalen und abgewinkelten Pfeilen in einem einheitlichen Stil. Die Fähigkeit wird durch eine Python-Engine (`textdiagram.py`) gesteuert, die der Agent in `/tmp/textdiagram/` erstellt und verwendet, um das Layout zu definieren. Der Agent arbeitet im Batch-Modus: Er schreibt ein Python-Skript, das die Engine importiert, Boxen mithilfe von Hilfsfunktionen wie `x_right_of`, `y_below` und `x_centered_under` relativ positioniert, und rendert dann das Diagramm. Fehler werden als `DiagramError` gemeldet; der Agent korrigiert das Layout und wiederholt den Vorgang. Die Ausgabe wird genau in einen Code-Block eingefügt, ohne manuelle Bearbeitung. Es werden verschiedene Pfeilarten unterstützt (gefüllte und hohle Köpfe), Bus-Leitungen (`fan_out`), abgewinkelte Routen mit mehreren Biegungen, Inline-Labels und freie Textanmerkungen. Der Standard-Text wird in Großbuchstaben umgewandelt, wobei bestimmte Einheiten (z. B. Hz, MB, ms) ausgenommen sind. Die Engine erzwingt eine maximale Breite (standardmäßig 80 Zeichen), die an den Konstruktor übergeben werden kann.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rohalrafael/unicode-diagrams/tree/HEAD

Installed? Explore more Bild skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Unicode-Diagramme?

Zeichne Diagramme als Klartext mit Unicode-Box-Zeichen, in einem einheitlichen Stil. Erstelle das Diagramm immer mit der untenstehenden textdiagram.py-Raster-Engine. Zeichne nicht von Hand: Handgezeichnete Diagramme geraten aus der Ausrichtung.

Stilregeln

  • Klartext in einem umschlossenen Code-Block. Kein Mermaid, SVG, Bilder oder Emojis.
  • Breite: Standardmäßig 80 Spalten. Um sie zu ändern, übergib max_width an den Konstruktor, z. B. D(max_width=100). Die Engine gibt einen Fehler bei einer längeren Zeile aus.
  • Alles in GROSSBUCHSTABEN. Die Engine erledigt das für dich: Schreibe normalen Text im Skript. Ausnahme: Einheiten, deren Groß-/Kleinschreibung die Bedeutung ändert, bleiben so stehen, wie sie geschrieben sind, wenn du sie exakt so schreibst: Hz kHz MHz GHz, kB MB GB TB KiB MiB GiB TiB, kb Mb Gb Tb kbps Mbps Gbps, ms µs ns. Andere Wörter, wie NGINX oder K8S, sind in Großbuchstaben.
  • KOMPONENTEN-Box (ein Teil des Systems: Dienst, Client, Datenbank, Warteschlange, Worker): helle Linien ┌─┐ │ └─┘ plus ein heller ░ Schatten, eine Spalte rechts und eine Zeile darunter. Um Teile zu gruppieren, teile eine Box in Abschnitte auf: helle Trennlinien ├───┤, ein Rahmen, ein Schatten.
  • TITEL-Box (der Haupttitel des Dokuments, eines pro Diagramm): doppelte Linien ╔═╗ ║ ╚═╝, kein Schatten. Ein Eintrag pro Zeile (Name, Dokumenttyp, Version), jede Zeile in der Box zentriert. Erstelle sie mit d.header(...): Die Engine zentriert die Box über dem gesamten Diagramm. Optional: eine Meta-Box links (Firma, RFC, Datum) und eine Stempel-Box rechts (Status). Alle drei erhalten die gleiche Höhe; Füllzeilen der Titelbox enthalten einen zentrierten Punkt ·. Kein Pfeil darf an einer Header-Box beginnen oder enden.
  • RAHMEN-Box (Abschnittsüberschrift, Notiz, Hinweis): helle Linien, kein Schatten. Notiz / Hinweis: setze den Namen in den oberen Rand, wie ┌─ HINWEIS ───┐. Füge keine Legende hinzu: Der Stil ist in jedem Diagramm gleich.
  • Freier Text (d.annotate): eine kurze Bemerkung ohne Box, neben dem Diagramm. Verwende es selten. Eine Linie darf ihn nicht kreuzen.
  • Horizontaler Pfeil: Beschriftung innerhalb der Linie, je ein Leerzeichen auf jeder Seite: ── HTTPS ──▶. Beide Enden berühren eine Box: Die Linie beginnt in der Schattenspalte der sendenden Box und die Spitze berührt die empfangende Box.
  • Vertikaler Pfeil: Linie beginnt mit ┬ am unteren Rand, endet mit ▼. Die Beschriftung geht rechts von der Linie, eine Zeile unter dem Schatten. Oder schneide die Beschriftung in die Linie (inline=True): Linie, leere Zeile, Beschriftungszeilen zentriert auf der Linie, leere Zeile, Linie.
  • Abgewinkelter Pfeil (d.route): beliebig viele Biegungen, in jede Richtung (▲ ▼ ◀ ▶). Die Beschriftung geht in ein horizontales Segment, oder neben (oder, mit inline=True, in) ein vertikales Segment. Linien, die sich kreuzen oder treffen, bilden eine Kreuzung (┼ ├ ┤ ┬ ┴). Eine Linie verläuft niemals durch eine Box.
  • Bus (d.fan_out): eine Linie von einer Box, die sich in einen Pfeil pro Ziel aufteilt. Die Beschriftung steht auf der gemeinsamen Linie.
  • Pfeilspitzen: gefüllte ▶ ◀ ▲ ▼ für den Hauptfluss. Hohle ▷ ◁ △ ▽ für eine zweite Art von Beziehung (asynchron, optional, Ereignis). Verwende hohle Spitzen nur, wenn das Diagramm zwei Arten benötigt, und benenne die Bedeutung in einer Beschriftung oder einer Notiz, nicht in einer Legende.
  • Beschrifte jeden Pfeil mit dem, was fließt (Protokoll, Ereignis, Daten).
  • Wenn nicht klar ist, welche Rolle eine Box hat: KOMPONENTE für Systemteile, TITEL für den Haupttitel, RAHMEN für alles andere.

Arbeitsablauf

  1. Liste die Komponenten, Rahmen und Pfeile auf, bevor du zeichnest.
  2. Schreibe die Engine nach /tmp/textdiagram/textdiagram.py (vollständiger Quellcode am Ende dieser Datei, kopiere ihn genau). Schreibe sie bei jeder Sitzung neu, damit nie eine alte Version verwendet wird.
  3. Schreibe ein kurzes Python-Skript, das die Engine importiert und das Diagramm erstellt. Verwende die Layout-Hilfsfunktionen, um Boxen zu platzieren (rate keine Koordinaten):
    • Diagram.x_right_of(a, label) — x für die nächste Box rechts von a, mit Platz für die Pfeilbeschriftung.
    • Diagram.x_left_of(a, lines, label) — x für eine neue Box links von a, mit Platz für die Beschriftung.
    • Diagram.y_below(a) — y für eine Box unter a. Mit einer Inline-Beschriftung: Diagram.y_below(a, lines=N).
    • Diagram.x_centered_under(a, lines) — x, damit eine Box zentriert unter a sitzt (erforderlich für arrow_v).
    • Für Routen-Spuren verwende die Kanten der Boxen: a.right + 4, a.bottom + 2.
  4. Führe es aus. Wenn es DiagramError auslöst, korrigiere das Layout gemäß der Meldung und führe es erneut aus.
  5. Füge die Ausgabe genau so in einen Code-Block ein, wie sie gedruckt wurde. Bearbeite sie nicht von Hand. Für eine Änderung bearbeite das Skript und führe es erneut aus.

Beispiel 1: Kopfzeile, Abschnitte, Routen

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()                                                   # max_width=80 ist der Standard
t = d.header(["Order Platform", "Architecture"],
             left=["Acme Inc", "RFC 9000", "Nov 2026"],
             right=["*~~~~~~~~~*", "Deep Dive", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Client"])                             # role="component" ist der Standard
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Gateway"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2,                 # Abschnitte: eine Box, ein Schatten
            [["Auth"], ["Orders"], ["Billing"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Calls")  # S-Form
cache = d.box(D.x_left_of(svc, ["Cache"], "Reads"), svc.rows[1] - 1, ["Cache"])
d.arrow_h(svc, cache, "Reads", row=svc.rows[1])           # an einem Abschnitt befestigen
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Events")  # eine Biegung
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2],   # Schleife: 3 Biegungen
        via=[svc.right + 4, svc.bottom + 2], label="Retry")
print(d.render())

Ausgabe:

┌────────────┐               ╔══════════════════╗            ┌───────────────┐
│  ACME INC  │               ║  ORDER PLATFORM  ║            │  *~~~~~~~~~*  │
│  RFC 9000  │               ║   ARCHITECTURE   ║            │   DEEP DIVE   │
│  NOV 2026  │               ║        ·         ║            │  *~~~~~~~~~*  │
└────────────┘               ╚══════════════════╝            └───────────────┘

┌──────────┐            ┌───────────┐                             ┌─────────┐
│  CLIENT  │── HTTPS ──▶│  GATEWAY  │░                            │  AUDIT  │░
└──────────┘░           └─────┬─────┘░                            └─────────┘░
 ░░░░░▲░░░░░░            ░░░░░│░░░░░░░                             ░░░░▲░░░░░░
      │                       │                                        │
      │                       │                                        │
      │                       └───── CALLS ─────┐                      │
      │                                         │                      │
      │                                         ▼                      │
      │                                 ┌─ SERVICES ────┐              │
      │                                 │  AUTH         │─── EVENTS ───┘
      │          ┌─────────┐            ├───────────────┤░
      │          │  CACHE  │◀─ READS ───│  ORDERS       │░
      │          └─────────┘░           ├───────────────┤░
      │           ░░░░░░░░░░░           │  BILLING      │────┐
      │                                 └───────────────┘░   │
      │                                  ░░░░░░░░░░░░░░░░░   │
      │                                                      │
      └─────────────────────── RETRY ────────────────────────┘

Beispiel 2: Bus, hohle Spitzen, Inline-Beschriftung, freier Text

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()
t = d.header(["Event Bus", "Design"], left=["Acme Inc", "ADR 12", "Nov 2026"],
             right=["*~~~~~~~*", "Draft", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publisher"])
s1 = d.box(36, y - 2, ["Billing"])
s2 = d.box(36, y + 4, ["Audit"])
s3 = d.box(36, y + 10, ["Search"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Events", head="hollow")  # bus, hohle Spitzen
arc = d.box(D.x_centered_under(pub, ["Archive"]), D.y_below(pub, lines=2), ["Archive"])
d.arrow_v(pub, arc, "Nightly\nbackup", inline=True)       # Beschriftung in die Linie geschnitten
d.annotate(46, y + 16, ["At-least-once", "delivery"])     # freier Text, keine Box
print(d.render())

Ausgabe:

┌────────────┐        ╔═════════════╗       ┌─────────────┐
│  ACME INC  │        ║  EVENT BUS  ║       │  *~~~~~~~*  │
│  ADR 12    │        ║    DESIGN   ║       │    DRAFT    │
│  NOV 2026  │        ║      ·      ║       │  *~~~~~~~*  │
└────────────┘        ╚═════════════╝       └─────────────┘

                                    ┌───────────┐
                            ┌──────▷│  BILLING  │░
┌─────────────┐             │       └───────────┘░
│  PUBLISHER  │── EVENTS ───┤        ░░░░░░░░░░░░░
└──────┬──────┘░            │
 ░░░░░░│░░░░░░░░            │
                            │       ┌─────────┐
    NIGHTLY                 ├──────▷│  AUDIT  │░
    BACKUP                  │       └─────────┘░
                            │        ░░░░░░░░░░░
       │                    │
       ▼                    │
 ┌───────────┐              │       ┌──────────┐
 │  ARCHIVE  │░             └──────▷│  SEARCH  │░
 └───────────┘░                     └──────────┘░
  ░░░░░░░░░░░░░                      ░░░░░░░░░░░░


                                              AT-LEAST-ONCE
                                              DELIVERY

API-Referenz

  • D(max_width=80) — Erstelle ein Diagramm; max_width ist das Spaltenlimit.
  • d.box(x, y, lines, role="component"|"frame"|"title", title=None, w=None, align="left") → Box (.x .y .w .h .right .bottom .cx .rows; right/bottom inklusive Schatten). lines ist eine Liste von Zeilen oder eine Liste von Abschnitten (Listen von Zeilen), um die Box zu teilen. box.rows enthält die Pfeilzeile jedes Abschnitts. align="center" zentriert den Text.
  • d.header(title, left=None, right=None, y=0) → Titel-Box. Jedes Argument ist eine Liste von Zeilen. Die Boxen erhalten ihre endgültige x-Position beim Rendern. Ein Header pro Diagramm.
  • d.arrow_h(a, b, label="", row=None, head="filled") — a und b nebeneinander; funktioniert in beide Richtungen. row wählt eine Abschnittszeile (a.rows[i]). head ist "filled" oder "hollow".
  • d.arrow_v(a, b, label="", head="filled", inline=False) — b unter a, zentriert darunter. Eine Beschriftung kann mehr als eine Zeile haben (" "). Mit inline=True, lasse Platz mit Diagram.y_below(a, lines=N).
  • d.route(a, a_side, b, b_side, via=(), label="", label_seg=None, a_row=None, b_row=None, head="filled", inline=False) — Seiten sind "left" "right" "top" "bottom". Die Linie verlässt a_side von a und tritt in b_side von b ein. Sie hat len(via) + 2 Segmente, die sich horizontal und vertikal abwechseln, beginnend mit der Richtung, die a_side verlässt. Jeder via-Wert ist die Spur eines mittleren Segments: ein x für ein vertikales Segment, ein y für ein horizontales Segment. via=[] ist eine Biegung, ein Wert ist zwei Biegungen (S- oder U-Form), zwei Werte sind drei Biegungen (eine Schleife). a_row / b_row wählen eine Abschnittszeile. label_seg wählt das Segment (von 0), das die Beschriftung trägt.
  • d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False) — ein Bus. trunk ist die Spur der gemeinsamen Linie: ein x für linke/rechte Seiten, ein y für obere/untere.
  • d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled") — eine Biegung, eine Kurzform von route. vh: Verlasse den Boden von a, biege in die Seite von b ein. hv: Verlasse die Seite von a, biege nach unten in die Oberseite von b ein. Die Richtung folgt der Position von b.
  • d.annotate(x, y, lines, align="left") → Box (Rolle "text") — freier Text, in Großbuchstaben. lines ist ein str (" " beginnt eine neue Zeile) oder eine Liste.
  • d.text(x, y, s) — roher Text (nicht in Großbuchstaben).
  • d.render() — gibt das Diagramm zurück; platziert den Header; überprüft die Breite und breite Zeichen.
  • Die Engine gibt DiagramError bei Überlappungen, kleinen Lücken, falschen Spurwerten oder Zeilen über der maximalen Breite aus.

Wenn keine Shell verfügbar ist

Zeichne von Hand mit denselben Regeln. Zähle dann die Spalten in jeder Zeile und überprüfe, dass: der rechte Schatten eine Spalte rechts von der Box ist; die untere Schattenzeile eine Spalte rechts vom linken Rand der Box beginnt und in der Schattenspalte endet; alle Boxkanten ausgerichtet sind.

Engine-Quellcode: textdiagram.py

"""textdiagram: Zeichne ausgerichtete Unicode-Boxdiagramme auf einem Zeichenraster.

Stil:
  Alles in Großbuchstaben, außer den Einheiten in KEEP.
  KOMPONENTEN-Box: helle Linien + heller Schatten (░) eine Spalte rechts, eine Zeile darunter.
  TITEL-Box: doppelte Linien, kein Schatten, zentriert über dem Diagramm (wird beim Rendern platziert).
  RAHMEN-Box: helle Linien, kein Schatten (Notiz, Hinweis).
  Header: Titelbox mit optionaler Meta-Box (links) und Stempel-Box (rechts);
  Füllzeilen der Titelbox enthalten einen zentrierten Punkt.
  Abschnitte: Eine Box geteilt durch helle Trennlinien, ein Schatten für die gesamte Box.
  Horizontaler Pfeil: Beschriftung innerhalb der Linie, beide Enden berühren eine Box:  ── BESCHRIFTUNG ──▶
  Vertikaler Pfeil: Beschriftung rechts von der Linie, eine Zeile unter dem Schatten.
  Route: Pfeil mit beliebig vielen Biegungen, festgelegt durch Spurenkoordinaten (via).
  Spitze: gefüllt (▶) oder hohl (▷). fan_out: eine Linie, die sich in mehrere Pfeile aufteilt.
  Beschriftung auf einer vertikalen Linie: neben der Linie oder in sie geschnitten (inline=True).
  annotate: freier Text ohne Box.
"""
import re
import unicodedata

SHADOW = "░"
MIN_DASH = 2  # Striche auf jeder Seite einer Pfeilbeschriftung
HEADER_GAP = 2  # Spalten zwischen den Header-Boxen

# Einheiten, deren Groß-/Kleinschreibung die Bedeutung ändert (MB = Byte, Mb = Bit, ms = Milli, MS = Mega).
# Ein Wort wird nur beibehalten, wenn es genau wie eines dieser Wörter geschrieben ist.
KEEP = {
    "Hz", "kHz", "MHz", "GHz",
    "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
    "kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
    "ms", "µs", "ns",
}

# Box-Zeichen als Sätze von Armen: Wo zwei Pfeillinien aufeinandertreffen, werden die Arme
# zu einem Kreuzungszeichen zusammengefügt (┼, ├, ...).
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
        "├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v): 

…

[nach Kürzung für die Übersetzung]“
}

Verwandte Skills