KI-Debug-Bridge

Die KI ist stark darin, gesamten Code zu lesen und Hypothesen zu bilden, aber sie kann die Laufzeit nicht direkt beobachten. Deshalb wird Debugging zu einer langsamen Staffel: „KI rät → Mensch führt aus → Mensch kopiert den Fehler → KI rät erneut”.

Die KI-Debug-Bridge nimmt den Menschen aus dieser Staffel heraus. Wenn du eine standardisierte strukturierte Debug-Zeile (@BLYCK@ {json}) in den Code einbaust, saugt Blyck die Ausgabeströme aller Ziele ein und füttert die KI in einem einheitlichen Format. Debugging wird so zu „KI entwirft ein Experiment → führt es aus → beobachtet das strukturierte Ergebnis direkt → korrigiert”. Das gilt einheitlich für Web, Desktop, Mobile und Konsole.

Warum das nötig ist

Probleme des klassischen Log-Debuggings	Inhalt
Langsam	KI rät → Mensch führt aus → Mensch kopiert den Fehler → KI rät erneut (der Mensch klemmt mitten in der Staffel)
Verlustbehaftet	Nur Teile der Konsole werden kopiert, intermittierende Bugs verpassen den entscheidenden Moment
Unstrukturiert	Die KI parst rohe Stacktraces / gemischte Logs rätselnd
Plattform-uneinheitlich	Web-Konsole / logcat / os_log / stdout … überall ein anderer Ansatz

Die zentrale Einsicht ist eine einzige Frage — „Fließt die Ausgabe der App in einen Textstrom, den Blyck besitzt (PTY · Terminal · SSH · logcat · Logdatei)?” Meist lautet die Antwort „ja”, und selbst zur einzigen Ausnahme, der Browser-Konsole, hat Blyck bereits einen Kanal.

Wire-Format — die strukturierte Debug-Zeile

Plattformunabhängig: eine Zeile mit Markierung + JSON.

@BLYCK@ {"label":"after-add","vals":{"qty":3,"total":null},"level":"debug","loc":"cart.js:42"}

Feld	Pflicht	Beschreibung
label	✅	Probe-Name
vals		Zu beobachtende Werte (Objekt). Ist es kein Objekt, wird es in {value:…} gewickelt
level		debug · info · warn · error · assert (Standard debug)
loc		Datei:Zeile (optional)

Blyck stempelt zum Erfassungszeitpunkt

ts (Zeitstempel) · source (terminal/preview) · sessionId werden nicht ins Wire-Format aufgenommen. Blyck hängt sie an, sobald es das Log erfasst (vermeidet Uhr- und Umgebungsunterschiede). Die Markierung @BLYCK@ unterscheidet sie von gewöhnlichen Logs, sodass der Parser sie exakt herausgreift; und selbst bei kaputtem JSON bleibt es als level:warn + Originaltext (raw) erhalten, um Verluste zu verhindern.

Helfer-API — die zwei Funktionen, die du in den Code einbaust

Es gibt nur zwei Konzepte.

• blyckDbg(label, vals) — gibt Werte aus (Probe).
• blyckAssert(cond, label, vals) — prüft eine Annahme und löst bei Verletzung ein level:"assert"-Ereignis aus.

Das Tool debug_shim(lang) liefert für 11 Sprachen einen Thin-Shim (je ~5 Zeilen) — js/ts · python · bash · go · rust · java · csharp · dart(flutter) · kotlin · swift · c. Alle bieten dbg + assert.

Automatische Deaktivierung im Release

Jeder Shim wird auf das native debug-only-Konstrukt der jeweiligen Sprache abgebildet (JS if (BLYCK_DEBUG) DCE, Python if __debug__:, Go-Build-Tags, Rust cfg(debug_assertions), Swift #if DEBUG, Kotlin BuildConfig.DEBUG usw.). In Release-Builds wird er automatisch entfernt/deaktiviert, sodass die Laufzeitkosten 0 betragen. → siehe Deployment-Gate.

Capture — zwei Pipes, ein Buffer

Pipe A — gemeinsamer Parser für Blyck-eigene Ströme

Aus allen Textströmen, die Blyck startet oder verbindet — Terminal-PTY · SSH-Shell · adb logcat usw. —, extrahiert und parst Blyck die @BLYCK@ {json}-Zeilen und speichert sie in einem strukturierten Ringpuffer (Obergrenze 1000, FIFO). Gewöhnliche Nicht-Probe-Ausgaben fließen in das Error-Marker-Parsing von Run & Observe (Rollentrennung).

Pipe B — Browser-Konsole

Die in der Webview eingeschlossene Browser-Konsole wird von der Konsolensammlung der Live Preview aufgenommen und in denselben Buffer normalisiert. Auch browserseitig genügt eine Zeile console.log("@BLYCK@ …").

→ Da beide Pipes in denselben Buffer münden, ist das Format, das die KI sieht, unabhängig vom Ziel identisch.

Plattformspezifische Log-Ströme

Was ein „Plattform-Adapter” genannt wird, ist in Wahrheit nur das Umleiten des Plattform-Logs ins Blyck-Terminal. Sobald der Strom im Terminal läuft, werden @BLYCK@-Zeilen automatisch erfasst.

Ziel	Log in den Blyck-Strom	Verarbeitung
Konsole / CLI / Backend	Terminal stdout/stderr	Pipe A
Android	adb logcat	Pipe A
iOS	idevicesyslog / os_log	Pipe A
Flutter	flutter run oder flutter logs (Mobile · Desktop vereint)	Pipe A
Remote (SSH)	SSH-Shell-Ausgabe	Pipe A
Webserverseitig (SSR · Dev-Server)	Prozess-stdout	Pipe A
Web-Browserseitige Konsole	Webview-Konsole	Pipe B

KI-Tools (MCP) — 5 Stück

Tool	Berechtigung	Rolle
debug_read(filter?)	Lesen (auto)	Liest strukturierte Debug-Ereignisse direkt (0× menschliches Copy-Paste). filter: label · level · loc · source · sessionId · paneId · sinceTs · sinceSeq (inkrementelles Polling) · limit
debug_shim(lang)	Lesen (auto)	Gibt den sprachspezifischen blyckDbg/blyckAssert-Helfer-Quellcode zurück (inkl. automatischem No-op-Guard im Release)
debug_probe(path, line, label, expr)	Bestätigung	Fügt an Datei:Zeile eine formatgarantierte @BLYCK@-Probe-Zeile ein (js/ts · python · dart · bash, lokal)
debug_release_check(path)	Lesen (auto)	Rekursiver Verzeichnisscan → meldet verbliebene @BLYCK@-Stellen (mit removable-Kennzeichnung)
debug_strip(path)	Bestätigung	Entfernt nur die Ausgabe-Statements mit @BLYCK@ gesammelt (lokal, dreifaches Sicherheitsnetz)

Der Wert von debug_probe

Der Kern von debug_probe ist die Formatgarantie, die den Unfall verhindert, dass „die KI ein Escape von Hand falsch setzt und debug_read es nicht erfasst”. Für eine schnelle Einzel-Capture wird auch ohne Helfer eine Zeile exakt eingefügt.

Zwei Betriebsmodi

Die Erfassung ist vollständig in Echtzeit (sobald ein Strom eintrifft, wird er gepuffert). Es gibt zwei Reaktionsweisen der KI.

Modus A — aktive Debug-Schleife (während der Arbeit)

Innerhalb eines Turns: Probe einbauen → App ausführen → live debug_read → bewerten → korrigieren → erneut ausführen → erneut beobachten. Der Mensch fällt aus der Fehler-Staffel heraus, und die KI dreht die Schleife aus Bearbeiten, Ausführen, Beobachten und Korrigieren allein. Der Kern, der Trial-and-Error abtötet.

Modus B — automatische Untersuchung (wenn die App im Lauf abstürzt)

Sobald ein @BLYCK@ mit level:error oder assert eintrifft, klinkt sich die KI ungefragt automatisch in den aktiven Chat ein und untersucht die Ursache. Es fühlt sich an wie „ein Breakpoint, der die KI ruft, wenn eine Laufzeit-Invariante verletzt wird”.

Modus B ist standardmäßig AUS — automatische KI-Turns kosten

Da die automatische Untersuchung Token-Kosten verursacht, ist sie durch 4 Sicherungsschichten gebunden und standardmäßig deaktiviert.

1. Standardmäßig AUS (Opt-in) — nur über die Checkbox im KI-Einstellungspanel oder den 🔔-Button im Live-Debug-Panel aktivierbar (Einstellung ist persistent)
2. Globales Rate-Limit — maximal 3 pro 60 Sekunden
3. Duplikat-Unterdrückung — gleiches label+loc hat 120 Sekunden Cooldown
4. Nur im Leerlauf — antwortet die KI gerade, wird übersprungen (das Ereignis bleibt im Buffer)

Die KI starrt nicht ständig auf den Strom

Die KI schaut nicht in jedem Moment in die Logs. Sie sieht sie innerhalb der Arbeitsschleife (Modus A) oder wenn ein Ereignis sie weckt (Modus B). Keine Token für untätige Ausgaben zu verbrauchen, ist sogar effizienter.

Live-Debug-Panel

Mit Ctrl+Shift+D umschaltbar. Es zeigt den strukturierten @BLYCK@-Strom in Echtzeit und bietet Filter nach label · loc · level · source, Pause·Leeren sowie den 🔔-Auto-Untersuchungs-Toggle (Modus B).

Da der Mensch denselben Buffer sieht, den die KI liest, wird neben dem Gesprächsfenster transparent sichtbar, „was die KI gerade beobachtet und behebt”.

Szenario — Warenkorb-Summen-Bug

1. Nutzer: „Behebe den Warenkorb-Summen-Bug”
2. KI: fügt an verdächtigen Stellen blyckDbg('after-add', {qty, total}) · blyckAssert(total > 0, 'total-positive', …) ein
3. KI: App ausführen (Terminal oder Vorschau) → Ablauf mit live debug_read beobachten
4. Assert schlägt fehl → die KI sieht Werte und Ort im selben Moment komplett → korrigiert sofort → führt erneut aus
5. Der Nutzer schaut im Debug-Panel + Gesprächsfenster in Echtzeit zu
6. Fertig → beim Deployment werden die Proben automatisch deaktiviert

Deployment-Gate — damit keine einzige Probe zurückbleibt

Prinzip: Proben sind rein für die Entwicklung, beim Deployment automatisch No-op/entfernt. Keine manuelle Reinigung.

1. Release-Flags (NODE_ENV=production · python -O · Build-Tag-Entfernung · NDEBUG …) → der Shim wird in das native Debug-Konstrukt kompiliert und automatisch deaktiviert. Selbst wenn die Markierung zurückbleibt, läuft sie im Release nicht — das wichtigste Sicherheitsnetz.
2. debug_release_check(path) — meldet per rekursivem Scan die verbliebenen @BLYCK@-Stellen und kennzeichnet pro Zeile, ob es sich um ein Ausgabe-Statement (Entfernungsziel) handelt.
3. debug_strip(path) — führt die Reinigung aus. Dreifaches Sicherheitsnetz:
   • Nur Ausgabe-Statements entfernen — nur Zeilen, in denen @BLYCK@ in einem print/log/console-Aufruf steht. Kommentare, String-Konstanten, Dokumentation und Helfer-Aufrufe bleiben erhalten
   • Shim-Definitionsdatei bewahren — das Löschen der Ausgabezeilen im Helfer-Inneren würde die Datei zerstören, daher wird die Datei komplett übersprungen
   • Truncate-Guard — große Dateien, die die Lese-Obergrenze überschritten haben und abgeschnitten wurden, würden beim Zurückschreiben Daten verlieren, daher übersprungen

Warum No-op der Standard ist

Nicht debug_strip (Entfernen), sondern ein gegate-ter No-op (Deaktivierung) ist der Standard. Denn nur durch Setzen des Flags lassen sich die Proben für Produktions-Debugging wiederbeleben.

Einschränkungen

• debug_probe (automatisches Einfügen) unterstützt derzeit nur lokale Dateien + js/ts · python · dart · bash. Bei kompilierten Sprachen (go · rust · java · c# usw.) und Remote-Dateien (SFTP) hänge die Helfer per debug_shim selbst an.
• Von den 11 Shims wurden 8 (js · python · bash · go · rust · java · csharp · dart) durch tatsächliches Kompilieren und Ausführen verifiziert; c · kotlin · swift durchliefen mangels Build-Toolchain nur eine Ausgabeprüfung.
• Die KI starrt nicht ständig auf den Strom (nur Modus A · B). Modus B (automatische Untersuchung) ist standardmäßig AUS; berücksichtige beim Aktivieren die Token-Kosten.
• Damit die Markierung nicht zerbricht, gib nach @BLYCK@ nur reines JSON aus (z. B. mischen sich in PowerShell Anführungszeichen-Reste hinein, bleibt es als malformed-Warnung erhalten).

FAQ

F. Muss ich die Konsolenausgabe kopieren und der KI geben? → Nein. Genau das ist der Kern dieser Funktion. Baue eine Probe ein und führe die App aus, dann liest die KI die Werte selbst per debug_read.

F. Ich habe ausgeführt, aber debug_read erfasst nichts. → Die Ausgabe muss in einen von Blyck gestarteten Terminal-/Vorschau-Strom fließen. Ausgaben aus Pfaden, die nicht auf dem Bildschirm erscheinen (z. B. isolierte Ausführung), werden von Pipe A nicht erfasst. Führe im Terminal-Panel aus oder lasse bei Mobile den adb logcat-/flutter logs-Strom im Terminal laufen.

F. Muss ich beim Deployment die Proben unbedingt löschen? → Allein durch Setzen des Release-Flags wird der Shim automatisch deaktiviert und läuft nicht. Willst du auch die Markierungen sauber aufräumen, prüfe mit debug_release_check und nutze dann debug_strip.

F. Klinkt sich die KI von selbst ein, wenn die App einen Fehler wirft? → Wenn du Modus B (automatische Untersuchung) einschaltest, ja. Standard ist AUS; aktiviere ihn über das KI-Einstellungspanel oder den 🔔-Button im Live-Debug-Panel (Ctrl+Shift+D).

F. Funktioniert es auch mit Mobile/Flutter? → Ja. Lässt du im Blyck-Terminal den Log-Strom laufen, werden die @BLYCK@-Zeilen der Geräte-App automatisch erfasst — Android adb logcat, iOS idevicesyslog, Flutter flutter run/flutter logs. (Bei Web-Zielen ist die Browser-Konsole = Pipe B.)