Yeshwanthyk/viz

Was macht viz?

Ein fester Renderer, assets/viz.js, zeichnet jede Visualisierung. Der Agent schreibt nur Daten in der Grammatik – so kostet eine Visualisierung etwa so viele Token wie der ASCII-Baum, den sie ersetzt. Dafür erhält sie Schritt-für-Schritt-Wiedergabe, einen Knoteninspektor, Kantenverfolgung, Filterung und Pfadkopie.

Wähle die Ansicht

Schreibe Daten, kein HTML: einen == graph-Abschnitt (Knoten, Pfade und eine view:) oder einen Chart-Abschnitt. Wähle je nach Frage des Lesers, lies dann nur die benötigte Grammatik: Grammatik für Graphen, Bäume und Diffs, Charts für == timing, gantt, hist, retries, causes, board, stock und waits.

Wie fließt es?

• Datenbewegung zwischen Komponenten (Verzweigungen, Fallbacks, asynchrone Sprünge, Fehlerausgänge) → view: flow, die Standardeinstellung. „Walk me through“ fügt einen Erzählschwanz hinzu (siehe unten). Beschrifte jede Kante mit dem, was bewegt wird, und deklariere die Kanten in der Reihenfolge ihres Auftretens; die Zahlen folgen.
• Wer handelt, was sendet, was filtert, was ergibt sich → ranks:-Spalten, ein Pfad pro Auslöser, endet mit => result wenn durchkommt und mit =| result wenn gefiltert wird. Teams oder Dienste als Bänder → füge lane: hinzu.
• Anfragen zwischen Diensten über die Zeit → view: seq, mit at:-Zeitpunkten, wenn die Wartezeit relevant ist. Wähle seq über flow, wenn die Reihenfolge der Aufrufe und die Wartezeiten dazwischen der Punkt sind, und flow, wenn die Verzweigungen wichtig sind. Welchen Zustand jeder Dienst nach jeder Nachricht hat → sets: id=*charging unter einer Kante und state: unter einem Knoten.
• Der Lebensweg eines Feldes oder Jobs → view: states, ein Pfad pro Geschichte (!giveup: running > blocked => dead). Ein benutzerorientierter Ablauf fügt einen Startpunkt ([*] -> form), Töne und group-Boxen hinzu (Ansichten).
• Wer wen aufruft → == tree. Ein Aufrufstapel zu einem Zeitpunkt, mit den Werten, die schiefgingen → view: stack und locals:.

Wann, und wie lange?

• Was gleichzeitig läuft: ein Rennen, überlappende Arbeit → == timing, eine Spur pro Arbeiter und ein !window über die Überlappung.
• Warum sich Wiederholungen aufstauten: Backoff, Jitter, der Aufgabepunkt, viele Clients gleichzeitig → == retries, mit policy:.
• Wohin die Latenz einer Anfrage geht und welche Kette sie begrenzt (kritischer Pfad, Spielraum) → == gantt, Balken mit after verketten; budget: zeichnet die Grenze, und was 140ms auf einer geänderten Zeile zeichnet den alten Durchlauf darunter.

Wie viel?

• Wie sich das Volumen aufteilt: eine Verkehrsaufteilung, ein Trichter, wo Anfragen abfallen → view: sankey, mit weight: unter jedem Pfad und Pfade, die abfallen, enden mit =| <exit node>. Verwende sankey über ranks:, wenn das Volumen wichtig ist.
• Ob es der Schwanz oder alles ist (p50 vs p99, eine Latenzregression) → == hist, mit was: für die alte Verteilung.
• Eine Größe über die Zeit gegen Schwellenwerte (Warteschlangentiefe, Verzögerung, belegter Pool), als Bestand-und-Fluss → == stock, mit meter:-Bändern. Für ein sich wiederholendes Muster zeichne ein typisches Fenster und sage, welches.

Warum ist es kaputt gegangen, und wo steckt es fest?

• Wer hält welches Lock und wer wartet darauf, ein Deadlock → == waits; es findet die Zyklen.
• Die vermuteten Ursachen eines Incidents, bestätigt oder ausgeschlossen → == causes, ein Fischgrätendiagramm.
• Arbeitselemente über Phasen (Shards in einem Backfill, Jobs in einer Pipeline), mit WIP-Grenzen und was blockiert ist → == board, ein Kanban.
• Welche Eingaben eine Prüfung liest und welche Auslöser jede frisch halten → == cover nach dem Graphen; eine Writer × Feld-Matrix → columns: <rank>.

Was hat sich geändert?

• Eine Änderung an einem Layout → + und - auf Knoten und Pfaden; der Leser erhält einen Vorher | Beide | Nachher-Umschalter.
• Was eine Änderung an einem Aufrufbaum bewirkt hat → == diff, vom Konverter statt von Hand. <viz> ist das Verzeichnis dieses Skills; die ersten beiden Argumente sind der Basis- und der Head-Referenz (der Basis-Branch eines PRs, dann HEAD); <paths> schränkt den Scan ein:

python3 <viz>/scripts/viz.py calldiff main HEAD --max-depth 4 <paths>   # gibt Basis + == diff aus, unveränderte Unterbäume zusammengeklappt
python3 <viz>/scripts/viz.py calltree --entry submitForm

Füge jeder Ansicht nach Bedarf hinzu:

• Das Warum jedes Schrittes → ein | payload | narration-Schwanz auf Pfaden; jeder wird zu einem Wiedergabeschritt.
• Ein Designdokument, das Szenarien durchspielt → theme drawing, shows: id = text unter Schritten, und ein meter:, wenn eine Zahl den Ausgang bestimmt (Zeichnung).
• Eine Seite, die gespeichert, gedruckt oder geteilt wird → theme paper. Es malt sein eigenes Blatt, daher behalten inline T3-Renderer das Standard-Theme.

Untermauere alles mit Beweisen. Jeder Knoten erhält einen @path:line- und Detailzeilen für Lese-, Schreib- und Fehlerverhalten. Jede Zahl (eine Dauer, ein Gewicht, ein Pegel) stammt aus einem Trace, Log, Query oder dem Code. Markiere alles, was du nicht gelesen oder gemessen hast, mit ?: ein ?-Präfix auf einem Knoten, Pfad, Balken oder Segment und ein # estimate-Hinweis auf einem Bestandspunkt.

Zeige es

T3 Code (die Werkzeugliste enthält html_render): Schreibe die Seite direkt in html_preview, lies die Konsole auf viz:-Parsefehler, übergib dann dieselbe Seite an html_render. Füge viz.js nicht ein.

<!doctype html><script src="https://cdn.jsdelivr.net/gh/Yeshwanthyk/agent-skills@efe8911d3765b764d7f0bf775e395d5201e29b16/skills/viz/assets/viz.js"></script>
<script type="text/viz">
…
</script>

Wenn die Vorschau-Konsole zeigt, dass das Skript nicht geladen werden konnte, falle auf die Seite unten zurück (überall sonst) und gib dem Benutzer den Pfad. Binde viz.js niemals in einen T3-Render ein: es sind etwa 55k Token pro Aufruf.

Überall sonst: Speichere die Daten nach /tmp/viz/<name>.viz, führe dann python3 <viz>/scripts/viz.py html /tmp/viz/<name>.viz --open aus. Es meldet Parsefehler, schreibt /tmp/viz/<name>.html mit eingebettetem Renderer und öffnet es im Browser. Auf pi mit installiertem glimpse öffne die Datei stattdessen dort (pi). Melde den Pfad.

In einer gespeicherten Seite, die in sich geschlossen bleiben muss (eine Seite, die der Benutzer behält oder teilt): Schreibe text/viz-Blöcke, wo die Ansichten hingehören, beende den Body mit <script data-viz></script> und führe viz.py inline page.html aus. Führe es nach einem Update von viz.js erneut aus. Gib einer Bildunterschrift, Tabellenzeile oder einem Glossarbegriff data-viz-id="<Knoten-ID oder Pfadname>" und beim Darüberfahren leuchtet dieser Teil jedes Graphen auf der Seite auf, ohne Seitenskript.

Antwort

Das Bild trägt die Struktur. Die Antwort fügt nur das hinzu, was es nicht zeigen kann: was du nicht verifiziert hast, und das eine, was man zuerst ansehen sollte.

Abschluss

Fertig, wenn das Bild ohne viz:-Fehler rendert, jeder Knoten und jede Zahl belegt oder mit ? markiert ist und du es dort gesehen hast, wo der Leser hinschaut: inline in T3, oder ein Screenshot der geöffneten Seite woanders. Ein Headless-Load, ein curl oder eine saubere Konsole ist kein Sehen; wenn du nicht schauen konntest, sage das, anstatt es als gerendert zu bezeichnen.