Spectature/dev-browser-local-profile-skill

Dev Browser Local Profile

Verwenden Sie diesen Skill, wenn die Browser-Automatisierung eine Verbindung zu einem langlebigen lokalen Browserprofil herstellen soll, anstatt einen frischen Browserzustand zu starten.

Dieses Projekt wurde von dev-browser übernommen, läuft aber eigenständig und erfordert kein dev-browser.

Kernregeln

• Verwenden Sie die gebündelten Playwright-over-CDP-Skripte anstelle von dev-browser.
• Gehen Sie davon aus, dass ein persistentes Browserprofil die Quelle der Wahrheit für den Login-Zustand ist.
• Bevorzugen Sie einen festen Remote-Debugging-Port. Standardmäßig 9222, sofern der Benutzer nichts anderes angibt.
• Halten Sie Profilpfade benutzerrelativ. Hardcodieren Sie niemals maschinenspezifische Benutzernamen.
• Öffnen Sie standardmäßig einen neuen Tab, anstatt den aktuellen Tab des Benutzers zu ersetzen, es sei denn, dieser wird darum gebeten.

Einrichtungsworkflow

1. Abhängigkeiten installieren

Führen Sie dies einmal im Skill-Verzeichnis aus:

npm install

Dadurch wird nur playwright-core installiert. Es wird kein separater verwalteter Browser heruntergeladen.

2. Chrome oder Chromium mit einem persistenten Profil starten

Verwenden Sie ein festes Benutzerdatenverzeichnis unter dem Home-Verzeichnis des aktuellen Benutzers:

• Windows: Join-Path $env:USERPROFILE 'chrome-dev-browser-profile'
• macOS/Linux: ~/chrome-dev-browser-profile

Verwenden Sie das gebündelte Startskript für den plattformübergreifenden Start:

python scripts/start_chrome_debug.py

Nützliche Optionen:

python scripts/start_chrome_debug.py --port 9222
python scripts/start_chrome_debug.py --profile-dir "C:\Users\name\chrome-dev-browser-profile"
python scripts/start_chrome_debug.py --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

3. Die eigenständigen Browser-Tools verwenden

Öffnen Sie eine URL in einem neuen Tab:

node scripts/browser_tools.mjs open --url "http://localhost:9800/h5-bzzx/"

Aktuelle Tabs auflisten:

node scripts/browser_tools.mjs list

Einen Screenshot erstellen:

node scripts/browser_tools.mjs screenshot --url "http://localhost:9800/h5-bzzx/" --output "./page.png"

4. Benutzerdefinierte Automatisierungsaufgaben ausführen

Verwenden Sie den generischen Task-Runner für mehr als einfache Open-/List-/Screenshot-Abläufe:

node scripts/run_task.mjs --task ./my-task.mjs --url "http://localhost:9800/h5-bzzx/" --task-arg mode=debug

Task-Module sollten eine standardmäßige asynchrone Funktion oder eine benannte run-Funktion exportieren.

Beispiel:

export default async function ({ page, helpers, taskArgs }) {
  await page.waitForLoadState("domcontentloaded");
  return {
    title: await page.title(),
    url: page.url(),
    taskArgs
  };
}

Hash-Routen-Handhabung

Verlassen Sie sich nicht auf json/new?... oder ähnliche direkte DevTools-Öffnungsabläufe für Hash-Routen-URLs. Der #...-Teil könnte verloren gehen.

Für Hash-Routen verwenden die gebündelten Skripte bereits eine zweistufige Navigationsstrategie:

1. Öffnen Sie zuerst die Basis-URL.
2. Setzen Sie dann window.location.href innerhalb der Seite.

Beispiel:

node scripts/browser_tools.mjs open --url "http://localhost:9527/#/inspection/log/list?book_id=352"

Überprüfungs-Checkliste

Überprüfen Sie den Erfolg nach dem Öffnen einer Seite explizit:

• Prüfen Sie, ob die url in der JSON-Ausgabe mit der erwarteten Route übereinstimmt.
• Prüfen Sie den title oder einen bekannten Selektor, wenn die Seite dynamische Titel hat.
• Wenn die Aktion still zu sein scheint, führen Sie node scripts/browser_tools.mjs list vor einem erneuten Versuch aus.
• Wenn der Login fehlt, bestätigen Sie, dass Chrome mit dem persistenten Profil und nicht mit einem temporären Profil gestartet wurde.

Fehlermodi

Browser-Tools konnten keine Verbindung herstellen

Wahrscheinliche Ursache: Chrome läuft nicht mit --remote-debugging-port=<port>.

Behebung:

• Starten Sie Chrome neu mit python scripts/start_chrome_debug.py.
• Bestätigen Sie, dass der Port mit dem übereinstimmt, der an die Skripte übergeben wurde.

Neuer Tab geöffnet, aber Route war falsch

Wahrscheinliche Ursache: Hash-Routen-Kürzung in einem externen Tool oder eine manuell gekürzte URL.

Behebung:

• Verwenden Sie den gebündelten open-Befehl.
• Übergeben Sie die vollständige Hash-Routen-URL.

Login-Zustand fehlt

Wahrscheinliche Ursache: Chrome wurde mit einem anderen Profilverzeichnis gestartet.

Behebung:

• Starten Sie Chrome neu mit dem persistenten --user-data-dir.
• Verwenden Sie dieses Profilverzeichnis konsistent weiter.

Umfang

Dieser Skill ist bewusst workflow-orientiert. Er standardisiert einen eigenständigen Browser-Automatisierungs-Setup für persistenten lokalen Login-Zustand unter Verwendung von Playwright über CDP.