jackyuyz/repo-demo-video-skill

Repo Demo Video

Nutzen Sie diese Fähigkeit, um ein Repository in einen ausgefeilten Produkt-Demo-Plan und, wenn genügend Laufzeitinformationen verfügbar sind, ein im Browser aufgezeichnetes Demo-Video zu verwandeln.

Kernprinzip

Bevorzugen Sie Beweise aus dem Repository gegenüber einer perfekten Benutzerkonfiguration:

1. Verwenden Sie demo.config.json oder demo.config.yaml, falls vorhanden.
2. Verwenden Sie DEMO_GUIDE.md, falls vorhanden.
3. Verwenden Sie README.md.
4. Verwenden Sie package.json, Framework-Dateien, Routenordner, Komponentennamen, Seitentitel und die Quellstruktur.
5. Erkunden Sie eine bereitgestellte oder lokale App im Browser, wenn eine sichere URL existiert.
6. Generieren Sie Fallback-Annahmen mit Konfidenzwerten.

Behandeln Sie README.md plus Quellcode als primäre Quelle, DEMO_GUIDE.md als empfohlenen menschenlesbaren Leitfaden und demo.config.* als optionalen maschinenlesbaren Überschreibungsmechanismus.

Arbeitsablauf

1. Lösen Sie den Repository-Pfad oder die URL auf. Verwenden Sie für die MVP-CLI einen lokalen Repository-Pfad; bei einer GitHub-URL bitten Sie den Benutzer, einen lokalen Klon bereitzustellen, es sei denn, ein zukünftiger Klon-Workflow ist explizit verfügbar.

2. Führen Sie den Analysator aus:

   npm run demo -- --repo ./pfad/zum/repo
   

   Optionale Eingaben:

   npm run demo -- --repo ./pfad/zum/repo --config ./demo.config.json
   npm run demo -- --repo ./pfad/zum/repo --url https://beispiel.com
   npm run demo -- --repo ./pfad/zum/repo --mode draft
   npm run demo -- --repo ./pfad/zum/repo --mode full
   

3. Überprüfen Sie die generierten Artefakte in einem mit Zeitstempel versehenen Ausgabeordner wie demoOutput-2026-05-10-143012/:

   • project_summary.md
   • demo_plan.draft.json
   • demo_plan.json bei ausreichend hohem Konfidenzniveau
   • narration_script.draft.md
   • narration_script.md
   • script_quality_report.json
   • timing_plan.json
   • demo_storyboard.md
   • manual_recording_guide.md
   • recordings/ bei erfolgreicher Browser-Aufnahme
   • screenshots/ bei erfolgreicher Browser-Erkundung
   • voiceover.mp3 wenn TTS_PROVIDER=openai und OPENAI_API_KEY verfügbar sind
   • demo_video.html als lokales Vorschau-Fallback, wenn die MP4-Komposition unvollständig ist
   • demo_video.mp4 nur wenn Aufnahme, echtes Audio und ffmpeg verfügbar sind

Konfidenzregeln

• Markieren Sie explizite Dokumentations- und Konfigurationsangaben als high.
• Behandeln Sie README-Funktionslisten als ausreichenden Beleg für die Erstellung eines endgültigen Plans, wenn Projektname, Zusammenfassung und mindestens eine Funktion klar sind.
• Markieren Sie Routennamen, Komponentennamen, Paket-Metadaten und klare Codestruktur als medium.
• Markieren Sie spekulative Produktbehauptungen und geschätzte Aktionen als low.
• Wenn wichtige Behauptungen eine niedrige Konfidenz aufweisen, generieren Sie demo_plan.draft.json, erklären Sie, was fehlt, und vermeiden Sie es, den endgültigen Videoplan als sicher darzustellen.

README-Parsing

• Ignorieren Sie Badges, Shield-Bilder, dekorative Bildzeilen, rohe URLs und Lizenz-/Status-Metadaten beim Extrahieren von Produktzusammenfassungen.
• Bevorzugen Sie DEMO_GUIDE.md-Pitch, README-Blockquote-Zusammenfassung, README-Übersichts-/Info-/Beschreibungsabschnitte, dann Paketbeschreibung.
• Erkennen Sie dekorierte Überschriften wie ## Features mit Emojis oder Symbolen, indem Sie Überschriften vor dem Abgleich normalisieren.
• Extrahieren Sie Aufzählungspunkte unter Feature-/Fähigkeits-/Highlight-Überschriften als hochvertrauenswürdige Funktionen.
• Extrahieren Sie nummerierte Arbeitsabläufe unter Usage-/How-To-/Demo-/Quick-Start-Überschriften als mittelvertrauenswürdige Demo-Fluss-Hinweise.
• Bereinigen Sie Erzähleingaben vor dem Schreiben von Skripten; übernehmen Sie keine Markdown-Badges, Bildsyntax oder rohe URLs in den Voiceover-Text.

Sicherheit

• Führen Sie die Repository-Analyse schreibgeschützt durch.
• Schreiben Sie generierte Artefakte nur in einen neuen, mit Zeitstempel versehenen Ordner demoOutput-YYYY-MM-DD-HHMMSS/ im Ziel-Repository.
• Löschen Sie keine Dateien rekursiv und führen Sie keine destruktiven Befehle aus.
• Führen Sie keine Bereitstellungsbefehle aus.
• Externe LLM/TTS-Aufrufe sind erlaubt, wenn der Benutzer eine kommentierte Ausgabe anfordert oder Umgebungsvariablen des Anbieters konfiguriert. Senden Sie nur bereinigte Projektzusammenfassungen, Demo-Pläne, Browser-Beobachtungen und Erzählskripttexte.
• Senden Sie keine rohen .env-Dateien, API-Schlüssel, privaten Token, privaten Benutzerdaten, echten Anmeldeinformationen oder unnötigen Quellcode an externe LLM/TTS-Anbieter.
• Geben Sie keine Geheimnisse, API-Schlüssel, privaten Token, .env-Werte, privaten Benutzerdaten oder echten Anmeldeinformationen in Erzählungen, Screenshots, Videos, Protokollen oder generierten Artefakten preis.
• Wenn ein Testkonto dokumentiert ist, erwähnen Sie nur, dass ein Demo-Konto verwendet wird, es sei denn, der Benutzer bittet explizit um etwas anderes.

Browser- und Videoverhalten

• Bevorzugen Sie eine bereitgestellte demoUrl aus der Konfiguration, DEMO_GUIDE.md, README.md oder dem --url-Argument.
• Verwenden Sie Playwright, wenn verfügbar, um sichtbare Überschriften, Schaltflächen, Links, Formulare zu inspizieren und Screenshots oder Aufnahmen zu erstellen.
• Verwenden Sie konservative DOM-Heuristiken, um sichere Beispiel-Eingaben auszufüllen, nicht leere Auswahloptionen auszuwählen und häufige Demo-Steuerelemente wie "Hinzufügen", "Berechnen", "Methode", "Ressourcen", "Neu" oder "Erstellen" anzuklicken.
• Halten Sie jede geplante Szene lange genug auf dem Bildschirm, um das Erzähltempo zu ermöglichen, und machen Sie nach heuristischen Aktionen eine kurze Pause, damit die Aufnahme nicht nur aus schnellen Klicks besteht.
• Registrieren Sie den kanonischen .webm-Aufnahmepfad in run_report.json.
• Erzwingen Sie keinen lokalen Projektstart, wenn die Ausführungsanweisungen unsicher sind.
• Wenn Playwright, TTS, ffmpeg oder die App-Laufzeit nicht verfügbar sind, erstellen Sie dennoch die schriftlichen Artefakte, Teillieferungen, demo_video.html und eine manuelle Aufzeichnungsanleitung.
• Komponieren Sie das endgültige MP4 anhand der Voiceover-Dauer. Verwenden Sie keine Kürzung des kürzesten Streams. Wenn die Browser-Aufnahme kürzer als das Voiceover ist, verlängern Sie den letzten Videoframe mit ffmpeg tpad und melden Sie die Verlängerungsdauer.

Professionelles Skript-Schreiben

• Verwenden Sie den deterministischen Entwurf als Fallback, bevorzugen Sie aber den OpenAI-Skript-Schreiber, wenn SCRIPT_PROVIDER=openai und OPENAI_API_KEY gesetzt sind.
• Generieren Sie timing_plan.json vor dem Schreiben des endgültigen Skripts. Basieren Sie ihn auf verfügbaren Funktionen, Browserszenen, konfigurierter Videodauer und Tempo-Warnungen.
• Verwenden Sie denselben OPENAI_API_KEY für das Skript-Schreiben und OpenAI TTS.
• Steuern Sie den Produkt-Demo-Schreib-Prompt in src/prompts/demoNarrationPrompt.ts.
• Steuern Sie das OpenAI Responses API-Modell mit OPENAI_SCRIPT_MODEL; falls nicht gesetzt, fallen Sie auf OPENAI_MODEL und dann gpt-5.4-mini zurück.
• Schreiben Sie narration_script.draft.md für den Vorlagenentwurf und narration_script.md für das endgültige LLM- oder Fallback-Skript.
• Schreiben Sie script_quality_report.json mit Anbieter, Modell, Fallback-Grund und Qualitäts-Warnungen.
• Der Prompt sollte den Skript-Schreiber veranlassen, das Produkt zuerst zu verstehen, Badges und rohe README-Metadaten zu vermeiden, sich auf Zielgruppe/Problem/Wert zu konzentrieren, konservative Formulierungen für unsichere Behauptungen zu verwenden und die Szenenzahl und das Wortbudget des Zeitplans zu respektieren.

Demo-Visuelle Hinweise

Für ausgefeilte Browser-Aufnahmen injizieren Sie temporäre, nicht persistente visuelle Hinweise-Overlays über Playwright, anstatt den App-Quellcode zu bearbeiten.

Verwenden Sie:

• Eine dezente Callout-Beschriftung für den aktuellen Erzählschritt.
• Einen Hervorhebungsring um das aktive UI-Element oder Ergebnisbereich.
• Hohes z-index, pointer-events: none und feste Positionierung.
• Neutrales Styling, das die Produkt-UI nicht verdeckt.

Verwenden Sie keine Overlays, um Funktionalität vorzutäuschen. Verwenden Sie sie nur, um die Aufmerksamkeit des Betrachters auf reale UI-Zustandsänderungen zu lenken. Die Overlays dürfen nur in der aufnehmenden Browser-Sitzung existieren und verschwinden, wenn die Sitzung geschlossen wird.

Voiceover

• Standardmäßig wird OpenAI TTS im vollständigen Modus verwendet, wenn OPENAI_API_KEY gesetzt ist.
• Um explizit echtes Audio zu generieren, setzen Sie TTS_PROVIDER=openai und OPENAI_API_KEY.
• Wenn TTS_PROVIDER nicht gesetzt ist, aber OPENAI_API_KEY existiert, verwenden Sie OpenAI TTS.
• Um den lokalen Mock-Modus zu erzwingen, setzen Sie TTS_PROVIDER=mock.
• OPENAI_API_KEY kann derselbe Schlüssel sein, der vom professionellen Skript-Schreiber verwendet wird.
• Optionale Variablen: OPENAI_TTS_MODEL, OPENAI_TTS_VOICE, OPENAI_TTS_INSTRUCTIONS, TTS_VOICE.
• Schreiben Sie echtes Audio in den aktuellen Ausführungsordner, z.B. demoOutput-2026-05-10-143012/voiceover.mp3.
• Das Senden des bereinigten voiceover_script.txt-Textes an den konfigurierten TTS-Anbieter ist erforderlich, um Voiceover-Audio zu erstellen.
• Schreiben Sie niemals API-Schlüssel in generierte Dateien.
• Geben Sie bei der Veröffentlichung der Demo an, dass das generierte Voiceover KI-generiert ist.

Erweiterung der Fähigkeit

Halten Sie die Architektur modular. Fügen Sie zukünftige Unterstützung für GitHub-URL-Klonen, tiefere UI-Interaktion, echte TTS-Anbieter, Untertitel, Videostile, lokales Starten und menschliche Überprüfung hinzu, indem Sie das entsprechende src/*.ts-Modul erweitern, anstatt die CLI in ein großes Skript zu verwandeln.