Installation du plugin : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution du plugin lorsque cette compétence se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
D'abord, gardez cette compétence à jour — confirmez avec l'utilisateur avant d'exécuter :
npx hyperframes skills update pr-to-video. Une opération rapide sans effet si tout est à jour ; sinon, elle actualise cette compétence ainsi que les compétences de domaine principales dont elle dépend avant que vous ne les utilisiez.
media-use : Avant de sourcer des audios/images/logos, appelez
/media-usepour résoudre les BGM/SFX/images du catalogue HeyGen et les logos de marque de leurs sources officielles. Exécutez d'abord--adoptpour enregistrer les actifs existants. Voir la compétence/media-use. Lorsque l'application hôte fournit ses propres outils de musique ou d'effets sonores, utilisez-les pour la musique et les effets sonores.
PR vers HyperFrames
Utilisez cette compétence pour ingérer une pull request GitHub, comprendre le changement, planifier une vidéo explicative des modifications de code et la construire image par image dans HyperFrames. L'entrée est une modification de code (lue via gh), pas un site web — il n'y a aucune étape de capture et aucun actif réel au-delà des avatars des contributeurs.
La porte d'entrée est
/hyperframes. Vous êtes l'orchestrateur. Exécutez chaque étape, vérifiez sa passerelle, et continuez seulement ensuite. Cette compétence est destinée à une pull request GitHub (une modification de code). Pour toute autre intention, un simple « faire une vidéo », ou toute incertitude → lisez/hyperframesd'abord — la couche d'intention possède chaque décision d'itinéraire, et une création fraîche arrivant ici sansBRIEF.mdpasse de toute façon par elle (règle d'ouverture de la configuration).
Vous êtes l'orchestrateur. Travaillez dans le PROJECT_DIR externe résolu, jamais dans le dépôt appelant par défaut. Exécutez les étapes dans l'ordre et passez chaque passerelle avant de continuer. Les étapes avec passerelle utilisateur sont l'étape 0, l'étape 3 et l'étape 6. Lisez ../hyperframes/references/brief-contract.md avant l'étape 0 — elle définit les types de passerelles et comment flow/storyboard de BRIEF.md dérivent le mode qui régit les passerelles des étapes 3/4/6. Faites chaque étape vous-même, sauf l'étape 5, où vous dispatchez un pool limité de workers d'images. Ne mettez pas de règles de conception ou de mouvement ici ; celles-ci vivent dans le sous-agent worker d'images, les ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ locaux de cette compétence, et hyperframes-creative.
Workflow : Étape 0 configuration → hyperframes.json ; Étape 1 ingestion → capture/extracted/ + assets/<login>.png ; Étape 2 système de conception → frame.md ; Étape 3 storyboard/script → STORYBOARD.md et SCRIPT.md ; Étape 3.1 audio → audio_meta.json ; Étape 4 conception visuelle → STORYBOARD.md enrichi ; Étape 5 images → compositions/frames/NN-*.html et index.html ; Étape 6 rendu final → renders/video.mp4.
Étape 0 : Configuration
Objectif : Entrer avec un brief confirmé — incluant la référence PR (une URL complète, une référence <propriétaire>/<dépôt>#<N>, ou « cette PR » dans un dépôt cloné) — créer le projet HyperFrames et rendre le brief durable. Le style est toujours code-éditorial (fixé à l'étape 2, jamais demandé).
Le brief est confirmé par la couche d'intention, pas par des questions posées ici. Règle d'ouverture, dans l'ordre : (1) BRIEF.md existe → lisez-le et ne demandez rien — le brief est réglé, et son flow/storyboard dérivent le mode (contrat de brief § 1). (2) Pas de BRIEF.md mais le projet existe (hyperframes.json / STORYBOARD.md sur le disque) → reprenez à partir des métadonnées du storyboard et des préférences enregistrées ; ne réinterrogez jamais un projet à moitié construit. (3) Ni l'un ni l'autre — une demande de création fraîche arrivée ici directement → lisez /hyperframes et exécutez sa couche d'intention (references/intent-interview.md) : elle vérifie les recettes et les valeurs par défaut mémorisées, et mène les questions de cet itinéraire — y compris la doctrine PR-taille → longueur, qui vit entièrement dans ../hyperframes/references/routes/pr-to-video.md — puis renvoie le brief verrouillé. Les demandes de modification sautent tout cela — allez faire la modification.
Résolvez le répertoire du projet avant d'effectuer tout autre travail. Préservez un répertoire de projet fourni par l'utilisateur ; sinon, utilisez l'emplacement de cache externe durable imprimé par le résolveur. Ne créez jamais videos/ dans le dépôt appelant :
PR="<url | propriétaire/dépôt#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "Projet PR-vers-vidéo : $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
La vérification préalable des capacités s'exécute avant la récupération, le travail de storyboard, l'audio ou le dispatch des images. Si la CLI installée ne peut pas exécuter la commande de validation requise par cette compétence, arrêtez-vous avec son instruction de mise à niveau plutôt que de consommer d'abord le contexte de l'exécution.
Initialisez uniquement si $PROJECT_DIR/hyperframes.json est manquant. Son nom de base provient de la PR, par exemple acme-sdk-pr-1842 ; n'utilisez jamais le nom de l'espace de travail ou un horodatage.
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init vérifie les compétences installées par rapport aux dernières sur GitHub et met à jour l'ensemble global si certaines sont obsolètes.
Chaque commande de chemin relatif ci-dessous s'exécute avec $PROJECT_DIR comme répertoire de travail. Les exemples sans sous-shell explicite signifient (cd "$PROJECT_DIR" && …) ; ne modifiez jamais l'arborescence de travail du dépôt appelant.
Écrivez BRIEF.md immédiatement après init (jamais avant — init refuse un répertoire non vide) : le brief verrouillé de la couche d'intention, forme selon ../hyperframes/references/brief-format.md. Résolvez <MEDIA_DIR> comme le répertoire de la compétence /media-use installée. Ensuite, enregistrez chaque réponse basée sur les préférences avec node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes . (brief-format.md nomme le sous-ensemble). Si la couche d'intention a adopté une recette, exécutez node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <nom> ; elle copie son frame.md dans le projet (l'étape 2 est alors ignorée) et renvoie les squelettes à partir desquels l'étape 3 rédige. Une recette remplit les réponses, pas les approbations ; les passerelles de révision s'exécutent toujours.
Affichez l'état de connexion avant de passer la configuration — exécutez npx hyperframes auth status et relayez sa sortie textuellement. Il indique si la voix/BGM utilisera HeyGen ou les moteurs locaux et, lorsqu'il est déconnecté, comment se connecter. Appliquez une branche :
- Collaboratif : attendez que l'utilisateur se connecte ou choisisse explicitement
offline/go. - Autonome : indiquez l'état et continuez via les moteurs locaux disponibles.
N'omettez pas silencieusement une capacité requise lorsqu'aucun fournisseur hors ligne n'existe ; signalez le blocage. Ne réduisez pas cette décision à une autre question et n'écrivez pas de clés dans un .env par dépôt. Propriété de l'authentification et solutions de repli hors ligne : /media-use references/setup-providers.md § Fournisseurs.
Passerelle : hyperframes.json et BRIEF.md existent ; la référence PR est capturée dans le brief ; les réponses basées sur les préférences ont été enregistrées (contrat de brief § 2) ; l'état de connexion a été affiché (connecté, ou continuation hors ligne).
Étape 1 : Ingérer la PR (pas de capture)
Objectif : Récupérer les faits de la PR et les intégrer dans le projet comme source d'information. Il n'y a aucune capture de site web. fetch-pr.mjs exécute gh de manière déterministe — complétant la liste des fichiers via gh api paginé afin qu'une grande PR ne soit pas tronquée à ~100 fichiers, et écrivant uniquement capture/pr.json + capture/diff.patch (pas de répertoire temporaire). Pour les PR FUSIONNÉES, il résout également un shipped_version ( + version_source) au mieux dans pr.json, afin que la carte de fin puisse citer une version réelle au lieu d'en inventer une. Ensuite, ingest.mjs intègre cela dans le package de capture synthétique hors ligne.
PR="<url | propriétaire/dépôt#N | N>"
# Récupérer la PR de manière déterministe : exécute gh, complète la liste des fichiers via gh api paginé
# (afin qu'une grande PR ne soit pas tronquée à ~100 fichiers), écrit uniquement capture/pr.json +
# capture/diff.patch — pas de répertoire temporaire. Les erreurs gh auth / not-found / private sortent avec 1 ici.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# Transformation hors ligne → capture/extracted/{tokens.json (colors:[] → palette code-éditoriale),
# visible-text.txt (le brief), people.json (contributeurs, filtrés des bots, nom+login,
# avatarFile=assets/<login>.png)}.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# La seule étape réseau du volet personnes — télécharger l'avatar GitHub de chaque contributeur vers
# assets/<login>.png pour le générique de fin. Au mieux ; toujours sort avec 0.
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
Si fetch-pr.mjs sort avec 1 (gh auth / not found / private), signalez sa stderr et arrêtez-vous — ne fabriquez pas le contenu de la PR. Si ingest.mjs sort avec 1, lisez sa stderr (généralement un pr.json malformé), corrigez et réexécutez (déterministe). fetch-people-avatars.mjs sort toujours avec 0 ; des avatars manquants signifient simplement qu'il n'y a pas de générique de fin pour l'auteur.
people.json porte un name pour les contributeurs que gh a déjà nommés (l'auteur de la PR, les auteurs de commits, mergedBy) — null pour les autres (réviseurs/commentateurs/assignés, que gh pr view ne donne jamais qu'un simple login). Avant d'écrire le générique de fin à l'étape 3, résolvez vous-même tout null name pour les 1 à 6 personnes qui apparaîtront réellement sur cette image : gh api users/<login> --jq .name (vous avez déjà gh — pas besoin de le scripter). Si GitHub n'a pas non plus de nom public pour cet utilisateur, utilisez le login à l'écran et supprimez cette personne de la ligne parlée (voir la section crédits de story-design.md — la voix off doit toujours dire les noms, jamais les identifiants bruts).
Passerelle : capture/pr.json, capture/diff.patch, capture/extracted/tokens.json, capture/extracted/visible-text.txt et capture/extracted/people.json existent ; vous pouvez énoncer le changement de la PR en une phrase claire. assets/<login>.png est au mieux — son absence n'est pas un échec.
Étape 2 : Système de conception
Objectif : Adopter le préréglage d'image code-éditorial ; un script le transforme en frame.md de cette vidéo + skin de légende.
Le style est fixe — code-éditorial (éditorial chaleureux ; une surface de code marine conçue pour les diffs). Exécutez :
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
Le script copie le FRAME.md du préréglage code-éditorial → frame.md, le remixe avec les éventuels tokens de marque dans capture/extracted/tokens.json (une PR n'en a pas → colors:[]/fonts:[] conserve la propre palette du code-éditorial, une conception complète), copie le skin de légende du préréglage vers .hyperframes/caption-skin.html, et s'auto-valide (sort avec 1 en cas de mapping cassé). Continuez dès qu'il sort avec 0 — pas de modification manuelle.
Passerelle : build-frame.mjs est sorti avec 0 — frame.md existe depuis le préréglage code-éditorial, et .hyperframes/caption-skin.html existe comme source du skin de légende.
Étape 3 : Storyboard et script
Objectif : Transformer la PR en un plan d'explication image par image approuvé.
Lisez ../hyperframes-creative/references/story-spine.md (langage d'accroche, valeur-avant-preuve, storyboard-comme-proposition, visuels traçables à la source), references/story-design.md, ../hyperframes-animation/blueprints-index.md, ../hyperframes/references/storyboard-format.md et ../hyperframes/references/script-format.md. Utilisez-les pour écrire STORYBOARD.md et, lorsque la narration est nécessaire, SCRIPT.md. Définissez la duration: des métadonnées à partir de la length du brief — une attente approximative ; l'assemblage indique où la coupe se situe par rapport à celle-ci.
Utilisez story-design.md pour l'archétype de la PR (journal des changements / révélation de fonctionnalité / explicatif de correctif / présentation de refactorisation), les types d'images natifs de la PR, l'accroche, la persuasion, les séquences, le budget de mots par image, et le générique de fin. La séquence provient de la conception narrative, pas de l'ordre des fichiers de la diff — expliquez le changement, ne lisez pas la diff à voix haute. Comme guide souple, consultez le menu rôle→plan dans ../hyperframes-animation/blueprints-index.md : pour chaque séquence, écrivez la voix off dans la forme qu'implique son plan candidat et étiquetez cet id de plan blueprint: quand un correspond (la vérité de l'histoire décide toujours quelles séquences existent — ne forcez jamais une séquence à correspondre à une forme). Présentez 2 à 4 véritables extraits de diff (de capture/diff.patch), chacun comme un petit snippet lisible ; nommez le bloc code-* que chacun souhaite dans la scene de l'image. Les images ne portent pas de asset_candidates sauf le générique credits (1 à 6 avatars assets/<login>.png). Utilisez les champs exacts requis des références de storyboard et de script.
Après la rédaction, exécutez le passage de plan de la boucle de révision — ../hyperframes/references/review-loop.md § 1 : présentez le plan comme une proposition, et posez les deux questions — approuver ou modifier, et esquisses d'abord (recommandé) ou passer. Les retours arrivent sous forme de réponse de chat ; bouclez jusqu'à approbation. C'est une passerelle de point de contrôle (contrat de brief § 1) : en mode autonome, il n'y a rien à demander — publiez le même résumé comme un avertissement et continuez ; les esquisses se fondent dans la construction, et l'aperçu final avec sa question unique vient à l'étape 6.
Passerelle : STORYBOARD.md existe, chaque image a les champs narratifs requis, SCRIPT.md existe lorsque la narration est nécessaire, et l'utilisateur a approuvé le plan (autonome : le résumé a été publié comme un avertissement).
Étape 3.1 : Audio
Objectif : Générer la narration, les temporisations des mots, la musique et les métadonnées audio à partir du script approuvé.
Démarrez l'audio après l'approbation de l'étape 3. Exécutez-le en arrière-plan, puis continuez à l'étape 4.
Choisissez la voix de narration à partir de la demande de l'utilisateur avant d'invoquer. Si la demande a nommé une voix, un genre ou un ton, choisissez un id de voix correspondant et passez-le avec --voice <id>. La valeur par défaut du pipeline est Marcia (féminine) sur HeyGen / am_michael sur Kokoro — donc une demande comme « une voix masculine » est silencieusement ignorée à moins que vous ne passiez le drapeau. Les ids de voix sont spécifiques au fournisseur ; résolvez-les par rapport au fournisseur que l'état de connexion de l'étape 0 a sélectionné : HeyGen (connecté) via node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list (ou GET /v3/voices?engine=starfish) ; Kokoro (hors ligne) via la table des voix dans <MEDIA_DIR>/audio/references/tts.md (préfixes am_/bm_ masculins, af_/bf_ féminins). Lorsque
… [tronqué pour la traduction]