Jamie-BitFlight/claude_skills

Browser-Automatisierung mit agent-browser

Kern-Workflow

Jede Browser-Automatisierung folgt diesem Muster:

1. Navigieren: agent-browser open <url>
2. Snapshot: agent-browser snapshot -i (holt Element-Referenzen wie @e1, @e2)
3. Interagieren: Referenzen verwenden, um zu klicken, auszufüllen, auszuwählen
4. Erneuter Snapshot: Nach Navigation oder DOM-Änderungen frische Referenzen holen

agent-browser open https://example.com/form
agent-browser snapshot -i
# Ausgabe: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # Ergebnis prüfen

Befehlsverkettung

Befehle können mit && in einem einzigen Shell-Aufruf verkettet werden. Der Browser bleibt zwischen den Befehlen über einen Hintergrund-Daemon bestehen, daher ist die Verkettung sicher und effizienter als separate Aufrufe.

# Öffnen + Warten + Snapshot in einem Aufruf
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# Mehrere Interaktionen verketten
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3

# Navigieren und erfassen
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

Wann verketten: Verwenden Sie &&, wenn Sie die Ausgabe eines Zwischenbefehls nicht lesen müssen, bevor Sie fortfahren (z. B. öffnen + warten + Screenshot). Führen Sie Befehle separat aus, wenn Sie zuerst die Ausgabe parsen müssen (z. B. Snapshot, um Referenzen zu entdecken, dann mit diesen Referenzen interagieren).

Wesentliche Befehle

# Navigation
agent-browser open <url>              # Navigieren (Aliase: goto, navigate)
agent-browser close                   # Browser schließen

# Snapshot
agent-browser snapshot -i             # Interaktive Elemente mit Referenzen (empfohlen)
agent-browser snapshot -i -C          # Cursor-interaktive Elemente einbeziehen (divs mit onclick, cursor:pointer)
agent-browser snapshot -s "#selector" # Auf CSS-Selektor beschränken

# Interaktion (@refs aus Snapshot verwenden)
agent-browser click @e1               # Element klicken
agent-browser click @e1 --new-tab     # Klicken und in neuem Tab öffnen
agent-browser fill @e2 "text"         # Text löschen und eingeben
agent-browser type @e2 "text"         # Eingeben ohne zu löschen
agent-browser select @e1 "option"     # Dropdown-Option auswählen
agent-browser check @e1               # Checkbox aktivieren
agent-browser press Enter             # Taste drücken
agent-browser scroll down 500         # Seite scrollen

# Informationen abrufen
agent-browser get text @e1            # Elementtext abrufen
agent-browser get url                 # Aktuelle URL abrufen
agent-browser get title               # Seitentitel abrufen

# Warten
agent-browser wait @e1                # Auf Element warten
agent-browser wait --load networkidle # Auf Netzwerkinaktivität warten
agent-browser wait --url "**/page"    # Auf URL-Muster warten
agent-browser wait 2000               # Millisekunden warten

# Erfassen
agent-browser screenshot              # Screenshot in temporäres Verzeichnis
agent-browser screenshot --full       # Vollseiten-Screenshot
agent-browser screenshot --annotate   # Annotierter Screenshot mit nummerierten Elementbeschriftungen
agent-browser pdf output.pdf          # Als PDF speichern

# Diff (Seitenzustände vergleichen)
agent-browser diff snapshot                          # Aktuellen mit letztem Snapshot vergleichen
agent-browser diff snapshot --baseline before.txt    # Aktuellen mit gespeicherter Datei vergleichen
agent-browser diff screenshot --baseline before.png  # Visueller Pixel-Diff
agent-browser diff url <url1> <url2>                 # Zwei Seiten vergleichen
agent-browser diff url <url1> <url2> --wait-until networkidle  # Benutzerdefinierte Wartestrategie
agent-browser diff url <url1> <url2> --selector "#main"  # Auf Element beschränken

Häufige Muster

Formularübermittlung

agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle

Authentifizierung mit Zustandspersistenz

# Einmal anmelden und Zustand speichern
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

# In zukünftigen Sitzungen wiederverwenden
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

Sitzungspersistenz

# Cookies und localStorage automatisch speichern/wiederherstellen über Browser-Neustarts hinweg
agent-browser --session-name myapp open https://app.example.com/login
# ... Login-Vorgang ...
agent-browser close  # Zustand automatisch gespeichert in ~/.agent-browser/sessions/

# Beim nächsten Mal wird der Zustand automatisch geladen
agent-browser --session-name myapp open https://app.example.com/dashboard

# Zustand im Ruhezustand verschlüsseln
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com

# Gespeicherte Zustände verwalten
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7

Datenextraktion

agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5           # Text eines bestimmten Elements abrufen
agent-browser get text body > page.txt  # Gesamten Seitentext abrufen

# JSON-Ausgabe zum Parsen
agent-browser snapshot -i --json
agent-browser get text @e1 --json

Parallele Sitzungen

agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com

agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i

agent-browser session list

Mit vorhandenem Chrome verbinden

# Laufenden Chrome mit Remote-Debugging automatisch erkennen
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot

# Oder mit explizitem CDP-Port
agent-browser --cdp 9222 snapshot

Visueller Browser (Debugging)

agent-browser --headed open https://example.com
agent-browser highlight @e1          # Element hervorheben
agent-browser record start demo.webm # Sitzung aufzeichnen
agent-browser profiler start         # Chrome DevTools-Profiling starten
agent-browser profiler stop trace.json # Profiling stoppen und speichern (Pfad optional)

Lokale Dateien (PDFs, HTML)

# Lokale Dateien mit file:// URLs öffnen
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png

iOS-Simulator (Mobile Safari)

# Verfügbare iOS-Simulatoren auflisten
agent-browser device list

# Safari auf einem bestimmten Gerät starten
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# Gleicher Workflow wie Desktop - Snapshot, Interaktion, erneuter Snapshot
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1          # Tippen (Alias für click)
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up         # Mobilspezifische Geste

# Screenshot machen
agent-browser -p ios screenshot mobile.png

# Sitzung schließen (fährt Simulator herunter)
agent-browser -p ios close

Voraussetzungen: macOS mit Xcode, Appium (npm install -g appium && appium driver install xcuitest)

Reale Geräte: Funktioniert mit physischen iOS-Geräten, wenn diese vorkonfiguriert sind. Verwenden Sie --device "<UDID>" wobei UDID von xcrun xctrace list devices stammt.

Diffing (Änderungen überprüfen)

Verwenden Sie diff snapshot nach einer Aktion, um zu überprüfen, ob sie die beabsichtigte Wirkung hatte. Dies vergleicht den aktuellen Barrierefreiheitsbaum mit dem letzten Snapshot in der Sitzung.

# Typischer Workflow: Snapshot -> Aktion -> Diff
agent-browser snapshot -i          # Basis-Snapshot erstellen
agent-browser click @e2            # Aktion ausführen
agent-browser diff snapshot        # Änderungen anzeigen (automatischer Vergleich mit letztem Snapshot)

Für visuelle Regressionstests oder Überwachung:

# Basis-Screenshot speichern, später vergleichen
agent-browser screenshot baseline.png
# ... Zeit vergeht oder Änderungen werden vorgenommen ...
agent-browser diff screenshot --baseline baseline.png

# Staging mit Produktion vergleichen
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot

diff snapshot verwendet + für Hinzufügungen und - für Entfernungen, ähnlich wie git diff. diff screenshot erzeugt ein Diff-Bild, in dem geänderte Pixel rot hervorgehoben sind, sowie einen Prozentsatz der Abweichung.

Timeouts und langsame Seiten

Der standardmäßige Playwright-Timeout beträgt 60 Sekunden für lokale Browser. Für langsame Websites oder große Seiten verwenden Sie explizite Wartebefehle anstatt sich auf den Standard-Timeout zu verlassen:

# Auf Netzwerkberuhigung warten (am besten für langsame Seiten)
agent-browser wait --load networkidle

# Auf ein bestimmtes Element warten
agent-browser wait "#content"
agent-browser wait @e1

# Auf ein bestimmtes URL-Muster warten (nützlich nach Weiterleitungen)
agent-browser wait --url "**/dashboard"

# Auf eine JavaScript-Bedingung warten
agent-browser wait --fn "document.readyState === 'complete'"

# Feste Dauer warten (Millisekunden) als letztes Mittel
agent-browser wait 5000

Bei konstant langsamen Websites verwenden Sie wait --load networkidle nach open, um sicherzustellen, dass die Seite vollständig geladen ist, bevor Sie einen Snapshot machen. Wenn ein bestimmtes Element langsam gerendert wird, warten Sie direkt mit wait <selector> oder wait @ref.

Sitzungsverwaltung und Bereinigung

Wenn mehrere Agenten oder Automatisierungen gleichzeitig ausgeführt werden, verwenden Sie immer benannte Sitzungen, um Konflikte zu vermeiden:

# Jeder Agent erhält seine eigene isolierte Sitzung
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# Aktive Sitzungen prüfen
agent-browser session list

Schließen Sie Ihre Browsersitzung immer, wenn Sie fertig sind, um Prozesslecks zu vermeiden:

agent-browser close                    # Standardsitzung schließen
agent-browser --session agent1 close   # Bestimmte Sitzung schließen

Wenn eine vorherige Sitzung nicht ordnungsgemäß geschlossen wurde, läuft der Daemon möglicherweise noch. Verwenden Sie agent-browser close, um ihn zu bereinigen, bevor Sie neue Arbeiten beginnen.

Referenz-Lebenszyklus (Wichtig)

Referenzen (@e1, @e2, usw.) werden ungültig, wenn sich die Seite ändert. Erstellen Sie immer einen neuen Snapshot nach:

• Klicken auf Links oder Schaltflächen, die navigieren
• Formularübermittlungen
• Laden dynamischer Inhalte (Dropdowns, Modale)

agent-browser click @e5              # Navigiert zu neuer Seite
agent-browser snapshot -i            # MUSS neuen Snapshot erstellen
agent-browser click @e1              # Neue Referenzen verwenden

Annotierte Screenshots (Vision-Modus)

Verwenden Sie --annotate, um einen Screenshot mit nummerierten Beschriftungen zu machen, die über interaktiven Elementen eingeblendet werden. Jedes Label [N] ist der Referenz @eN zugeordnet. Dies speichert auch die Referenzen zwischen, sodass Sie sofort mit Elementen interagieren können, ohne einen separaten Snapshot.

agent-browser screenshot --annotate
# Ausgabe enthält den Bildpfad und eine Legende:
#   [1] @e1 button "Submit"
#   [2] @e2 link "Home"
#   [3] @e3 textbox "Email"
agent-browser click @e2              # Klicken mit Referenz aus annotiertem Screenshot

Verwenden Sie annotierte Screenshots, wenn:

• Die Seite unbeschriftete Symbole oder nur visuelle Elemente hat
• Sie das visuelle Layout oder Styling überprüfen müssen
• Canvas- oder Diagrammelemente vorhanden sind (für Text-Snapshots unsichtbar)
• Sie räumliches Denken über Elementpositionen benötigen

Semantische Locators (Alternative zu Referenzen)

Wenn Referenzen nicht verfügbar oder unzuverlässig sind, verwenden Sie semantische Locators:

agent-browser find text "Sign In" click
agent-browser find label "Email" fill "[email protected]"
agent-browser find role button click --name "Submit"
agent-browser find placeholder "Search" type "query"
agent-browser find testid "submit-btn" click

JavaScript-Auswertung (eval)

Verwenden Sie eval, um JavaScript im Browser-Kontext auszuführen. Shell-Quoting kann komplexe Ausdrücke beschädigen -- verwenden Sie --stdin oder -b, um Probleme zu vermeiden.

# Einfache Ausdrücke funktionieren mit normalem Quoting
agent-browser eval 'document.title'
agent-browser eval 'document.querySelectorAll("img").length'

# Komplexes JS: --stdin mit Heredoc verwenden (EMPFOHLEN)
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
  Array.from(document.querySelectorAll("img"))
    .filter(i => !i.alt)
    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
)
EVALEOF

# Alternative: Base64-Kodierung (vermeidet alle Shell-Escaping-Probleme)
agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"

Warum das wichtig ist: Wenn die Shell Ihren Befehl verarbeitet, können innere doppelte Anführungszeichen, !-Zeichen (History-Expansion), Backticks und $()-Konstrukte das JavaScript beschädigen, bevor es agent-browser erreicht. Die Flags --stdin und -b umgehen die Shell-Interpretation vollständig.

Faustregeln:

• Einzeilig, keine verschachtelten Anführungszeichen -> reguläres eval 'expression' mit einfachen Anführungszeichen ist in Ordnung
• Verschachtelte Anführungszeichen, Pfeilfunktionen, Template-Literale oder mehrzeilig -> eval --stdin <<'EVALEOF' verwenden
• Programmatisch generierte Skripte -> eval -b mit Base64 verwenden

Konfigurationsdatei

Erstellen Sie agent-browser.json im Projektstammverzeichnis für dauerhafte Einstellungen:

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data"
}

Priorität (niedrigste bis höchste): ~/.agent-browser/config.json < ./agent-browser.json < Umgebungsvariablen < CLI-Flags. Verwenden Sie --config <pfad> oder die Umgebungsvariable AGENT_BROWSER_CONFIG für eine benutzerdefinierte Konfigurationsdatei (beendet mit Fehler, wenn fehlend/ungültig). Alle CLI-Optionen sind auf camelCase-Schlüssel abgebildet (z. B. --executable-path -> "executablePath"). Boolesche Flags akzeptieren true/false-Werte (z. B. --headed false überschreibt die Konfiguration). Erweiterungen aus Benutzer- und Projektkonfigurationen werden zusammengeführt, nicht ersetzt.

Vertiefende Dokumentation

Referenz	Wann verwenden
references/commands.md	Vollständige Befehlsreferenz mit allen Optionen

[truncated]