wangjs-jacky/jacky-skills

HyperFrames Ops

Avant de répondre aux questions relatives à l'environnement, lisez d'abord le fichier experience.local.md dans le même répertoire pour obtenir les faits les plus récents de la machine (commandes proxy, instantanés de version, historique des questions/réponses).

0. Pourquoi une couche Ops indépendante

Les Skills tierces ne décrivent souvent que des capacités génériques, incapables de prévoir le réseau, le proxy, la version de Node/FFmpeg, le cache de polices, l'état de connexion et la combinaison d'outils de chaque machine. Modifier directement la Skill officielle entraînerait des conflits de mise à jour et mélangerait des faits locaux avec des instructions génériques en amont.

C'est pourquoi nous séparons les deux couches :

• Les Skills officielles sont la source de capacité : elles restent à jour et remplaçables.
• hyperframes-ops est la couche d'adaptation locale : elle enregistre les meilleures pratiques, les différences de compatibilité, les modes d'échec et les contournements validés.
• En cas de problème créatif, lisez d'abord la Skill officielle ; en cas de problème d'environnement, de combinaison, de version ou d'adaptation locale, lisez ensuite cette Skill.
• Lorsqu'une mise à jour en amont rend obsolète une ancienne expérience, marquez-la comme obsolète dans l'expérience locale et revalidez-la ; n'utilisez pas une ancienne expérience pour écraser un nouveau comportement.

1. Identité du projet (faits généralisés)

• HyperFrames est un projet officiel de HeyGen, open-source : github.com/heygen-com/hyperframes, nom du paquet npm hyperframes
• Positionnement : écrire la composition vidéo en HTML, la rendre en mp4 via un headless Chrome (CLI npx hyperframes)
• Configuration requise : Node.js >= 22, FFmpeg

2. Mécanisme de distribution des skills officielles

• Les skills officielles sont maintenues et versionnées dans le même dépôt que la CLI. Le manifeste se trouve à la racine du dépôt : https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills-manifest.json
• Composition : ensemble de base (hyperframes / hyperframes-core / hyperframes-cli / hyperframes-animation / hyperframes-keyframes / hyperframes-creative / hyperframes-registry / remotion-to-hyperframes) + ensemble de workflows (general-video, slideshow, motion-graphics, music-to-video, pr-to-video, product-launch-video, website-to-video, faceless-explainer, talking-head-recut, embedded-captions, media-use, figma). Se référer à la sortie réelle de skills check
• Commandes de gestion :
  • npx hyperframes skills check – vérifie les versions par rapport au manifeste
  • npx hyperframes skills update – met à jour toutes les skills installées + nettoie celles officiellement retirées
  • npx hyperframes init – force la synchronisation des skills avec la dernière version (--skip-skills est actuellement désactivé officiellement)
• Emplacement d'installation : global ~/.claude/skills/ (la CLI reconnaît automatiquement claude-code)
• Sécurité de nommage : la logique de nettoyage de skills update se base sur le fichier de verrouillage et détermine la « provenance ». Elle ne supprime que les skills provenant du dépôt officiel et qui ont été retirées. Bien que cette skill commence par hyperframes-, elle n'est pas dans le verrouillage officiel, elle ne sera donc pas supprimée par erreur par le programme de mise à jour officiel

3. Arbre de diagnostic

Symptôme	Diagnostic
skills check/update/init lance une AbortError (timeout fetchManifest)	Problème réseau : la CLI utilise le fetch intégré de Node pour accéder à raw.githubusercontent.com. En cas d'échec de connexion directe, un proxy est obligatoire. Lisez experience.local.md pour obtenir la commande prête à l'emploi de la machine
Autres échecs réseau de npx hyperframes	Idem ; notez que le fetch intégré de Node (undici) ne lit pas la variable d'environnement HTTP_PROXY par défaut. Pour Node 24+, ajoutez NODE_USE_ENV_PROXY=1 (ou --use-env-proxy)
Problèmes de rendu/prévisualisation	npx hyperframes doctor, npx hyperframes browser pour l'auto-test ; confirmez que Node >= 22 et FFmpeg sont disponibles
Le comportement d'une skill ressemble à une ancienne version	skills check pour voir l'écart de version, skills update pour se synchroniser
Échec de l'échange de token heygen auth login --oauth (api2.heygen.com connection refused) ou timeout des appels à la bibliothèque musicale	Le CLI heygen est un programme Go, il reconnaît les variables d'environnement HTTP(S)_PROXY (contrairement au fetch Node, sans commutateur supplémentaire). Dans les réseaux restreints, toutes les commandes heygen doivent utiliser un proxy. Le service de callback OAuth ne vit que 5 minutes et nécessite un shell interactif (un lancement en arrière-plan/nohup échouera en raison de l'absence de callback). Les commandes de la machine se trouvent dans experience.local.md
Le rendu des polices est incorrect (le titre s'élargit, dépasse le conteneur, mais lint/inspect reste tout vert)	Les 18 polices intégrées sont téléchargées à la demande au moment de l'exécution (@fontsource → ~/.cache/hyperframes/fonts). Si le téléchargement échoue, le système se rabat silencieusement sur les polices système. Solution pour réseau restreint : télécharger les woff2 dans le projet et utiliser explicitement @font-face en auto-hébergement
Problèmes de création (comment écrire une composition, animation, paramètres de rendu)	Cela ne relève pas de cette skill ; référez-vous à la table de routage de la skill officielle hyperframes d'entrée

4. Protocole de rédaction de l'expérience

• Rédigez dans experience.local.md (privé à la machine, ignoré par .gitignore de ce répertoire) : nouveaux problèmes rencontrés et solutions validées, instantanés de version/statut d'installation (avec date), commandes propres à la machine, faits de proxy et réseau, historique des questions/réponses
• Rédigez dans ce SKILL.md (dans git, partageable) : changements dans le mécanisme officiel (mode de distribution, sémantique des commandes, logique de nettoyage), nouvelles routes de diagnostic généralisées
• Critère de décision : si cela reste vrai sur une autre machine → SKILL.md ; si cela n'est vrai que pour cette machine → experience.local.md
• Chaque fois que vous êtes appelé pour un problème d'environnement HyperFrames et que vous le résolvez, rédigez la conclusion selon la couche ci-dessus, en indiquant la date.