szcharlesji/tikz-explorer-book

TikZ-Explorer-Buch

Du erstellst ein Buch, das jemand erkundet: eine einzelne Webseite, deren Startseite eine Concept Map des gesamten Fachgebiets ist, und deren Kapitel jeweils eine Idee mit sorgfältig berechneten TikZ-Figuren sichtbar machen. Der Leser möchte zuerst die Landschaft sehen, die Punkte verbinden, und dann dort tief einsteigen, wo er möchte.

Visualisierung hat Priorität. Ein Kapitel sind seine Figuren. Text führt zu einer Figur hin und zieht Schlussfolgerungen aus ihr; er ersetzt niemals eine Figur, die dasselbe zeigen könnte. Wenn du Zeit abwägst, behalte die Figurenqualität und kürze den Text.

Dieses Skill orchestriert; die Figurenerstellung lebt in zwei verwandten Skills, die sich eine visuelle Sprache teilen (dlviz.sty, Farbe = Rolle). Sie werden zusammen ausgeliefert und befinden sich neben dem Ordner dieses Skills; unten steht <skills> für den Ordner, der alle drei enthält (der übergeordnete Ordner dieses Skills, wo auch immer er installiert ist):

• tikz-dl-visualizer (<skills>/tikz-dl-visualizer/): statische Figuren. Seine Stil-Datei, Archetypen und das Render-Skript definieren, was eine gute Figur ausmacht. Die meisten Figuren in einem Buch sind statisch.
• tikz-live (<skills>/tikz-live/): Live-Figuren. Ein TikZ-Gerüst, kompiliert von pdflatex, plus eine kleine JS-Spezifikation, die den beweglichen Teil zeichnet, so dass der Leser einen Startpunkt ziehen, eine Temperatur schieben oder ein Token überfahren kann, während jedes Label reines TeX bleibt. Das Buch bindet sie ein und sie folgen seinem Hell/Dunkel-Design.

Lies beide SKILL.md-Dateien einmal vor der Planung, damit du weißt, was eine gute Figur ist und wann Interaktion ihren Platz verdient.

Was du lieferst

<book>/
├── book.json            Titel, Teile, Kapitel-IDs, Farbrollen, Karten-Einstellungen
├── SPEC.md              der Vertrag, dem jeder Kapitel-Autor folgt
├── chapters/00-front.html   Hero, Karten-Slot, Leseanleitung, Konventionen, Legende
├── chapters/<cid>.html  ein <section class="chapter"> pro Kapitel
├── figs/<cid>-<slug>.tex/.png/-light.png/.pdf
├── figs/<cid>-<slug>.js     Nur Live-Figuren: die Spezifikation; fig.sh schreibt auch
│                            .live.html (vom Build eingebunden), .html (eigenständig)
│                            und <slug>.<snapshot>.png (zur Überprüfung)
├── scripts/<cid>-<slug>.py  das Python hinter jeder Zahl einer Figur
├── map/data.json        Concept Map: Familien, Konzepte, Schlüsselwerke, Links, Tour
├── tools/               build.py, shell.html (Seitendesign), fig.sh, dllive.js (Live-Laufzeit)
└── index.html, preview.html   erstellte Seite (index.html veröffentlichen)

Voraussetzungen: Eine TeX-Installation mit TikZ/pgfplots (pdflatex), Ghostscript oder poppler für PNGs, ImageMagick für Kontaktbögen, uv (oder Python mit numpy/scipy) für Figurenzahlen und für Live-Figuren node plus PyMuPDF (uv run --with pymupdf, was fig.sh für dich erledigt). Die Seite lädt MathJax (jsDelivr) und d3 (cdnjs). Überprüfe frühzeitig which pdflatex gs magick uv node; falls TeX-Pakete fehlen, sage dem Benutzer den tlmgr install-Befehl, anstatt sie zu installieren.

Arbeitsablauf

1. Verstehe die Quelle und den Leser

Lies die Quelle (rufe den Kurskalender oder Lehrplan ab, liste die Lektüre auf). Dann bestimme den Leser: was er bereits weiß (überspringe die Grundlagen, die er kennt, zeichne aber die Grundlagen trotzdem gut) und was er anstrebt (einen Job, eine Prüfung, eine Forschungsrichtung). Das Ziel bestimmt die Form des Buches:

• Teil I folgt der Quelle, ein Kapitel pro Sitzung oder Einheit. Jedes geht tief auf eine Idee ein, anstatt alles zusammenzufassen.
• Teil II ist ein Toolkit für das Ziel des Lesers, z.B. "Was ein Videogenerierungs-Forscher wissen muss": die übergreifenden Grundlagen, die die Quelle voraussetzt oder überspringt, praktisch und aktuell, mit echten Zahlen. Überspringe Teil II, wenn der Leser kein über die Quelle hinausgehendes Ziel hat.
• Die Startseite ist eine Concept Map: das große Ganze vor jeder Tiefe.

Frage den Benutzer nur, wenn das Ziel wirklich unklar ist; ansonsten gib deine Einschätzung in einem Satz und lege los.

2. Plane Kapitel um Figuren herum

Schreibe für jedes Kapitel eine Kurzbeschreibung: den tiefgehenden roten Faden (ein Satz), 2–3 Figuren mit dem, was jede sichtbar machen muss, welchen Archetyp und was zu berechnen ist. Dies ist der wichtigste Schritt. Kurzbeschreibungen, die den Mechanismus benennen, ergeben großartige Figuren; Kurzbeschreibungen, die ein Thema benennen, ergeben Kasten-Diagramme.

• Schwach: "Figur über classifier-free guidance".
• Stark: "1-D Zwei-Klassen-Mischung; integriere die geführte ODE mit exakten Geschwindigkeiten für w = 0, 1, 2, 4; kleine Multiples der resultierenden Dichten gegen p(x|c) und die geneigte Dichte, zeige, dass Guidance über das Ziel hinausschießt."

Gute Figurenthemen: ein Mechanismus in Aktion (Pfade, Flüsse, Aktualisierungen), ein Vorher/Nachher, ein Vergleich zweier Methoden bei identischen Eingaben, Formen und Zählungen (Tensor-Formen, Token-Anzahlen, FLOPs), ein numerisches Experiment, dessen Ergebnis der Punkt ist. Jedes muss berechenbar sein: der Autor wird jede Zahl in Python produzieren.

Entscheide, welche Figuren live sind. Eine Figur verdient Interaktion, wenn der Leser lernt, indem er etwas ändert und den Mechanismus reagieren sieht, und zwar so, wie es ein statisches Bild oder kleine Multiples nicht gleich gut zeigen können. Schreibe den Interaktionssatz in die Kurzbeschreibung: "der Leser zieht X / schiebt Y / überfährt Z und sieht W". Budget: etwa eine Live-Figur pro Kapitel, für den Hauptmechanismus des Kapitels; alles andere statisch. Gute Kandidaten: Optimierer-Pfade (Start ziehen, β schieben), Attention oder Convolution (eine Zeile oder Zelle überfahren), ein Guidance-Gewicht oder Temperatur-Sweep, eine lineare Abbildung (Basisvektoren ziehen), Sampling-Schritte (abspielen). Schlechte: Pipelines, Architekturdiagramme, alles, wo kleine Multiples den Trend bereits zeigen.

• Live-Kurzbeschreibung: "1-D Zwei-Klassen-Mischung; der Leser schiebt das Guidance-Gewicht w von 0 auf 6 und sieht, wie die geführte Dichte über das geneigte Ziel hinausschießt; ein Play-Button integriert die ODE Schritt für Schritt; Zahlen: KL zum Ziel, live."

Entscheide auch, einmal für das ganze Buch: die Farbrollen (welche Farbe bedeutet was; setze sie in book.json, damit Figuren, Prosa-Mathematik und die Legende übereinstimmen), die Konventionen, bei denen das Fachgebiet unterschiedlicher Meinung ist (Zeitrichtung, Vorzeichen, Notation und Symbole, die in verschiedenen Kapiteln unterschiedliche Dinge bedeuten, wie z.B. (v) für die Geschwindigkeit des Impulses und das zweite Moment von Adam), und die Kapitel-IDs (w01..., v01...; der Buchstabe wird das Figuren-Label-Präfix, W3.2, V5.1).

3. Gerüst aufbauen

python3 <skill>/scripts/init_book.py <book> --title "Buchtitel" --sub "Quelle · Semester"

Bearbeite book.json (Teile, Kapitel-IDs, Rollen) und chapters/00-front.html; lies jede zuerst, da die Datei-Werkzeuge sich weigern, eine Datei zu überschreiben, die du nicht gelesen hast. Die Vorlage hat generische Deep-Learning-Rollen (Eingabe, versteckt, latent...): ersetze sie durch die des Fachgebiets (für Optimierer: Iteration, Gradient, Geschwindigkeit, Verlust...). Schreibe <book>/SPEC.md aus references/author-spec.md, fülle jeden «…»-Block aus: Leser, Teile, Rollentabelle, Konventionen, Kapitelkarte. Autoren sehen nur SPEC.md und ihre Kurzbeschreibung, also muss SPEC.md für sich allein stehen können. Schreibe es auch, wenn du das Buch selbst verfasst: es ist der Ort, an dem die Konventionen für spätere Kapitel und spätere Sitzungen leben.

Bevor du jemanden startest, rendere eine Wegwerffigur mit bash <book>/tools/fig.sh, um zu beweisen, dass die TeX-Pipeline funktioniert, und, wenn der Plan Live-Figuren vorsieht, auch eine Live-Figur: kopiere <skills>/tikz-live/assets/examples/momentum/momentum.{tex,js} nach figs/_test/, führe bash <book>/tools/fig.sh figs/_test/momentum.tex aus, dann rm -rf <book>/figs/_test (seine Zwischendateien leben in figs/_test/.dllive/, also bleibt nichts zurück). Das beweist, dass node und PyMuPDF funktionieren und platziert tools/dllive.js am richtigen Ort. Eine kaputte Pipeline, die von neun parallelen Autoren entdeckt wird, kostet neunmal so viel.

4. Delegiere die Kapitel

Für einen vollständigen Kurs (10+ Kapitel) starte parallele General-Purpose-Subagents, die jeweils 2–4 zusammenhängende Kapitel besitzen (etwa 5–7 Figuren). Jeder Prompt sagt: lies zuerst <book>/SPEC.md und folge ihr; die Kapitel-IDs, die er besitzt; pro Kapitel die Sitzungsmetadaten, Papiere, den tiefgehenden roten Faden und die Figuren-Kurzbeschreibungen; rendere, schaue, korrigiere, dann berichte gemäß SPEC Abschnitt 5. Gruppe zusammenhängende Kapitel unter einem Autor, damit geteilte Figuren konsistent bleiben (z.B. dynamisches OT mit OT-Kopplungen).

Nutzungslimits sind real: neun Autoren auf einmal können ein Sitzungslimit mitten im Lauf erschöpfen. Wenn Agenten mit einem Rate-Limit-Fehler anhalten, bleiben ihre Dateien erhalten. Setze jeden mit SendMessage fort ("mache da weiter, wo du aufgehört hast; überprüfe, was du bereits gemacht hast"), sobald das Limit zurückgesetzt ist, anstatt neue Agenten zu starten. Für große Bücher erwäge das Starten in zwei Wellen.

Für ein kleines Buch (ein Thema, 3–5 Kapitel) überspringe Subagents und schreibe es selbst, befolge aber trotzdem SPEC.md.

5. Während die Autoren zeichnen: Frontmatter und die Karte

Schreibe chapters/00-front.html (Hero, Leseanleitung, die Konventionen, die <!--ROLES-->-Legende, optional eine Tabelle, die die Quelle abbildet, z.B. den Kurskalender mit Kapitel-Links) und map/data.json. Lese references/concept-map.md für das Schema und wie man Familien, Knoten, Beziehungen und die Tour auswählt. Die Karte ist ein Überblick: was jede Idee ist, wo sie sitzt, wie sie zusammenhängt und welches Kapitel tiefer geht. Erkläre dort keine Mechanismen.

6. Überprüfe, während Berichte eintreffen

Jeder Bericht listet die Ein-Ideen-Sätze seiner Figuren und seine unbelegten Behauptungen auf. Öffne selbst die wichtigsten Figuren (den Hauptvergleich, alles, was der Benutzer namentlich angefragt hat) und überprüfe sie anhand der Fakten, die du kennst. Sende konkrete Korrekturen an den Autor zurück, der sie gezeichnet hat.

7. Zusammenbauen, überprüfen, lesen

python3 <book>/tools/build.py
python3 <skill>/scripts/check_book.py <book> --sheet

Dann folge references/qa-and-publish.md: Kontaktbogen-Ansicht, Browser-Prüfungen (Mathematikfehler, Handybreite-Überlauf, Karte, Hellmodus, Live-Figuren: alle eingebunden, Ziehen und Überfahren funktionieren, der Theme-Umschalter färbt sie neu), und lies den Text jedes Kapitels vor der Veröffentlichung. Korrigiere Metadaten-Fehler (Sitzungsnummern, Daten), die Autoren aus deinen Kurzbeschreibungen übernommen haben.

Überspringe die Browser-Prüfung nicht. Die statischen Checks können das JavaScript der Seite nicht ausführen, und die wichtigsten Fehler sind still: eine Karte, die nie rendert, Mathematik, die das Setzen einstellt. Wenn du wirklich keinen Browser öffnen kannst, sage dies bei der Übergabe und liste die Browser-Prüfungen als nicht erledigt auf.

8. Veröffentlichen

Veröffentliche <book>/index.html als ein Artefakt mit jedem Figuren-PNG als unterstützende Datei (check_book.py --files-json gibt die Liste aus; Live-Figuren sind in die Seite eingebunden, daher werden ihre PNGs ausgelassen), oder übergebe den Ordner, wenn kein Artefakt-Werkzeug existiert. Sage dem Benutzer, was in jedem Teil ist, was unbelegt ist, welche Figuren Illustrationen und keine berechneten Ergebnisse sind und wie man neu erstellt (python3 tools/build.py) oder eine Figur neu rendert.

Spätere Anfragen

Bearbeite denselben Ordner und veröffentliche denselben Dateipfad neu, damit der Link gleich bleibt: füge ein Kapitel hinzu (hänge seine ID in book.json an), erweitere die Karte (bearbeite map/data.json) oder ändere das Design (bearbeite tools/shell.html). Behalte die Korrekturen aus references/qa-and-publish.md §3 im Auge, wenn du die Shell oder map.js berührst.

Referenzdateien

• references/author-spec.md — die Vorlage für SPEC.md, der Vertrag der Kapitelautoren (Figurenregeln, HTML-Fragment-Format, Zitierregeln).
• references/concept-map.md — map/data.json-Schema und wie man eine Karte schreibt, die die Punkte verbindet.
• references/qa-and-publish.md — Prüfungen, Browser-Snippets, bekannte Fallstricke, die bereits in der Vorlage behoben sind, Veröffentlichung.
• assets/template/ — das Buchskelett, das init_book.py kopiert.