CLI HyperFrames
Exécutez les commandes sous la forme npx hyperframes ... sauf si les instructions du projet fournissent un wrapper. Respectez le wrapper lorsqu'il est présent. La CLI nécessite Node.js 22 ou plus récent et FFmpeg.
Boucle de développement
- Échafaudage :
npx hyperframes init <projet>ou capturez un site. En mode non-TTY, passez--non-interactive --example=<nom>. - Trouver le mouvement : avant d'écrire un mouvement à la main, cherchez une primitive qui le fait déjà :
npx hyperframes catalog --query "révéler un titre ligne par ligne". Demandez l'effet souhaité plutôt que le mécanisme envisagé. Installez avecnpx hyperframes add <nom>(voir/hyperframes-registry). N'écrivez à la main que si rien ne correspond. - Écrire : rédigez la composition en utilisant
/hyperframes-core. - Obtenez un retour rapide pendant l'édition : exécutez
npx hyperframes lintaprès le premier passage HTML et après les changements structurels. - Exécutez la vérification finale : exécutez
npx hyperframes check; il relance lint avant d'ouvrir le navigateur. N'ajoutez pas d'appel lint autonome redondant. Ajoutez--snapshotspour des vues d'ensemble annotées et trouver les recadrages. - Inspectez les sous-compositions : lorsque
index.htmlmontedata-composition-src, capturez des instantanés au milieu et inspectez chaque scène montée. - Ouvrez l'aperçu final Studio : exécutez
npx hyperframes preview, donnez l'URL du projet de timeline à l'utilisateur et demandez s'il faut réviser ou rendre. - Rendez uniquement après approbation : utilisez la qualité brouillon pour l'itération et la qualité élevée pour la livraison.
- Vérifiez la sortie : confirmez que le fichier existe, n'est pas vide et a une durée plausible.
# Vérification rapide d'itération ; répétez si nécessaire pendant l'écriture.
npx hyperframes lint
# Vérification finale obligatoire ; inclut lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check exécute lint en premier, puis utilise une session navigateur et un seul passage de recherche pour auditer les erreurs d'exécution, les requêtes échouées, la mise en page, les assertions *.motion.json et le contraste WCAG. Les problèmes persistants bloquent le code de sortie ; les problèmes transitoires d'entrée ou de sortie sont informatifs. Utilisez --strict pour bloquer les avertissements. validate, inspect et layout restent des alias pour la compatibilité mais ne doivent pas apparaître dans les nouvelles instructions ou scripts.
Deux surfaces d'aperçu différentes
Ne confondez pas ces états :
| Surface | Quand elle peut s'ouvrir | But |
|---|---|---|
| Planche de storyboard | Avant les vérifications de composition, uniquement si storyboard: yes | Examiner les fiches de plan et les croquis fil de fer. Ouvrir ?view=storyboard#project/<nom>. |
| Aperçu final de composition | Après la réussite de check | Examiner la timeline assemblée avant le rendu. Ouvrir #project/<nom>. |
La planche précoce n'est pas une approbation de la vidéo finale. Le rendu nécessite toujours l'approbation finale définie par hyperframes-core/references/review-loop.md.
Test de fumée des sous-compositions
Les audits statiques ne peuvent pas détecter tous les échecs de montage. Lorsque le projet utilise des sous-compositions, capturez au moins un point médian visible pour chaque emplacement hôte :
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Traitez le contenu minuscule non stylisé, les icônes de taille canevas, les éléments héros manquants ou les délais d'enregistrement de timeline comme des défauts de montage bloquant le rendu. Voir hyperframes-core/references/sub-compositions.md pour les correctifs correspondants.
Conventions pour les agents
-
Recherchez dans le catalogue avant d'écrire un mouvement à la main.
npx hyperframes catalog --query "<le beat, en langage clair>". La recherche est entièrement locale : il n'y a pas de niveau hébergé, pas de compte, et le texte de la requête n'est jamais envoyé nulle part. Par défaut, il classe en fonction du vocabulaire partagé avec le nom, le titre et la description de l'élément, ce qui manque toute formulation qui ne réutilise pas le propre vocabulaire du catalogue. Ajoutez--on-devicepour classer par sens à la place (voir le niveau hors ligne ci-dessous). -
Lisez quel niveau a répondu ; ne le déduisez jamais de l'apparence des résultats. Avec
--json, l'enveloppe contientquery,tier(on-deviceouwords),tier_detail,dropped,unindexed,shown,totaletresults, plustop_scorelorsque le niveau répondant en produit un etwarningslorsqu'un niveau a été demandé et n'a pas pu s'exécuter. Un résultat faible surwordsest attendu ; le même résultat suron-deviceest un bug.top_scoreest uniquement sur appareil et n'a pas de seuil derrière : le classeur retourne l'ensemble du catalogue dans un certain ordre pour chaque requête, lisez-le donc comme une preuve plutôt que comme une réussite ou un échec. -
droppedetunindexedsont des biais opposés entre le registre et l'index sur appareil, et reformuler la requête ne corrige ni l'un ni l'autre.droppedcompte les noms classés que ce registre ne peut pas installer, donc les meilleures correspondances sont celles perdues.unindexedcompte les déplacements du registre que l'index ne peut pas voir du tout, qu'aucune requête ne peut jamais retourner. Actualiser le registre n'est la réponse ni pour l'un ni pour l'autre : son manifeste a un TTL de 24h et se guérit tout seul, tandis que les vecteurs sont un artefact publié séparément récupéré dans~/.hyperframes/catalog/. Réexécuter avec--on-devicerécupère à nouveau cet index lorsqueunindexedest supérieur à zéro, c'est donc le remède à donner à l'utilisateur. Un biais de surcouverture pure (droppedsupérieur à zéro tandis queunindexedest nul) ne déclenche pas la récupération ; vider~/.hyperframes/catalog/est la seule issue pour celui-ci. Les deux comptent des noms plutôt que des résultats, donc l'un ou l'autre peut dépassertotal. -
Lorsque la recherche par sens ne donne rien qui vaille la peine d'être installé, dites-le.
npx hyperframes feedback --search-miss "<la requête que vous avez exécutée>" --wanted "<le mouvement dont vous aviez besoin>" --tier on-device. C'est le seul chemin qui envoie une requête quelque part, et c'est une commande délibérée distincte précisément pour quecatalog --querysimple tienne sa promesse de n'envoyer rien. Signalez l'absence lorsque le niveau sur appareil a répondu et que les meilleurs résultats ne font toujours pas l'affaire ; un résultat faible sur le niveauwordsest attendu et ne vaut pas la peine d'être signalé. Ce qui revient est une liste de mouvements que le catalogue n'a pas encore, lue directement plutôt que devinée à partir des comptes d'installation, donc la formulation qui compte est l'effet que vous souhaitiez, pas le nom d'élément que vous imaginiez. Il ne comporte aucune évaluation et n'atterrit jamais dans la métrique d'évaluation. -
Proposez le niveau hors ligne ; ne l'activez jamais silencieusement. Un téléchargement unique d'environ 33 Mo (une version quantifiée ONNX de
bge-small-en-v1.5plus son tokenizer, épinglée à une révision fixe) et les vecteurs du catalogue depuis le registre, tous deux mis en cache sous~/.hyperframes/, aucun ajouté au projet ou à un package. Une fois en cache, il classe par sens sans rien envoyer. Dites la taille à voix haute et laissez la personne décider, puis passez--on-device(avec-ypour ignorer l'invite) une fois qu'elle a accepté. L'offre interactive ne se déclenche que sur un TTY, et sous--json, rien à ce sujet n'est imprimé du tout, donc dans une exécution d'agent, vous devez le soulever vous-même auprès de l'utilisateur. -
Préférez
--jsonpour les appels d'agent et CI. Les modes serveurrender,previewetplayne fournissent pas de sortie JSON ordinaire ;preview --selection --jsonetpreview --context --jsonsont des exceptions en mode requête. -
doctor --jsonse termine toujours par zéro. Filtrez sur sa charge utile :npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Le mode non-TTY est automatique.
initnécessite--examplelà-bas ; utilisez--non-interactivepour forcer un comportement déterministe sur un TTY. -
Utilisez un seul
HYPERFRAMES_RUN_IDpour toutes les commandes dans la même boucle de vérification. -
Utilisez
--strict,--strict-allet--strict-variableslorsque les avertissements, variables ou conditions CI correspondants doivent bloquer le rendu. -
Les chemins JSON masquent le répertoire personnel en tant que
$HOME; n'essayez pas d'inverser le masquage. -
Lorsqu'un projet cloud hébergé approche ou dépasse la limite de téléchargement de 200 Mo, utilisez
cloud render --dry-run --jsonet suivez l'investigation.hyperframesignoredansreferences/cloud.md. N'ignorez jamais un actif simplement parce qu'il est volumineux. -
Ne rendez jamais simplement parce que les vérifications réussissent. Pausez sur l'aperçu final et attendez l'approbation.
Éditions dirigées par Studio
Lorsque l'utilisateur fait référence à « cet élément » ou à la sélection en cours, interrogez Studio au lieu de deviner :
npx hyperframes preview --context --json --context-fields selection
Utilisez selection.target.hfId lorsqu'il est disponible, sinon son sélecteur et son fichier source. Si le résultat signale no-selection, demandez à l'utilisateur de cliquer sur l'élément et de réexécuter. Demandez uniquement les tranches de contexte dont vous avez besoin ; utilisez --context-detail full uniquement pour les styles calculés ou les métadonnées de texte modifiable. Le comportement complet et les codes d'échec se trouvent dans references/preview-render.md.
Choix de rendu
| Besoin | Commande |
|---|---|
| Itération locale rapide | npx hyperframes render --quality draft |
| Livraison locale finale | npx hyperframes render --quality high --output out.mp4 |
| Rendu conteneur reproductible | npx hyperframes render --docker --strict --output out.mp4 |
| Rendu par lots local piloté par variables | npx hyperframes render --batch rows.json --output "rendus/{nom}.mp4" |
| Rendu hébergé HeyGen sans infrastructure | npx hyperframes cloud render |
| Rendu distribué AWS autogéré | npx hyperframes lambda render <projet> --width 1920 --height 1080 --wait |
| Rendu distribué GCP autogéré | npx hyperframes cloudrun render <projet> --width 1920 --height 1080 --wait |
L'attribution de compétence est automatique — les exemples ci-dessus n'ont pas besoin de --skill. Un projet échafaudé par un workflow (hyperframes init --skill=<workflow>) enregistre sa compétence propriétaire dans hyperframes.json, et chaque rendu ultérieur l'hérite sur la télémétrie anonyme : re-rendus, npm run render et --batch inclus. Passez explicitement --skill=<slug> uniquement pour étamper un projet qui n'a pas été créé via un workflow (son premier rendu le persiste ensuite).
Utilisez le rendu cloud lorsque l'utilisateur souhaite un rendu hébergé sans Chrome local, FFmpeg ou AWS. Utilisez Lambda uniquement lorsque la propriété AWS est une exigence. Utilisez Cloud Run uniquement lorsque la propriété GCP est une exigence. Lisez la référence correspondante avant d'exécuter un chemin cloud.
Après avoir vérifié un rendu réussi, envoyez un rapport de feedback sauf si la télémétrie est désactivée ou que l'utilisateur s'est désinscrit :
npx hyperframes feedback --rating <0-10> --comment "<résultat spécifique ou friction>"
Gardez les commentaires pour les exécutions propres concis. Pour tout bug ou friction, capturez un paquet de reproduction avant de soumettre ; n'envoyez pas seulement un résumé des symptômes. Incluez la commande réexécutable (relative au répertoire du projet — le feedback est soumis à un canal public, donc ne collez pas de chemins absolus, de préfixes de répertoire personnel ou d'identifiants d'utilisateur/machine), le comportement attendu versus réel, l'erreur exacte (supprimez également les chemins absolus des traces de pile — conservez nom de base + ligne, supprimez le répertoire de tête), si la sortie s'est terminée/est tombée en panne/a échoué, la solution de contournement et le statut du projet de repro. Pour une note ≤ 7 qui décrit un défaut visuel (image noire, scintillement, sortie corrompue, mauvaise image, sortie blanche, autre anomalie visuelle), incluez également un bloc COMPOSITION_STRUCTURE: — une anatomie structurelle préservant la vie privée (recensement des éléments + présence d'attributs + forme de la timeline) afin que les mainteneurs puissent faire correspondre des motifs avec des familles de bugs connues sans le ZIP de la composition. Les agents remplissent automatiquement ceci via l'assistant de recensement de composition ; l'utilisateur humain ne le remplit pas à la main. Si le problème ne s'est pas reproduit, dites-le et incluez quand même la dernière commande ayant échoué et les logs. Utilisez --file-issue uniquement avec consentement : il publie une reproduction minimale sur une URL publique. Le format de paquet requis et l'avertissement de confidentialité se trouvent dans references/preview-render.md.
Lisez la référence correspondante avant d'exécuter une commande
Les références et compétences propriétaires suivantes sont des contrats de commande obligatoires, pas une lecture de fond facultative. Avant d'exécuter une commande dans le tableau, lisez sa ligne correspondante.
| Besoin | Référence |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, sidecars de mouvement, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, render --batch piloté par variables | references/compare-and-batch.md |
beats pour la grille de beats Studio d'un projet existant | references/beats.md |
preview, play, render, publish, contexte Studio, feedback | references/preview-render.md |
doctor, gestion du navigateur | references/doctor-browser.md |
auth, rendu cloud hébergé HeyGen et variables de modèle | references/cloud.md |
| Déploiement et rendu AWS Lambda | references/lambda.md |
| Déploiement et rendu Google Cloud Run | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, télémétrie, prétraitement multimédia | references/upgrade-info-misc.md |
Pour les variables de composition, al
…
[tronqué pour la traduction]