WP Pilot AI – File Handler Dokumentation

Was der File Handler ist

Der File Handler ist kein allgemeiner Dateimanager und auch kein unkontrollierter Code-Editor. Er ist ein kontrollierter Workflow für Lesen, Analysieren, Vorbereiten, Prüfen, Schreiben, Sichern und Wiederherstellen von freigegebenen WordPress-Dateien.

Das Modul ist besonders hilfreich, wenn du gezielt technische Probleme lösen möchtest, zum Beispiel:

• Debug-Fehler in wp-config.php, .htaccess oder debug.log prüfen
• eine kleine Code-Stelle in Theme- oder Plugin-Dateien anpassen
• mehrere zusammenhängende Dateiänderungen als koordiniertes Set vorbereiten
• einen Fehler nach einer Änderung schnell über Backups oder Recovery rückgängig machen
• Text- oder Regex-Suchen in erlaubten Theme-, Plugin- und MU-Plugin-Dateien durchführen

Der typische Ablauf ist bewusst sicher aufgebaut: erst lesen oder analysieren, dann eine Vorschau erzeugen, anschließend im File-Operations-Bereich prüfen und erst danach im Chat bestätigen.

Welche Aufgaben der File Handler abdeckt

Dateien lesen und analysieren

Du kannst einzelne freigegebene Dateien auslesen, strukturierte Analysen anfordern und bei Logdateien gezielt die letzten Zeilen prüfen lassen. Das ist ideal für Ursachenanalyse, Fehlersuche oder technische Einschätzungen.

Dateien gezielt durchsuchen

Der File Handler kann erlaubte Verzeichnisse nach Texten oder regulären Ausdrücken durchsuchen. Das ist sehr nützlich, um Hooks, Skripte, problematische Funktionen, doppelte Implementierungen oder Konfliktstellen zu finden.

Vorschläge vorbereiten statt blind schreiben

Bevor eine Datei verändert wird, kann zuerst eine Vorschau erzeugt werden. Das gilt sowohl für vollständige Inhalte als auch für gezielte Patches und mehrteilige Changesets.

Einzelne Dateien oder mehrere Dateien ändern

Der File Handler unterstützt sowohl Einzeländerungen als auch koordinierte Multi-File-Änderungen. Mehrere Änderungen lassen sich in einem Changeset zusammenfassen, gemeinsam prüfen und gesammelt anwenden.

Backups, Restore und Health Checks

Vor jeder echten Änderung wird automatisch ein Backup erstellt. Nach Schreib- oder Restore-Vorgängen führt das System Reachability- und Selbsttests aus und gibt eine Einschätzung zurück, ob alles gesund, warnungswürdig oder kritisch ist.

Freigegebene Bereiche: lesen, prüfen, ändern

Der File Handler arbeitet mit einer klaren Freigabeliste. Es ist also nicht jede Datei auf dem Server erreichbar. Das schützt vor unkontrollierten Zugriffen und begrenzt die Auswirkungen auf definierte, nachvollziehbare Bereiche.

Wichtig: Der File Handler kann damit theoretisch auch in bestehende aktive Plugins eingreifen und deren Dateien verändern. Das ist technisch möglich, sollte im Regelfall aber nicht die bevorzugte Lösung sein, weil Plugin-Updates solche Änderungen später wieder überschreiben können.

Gesperrte Bereiche und warum sie gesperrt sind

Der File Handler sperrt alle Pfade, die nicht ausdrücklich freigegeben sind. Zusätzlich blockiert er typische Risikoquellen für Escapes, Geheimnisse oder Deployment-Artefakte.

Grundsätzlich gesperrt

• beliebige Dateien außerhalb der freigegebenen Liste
• Pfadangaben mit ..
• absolute Pfade
• Pfade mit Null-Bytes
• Symlink-Pfade, die aus dem WordPress-Verzeichnis herausführen könnten
• unzulässige Dateiendungen

Explizit blockierte Muster

• .env
• wp-config-sample.php
• .git/, .svn/
• node_modules/, vendor/
• .ssh/
• private Schlüssel und Zertifikatsdateien wie id_rsa, .pem, .key, .crt, .p12

Wichtige praktische Grenzen

• WordPress-Core-Dateien außerhalb der ausdrücklich erlaubten Root-Dateien sind nicht als allgemeiner Schreibbereich gedacht.
• Inaktive Themes sind nicht für Schreibvorgänge freigegeben.
• Inaktive Plugins sind nicht für Schreibvorgänge freigegeben.
• Das Plugin schützt seinen eigenen Bereich: das WP Pilot AI Plugin-Verzeichnis selbst wird nicht als aktives Plugin-Schreibziel freigegeben.
• MU-Plugin-Unterordner sind nicht als Schreibziel vorgesehen; erlaubt sind dort nur direkte Top-Level-.php-Dateien.

Diese Trennung existiert, damit das Modul technisch stark bleibt, aber trotzdem nicht zu einem unkontrollierten Server-Dateimanager wird.

Einzeländerungen an Dateien

Für Einzeländerungen ist der sicherste Ablauf:

1. Datei lesen oder analysieren
2. eine Vorschau vorbereiten
3. die Änderung im Bereich File Operations prüfen
4. im Chat ausdrücklich bestätigen
5. erst dann schreiben lassen

Was sich als Einzeländerung eignet

• eine Konstante in wp-config.php aktivieren oder korrigieren
• eine Rewrite-Regel in .htaccess ergänzen
• eine kleine Template-Stelle im aktiven Theme korrigieren
• eine Plugin-Datei an einer klar umrissenen Stelle anpassen
• robots.txt strukturieren oder ergänzen

Beispiel-Prompts für Einzeländerungen

Bitte lies meine wp-config.php, prüfe die Debug-Konstanten und bereite eine sichere Vorschau vor, um WP_DEBUG_LOG zu aktivieren, ohne andere Einstellungen zu verändern.

Lies die .htaccess und bereite eine minimal-invasive Änderung vor, damit www auf non-www umgeleitet wird. Bitte zuerst nur Vorschau.

Analysiere die Datei wp-content/themes/mein-theme/functions.php und schlage nur die kleinste notwendige Änderung vor, um den Fatal Error zu beheben. Bitte zuerst Preview und Review-Link erzeugen.

Lies robots.txt, erkläre mir kurz den aktuellen Inhalt und bereite danach eine saubere Fassung für eine normale Unternehmenswebsite vor.

Gezielte Patches statt Vollersatz

Nicht jede Änderung muss die komplette Datei ersetzen. Der File Handler unterstützt gezielte Patch-Aktionen wie:

• replace
• insert_before
• insert_after
• delete

Das ist ideal, wenn nur eine sehr kleine Stelle angepasst werden soll. Patches reduzieren die Breite der Änderung und sind oft leichter zu prüfen.

Typische Patch-Szenarien

• einen Hook ergänzen
• eine fehlerhafte Funktionszeile ersetzen
• einen Debug-Block einfügen
• eine problematische Zeile vorübergehend entfernen

Beispiel-Prompts für Patches

Suche in der functions.php meines aktiven Themes die Stelle, an der das Script eingebunden wird, und bereite einen gezielten Patch vor, der defer ergänzt. Bitte kein Full Rewrite, sondern nur Patch-Preview.

Analysiere die Plugin-Datei, finde den fehlerhaften Redirect und bereite einen Patch vor, der nur diese Bedingung ersetzt. Bitte mir vorher die Patch-Zusammenfassung zeigen.

Lies wp-content/plugins/mein-plugin/includes/class-handler.php und bereite einen insert_after-Patch vor, um dort Logging für den Problemfall einzubauen. Noch nicht anwenden.

Mehrere Dateien in einem Changeset

Manche Reparaturen oder Anpassungen betreffen mehr als eine Datei. Dafür gibt es koordinierte Changesets. Ein Changeset bündelt mehrere Einzeländerungen in einem gemeinsamen Review- und Apply-Ablauf.

Wofür Changesets ideal sind

• Template + CSS + JS zusammen ändern
• Hook-Datei und zugehörige Include-Datei gemeinsam anpassen
• eine Funktion in mehreren Dateien konsistent umbenennen oder ergänzen
• einen Fehler fixen, der Theme- und Plugin-Code gleichzeitig berührt

Wichtige Eigenschaften eines Changesets

• maximal 10 Dateien pro Set
• maximal 512 KB Gesamtgröße für das komplette Set
• keine doppelte Datei im selben Set
• jede Datei wird mit Risiko- und Änderungsinformationen vorbereitet
• alle betroffenen Dateien werden in einer Review-Session zusammen geprüft
• bei der Anwendung entstehen gruppierte Backups mit einer gemeinsamen Backup-Set-ID

Wann ein Changeset sinnvoller ist als Einzeländerungen

Wenn mehrere Dateien logisch zusammengehören, ist ein Changeset meist besser als drei oder vier getrennte Einzelschritte. So bleibt die Änderung nachvollziehbar und lässt sich auch gesammelt wiederherstellen.

Beispiel-Prompts für Changesets

Bitte analysiere den Fehler in meinem aktiven Theme und bereite ein Changeset vor, das functions.php, das betroffene Template und die zugehörige CSS-Datei gemeinsam korrigiert. Ich möchte zuerst die komplette Review-Ansicht sehen.

Suche die Stellen, an denen mein Formular-Button eingebunden und gestylt wird, und bereite ein Multi-File-Changeset vor: Template, CSS und optional JS. Bitte mit möglichst kleinen Änderungen pro Datei.

Analysiere, warum der WooCommerce-Hinweis doppelt angezeigt wird, und bereite ein koordiniertes Changeset für das aktive Theme und das aktive Plugin vor. Erst Vorschau, keine direkte Ausführung.

Debug-Log analysieren, Konflikte erkennen, Fehler eingrenzen

Der File Handler eignet sich sehr gut für klassische technische Analyse. Besonders wichtig ist dabei das Zusammenspiel aus lesen, analysieren, suchen und anschließend gezielt korrigieren.

Debug-Log lesen

wp-content/debug.log ist lesbar, aber nicht schreibbar. Das Modul arbeitet hier im Regelfall in einem Tail-Modus. Standardmäßig werden die letzten 200 Zeilen betrachtet, maximal 500 Zeilen.

Typische Analyse-Aufgaben

• Fatal Errors erkennen
• Warnings, Notices und Deprecated-Meldungen einsortieren
• prüfen, ob der Fehler aus Theme, Plugin oder MU-Plugin stammt
• betroffene Datei und Zeile identifizieren
• anschließend die betreffende Datei lesen und einen Fix vorbereiten

Konflikte erkennen

Sehr oft liegen Probleme nicht in einer einzigen Datei, sondern in Konflikten zwischen Theme und Plugin oder zwischen zwei aktiven Plugins. Dafür ist die Dateisuche besonders nützlich. Du kannst nach Funktionsnamen, Hooks, Enqueue-Aufrufen, Redirects, CSS-Klassen oder eigenen Markern suchen lassen.

Was bei Konflikten möglich ist

• nach einem Hook oder Funktionsnamen in erlaubten Verzeichnissen suchen
• prüfen, welche Datei denselben Filter oder dieselbe Klasse verwendet
• Vergleich von zwei oder mehr Implementierungen
• gezielte Korrektur an genau der konfliktverursachenden Stelle

Typische Debug- und Konflikt-Prompts

Lies die letzten 200 Zeilen aus wp-content/debug.log, gruppiere Fatal, Warning und Deprecated getrennt und sage mir, welche Datei ich als Nächstes prüfen sollte.

Analysiere das Debug-Log und finde heraus, ob der Fehler eher aus dem Theme oder aus einem aktiven Plugin kommt. Bitte nenne mir den wahrscheinlichsten Einstiegspunkt für die Reparatur.

Durchsuche die erlaubten Theme- und Plugin-Dateien nach dem Hook woocommerce_before_single_product und zeige mir alle Treffer mit etwas Kontext. Ich möchte Konflikte erkennen.

Suche per Regex nach wp_enqueue_script\s*\( in meinem aktiven Theme und in aktiven Plugins, damit wir doppelte Script-Einbindungen erkennen.

Lies zuerst wp-content/debug.log und danach die im Fehler genannte Datei. Bereite eine sichere Patch-Vorschau vor, aber ändere noch nichts.

Bitte finde heraus, ob zwei aktive Plugins denselben Redirect oder dieselbe Ausgabe doppelt erzeugen. Suche dafür nach dem Text 'Danke für deine Bestellung' und vergleiche die Treffer.

Bestehende Themes und Plugins prüfen oder verändern

Der File Handler kann nicht nur dein aktives Theme prüfen, sondern auch Dateien in aktiven Plugins und in einem eng begrenzten MU-Plugin-Bereich analysieren und – wenn freigegeben – verändern.

Was möglich ist

• aktive Theme-Dateien lesen und ändern
• aktive Plugin-Dateien lesen und ändern
• MU-Plugin-Dateien lesen; direkte Top-Level-.php-Dateien dort auch ändern

Was dabei wichtig ist

Auch wenn Änderungen in bestehenden Plugins technisch möglich sind, sind sie oft nur eine temporäre technische Lösung. Bei regulären Plugin-Updates können diese Änderungen wieder überschrieben werden.

Empfohlene Denkweise

• für dauerhafte Anpassungen möglichst zuerst Theme, Child Theme, Hooks oder Snippets prüfen
• Plugin-Dateien nur ändern, wenn der Fehler wirklich dort sitzt und keine sauberere Alternative möglich ist
• bei Plugin-Änderungen immer zusätzlich notieren, was geändert wurde und warum
• bei produktiven Shops und Mitgliedsseiten besonders vorsichtig sein

Beispiel-Prompts rund um bestehende Plugins

Analysiere das aktive Plugin-Verzeichnis von Plugin X und finde die Datei, in der der Checkout-Hinweis erzeugt wird. Bitte noch nichts ändern.

Bitte prüfe, ob die gewünschte Korrektur besser im Theme, per Snippet oder direkt im aktiven Plugin umgesetzt werden sollte. Begründe die Empfehlung kurz.

Bereite einen minimalen Patch für die betroffene aktive Plugin-Datei vor, aber erinnere mich ausdrücklich daran, dass ein Plugin-Update die Änderung später überschreiben kann.

Suche im aktiven Plugin nach der Funktion, die den Fatal Error auslöst, und bereite nur eine Reparaturvorschau vor. Keine direkte Ausführung.

Sicherheit, Schutzmechanismen und Freigabe-Logik

Der File Handler ist absichtlich streng aufgebaut. Das betrifft sowohl den Zugriff auf Pfade als auch die eigentliche Ausführung von Änderungen.

Wichtige Schutzmechanismen

• Zugriff nur auf freigegebene Dateien und Verzeichnisse
• Schutz vor Pfad-Traversal, absoluten Pfaden und Null-Byte-Pfaden
• Symlink-Schutz gegen Escapes außerhalb der WordPress-Installation
• Extension-Allowlist für Dateien in freigegebenen Ordnern
• Redaktion sensibler Inhalte, besonders bei wp-config.php
• Schreibvorgänge nur nach ausdrücklicher Freigabe im Chat
• Hash-basierte Konflikterkennung, wenn sich eine Datei zwischen Vorschau und Ausführung verändert hat
• atomisches Schreiben per temporärer Datei und anschließendem Replace
• automatische Backups vor echten Änderungen

Review-Sessions

Wenn eine Vorschau erzeugt wird, entsteht eine Review-Session mit einer eigenen ID und einem Link in den Bereich File Operations. Dort kannst du die vorbereitete Änderung separat prüfen. Erst danach sollte die Freigabe im Chat erfolgen.

• Einzeldatei-Review-Sessions laufen typischerweise bis zu 24 Stunden.
• Multi-File-Changesets haben eine kürzere Laufzeit von typischerweise 6 Stunden.
• Wenn eine Session nur noch als Anzeige-Fallback vorliegt, bleibt die Ansicht sichtbar, aber für die Ausführung muss eine frische Vorschau erzeugt werden.

Warum diese Schutzmechanismen wichtig sind

Der File Handler arbeitet an hochsensiblen Live-Dateien. Deshalb sind Prüfbarkeit, Wiederholbarkeit, Kollisionsschutz und Wiederherstellung genauso wichtig wie die eigentliche Änderung selbst.

Backups, Wiederherstellung und Emergency Recovery

Automatische Backups vor Änderungen

Vor jeder echten Änderung wird automatisch ein Backup der betroffenen Datei erzeugt. Die Backups enthalten Metadaten wie Pfad, Größe, Zeitstempel, Prüfsumme und zusätzliche Zuordnung zu Changesets.

Wiederherstellung einzelner Dateien

Einzelne Dateien lassen sich über die Backup-Funktionen wiederherstellen. Auch das aktuelle File-Operations-Review kann nach einer Änderung Health-Checks und Rollback-Hinweise liefern.

Wiederherstellung kompletter Changesets

Wenn eine koordinierte Mehrfachänderung angewendet wurde, entstehen gruppierte Backup-Sets. Diese lassen sich später zusammen wiederherstellen. Vor einem Set-Restore werden zusätzlich Guard-Backups erzeugt, damit auch ein fehlerhafter Restore selbst noch zurückgenommen werden kann.

Health Checks nach Write oder Restore

Nach wichtigen Änderungen oder Wiederherstellungen prüft das System unter anderem:

• Frontend-Homepage
• Login-Seite
• Admin-Dashboard
• REST-Root
• AJAX-Selftest
• REST-Health-Ping

Das Ergebnis wird als healthy, warning oder critical zusammengefasst. Gerade nach riskanten Änderungen an Plugin-, Theme- oder Root-Dateien ist das sehr wertvoll.

Emergency Recovery

Zusätzlich gibt es ein separates Emergency-Recovery-Skript, das außerhalb des normalen WordPress-Bootstraps im WordPress-Root bereitgestellt werden kann. Es ist token-geschützt und dient als letzte Wiederherstellungslinie, falls die normale WordPress-Oberfläche nicht mehr sauber erreichbar ist.

Was Recovery besonders stark macht

• Restore einzelner Backups
• Restore kompletter Backup-Sets
• Restore-All-Szenarien im Recovery-Kontext
• Prüfung gegen gespeicherte Policy-Snapshots
• Guard-Backups vor Set-Restores

Beispiel-Prompts rund um Backups und Recovery

Zeige mir die letzten Backups für wp-config.php und erkläre kurz, welches Backup zum letzten funktionierenden Zustand gehören dürfte.

Liste mir die letzten Änderungen an .htaccess auf und zeige mir die zugehörigen Backup-IDs.

Bitte prüfe, ob der Fehler direkt nach dem letzten Changeset aufgetreten ist, und sage mir, ob ein Restore des letzten Backup-Sets sinnvoll wäre.

Zeige mir die History für die betroffene Plugin-Datei und bewerte, ob eher Restore oder gezielte Nachkorrektur der bessere Weg ist.

Viele Beispiel-Prompts für die Praxis

Lesen und verstehen

Lies wp-config.php und erkläre mir nur die Debug- und Performance-relevanten Konstanten.

Lies robots.txt und erkläre verständlich, was diese Datei aktuell bewirkt.

Lies die letzten 300 Zeilen aus wp-content/debug.log und fasse die wichtigsten Fehlerquellen zusammen.

Suchen und vergleichen

Durchsuche erlaubte Theme- und Plugin-Dateien nach der Klasse my-custom-checkout-note und zeige mir alle Treffer mit Kontext.

Suche in aktiven Plugin-Dateien nach add_action( 'init' und finde heraus, welches Plugin den Redirect setzt.

Bitte suche per Regex nach wp_mail\s*\( und liste mir alle relevanten Treffer in Theme und aktiven Plugins auf.

Einzeländerungen vorbereiten

Analysiere meine .htaccess und bereite eine sichere Preview vor, um nur den doppelten Redirect zu entfernen. Noch nicht schreiben.

Lies die betroffene Theme-Datei, finde den Syntaxfehler und bereite einen minimalen Patch vor. Ich möchte zuerst nur die Vorschau.

Bitte prüfe die Datei wp-content/plugins/plugin-x/includes/class-main.php und schlage nur die kleinste notwendige Änderung vor, um den Fatal Error zu beheben.

Mehrere zusammenhängende Änderungen

Bereite ein Changeset vor, das Template, CSS und die zugehörige JS-Datei gemeinsam korrigiert. Bitte jede Datei einzeln begründen und eine gemeinsame Review-Session erzeugen.

Ich vermute einen Konflikt zwischen aktivem Theme und Plugin. Analysiere beide Seiten und erstelle ein koordiniertes Changeset nur dann, wenn wirklich mehrere Dateien notwendig sind.

Debug und Konflikte

Analysiere debug.log, finde die wahrscheinlichste Ursprungsdatei und lies danach automatisch die betroffene Datei, damit du mir eine Reparaturvorschau erstellen kannst.

Bitte suche in Theme und aktiven Plugins nach allen Stellen, die dieselbe Produktbeschreibung manipulieren, damit wir einen Konflikt erkennen können.

Prüfe, ob mein Fehler eher ein Plugin-Konflikt, ein Hook-Konflikt oder eine doppelte Script-Einbindung ist. Nutze dafür Loganalyse und Dateisuche.

Backups und Wiederherstellung

Liste mir die letzten Backups der geänderten Datei und die History dazu auf.

Zeige mir das letzte Backup-Set der Mehrfachänderung und bewerte, ob ein Restore als nächster Schritt sinnvoll wäre.

Tipps und Best Practices

• Starte bei unklaren Problemen fast immer mit lesen oder analyze, nicht direkt mit einer Änderung.
• Nutze bei kleinen Änderungen möglichst Patches statt kompletter Full Rewrites.
• Bitte bei Live-Seiten ausdrücklich um eine Preview und prüfe diese in der Review-Ansicht.
• Wenn mehrere Dateien betroffen sind, bitte lieber gezielt um ein Changeset statt viele verstreute Einzeländerungen.
• Bei Debug-Problemen zuerst debug.log, dann die betroffene Datei, dann die Vorschau.
• Änderungen in bestehenden Plugins nur dann bevorzugen, wenn es keine sauberere Alternative im Theme, Hook oder Snippet gibt.
• Wenn eine Datei zwischen Vorschau und Ausführung verändert wurde, akzeptiere die Konfliktmeldung und lass eine neue Vorschau erzeugen.
• Nutze History und Backups aktiv, nicht erst im Notfall.

FAQ

Kann der File Handler jede Datei auf meinem Server ändern?

Nein. Er arbeitet mit einer festen Freigabeliste und blockiert alles, was nicht ausdrücklich erlaubt ist.

Kann ich damit bestehende Plugins verändern?

Ja, technisch ist das bei aktiven Plugins möglich. Im Regelfall ist das aber nur für gezielte Reparaturen sinnvoll, weil Plugin-Updates solche Änderungen später überschreiben können.

Kann ich damit WordPress-Core beliebig ändern?

Nein. Es gibt einige ausdrücklich erlaubte Root-Dateien wie wp-config.php oder .htaccess, aber kein offenes Schreibmodell für beliebige Core-Dateien.

Kann ich Logdateien analysieren?

Ja. Vor allem wp-content/debug.log ist dafür gedacht. Die Datei ist lesbar, aber bewusst nicht schreibbar.

Was passiert, wenn sich eine Datei seit der Vorschau verändert hat?

Dann greift die Konflikterkennung. Die Änderung wird nicht blind angewendet, sondern du musst eine frische Vorschau erzeugen lassen.

Was passiert nach einer riskanten Änderung?

Es wird ein Backup angelegt, anschließend werden Health Checks durchgeführt und bei problematischen Ergebnissen kann ein Restore empfohlen werden.

Gibt es eine letzte Rettung, wenn die Seite gar nicht mehr sauber lädt?

Ja. Dafür ist das Emergency-Recovery-Konzept gedacht, das mit dem separaten Recovery-Skript und den Backups arbeitet.