repoviz

Was macht repoviz?

Verwandeln Sie eine Codebasis in renderbereite Diagramm-URLs. Jedes Diagramm ist eine einzige https://x-cmd.com/draw URL (flache, prozentcodierte Parameter), die SVG in Browsern, GitHub-READMEs und jedem Markdown-Betrachter rendert. Der Standardmodus schreibt keine lokalen Dateien; Lokaler Export erfolgt nur auf explizite Anfrage über scripts/.

Rendert ≠ wahr: Jeder Knoten und jede Kante trägt Quellnachweise (verifiziert / abgeleitet / unbekannt) – die Ausgabe ist ein überprüfbares Asset, keine KI-Skizze.

Schritt 1 – Absichtsanalyse & Diagramm-Routing

Wählen Sie den oder die Diagrammtyp(en) aus Absicht und Repository-Form. Lesen Sie nur die passenden references/-Datei(en), bevor Sie dieses Diagramm konstruieren.

Benutzerabsicht	Diagramm	Referenz
Systemübersicht, Ordnerhierarchie, Microservices, Tech-Stack	Architektur-Map (/draw/archmap)	references/architecture.md
Request-Lebenszyklus, Funktionsaufrufketten, API-Handshakes	Sequenzdiagramm (/draw/seq)	references/flowchart.md
Verzweigungslogiken, Algorithmen, Auth/Pipeline-Stufen	Flussdiagramm (/draw/mermaid)	references/flowchart.md
Zustandsautomaten, Status, Wiederholungen/Rollbacks	Lebenszyklus (/draw/lifecycle)	references/flowchart.md
Datenpipelines, Abhängigkeits-/Bundle-Gewichtungen, Traffic-Routing	Sankey (?type=sankey)	references/sankey.md
Feature-Bäume, Modultaxonomie	Mindmap (/draw/mindmap)	references/general-charts.md
Roadmaps, Zeitpläne, Release-Pläne	Gantt (/draw/gantt)	references/general-charts.md
Quantitative Repository-Metriken (Sprachsplit, Abdeckung, Wachstum)	Daten-Charts (`?type=pie	hbar
Allgemeines „Visualisiere dieses Repository“	Multi-Diagramm-Suite: 1 archmap-Übersicht + 1 Sankey (Daten-/Abhängigkeitsfluss) oder seq (Kern-Request-Fluss)	die beiden passenden Referenzen

Gleichgrammatik-Geschwister von archmap (siehe references/architecture.md): arch2 (altes Skin). Daten-/Verhaltensmodellierung: uc, dataflow, erd, class – Grammatiken und Live-Beispiele in references/technical-diagrams.md. Nischen-Charts (Treemap, Funnel, Graph, ...): /draw/echarts?d=<url-encoded echarts option JSON>.

Scan-Modi – legen Sie den Scan-Umfang vor dem Lesen des Codes fest (Benutzer kann wählen; Standard aus der Absicht):

Modus	Umfang	Typische Ausgabe
quick	Manifeste, Baum bis Tiefe 2, Einstiegspunkte	1 Übersichtsdiagramm
architecture	Module, Dienste, Abhängigkeitsgraph	archmap (+ Sankey nach Gewicht)
deep-dive	Aufrufketten, Datenfluss, Zustandsautomaten	seq / Flussdiagramm / Sankey-Suite
impact	git diff vs. Basis: geänderte Dateien und deren Abhängige	Änderungsflussdiagramm
full	Alle oben genannten	Repository-Bericht (Suite + Qualitätsbericht)

impact-Modus lädt references/architecture-diff.md (Git-Diff-Delta-Workflow); full-Modus lädt references/codebase-report.md (Standardberichtsstruktur); wiederholte Scans desselben Repositorys können references/incremental-scan.md laden (Opt-in-Cache-Protokoll); Multi-Diagramm- oder nachweisempfindliche Arbeit lädt references/repository-ir.md.

Schritt 2 – Token-disziplinierter Codebase-Scan

1. Lesen Sie zuerst die Root-Manifeste: package.json, go.mod, Cargo.toml, pyproject.toml, docker-compose.yml, plus einen Verzeichnisbaum bis Tiefe 3 und die deklarierten Einstiegspunkte.
2. Lesen Sie niemals jede Quelldatei. Samplen Sie Einstiegsdateien und Routentabellen; fassen Sie Komponenten in hochsignifikante Knoten und Kanten zusammen.
3. Leiten Sie Sankey-Gewichte aus realen Quantitäten ab, wo möglich: Dateigrößen (du -sh), Import-/Referenzzahlen oder Verkehrs-/Kostenzahlen, die der Benutzer liefert.
4. URL-Längen-Schutzvorrichtung: Halten Sie ein Diagramm auf ~15–20 Knoten (~60 Links für Sankey), sodass URLs lesbar und innerhalb der CDN-Grenzen bleiben. Für große Repositories geben Sie eine hochrangige Übersichtsgrafik + ein Diagramm pro Subsystem aus, niemals ein einziges dichtes Mega-Diagramm.
5. Erkennen Sie Sprache und Stack aus den Manifesten und scannen Sie mit dieser Linse: Go → Packages/Interfaces/Goroutinen; TypeScript → Module/Import-Graph/API-Routen; Rust → Crates/Traits/Features; Python → Packages/Dekorateure/Einstiegspunkte.
6. Zeichnen Sie während des Scans Nachweise auf: Jeder Knoten/jede Kante erhält datei[:symbol[:zeilen]] und eine Stufe – verifiziert (im Code gesehen), abgeleitet (aus der Struktur abgeleitet) oder unbekannt (Musterannahme). Markieren Sie niemals verifiziert, ohne die Datei geöffnet zu haben.

Schritt 3 – Erstellen Sie die URL

• Erstellen Sie zuerst das leichte Repository-IR für Suiten (ein gemeinsames Knoteninventar, ein Dokument pro Diagramm); mappen Sie IR → URL zur Codierungszeit. Schema und Validierungs- protokoll: references/repository-ir.md.
• Jede von Ihnen erstellte URL trägt ihre Beschriftungen zum Renderer – wenden Sie die Vertraulichkeitsregel aus Schritt 4 an, bevor Sie sie konstruieren, validieren oder exportieren.
• Grammatik (Knoten/Kanten/Grenzen), Kodierungstabelle, ausgearbeitete Beispiele und typspezifische Grenzen befinden sich in den Referenzdateien. Befolgen Sie sie genau; jedes Beispiel dort ist live getestet.
• Kodierungsgrundlagen: Leerzeichen %20, + %2B, & %26, # %23, </> %3C/%3E, Zeilenumbruch %0A; Trennzeichen ; = , : / @ bleiben literal. Kein Base64.
• Häufige Modifikatoren: title=, scheme=dark|light, t=<style> (typspezifische Familien in Referenzen – arch2/seq sehen am besten mit t=shadcn aus; arch2-Knoten nehmen ein optionales 6. icon-Feld, z.B. n=api;be;API;ECS;r2c0;aws:ecs), w=/h=, v=N zum Fixieren einer gecachten Version, num=all|peak|none (Charts).
• PNG-Ausgabe enthält ein GB2312-Level-1-CJK-Teilset: Seltene Zeichen (z.B. 渲) werden zu Tofu in PNG. SVG hat keine solche Einschränkung – bevorzugen Sie gängige Synonyme für chinesische PNG-Beschriftungen.
• Bei einem 4xx ist der Antworttext Klartext mit einem Korrekturbeispiel – lesen Sie ihn, beheben Sie den fehlerhaften Parameter und wiederholen Sie den Vorgang. Raten Sie nie zweimal.

Schritt 4 – Ausgabebereitstellung

Standardmodus – keine Dateischreibvorgänge. Antworten Sie mit, pro Diagramm:

### <Diagrammtitel>
![<titel>](<draw-url>)
*[Interaktive Vorschau](<draw-url>)* · [Im Editor öffnen](<explore-url>)

- <Aufzählungspunkt: was das Diagramm zeigt – Ebenen, kritischer Pfad, schwerste Flüsse>
- <Aufzählungspunkt: bemerkenswerte Kopplung / Single Points of Failure / Eigentumsgrenzen>

• <explore-url> schreibt /draw?type=X&q → /draw/explore?type=X&q und /draw/<name>?q → /draw/explore/<name>?q um – der integrierte interaktive Editor von draw; verlinken Sie ihn, bauen Sie ihn nicht neu.
• 2–5 prägnante Aufzählungspunkte pro Diagramm. Das Bild ist das Lieferobjekt; die Aufzählungspunkte fügen Beurteilung hinzu.
• Vertraulichkeit: Rendering – und L1-Validierung sowie export.sh-Downloads – senden Diagrammbeschriftungen (bei Flussdiagrammen den gesamten Programmtext) an den x-cmd.com- Renderer als URL-Parameter; diese können in Serverzugriffsprotokollen auftauchen (Prozentcodierung ist keine Verschlüsselung), und Markdown-Bild-Einbettungen können von Clients oder Proxys automatisch abgerufen werden. Lokaler Export vermeidet dies nicht – das Rendern wird dennoch von x-cmd.com angefordert. Für vertrauliche Repositories warnen Sie den Benutzer und holen Sie die ausdrückliche Zustimmung ein, bevor Sie rendern, validieren oder exportieren – oder rendern Sie vollständig offline über eine lokal installierte Draw-CLI.

Schließen Sie eine Suite mit dem Qualitätsbericht ab (nur echte Zählungen – niemals erfinden):

Repository-Analyse — <repo> (<scan_mode>, <commit>)
Inspizierte Dateien: N | Module: N | Beziehungen: N
Nachweise: verifiziert N · abgeleitet N · unbekannt N
Validierung: L1 bestanden|übersprungen (Datenschutz) · L2 bestanden · L3: N ungelöst (unten markiert)

L1 ist nicht automatisch – es ruft die URL ab, d.h. es sendet das Diagramm an x-cmd.com. Führen Sie es für vertrauliche Repositories nur mit ausdrücklicher Zustimmung des Benutzers aus (Schritt-4-Vertraulichkeitsregel); andernfalls melden Sie L1 übersprungen (Datenschutz). Markieren Sie jedes unbekannt unter seinem Diagramm. Für explizite „Validieren“-Anfragen oder Vor-Export-Prüfungen: bash scripts/validate.sh <urls...> (L1-Rendering) und bash scripts/validate.sh --ir <ir.json> (L2-Struktur). L3 ist Ihr erneutes Lesen der zitierten Dateien.

Exportmodus – nur wenn der Benutzer ausdrücklich sagt „lokal speichern“, „SVG/PNG herunterladen“, „Bild exportieren“, „Kurzlink“, „dies in meine README einfügen“ oder „HTML-Bericht erstellen“:

bash scripts/export.sh "<draw-url>" "<out.svg|png>"        # einzelner Download
bash scripts/export.sh --batch <manifest.tsv>              # viele: "<url>\t<out>" pro Zeile, # Kommentare
bash scripts/shorten.sh <type> '<d-schema json>' [title]   # permanent /draw/c/<hash> (?type= Charts nur)
bash scripts/build_html.sh "<title>" "<out.html>" '<json>'  # eigenständiger Bericht (+ optional ev Nachweise)
bash scripts/inject_readme.sh "<README.md>" '<json>'       # Diagramme zwischen repoviz-Markern einfügen/aktualisieren

• export.sh lädt über curl herunter (Fallback: bereits lokal installierte CLIs – es ruft nie Pakete ab oder installiert sie); .png-Ziele erhalten automatisch &format=png (fügen Sie &scale=2|3 für höhere Auflösung hinzu; übergeben Sie scheme=dark – PNG standardmäßig hell). Batch-Modus: eine url<TAB>output pro Zeile, #-Kommentare erlaubt; beendet mit Fehler wenn ein Element fehlschlägt.
• shorten.sh POSTet die Chartdefinition (das ?d= JSON-Schema) an x-cmd.com – Ratenbegrenzung ~30/min/IP. Nur die ?type=-Familie akzeptiert POST; Knoten-/Kanten-Diagramme (/draw/archmap, /draw/seq, ...) geben 405 zurück – behalten Sie ihre vollständigen URLs. Die zurückgegebene /draw/c/<hash> rendert mit GET und ist permanent. Führen Sie es nur auf expliziten Benutzerwunsch aus: Die gespeicherte Definition ist permanent und öffentlich für jeden, der den Link hält (Schritt-4-Vertraulichkeitsregel).
• build_html.sh nimmt ein JSON-Array von {"title","url","note"[,"ev"]}-Objekten (url beschränkt auf https://x-cmd.com / https://www.x-cmd.com Draw-Render-URLs; ev optional, codiert "node|datei|symbol|zeilen|level;..." – rendert eine filterbare Quell-Nachweis- Tabelle) und gibt einen eigenständigen, dark/light-responsiven Bericht aus: Seitenleisten-Navigation, Zoom, Vollbild, URL-Kopieren-Schaltflächen, druckbar als PDF. Alle Werte sind HTML-escaped. Beispiel-Payload: [{"title":"Architektur","url":"https://x-cmd.com/draw/archmap?...","note":"3 Ebenen; Gateway ist der einzige Einstieg","ev":"api|src/api.ts|createServer|12-40|verifiziert"}]
• inject_readme.sh ist idempotent: hängt einen <!-- repoviz:start --> … <!-- repoviz:end -->-Block (Markdown-Bild + Notiz pro Diagramm) bei erster Verwendung an, ersetzt ihn bei späteren Ausführungen an Ort und Stelle – Diagramme werden zu lebenden Assets im Repository.
• Nach dem Export geben Sie die gespeicherten Pfade aus und fahren mit der Ausgabe des Markdown-Blocks für den Chat fort, damit der Benutzer beides erhält.

Regeln

• Markenneutral: Präsentieren Sie Ergebnisse als repoviz-Diagramme; benennen Sie die Render-URLs nie um oder umbrechen Sie sie.
• Ein Scan, viele Diagramme: Verwenden Sie das Knoteninventar über die Suite hinweg wieder, anstatt das Repository pro Diagramm erneut zu lesen.
• Bevorzugen Sie weniger, gut gewählte Knoten vor Vollständigkeit; klappen Sie Details in sub- Beschriftungen und Begrenzungsboxen ein.
• Nachweis oder es ist nicht passiert: Jeder Knoten/jede Kante ist verifiziert, abgeleitet oder als unbekannt markiert – niemals erfunden. Behalten Sie die IR-/Renderer-Trennung bei, damit Suiten, Berichte und zukünftige Architektur-Diffs ein gemeinsames Inventar haben; das Rendern bleibt ein austauschbarer Adapter.
• URL-als-Daten inkrementelle Bearbeitungen: Ein vorhandenes repoviz-Diagramm ist vollständig durch seine URL definiert – verwenden Sie niemals Vision- oder Bildlesetools, um es zu inspizieren. Dekodieren Sie die URL aus dem Markdown, vergleichen Sie seinen Knoten-/Kantensatz mit dem aktuellen Code und geben Sie die aktualisierte URL an Ort und Stelle aus, wobei Knoten-IDs, Beschriftungen und Layout-Konventionen erhalten bleiben.