jackyuyz/repo-demo-video-skill

Vidéo de Démo de Dépôt

Utilisez ce skill pour transformer un dépôt en un plan de démonstration produit soigné et, lorsque suffisamment d’informations d’exécution sont disponibles, en une vidéo de démo enregistrée via navigateur.

Principe Fondamental

Privilégiez les preuves du dépôt plutôt qu’une configuration parfaite de l’utilisateur :

1. Utilisez demo.config.json ou demo.config.yaml s’ils sont présents.
2. Utilisez DEMO_GUIDE.md s’il est présent.
3. Utilisez README.md.
4. Utilisez package.json, les fichiers du framework, les dossiers de routes, les noms de composants, les titres de pages et la structure du code source.
5. Explorez une application déployée ou locale dans le navigateur si une URL sûre existe.
6. Générez des hypothèses de repli avec des scores de confiance.

Considérez README.md plus le code source comme la source principale, DEMO_GUIDE.md comme le guide recommandé et convivial, et demo.config.* comme une surcharge optionnelle adaptée aux machines.

Workflow

1. Résolvez le chemin ou l’URL du dépôt cible. Pour la CLI MVP, utilisez un chemin de dépôt local ; si une URL GitHub est donnée, demandez à l’utilisateur de fournir un clone local, sauf si un workflow de clonage futur est explicitement disponible.

2. Lancez l’analyseur :

   npm run demo -- --repo ./chemin-vers-le-depot
   

   Entrées optionnelles :

   npm run demo -- --repo ./chemin-vers-le-depot --config ./demo.config.json
   npm run demo -- --repo ./chemin-vers-le-depot --url https://example.com
   npm run demo -- --repo ./chemin-vers-le-depot --mode draft
   npm run demo -- --repo ./chemin-vers-le-depot --mode full
   

3. Examinez les artefacts générés dans un dossier de sortie horodaté tel que demoOutput-2026-05-10-143012/ :

   • project_summary.md
   • demo_plan.draft.json
   • demo_plan.json lorsque la confiance est suffisamment élevée
   • narration_script.draft.md
   • narration_script.md
   • script_quality_report.json
   • timing_plan.json
   • demo_storyboard.md
   • manual_recording_guide.md
   • recordings/ lorsque la capture navigateur réussit
   • screenshots/ lorsque l’exploration navigateur réussit
   • voiceover.mp3 lorsque TTS_PROVIDER=openai et OPENAI_API_KEY sont disponibles
   • demo_video.html comme solution de repli de prévisualisation locale lorsque la composition MP4 est incomplète
   • demo_video.mp4 uniquement lorsque l’enregistrement, l’audio réel et ffmpeg sont disponibles

Règles de Confiance

• Marquez les affirmations explicites de la documentation et de la configuration comme haute.
• Considérez les listes de fonctionnalités du README comme des preuves suffisantes pour générer un plan final lorsque le nom du projet, le résumé et au moins une fonctionnalité sont clairs.
• Marquez les noms de routes, les noms de composants, les métadonnées du package et la structure de code claire comme moyenne.
• Marquez les affirmations spéculatives sur le produit et les actions devinées comme basse.
• Si les affirmations importantes sont de faible confiance, générez demo_plan.draft.json, expliquez ce qui manque et évitez de présenter le plan vidéo final comme certain.

Analyse du README

• Ignorez les badges, les images de bouclier, les lignes d’images décoratives, les URL brutes et les métadonnées de licence/statut lors de l’extraction des résumés produit.
• Préférez le pitch de DEMO_GUIDE.md, le résumé en blocquote du README, les sections overview/about/description du README, puis la description du package.
• Reconnaissez les titres décorés tels que ## Features avec des emojis ou des symboles en normalisant les titres avant la correspondance.
• Extrayez les listes à puces sous les titres de fonctionnalités/capacités/points forts comme fonctionnalités à haute confiance.
• Extrayez les workflows numérotés sous les titres usage/how-to/demo/quick-start comme indices de flux de démo à confiance moyenne.
• Nettoyez les entrées de narration avant d’écrire les scripts ; ne transportez pas les badges Markdown, la syntaxe d’image ou les URL brutes dans le texte de la voix off.

Sécurité

• Maintenez l’analyse du dépôt en lecture seule.
• Écrivez les artefacts générés uniquement dans un nouveau dossier horodaté demoOutput-YYYY-MM-JJ-HHMMSS/ dans le dépôt cible.
• Ne supprimez pas de fichiers de manière récursive et n’exécutez pas de commandes destructrices.
• N’exécutez pas de commandes de déploiement.
• Les appels externes LLM/TTS sont autorisés lorsque l’utilisateur demande une sortie narrée ou configure les variables d’environnement du fournisseur. Envoyez uniquement des résumés de projet nettoyés, des plans de démo, des observations navigateur et le texte du script de narration.
• N’envoyez pas de fichiers .env bruts, de clés API, de jetons privés, de données utilisateur privées, d’identifiants réels ou de fichiers source inutiles à des fournisseurs LLM/TTS externes.
• N’exposez pas de secrets, de clés API, de jetons privés, de valeurs .env, de données utilisateur privées ou d’identifiants réels dans la narration, les captures d’écran, la vidéo, les journaux ou les artefacts générés.
• Si un compte de test est documenté, mentionnez uniquement qu’un compte de démo est utilisé, sauf si l’utilisateur demande explicitement autre chose.

Comportement Navigateur et Vidéo

• Préférez un demoUrl déployé, provenant de la configuration, de DEMO_GUIDE.md, du README ou de l’argument --url.
• Utilisez Playwright lorsqu’il est disponible pour inspecter les titres, boutons, liens, formulaires visibles et capturer des captures d’écran ou des enregistrements.
• Utilisez des heuristiques DOM prudentes pour remplir des exemples d’entrées sûrs, choisir des options de sélection non vides et cliquer sur des contrôles de démo courants tels que Ajouter, Calculer, Méthode, Ressources, Nouveau ou Créer.
• Maintenez chaque scène planifiée à l’écran assez longtemps pour le rythme de la narration, et faites une pause brève après les actions heuristiques afin que l’enregistrement ne soit pas qu’une série de clics rapides.
• Enregistrez le chemin canonique de l’enregistrement .webm dans run_report.json.
• Ne forcez pas le démarrage du projet local lorsque les instructions d’exécution sont incertaines.
• Si Playwright, TTS, ffmpeg, ou l’environnement d’exécution de l’application n’est pas disponible, produisez quand même les artefacts écrits, les livrables partiels, demo_video.html et un guide d’enregistrement manuel.
• Composez le MP4 final en fonction de la durée de la voix off. N’utilisez pas le troncature du flux le plus court. Si l’enregistrement navigateur est plus court que la voix off, prolongez la dernière image vidéo avec tpad de ffmpeg et signalez la durée de prolongation.

Rédaction Professionnelle de Scripts

• Utilisez le brouillon déterministe comme solution de repli, mais préférez le rédacteur de script OpenAI lorsque SCRIPT_PROVIDER=openai et OPENAI_API_KEY sont définis.
• Générez timing_plan.json avant d’écrire le script final. Basez-le sur les fonctionnalités disponibles, les scènes navigateur, la durée vidéo configurée et les avertissements de rythme.
• Utilisez la même OPENAI_API_KEY pour la rédaction du script et pour OpenAI TTS.
• Contrôlez l’invite de rédaction de démo produit dans src/prompts/demoNarrationPrompt.ts.
• Contrôlez le modèle de l’API Responses d’OpenAI avec OPENAI_SCRIPT_MODEL ; s’il n’est pas défini, utilisez OPENAI_MODEL comme valeur de repli, puis gpt-5.4-mini.
• Écrivez narration_script.draft.md pour le brouillon modèle et narration_script.md pour le script final LLM ou de repli.
• Écrivez script_quality_report.json avec le fournisseur, le modèle, la raison du repli et les avertissements de contrôle qualité.
• L’invite doit faire comprendre le produit au rédacteur de script en premier, éviter les badges et les métadonnées brutes du README, se concentrer sur le public/le problème/la valeur, utiliser un langage prudent pour les affirmations incertaines et respecter le nombre de scènes et le budget de mots du plan de timing.

Guidage Visuel de la Démo

Pour les enregistrements navigateur soignés, injectez des superpositions de guidage visuel temporaires et non persistantes via Playwright plutôt que de modifier le code source de l’application.

Utilisez :

• Une légende d’appel subtile pour le temps de narration en cours.
• Un anneau de surbrillance autour de l’élément d’interface actif ou de la zone de résultat.
• Un z-index élevé, pointer-events: none, et un positionnement fixe.
• Un style neutre qui n’obscurcit pas l’interface du produit.

N’utilisez pas de superpositions pour fabriquer des fonctionnalités. Utilisez-les uniquement pour guider l’attention du spectateur vers des changements réels d’état de l’interface. Les superpositions doivent exister uniquement dans la session navigateur d’enregistrement et disparaître lorsque la session se ferme.

Voix Off

• Par défaut, utilisez OpenAI TTS en mode complet lorsque OPENAI_API_KEY est défini.
• Pour générer explicitement de l’audio réel, définissez TTS_PROVIDER=openai et OPENAI_API_KEY.
• Si TTS_PROVIDER n’est pas défini mais que OPENAI_API_KEY existe, utilisez OpenAI TTS.
• Pour forcer le mode local factice, définissez TTS_PROVIDER=mock.
• OPENAI_API_KEY peut être la même clé que celle utilisée par le rédacteur de script professionnel.
• Variables optionnelles : OPENAI_TTS_MODEL, OPENAI_TTS_VOICE, OPENAI_TTS_INSTRUCTIONS, TTS_VOICE.
• Écrivez l’audio réel dans le dossier de l’exécution en cours, par exemple demoOutput-2026-05-10-143012/voiceover.mp3.
• L’envoi du texte nettoyé de voiceover_script.txt au fournisseur TTS configuré est nécessaire pour créer l’audio de la voix off.
• N’écrivez jamais de clés API dans les fichiers générés.
• Divulguez que la voix off générée est produite par IA lors de la publication de la démo.

Extension du Skill

Gardez l’architecture modulaire. Ajoutez la prise en charge future du clonage d’URL GitHub, d’interactions UI plus profondes, de vrais fournisseurs TTS, de sous-titres, de styles vidéo, de démarrage local et de révision humaine en étendant le module src/*.ts correspondant plutôt que de transformer la CLI en un seul grand script.