Ref-Researcher

Reference Researcher (ref-researcher)

Übersicht

ref-researcher verwandelt rohe Inspiration (Live-Websites, Design-Galerien, App-Aufzeichnungen, UI-Screenshots oder gespeichertes HTML) in einen meinungsstarken, ausführungsbereiten .md Design- & Produkt-Spielplan, bevor mit dem Design oder der Programmierung begonnen wird.

Verwenden Sie diese Fertigkeit für Mobile-App-Funktionen, Web-App-Abläufe oder Marketing-Websites, wenn Sie visuelle Gestaltung, Bewegungsabläufe, Textmuster und negative Beispiele aus externen Referenzen gründlich untersuchen müssen – ohne die Verbindung zu den tatsächlichen Marken-Tokens, Plattformregeln und dem Lieferumfang Ihres Projekts zu verlieren.

Abhängigkeiten

Koordiniere diese installierten Fertigkeiten, anstatt deren Zuständigkeiten zu duplizieren:

• uv – Python-CLI-Skripte sauber via uv run prüfen und aufrufen (nur auf python3 zurückgreifen, wenn streng offline/ohne installiertes uv mit der Standardbibliothek gearbeitet wird).
• chrome-devtools – JS-lastige SPAs rendern, Live-Layout-/Animationsverhalten inspizieren und ganzseitige Screenshots oder interaktive Browser-Sitzungen erfassen, wenn statisches HTTP-Abfragen auf Client-seitige Shells (needs_browser_capture: true) oder geschützte Seiten trifft.
• frontend-design – Visuelle Perspektive, Typografie-Paarung, räumliche Zurückhaltung und Anti-Template-Kritik bei der Synthese von Web-Apps oder Marketing-Websites leiten.
• apple-hig-designer – Native iOS/iPadOS/watchOS-Komponententreue, Safe Areas, Sheets, Dynamic Type und Barrierefreiheit validieren, wenn Mobile-App-Funktionen oder native Apple-Geräte-Präsentationen synthetisiert werden.

Schnellstart

Sie können entweder von Live-URLs (Abrufen von öffentlichem HTML/Assets und Erfassen von Browser-Screenshots) oder von einem vorhandenen lokalen Referenzordner starten:

# 1. Gespeicherte HTML-Referenzen in strukturiertes JSON extrahieren
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./Docs/References & Inspo" \
  --limit 25 \
  --output "/tmp/ref_html_summary.json"

# 2. Extrahöhe Screenshots zuschneiden und Video-Keyframes in Scratch extrahieren (1024px breit)
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./Docs/References & Inspo" \
  --scratch-dir "/tmp/ref_slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/ref_media_manifest.json"

Hilfsskripte

Alle programmatischen Extraktionen, Zuschneidevorgänge, höflichen HTTP-Abfragen und Link-Prüfungen sind in scripts/ref_researcher.py enthalten. Jeder Befehl erfordert explizite Grenzen und --output <datei.json> (schreibt nur eine kurze Zusammenfassung auf die Standardausgabe).

1. fetch-page — Höflicher öffentlicher URL & Asset-Abrufer

Lädt statisches HTML und die wichtigsten Stylesheets/Bilder von öffentlichen URLs herunter und erkennt dabei Login-Wände, Bot-Herausforderungen und Client-seitige JavaScript-Shells (needs_browser_capture: true).

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py fetch-page \
  --url "https://example.com" \
  --asset-dir "./refs/example" \
  --max-assets 20 \
  --output "/tmp/fetch_example.json"

2. extract-html — Code-, Text-, Typografie- & Token-Extraktor

Analysiert gespeicherte .html- und .css-Dateien bis zu --limit und gibt Titel, Navigationslinks, H1–H3-Hierarchie, CTAs, Textbeispiele, Hex-Farben, font-family-Deklarationen und Animation-Bibliotheks-Hinweise (@keyframes, framer, gsap, lottie) aus.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./refs" \
  --limit 25 \
  --output "/tmp/html_summary.json"

3. slice-media — Zuschneider für große Screenshots & Video-Keyframes

Liest die tatsächlichen Pixelabmessungen von Bildern (behandelt falsch benannte Erweiterungen wie JPEG als .webp), teilt große ganzseitige Screenshots in scharfe Viewport-Ausschnitte mit 1024px Breite und extrahiert gleichmäßig verteilte MP4/MOV/WebM-Keyframes via ffmpeg.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./refs" \
  --scratch-dir "<scratch_dir>/slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/slice_manifest.json"

Workspace-Hygiene: Zeigen Sie --scratch-dir immer auf Ihr Gesprächs-Scratch-Verzeichnis (oder /tmp/), niemals in das Repository-Arbeitsverzeichnis des Benutzers.

4. verify-links — Asset-Link-Prüfer für Spielpläne

Validiert jeden relativen Markdown-Link in generierten .md-Dateien auf der Festplatte und beendet das Programm mit dem Exit-Code 1, wenn ein Pfad defekt ist.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py verify-links \
  --markdown "./Docs/References & Inspo/PLAYBOOK.md" \
  --markdown "./Docs/References & Inspo/README.md" \
  --output "/tmp/verify_links.json"

Arbeitsablauf

1. Zuerst Zielprodukt und Einschränkungen prüfen

Bevor Sie einen einzigen Inspirationslink öffnen, lesen Sie die zentralen Dokumente des Zielprojekts (PRD, Markenfarben/-Tokens, Designsystem, Plattformbeschränkungen). Notieren Sie:

• Zieloberfläche: Mobile-App-Funktion, Web-App-Ablauf oder Marketing-Website.
• Visuelle Tokens & Kontrastfallen: Exakte Hex-Werte und WCAG-AA-Mindestanforderungen (z. B. kontrastarme Akzente im Dunkelmodus).
• Produkt-Wahrheits-Matrix: Trennen Sie Lieferung heute vs. Roadmap / Unzulässige Behauptungen.

2. Referenzen sammeln (Live-Abruf, Browser-Erfassung oder vorhandener Ordner)

• Vorhandene lokale Referenzen: Führen Sie sofort extract-html und slice-media für das bereitgestellte Verzeichnis aus.
• Öffentliche URLs / Recherche von Grund auf:
  1. Führen Sie zuerst fetch-page für einen schnellen, ratenbegrenzten statischen HTML- und Asset-Abruf aus.
  2. Wenn needs_browser_capture true ist (React/Next/Vite CSR-Shell) oder ganzseitige visuelle Screenshots benötigt werden, verwenden Sie die chrome-devtools-Fertigkeit (oder den Browser-Workflow), um Bilder/DOM zu rendern und zu erfassen.
  3. Protokoll für authentifizierte/blockierte Seiten (STRENG): Wenn eine Seite HTTP 401/403 zurückgibt, auf /login weiterleitet oder eine Paywall/Bot-Wall anzeigt:
     • Bitten Sie den Benutzer, sich zuerst anzumelden, und wiederholen Sie den Vorgang maximal 2 Mal.
     • Wenn der Zugriff nach 2 Wiederholungen immer noch fehlschlägt, protokollieren Sie die blockierte Quelle klar und wechseln Sie automatisch zu zugänglichen öffentlichen Seiten/Alternativen, damit der Fortschritt nie ins Stocken gerät.

3. Visuell und programmatisch inspizieren (Niemals große Aufnahmen blind überfliegen)

• Ganzseitige Aufnahmen (3840w × 15000px+) werden zu unleserlichen Miniaturansichten verkleinert, wenn sie als Ganzes betrachtet werden. Überprüfen Sie immer die sequentiellen Viewport-Ausschnitte, die von slice-media erstellt wurden, über alle gesammelten Referenzen hinweg sowie die extrahierten Text-/CSS-Tokens von extract-html.
• Kombinieren Sie die visuelle Untersuchung mit Plattformrichtlinien:
  • Rufen Sie apple-hig-designer-Hinweise für iOS/iPadOS-Navigation, Sheets, SF-Symbole und Touch/Dynamic Type-Ergonomie auf.
  • Rufen Sie frontend-design-Hinweise für Web-Typografie-Kontrast, bewusste Weißräume und das Durchbrechen von KI-Vorlagen-Standards auf.

4. Den .md-Spielplan synthetisieren

Schreiben Sie den auslieferbaren Spielplan im Referenzordner des Zielprojekts, indem Sie der references/playbook_template.md folgen. Passen Sie die Blaupause an die Zieloberfläche an, und stellen Sie sicher, dass Folgendes immer enthalten ist:

1. Produkt-Wahrheits- & Einschränkungs-Matrix (einschließlich Dunkel-/Hell-Kontrastfallen)
2. Kreative & UX-Richtlinie der Geschäftsleitung
3. Architektur / Bildschirmablauf-Blaupause
4. Bestandsaufnahme von Zuständen & Randfällen (leer, laden/streamen, teilweise/Limit erreicht, Fehler/Berechtigung)
5. Plattform- & Responsive-Übersetzungs-Matrix
6. Typografie-, Oberflächen-, Bewegungs- & Textregeln
7. Strenges DOS & DON'TS mit konkreten positiven und negativen Beispielen aus Ihrer Sammlung
8. Indizierte Referenz-Asset-Nachschlagetabelle (relative Markdown-Links)
9. Checkliste für die Ausführung & Qualitätssicherung vor dem Bau

Aktualisieren Sie die README.md des Verzeichnisses (falls vorhanden), um den neuen Spielplan ganz oben zu platzieren.

5. Alle relativen Links überprüfen

Führen Sie verify-links für den Spielplan (und die aktualisierte README.md) aus. Beheben Sie jeden Nicht-Null-Exit-Code, bevor Sie die Fertigstellung dem Benutzer melden.

Ratenbegrenzung

• fetch-page erzwingt 1.0 Anforderung/Sekunde (REQUESTS_PER_SECOND = 1.0) über gleichzeitige Agentenprozesse hinweg mittels einer Dateisperre (/tmp/ref_researcher_fetch.lock) und monotone Zeitstempel (time.monotonic()).
• HTTP 429 löst eine exponentielle Verzögerung aus (Retry-After oder 2^Versuch), die auf stderr protokolliert wird, bevor ein RateLimitError ausgelöst wird.
• HTTP 5xx wird mit exponentieller Verzögerung wiederholt; permanente HTTP-Fehler enthalten die URL und den abgeschnittenen Antworttext für eine schnelle Diagnose.

Häufige Fehler

• Unzerschnittene 15.000px hohe Screenshots direkt untersuchen: Führt zu unscharfen Vermutungen und übersehenen Mikrointeraktionen. Schneiden Sie immer zuerst mit slice-media zu.
• Blockierte Logins endlos umgehen oder an einer Paywall hängen bleiben: Bitten Sie den Benutzer einmal, sich anzumelden, wiederholen Sie den Vorgang maximal 2×, wechseln Sie dann sauber zu zugänglichen Quellen und protokollieren Sie die Lücke.
• Marketingbehauptungen von Wettbewerbern mehr vertrauen als der eigenen Codebasis/PRD: Das blinde Kopieren einer „Cloud Sync“- oder „Mac App“-Helden eines Mitbewerbers erzeugt falsche Marketingaussagen. Überprüfen Sie jedes Muster immer anhand der Produkt-Wahrheits-Matrix.
• Relative Links defekt lassen oder Scratch-Bilder im Projekt-Repository ablegen: Schreiben Sie Ausschnitte immer in das Scratch-Verzeichnis und führen Sie verify-links aus, bevor Sie abschließen.

[Dieses Dokument wurde automatisch übersetzt.]