devchristian1337/record-and-replay

Aufzeichnen & Wiedergeben (Browser + Desktop)

Aufzeichnen & Wiedergeben ermöglicht es einem Agenten, einen vom Benutzer demonstrierten Arbeitsablauf zu erlernen und in eine wiederverwendbare Fähigkeit umzuwandeln. Zwei Modi:

• Browser-Modus (Standard, reichhaltigste Beweise): Ein gesteuerter Playwright-Browser (systemeigener Google Chrome, falls verfügbar) zeichnet jede Benutzeraktion mit mehreren Selektorkandidaten sowie Playwright-Trace-Teildateien (trace-NNN.zip) in events.jsonl auf. Funktioniert unter macOS, Windows und Linux.
• Desktop-Modus (native Apps): Ein leichtgewichtiger Einzelprozess-Rekorder (pynput) erfasst globale Maus-/Tastaturereignisse, Änderungen des aktiven Fensters, Screenshots bei Klicks und das Barrierefreiheitsziel jedes Klicks (macOS AX, Windows UI Automation) in desktop-events.jsonl + screens/, wobei Passwortfelder maskiert werden – Codex-Parität (Codex zeichnet ebenfalls einen Ereignis-/Kontext-Stream auf, kein Video), ~1-3% CPU. Funktioniert unter macOS, Windows und Linux (X11). Siehe "Desktop-Aufzeichnung" unten.

Wählen Sie den Browser-Modus, wann immer der Arbeitsablauf nur den Browser betrifft – seine semantischen Selektoren erzeugen weitaus bessere Fähigkeiten als Desktop-Koordinaten.

Einrichtung (einmalig)

cd ~/.agents/skills/record-and-replay
node setup.mjs      # npm install + (Chromium nur, wenn Chrome fehlt) + Selbsttests
node install.mjs    # Verknüpfung in Agent-Fähigkeitsverzeichnisse (Symlink unter macOS/Linux, Junction unter Windows)

Installiert das playwright npm-Paket. Browser werden NICHT heruntergeladen, wenn Google Chrome installiert ist (der Rekorder verwendet channel: 'chrome'); andernfalls lädt das Skript Chromium herunter. Beide Skripte sind plattformübergreifend (Node).

Arbeitsablauf für die Aufzeichnung

1. Bitten Sie den Benutzer vor dem Start, Fenster, Dateien und Unterhaltungen zu schließen, die nicht erfasst werden sollen, und keine Geheimnisse einzugeben, die nicht gespeichert werden sollen. Starten Sie den Rekorder im Hintergrund getrennt erst, wenn der Benutzer bereit ist. Übergeben Sie immer --name <slug>, damit das Ausgabeverzeichnis von Anfang an bekannt ist:

   cd ~/.agents/skills/record-and-replay
   # macOS / Linux:
   nohup node scripts/recorder.mjs --minutes 30 --name <slug> [--url <startUrl>] \
     > ~/.agents/recordings/recorder.log 2>&1 &
   # Windows (PowerShell):
   Start-Process node -WindowStyle Hidden -ArgumentList "scripts/recorder.mjs","--minutes","30","--name","<slug>"
   

   Agenten mit einer nativen Hintergrundausführungsfunktion (z. B. Claude Codes Bash run_in_background) können diese stattdessen verwenden. Die Ausgaben gehen nach ~/.agents/recordings/<slug>/.

2. Einmaliger Startüberprüfung (~2-3 Sekunden nach dem Start – eine einzelne Prüfung, keine Polling-Schleife): Bestätigen Sie, dass ~/.agents/recordings/<slug>/session.json mit "status": "recording" existiert (der Rekorder gibt bei Erfolg auch eine {"status":"recording",...}-Zeile im Log aus). Wenn die Prüfung fehlschlägt, lesen Sie das Log: recording_already_active (exit 2) bedeutet, dass eine andere Aufzeichnung die Sperre hält; launch_failed oder ein Fehler eines fehlenden Moduls bedeutet, dass eine Einrichtung erforderlich ist. Melden Sie das tatsächliche Problem, anstatt dem Benutzer mitzuteilen, dass die Aufzeichnung begonnen hat.

3. Nach der Startüberprüfung nicht schlafen, abfragen oder in einer Schleife warten. Beenden Sie Ihren Zug: Teilen Sie dem Benutzer mit, dass die Aufzeichnung begonnen hat, wie das Zeitlimit ist und dass ein kleines schwebendes Steuerungsfenster (unten rechts, ähnlich wie Codex' Aufzeichnungssteuerung) einen Timer sowie Pause/Fortsetzen, Stopp und Verwerfen (zum Bestätigen zweimal tippen) enthält. Während der Pause wird nichts erfasst – Ereignisse und Trace werden beide gestoppt. Wenn der Benutzer das Steuerungsfenster versehentlich schließt, öffnet es sich von selbst wieder; das Schließen des Hauptbrowserfensters beendet ebenfalls die Sitzung (vermeiden Sie es, den Browser vollständig mit Cmd+Q zu beenden, da dies die letzte Minute des Traces verlieren kann). Übergeben Sie --badge beim Start, um anstelle des Steuerungsfensters ein Abzeichen auf der Seite zu verwenden (Notlösung für exotische Umgebungen).

4. Pause/Fortsetzen (Benutzer bittet Sie, zu pausieren, oder Sie müssen einen sensiblen Abschnitt überspringen): touch ~/.agents/recordings/<slug>/PAUSE pausiert innerhalb von 2 Sekunden; löschen Sie die Datei, um fortzusetzen. Die Schaltflächen im Steuerungsfenster und die PAUSE-Datei bleiben synchron; session.json trägt den aktuellen paused-Zustand. Pausierte Intervalle erscheinen als paused/resumed-Marker in events.jsonl und sind im Trace nicht vorhanden.

5. Wenn der Benutzer sagt, dass er fertig ist:

   • Wenn der Prozess noch läuft, stoppen Sie ihn ordnungsgemäß: touch ~/.agents/recordings/<slug>/STOP (der Rekorder bemerkt dies innerhalb von 2 Sekunden und schließt ab).
   • Lesen Sie session.json – status: "recording" bedeutet noch aktiv; "completed" bedeutet, dass die Ausgaben endgültig sind; "discarded" bedeutet, dass der Benutzer auf "Verwerfen" gedrückt hat – die Beweisdateien wurden gelöscht, bestätigen Sie dies und ERSTELLEN SIE NIEMALS eine Fähigkeit daraus. endReason ist einer von user_stopped, user_discarded, browser_closed, stop_file, time_limit, signal, event_limit.
   • Überprüfen Sie die erfassten Ereignisse vor dem Antworten: Führen Sie node scripts/summarize.mjs <outDir> für eine kompakte Zeitleiste aus, lesen Sie dann events.jsonl direkt für Schritte, die Details benötigen.

6. Abbruch wird durch Inhalt, nicht durch endReason definiert: Wenn die Aufzeichnung wenige oder keine kind: "dom"-Ereignisse enthält – unabhängig vom endReason – behandeln Sie sie als abgebrochen. Bestätigen Sie, erstellen oder aktualisieren Sie keine Fähigkeit.

7. Wenn die Aufzeichnung genügend Informationen enthält, um einen wiederverwendbaren Arbeitsablauf zu identifizieren, erstellen oder verfeinern Sie standardmäßig eine Fähigkeit dafür – auch wenn der Benutzer nicht explizit darum gebeten hat. Hören Sie nicht auf, nachdem Sie nur eine Zusammenfassung oder einen Wiedergabeplan erstellt haben. Befolgen Sie "Erstellen von Fähigkeiten aus einer Aufzeichnung" unten – es beginnt mit einer kurzen Klärungsrunde.

8. Wenn die Aufzeichnung zu dünn oder mehrdeutig ist, um den Arbeitsablauf zu identifizieren, raten Sie nicht. Erklären Sie, was unklar ist, und fragen Sie den Benutzer nach den fehlenden Teilen.

Gleichzeitige Aufzeichnung

Es kann immer nur eine Aufzeichnung gleichzeitig aktiv sein (Sperrdatei ~/.agents/recordings/.lock). Wenn der Rekorder mit recording_already_active beendet wird, starten Sie keine weitere; teilen Sie dem Benutzer mit, dass bereits eine Aufzeichnung läuft, und fragen Sie, ob er diese verwenden oder zuerst stoppen möchte. Ein Neustart mit demselben --name ist sicher: Das vorherige events.jsonl wird als zeitgestempelte .bak-Datei gespeichert, nicht angehängt.

Interpretieren von Ereignissen

events.jsonl ist der primäre Beweis; session.json gibt nur Zeit-/Pfadangaben; die trace-NNN.zip-Teildateien sind die Grundwahrheit auf DOM-Ebene (npx playwright show-trace <outDir>/trace-*.zip; session.json's traceChunks listet sie in der Reihenfolge auf). Der Trace verwendet standardmäßig den leichten Modus – vollständige DOM-Schnappschüsse pro Aktion, aber keine fortlaufenden Screenshots (hält die CPU niedrig). Starten Sie mit --trace full, wenn der Benutzer pixelgenaue visuelle Beweise wünscht, oder --trace off für den absolut minimalen Fußabdruck.

Jede Zeile ist ein Ereignis: {seq, t (ms seit Start), kind, type, url, ...}.

• kind: "page" – Navigationen, Downloads, Dialoge, Tab-Öffnen/-Schließen. Navigationen unterteilen den Arbeitsablauf in Phasen.
• kind: "dom" – Benutzeraktionen. target.selectors führt mehrere Selektorkandidaten auf: testId, role ({role, name}), id, nameAttr, text, css. Bevorzugen Sie sie in dieser Reihenfolge beim Generieren von Wiedergabecode; css ist die letzte Wahl.
• type: "input"-Ereignisse werden entprellt – ein Ereignis pro Feld mit dem endgültigen Wert (bei Verlassen des Fokus, Enter, Änderung und Formularübermittlung geleert). Passwort-/Kreditkarten-/OTP-ähnliche Felder (englische und türkische Namen: password, parola, şifre, kart, kimlik…) kommen vorab maskiert an (***MASKED***, masked: true).
• selection- und copy-Ereignisse zeigen, mit welchem Inhalt der Benutzer gearbeitet hat – oft der beste Hinweis, wenn der Benutzer sich auf "dieses" oder "das ausgewählte Ding" bezieht. Geheimnisaussehende Auswahlen (OTPs, API-Schlüssel, Tokens) werden maskiert. paste-Ereignisse enthalten nur Länge/Wortanzahl, niemals Inhalt.
• Sensible Daten: Die Maskierung ist heuristisch, keine Garantie – und sie gilt nur für events.jsonl. Die Trace-Teildateien sind NICHT maskiert: DOM-Schnappschüsse enthalten rohe Eingabewerte (einschließlich Werten, die im JSONL maskiert sind) und Screenshots erfassen alles, was auf dem Bildschirm sichtbar ist (angezeigte Tokens, 2FA-Codes, Kontostände). Behandeln Sie das gesamte Verzeichnis ~/.agents/recordings/<name>/ als sensibel: Überprüfen Sie es nur lokal, laden Sie es niemals hoch oder committen Sie es, und zitieren Sie niemals wortwörtliche Geheimnisse daraus in Zusammenfassungen oder generierten Fähigkeiten – verwenden Sie Platzhalter oder generische Beschreibungen.

Erstellen von Fähigkeiten aus einer Aufzeichnung

Lesen Sie references/skill-authoring.md vor dem Schreiben: Es enthält den Fragenkatalog, die Frontmatter-Grenzen, das SKILL.md-Gerüst, die Regeln für gebündelte Skripte und die Qualitätscheckliste. Wenn eine skill-creator-Fähigkeit in Ihrer Umgebung verfügbar ist, gelten auch deren Anleitungen. Erstellen Sie eine tatsächlich auffindbare Fähigkeit (einen SKILL.md-Ordner), nicht nur ein Markdown-Handbuch.

Kopieren Sie diese Checkliste und haken Sie sie ab:

- [ ] 1. Fassen Sie die Aufzeichnung zusammen; notieren Sie jede Lücke (Entscheidungen, maskierte Abschnitte, blinde Flecken)
- [ ] 2. Klären Sie: eine Nachricht, höchstens 6 Fragen, nur zu den Lücken
- [ ] 3. Prüfen Sie auf eine vorhandene Fähigkeit, die diesen Arbeitsablauf abdeckt → aktualisieren Sie diese, anstatt zu duplizieren
- [ ] 4. Schreiben Sie die Fähigkeit + eval/evals.json (die Aufzeichnung ist Testfall 1)
- [ ] 5. Validieren Sie: node scripts/export-skill.mjs <skillDir> --check → beheben Sie Fehler, führen Sie erneut aus
- [ ] 6. Bieten Sie die Trigger-Prüfung + einen Probelauf an; integrieren Sie Korrekturen, erhöhen Sie metadata.version
- [ ] 7. Bieten Sie den claude.ai ZIP-Export an

Schritt 2 – vor dem Schreiben klären. Es gibt keine Audio: Die Aufzeichnung zeigt, was passiert ist, nicht warum. Beantworten Sie aus der Aufzeichnung, was sie zeigt, und fragen Sie dann den Benutzer – einmal, in einer einzigen Nachricht, höchstens 6 Fragen – nach dem, was sie nicht kann: dem Ergebnis und wie man erkennt, dass es funktioniert hat, welche Werte zwischen Läufen variieren, warum sie X zu einem bestimmten Zeitpunkt gewählt haben, welche Aktionen Umwege waren, was sie sagen würden, um die Fähigkeit auszulösen (und was nicht), und welche Aktionen eine Bestätigung benötigen. Zitieren Sie den Moment, den Sie meinen ("um 02:14 haben Sie den Datumsfilter gelöscht – warum?"). Verwenden Sie Ihr strukturiertes Fragentool, falls vorhanden; ansonsten einfachen Chat. Überspringen Sie die Runde nur, wenn die Aufzeichnung zusammen mit der Anfrage des Benutzers bereits alles beantwortet, und sagen Sie dies.

Schreibregeln:

• Behandeln Sie die Aufzeichnung als Beweis für das beabsichtigte Ergebnis des Benutzers, nicht als Skript, das Pixel für Pixel wiederholt werden soll. Wenn ein Connector/API/CLI/MCP-Tool dasselbe Ergebnis semantisch erzielen kann (ein Kalenderereignis erstellen, einen PR öffnen, eine Nachricht posten), bevorzugen Sie es gegenüber der UI-Automatisierung.
• Wenn eine UI-Wiedergabe tatsächlich erforderlich ist, generieren Sie ein Playwright-Skript aus scripts/replay-template.mjs: semantische Locators (getByTestId > getByRole > getByLabel > getByText), ein Überprüfungsschritt nach jeder kritischen Aktion, Geheimnisse aus Umgebungsvariablen. Verwenden Sie niemals rohe Koordinaten, es sei denn, der Ereignisstrom bietet kein besseres Ziel.
• Desktop-Schritte benennen das erfasste Ziel (Rolle + Name + Fenster, z. B. Schaltfläche "Speichern" in "Rechnung — Acme"), damit ein Barrierefreiheitsbaum-Tool es finden kann; Koordinaten nur, wenn kein Ziel erfasst wurde.
• Das persistente Profil des Rekorders (~/.agents/recordings/.browser-profile) behält Anmeldungen über Sitzungen hinweg, sodass generierte Fähigkeiten normalerweise keine Anmeldeschritte benötigen. Sicherheit: Dieses Verzeichnis enthält lebendiges, authentifiziertes Sitzungsmaterial (Cookies/localStorage; Playwright startet Chrome mit einer Mock-Keychain, behandeln Sie es also als Klartext-Anmeldeinformationen). Committen, teilen oder sichern Sie es niemals unverschlüsselt – und denken Sie daran, dass jede Wiedergabefähigkeit, die es wiederverwendet, mit den Anmeldungen des Benutzers läuft. Für Aufzeichnungen auf nicht vertrauenswürdigen oder hochsensiblen Websites bevorzugen Sie ein temporäres Profil (--out plus ein temporäres Profil) oder löschen Sie das Profil anschließend.
• Speichern Sie neue Fähigkeiten in ~/.agents/skills/<skill-name>/ (Ordnername = name, kebab-case) und verknüpfen Sie sie mit den Agent-Fähigkeitsverzeichnissen (siehe install.mjs für das Muster), damit jeder Agent auf diesem Computer sie verwenden kann.
• Parametrisieren Sie, was variiert (Daten, Beträge, Namen), und kodieren Sie fest, was nicht. Geben Sie den Zweck des Arbeitsablaufs und die Überprüfungskriterien in der generierten SKILL.md an. Kopieren Sie niemals Geheimnisse oder maskierte Werte in die Fähigkeit.

Export für claude.ai (Bieten Sie es an; führen Sie es auf Anfrage aus): node scripts/export-skill.mjs ~/.agents/skills/<name> schreibt ~/.agents/exports/<name>.zip (Ordner im ZIP-Root; README, Evals, Caches und Aufzeichnungsbeweise ausgelassen; Archiv vor Erfolg zurückgelesen). Wenn die Fähigkeit Claude-Code-spezifisches Frontmatter verwendet (disable-model-invocation, …), fügen Sie --strip-cc-keys hinzu. Teilen Sie dem Benutzer mit, wo sich die Datei befindet und dass sie unter Customize › Skills › + › Skill hochladen hochgeladen wird (Code-Ausführung muss aktiviert sein).

Desktop-Aufzeichnung (macOS, Windows, Linux/X11)

Einrichtung: node setup.mjs (erstellt die minimale .venv-desktop Python-Umgebung aus requirements-desktop.txt – pynput+mss+pillow, plus comtypes unter Windows, ~50 MB; erfordert uv).

Berechtigungen (macOS): Der Rekorder prüft sie vorab und meldet einen maschinenlesbaren Status, also raten Sie nie. start gibt permissions: {inputMonitoring, screenRecording, grantTo} plus eine warning aus, wenn etwas fehlt, und öffnet automatisch den Systemdialog und den richtigen Einstellungsbereich (--no-permission-prompt deaktiviert dies; node scripts/desktop-record.mjs permissions führt es bei Bedarf aus). grantTo benennt die App, der der Benutzer die Berechtigung erteilen muss – eine TCC-Berechtigung bindet an das .app-Bundle, das den Agenten hostet, nicht an Python, und diese App muss danach neu gestartet werden. Geben Sie grantTo wörtlich weiter; dem Benutzer zu sagen, "erteilen Sie sie Ihrem Terminal", ist normalerweise falsch. Windows benötigt keine Berechtigungen und keine Administratorrechte.

Die Engine ist ein Einzelprozess-Rekorder (~0-3% CPU): Eingabeereignis-Stream + Änderungen des aktiven Fensters/Titels + ein JPEG mit halber Auflösung bei jedem Klick (max. 1/700ms) → desktop-events.jsonl + screens/. Jeder Klick trägt auch die Barrierefreiheitsbeschreibung des Elements unter dem Cursor (kind: "target"-Zeile, mit dem Klick durch forSeq verbunden): role, name, automationId, window, ancestors – ein semantisches Ziel wie Button "Speichern" anstelle einer bloßen Koordinate (macOS AX, Windows UI Automation; nichts unter Linux). Die Eingabe erscheint als type: "text"-Ereignisse, die den endgültigen Wert jedes Bursts enthalten (Rücktaste-Korrekturen angewendet); Tastenkombinationen und Sondertasten als press-Ereignisse (ctrl+c, enter). Screenshots, Zielabfragen und Fokusprüfungen werden in Worker-Threads ausgeführt, niemals im Eingabe-Callback: Ein langsamer Callback führt zur Deaktivierung des macOS-Ereignis-Taps und zum stillen Entfernen des Windows-Hooks (der Rekorder überwacht auch letzteres und installiert die Hooks neu).

Dies ist Codex-Parität: Codex' Record & Replay zeichnet ebenfalls auf …